From 3e6827e7dc7261729575ec95bc417bb863f71c64 Mon Sep 17 00:00:00 2001 From: Mikael Hugo Date: Thu, 7 May 2026 03:33:14 +0200 Subject: [PATCH] docs: remove stale direct db and mcp guidance --- AGENTS.md | 2 +- docs/dev/ADR-017-charm-tui-client.md | 2 +- docs/dev/MEMORY-SYSTEM-ARCHITECTURE.md | 15 +++--- .../2026-05-01-repo-vcs-and-notifications.md | 4 +- docs/user-docs/troubleshooting.md | 2 +- .../extensions/sf/bootstrap/exec-tools.js | 3 +- .../extensions/sf/bootstrap/memory-tools.js | 4 +- .../sf/commands-extract-learnings.js | 2 +- .../extensions/sf/memory-relations.js | 2 +- .../sf/skills/brainstorming/SKILL.md | 2 +- .../sf/skills/context-doctor/SKILL.md | 10 ++-- .../sf/skills/dispatching-subagents/SKILL.md | 2 +- .../sf/skills/receiving-code-review/SKILL.md | 2 +- .../sf/skills/requesting-code-review/SKILL.md | 2 +- .../extensions/sf/skills/researcher/SKILL.md | 51 +++++-------------- .../sf/skills/spec-first-tdd/SKILL.md | 2 +- .../sf/skills/systematic-debugging/SKILL.md | 2 +- .../extensions/sf/tools/exec-tool.js | 4 +- 18 files changed, 46 insertions(+), 67 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9610ca6de..b09455709 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -219,7 +219,7 @@ See [`docs/plans/README.md`](docs/plans/README.md), [`docs/adr/README.md`](docs/ ## SF Schedule -The SF schedule system (`/sf schedule`) stores time-bound reminders in `.sf/schedule.jsonl` as append-only JSONL. Items surface on their due date via pull queries at launch and auto-mode boundaries — there is no background daemon. +The SF schedule system (`/sf schedule`) stores time-bound reminders in `.sf/schedule.jsonl` as versioned append-only JSONL. Items surface on their due date via pull queries at launch and auto-mode boundaries — there is no background daemon. **When to use `sf schedule` vs backlog:** - **`sf schedule`** — time-bound items that must surface at a future date: a 2-week adoption review after shipping a feature, a 1-month audit of an architectural decision, a 30-minute reminder to run a command. Use when the *timing* matters, not just the *priority*. diff --git a/docs/dev/ADR-017-charm-tui-client.md b/docs/dev/ADR-017-charm-tui-client.md index d1210a7b8..efbb9ab3f 100644 --- a/docs/dev/ADR-017-charm-tui-client.md +++ b/docs/dev/ADR-017-charm-tui-client.md @@ -33,7 +33,7 @@ This ADR plans the extraction. - *Rejected:* fragile FFI; defeats the architectural goal of separating engine from UI. - **Keep `pi-tui` indefinitely; only build Charm TUI as an alternative for SSH access.** - *Rejected:* leaves ~10k LOC of TS in sf core *forever* as a maintenance burden. The whole point is to delete it. -- **Don't build a new TUI; expose the daemon over MCP/HTTP and rely on third-party clients (Claude Code, Cursor) to render.** +- **Don't build a new TUI; expose the daemon over an external API and rely on third-party clients (Claude Code, Cursor) to render.** - *Rejected:* sf's user-facing surface is the TUI when working interactively. Outsourcing it removes a major UX touchpoint we own. ## Consequences diff --git a/docs/dev/MEMORY-SYSTEM-ARCHITECTURE.md b/docs/dev/MEMORY-SYSTEM-ARCHITECTURE.md index 0df0b3b14..c6380109d 100644 --- a/docs/dev/MEMORY-SYSTEM-ARCHITECTURE.md +++ b/docs/dev/MEMORY-SYSTEM-ARCHITECTURE.md @@ -257,14 +257,13 @@ memory_sources ( **Purpose:** Command-line interface to memory system. **Commands:** -- `sf memory list [category]` — List all memories (optionally filtered) -- `sf memory search ` — Find memories by content -- `sf memory add --category ` — Manually add memory -- `sf memory recall ` — Get context-relevant memories -- `sf memory decay [--older-than-days N]` — Age memories -- `sf memory stats` — Memory database statistics -- `sf memory export` — Export all memories to JSON -- `sf memory import ` — Import memories from JSON +- `/sf memory list [category]` — List all memories (optionally filtered) +- `/sf memory search ` — Find memories by content +- `/sf memory note ` — Manually add memory +- `/sf memory status` — Memory database statistics +- `/sf memory decay [--older-than-days N]` — Age memories +- `/sf memory export ` — Export all memories to JSON +- `/sf memory import ` — Import memories from JSON --- diff --git a/docs/records/2026-05-01-repo-vcs-and-notifications.md b/docs/records/2026-05-01-repo-vcs-and-notifications.md index 75d48feb6..f8086bb8a 100644 --- a/docs/records/2026-05-01-repo-vcs-and-notifications.md +++ b/docs/records/2026-05-01-repo-vcs-and-notifications.md @@ -37,13 +37,13 @@ ## Contradictions Found -- ADR-008 (SF tools over MCP) is marked "Accepted — impl in progress" but the user has clarified that SF is the only runtime in use; Claude Code is used as an external dev assistant, not as a provider inside SF. ADR-008's premise (provider parity for Claude Code CLI as a Pi provider) may not apply to the current usage model. Needs clarification. +- ADR-008 (SF tools over MCP) was superseded after the user clarified that SF is the only runtime in use; Claude Code is used as an external dev assistant, not as a provider inside SF. Current guidance rejects SF-as-MCP-server exposure and keeps MCP strictly client-side for external tools. - `docs/design-docs/` and `docs/dev/ADR-*.md` are split across two directories. The design-docs folder has 2 files; 18 ADRs live in dev/. This split is navigable with the index but worth consolidating eventually. ## What Remains Unresolved -- ADR-008 relevance: does exposing workflow mutations over MCP make sense if SF is always the sole runtime? +- ADR-008 relevance is resolved by `docs/dev/ADR-008-sf-tools-over-mcp-for-provider-parity.md`: SF must not expose workflow mutations over MCP. - ADR-018 Phase 1 (repo profiler wired into dispatch) is not yet started - Notification event model implementation (Phase 2 of the spec) is not yet started - No ADR template or `just adr` recipe diff --git a/docs/user-docs/troubleshooting.md b/docs/user-docs/troubleshooting.md index 3a6bd5222..76685b411 100644 --- a/docs/user-docs/troubleshooting.md +++ b/docs/user-docs/troubleshooting.md @@ -301,7 +301,7 @@ rm .sf/routing-history.json /sf doctor ``` -Doctor rebuilds `STATE.md` from plan and roadmap files on disk and fixes detected inconsistencies. +Doctor derives current state from the DB-backed runtime model when available, regenerates projections such as `STATE.md`, and fixes detected inconsistencies. File-based plan and roadmap parsing is only a recovery path for unmigrated or damaged state. ## Getting Help diff --git a/src/resources/extensions/sf/bootstrap/exec-tools.js b/src/resources/extensions/sf/bootstrap/exec-tools.js index 4dfe249ca..3d19c55b6 100644 --- a/src/resources/extensions/sf/bootstrap/exec-tools.js +++ b/src/resources/extensions/sf/bootstrap/exec-tools.js @@ -1,6 +1,7 @@ // SF — Exec (context-mode) tool registration. // -// Exposes the `sf_exec`, `sf_exec_search`, `sf_resume`, and `kill_agent` tools over MCP. +// Registers the `sf_exec`, `sf_exec_search`, `sf_resume`, and `kill_agent` +// tools as native SF agent tools. // Opt-in: sf_exec is disabled unless `context_mode.enabled: true` is set // (or left unset — enabled by default). import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs"; diff --git a/src/resources/extensions/sf/bootstrap/memory-tools.js b/src/resources/extensions/sf/bootstrap/memory-tools.js index fbd2ee080..ac4de8b8b 100644 --- a/src/resources/extensions/sf/bootstrap/memory-tools.js +++ b/src/resources/extensions/sf/bootstrap/memory-tools.js @@ -1,8 +1,8 @@ // SF — Memory tool registration // // Exposes the memory-layer tools (capture_thought, memory_query, sf_graph) -// to the LLM over MCP. All three degrade gracefully when the SF database -// is unavailable. +// as native SF tools. All three degrade gracefully when the SF database is +// unavailable. import { Type } from "@sinclair/typebox"; import { executeMemoryCapture, diff --git a/src/resources/extensions/sf/commands-extract-learnings.js b/src/resources/extensions/sf/commands-extract-learnings.js index 9b04d729f..11129b4b1 100644 --- a/src/resources/extensions/sf/commands-extract-learnings.js +++ b/src/resources/extensions/sf/commands-extract-learnings.js @@ -308,5 +308,5 @@ high confidence, skip the capture entirely. ### Step 8 — Surprises stay only in LEARNINGS.md Surprises are milestone-local context and are NOT cross-session-reusable. Do -not persist them via \`capture_thought\` or any other MCP tool.`; +not persist them via \`capture_thought\` or any other native memory tool.`; } diff --git a/src/resources/extensions/sf/memory-relations.js b/src/resources/extensions/sf/memory-relations.js index 4ec66c3bb..137808b55 100644 --- a/src/resources/extensions/sf/memory-relations.js +++ b/src/resources/extensions/sf/memory-relations.js @@ -8,7 +8,7 @@ // Read consumers: // (1) `getRelevantMemoriesRanked` walks edges of cosine top-N memories // and applies a one-pass intra-pool score boost (damping 0.4). -// (2) `sf_graph` MCP tool exposes BFS traversal for explicit queries. +// (2) `sf_graph` exposes BFS traversal for explicit agent queries. // All writes go through the single-writer gate in `sf-db.ts`. import { _getAdapter, isDbAvailable } from "./sf-db.js"; export const VALID_RELATIONS = [ diff --git a/src/resources/extensions/sf/skills/brainstorming/SKILL.md b/src/resources/extensions/sf/skills/brainstorming/SKILL.md index d9becb478..5b4ca1ac0 100644 --- a/src/resources/extensions/sf/skills/brainstorming/SKILL.md +++ b/src/resources/extensions/sf/skills/brainstorming/SKILL.md @@ -136,7 +136,7 @@ Cover: purpose, consumer, contract, implementation sketch, test strategy, eviden When approved, persist to memory so the next session can find it: ``` -sf_save_memory( +capture_thought( category="design-decision", content="design: for — approach: — refused: ", confidence=0.9 diff --git a/src/resources/extensions/sf/skills/context-doctor/SKILL.md b/src/resources/extensions/sf/skills/context-doctor/SKILL.md index 68117b2a7..bfc2091d1 100644 --- a/src/resources/extensions/sf/skills/context-doctor/SKILL.md +++ b/src/resources/extensions/sf/skills/context-doctor/SKILL.md @@ -34,13 +34,15 @@ Read each persistent context file and judge: | `.sf/PM-STRATEGY.md` | Still aligned with current direction? | | `MEMORY.md` (root) | Index lines still pointing at extant files? | -For the memory store (the `memories` table in `.sf/sf.db`): +For the memory store, use SF's DB-backed memory/query tools rather than direct `sqlite3` access: ```bash -sqlite3 .sf/sf.db "SELECT category, content, confidence, hit_count FROM memories ORDER BY confidence DESC LIMIT 20" -sqlite3 .sf/sf.db "SELECT COUNT(*) FROM memories WHERE confidence < 0.5" +/sf memory status +/sf memory search "pattern" ``` +Inside an agent session, prefer the registered `memory_query` tool for targeted lookups. + Look for: - Low-confidence rows (`< 0.5`) that haven't been hit in N days — candidates for archival. @@ -71,7 +73,7 @@ For non-trivial cleanups, present this plan to the user before executing — sf' ### Step 4 — Execute Repairs -Apply edits with `Edit`. For the `memories` table, prefer `sf_save_memory` / `sf_delete_memory` (or whatever the current sf memory tools are) over direct `sqlite3` writes — those bypass tool-level invariants. +Apply edits with `Edit`. For memory cleanup, use the current `/sf memory` commands or registered memory tools over direct `sqlite3` writes — direct DB mutation bypasses tool-level invariants. **Scope rules:** diff --git a/src/resources/extensions/sf/skills/dispatching-subagents/SKILL.md b/src/resources/extensions/sf/skills/dispatching-subagents/SKILL.md index 2cc00c723..b42c7a0fd 100644 --- a/src/resources/extensions/sf/skills/dispatching-subagents/SKILL.md +++ b/src/resources/extensions/sf/skills/dispatching-subagents/SKILL.md @@ -275,7 +275,7 @@ After a parallel or debate batch returns, the parent agent **must** synthesise. Persist non-trivial syntheses to memory: ``` -sf_save_memory( +capture_thought( category="design-synthesis", content=" — slice ", confidence=<0.0-1.0> diff --git a/src/resources/extensions/sf/skills/receiving-code-review/SKILL.md b/src/resources/extensions/sf/skills/receiving-code-review/SKILL.md index 7e0c0f868..03226ba94 100644 --- a/src/resources/extensions/sf/skills/receiving-code-review/SKILL.md +++ b/src/resources/extensions/sf/skills/receiving-code-review/SKILL.md @@ -145,7 +145,7 @@ Keep scope tight: fix the validated review issue, not every adjacent redesign th After resolving significant review comments: ``` -sf_save_memory( +capture_thought( category="review-learning", content="review caught: in — prevent by ", confidence=0.9 diff --git a/src/resources/extensions/sf/skills/requesting-code-review/SKILL.md b/src/resources/extensions/sf/skills/requesting-code-review/SKILL.md index fe8e8b8cc..cd1066075 100644 --- a/src/resources/extensions/sf/skills/requesting-code-review/SKILL.md +++ b/src/resources/extensions/sf/skills/requesting-code-review/SKILL.md @@ -181,7 +181,7 @@ Stop when: Persist the delivery context so future units can trace what was built and why: ``` -sf_save_memory( +capture_thought( category="delivery", content="delivered: — slice: — consumer: — insight: ", confidence=0.9 diff --git a/src/resources/extensions/sf/skills/researcher/SKILL.md b/src/resources/extensions/sf/skills/researcher/SKILL.md index df53d3d25..df929897d 100644 --- a/src/resources/extensions/sf/skills/researcher/SKILL.md +++ b/src/resources/extensions/sf/skills/researcher/SKILL.md @@ -7,7 +7,7 @@ description: Researches codebase, project state, and external knowledge using lo Research a topic using four complementary information sources, in priority order: 1. **Native LSP tool + local search** (`lsp`, `rg`, `find`, `ls`) — use FIRST for code exploration 2. **sift** (hybrid BM25+vector local search) — use when LSP/rg is not enough -3. **SF project database** (sqlite3) — use for project state (milestones, requirements, decisions) +3. **SF project state tools** — use DB-backed SF query tools for milestones, requirements, and decisions 4. **Web search** — use for external documentation and current information This skill is the first step before planning — it produces the evidence base that drives good decisions. Without research, agents plan from assumptions; with this skill, they plan from evidence. @@ -21,7 +21,7 @@ Strictly prohibited while running this skill: - File creation, modification, or deletion (no `Write`, `Edit`, `NotebookEdit`, `touch`, `rm`, `mv`, `cp`). - Bash redirects or heredocs that write files: `>`, `>>`, `tee`, `cat < file`, `python -c "open(...).write(...)"`. The shell back-door does not bypass the read-only contract. -- DB writes: `sqlite3 .sf/sf.db "INSERT|UPDATE|DELETE|DROP|CREATE ..."`. Use `SELECT` only. +- Direct DB access: do not run `sqlite3 .sf/sf.db` or load SQLite from ad-hoc scripts. Use SF query tools exposed by the runtime; the engine owns the WAL connection. - Git write operations: `add`, `commit`, `push`, `merge`, `rebase`, `checkout -b`, `branch -d`. - Package installs: `npm install`, `pip install`, `cargo add`. - Spawning subagents that perform any of the above on the researcher's behalf — the prohibition applies to delegated actions as well. @@ -78,20 +78,12 @@ quotas. Use GitHub code search only for repositories that are not on disk, dedupe repeated queries, and treat `403` rate-limit responses as a signal to wait for reset or continue with local evidence. -**SF project database queries:** -```bash -# Current milestone and slices -sqlite3 .sf/sf.db "SELECT id, title, status FROM milestones WHERE status='active'" +**SF project state queries:** +Use the runtime query tools instead of opening `.sf/sf.db` directly: -# All requirements -sqlite3 .sf/sf.db "SELECT id, class, status, description FROM requirements" - -# Recent decisions -sqlite3 .sf/sf.db "SELECT id, scope, decision FROM decisions ORDER BY seq DESC LIMIT 10" - -# Tasks by slice -sqlite3 .sf/sf.db "SELECT id, title, status FROM tasks WHERE milestone_id='M001' AND slice_id='S01'" -``` +- `sf_milestone_status` — read milestone, slice, and task status inside an agent session. +- `sf headless query` — get the full DB-backed project snapshot when running from the shell. +- `/sf inspect db` — inspect schema/version diagnostics when the user asks for database health. **Web search — use the search-the-web tool directly for current information.** @@ -102,7 +94,7 @@ sqlite3 .sf/sf.db "SELECT id, title, status FROM tasks WHERE milestone_id='M001' Before searching, identify what you need to know: - **Code exploration** (finding functions, types, references) → use native `lsp` first, then `rg` -- **Project state** (milestones, slices, tasks, requirements) → query the SF DB +- **Project state** (milestones, slices, tasks, requirements) → use SF DB-backed query tools - **Current external information** → use web search - **All of the above** → combine all four sources @@ -139,31 +131,16 @@ or explicit strategy control: {"query": "how does the dispatch loop handle retries and timeouts", "agent": true, "agentMode": "graph"} ``` -## Step 4: Query the SF project database +## Step 4: Query SF project state -The SF database (`.sf/sf.db`) contains the canonical project state: +The SF database contains the canonical project state, but agents should inspect it through SF's runtime tools so they do not contend with the single-writer WAL connection: ```bash -# List active milestones with their slices -sqlite3 .sf/sf.db " - SELECT m.id, m.title, m.status, s.id, s.title, s.status - FROM milestones m - LEFT JOIN slices s ON s.milestone_id = m.id - WHERE m.status IN ('active','planning') - ORDER BY m.id, s.id -" +# Full state snapshot from shell +sf headless query -# Get requirements by status -sqlite3 .sf/sf.db "SELECT id, class, status, description FROM requirements WHERE status='active'" - -# Recent decisions (most recent first) -sqlite3 .sf/sf.db "SELECT id, scope, decision, choice FROM decisions ORDER BY seq DESC LIMIT 20" - -# Blocked or pending tasks -sqlite3 .sf/sf.db "SELECT id, title, status FROM tasks WHERE status IN ('blocked','pending')" - -# Artifacts (plans, summaries) for a milestone -sqlite3 .sf/sf.db "SELECT path, artifact_type FROM artifacts WHERE milestone_id='M001'" +# In an agent session, call the DB-backed `sf_milestone_status` tool +# with milestoneId=M001 when you need a focused milestone snapshot. ``` ## Step 5: Web search for external information diff --git a/src/resources/extensions/sf/skills/spec-first-tdd/SKILL.md b/src/resources/extensions/sf/skills/spec-first-tdd/SKILL.md index 973343ed2..f6f026477 100644 --- a/src/resources/extensions/sf/skills/spec-first-tdd/SKILL.md +++ b/src/resources/extensions/sf/skills/spec-first-tdd/SKILL.md @@ -133,7 +133,7 @@ LLM confidence is poorly calibrated in absolute terms — the relative signal ma - For non-trivial slices, persist the contract to sf memory: ``` -sf_save_memory( +capture_thought( category="contract", content=" — — slice ", confidence=0.9 diff --git a/src/resources/extensions/sf/skills/systematic-debugging/SKILL.md b/src/resources/extensions/sf/skills/systematic-debugging/SKILL.md index d0e131627..703db27a6 100644 --- a/src/resources/extensions/sf/skills/systematic-debugging/SKILL.md +++ b/src/resources/extensions/sf/skills/systematic-debugging/SKILL.md @@ -137,7 +137,7 @@ A check without a `Command run` block is a skip. "I re-ran the repro and it work Persist the pattern to memory so future units don't re-hit it: ``` -sf_save_memory( +capture_thought( category="anti-pattern", content=" in — root cause: — fix: — test: ", confidence=0.9 diff --git a/src/resources/extensions/sf/tools/exec-tool.js b/src/resources/extensions/sf/tools/exec-tool.js index efe5a08fd..9fb62ae4a 100644 --- a/src/resources/extensions/sf/tools/exec-tool.js +++ b/src/resources/extensions/sf/tools/exec-tool.js @@ -1,8 +1,8 @@ -// SF Exec Tool — executor for the sf_exec MCP tool. +// SF Exec Tool — executor for the native sf_exec agent tool. // // Thin wrapper around exec-sandbox.ts that reads effective options from // the project preferences (context_mode block) and formats the result -// for MCP return. +// for agent-tool return. import { EXEC_DEFAULTS, runExecSandbox } from "../exec-sandbox.js"; import { isContextModeEnabled } from "../preferences-types.js"; export function buildExecOptions(baseDir, cfg, extras) {