@moretea-labs/forge 1.6.0 → 1.7.1

package/docs/README.md

@@ -1,6 +1,6 @@
 # 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.
+> Maintained documentation for the current Forge product and runtime. Executable behavior and [`architecture/CURRENT.md`](architecture/CURRENT.md) are authoritative for implementation facts and architecture contracts; 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)
 
@@ -11,8 +11,8 @@
 | 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) |
+| Install an official provider | [Plugin management](forge-plugin-management.md) | [Plugin management](forge-plugin-management.md) |
+| Understand Forge | [Current architecture](architecture/CURRENT.md) | [Roadmap](ROADMAP.md) |
 | Operate or recover | [Operations](wiki/Operations.md) | [Troubleshooting](operations/troubleshooting.md) |
 | Contribute or release | [Contributing](../CONTRIBUTING.md) | [Release process](operations/releasing.md) |
 
@@ -31,15 +31,14 @@ Forge is Direct-first: investigation does not create durable Work by itself, and
 - [Platform support](operations/platform-support.md)
 
 ### Understand
+- [Current architecture](architecture/CURRENT.md)
+- [Roadmap](ROADMAP.md)
+- [Architecture evolution](architecture/EVOLUTION.md)
+- [Version architecture snapshots](architecture/versions/)
 - [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)
@@ -53,9 +52,10 @@ Forge is Direct-first: investigation does not create durable Work by itself, and
 - [Standalone disaster recovery](operations/standalone-disaster-recovery.md)
 
 ### Maintain
+- [Roadmap](ROADMAP.md)
+- [Release changelog](../CHANGELOG.md)
 - [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)
 
@@ -69,4 +69,4 @@ Forge is Direct-first: investigation does not create durable Work by itself, and
 
 ## 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.
+Current architecture lives only in [`architecture/CURRENT.md`](architecture/CURRENT.md). [`ROADMAP.md`](ROADMAP.md) records current priorities, [`architecture/EVOLUTION.md`](architecture/EVOLUTION.md) records architecture history, and [`architecture/versions/`](architecture/versions/) stores release-family snapshots. Research notes and task records are evidence, not current contracts.

package/docs/architecture/CURRENT.md

