@moretea-labs/forge 1.6.0 → 1.7.1

package/docs/architecture/current/codegraph-context-provider.md

@@ -1,238 +0,0 @@
-# CodeGraph Context Provider
-
-Status: **Runtime Authority — impact-context convergence implemented**
-Source baseline: `a49465096c4e2532da37ab2f9d10dca2238217ac`  
-Scope: Controller Context Plane only
-
-## Problem
-
-Forge already installs and diagnoses `@colbymchenry/codegraph`, and the repository already has a local `.codegraph/codegraph.db`. However, ChatGPT/Controller planning still relies on token search plus bounded raw file reads. CodeGraph is not available as a policy-bounded Controller read capability, so `-plan` and `-debug` cannot use symbol, call-graph, dependency, or impact data directly.
-
-The missing capability is not another top-level MCP tool. It is a Context Plane provider that can add structural evidence to the existing `rh_context` / `controller_context_pack` path.
-
-## Constraints
-
-1. The default workflow remains unchanged. No explicit mode directive still uses the existing automatic Direct-first routing.
-2. `-plan` and `-debug` are opt-in routing instructions. CodeGraph must not add latency to ordinary Direct edits by default.
-3. Forge continues to support Node.js `>=20.10.0`.
-4. CodeGraph's embedded SDK requires Node.js `>=22.5` to open its SQLite database through `node:sqlite`.
-5. CodeGraph's CLI/MCP server uses its own bundled runtime and may auto-sync the index. Planning must not silently mutate source files or silently refresh derived indexes.
-6. Source reads remain governed by the existing repository/path policy. A graph hit is discovery evidence, not permission to read a denied path.
-7. The existing five facade tools remain the preferred host surface. Do not add a `codegraph_*` top-level Forge tool family.
-8. If CodeGraph is absent, stale, incompatible, or unavailable, Context Pack must fail open to the existing bounded text search when structural context is optional, and fail clearly when structural context was explicitly required.
-
-## Decision
-
-Add a `CodeGraphReadProvider` to the Context Plane, backed by a self-contained CodeGraph sidecar running on CodeGraph's bundled Node runtime.
-
-The Forge Controller process never imports and opens CodeGraph directly on Node 20. Instead it launches a small packaged sidecar with the matching platform bundle runtime and communicates through a bounded JSON protocol.
-
-The sidecar opens CodeGraph with:
-
-```text
-CodeGraph.open(projectRoot, { sync: false, readOnly: true })
-```
-
-It never calls:
-
-- `init` / `initSync`
-- `indexAll` / `indexFiles`
-- `sync`
-- `watch`
-- `optimize`
-- `clear`
-- `uninitialize`
-
-This keeps structural planning read-only with respect to both the repository and the derived CodeGraph index.
-
-## Runtime layout
-
-```text
-ChatGPT
-  -> rh_context / controller_context_pack
-  -> Context Pack builder
-       -> bounded text search + raw repository reads
-       -> CodeGraphReadProvider (only when requested)
-            -> CodeGraph sidecar
-                 -> bundled CodeGraph Node runtime
-                 -> CodeGraph.open(... readOnly=true, sync=false)
-                 -> .codegraph/codegraph.db
-```
-
-The sidecar is a provider implementation detail. It is not a second Forge Runtime and does not own Controller state, Work, scheduling, repository mutation, or recovery.
-
-## Provider contract
-
-Phase 1 provider operations:
-
-- `status`
-  - initialized
-  - provider/runtime availability
-  - index last indexed time
-  - index build version/extraction version
-  - stale-engine signal
-  - changed-file signal from CodeGraph when available
-- `search`
-  - symbol/name search
-  - bounded node metadata only
-- `context`
-  - task/query relevant subgraph via CodeGraph structural context
-  - bounded nodes and edges
-- `impact`
-  - impact radius from a resolved node
-- `file_dependencies`
-  - dependencies and dependents for explicit files
-
-Later operations may add callers/callees/usages and affected-test calculation, but Phase 1 should not expand before the Context Pack integration is proven useful.
-
-Every request includes the canonical repository root chosen by Repository Registry. The sidecar must reject attempts to substitute an arbitrary root after startup.
-
-## Context Pack integration
-
-Extend `ControllerContextPackOptions` with a structural context policy:
-
-```text
-structuralContext = off | auto | required
-```
-
-Default is `off` to preserve current Direct performance and behavior.
-
-Expected mode usage:
-
-- ordinary Direct: `off` (zero CodeGraph provider calls)
-- explicit `-debug`: `auto`
-- explicit `-plan`: `required` when a CodeGraph index is present; otherwise return a clear degraded-plan warning and use bounded text search
-- Goal/Plan planning and review: `auto` or `required` when structural evidence materially improves the decision
-
-When enabled, graph results augment candidate ranking and the bounded impact contract. They do not replace raw source reads. Important files selected through CodeGraph still pass through `resolveMcpPath` and `readRepositoryRange` before implementation.
-
-After the initial structural `context` query, the Context Plane may issue bounded `file_dependencies` queries for a small number of entry-point files. Dependencies and dependents are folded into the same policy-filtered Context Pack; they are not exposed as another ChatGPT tool flow. The pack derives an `impactContext` containing primary targets, must-inspect and likely-affected files, related tests/checks, architecture contracts, coverage gaps, freshness, and confidence. These remain discovery evidence: ChatGPT is still the semantic-sufficiency authority.
-
-Context Pack gains a bounded `structuralContext` section containing:
-
-- provider: `codegraph`
-- requested mode
-- status: `ready | unavailable | stale | degraded`
-- index freshness/build metadata
-- query terms used
-- selected structural entry points
-- related/impact file paths
-- graph truncation metadata
-- fallback reason when graph data was not used
-
-Candidate reasons should distinguish graph evidence, for example:
-
-- `codegraph:search:<symbol>`
-- `codegraph:context`
-- `codegraph:impact:<node-id>`
-- `codegraph:dependent:<path>`
-
-## Freshness policy
-
-Read-only planning never auto-syncs CodeGraph.
-
-If the provider reports changed files, stale extraction, or an index built by an older extraction engine:
-
-1. mark structural context stale/degraded;
-2. do not silently run `sync` or `index`;
-3. use direct repository reads for affected files;
-4. optionally recommend an explicit CodeGraph refresh action outside the read-only planning step.
-
-A later typed maintenance action may perform refresh. That action is separate from planning and may write only derived `.codegraph` state, never source files.
-
-### Isolated checkout baseline overlay
-
-CodeGraph binds source root and `.codegraph` database root to the same `projectRoot`; the embedded API does not expose a separate read-only database path. Forge therefore does **not** copy or synchronously build an 84MB-class structural index for every managed worktree.
-
-When structural context is requested for an isolated checkout that has no local index, the Context Plane may reuse an indexed non-worktree checkout from the same Repository Registry family as **repository-baseline structural evidence**. Current-checkout lexical/raw source remains authoritative. Forge overlays the selected checkout's current Git-changed paths on the graph candidates and reports `indexSource=repository_baseline` plus explicit coverage gaps.
-
-The baseline is never presented as current-checkout truth. A dirty current checkout or a baseline/current HEAD mismatch marks the structural evidence stale and prevents `structural_context=required` from being satisfied. Optional structural requests may still use the graph as bounded discovery evidence while raw current-checkout reads cover changed files.
-
-This fallback executes only when structural context was already requested. Ordinary Direct routing remains `structural_context=off`, performs zero CodeGraph provider calls, and pays no baseline lookup or structural refresh cost.
-
-## Packaging and platform behavior
-
-The provider locates the matching optional platform package:
-
-```text
-@colbymchenry/codegraph-<platform>-<arch>
-```
-
-and uses its bundled `node` / `node.exe` to launch the packaged sidecar.
-
-If the platform package is missing, provider status is `unavailable` with remediation to reinstall CodeGraph with optional dependencies enabled. Forge must remain usable without CodeGraph.
-
-The sidecar code ships inside Forge's existing published `src/` or `scripts/` package surface; no new external service or daemon is required for Phase 1.
-
-## Security and policy
-
-- Structural queries are repository-scoped and read-only.
-- Sidecar stdin accepts typed JSON requests, not shell commands.
-- Sidecar output is bounded before returning to the host.
-- Telemetry is disabled for provider subprocesses (`CODEGRAPH_TELEMETRY=0`, `DO_NOT_TRACK=1`).
-- No network capability is required.
-- No arbitrary executable path is accepted from the user.
-- No arbitrary repository root is accepted from the user after Controller selection.
-- Graph-selected paths are rechecked through Forge read policy before raw code is returned.
-- Errors return bounded diagnostics and never dump database contents.
-
-## Performance policy
-
-Phase 1 uses an on-demand sidecar request path and records timing for:
-
-- process startup
-- CodeGraph open
-- graph query
-- Context Pack merge
-
-Do not introduce a persistent sidecar pool until measurements show startup/open dominates p95 planning latency. If pooling is later justified, use bounded per-repository LRU instances with explicit close/eviction and no file watcher.
-
-This avoids adding a new always-running process before benchmark evidence exists.
-
-## Phase 1 implementation steps
-
-1. Add the read-only sidecar and host provider with availability/freshness reporting.
-2. Add unit tests proving no mutation operations are exposed by the provider protocol.
-3. Add `structural_context` to `controller_context_pack`; default remains `off`.
-4. Merge CodeGraph structural candidates with existing text-search candidates while retaining policy checks and raw snippets.
-5. Update `SKILL.md` so explicit `-plan` requests structural context and explicit `-debug` prefers it when available. Do not change automatic Direct routing.
-6. Add focused tests for unavailable provider fallback, stale-index warnings, graph candidate ranking, denied-path rechecks, and output bounds.
-7. Run a live Forge CodeGraph query and record evidence before declaring CodeGraph integration ready.
-
-## Acceptance criteria
-
-Phase 1 is accepted only when all of the following are true:
-
-- Node.js 20.10 remains the public Forge baseline.
-- Default Direct workflow and Route Policy are unchanged.
-- `controller_context_pack` with no structural option performs no CodeGraph process work.
-- `structural_context=auto` degrades cleanly when CodeGraph is unavailable.
-- `structural_context=required` reports a clear blocker/degraded state instead of silently pretending structural evidence exists.
-- Sidecar opens the index read-only with sync disabled.
-- A query cannot invoke CodeGraph mutation APIs.
-- CodeGraph-selected files still obey Forge path policy before raw source is returned.
-- Context Pack output remains bounded.
-- Typecheck and targeted Context Pack/provider tests pass.
-- A real query against Forge's `.codegraph` index returns structural evidence.
-- No second Forge Runtime, rollout slot, or hidden managed browser/process authority is introduced.
-
-## Architecture review
-
-Review result: approved for Phase 1.
-
-Reasons:
-
-- Reuses the existing Context Plane instead of widening the top-level tool surface.
-- Preserves the Node 20 public contract by isolating the SDK runtime requirement.
-- Separates derived-index maintenance from read-only planning.
-- Keeps Direct fast by making structural context opt-in.
-- Preserves Forge path policy as the final authority for raw code access.
-- Provides a measurable migration path: on-demand sidecar first, pooling only after benchmark evidence.
-
-Rejected alternatives:
-
-1. Import CodeGraph directly into Controller: rejected because it raises the effective Node runtime requirement to 22.5+.
-2. Use `codegraph serve --mcp` directly for Plan reads: rejected for Phase 1 because its normal lifecycle includes connect-time catch-up and watcher/auto-sync behavior, which blurs the read-only planning boundary.
-3. Add new Forge top-level `codegraph_*` MCP tools: rejected because the existing five-facade architecture should remain the preferred host surface.
-4. Parse CodeGraph CLI human-readable output: rejected because the SDK provides a typed API and CLI text is a weaker protocol contract.
-5. Auto-sync before every Plan: rejected because derived-state mutation must be explicit and should not inflate planning latency without evidence.

