From 2fae96d539e9f99fc4758a8620586b7d072e89fd Mon Sep 17 00:00:00 2001 From: Mikael Hugo Date: Thu, 7 May 2026 03:09:55 +0200 Subject: [PATCH] docs: align runtime state and mcp boundaries --- docs/adr/0075-uok-gate-architecture.md | 2 +- docs/dev/architecture.md | 2 +- docs/exec-plans/tech-debt-tracker.md | 10 +++++----- src/resources/extensions/mcp-client/index.js | 2 +- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/adr/0075-uok-gate-architecture.md b/docs/adr/0075-uok-gate-architecture.md index b3fe691d8..2639896b8 100644 --- a/docs/adr/0075-uok-gate-architecture.md +++ b/docs/adr/0075-uok-gate-architecture.md @@ -55,7 +55,7 @@ Retries are persisted to the `gate_runs` SQLite table and emitted as audit event ### Durable Message Bus -The `MessageBus` persists messages to `.sf/runtime/uok-messages.jsonl` with at-least-once delivery. Inbox read-state is stored per-agent in `.sf/runtime/uok-inbox-{agent}.json`. Messages are pruned by TTL (`retentionDays`, default 7) and inbox size is capped (`maxInboxSize`, default 1000). +The `MessageBus` persists messages to `.sf/sf.db` (`uok_messages` and `uok_message_reads`) with at-least-once delivery. The old `.sf/runtime/uok-messages.jsonl` and per-agent inbox JSON files are legacy artifacts only; normal runtime message state is SQLite-backed. Messages are pruned by TTL (`retentionDays`, default 7) and inbox size is capped (`maxInboxSize`, default 1000). ### Chaos Engineering Safety diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md index 1195cd228..578126d0b 100644 --- a/docs/dev/architecture.md +++ b/docs/dev/architecture.md @@ -63,7 +63,7 @@ Every dispatch creates a new agent session. The LLM starts with a clean context | **Context7** | Up-to-date library/framework documentation | | **Background Shell** | Long-running process management with readiness detection | | **Subagent** | Delegated tasks with isolated context windows | -| **MCP Client** | Native MCP server integration via @modelcontextprotocol/sdk | +| **MCP Client** | Client-side integration with external MCP tool servers via @modelcontextprotocol/sdk; SF does not expose its own workflow as an MCP server | | **Voice** | Real-time speech-to-text on Linux | | **Slash Commands** | Custom command creation | | **LSP** | Language Server Protocol — diagnostics, definitions, references, hover, rename | diff --git a/docs/exec-plans/tech-debt-tracker.md b/docs/exec-plans/tech-debt-tracker.md index 251dc0561..4bba759da 100644 --- a/docs/exec-plans/tech-debt-tracker.md +++ b/docs/exec-plans/tech-debt-tracker.md @@ -12,15 +12,15 @@ --- -## MCP workflow mutations — read-only only +## External workflow mutations — RPC/headless only -**Impact:** External providers (Claude Code CLI, remote orchestrators) that route through MCP can query SF state but cannot advance it. `sf_task_complete`, `sf_plan_milestone`, etc. are in-process only. +**Impact:** External orchestrators must advance SF through native SF commands, headless/RPC, or the daemon/RPC client path. SF must not expose workflow mutation tools through MCP. -**Proposed fix:** Extract shared handlers from native tools; expose over MCP server (ADR-008 Phase 1). +**Proposed fix:** Extract shared handlers from native tools behind an internal command/RPC boundary. Keep ADR-008 rejected: do not build or restore an SF MCP server. -**Verification:** Claude Code provider session completes a task via MCP `sf_task_complete` and produces identical STATE.md outcome. +**Verification:** A daemon/RPC session completes a task through the native `sf_task_complete` path and produces the same DB/projection outcome as interactive SF. -**Tracked in:** [active/index.md — ADR-008 Phase 1](./active/index.md) · [ADR-008](../dev/ADR-008-IMPLEMENTATION-PLAN.md) +**Tracked in:** [ADR-008 tombstone](../dev/ADR-008-IMPLEMENTATION-PLAN.md) --- diff --git a/src/resources/extensions/mcp-client/index.js b/src/resources/extensions/mcp-client/index.js index 3dab8a5a7..dbb04937c 100644 --- a/src/resources/extensions/mcp-client/index.js +++ b/src/resources/extensions/mcp-client/index.js @@ -1,5 +1,5 @@ /** - * MCP Client Extension — Native MCP server integration for pi + * MCP Client Extension — client-side integration with external MCP tool servers * * Provides on-demand access to MCP servers configured in project files * (.mcp.json, .sf/mcp.json) using the @modelcontextprotocol/sdk Client