@@ -0,0 +1,178 @@
+# Forge Current Architecture
+
+Status: **Runtime Authority**
+
+This file is the sole maintained architecture authority for the current Forge runtime. Executable code and persisted schemas are authoritative for implementation facts; this document defines the architecture contracts they are expected to preserve. Do not hard-code a source commit here: release-specific snapshots belong in [`versions/`](versions/).
+
+## Product model
+
+Forge is an executable AI harness for a semantic controller. The controller owns requirement interpretation, repository understanding, implementation decisions, review, and the decision to keep exploring. Forge supplies fast context retrieval, deterministic local execution, provider actions, bounded verification, evidence, and optional durable continuity. Forge verification and evidence are factual inputs, not semantic acceptance rules: only the semantic Controller decides whether acceptance criteria are satisfied, whether another round is needed, or whether a Goal is complete.
+
+```text
+Semantic Controller
+  -> Context Engine
+  -> Thin Execution Harness
+  -> Verification / Evidence
+  -> Optional Durable Workflow / External Effect boundary
+```
+
+Quality is prioritized over interactive performance; performance is prioritized over durability machinery that does not materially improve ordinary coding.
+
+## Controller efficiency contract
+
+- The optimization unit is a **semantic checkpoint**, not a single low-level operation. GPT may issue one intent that mechanically fans into several bounded reads/searches or one coherent edit-plus-validation transaction when the implied steps require no new semantic judgement.
+- Forge may execute deterministic conditionals such as `check failed -> collect bounded diagnostics and failure-site source`; it must stop before semantic actions such as choosing a repair, widening product scope, or deciding that acceptance is satisfied.
+- Controller turns should stay continuous through a coherent implementation slice. External Controller relay is for real continuity boundaries such as scheduling, long waits, context/session rollover, or unattended resumption, not a normal inner-loop coding primitive.
+- Operational output is aggressively bounded, while source/diagnostic evidence may use a larger information budget when that reduces repeated controller round trips. Every evidence bundle remains source/revision identified and reports truncation or coverage gaps rather than claiming semantic completeness.
+- ChatGPT-native perception/compute capabilities are not copied into Forge merely to centralize tools. Web/Vision/one-shot connector perception may stay controller-native; Forge owns the local or durable execution/evidence boundary. A separate ChatGPT sandbox is never repository source or build authority.
+
+## Context engine
+
+- `rh_context` is the primary discovery/read path and may be called repeatedly.
+- For exact or selected source paths, `rh_context` resolves applicable repository guidance by walking only that path's bounded directory ancestry from repository root to the nearest directory and returning present `AGENTS.md` / `CLAUDE.md` files in `instructionContext`. These files are guidance-only evidence: they do not consume the source `max_files` budget, define semantic scope, or become lifecycle/architecture authority. Missing optional guidance files are normal; policy denial, read failure, or bounded truncation stays visible as a coverage gap.
+- The first request may perform one broad parallel discovery fan-in; natural-language lexical terms are heuristic hints, not completeness obligations. Broad lexical discovery stops after sufficient distinct candidate evidence across multiple hints and reports the remaining coverage gap instead of scanning toward a quota for every guessed term; exact known-file and compiler-semantic retrieval remain strict.
+- Once credible paths or symbols are discovered, the semantic controller derives the next retrieval from returned source and prefers exact known paths, compiler-backed symbol navigation, or structural relationships over repeating the same broad lexical scan. Follow-up requests reuse in-process/session caches.
+- Exact known paths reserve retrieval budget and current raw source is authoritative.
+- Complete small files and complete matched symbols are preferred over arbitrary line windows.
+- CodeGraph is discovery/relationship evidence, not semantic-completeness authority. Stale structural evidence must be labeled and current changed files remain raw-source authoritative.
+- TypeScript Language Service navigation provides compiler-backed definition/reference/implementation lookup for TypeScript symbols through `rh_context`. Swift uses the same bounded `semantic_navigation` route with SourceKit-LSP, but only on explicit symbol requests and only when SwiftPM, BSP (`buildServer.json`), or compilation-database build settings are already available; Forge never performs an implicit build/index just to answer context. Xcode projects use `xcode-build-server` as the build-settings bridge. Because a present BSP can still return generic inferred flags instead of target settings, explicit Swift navigation verifies xcode-build-server compiler-option quality before starting SourceKit; obviously fallback options are rejected as incomplete. Manual `.compile` data produced from real `xcodebuild` output is validated locally, while automatic xcode-build-server mode uses a short cached BSP probe. SourceKit sessions are started lazily, serialized per repo/workspace, kept for a short two-minute idle TTL, and resynchronize changed open files; the first explicit Xcode semantic request has a bounded cold-start budget while warm requests retain the tighter interactive budget. Ordinary `rh_context` calls do not start either the BSP probe or SourceKit. Missing/stale/fallback build settings degrade explicitly to lexical/CodeGraph evidence rather than returning a false complete closure.
+- The default 19-tool MCP schemas are a deployment ABI because approved ChatGPT apps may retain a frozen action/input snapshot. Core quality capabilities therefore need a path through already-stable facade fields. `rh_context` supports precise `@tsnav` and `@swiftnav` directives in `query` as compatibility paths; refreshed clients may use the existing structured `semantic_navigation` field.
+- Exact lexical search remains necessary for dynamic registrations, manifests, string capability IDs, persisted aliases, and unrelated same-name implementations, but it is a discovery/fallback mechanism rather than the proof of static symbol completeness.
+
+## Execution lanes
+
+### Ephemeral Direct — default
+
+Ordinary local reads, Git inspection, edits, local scripts, builds, and short checks should execute with minimal controller overhead. No persistent Work is created merely because the task is complex or investigative.
+
+### Lightweight Managed
+
+Commands that outlive the interactive admission window may expose an in-memory/lightweight process handle with bounded logs and wait/cancel/status. This lane does not require durable Process records, recovery membership, or Lease ownership merely to remain queryable during the current Runtime lifetime.
+
+### Durable Workflow / Process
+
+Persistent Work/Process state is reserved for actual continuity requirements: scheduled workflows, multi-session continuation, independent deliverables, explicit recoverability, long asynchronous workflows, release boundaries, or multi-controller coordination.
+
+### External effects
+
+Remote or non-idempotent effects are explicit boundaries. Ambiguous outcomes are reported as `outcome_unknown`; Forge must not silently replay a non-idempotent remote operation.
+The low-level repository command facade classifies these operations as `durable` but does not dispatch them: it returns `not_started` with `never_auto_retry`. A typed provider action or explicitly owned Durable Workflow must perform the effect and reconcile remote state before any retry after an ambiguous result.
+
+## Work and Plan
+
+Work is a continuity/orchestration mechanism, not a coding-quality mechanism. File count, changed-line count, protected paths, dirty workspace state, review intent, or investigation alone must not create Work. Complex implementation quality is achieved through better repository understanding and fresh review, not heavier lifecycle state.
+
+Plan is optional intent/coordination state. Initial likely paths are evidence, not a frozen semantic scope. The controller may discover and edit additional policy-allowed files without creating a second lifecycle solely because understanding improved.
+
+### Persistent autonomous continuation
+
+A scheduled unattended workflow is one durable **Work + ChatGPT conversation lineage**, not one browser tab and not one schedule occurrence. The existing authorities compose into one lifecycle:
+
+1. A Schedule occurrence mechanically selects its already-bound active Work and requests `external_controller_wake`; it never invents semantic work.
+2. The ChatGPT launcher resolves the Work's durable conversation binding, opens or reattaches only the execution tab/session needed for this round, submits the continuation prompt, and records dispatch evidence. Dispatch is transport evidence only; it is not a Controller claim or semantic completion.
+3. The launched ChatGPT Controller claims the exact Work and independently reconstructs current Plan/Work/Schedule/Handoff/source/runtime evidence before deciding what to do. Chat history is useful transport context but is never the durable source of truth.
+4. ChatGPT performs semantic reasoning while Forge performs deterministic context, edit, process, provider, verification, and finalize operations. Forge may automatically execute checks or lifecycle mechanics that ChatGPT explicitly requests, but it never infers that acceptance is satisfied.
+5. Before a Controller round ends, ChatGPT records exactly one semantic disposition: `continue_immediately`, `wait`, `wait_for_user` with an active Handoff, or `goal_complete`. The exact Controller claim/release lineage fences this transition.
+6. Round-owned automation resources are cleaned only after the round reaches its settlement boundary. User-owned browser tabs are preserved; a Forge-owned ephemeral ChatGPT tab may be closed while the Work's conversation id/url binding remains durable for the next wake.
+7. `wait` keeps a persistent Work active and schedulable. A later Schedule wake must recover the same Work and same conversation lineage without requiring the user to restate the remaining task. `goal_complete` is the semantic terminal path and terminal Work automatically stops its continuation schedule.
+
+Machine-observable continuation health is derived from existing records rather than a new database: Schedule occurrence, WorkContract, ChatGPT conversation binding, ControllerSession/round relay, verification/finalization receipts, and browser cleanup evidence. Health reporting must distinguish `wake requested`, `prompt dispatched`, `Controller claimed`, `semantic disposition recorded`, `lease released`, `verification/finalize outcome`, `tab cleanup`, and `waiting/next eligible`; none of those states may be substituted for another.
+
+Transient Runtime, connector, or browser-provider unavailability may delay a wake through bounded backoff/re-arm, but must not silently terminalize the Work or permanently freeze a healthy persistent schedule. Repeated-state fencing remains a protection against semantic self-spin; recovery requires new durable evidence or a valid new Controller claim rather than blind retries.
+
+Explicit **Scale** is the opt-in coordination form of this existing model, not a separate runtime tier. `rh_work mode=scale` requires a bound approved Plan step, routes through durable bounded Work with an isolated checkout, and lets the semantic controller decompose independent deliverables across multiple Plan steps. Independent Scale Work may proceed concurrently when existing Process/resource claims permit; conflicting claims still serialize or reject through the same Lease authority. Generic `requires_parallelism` alone does not imply Scale, Plan, Work, or isolation. Scale does not introduce an agent swarm, second scheduler, or second project lifecycle.
+
+## State ownership
+
+- Git/worktree owns repository source truth.
+- Edit Session owns one deterministic local patch transaction and reviewable diff evidence.
+- Lightweight process handles own only current-runtime attach state.
+- Validation results own check evidence for the exact inputs they verified.
+- Work owns durable continuity only when continuity is actually required.
+- Durable Process owns persisted command/check lifecycle only when the selected lane is durable.
+- Runtime release/recovery state owns Forge service availability and immutable release activation; it is separate from ordinary command recovery. The canonical OS service executes an atomic byte-identical mirror of the selected signed Runtime entrypoint from the fixed physical `runtime/service/active-forge-runtime` path, while release resources and identity remain manifest-bound. The stable physical path prevents macOS TCC from treating every immutable release directory as a new responsible-process principal.
+- Historical Issue/Task/Local Job and compatibility projections must not become second mutable authorities.
+- Work lifecycle policy is separated from persistence: `work-state-machine.ts` owns legal phase/dispatch/evidence/completion transitions, while `work-contract-store.ts` owns locked persistence and applies that policy. Work completion projection is centralized in `work-completion-authority.ts`, and Work verification execution/evidence is centralized in `work-verification-service.ts`. Transports may submit requests and encode results but must not reimplement these rules.
+- Work delivery/finalization is also an application service: `work-finalization-service.ts` owns the commit/merge/cleanup/receipt transaction and `work-execution-support.ts` owns shared exact identity/cleanup primitives. MCP `execution-tools.ts` and `rh_work` compatibility glue may prepare arguments or reconcile legacy handles, but they must enter that same finalization authority rather than perform Git delivery themselves.
+- Work preparation/adoption is an application service as well: `work-preparation-service.ts` owns managed-workspace selection, WorkContract admission/reuse, exact successor-HEAD adoption and Controller ownership binding. MCP `execution-tools.ts` only decodes `work_prepare` / repository-bind requests and delegates; it must not recreate workspace admission or WorkHandle/WorkContract preparation transitions.
+- Work command execution and validation live in `work-operation-service.ts`. Both MCP Gateway and Durable Worker call this application service directly; Workers must never dynamic-import MCP transport to obtain Work semantics. The architecture gate also forbids any `runtime/control-plane` source from depending back on `runtime/gateway`.
+- Production Browser session persistence is Controller-home SQLite `BrowserSessionAuthority`. Compatibility JSON may be imported or used only when no Controller authority is available; handoff sidecars return interaction results and never write BrowserSession state directly.
+
+## Runtime and MCP boundary
+
+- Canonical Runtime is activated as one immutable whole release with a previous release retained for rollback.
+- Runtime availability/recovery keeps Forge itself healthy; it does not imply exactly-once crash recovery for every local shell command.
+- The default Controller MCP schema is the stable **19-tool** surface.
+- `core` and `advanced` expose that same stable surface.
+- `toolset=full` is an explicit compatibility profile and may contain historical definitions; current default schema construction must not depend on those legacy definitions.
+- Current schemas/handlers should live with their owning module. Legacy compatibility may delegate but must not independently own current business rules. Shared transport contracts and tool definitions belong in neutral contract/definition modules so the dependency direction remains transport -> application/domain authority rather than transport implementations importing one another.
+- Work-attributed verification is an application service, not an MCP/Local Bridge implementation detail: all Work verification resolves the Work checkout/check registry, runs through Process Runtime, validates terminal receipt identity, and records Work evidence through the same `work-verification-service.ts`.
+
+### Controller facade and handoff boundary
+
+- The stable Controller-facing facade is `rh_access`, `rh_status`, `rh_inbox`, `rh_context`, and `rh_work`. Internal repository, controller, evidence, maintenance, and plugin capabilities may grow behind the capability registry without creating another top-level tool for each feature.
+- Handoff Inbox state is durable decision state for blocked or review-needed Controller judgement. It is not a log sink and must not become a second Requirement, Plan, Work, or Process lifecycle.
+- Facade results are bounded summaries plus evidence references. Forge may report policy, verification, lifecycle, and capability facts; semantic acceptance and the decision to continue remain Controller-owned.
+
+### Host hook boundary
+
+Host hook files are integration surfaces, not lifecycle or architecture authorities. Forge-managed entries are identified so install/uninstall can change only Forge-owned entries while preserving sibling user hooks; legacy adapter entries are migration input rather than a second current identity. The hot host path converges on the minimal `forge-hook` entrypoint and current hook runtime, and CLI absence fails safely instead of turning a host hook into a repository failure. Setup/readiness flows may inspect and report host gaps but must not silently treat user-owned host configuration as current architecture state.
+
+## Provider boundary
+
+Typed provider/plugin actions should use Forge capability/resource semantics directly instead of hiding host/browser/device operations inside arbitrary repository shell commands. Built-in providers may remain inside Forge when they are tightly coupled to Controller policy and lifecycle; independent products/providers retain independent release boundaries and integrate through the Plugin Protocol.
+
+### iOS physical-device boundary
+
+- `ios-device` is the single physical-device resource domain. Backend/engine details may vary, but they must not create independent mutation authority or concurrent ownership for the same phone.
+- Agent-device readiness is capability-negotiated from a reviewed version/help contract and a stable contract fingerprint. A preferred version is support guidance rather than authority; unsupported or unreviewed pre-1.0 contracts fail closed instead of guessing flags or semantic support.
+- Application adapters own app-specific semantic targeting and assertions; provider code owns transport, device/session lifecycle, and command execution. Semantic action failure is distinct from transport/session death, and unknown mutation outcomes are fenced rather than blindly replayed.
+- iOS evidence is bounded and redacted. Read-only lifecycle/screenshot capability must never be represented as proof of semantic mutation capability.
+
+## Browser Runtime V3 contract
+
+Browser Runtime V3 is the current Browser execution authority. Controller-home BrowserSession state is the sole durable browser-session authority; stable provider/resource identity is distinct from mutable observed URL/title, and provider-local live handles are acceleration state only. The accepted Browser Runtime V2 ADR remains historical rationale rather than a competing current authority.
+
+Browser providers are selected by declared capability. Common DOM and typed browser-internal operations must remain background-safe. Native macOS sessions reuse or recover only exact Forge-owned `windowId` + `tabId` identities. Provider-wide tab inventory is an optional optimization: when the installed broker cannot enumerate tabs, Forge may create a new plugin-owned tab or validate a saved exact ref, but it must not scan for or guess an unrelated user tab.
+
+Foreground presentation is an explicit effect reserved for capabilities that truly require physical pointer/keyboard input or human handoff. Browser `trusted_input` never silently activates a background tab or converts CSS viewport coordinates into desktop coordinates. If the native broker lacks the required trusted-input capability, Browser fails with a typed capability error; an explicitly requested Desktop Operator foreground/physical action remains a separate authority boundary. Mutating provider actions are complete only when their declared postconditions are verified; transport, Apple Events, Accessibility, socket, or CGEvent success alone is not semantic completion.
+
+The public Browser action surface remains compatible across Playwright/CDP/native providers. Current native compatibility may omit optional broker methods such as global tab inventory while preserving exact-ref lifecycle safety. DOM automation through Chrome/Vivaldi Apple Events still requires the browser's JavaScript-from-Apple-Events permission; missing permission fails closed instead of weakening the provider contract. Browser replay safety is derived from the Browser Runtime transaction contract rather than an adapter-local action allowlist, and native session liveness/reconciliation is centralized outside the plugin composition root. A human-handoff host may persist its own InteractionSession result, but BrowserSession mutation returns to the canonical Runtime authority.
+
+## Testing and verification
+
+Tests are verification evidence, not an alternate architecture authority.
+
+- Development/task gate: typecheck + static architecture + generated-authority drift + source-duplication classification + controller-UI reproduction + manifest validity + affected tests.
+- Main candidate: task gate + core regression + Runtime smoke.
+- Release candidate: main gate + full regression + release packaging/readiness.
+- Static architecture additionally requires the production `src/**/*.ts` relative-import graph to be acyclic. Neutral contracts may break dependency direction; dynamic imports must not be used merely to conceal a static architecture cycle.
+- Source-duplication governance permits only classified distribution/template projections, guidance aliases, and placeholders; unclassified exact duplicates fail the gate. Generated copies may exist for packaging, but manual implementation duplication is not an accepted source-authoring model.
+- Test governance validates registration, resource classification, selection and execution isolation; it does not impose arbitrary global test-line or resource-count budgets.
+- Prefer a small number of architectural invariants, focused module tests and essential integration/E2E coverage. Delete implementation-coupled or retired-compatibility tests when the underlying obligation is removed.
+
+## Documentation authority
+
+The maintained documentation surface is intentionally small:
+
+- [`../README.md`](../README.md) — documentation entry.
+- [`../ROADMAP.md`](../ROADMAP.md) — current/next priorities.
+- `CURRENT.md` — sole maintained current architecture authority.
+- [`index.md`](index.md) — architecture navigation and lifecycle rules.
+- [`EVOLUTION.md`](EVOLUTION.md) — append-only architecture change log.
+- [`decisions/`](decisions/) — accepted ADR rationale; once a rule is ordinary current architecture it is folded into `CURRENT.md` and the ADR remains historical rationale.
+- [`versions/`](versions/) — architecture snapshot created at release/version boundaries.
+- [`history/`](history/) and [`history.md`](history.md) — archived historical evidence and compatibility history, never runtime authority.
+- [`../../CHANGELOG.md`](../../CHANGELOG.md) — release/user-visible change log.
+
+Architecture-root Markdown is deliberately restricted to `CURRENT.md`, `EVOLUTION.md`, `history.md`, and `index.md`. A proposed architecture change belongs in a request/ADR or durable Plan/Work evidence until its accepted invariant is folded into `CURRENT.md`; do not create a parallel root-level "current design" page. Execution statuses such as phases, "implementation in progress", pending manual validation, operator-specific paths, and machine-local observations belong in Work/Plan/evidence or the history archive, not in maintained current architecture.
+
+Research notes, tasks, reviews, archived architecture pages, plans and Git history are evidence/history only. They do not need to be synchronized on every source edit.
+
+## Intentionally retained compatibility debt
+
+- Explicit `toolset=full` remains a supported legacy compatibility boundary for now. Issue/Task/project-board writers are migration-only compatibility and are permanently retired after the SQLite requirement-portfolio cutover marker; they must not become a second current control plane.
+- Some large runtime modules still aggregate multiple responsibilities and should be decomposed only when a clear ownership boundary is available.
+- CodeGraph may be structurally stale between index refreshes; current raw source and changed-file overlays remain authoritative.
+
+These items belong on the roadmap, not in parallel current-architecture documents.

