@moretea-labs/forge 1.5.0-rc.1

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

@@ -0,0 +1,82 @@
+# 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.

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

@@ -0,0 +1,148 @@
+# 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；后续可在迁移窗口结束后进一步降级提示或清理。

package/docs/architecture/current/dispatch-and-agent-strategy.md

@@ -0,0 +1,354 @@
+# Dispatch and Agent Strategy
+
+> Status: **Runtime Authority**
+
+## 1. Objective
+
+Dispatch converts a user or automation objective into the smallest safe execution mechanism. The goal is not to maximize Agent use. The goal is to select the least expensive mechanism that can produce reviewable evidence without losing recoverability.
+
+The Controller owns dispatch decisions. Workers and Agents execute scoped contracts; they do not decide whether the system should have used Direct Edit, a durable Task, or another repository.
+
+## 2. Work Assessment
+
+Every change request is assessed before execution using:
+
+```text
+objective clarity
+known paths
+expected files
+expected changed lines
+investigation depth
+runtime or environment dependencies
+parallelism need
+dependency graph need
+verification duration
+risk
+external side effects
+repository count
+```
+
+The assessment produces:
+
+```text
+recommendedMode
+confidence
+reasons
+requiredScope
+requiredClaims
+verificationClass
+humanBoundary
+```
+
+Repository search is an information-gathering step, not by itself a reason to start an Agent or create a durable Issue.
+
+## 3. Execution Modes
+
+### 3.1 Direct Edit
+
+Direct Edit is the default when the Controller understands the implementation and can bound the change precisely.
+
+Preferred characteristics:
+
+- objective and behavior are understood;
+- target paths can be found with bounded search;
+- approximately eight or fewer files;
+- approximately one thousand or fewer changed lines;
+- no autonomous compile/fix loop is required;
+- risk is not destructive;
+- focused verification exists.
+
+Flow:
+
+```text
+search/read
+  -> begin Edit Session
+  -> bounded revisions
+  -> inspect aggregate diff
+  -> focused checks
+  -> finalize or rollback
+  -> Task verification when linked
+```
+
+Direct Edit MUST use the same Workspace single-writer resource boundary as a Workspace Agent.
+
+### 3.2 Quick Agent
+
+Quick Agent is used when the objective is clear but implementation requires meaningful exploration or repeated local edit/test cycles, without needing a durable multi-Task dependency graph.
+
+Preferred characteristics:
+
+- one coherent objective;
+- one reviewable result;
+- bounded path scope;
+- no long-lived cross-session product workflow;
+- retry can replace the whole attempt;
+- Agent autonomy provides clear value over Direct Edit.
+
+Quick Agent work may use ephemeral Issue metadata, but Job and Run evidence remain durable.
+
+### 3.3 Issue and Task
+
+A durable Issue/Task graph is required when work has one or more of:
+
+- multiple independently verifiable objectives;
+- dependencies or ordered migration phases;
+- parallel implementation opportunities;
+- high or destructive risk;
+- protected or release-sensitive surfaces;
+- cross-repository work;
+- long-running verification or environment dependencies;
+- schedule-driven recurrence;
+- a need for review and recovery across multiple sessions;
+- release or rollout coordination.
+
+A durable Task is not ceremony. It is the unit that owns scope, dependencies, evidence, retry history, and acceptance.
+
+## 4. Decision Order
+
+The Controller applies this order:
+
+```text
+1. Is the request read-only?
+2. Can bounded Direct Edit safely satisfy it?
+3. Is one scoped Agent attempt sufficient?
+4. Does the work require a durable Task graph?
+5. Does it cross repositories or require a Schedule?
+6. Does any external or destructive boundary require human authorization?
+```
+
+The system MUST NOT default to Agent execution merely because an Agent is available.
+
+## 5. Agent Roles
+
+Agent roles describe responsibility, not permanent products.
+
+### Controller / Architect
+
+Normally ChatGPT or a human-guided controller.
+
+Owns:
+
+- problem understanding;
+- architecture decisions;
+- Task decomposition;
+- acceptance criteria;
+- scope and resource declarations;
+- Agent and execution-mode selection;
+- review and acceptance.
+
+The Controller SHOULD remain runtime-light and MUST NOT become the hidden owner of a long Worker process.
+
+### Explorer
+
+A read-only role used for:
+
+- root-cause investigation;
+- architecture mapping;
+- candidate path discovery;
+- dependency analysis;
+- risk assessment.
+
+Explorer output is evidence or a proposed plan. It does not authorize writes.
+
+### Implementer
+
+A scoped worker role used for:
+
+- code or document changes;
+- local compile/test/fix loops;
+- producing a reviewable diff;
+- reporting limitations and unresolved blockers.
+
+An Implementer cannot accept its own Task.
+
+### Verifier
+
+An optional independent role for high-risk, safety-sensitive, or ambiguity-prone work.
+
+The Verifier MUST use the Task's declared checks and acceptance criteria as its rubric. It MUST NOT invent a competing quality standard or replace authoritative repository tests.
+
+Independent verification is not a default for every Task because extra evaluators can add cost and drift without improving acceptance alignment.
+
+### Integrator
+
+Integration is a deterministic system role, not an LLM role.
+
+It validates source evidence, base revisions, target state, supported file operations, conflicts, and cleanup. An Agent may explain a conflict, but must not silently decide to overwrite it.
+
+### Release Steward
+
+The Release Steward evaluates the release gate, produces the release manifest, and identifies unresolved human boundaries. It cannot silently push, merge, publish, or deploy.
+
+## 6. Runtime Agent Selection
+
+Tasks remain executor-neutral. At dispatch time the Controller chooses among enabled providers based on capability and constraints.
+
+General policy:
+
+| Work characteristic | Preferred executor |
+| --- | --- |
+| Small understood change | Direct Edit |
+| Broad repository exploration and repeated code/test loop | Codex or Claude local Agent |
+| Architecture, policy, documentation, semantic cross-module review | ChatGPT, Claude, or Direct Edit after analysis |
+| GitHub-native collaboration and draft PR | GitHub Copilot session |
+| Deterministic check, command, integration, or release gate | Non-Agent Worker |
+| Read-only root-cause map | Explorer role |
+
+Agent choice considers:
+
+```text
+required tools
+repository language
+context size
+expected autonomy
+local availability
+provider health
+cost budget
+past failure classification
+need for GitHub collaboration
+```
+
+A Task does not permanently bind to one Agent. However, switching Agents after failure requires a reason, not reflex.
+
+## 7. Failure Classification Before Retry
+
+Before retry or Agent switching, classify the failure:
+
+- `infrastructure_failure` — transport, process launch, authentication, unavailable provider;
+- `scope_conflict` — resource or allowed-path collision;
+- `environment_failure` — missing dependency, build service, credentials, external system;
+- `implementation_failure` — produced change does not compile or satisfy checks;
+- `acceptance_failure` — implementation works locally but misses declared criteria;
+- `integration_failure` — reviewed change cannot be integrated safely;
+- `agent_capability_mismatch` — execution requires capabilities unavailable to the selected Agent;
+- `controller_contract_failure` — Task scope, acceptance, or prompt was insufficient or contradictory.
+
+Response policy:
+
+| Classification | Default response |
+| --- | --- |
+| Infrastructure | Retry same contract after recovery |
+| Scope conflict | Wait, re-scope, or isolate |
+| Environment | Block with external dependency evidence |
+| Implementation | Request focused changes or retry same Agent |
+| Acceptance | Refine implementation, not the criteria unless product intent changed |
+| Integration | Preserve Worktree; repair from current target state |
+| Capability mismatch | Select a more suitable Agent/provider |
+| Controller contract | Re-plan Task before another Run |
+
+## 8. Task Execution Contract
+
+Every Agent Run receives a generated contract containing:
+
+```text
+repository and checkout identity
+Issue and Task objective
+current implementation context
+allowed and forbidden paths
+required outputs
+acceptance criteria
+named checks
+risk and destructive boundary
+resource placement
+base revision
+budget and deadline
+result and artifact paths
+completion and stop conditions
+```
+
+The prompt MUST state that:
+
+- unrelated changes are forbidden;
+- repository state is authoritative over chat memory;
+- the Agent must not commit, merge, push, publish, deploy, reset, rebase, or remove Worktrees unless the explicit contract permits it;
+- test failure must be reported honestly;
+- a successful self-report does not complete the Task;
+- user modifications outside scope must be preserved.
+
+## 9. Budget Model
+
+Every Agent or scheduled execution SHOULD declare bounded budgets:
+
+```text
+wall-clock timeout
+maximum retries
+maximum parallel children
+maximum changed files
+maximum changed lines
+maximum output bytes
+optional token or provider cost budget
+```
+
+Budget exhaustion produces a durable outcome. It must not silently extend itself indefinitely.
+
+## 10. Placement Decision
+
+Placement is separate from Agent selection.
+
+### Workspace
+
+Use when:
+
+- no other write owner exists;
+- work is serial;
+- fast local iteration is valuable;
+- the user expects changes in the visible working tree.
+
+### Worktree
+
+Use when:
+
+- another writer is active;
+- independent Tasks should run concurrently;
+- isolation is explicitly requested;
+- the main Workspace is dirty and safe direct ownership cannot be established;
+- implementation should be reviewed before integration.
+
+### GitHub branch/provider
+
+Use when:
+
+- remote collaboration is requested;
+- the provider requires a remote branch;
+- a draft PR is a desired artifact;
+- local execution is unavailable.
+
+The default `auto` placement policy chooses Workspace for one local serial writer and Worktree when concurrency exists. It MUST still honor explicit claims and dirty-state safety.
+
+## 11. Review and Continuation
+
+After execution:
+
+```text
+read Run/Job outcome
+  -> inspect diff and evidence
+  -> classify defects or blockers
+  -> integrate when isolated
+  -> verify exact Revision
+  -> accept or request changes
+  -> unlock dependents
+```
+
+The Controller may use Direct Edit for a small correction after an Agent Run. This creates separate, reviewable evidence rather than asking the Agent to rerun the entire task unnecessarily.
+
+## 12. Anti-Patterns
+
+The dispatch layer MUST avoid:
+
+- starting an Agent for a deterministic one-file edit;
+- creating a durable Issue solely because file discovery is needed;
+- binding every Task permanently to Codex;
+- launching multiple Agents with overlapping unknown write scopes;
+- using a Verifier with criteria different from Task acceptance;
+- retrying on every network error without idempotency lookup;
+- treating a successful process exit as product acceptance;
+- allowing an automation Agent to recursively create unlimited work;
+- using the Controller conversation as the only execution state.
+
+## 13. Current Implementation
+
+The repository implements Direct Edit, Quick Agent and Issue/Task assessment; runtime Agent selection; bounded Task scope; persistent Runs; Workspace/Worktree placement; and risk-adaptive verification.
+
+The Thin Gateway keeps deterministic local commands on Direct Edit or Process Runtime paths. Agent dispatch is now an explicit external-Controller handoff; the Kernel no longer creates Execution Jobs for ordinary Agent launches. Work ownership, repository placement, and resource claims remain durable Controller state, while provider selection and model execution belong to the claimed external Controller.
+
+Failure outcomes are retained on Work, Process, Handoff, or legacy read-only Job evidence as applicable; retries preserve the failed attempt and create a new explicit continuation attempt rather than falling back to implicit Job creation.