package/docs/architecture/current/control-plane-authority-inventory.md

@@ -1,94 +0,0 @@
-# Control-plane authority inventory
-
-Status: current implementation  
-Cutover date: 2026-08-05
-
-## Invariant
-
-Each mutable control-plane record family has exactly one writer. For the
-migrated families below that writer targets
-`<durable-controller-home>/control-plane.sqlite`. Git stores source and accepted
-documentation; artifact roots store bounded external evidence. Neither is a
-second lifecycle writer.
-
-## Mutable families and writers
-
-| Family | SQLite identity | Sole writer boundary | Read/default projection |
-| --- | --- | --- | --- |
-| Requirement | `requirement/controller/<requirementId>` | Requirement store and Requirement facade CAS operations | Requirement Board |
-| ExecutionPlan | `plan_contract/<repoId>/<planId>` | Plan-contract store and migrated completion transaction | Requirement Board and Execution Diagnostics |
-| PlanStep | versioned member of its ExecutionPlan row | Plan mutation transaction; never Task JSON | Execution Diagnostics; deprecated Task alias derives from this state |
-| Work and Requirement/Plan relationship | Work/contract namespaces scoped to repository | Work lifecycle store | Execution Diagnostics |
-| Portfolio migration marker | `requirement_portfolio_migration/<repoId>/requirement-portfolio-20260802-v1` | one-time migration transaction | cutover guard and audit diagnostics |
-| Revision/audit | `control_plane_records`, `control_plane_audit` | SQLite store transaction | integrity and recovery inspection |
-| Repository identity | Git and repository registry, not Issue/Task | repository registration and Git observation paths | Work/diagnostic identity fields |
-| Logs, binaries and large evidence | artifact files referenced by stable IDs | process/check/artifact owners | evidence references only |
-
-## Frozen compatibility surfaces
-
-The following surfaces have no durable runtime mutation authority after the
-migration marker exists:
-
-- repository Issue JSON/Markdown creation, status, archive and update;
-- repository Task status, verification, completion and dependency mutation;
-- `currentIssue` and legacy project-state mutation;
-- legacy project-board mutation and default Issue/Task board;
-- task-ledger and handoff artifact writes;
-- governance reconciliation that mutates Issue/Task/project state;
-- MCP aliases for legacy Issue/Task/currentIssue mutation;
-- Local Bridge Issue/Task/currentIssue mutation routes;
-- fallback overwrite or repository-to-SQLite reconciliation;
-- Work-to-Task durable reverse projection.
-
-Pre-cutover parsing helpers and ephemeral Issue support may remain for an
-unmigrated fixture or historical tool compatibility. Every durable public entry
-checks the migration marker before reading or writing a legacy file. This is not
-a dual-writer allowance.
-
-## Compatibility read contract
-
-A historical Issue/Task alias may appear only in Execution Diagnostics or an
-explicit legacy read API. Its state is derived from authoritative Requirement,
-ExecutionPlan, PlanStep and Work rows. Responses identify themselves as
-`deprecated`, `frozen`, `readOnly` and `controller-home-sqlite` authoritative.
-Changing the source Issue/Task file after cutover cannot alter the projection.
-
-The default user view is Requirement Board. It does not select a
-`currentIssue`, expose a mutable legacy board or infer execution state from Git
-JSON.
-
-## Export contract
-
-`requirement-portfolio-export` is SQLite-to-offline only. It includes the source
-revision, migration fingerprint, per-record SQLite revisions and a content
-fingerprint. Publication is staged and atomic. It cannot target `tasks/issues`,
-has `replayAllowed: false`, and export failure does not affect the committed
-SQLite transaction.
-
-## Deletion verification
-
-The final cutover tests prove:
-
-1. all durable Issue/Task writer entry points fail at the cutover guard;
-2. no source file contains both an authoritative SQLite writer call and a
-   legacy writer call;
-3. no reverse export importer or stale-projection replay path exists;
-4. late legacy writes leave SQLite-derived views unchanged;
-5. Canonical Runtime and standalone Recovery minimum bootstrap do not depend on
-   legacy Issue/Task files.
-
-Any later non-critical compatibility residue is recorded as a
-MaintenanceFinding. It does not reopen a completed Requirement unless the user
-outcome itself regresses.
-
-## Session continuation versus HandoffItem
-
-The frozen `handoff artifact writes` rule refers to lifecycle/decision handoff state. Current hooks may write only the ignored, rebuildable host-session cache under `.ai/harness/session/`; those files are projections for fresh-session context and are never control-plane writers.
-
-A decision requiring ChatGPT or user judgement is represented by Runtime `HandoffItem` and surfaced through `rh_inbox`. Session Markdown cannot create, acknowledge, resolve, dismiss, supersede, or expire a `HandoffItem`.
-
-`HandoffItem` persistence intentionally remains Controller-owned JSON at `Controller Home/repositories/<repoId>/handoff-inbox/index.json`, written atomically under the repository handoff-inbox lock. It is the sole authority for the attention/decision inbox. It is not moved into the Requirement/Plan/Work SQLite tables merely for storage uniformity: those tables own transactional delivery lifecycle, while the inbox owns bounded human/controller judgement points. Runtime restart recovery reopens this Controller Home record; repo-local session, projection, controller-packet, and transfer files are never replayed into it.
-
-Repo-local recovery artifacts now have disjoint namespaces: `.ai/harness/session/` for rebuildable host-session context, `.ai/harness/controller/packets/` for bounded external-controller packets, `.ai/harness/projections/` for read-only compatibility/status views, and `.ai/harness/transfers/` for patch-transfer artifacts. The generic `.ai/harness/handoff/` namespace is retired.
-
-See `docs/architecture/current/legacy-governance.md` for the RepoHarness-to-Forge disposition rules.