package/docs/architecture/EVOLUTION.md

@@ -0,0 +1,42 @@
+# Forge Architecture Evolution
+
+Status: **Historical Design — Not Runtime Authority**
+
+Append-only summary of why the architecture changed. The current contract is always [`CURRENT.md`](CURRENT.md); detailed superseded implementations remain available through Git history instead of parallel maintained architecture documents.
+
+## 2026-08-18 — Quality-first executable harness
+
+- Reframed Forge as an executable harness for the semantic controller rather than a lifecycle-heavy coding control plane.
+- Made repository context progressive and repeatable; exact known paths receive reserved budget and source materialization prefers complete symbols/small files.
+- Kept CodeGraph as discovery evidence while current raw source remains authoritative.
+- Added an internal zero-dependency TypeScript Language Service navigation prototype and benchmarked real Forge refactors; compiler references found useful caller structure while exact lexical search still found unrelated same-name/registration paths.
+- Moved ordinary shell wrappers and inline interpreters onto Lightweight/direct execution when high-level effect classification permits it.
+- Removed dirty workspace, protected path and review intent as automatic Work triggers; Work remains for continuity/orchestration/external-effect needs.
+- Retired hundreds of lines of unreachable Local Bridge execution/submission code instead of relocating it.
+- Detached the default 19-tool Controller schema from the historical legacy tool-definition set; `toolset=full` remains explicit compatibility only.
+- Simplified test governance: affected tests for development, core regression for main candidates, full regression for release candidates; removed arbitrary global test-line/resource-count budgets.
+- Consolidated current architecture documentation into a single `CURRENT.md`, a single roadmap, this evolution log and per-version snapshots.
+
+## 2026-08 — Canonical Runtime and thin public surface
+
+- Converged Runtime activation on immutable whole releases with standalone recovery and exact release identity.
+- Reduced the normal ChatGPT Connector surface to a bounded 19-tool schema and separated public Gateway concerns from Canonical Runtime execution.
+- Moved ordinary repository actions toward direct/lightweight paths while retaining durable paths for explicit lifecycle requirements.
+
+## Earlier Controller generations
+
+Earlier V4–V8 Controller, Local Bridge, Supervisor, Issue/Task/Job and recovery designs are retained in Git history and accepted ADRs where still useful. They are not maintained as parallel current architecture authorities.
+
+## 2026-08-26 — Documentation lifecycle governance
+
+- Folded the still-current Controller facade/Handoff, host-hook ownership, and iOS physical-device provider invariants into `CURRENT.md` from current source rather than preserving old implementation plans as parallel authority.
+- Retired root-level phase/status design pages into the history archive; accepted ADRs and version snapshots remain rationale/snapshots while `CURRENT.md` remains the sole current architecture contract.
+- Added deterministic task-gate protection so new root-level parallel architecture pages and stale current-status/personal-machine identity markers fail existing static architecture verification instead of relying on a daemon or manual cleanup pass.
+
+## 2026-08-27 — Browser Runtime V3 becomes current authority
+
+- Promoted the Browser provider/resource transaction model from V2 migration rationale to the current V3 runtime contract while retaining one public Browser action surface.
+- Kept controller-home BrowserSession state as the only durable browser-session authority and made exact native `windowId` + `tabId` identity authoritative across warm-handle invalidation and cold rebind.
+- Made provider-wide native tab inventory optional for compatibility with the stable Desktop Operator broker: absence of inventory may reduce cross-tab reuse, but must never permit guessing or adopting an unrelated user tab.
+- Kept foreground/physical input explicit. Browser background actions never silently activate a tab; Desktop Operator foreground/physical actions remain a separate verified capability boundary.
+- Added current-source live acceptance coverage for Chrome/Vivaldi native lifecycle, background foreground-preservation, URL drift/rebind, replacement postconditions, internal resources, cleanup, and attributable latency reporting. Environment-owned browser permission gaps remain typed external blockers rather than reasons to weaken the runtime contract.

