@moretea-labs/forge 1.5.0-rc.1

package/docs/README.md

@@ -0,0 +1,72 @@
+# Forge Documentation
+
+> Maintained documentation for the current Forge product and runtime. Executable behavior and [`architecture/current/`](architecture/current/) are authoritative; historical notes are context, not active contracts.
+
+[中文文档中心](README.zh-CN.md) · [GitHub](https://github.com/moretea-labs/forge) · [Releases](https://github.com/moretea-labs/forge/releases) · [Support](../SUPPORT.md)
+
+## Start here
+
+| Goal | Start | Next |
+| --- | --- | --- |
+| Install Forge | [Install and start](tutorials/01-install-and-start.md) | [Platform support](operations/platform-support.md) |
+| Connect ChatGPT | [Connect ChatGPT](tutorials/02-connect-chatgpt.md) | [MCP setup](forge-chatgpt-mcp-setup.md) |
+| Complete a first task | [First repository task](tutorials/03-first-repository-task.md) | [Public usage guide](public-usage-guide.md) |
+| Install an official provider | [Plugin management](forge-plugin-management.md) | [Provider configuration](operations/provider-configuration.md) |
+| Understand Forge | [Core Concepts](wiki/Core-Concepts.md) | [Architecture](wiki/Architecture.md) |
+| Operate or recover | [Operations](wiki/Operations.md) | [Troubleshooting](operations/troubleshooting.md) |
+| Contribute or release | [Contributing](../CONTRIBUTING.md) | [Release process](operations/releasing.md) |
+
+## Product surface
+
+The normal ChatGPT connector exposes a bounded **19-tool MCP surface**. The five preferred facades—`rh_status`, `rh_access`, `rh_inbox`, `rh_context`, and `rh_work`—cover the normal control loop; repository, source/patch, check, Process, plugin-dispatch, and result tools complete the default surface.
+
+Forge is Direct-first: investigation does not create durable Work by itself, and worktrees are introduced only when isolation is needed. Long-running commands use one Process lifecycle and return bounded summaries plus durable references.
+
+## Documentation map
+
+### Learn
+- [Tutorials](tutorials/README.md)
+- [Public usage guide](public-usage-guide.md)
+- [Features and setup levels](operations/features.md)
+- [Platform support](operations/platform-support.md)
+
+### Understand
+- [Core Concepts](wiki/Core-Concepts.md)
+- [Architecture](wiki/Architecture.md)
+- [Runtime Architecture](wiki/Runtime-Architecture.md)
+- [Work Lifecycle](wiki/Work-Lifecycle.md)
+- [Implementation map](wiki/Implementation.md)
+
+### Integrate
+- [Plugin management](forge-plugin-management.md)
+- [Provider configuration](operations/provider-configuration.md)
+- [Browser provider](operations/controller-browser-plugin.md)
+- [Desktop provider](operations/controller-desktop-plugin.md)
+- [Local system assistant](operations/local-system-assistant.md)
+- [iOS development assistant](forge-ios-development-assistant.md)
+
+### Operate
+- [Operations overview](wiki/Operations.md)
+- [Troubleshooting](operations/troubleshooting.md)
+- [Controller reliability runbook](operations/controller-reliability-runbook.md)
+- [Runtime performance diagnostics](operations/runtime-performance-diagnostics.md)
+- [Standalone disaster recovery](operations/standalone-disaster-recovery.md)
+
+### Maintain
+- [Release process](operations/releasing.md)
+- [Open-source release hygiene](operations/open-source-release-hygiene.md)
+- [GitHub repository baseline](operations/github-repository.md)
+- [Versioning](versioning.md)
+- [Security policy](../SECURITY.md)
+
+## Current runtime facts
+
+- Controller is a global multi-repository service; repository work is explicitly scoped by stable `repoId` and, when needed, `checkoutId`.
+- Controller Home owns service configuration, authentication, provider settings, durable runtime state, and release metadata.
+- The public MCP endpoint is separate from the localhost-only Controller UI.
+- Long-running work returns bounded summaries and durable references instead of unbounded logs.
+- Stable runtime rollout uses immutable releases and exact revision identity; ambiguous ownership or release drift fails closed.
+
+## Authority and history
+
+Current architecture lives in [`architecture/current/`](architecture/current/). The [architecture index](architecture/index.md) and [consolidated history](architecture/history.md) explain superseded designs. Research notes under [`researches/`](researches/) are evidence, not current contracts.

package/docs/README.zh-CN.md

@@ -0,0 +1,58 @@
+# Forge 中文文档
+
+> 这里维护 Forge 当前产品与 Runtime 的公开文档。可执行代码与 [`architecture/current/`](architecture/current/) 是当前事实来源；历史设计与研究文档只提供背景，不覆盖当前契约。
+
+[English docs](README.md) · [GitHub](https://github.com/moretea-labs/forge) · [版本发布](https://github.com/moretea-labs/forge/releases) · [支持](../SUPPORT.md)
+
+## 从这里开始
+
+| 目标 | 先读 | 接着读 |
+| --- | --- | --- |
+| 安装 Forge | [安装并启动](tutorials/01-install-and-start.zh-CN.md) | [平台支持](operations/platform-support.zh-CN.md) |
+| 连接 ChatGPT | [连接 ChatGPT](tutorials/02-connect-chatgpt.zh-CN.md) | [MCP 配置](forge-chatgpt-mcp-setup.md) |
+| 完成第一个任务 | [第一个仓库任务](tutorials/03-first-repository-task.zh-CN.md) | [公开使用指南](public-usage-guide.zh-CN.md) |
+| 安装官方 Provider | [插件管理](forge-plugin-management.md) | [Provider 配置](operations/provider-configuration.md) |
+| 理解 Forge | [核心概念](wiki/Core-Concepts.md) | [架构](wiki/Architecture.md) |
+| 运维与恢复 | [Operations](wiki/Operations.md) | [故障排查](operations/troubleshooting.zh-CN.md) |
+| 贡献与发布 | [贡献指南](../CONTRIBUTING.md) | [发布流程](operations/releasing.zh-CN.md) |
+
+## 当前产品面
+
+普通 ChatGPT Connector 默认暴露 **19 个 MCP 工具**。`rh_status`、`rh_access`、`rh_inbox`、`rh_context`、`rh_work` 五个 facade 覆盖主要控制循环，其余默认工具负责仓库、源码/补丁、check、Process、插件分发与结果读取。
+
+Forge 默认 Direct-first：仅调查不会创建 durable Work；只有真正需要隔离时才建立 worktree。长命令由同一个 Process 生命周期管理，并返回有界摘要与可继续读取的引用。
+
+## 文档地图
+
+### 学习与使用
+- [教程目录](tutorials/README.zh-CN.md)
+- [公开使用指南](public-usage-guide.zh-CN.md)
+- [功能与配置层级](operations/features.zh-CN.md)
+- [平台支持](operations/platform-support.zh-CN.md)
+
+### 理解架构
+- [核心概念](wiki/Core-Concepts.md)
+- [架构](wiki/Architecture.md)
+- [Runtime 架构](wiki/Runtime-Architecture.md)
+- [工作生命周期](wiki/Work-Lifecycle.md)
+- [实现地图](wiki/Implementation.md)
+
+### 集成能力
+- [插件管理](forge-plugin-management.md)
+- [Provider 配置](operations/provider-configuration.md)
+- [桌面 Provider](operations/controller-desktop-plugin.md)
+- [本地系统助手](operations/local-system-assistant.zh-CN.md)
+- [iOS 开发助手](forge-ios-development-assistant.md)
+
+### 运维与维护
+- [故障排查](operations/troubleshooting.zh-CN.md)
+- [发布流程](operations/releasing.zh-CN.md)
+- [GitHub 仓库基线](operations/github-repository.md)
+- [版本策略](versioning.md)
+- [安全策略](../SECURITY.md)
+
+## 当前事实与历史
+
+Controller 是全局多仓库服务，但执行始终由稳定 `repoId` 和必要时的 `checkoutId` 明确限定。Controller Home 保存服务配置、认证、Provider、持久状态与发布元数据；公网 MCP 与仅本机可见的 Controller UI 相互分离。
+
+当前架构以 [`architecture/current/`](architecture/current/) 为准；[`architecture/history.md`](architecture/history.md) 与 [`researches/`](researches/) 用于追溯历史和证据，不是当前运行契约。

package/docs/architecture/chatgpt-handoff-facade.md

@@ -0,0 +1,393 @@
+# ChatGPT Handoff Inbox and MCP Facade Architecture
+
+## Purpose
+
+This design keeps ChatGPT as the strong interactive controller while making Forge a safer, smaller, and more useful repository control plane.
+
+The architecture addresses two current bottlenecks:
+
+1. Forge can execute work but cannot proactively return pending decisions to the ChatGPT control conversation.
+2. ChatGPT sees too many narrow MCP tools, making tool selection harder as new repository and plugin capabilities are added.
+
+The solution is not to make Forge a replacement LLM agent. The solution is to expose a small ChatGPT-facing facade, route concrete work through internal capabilities, and record pending decisions in a durable Handoff Inbox.
+
+## Design principles
+
+- ChatGPT remains the strong主控 for ambiguous design, product, architecture, and high-risk decisions.
+- Forge owns deterministic control-plane work: repository state, worktrees, task lifecycle, evidence, verification, policy, and cleanup.
+- Codex or another coding agent may be used as a worker, but Forge remains the scheduler, verifier, and policy gate.
+- Internal capabilities may grow, but the ChatGPT-facing tool surface should stay small and stable.
+- New features should register internal capabilities instead of adding one visible MCP tool per feature.
+- All ChatGPT-facing responses should be bounded summaries by default, with explicit detail/ref follow-up.
+- Risky operations should return approval requests, not be exposed as separate high-risk tools.
+
+## Capability domains
+
+Forge has at least two peer capability domains. They should be modeled in parallel, not nested under each other.
+
+### Repository capabilities
+
+Repository capabilities operate on code, tasks, checks, branches, worktrees, commits, and evidence.
+
+Examples:
+
+- inspect repository status
+- create or reuse a worktree
+- read task context
+- apply bounded edits
+- run verification
+- summarize diff and evidence
+- commit, merge, or cleanup after policy approval
+
+### Plugin capabilities
+
+Plugin capabilities operate on external service integrations or assistant runtime extensions. They are not inherently repository operations, even if their configuration or tests live in the repository.
+
+Examples:
+
+- Gmail plugin actions
+- Calendar plugin actions
+- browser plugin actions
+- GitHub plugin actions
+- future assistant/runtime plugins
+
+### Why they should be parallel
+
+Treating plugin capabilities as a subset of repository tools causes tool growth and mixed permissions. A browser preview, a GitHub issue sync, and a repository verification check have different risk shapes. They should all register as internal capabilities with metadata, but ChatGPT should not receive a new top-level tool for each one.
+
+The common abstraction should be:
+
+```text
+Capability
+  id
+  domain: repository | plugin | controller | evidence | maintenance
+  operation class: read | write | execute | verify | finalize
+  risk: low | medium | high | destructive
+  input contract
+  result contract
+  exposed via facade operation
+```
+
+This keeps plugin abilities and repository abilities extensible without growing the public MCP surface.
+
+## ChatGPT-facing facade
+
+The facade is a small set of stable tools. It should hide controller internals such as runId, checkoutId, raw job payloads, leases, fingerprints, and plugin-specific implementation details unless explicitly requested through a detail path.
+
+Recommended first surface:
+
+```text
+rh_status   - current controller/repo/task readiness and pending attention
+rh_inbox    - list, get, ack, resolve handoff items
+rh_context  - task, repo, diff, evidence, recent attempts, context map
+rh_work     - start, continue, verify, repair, finalize, stop
+```
+
+A later `rh_evidence` can be split out if evidence becomes too large for `rh_context`.
+
+### Facade operation rule
+
+Operations describe generic workflow actions, not business-specific features.
+
+Good operations:
+
+```text
+start
+continue
+verify
+repair
+finalize
+list
+get
+ack
+resolve
+```
+
+Bad operations:
+
+```text
+fix_durable_job_response
+migrate_mcp_runtime_config
+repair_browser_preview
+sync_gmail_plugin
+```
+
+Business meaning belongs in `objective`, `task_id`, `acceptance_criteria`, `runbook_ref`, and evidence summaries.
+
+## Unified facade result
+
+Every ChatGPT-facing facade should return the same outer envelope.
+
+```text
+FacadeResult
+  status: ok | blocked | failed | approval_required | not_found
+  summary: short natural-language summary for ChatGPT
+  data: bounded structured data
+  evidence_refs: bounded references to detailed evidence
+  warnings: policy or validation warnings
+  suggested_next_actions: concrete facade calls that are safe next steps
+  raw_available: whether a more detailed view exists
+```
+
+`suggested_next_actions` is important because it turns Forge into a guided workflow. ChatGPT should not have to choose from many tools after every result. The controller should return a small set of next safe actions.
+
+## Handoff Inbox
+
+The Handoff Inbox is the durable bridge from background work back to the ChatGPT主控.
+
+Forge should create a handoff when it reaches a state where a strong controller should decide the next step.
+
+Typical triggers:
+
+- verification failed and the repair direction is ambiguous
+- work is ready for review or merge approval
+- an operation was blocked by policy
+- a background task discovered a new candidate issue
+- a plugin capability needs configuration or user authorization
+- a coding agent completed work but Forge cannot safely finalize
+
+### Handoff item contract
+
+```text
+HandoffItem
+  id
+  repo_id
+  task_id
+  title
+  severity: info | needs_review | blocked | failed | ready_to_continue
+  status: pending | acknowledged | in_progress | resolved | dismissed | superseded
+  reason: why ChatGPT/main controller is needed
+  summary: what happened
+  current_state: bounded repo/task/work state
+  evidence_refs: evidence references, not raw logs by default
+  recommended_decision: what ChatGPT should decide
+  recommended_prompt: continuation prompt for a new or resumed ChatGPT session
+  suggested_next_actions: safe facade calls for the next step
+  created_at
+  updated_at
+```
+
+### Handoff lifecycle
+
+```text
+pending -> acknowledged -> in_progress -> resolved
+```
+
+Additional terminal states:
+
+```text
+dismissed
+superseded
+expired
+```
+
+The inbox should be pull-friendly. ChatGPT or a scheduled checker can call `rh_inbox list`, read the highest-priority pending item, then continue with `rh_context` and `rh_work`.
+
+## Policy gate
+
+Permissions should not be encoded by creating more MCP tools. They should be enforced by a policy gate below the facade.
+
+The gate classifies each requested capability invocation as:
+
+```text
+allowed
+approval_required
+denied
+dry_run_only
+```
+
+Examples:
+
+- reading bounded task context: allowed
+- running a known targeted check: allowed
+- creating a worktree for scoped work: allowed or approval-free if low/medium risk
+- committing a scoped verified change: allowed when task policy permits
+- merging to main: approval_required
+- deleting a worktree: approval_required unless it is controller-owned and terminal
+- running arbitrary shell from ChatGPT input: denied or approval_required
+- reading raw tokens, auth files, or full environment: denied by default
+
+## Avoiding security-prone ChatGPT request shapes
+
+ChatGPT-facing tools should avoid request shapes that look like unconstrained local execution or agent takeover.
+
+Prefer this shape:
+
+```text
+rh_work({
+  operation: "continue",
+  task_id: "T17",
+  mode: "supervised",
+  constraints: { max_changed_files: 6, allow_merge: false }
+})
+```
+
+Avoid this shape:
+
+```text
+execute_command({ command: "..." })
+run_agent({ prompt: "do anything needed" })
+```
+
+Execution should be staged:
+
+1. ChatGPT submits a high-level intent through a facade.
+2. Forge returns a preview, policy classification, and suggested next actions.
+3. Forge creates a controller-owned worktree or direct-edit session internally.
+4. Risky execution requests become approval requests with bounded previews.
+5. Raw logs, large stdout/stderr, local paths, and secrets are not returned by default.
+
+This design reduces the chance that ChatGPT triggers safety systems with a broad local-execution request. It also gives Forge a stronger audit trail.
+
+## Execution mode selection
+
+The facade should not force every request into the Goal Workloop. Forge needs a lightweight router that preserves the existing fast path while upgrading only the work that benefits from recovery, isolation, worker execution, approval, plugin authorization, or background continuation.
+
+### Direct Control
+
+Use Direct Control when ChatGPT is actively supervising a small, clear change.
+
+Typical conditions:
+
+- expected files are three or fewer
+- expected changed lines are roughly two hundred or fewer
+- scope and paths are clear
+- no external plugin side effect is required
+- no worker or background recovery is required
+- no merge, cleanup, or destructive approval is required
+
+Direct Control may still use bounded primitives such as search, read, direct edit, patch, targeted check, and selected-path commit. It is a fast execution path, not a policy bypass.
+
+### Goal Workloop
+
+Use Goal Workloop when the work has enough complexity to benefit from a durable contract.
+
+Typical conditions:
+
+- multi-step implementation or verification
+- controller-owned worktree isolation
+- Codex or another worker may be useful
+- explicit policy approval may be needed
+- a later ChatGPT session may need to resume
+- plugin capability or external service state is involved
+
+The Goal Workloop can internally choose direct edit, isolated worktree, worker execution, or handoff, but ChatGPT should not have to select the low-level mechanism in the request shape.
+
+### Handoff-only
+
+Use Handoff-only when Forge should not execute yet.
+
+Typical conditions:
+
+- the objective is underspecified
+- acceptance criteria are missing
+- allowed paths are unclear
+- a plugin is missing authorization
+- the next step requires product or architecture judgment
+- the operation is high risk and lacks approval
+
+Handoff-only creates a pending decision packet for ChatGPT or the user. It should not become a general log sink.
+
+### Routing rule
+
+```text
+small + clear + supervised
+  -> Direct Control
+
+clear + complex or needs recovery/worker/approval/external effect
+  -> Goal Workloop
+
+unclear or unsafe without a decision
+  -> Handoff-only
+```
+
+This rule prevents process inflation: direct edit remains the default for small supervised work, and Goal Workloop is an escalation path rather than a universal wrapper.
+
+## Work start flow
+
+The expected implementation flow for new work is:
+
+```text
+ChatGPT request
+  -> rh_status / rh_context to inspect readiness
+  -> rh_work start or continue with bounded constraints
+  -> policy gate decides allowed / approval_required / denied
+  -> Forge creates worktree or edit session
+  -> internal capability executes work
+  -> evidence is captured as bounded references
+  -> rh_work returns summary and suggested_next_actions
+  -> if blocked or review-needed, Handoff Inbox item is created
+```
+
+For low-risk documentation or contract work, Forge may use a bounded direct-edit session. For isolated code changes, Forge should prefer a controller-owned worktree. ChatGPT should not need to choose the low-level mechanism unless the user explicitly asks.
+
+## Capability registry
+
+New features should be added to the registry, not to the ChatGPT-visible tool list.
+
+Example:
+
+```text
+Capability: browser_result_preview
+  domain: plugin
+  operation_class: evidence
+  risk: low
+  exposed_via: rh_context.evidence
+```
+
+```text
+Capability: stale_worktree_cleanup
+  domain: maintenance
+  operation_class: finalize
+  risk: medium
+  exposed_via: rh_work.finalize
+```
+
+```text
+Capability: durable_job_bounded_response_check
+  domain: controller
+  operation_class: verify
+  risk: low
+  exposed_via: rh_work.verify
+```
+
+This prevents new feature work from expanding ChatGPT's tool menu.
+
+## Implementation stages
+
+### Stage 1: documentation and contracts
+
+- Document Handoff Inbox and MCP facade architecture.
+- Define `HandoffItem` and `FacadeResult` contracts.
+- Define the first facade operations and result envelopes.
+- Document policy and safety rules.
+
+### Stage 2: Handoff Inbox MVP
+
+- Add persistent handoff storage under controller-home repository runtime storage.
+- Add create/list/get/ack/resolve operations internally.
+- Surface pending handoff count in status.
+- Create handoffs from blocked, failed, approval-required, and ready-to-continue states.
+
+### Stage 3: MCP facade MVP
+
+- Add `rh_status`, `rh_inbox`, `rh_context`, and `rh_work` facade tools.
+- Route existing controller actions through facade operations.
+- Return `FacadeResult` consistently.
+- Mark legacy narrow tools as internal/deprecated for ChatGPT use.
+
+### Stage 4: capability routing and policy gate
+
+- Add capability metadata and routing.
+- Move plugin and repository operations behind the same registry/policy model.
+- Enforce approval_required for merge, cleanup, raw detail, and arbitrary execution.
+
+### Stage 5: worker integration
+
+- Let `rh_work` schedule Codex or another worker only after policy classification.
+- Keep Codex as a worker, not the owner of task lifecycle.
+- Forge remains responsible for verification, evidence, finalization, and handoff.
+
+## Acceptance for this architecture
+
+The design is successful if ChatGPT can operate Forge primarily through four stable entry points, if background work can leave a resumable handoff, and if new repository or plugin capabilities can be added internally without growing the public tool list.

package/docs/architecture/current/README.md

@@ -0,0 +1,158 @@
+# Current Controller Runtime Architecture
+
+> **Runtime Authority** — this directory is the approved architecture source for Forge Controller Runtime.
+
+## Purpose
+
+This directory defines the architecture that implementation work must converge toward. It exists to prevent runtime behavior from being inferred from whichever V5, V6, V7, V8, plan, research report, or Issue happens to be read first.
+
+Forge is designed as an **Agent Engineering Control Plane**:
+
+```text
+Thin Gateway
+  -> Global Control Plane
+     -> Per-Repository Actor
+        -> Durable Job Queue
+           -> Isolated Worker
+              -> Evidence Plane
+```
+
+The architecture is both technical and operational. It defines not only modules and processes, but also:
+
+- who may decide;
+- who may execute;
+- how work is persisted and recovered;
+- when tasks may run concurrently;
+- what counts as a conflict;
+- how multiple repositories share system resources;
+- how scheduled work remains bounded;
+- what evidence is required before completion or release.
+
+## Authority Statement
+
+The documents in this directory are the sole architecture authority for the current Controller Runtime.
+
+The execution control-plane topology is implemented, but the lifecycle simplification described by `runtime-architecture-simplification.md` remains a target under migration. Normative documents must distinguish current behavior, approved target rules, and compatibility boundaries using these labels:
+
+### Current Implementation
+
+Verified behavior that exists in code, tests, persisted schemas, or observable runtime state.
+
+Use this label only when a repository path or executable check can support the claim.
+
+### Architecture Requirement
+
+A non-negotiable behavior that current and future implementations must preserve. Runtime evidence is listed in `implementation-status.md`.
+
+### Compatibility Rule
+
+A rule that protects existing tools, stored state and callers while the runtime uses the new control-plane implementation.
+
+## Reading Order
+
+Read the architecture in this order:
+
+1. `system-overview.md` — boundary, layers, and process topology.
+2. `personal-assistant-plugin-baseline.md` — concrete assistant/plugin/GitHub/Gmail/Calendar boundary and migration baseline.
+3. `architecture-invariants.md` — non-negotiable rules.
+4. `entity-model.md` — durable entity meanings and ownership.
+5. `job-and-run-lifecycle.md` — execution, retry, cancellation, and terminal-state semantics.
+6. `dispatch-and-agent-strategy.md` — selection of Direct Edit, Quick Agent, durable Tasks, and Agent roles.
+6a. `thin-harness-v1.md` — Fast Path router, typed batch, lightweight lanes, and durable escalation rules.
+7. `scheduler-and-resource-claims.md` — repository actors, claims, leases, workspace conflicts, and integration queues.
+8. `multi-repository-execution.md` — cross-repository quotas, fairness, DAGs, and failure isolation.
+9. `automation-and-schedule-engine.md` — schedules, bounded occurrences, deduplication, budgets, and stop conditions.
+10. `failure-recovery.md` — Gateway, Controller, Worker, orphan, stale, timeout, and reconciliation behavior.
+11. `verification-and-release-gates.md` — exact-revision verification, acceptance, release freeze, and human authorization.
+12. `implementation-status.md` — verified implementation coverage and compatibility boundaries.
+13. `migration-roadmap.md` — completed execution-plane phases and the active lifecycle convergence record.
+14. `runtime-architecture-simplification.md` — single-owner services, canonical authority/config, immutable activation, Recovery boundary, invariants, and deletion map.
+15. `runtime-directory-map.md` — executable module boundaries.
+16. `operations-runbook.md` — health, recovery and release operations.
+17. `governance.md` — ownership, ADR, drift, and maintenance rules.
+18. `session-aware-execution-and-authorization.md` — Session Context, Work Handle, Goal delegation, and resumable approval boundaries.
+19. `runtime-health-and-resource-lifecycle.md` — shared health evaluation, projection freshness, capability status, attention/history, and bounded ownership-aware cleanup.
+20. `runtime-architecture-simplification.md` — canonical single Runtime lifecycle, release and recovery boundary.
+21. `human-interaction-plane.md` — foreground provider sessions, durable human handoff, profile fencing, and safe resumption.
+
+
+## Architecture Layers
+
+The approved top-level layers are:
+
+| Layer | Primary responsibility | Must not own |
+| --- | --- | --- |
+| Thin Gateway | Authentication, validation, routing, compact reads, durable command acceptance | Long execution, Agent lifetime, heavy checks |
+| Global Control Plane | Repository registry, global quotas, portfolio scheduling | Repository-local workflow mutation |
+| Per-Repository Actor | Repository-local ordering, claims, conflict decisions, integration and release coordination | Cross-repository global locks |
+| Workflow Plane | Issue, Task, Schedule, Occurrence intent and dependency state | Process lifetime and raw logs |
+| Durable Execution Plane | Job acceptance, dispatch, Run attempts, commands, checks, workers | Product acceptance decisions |
+| Workspace Plane | Workspace/worktree allocation, Git integration, resource leases | Business intent |
+| Evidence Plane | Diffs, checks, logs, artifacts, verification and release evidence | Scheduling policy |
+| Projection Plane | Compact snapshots, indexes, dashboard and MCP read models | Source-of-truth state mutation |
+
+## Source-of-Truth Rules
+
+- Issue and Task files own durable work intent.
+- Jobs own asynchronous system-operation state.
+- Runs own individual Agent execution attempts.
+- Edit Sessions own transactional direct modifications.
+- Verification records own exact-revision completion evidence.
+- Event logs own audit history.
+- Atomic snapshots and indexes are projections optimized for reads and recovery.
+- The controller task ledger projection (`.ai/harness/controller/task-ledger.json` and `.ai/harness/handoff/controller-current.md`) is a compact recovery/read model derived from durable Issue, Task, Run, and worklog state; its `status` field is a deterministic continuation hint for controller recovery, not a competing mutable task source.
+- The controller context pack is a transient Projection Plane read model for scoped code investigation. It may return live Git metadata, validation hints, ranked candidate files, and bounded raw snippets, but it must not become source-of-truth for implementation decisions or replace exact source, diff, and validation review.
+- Chat history, UI state, worker self-reports, and in-memory maps are never durable truth.
+
+## Historical Documents
+
+Superseded V5–V8 decisions are consolidated in [`docs/architecture/history.md`](../history.md), which is explicitly **Historical Design — Not Runtime Authority**. Detailed legacy documents are retained by Git history rather than published as parallel architecture surfaces.
+
+The history may describe behavior that still exists, behavior that was removed, or behavior not yet migrated. It never overrides this directory.
+
+## Change Discipline
+
+A change requires architecture review when it modifies any of the following:
+
+- process or service boundaries;
+- authority or ownership of state;
+- entity meanings or lifecycle transitions;
+- task dispatch or Agent-selection behavior;
+- concurrency, conflict, claim, lease, or integration semantics;
+- multi-repository isolation or fairness;
+- schedule, retry, budget, or stop-condition behavior;
+- verification, acceptance, release, or destructive-operation boundaries;
+- public MCP execution contracts or durable schema compatibility.
+
+The expected sequence is:
+
+```text
+request or ADR
+  -> current architecture update
+     -> implementation Task
+        -> executable verification
+           -> architecture drift check
+```
+
+Implementation may precede the documentation update only for an urgent incident fix. In that case the change must record a temporary architecture drift item with an owner and closure condition.
+
+## Completion Standard
+
+The architecture baseline is complete only when:
+
+- every required document exists;
+- terms have one meaning across documents;
+- Current Implementation and Target Architecture are distinguishable;
+- every normative invariant has an implementation owner or migration item;
+- historical documents are visibly non-authoritative;
+- automated checks protect the document set and authority markers;
+- future Issues can cite these documents instead of reconstructing strategy from conversation history.
+
+See [Architecture Governance Contract](governance.md).
+
+
+- [Forge + ChatGPT current comprehensive architecture (zh-CN)](chatgpt-Forge-current-architecture.zh-CN.md)
+- [Approved target architecture (zh-CN)](approved-target-architecture.zh-CN.md)
+- [Personal assistant/plugin baseline](personal-assistant-plugin-baseline.md)
+- [Target requirements traceability](target-requirements-traceability.md)
+- [Human interaction plane](human-interaction-plane.md)