package/docs/architecture/current/controller-repository-decoupling.md

@@ -1,148 +0,0 @@
-# Controller 与仓库解耦计划
-
-## 背景
-
-forge 已经具备 Repository Registry、`repoId`、`checkoutId` 和 controller home 运行态目录，但历史启动入口仍然以 `--repo` 为中心。这会让 MCP Gateway、Local Bridge 和具体仓库之间的边界变得模糊：服务看起来像是“从某个仓库启动并代表该仓库”，而不是“全局 controller 服务管理多个仓库”。
-
-目标架构应改为：
-
-```text
-ChatGPT / Local UI
-  -> MCP Gateway / Local Bridge
-  -> Controller Runtime
-  -> Repository Registry
-  -> repoId + checkoutId scoped repository operation
-```
-
-`repoRoot` 只应在注册仓库、兼容旧配置、具体执行命令时出现；服务级配置和运行态应逐步迁移到 controller home。
-
-## 命名边界
-
-- **MCP Gateway**：ChatGPT 连接的全局工具网关，不应绑定某个仓库身份。
-- **Local Bridge**：本机 Local Workbench/API 兼容名称，负责本地 GUI、移动 intent、本地任务入口。
-- **Repository**：被注册、选择、执行的工作目标。
-- **repoId / checkoutId**：所有仓库级操作的显式作用域。
-- **repoRoot**：仓库本地路径，只在注册和执行层使用。
-
-## 分阶段改动
-
-### Phase 1：文档与入口语义收敛
-
-- 将 `--repo` 描述为兼容默认仓库和配置引导入口。
-- 文档中明确 MCP Gateway / Local Bridge 是全局 controller 服务。
-- GUI 和用户文案避免把 Local Bridge 暴露成用户需要理解的概念。
-
-### Phase 2：Local Bridge 支持 repoId-scoped 业务入口
-
-先不迁移存储，降低风险。
-
-- `LocalBridgeServerOptions` 保留 `repoRoot` 作为兼容 fallback。
-- 新增 `controllerHome` 和 `defaultRepoId` 选项。
-- `/api/snapshot`、`/api/user-snapshot` 支持 `?repoId=` 和 `?checkoutId=`。
-- 新增 `/api/repositories/:repoId/snapshot`。
-- 新增 `/api/repositories/:repoId/user-snapshot`。
-- 仓库列表按 selected repoId 标记 current，而不是只能按启动 repoRoot 判断。
-- completion、progress、governance、assistant readiness/intent 和 recovery probe/plan/apply 入口通过 request 解析目标仓库。
-- assistant inbox/routines/memory、runtime cleanup、mobile devices 入口通过 request 解析目标仓库。
-- project-state、issue focus、launch/archive/restore、task launch/verify/accept/request-changes/cancel/dependencies 和 timeline 入口通过 request 解析目标仓库。
-- task detail、worklog export、edit session list/detail/diff/savepoint/verify/finalize/rollback 入口通过 request 解析目标仓库。
-- plugin、GitHub sync、browser target、DeepSeek handoff/request 入口通过 request 解析目标仓库。
-- local jobs 与 runs 的 detail/log/events/finish/diff/integrate/cancel/retry 入口通过 request 解析目标仓库。
-
-### Phase 3：迁移服务级运行态到 controllerHome
-
-后续迁移应拆独立任务，避免和 UI/执行逻辑混在一起。
-
-MCP service-level 配置以 controller home 为 authority：
-
-```text
-controllerHome/
-  mcp/mcp.local.json
-  mcp/mcp.runtime.json
-  mcp/mcp.oauth.json
-  mcp/mcp.oauth-tokens.json
-  mcp/mcp.tokens.json
-  local-bridge/server.json
-  local-bridge/sessions.json
-  plugins/*.json
-```
-
-继续 repo-scoped：
-
-```text
-controllerHome/repositories/<repoId>/runs
-controllerHome/repositories/<repoId>/local-jobs
-controllerHome/repositories/<repoId>/worktrees
-controllerHome/repositories/<repoId>/edit-sessions
-controllerHome/repositories/<repoId>/artifacts
-controllerHome/repositories/<repoId>/controller-state
-```
-
-仓库目录可继续保留 repo policy、兼容 symlink / projection，以及 MCP 旧版本 fallback：
-
-```text
-.forge/mcp.policy.json
-.forge/mcp.local.json              # legacy service config fallback
-.forge/mcp.tokens.json             # legacy bearer fallback
-.forge/mcp.oauth.json              # legacy OAuth passphrase fallback
-.forge/mcp.oauth-tokens.json       # legacy OAuth token-store fallback
-.forge/mcp.runtime.json            # legacy runtime fallback
-.forge/plugins/*.json
-.forge/external-filesystem-grants.json
-.ai/harness/*  # compatibility/projection only
-```
-
-## 兼容策略
-
-- 多仓库启用时，MCP 工具和 Local Bridge 写操作必须显式携带 `repoId`，不能靠启动目录猜测。
-- 单仓库启用时可以保留 sole repository fallback。
-- `--repo` 在迁移完成前继续可用，但不应被描述为服务身份。
-- MCP service-level 配置读取顺序为 controllerHome 优先、repo-local `.forge/mcp.*` legacy fallback 其次；新 controller profile setup/restart/keepalive 写入 controllerHome。
-
-## 当前完成状态
-
-- 已新增 Local Bridge request-level repo selection helper。
-- 已让 `/api/snapshot` 和 `/api/user-snapshot` 支持 repoId / checkoutId。
-- 已新增 repoId-scoped snapshot 和 user-snapshot endpoints。
-- 已将主要 Local Bridge 业务 API 改为 request-scoped repo selection，包括 completion、progress、governance、assistant、recovery、project-state、issue/task、timeline、worklog、edit-session、plugin、GitHub、toolchain、local jobs 和 runs。
-- 已将 README 的启动说明改为 registry-first / compatibility `--repo` 语义。
-- MCP HTTP service-level 配置、auth token、OAuth passphrase/token store、public origin 和 runtime state 已迁移到 controllerHome-backed storage，并保留 `.forge/mcp.*` legacy fallback。
-- 当前剩余的 `options.repoRoot` 用法集中在启动默认仓库 fallback、启动时 reconcile、stream signature、runtime policy/mobile intent 兼容入口、仓库列表默认选择和 server close/cache cleanup。
-
-## 仍未完成的架构收口
-
-### 1. MCP Gateway 身份边界复核
-
-已复核 MCP Gateway 的 controller profile 主路径：
-
-- `src/cli/mcp/server.ts` 在 controller profile 下创建 multi-repository context；`--repo .` 会被降级为未指定 repo，避免把当前目录强行当作服务身份。
-- `src/cli/mcp/multi-repository.ts` 会给工具 schema 注入 `repo_id` / `checkout_id`，并在调用时通过 Repository Registry 解析目标仓库。
-- 未传 `repo_id` 时只允许 explicit repository fallback 或 sole-repository fallback；多仓库场景应返回解析错误。
-- MCP tool 调用会使用目标仓库的 `repository.canonicalRoot` 构造 scoped context，并把 repository/runtimeStorage envelope 写回结果。
-- `src/cli/mcp/repository-tools.ts` 的 repository/git/safe-patch/command tools 已按 `repo_id` / `checkout_id` 解析目标仓库，并把 command job payload 绑定到 `repoId` / `checkoutId`。
-
-durable router 和 runtime gateway 主路径均已完成补充复核：
-
-- `src/runtime/gateway/mcp/router.ts` 会对可持久化 MCP 调用执行 `resolveRepositorySelection`，将 `repoId` / `checkoutId` 写入 ExecutionJob，并通过 `repositoryScopedToolArgs` 注入目标仓库上下文。
-- controller-scoped repository tools 仅限 `repository_register` 以及未指定仓库的 `repository_workbench`；其他 repository tools 会解析目标仓库。
-- `src/runtime/gateway/mcp/runtime-tools.ts` 的 tool definitions 暴露 `repo_id`，执行 helper `selected(ctx,args)` 使用 `repo_id` / `checkout_id` / explicit repository / sole-repository fallback 统一解析目标仓库；已抽查 work/git/local-bridge/plugin/recovery/iOS/review/runtime-cleanup 等工具段，均通过目标 repository 执行。
-
-### 2. 服务级运行态迁移
-
-MCP Gateway 的 service-level runtime/config 已迁移到 `controllerHome/mcp/mcp.*`，并将 repo-local `.forge/mcp.*` 降级为 legacy fallback。Local Bridge 仍保留 `options.repoRoot` 用于启动级 reconcile、stream signature、runtime policy 和缓存清理。短期允许作为 compatibility default；长期应迁移为 controller-home/global runtime state，并让 `repoRoot` 只出现在 repository registration 和 repository-scoped execution 层。
-
-### 3. 最小多仓库验收
-
-不需要膨胀测试，但至少应做以下针对性验证：
-
-- 注册两个仓库后，分别请求 snapshot / issue / run / plugin API，不串仓。
-- `repoId`、`checkoutId`、默认 fallback 三条路径行为明确且可解释。
-- GUI 切换仓库后，所有业务请求携带选中的 repoId。
-- Local Bridge 重启后，默认仓库只影响初始选择，不影响 request-scoped API。
-
-## 后续验收点
-
-- GUI 切换仓库后，请求应带 `repoId`，而不是依赖启动目录。
-- 多仓库注册时，Local Bridge 首页应能显示所有仓库，并正确标记当前选择。
-- MCP Gateway 启动和 ChatGPT Connector 配置应逐步不再要求用户位于某个仓库目录。
-- repo-local `.forge/mcp.*` 文件只作为 legacy fallback；后续可在迁移窗口结束后进一步降级提示或清理。