package/docs/architecture/current/README.md

@@ -1,159 +1,7 @@
-# Current Controller Runtime Architecture
+# Legacy current-architecture path
 
-> **Runtime Authority** — this directory is the approved architecture source for Forge Controller Runtime.
+> **Historical compatibility path — Not Runtime Authority**
 
-## Purpose
+The maintained Forge architecture moved to [`../CURRENT.md`](../CURRENT.md).
 
-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, bounded human-interaction handoff, profile fencing, and safe resumption.
-22. `control-plane-authority-inventory.md` — single-writer persistence families and frozen legacy writers.
-23. `legacy-governance.md` — RepoHarness inheritance, session-continuation boundary, CLI governance, and deletion rules.
-
-
-## 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 | Requirement, PlanStep, Work, 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
-
-- Migrated Requirement, ExecutionPlan/PlanStep, Work, dependency, receipt, validation, and approval lifecycle state is single-writer state in `<durable-controller-home>/control-plane.sqlite` as defined by `control-plane-authority-inventory.md`.
-- Git owns source code and accepted source artifacts such as specs, design notes, and captured plans; those artifacts are not a second lifecycle writer after migration.
-- Jobs own asynchronous system-operation state and 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, indexes, task-ledger files, historical Issue/Task aliases, `tasks/current.md`, and `.ai/harness/session/*` are projections or compatibility/session caches only.
-- The legacy controller task-ledger projection is read-only after control-plane cutover and cannot mutate Requirement/Plan/Work state.
-- 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)
+This directory is retained only so old links fail gracefully. Detailed pre-consolidation architecture pages were removed from the maintained working tree; their exact content remains available in Git history. Do not add new current architecture documents here.

package/docs/architecture/decisions/20260803-release-identity-binding-and-exit-policy.md

@@ -2,7 +2,7 @@
 
 - **Status:** Accepted and aligned with the Canonical Forge Runtime
 - **Date:** 2026-08-03; revised 2026-08-09
-- **Authority:** [`../current/runtime-architecture-simplification.md`](../current/runtime-architecture-simplification.md), [`../current/failure-recovery.md`](../current/failure-recovery.md)
+- **Authority:** [`../CURRENT.md`](../CURRENT.md), [`../CURRENT.md`](../CURRENT.md)
 
 ## Decision
 
@@ -25,7 +25,7 @@ Authority order is:
 3. an owning Git checkout only for explicit developer launches;
 4. never an ambient parent repository.
 
-The OS service manager starts and automatically restarts the single `forge-runtime` root process after unexpected process death. Module readiness failure does not create component restart authority. A release transition stops and starts the complete Runtime, verifies binary whole-Runtime readiness, and on failure restores the previous complete release together with its bound SQLite backup.
+The OS service manager starts and automatically restarts the single `forge-runtime` root process after unexpected process death. The service executes from the stable physical path `ControllerHome/runtime/service/active-forge-runtime`; that file is an atomic byte-for-byte mirror of the signed entrypoint in the selected immutable release, not a symlink into `runtime/releases/<releaseId>`. Release assets and semantic identity remain bound by the selected manifest and `FORGE_RELEASE_*` environment. The fixed physical executable path is required so macOS TCC descendants inherit one stable responsible-process identity across releases instead of creating one permission principal per release directory. Module readiness failure does not create component restart authority. A release transition stops and starts the complete Runtime, refreshes the stable mirror from the selected release before launch, verifies binary whole-Runtime readiness, and on failure restores the previous complete release together with its matching stable mirror and bound SQLite backup.
 
 Standalone Recovery remains independently installed. It may diagnose the service, repair the service definition or tunnel, and perform authorized offline whole-Runtime rollback when the primary Runtime cannot start. It never becomes a second scheduler, Gateway, state writer, or component owner.
 

package/docs/architecture/decisions/20260823-immediate-controller-relay.md

@@ -0,0 +1,53 @@
+# ADR: Immediate Controller Relay
+
+- **Status:** Accepted for the Forge 1.6.x stabilization line
+- **Date:** 2026-08-23
+- **Authority:** [`../CURRENT.md`](../CURRENT.md), [`../../../AGENTS.md`](../../../AGENTS.md)
+
+## Decision
+
+ChatGPT remains the semantic Controller. Forge may persist and execute an explicit end-of-round Controller disposition, but it must never infer that a Requirement, Goal, or Work should continue.
+
+The supported dispositions are:
+
+```text
+continue_immediately
+wait
+wait_for_user
+goal_complete
+```
+
+`continue_immediately` creates a durable `controller_round_relay` record under the existing Controller Home SQLite authority. It does not create a second scheduler, daemon, lifecycle owner, or autonomous agent. The current ChatGPT controller must own the exact live Work lease when it submits the disposition. Dispatch begins only after that lease is explicitly released.
+
+A ChatGPT wake is a two-stage mechanical lifecycle: `dispatched -> claimed`. Browser prompt submission proves only transport dispatch. The round becomes `claimed` only when an authenticated ChatGPT Controller acquires the exact Work lease. Neither state is semantic acceptance. A claimed round must still end with an explicit ChatGPT disposition. If the lease disappears without a disposition, Forge may mechanically re-dispatch after the bounded liveness grace; it must not infer whether the Goal should continue or complete.
+
+The relay reuses the existing ChatGPT controller-browser launcher path. The originating Work's durable ChatGPT conversation binding is inherited automatically and then carried forward by stable relay scope, so later rounds and later Works under the same Requirement/Goal can reuse the same ChatGPT conversation without making chat history authoritative. Requirement, Work, Handoff and evidence state remain the source of truth.
+
+A Requirement-bound relay scope is `requirement:<requirementId>`. A Goal without a durable Requirement uses an explicit stable goal scope; the initial fallback is `goal:<originWorkId>`. The next ChatGPT round may select or create a different Work under the same semantic scope.
+
+## Lifecycle authority
+
+- `rh_work controller_disposition` records the Controller's explicit semantic decision.
+- `controller_release` is the only transition that may consume a pending immediate relay for that Work.
+- the canonical ChatGPT launcher performs the next-round dispatch;
+- Controller Session ownership, principal/session/instance fences, Handoff authority and external-effect policy remain unchanged and cannot be bypassed by Relay;
+- `wait_for_user` requires an active Handoff bound to the relevant Work or repository decision surface.
+
+## Mechanical anti-spin policy
+
+Forge may block repeated execution mechanically, without making a semantic product decision. The relay records bounded round count, repeated semantic-state fingerprint count and consecutive launch failures. Limits can be tightened by a Controller but cannot be loosened inside an existing relay scope. A blocked relay requires a fresh Controller decision or explicit recovery.
+
+## Failure and cleanup
+
+A failed next-round launch records failure evidence and does not silently retry, fabricate progress, or create an alternate scheduler. If Browser/ChatGPT launch requires a user or host permission, the relay stops at that external blocker.
+
+Terminal dispositions (`wait`, `wait_for_user`, `goal_complete`) leave no runnable immediate relay. Completed or superseded relay records are historical control-plane evidence and are subject to the same bounded Controller Home retention/maintenance policy as other durable control-plane records; they have no independent process or service cleanup lifecycle.
+
+## Verification
+
+- a same-principal but different live MCP session cannot submit a disposition for another session's Work lease;
+- `continue_immediately` remains pending until explicit controller release;
+- the existing Work-to-ChatGPT conversation binding is inherited when the Controller omits browser/session URL arguments;
+- repeated unchanged state and round/failure budgets fail closed;
+- Runtime architecture retains one Scheduler and one lifecycle owner;
+- a live browser dispatch is required before the stabilization baseline is declared complete.

package/docs/architecture/decisions/20260826-browser-runtime-v2.md

@@ -0,0 +1,73 @@
+# Browser Runtime V2: unified authority and provider transactions
+
+Status: accepted migration architecture
+Date: 2026-08-26
+
+## Decision
+
+Forge Browser converges on one controller-owned Browser Runtime. The public `browser` plugin action names remain stable during migration, but provider-specific workflows are internal implementation details.
+
+The durable source of truth for Browser sessions is Controller Home SQLite. A provider may keep an ephemeral live handle, cache, socket connection, CDP session, Apple Events reference, or Accessibility element reference, but it must not maintain a second durable Browser-session authority.
+
+A Browser session separates **stable target identity** from **mutable observed state**. The identity names the exact provider resource (for example a Chrome window/tab identity or a managed page identity). URL and title are observations of that resource and may change without invalidating the session. This applies to supported browser-internal resources such as `chrome://bookmarks/`: changing an internal route or query parameter is not a new tab identity.
+
+## Capability ladder
+
+The Runtime selects providers by declared capability rather than by catching one provider failure and falling through a long chain. Capabilities include DOM read, DOM interaction, browser-internal resources, screenshot/vision, trusted physical input, foreground authority, provider transaction execution, and persistent handle reuse.
+
+Preferred order is capability-driven:
+
+1. persistent DOM/CDP/extension/native background capability for normal web work;
+2. typed browser-internal-resource capability for bookmarks/tabs/downloads/history-like browser resources where supported;
+3. screenshot/vision only when DOM/resource APIs are insufficient;
+4. Accessibility/physical input only for operations that cannot be expressed above;
+5. foreground physical input only when the selected capability explicitly declares `explicit_required`.
+
+Foreground activation is never a hidden fallback side effect. If a provider cannot satisfy an operation without foreground authority, it returns that capability requirement to the Runtime; the controller then chooses an explicit foreground/handoff path or another provider.
+
+## Provider transaction
+
+Browser interactions use a provider-local transaction:
+
+`precondition -> action -> postcondition -> bounded evidence`
+
+The provider performs these phases in one RPC whenever it declares `browser.transaction`. Transport success, Apple Events success, `AXPress == .success`, or successful CGEvent injection are execution facts only. They do **not** make the Browser action successful unless the configured postcondition is also satisfied.
+
+A transaction binds the stable target identity, required capabilities, replay safety, foreground requirement, timeout, action, and verification predicates. Non-idempotent actions are never retried by the Runtime after an ambiguous result unless the provider supplies a transaction/deduplication identity proving that replay is safe.
+
+## Session and handle lifecycle
+
+Controller Home stores the durable BrowserSession record. Providers return ephemeral handles that may be cached for bounded consecutive actions. The Runtime revalidates the stable target identity when a handle is stale or after provider restart. It does not rediscover every provider on every action when a live compatible handle already exists.
+
+Provider restart may invalidate an ephemeral handle but not the controller session. Rebind uses exact stable resource identity and fails closed if exact-target fencing cannot be restored. User-owned resources are never silently substituted, navigated, closed, or replaced merely to recover a session.
+
+Desktop Operator remains a controller-scoped execution provider. Its generic desktop session store is not Browser session truth.
+
+## Browser-internal resources
+
+Generic top-level navigation may remain HTTP(S)-only for the public web-navigation actions. Browser-internal resources are represented through typed provider capability, not by weakening the generic URL boundary. Native/adopted Chrome or Vivaldi targets can therefore model internal resources without conflating `chrome:`/`vivaldi:` with ordinary network navigation.
+
+## Performance and round-trip budgets
+
+V2 targets the common warm path at one provider call after session resolution:
+
+| Operation | p95 target | Warm provider calls | Cold/rebind calls | Foreground |
+| --- | ---: | ---: | ---: | --- |
+| Read/extract | 350 ms | 1 | <=2 | forbidden |
+| DOM interaction + verify | 600 ms | 1 | <=2 | forbidden |
+| Browser-internal resource operation | 700 ms | 1 | <=2 | forbidden |
+| Explicit physical-input fallback | 1500 ms | 1 | <=2 | allowed only when explicit |
+
+These are architecture targets and live-gate budgets, not promises about every website or machine. A regression that exceeds them must expose attributable provider timing instead of being hidden behind controller sleeps/retries.
+
+There is no unconditional post-action sleep in the V2 transaction contract. Providers wait on explicit state/postconditions within the action timeout.
+
+## Migration
+
+1. Land this contract and architecture authority.
+2. Introduce a Runtime coordinator/provider registry behind the existing Browser action surface.
+3. Move macOS existing-browser support to capability-based persistent handles and internal-resource operations.
+4. Version the Desktop Operator browser broker with transaction execution and postcondition evidence.
+5. Add real-socket live gates and latency reporting, then remove redundant fallback/reconnect paths.
+
+Legacy compatibility remains bounded during migration and must not become an independent source of business rules.