@moretea-labs/forge 1.7.2 → 1.8.1

package/docs/architecture/CURRENT.md

@@ -1,23 +1,56 @@
 # Forge Current Architecture
 
+### Technical design baseline
+
+This authority applies one default design rule across new architecture and refactors: **Forge is thin but capable — stateless in coordination, stateful in facts, optimistic in concurrency, and explicit in effects.** The model/controller owns reasoning, workflow policy, validation strategy and semantic completion; Forge owns durable facts, execution capabilities, mechanical correctness and recoverable effects. Cognitive learning follows the same split: the model authors reusable semantic deltas and usage judgments, while the shared MCP transport may settle that bounded advisory metadata after any successful meaningful ordinary tool outcome; routine micro-steps do not create a learning lifecycle.
+
+- **One fact, one authority.** Do not repair ambiguity with mirrored status, a compatibility owner, a second lifecycle, or another orchestration store. Composition services should remain stateless over existing authorities whenever practical.
+- **Classify state explicitly.** Durable semantic facts survive restart; runtime handles/connections are ephemeral; summaries, indexes and status views are rebuildable projections. Transport or execution identity must never become semantic identity.
+- **Prefer optimistic concurrency.** Use expected-revision/CAS for semantic aggregates; serialize only the narrow aggregate or physical resource that truly conflicts, while unrelated aggregates remain parallel. Leases and fences protect liveness/physical mutation, not semantic truth.
+- **Effects are explicit.** Reserve stable effect/request identity before replay-sensitive external mutation. Reads may retry when provider semantics allow it; idempotent mutations reuse the same key; ambiguous non-idempotent outcomes become `outcome_unknown` and must be observed/reconciled before any replay.
+- **Events trigger; state decides.** Duplicate wakes/recovery demand coalesce around canonical occurrence/effect identity. Contention is a scheduling condition rather than semantic failure when the operation can run later.
+- **Keep failure domains isolated.** Browser, MCP, plugin, provider or UI transport failure degrades that adapter/capability; it does not redefine Work/Scheduler semantics. Recovery reconstructs bindings from durable truth and reconciles effects; it does not invent a fallback authority.
+- **Keep workflow policy above the Kernel.** Verification/review/merge ordering is user/model/project policy, not a reason to add durable `validating`, `reviewing`, `awaiting_acceptance`, `finalizing`, or similar Work states.
+- **Stay a modular monolith.** Kernel/domain modules expose small ports; adapters translate provider/transport semantics once; composition roots wire dependencies and do not own domain policy. Use distributed-systems correctness disciplines without distributed deployment machinery unless deployment actually requires it.
+- **Self-host through a stable control plane.** Stable Runtime evaluates candidate source/runtime; candidate validation either promotes atomically or leaves Stable authority intact.
+- **Before adding state/store/service/daemon/queue/lock/retry paths, prove the missing fact or physical resource cannot be represented by the existing authority plus CAS, a narrow resource claim, or the existing effect ledger.**
+
 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.
+Forge is an executable AI harness for a semantic controller. The controller owns requirement interpretation, repository understanding, implementation decisions and review. Forge supplies fast context retrieval, deterministic local execution, provider actions, bounded verification, evidence, and durable lower-layer continuity. Forge verification and evidence are factual inputs, not semantic acceptance rules.
+
+Long-running autonomous operation adds one higher lifecycle authority: **Workflow Supervisor** owns cross-assistant-turn scheduling for an original Goal after the current ChatGPT/MCP call stack has ended. The stable outer-turn identity is the exact logical conversation, not a Requirement, Work, MCP request, Browser tab, or provider session. ChatGPT still owns semantic reasoning and submits a bounded `CONTINUE | DONE | NEEDS_USER` decision through the canonical Forge automation receipt; Supervisor derives the exact task, conversation and applied source effect locally. Legacy assistant-text receipts remain causal read compatibility for already-durable conversations. `DONE` and `NEEDS_USER` become terminal only after the configured completion/blocker contracts validate authoritative evidence. Work, ControllerRound, Scheduler and MCP/session recovery remain lower-layer authorities and must not impersonate this outer turn scheduler. See [Workflow Supervisor authority](decisions/20260916-workflow-supervisor-authority.md). V1 persists this authority only in `${ControllerHome}/supervisor/supervisor.sqlite`; `control-plane.sqlite` and the declarative `workflow_run` namespace are lower-layer authorities and are not Supervisor storage.
+
+After explicit enrollment, the Supervisor task/effect/completion journal alone owns the prompt chain. For an already-enrolled standalone Supervisor, the fifteenth **committed** `CONTINUE` receipt since the most recent conversation migration atomically changes the successor to a fresh enrollment and records the one canonical conversation move in the same Supervisor transaction. The fresh bootstrap must be a new `/c/<id>` and cannot rebind its source conversation. Only genuinely current provider UI (not message history) may report a terminal conversation-length limit and initiate a bounded CAS-fenced migration; the duplicate-migration guard counts moves without a subsequent successful completion rather than imposing a lifetime cap. A causal `CONTINUE` atomically reserves its fixed successor; it never requires a lower Work to remain present, a ControllerRound budget to reopen, or a manufactured ControllerSession claim/release. Lower round preparation remains initial admission/direct-effect bookkeeping, and authenticated repository mutations keep their own scope, ownership and resource fences. An explicit conversation rebind denies new sends to the previous conversation while already-started effects remain eligible for read-only reconciliation. Scheduler uses canonical Work lookup for relay-referenced semantic Work instead of treating a repository projection omission as deletion. See [Supervisor turn authority](decisions/20261001-supervisor-turn-authority.md).
 
 ```text
-Semantic Controller
-  -> Context Engine
-  -> Thin Execution Harness
+Original Goal / exact logical conversation
+  -> Workflow Supervisor (cross-turn durable authority; conversation-stable task)
+  -> active Requirement/Work scope
+  -> Semantic Controller / ChatGPT turn
+  -> Context + Thin Execution Harness / Forge Work
   -> Verification / Evidence
-  -> Optional Durable Workflow / External Effect boundary
+  -> Provider / External Effect boundary
 ```
 
+Project/browser discovery is a projection into that one authority, not another scheduler. A ChatGPT Project adapter may discover exact `/c/<id>` conversation identities for a repository-derived project scope and persist bounded discovery metadata. All Work-bound ChatGPT progression enters one stateless Runtime composition: launcher, Schedule and Scheduler liveness may prepare or reuse the same ControllerSession/ControllerBinding/ControllerRound mechanical facts, but none may submit a provider turn. `launcher_start` validates the request, optionally binds an explicit/current conversation, establishes retained controller identity when needed, invokes the canonical progression composition and returns without creating a Browser session or synchronously waiting for provider delivery. The composition derives/reuses the exact ControllerRound occurrence and provider-effect identity, then reserves the corresponding Workflow Supervisor task/effect. For a fresh Work with no canonical `/c/<id>`, Supervisor registers a bootstrap task against the ChatGPT root; only after that effect is durably reserved may the provider-neutral Computer ChatGPT target port ensure a target and dispatch the provider mutation. The Computer-owned Chromium extension is the primary semantic provider and Apple Events remains a compatibility provider; neither provider owns or directly consumes the Supervisor effect ledger. After the first confirmed submission exposes ChatGPT's canonical conversation URL, Supervisor atomically adopts that exact conversation as the durable task identity. For an already-bound conversation, the same registration RPC returns the existing conversation-stable task, including across explicit predecessor/successor Work turnover. Workflow Supervisor's effect ledger is the sole Work-bound ChatGPT send/retry/outcome-unknown replay authority; each applied turn settles through its existing task-scoped Forge automation receipt, with recovery/correction causality carried only as bounded model-facing advisory context; an idle provider response lacking a receipt remains an observable applied obligation and must not automatically trigger another provider send as though generation had hung; ControllerRound retains the lower mechanical occurrence/effect identity but is not a second provider replay owner. Browser/session/Supervisor unavailability before provider submission therefore remains lower-layer availability evidence and must not consume a provider-dispatch failure budget. Explicit `bound` transport without an existing binding or explicit URL is rejected rather than guessing from the foreground browser. Repeated discovery converges on the same conversation-stable Supervisor task. A mutable project title may select a discovery scope but never becomes conversation, Goal, Requirement, Work, or terminalization authority. Browser tabs, DOM, Accessibility, Native Messaging and project pages remain replaceable transports. Computer Surface stable identities are immutable during active ownership. A terminal Surface releases its physical tab binding index while retaining stable/alias identity for explicit reactivation; legacy terminal binding indexes may be reclaimed, but an active owner cannot be displaced. ChatGPT provider mutation is one bounded external-resource lane per active authenticated Controller Browser/bridge identity: concurrent continuation/standalone sends serialize in the active Runtime, and Workflow Supervisor outer-turn delivery shares that Runtime's provider-pressure scope; explicit 429, timeout, stream-unavailable, or outcome-unknown evidence creates shared transient provider backpressure with bounded exponential delay and `Retry-After` preference; pre-submit rate limiting never becomes an ambiguous send; post-submit rate limiting remains outcome-unknown and is reconciled rather than replayed. Provider-failure classification uses dedicated live error/status UI and typed network diagnostics where available, never ordinary conversation text; while 429 backpressure is active, Workflow Supervisor may continue bounded local observation but must neither mint a rate-limit recovery effect nor submit a recovery prompt. Only an explicitly enrolled unattended-continuation task receives generation liveness recovery: if the exact conversation continues to advertise generation but its assistant/provider activity digest is unchanged for the bounded grace window, Supervisor treats that turn as stale and reserves the existing exactly-once same-conversation recovery effect; ordinary non-enrolled chats are never adopted, and the already-applied source effect is never replayed. A bound `/c/<id>` is transport identity, so navigation failure fails closed instead of falling back to the ChatGPT root or inventing a replacement conversation. Provider pressure/session state is mechanical and process-local, never Requirement/Plan/Work lifecycle authority; ControllerRound effect identity remains the durable replay fence across Runtime rotation. A canonical Runtime rotation may mechanically rebind an exact live same-principal ControllerRound to the successor Runtime, but it must preserve that round's durable authority id rather than requiring chat-driven rekey; explicit stale or foreign authority remains fail-closed. Canonical Runtime projects one package-owned Computer Chromium extension and its Native Messaging bridge into supported Chromium-family browsers, including Chrome and Vivaldi on macOS. The bridge exposes only typed Computer target commands plus bounded discovery; it does not expose Supervisor effect RPCs or create browser-specific workflow authority. Unattended Supervisor sends request highest available reasoning through the same typed Computer target; the Chromium extension first performs a read-only exact-tab content-script capability preflight (so stale pre-upgrade scripts cannot silently ignore the request), then verifies the actual provider control before prompt mutation and records the verified level in existing effect evidence. An unavailable or unverified control rejects before sending, and compatibility providers never silently claim Extra High. Direct Computer sends without a reasoning requirement preserve the user's current preference. Normal Browser sessions default to Forge-managed persistent Browser resources with native attach disabled; the macOS native browser automation bridge remains an explicit compatibility provider only. Screen unlock/frontmost requirements belong only to explicit physical-input or visible-capture capabilities that mechanically need the foreground desktop; ordinary Browser DOM delivery and Supervisor continuation do not depend on them. Ephemeral Forge-owned ChatGPT tabs are settled through the existing Browser ownership boundary and record durable per-round settlement evidence so restart/periodic reconciliation closes them at most once; user-owned tabs are preserved and a recorded preservation is likewise terminal for cleanup.
+
+Computer-owned ChatGPT delivery accepts an optional requested reasoning effort on the existing exact-target dispatch command. Unattended Workflow Supervisor prefers `xhigh`; the primary Chromium extension must select and verify the available composer level before mutation and report the **actual** verified effort (`xhigh`, `high`, or `medium`). A missing/disabled/unverified extension reasoning control fails closed. Only when the primary extension was proved unavailable **before mutation** may the existing target router select the Apple Events compatibility provider; it omits that optional effort preference, retains the exact effect and recovery mode, and never claims that `xhigh` was verified. A direct Apple Events request with an explicit reasoning requirement still fails closed. **Every Supervisor effect**, on either provider, must bind and verify the exact structured main-Forge App chip together with the complete effect payload before Send; a literal `@forge` text prefix is not a plugin invocation. An ambiguous app, invalid composer, or unavailable picker is a pre-send failure, never a text-only completion. Transport ambiguity **after** provider submission remains `outcome_unknown` under the same Supervisor effect identity, with no cross-provider retry. This is one provider capability/transport contract, not a second Work, Scheduler, completion, or reasoning authority.
+
 Quality is prioritized over interactive performance; performance is prioritized over durability machinery that does not materially improve ordinary coding.
 
+## Runtime performance acceptance
+
+Recovery runaway acceptance is `runaway-cpu-v4`. Functional verification plus a fresh, process/release-bound CPU observation (10 seconds warmup, twenty 2.5-second windows, one core = 100%) still gate known-good, but runaway is decided by *sustained* consumption: a sample is rejected only when the mean exceeds the 25% ceiling or when at least half of the observed windows reach the 50% per-window ceiling. Nearest-rank p95 remains in the evidence for audit and is no longer the decision rule, because a tail-only estimator cannot separate bounded scheduled maintenance from runaway: the Canonical Runtime's release-fenced maintenance pass lasts several seconds and recurs about once per minute, so it always occupies the second-highest window of a 50-second observation (live rollbacks: mean 11-13% with p95 ~65% on a functionally healthy Runtime). The `runaway-cpu-v3` tail estimator described in the following paragraph is superseded by this rule; the same 25%/50% ceilings, the same 60-second budget and the separate Release Evaluation/Benchmark <=10% regression contract are unchanged.
+
+Work candidate JSON filters use a Work-defined, SQLite-maintained partial index initialized during Runtime database startup; Work JSON and CAS remain authority. Read paths perform no DDL. Recovery known-good is explicit release acceptance, requiring functional verification and fresh process/release-bound CPU runaway evidence: 10 seconds warmup plus twenty 2.5-second windows, with a safety ceiling of mean <=25% and p95 <=50% (one core = 100%). The `runaway-cpu-v3` tail estimator therefore treats p95 as the second-highest of twenty windows rather than the single maximum, so one transient 2.5-second burst cannot by itself become terminal runaway evidence while repeated high-tail windows still fail the unchanged ceiling. This is deliberately a catastrophic/runaway guardrail, not comparative performance acceptance: the governed Release Evaluation/Benchmark authority owns the <=10% candidate-vs-baseline CPU regression contract. A soaking ReleaseSession may consume an already-durable, exactly matching recoverable known-good attestation for the same active release instead of repeating CPU observation; it still fences exact live Runtime/release identity before terminalizing the session. Public MCP semantic acceptance is the authenticated MCP end-to-end session (initialize, initialized notification, tools/list, read-only tools/call, session close); the separate unauthenticated external MCP probe remains diagnostic and drives dedicated external/tunnel repair, but cannot alone veto full stable verification when that stronger MCP E2E succeeds. The bounded read-only observation does not hold the exclusive Recovery mutation lock: production CPU sampling runs in one short-lived supervised child of the exact immutable `forge-recovery` release, so the persistent single Recovery daemon can keep serving Gateway/watchdog work without delaying the sampler's monotonic windows. The child is read-only execution, not another Recovery owner or writer; every sample is fenced to exact Runtime/release identity, the parent fences Recovery-release and Runtime identity again after observation, and final verification plus known-good persistence reacquire the short mutation lock. Watchdog health does not grant this acceptance or trigger CPU-based recovery. Explicit rollback cannot be vetoed by an active known-good designation; stopped-owner and whole-release/backup safety checks remain mandatory. Historical functional attestations remain rollback evidence without being reclassified as performance evidence. See [design and evidence](../researches/runtime-cpu-work-candidate-recovery-acceptance.md).
+
+ReleaseSession Candidate B storage follows the same single-authority lifecycle. The ReleaseSession domain is the only durable semantic owner of normal Runtime release progression and rollback transaction semantics, and at most one non-terminal ReleaseSession may exist per Forge instance. ReleaseSession keeps wire `schemaVersion=1` so the immediately previous Recovery release can still inventory records after rollback, while `semanticEpoch=2` is the only current internal model; migration upgrades legacy epoch-1/epoch-less records once. RuntimeReleaseAuthority is a schema-v2 physical pointer/store only: active/previous immutable release identity plus the previous SQLite backup, with no ReleaseSession activation transaction state. A stateless ReleaseCoordinator always re-derives the next action from that durable phase and never creates a Work or coordinator-local state per release phase. Explicit/manual run-to-boundary calls may drain immediately executable phases within the existing fixed safety budget, but Runtime cutover itself has one caller-independent Connector quiet fence: automatic, explicit, and plugin-driven ReleaseSession progression all defer while MCP POST/stream/initialize activity is live or while remaining sessions have not satisfied the bounded quiet window. Cutover transport safety is therefore an invariant of the provider boundary, not a request-id policy. Unattended release progression is narrower: the single persistent Standalone Recovery daemon hosts one serial trigger loop, and each reconciliation launches one short-lived supervised child of the exact immutable `forge-recovery` release that invokes exactly one `advanceConfiguredRuntimeReleaseStep`. The trigger runs only while a non-terminal ReleaseSession exists or, with no active session, when configured source HEAD differs from the active Runtime manifest `sourceCommit`; equal source identity is a strict no-op and unknown source identity fails closed. The child owns no durable state or release intent, and the next trigger always re-derives work from persisted ReleaseSession state after success, crash, timeout, cutover, or Runtime restart. Standalone Recovery implements the release-facing provider boundary for physical candidate preparation, Runtime activation, verification and rollback. Normal Runtime release reuses the installed Recovery release and never upgrades Recovery merely because Runtime source changed; Recovery upgrades remain an explicit independent operation when its own artifact/contract changes. The Recovery process runs the health/watchdog policy in-process and owns health-driven restart/recovery only, never release intent. An interrupted `source_frozen` preparation resumes the same session when source and Stable A identity still match rather than creating another authority. The current `recovery/state/release-sessions` path is a storage location, not semantic ownership. Canonical Runtime maintenance is physical retention only: on the existing `releases` cleanup phase it may remove a path-fenced Candidate Home only when durable ReleaseSession phase proves Candidate B retired (`soaking`, `known_good`, `rolled_back`, or `failed`) and no live Candidate Runtime owner remains. Resumable phases and directories without readable ReleaseSession authority are retained and surfaced as bounded diagnostics; age alone never authorizes Candidate deletion. Ordinary repository Work completes at source-delivery acceptance and never waits for staging, cutover, soak or known-good. Release-level gates run once for the frozen ReleaseSession candidate, not once per contributing Work. No second cleanup daemon, ReleaseSession writer, runtime-switch Work state, or fallback authority is permitted.
+
 ## 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.
@@ -33,14 +66,60 @@ Quality is prioritized over interactive performance; performance is prioritized
 - 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.
+- Complete small files and complete matched symbols are preferred over arbitrary line windows. Bounded source materialization never character-cuts a declared source range while reporting the original line bounds: oversized symbols are split into contiguous whole-line snippets, and if the file snippet budget is exhausted the final returned chunk is explicitly marked `truncated` with its actual end line. Partial source therefore degrades readiness instead of masquerading as complete code.
 - 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.
+- 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. For a newer semantic facade operation or newly required semantic field that an old `rh_work` schema cannot express, `operation=repair` plus `capability_id=semantic.v1:<bounded-payload>` is the generic transport-only compatibility envelope. The server owns an explicit per-operation allowlist and exact payload schema. The current allowlist admits `requirement_create` and `plan_create`: Requirement creation keeps `requirement_id` explicit outside the envelope, while frozen Plan creation transports only the missing bounded `obligation_dispositions`; Plan id, Requirement id, scope, source revision, steps and relation remain native stable arguments. Unknown operations/fields and conflicting native inputs fail closed, and both paths dispatch into the same canonical Requirement/Plan admission and Plan obligation-continuity authorities. Existing one-off field carrier `plan.obligations.v1` remains bounded migration debt for already deployed frozen clients, not a second Plan authority. No compatibility decoder owns semantic decisions or persistence. The generic envelope is removed once supported clients provide guaranteed schema/version negotiation rather than per-conversation frozen snapshots; until then new schema gaps must extend the allowlisted generic transport instead of minting one bespoke lifecycle/persistence path per 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.
 
+## Cognitive Plane
+
+- Forge has one domain-independent Cognitive Plane for long-term learning and associative recall. It follows **learn early, trust gradually**, but semantic admission, abstraction and scope are model decisions: Forge must not convert repetition counts, kinds, keywords, confidence thresholds, failures or execution codes into a rule for what deserves learning or when knowledge becomes cross-project.
+- `MemoryUnit` / `MemoryEdge` / `LearningSignal` are advisory knowledge contracts, never Work/Controller/Scheduler authority. `LearningSignal.kind` is open descriptive vocabulary. A model may emit no learning or many semantic deltas; per-call item/byte limits are transport/resource envelopes and larger semantic deltas are recorded in additional batches. Forge derives provenance and persists through `CognitiveWriteAuthorityPort`; Cognition cannot terminalize Work, weaken safety or create a parallel lifecycle.
+- Canonical cognition metadata/relations/evidence share the Controller SQLite authority. Large immutable payloads may use SHA-256 content-addressed storage. Derived lexical/concept/vector/graph/usage projections are rebuildable accelerators and cannot become competing durable truths.
+- Existing `ExperienceRecord` remains a migration-compatible canonical record and is projected transiently into cognition during recall rather than durably duplicated. New generic memories use the cognition application service. When a deterministic `forge-incident-repair:*` Work closes a ControllerRound with current passed verification receipts, the same round-close learning composition records one evidence-backed `OutcomeObservation`, one durable repair `ExperienceRecord`, and one Cognitive `MemoryUnit` with exact source Work/Round provenance. This projection describes the verified repair candidate only; it is advisory and cannot change Work acceptance, mandatory checks, approval, ReleaseSession, Runtime cutover, or known-good authority.
+- Every meaningful task start/resumption uses one bounded advisory resolver: ordinary `rh_context` work, ControllerRound composition, Workflow Supervisor turns, and Codex/Claude thin-launcher prompts share the same activation semantics. Work/Requirement/Project/Workspace candidates compete in one relevance ranking; narrower scope is a modest prior, never a Workspace starvation rule. Exact concepts expose rebuildable lexical parts, so multi-cue natural language can qualify a long memory without lowering the global cue floor. Optional semantic expansion exists only when a provider is configured; Forge does not claim vector semantics otherwise. Consolidated memory and retained `derived_from` sources consume one ordinary recall slot, while conflict/supersession views remain visible. The returned `ActivationPack` is an initial working set, not semantic completeness.
+- Every Controller MCP tool shares one optional bounded cognition-settlement transport field, so ordinary repository/edit/process outcomes can learn too; the model emits it only at a meaningful successful outcome boundary, not on routine micro-steps. Forge settles it after the primary operation succeeds, derives repository/session/time and optional selected Work/Requirement provenance, validates reachable scope/evidence, and invokes the existing Cognitive writer/usage writer. A settlement defect is visible advisory metadata/warning and cannot convert an already-applied primary effect into retry authority. `rh_work learning_record` remains a compatibility surface over the same writer. This adds no Reflection/Memory lifecycle, per-tool reflection ritual, or second durable authority.
+- Consolidation may mechanically coalesce related traceable memories while retaining source provenance, but it does not author a more abstract lesson or promote scope. Project-to-Workspace generalization is explicit model-authored semantics: the model may use repeated independent evidence as justification, but Forge has no fixed corroboration count or source-category gate. Workspace writes require explicit portable intent and remain advisory; they never create policy authority.
+- `assistant_context_usage` remains canonical ControllerRound evidence. Used/rejected feedback affects retrieval applicability, not truth confidence; stale/contradicted rejection adds explainable conflict pressure without silently deleting memory. `rh_context search` exposes bounded read-only `knowledge_*` audit over reachable Project/Workspace/Work scopes, including provenance, relations, usage and activation reasons, but audit never contributes to source mutation readiness.
+- Hot/warm/cold are retrieval/retention hints, not independent stores. Machine-native encodings remain internal implementation details; MCP/ChatGPT projection is semantic typed JSON/text. See [`decisions/20260917-cognitive-memory-foundation.md`](decisions/20260917-cognitive-memory-foundation.md).
+
 ## Execution lanes
 
+### Semantic classification authority
+
+Execution placement, lifecycle, retry, authorization, and acceptance decisions consume typed domain contracts after ingress normalization. Human-readable ids, descriptions, prompts, log text, and error messages are evidence or presentation, not machine authority. When a legacy transport can provide only strings, one bounded compatibility ingress may normalize an explicitly constrained code/token into typed state with provenance; downstream routers and domain services must consume that typed state rather than repeat regex or substring inference. Compatibility decoders never become persistence or semantic owners.
+
+### Failure contract authority
+
+Machine-visible failures have a stable code plus an explicit class and retry disposition; transport projections such as HTTP status derive from that contract. Free-form messages exist for diagnostics and user presentation. A producer-specific adapter may translate a native SDK/OS error into the failure contract once, but retry policy must not be inferred from words such as `temporary`, `worker`, or `network`, and authorization must not be inferred from arbitrary prose. Ambiguous non-idempotent outcomes use an explicit reconciliation-before-retry disposition rather than generic transient retry.
+
+### Persistent service identity authority
+
+Forge core persistent service ownership is machine-enumerable in `src/runtime/platform/service-inventory.ts`. The inventory owns exact current Runtime/Connector/Recovery identities and an explicit exact retired set; platform service managers own only launchd/systemd mechanics. Standalone Recovery is one fault-domain-independent persistent service: its HTTP/MCP provider surface and watchdog policy share one process/lifecycle owner, while launchd/systemd supervises process death. Bounded read-only helper children, such as the known-good CPU sampler, may execute from the same immutable Recovery release but never become persistent service, mutation, or lifecycle authority. Historical Recovery Gateway/Watchdog service labels are retired migration identities, not current owners. Upgrade reconciliation may retire only exact entries from the retired Forge-core set and must verify service plus installed artifact absence. Broad `com.moretea.*` / `com.moretea.forge.*` prefix retirement is forbidden. Provider-owned services such as Desktop Operator and user-configured tunnel services remain outside Forge core retirement authority even when their labels share Forge naming.
+
+### Tool Contract ABI authority
+
+The published tool contract is a transport ABI, not a second semantic authority. Current and frozen clients must enter the same canonical typed handlers. The stable `rh_work` operation registry is one ABI authority shared by MCP schema generation and server-side `SuggestedNextAction` admission, so lifecycle projection cannot invent an operation the published contract does not expose or reject an operation the schema already owns. New frozen `rh_work` compatibility travels through the versioned `semantic.v1` envelope; older ad-hoc `capability_id` prefixes are shrinking migration debt and new prefixes are rejected by the runtime architecture gate.
+
+A bridge may derive only required machine identity or CAS expectations that the target authority itself exposes through a typed status contract. Explicit caller expectations are never overwritten, partial caller-owned machine identity is rejected rather than mixed with server-derived identity, and an upgraded tool whose required fields cannot be represented fails before mutation with `RECOVERY_TOOL_SCHEMA_UNREPRESENTABLE`. Tool-surface or installed-runtime skew must remain an explicit stale/coherence condition; it must not masquerade as a missing plugin, missing user input, or authorization decision.
+
+### Root-cause repair workflow
+
+Repeated defects in routing, lifecycle, retry, authorization, schema compatibility, state projection, or placement are treated as architecture signals rather than isolated bug tickets. The required repair sequence is:
+
+1. Reproduce the smallest failing behavior and name the exact machine decision that was wrong. Do not start by adding a special case for the observed string, tool name, check id, error message, or status.
+2. Identify the current semantic owner and all inputs that influence that decision. Human-readable text, legacy status projections, transport session identity, and adapter-local inference are suspect whenever typed domain state already exists.
+3. Search the repository for the same semantic decision and equivalent heuristics. Same-root symptoms are consolidated under one repair Work/issue; they are not fixed as independent patches merely because they surfaced through different tools.
+4. Establish or select one typed owner for the decision. Adapters may normalize bounded legacy transport data once with provenance, but they do not own lifecycle, persistence, routing, retry, or acceptance semantics. Compatibility code must re-enter the canonical owner rather than create a parallel path.
+5. Migrate the highest-risk consumers first, preserving only bounded ingress compatibility that cannot yet be removed. Any compatibility debt must be visible and mechanically enumerable.
+6. Add focused behavioral regression for the old failure mode and an architecture guardrail when the defect class can recur mechanically. The regression must prove that the former heuristic no longer gains authority, not merely that the current example happens to pass.
+7. Run one representative end-to-end journey before closing the root issue family. Related issues close only after the canonical owner is in use, dominant consumers have migrated, the guardrail passes, and any tracked compatibility debt has shrunk or has an explicit remaining owner.
+
+Recurring infrastructure failures use one incident-repair authority. MCP failures and Scheduler progression/release/maintenance observations are normalized to a stable root code, recorded only as bounded evidence in the existing audit/event ledgers, and promoted after the existing recurrence threshold into one request-id-deduplicated system repair Work. Repeated observations append evidence to that Work; unrelated root codes remain separate; a terminal repair may create only the next generation for the same root. The repair Work still enters normal Work admission, approval, verification, Controller, ReleaseSession, and Runtime fencing. Event ledgers are evidence, never a second failure or Work state machine. Provider authorization, user-action waits, and outcome-unknown effects are excluded from automatic repair promotion.
+
+The runtime architecture gate maintains an AST-derived semantic-string debt ledger for authority-critical code. New human-readable string matching in machine-decision branches must not be normalized by casually extending that ledger; ledger additions are architecture exceptions requiring explicit review and a migration rationale. Ordinary repair work may only remove entries. This guardrail intentionally does not ban parsers, regexes, or string matching globally: discovery, presentation, input validation, and bounded compatibility ingress remain valid when they do not become downstream semantic authority.
+
 ### 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.
@@ -57,56 +136,154 @@ Persistent Work/Process state is reserved for actual continuity requirements: sc
 
 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.
+Effectful plugin/provider actions follow the same continuity rule. Before provider dispatch, Forge binds the stable `request_id` to one durable Process identity; the MCP/ChatGPT stream is only an observation channel. Read-only actions and explicitly `direct_non_persistent` actions may remain direct, but every other effectful plugin action executes through the managed Process sidecar. Interactive timeout, stream interruption, MCP session replacement, or Runtime rotation must reattach to the same Process/receipt and must never reacquire the provider resource for a duplicate dispatch. `apply_mode=async` requests zero interactive wait and returns the durable Process/result reference immediately. A terminal sidecar writes the authoritative plugin receipt, after which repeating the same `request_id` deterministically reads/binds that receipt without replay.
 
 ## 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.
+Current-task semantics are a pure projection of the exact Work objective and explicit Work/Requirement/Plan lineage. Requirement and Plan identifiers may define broader Goal scope, but membership alone never pulls sibling Work into the current task, Controller mechanical fingerprint, continuation decision, or exact Work context. Repository-wide active Work remains repository inventory used only for typed ownership, conflict and release-admission observations; recency never establishes current-task authority. No current-task persistence store or second writer exists.
+
+Objective decomposition is represented only by optional `semanticParentWorkId` plus bounded `dependsOnWorkIds` on primary semantic Work. `semanticParentWorkId` is a decomposition edge and is distinct from execution-child `parentWorkId`; `dependsOnWorkIds` is explicit ordering only and is never inferred from Plan items. Both relations use the same semantic Work CAS/revision history, require existing primary Work in the same canonical Work scope, reject self/cyclic edges, and project current/history graphs on read without a graph database or projection writer. Continuation/replacement remains `predecessorWorkId`/`supersedes`/`supersededBy`, so decomposition, dependency, execution ownership and continuation are four separate meanings.
+
+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. `work_complete` records the Controller's semantic completion decision rather than a Forge acceptance verdict, but semantic terminality is monotonic: `completed` and `cancelled` never reopen in place. If later evidence shows the same root cause remains incomplete, the model creates an explicit successor Work and preserves the prior terminal audit record. Terminal semantic state also starts reconciliation of Forge-owned execution resources by the existing `work_finalizer`; a repository completion receipt is delivery evidence, not a second cleanup authorization. The finalizer still independently proves exact OwnedResource identity, preserves dirty bytes and unique committed source, settles live process ownership, and honors explicit `retained_by_request` disposition before any physical removal; its cleanup receipt is durable progress/result evidence rather than lifecycle authority. Placement is a separate concern from Work creation. For mutating durable repository Work, the stable legacy/default `auto` placement is a mechanical alias for an isolated checkout with the Work start revision frozen; explicit `current` is the Controller/model choice to reuse the selected registered checkout. Admission does not infer or rewrite topology from dirty paths, task risk, parallel relations, or lifecycle state. Physical checkout isolation remains an execution fact: a shared-checkout Work and a disjoint isolated-checkout Work do not conflict merely because they share a repository id, while concrete WorkHandle, Lease, Git identity, and overlapping resource conflicts remain authoritative at mutation time. Once a mutating Work starts, its source/base is frozen until the final delivery boundary; target integration is not an implementation-time baseline update.
+
+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. Durable semantic ownership is layered as `Requirement -> semantic scope -> stable Plan -> PlanRevision audit -> Work`: Requirement is portfolio/outcome authority, not a conflict domain; `scopeKey` identifies the bounded Plan slice; one current Plan identity owns that scope; ordinary replanning advances the same Plan through a staged durable revision; historical revision records are immutable audit evidence and never own active scope, Work, scheduling, or admission authority. `supersede` is reserved for true semantic Plan replacement, not normal iteration.
+
+Same-Requirement sibling Plans with distinct scope may coexist without `parallel` ceremony, and Requirement membership alone never makes sibling Work a semantic continuation candidate. Existing Work is selected only through explicit Work relation or an exact Plan/step binding. Placement/resource conflicts remain separate execution-safety authorities, so narrowing semantic admission does not weaken single-writer or isolation fences. Older clients may still send `plan_create + plan_relation=extend + related_plan_id + a new plan_id`; that is transport compatibility only: Forge revises the related stable Plan in place and records the requested id only as bounded revision audit metadata instead of minting another active Plan.
+
+
+### Engineering Workloop authority
+
+Engineering quality evidence is versioned Work-domain state, not a second Work/Plan lifecycle. The source-controlled `ProjectEngineeringContract` remains project fact authority; Work stores only its exact revision/digest receipt. `rh_context` produces a bounded exact-revision `ContextClosureReceipt` from current source, applicable guidance, project facts, Skill routing and semantic-tool readiness. The current Runtime generation keeps a bounded issued-receipt provenance registry: content hashes prove integrity, while Runtime issuance proves the exact receipt actually came from `rh_context`; a Runtime restart intentionally requires fresh Context Closure evidence. Legacy receipt-id strings remain audit compatibility only and cannot authorize high/critical mutation.
 
-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.
+For material high/critical mutation, Runtime composition accepts semantic precondition content and mints source-bound `ProductDoDReceipt`, `DesignDecisionContractReceipt` and `IndependentCritiqueReceipt`; raw MCP arguments never carry the trusted evidence object into Kernel. Product DoD records user outcome, completion conditions, non-regression, material performance expectations and non-goals. Design records semantic scope keys and mutation class plus ownership/single-writer, transaction, lifecycle, concurrency, persistence, failure, projection/cache, time, performance and compatibility decisions. Its complexity budget makes added writers, durable mechanisms, projection paths, global invalidations, lifecycle hooks and synchronous critical-path work explicit before mutation. File paths are discovery/policy evidence, never semantic-scope authority.
 
-### Persistent autonomous continuation
+Independent critique is bound to the fresh Requirement digest, current-source Context Closure, Project Contract digest, Product DoD and exact Design receipt and only an `approved` critique satisfies high/critical admission. A same-root-cause blocker that invalidates an existing design persists `return_to_design`; when the Work already has a formal Design receipt, it marks that design `revisit_required` and mutation cannot resume until a new design explicitly supersedes the prior receipt and receives an independently `approved` critique. Progressive discovery inside the already selected architecture authority is instead classified explicitly as `same_root_cause_scope_extension`: it persists `extend_candidate`, keeps the exact Work/candidate, and continues through the same call without Design re-entry or sibling Work. Observe-only low/normal Work with no prior Design receipt keeps the conservative `same_root_cause` behavior unless the Controller explicitly classifies a bounded scope extension. An unrelated blocker deterministically creates or reuses one parallel investigation Work, persists its exact `linkedWorkId` in the `linked_work` disposition, and does not widen the current Work semantic scope. These receipts live inside existing Work authority; they do not create another persistence writer, lease, scheduler or lifecycle.
 
-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:
+### ControllerRound continuation and Workflow Supervisor boundary
 
-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.
+This section describes the durable **Requirement/Plan/Step/Work/ControllerRound execution lineage** and its boundary with the upper cross-assistant-turn Workflow Supervisor. Provider conversations, browser tabs, ControllerSession transport ids, and Schedule occurrences are delivery or trigger facts; none is allowed to become a second continuation lifecycle.
 
-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.
+1. Scheduler owns only time/event/condition triggering. A Schedule occurrence contributes its exact occurrence identity and may request a ControllerRound action, but Scheduler does not persist continuation status, provider attempt state, provider receipts, semantic wait state, or replay authority. The retired `ScheduledContinuationDispatch` / `scheduler_continuation_dispatch` state machine must not be recreated.
+2. `ControllerRound` is the sole lower-layer continuation authority. It owns semantic disposition, exact occurrence binding, semantic fingerprint suppression, provider effect identity, dispatch start/attempt, receipt, `provider_dispatch_outcome_unknown`, `wait_for_user`, recovery fencing, and the currently open semantic round.
+3. Immediate lower-layer continuation does not require a Schedule. `continue_immediately` may close/release the current round and prepare the successor ControllerRound directly. A Schedule is used only when a real time/event/condition trigger is needed.
+4. `wait` keeps the lower semantic lane quiescent. The ControllerRound semantic fingerprint is derived from stable Requirement/Work/Handoff facts, excluding persistence timestamps and record ordering. An unchanged occurrence returns `semantic_wait` before provider dispatch; a meaningful semantic change may admit one successor round.
+5. `ControllerHost` is the provider-neutral delivery port. Provider/browser adapters may navigate, submit, observe, and reconcile external effects, but they never own Work or ControllerRound semantics. Before any non-idempotent provider submit, ControllerRound atomically records the provider effect id and dispatch start/attempt. A confirmed result records the receipt on that same round. An ambiguous submit records `provider_dispatch_outcome_unknown` and forbids blind replay.
+6. A launched Controller claims the exact Work/ControllerRound and reconstructs bounded current Requirement/Plan/Step/Work/Handoff/source/runtime evidence. For relay-bound claims, relay claimability and authoritative ControllerSession ownership are revalidated under the canonical relay→session lock order, then committed through one control-plane SQLite transaction; a direct Work relay acknowledgement commits in that same transaction, while an inherited Requirement-scope relay is fenced but never rewritten for a sibling Work. Chat history and MCP/provider sessions are transport context, not durable semantic truth.
+7. Before a Controller round ends, the Controller records exactly one disposition: `continue_immediately`, `wait`, `wait_for_user` with an active Handoff, or `goal_complete`. `goal_complete` closes the lower Controller lane only; outer Goal completion still requires Workflow Supervisor `DONE` validation against canonical Requirement evidence.
+8. Once a Requirement-backed Work has an exact ChatGPT conversation binding, the Workflow Supervisor owns the next **outer assistant-turn submit** for that Goal. Scheduler, stalled-round maintenance, and `continue_immediately` may prepare or preserve the lower ControllerRound, but they must not send another outer ChatGPT message. Autonomous liveness must prepare the canonical lower ControllerRound before Supervisor enrollment; if the Requirement scope still points at a failed/cancelled, ownerless prior Work, canonical ControllerRound terminal reconciliation retires that stale relay before the current Work round is prepared. No Requirement-membership-only authority inheritance is permitted. The next assistant turn may claim the prepared `dispatching` ControllerRound through normal Controller authority.
+9. Supervisor enrollment is idempotent and Requirement/Goal-scoped, not per-Work. Task identity is repository-namespaced; successor Works in the same Requirement inherit the exact conversation binding. Lower layers derive the Supervisor boundary from canonical Work + conversation facts instead of copying an `owned` status into Scheduler or ControllerRound.
+10. Workflow Supervisor is co-hosted inside the existing Canonical Forge Runtime process. It owns a separate `supervisor.sqlite` and Unix socket under the exact configured Controller Home and is the only opener/writer of that Supervisor database. This preserves an independent authority namespace without adding a second launchd/systemd service or process lifecycle.
 
-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.
+A provider authentication, consent, capability-grant, or permission blocker is `wait_for_user`, not rejection. Resolving the exact Handoff creates new durable evidence that may re-admit continuation; conversation/session replacement during recovery is normal delivery-state turnover and must preserve the same Requirement/Work/ControllerRound lineage. A known non-ambiguous provider failure is retried within the same ControllerRound authority, occurrence and failure budget; it never creates a successor semantic round merely to retry delivery. Scheduler may mechanically reconstruct a missing Work-scoped ControllerBinding from the retained ControllerSession and existing conversation/predecessor projection, but it may not mint browser authorization or clear an outcome-unknown fence.
 
-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.
+Machine-observable continuation health is derived from canonical Requirement/Plan/Step, optional Schedule occurrence, semantic WorkContract, provider-effect/receipt facts, Supervisor task/effect journal, and real repository/process safety evidence. Persistent scheduled Work is ordinary pending intent, not a stuck Work or Runtime blocker. Health reporting distinguishes trigger, provider dispatch start/confirmed/outcome-unknown, outer-turn effect reservation/application, real execution outcome, and genuine waiting state; none may be substituted for another.
+
+Transient Runtime, connector, browser-provider, or Supervisor-adapter unavailability may delay progress, but it does not authorize a lower layer to seize outer-turn ownership. Once the exact conversation boundary exists, failure to enroll or reach Supervisor remains quiescent/retriable infrastructure state rather than a fallback permission for Scheduler or maintenance to double-send.
+
+**Model owns reasoning and engineering policy. Forge owns capabilities, durable facts, execution mechanics and receipts.** Forge carries no route/mode vocabulary that selects Direct Control, durable Work, handoff, a worker/provider, verification, review, or completion on the model's behalf. Invoking `rh_work` is itself the explicit decision to use durable Work; `work_kind` is the explicit declaration of the technical evidence shape. Parallel delivery across independent Plan steps is expressed through explicit Work/Plan lineage plus existing Process/resource claims, which serialize or reject conflicts through the same Lease authority; no Forge-side task-size, complexity, or parallelism heuristic promotes a task into a lifecycle tier. There is no separate runtime tier, agent swarm, second scheduler, or second project lifecycle.
 
 ## State ownership
 
-- Git/worktree owns repository source truth.
+- Git/worktree owns repository source truth. Direct commit scope is the exact staged Git index at the commit boundary; a WorkContract may further constrain that scope through its durable allowed/forbidden path authority. Caller-supplied commit pathspecs are an explicit narrowing input, not a second source of scope 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.
+- Requirement, Plan, and optional Work are the only cross-domain model-authored semantic working-context records. Each has one stable identity and monotonic semantic revision with expected-revision CAS; append-only semantic revision records are history evidence, not second mutable authorities. Plan source/Requirement basis revisions are provenance and advisory staleness only, never execution gates. Legacy PlanContract lifecycle/steps remain migration execution data and cannot rewrite `semanticContext` once it exists.
+- Work owns an independently resumable semantic objective only when durable continuity is useful. Its semantic state is `open|completed|cancelled` and is independent from mechanical running/blocked/verification/review/delivery/cleanup/provider/recovery state. Model-selected Work result refs stay separate from mechanical completion/check receipts. Pre-semantic legacy Work may infer its initial semantic state once; new Work materializes semantic state at creation.
+- When creating a Work with explicit Plan/Requirement identity, Forge resolves their existing current semantic heads and records the adopted `planRevision`/`requirementRevision` in Work's own CAS/history; an explicitly chosen existing historical revision is also valid. A selected Plan may supply its already-authored Requirement identity when Work has no stronger explicit/predecessor binding, but Requirement membership never guesses a Plan or successor. Mismatching Plan/Requirement links and nonexistent revisions fail before Work creation or revision. Later upstream head changes are not silently adopted during manual or autonomous continuation: `rh_work get` projects the current head alongside Work's adopted basis and, for detail reads, both semantic snapshots when available. A model/user explicitly changes either basis through `rh_work revise` and Work `expected_revision` CAS, preserving the old basis in immutable Work revision history; terminal Work cannot switch its basis in place. Version drift is advisory context for model judgment, not a verification, execution or acceptance gate.
+- ResumeContext is assembled on demand from current Requirement/Plan/Work semantic views plus fresh source/resource facts, unresolved human requests, active durable handles, and pertinent receipts; it is not persisted as another aggregate. ControllerRound currently remains a lower-layer continuation/effect fence during migration, but its claim/lease mechanics do not own Requirement/Plan/Work semantic identity or revision authority.
+- Scheduler owns trigger/time/event/condition occurrence authority only; it does not own continuation lifecycle or provider-dispatch truth.
+- Workflow Supervisor owns committed assistant-turn and Goal-level `CONTINUE`/validated `DONE`/validated `NEEDS_USER` plus next outer assistant-turn startup. Its durable browser task identity is conversation-stable so one ChatGPT Project conversation survives explicit predecessor/successor Work turnover and Requirement takeover. Work-derived task ids are bootstrap reservation identities only; after exact conversation binding, the registered conversation task is canonical while the active semantic scope remains the exact Requirement/Work reported and validated for the current turn. Discovery observations may be durable, but only `WorkflowSupervisorControlPlane -> WorkflowSupervisorStore` may persist them; server/native-browser transports only normalize and submit typed observations. The dedicated database/socket remain co-hosted by the Canonical Runtime process under Controller Home.
 - 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.
+- MCP transport owns only bounded request/session delivery, not semantic execution authority. Modern and legacy POSTs participate in the same active-request admission/health accounting. During Canonical Runtime shutdown or release cutover, the listener stops new admission first and already-admitted requests receive one bounded drain window; any still-unsettled request must be surfaced as explicit `outcome_unknown` / `reconcile` before session/socket teardown. A cutover ambiguity never authorizes blind replay: only an operation whose canonical idempotency authority already proves replay-safe may reconnect and replay. Transport completion/health therefore cannot infer Work, ControllerRound, or provider-effect completion, and a newly healthy Runtime does not retroactively prove an interrupted request completed.
+- Workflow Supervisor retry or provider-resume exhaustion remains a derived projection of the existing task/effect journal, not a new task state. Exhaustion is projected through Direct Activity so operators can see that automatic mutation has stopped; clearing the canonical stall closes that same projection. Outcome-unknown effects remain reconcile-only and late receipt observation stays read-only.
+- 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 launcher from the fixed physical `runtime/service/active-forge-runtime` path, while release resources and identity remain manifest-bound. That compiled launcher is deliberately narrow: it validates the manifest-attested Runtime bundle and release-owned Bun interpreter, supervises exactly one interpreter child, forwards lifecycle and diagnostic signals, and mirrors the child terminal outcome; it never loads the long-lived Runtime bundle into its own compiled JSC VM. The stable physical launcher path remains the macOS TCC responsible-process boundary for its Runtime descendants across releases. Heavy TypeScript compiler/LanguageService/AST work is not part of the canonical Runtime residency boundary: semantic navigation and TypeScript/JavaScript declaration indexing execute in the manifest-attested short-lived `forge-typescript-navigation` sidecar, preserve the caller's MCP read policy, and return only bounded plain-data results. The parent Runtime may cache those plain declaration ranges by content identity, but it must not retain TypeScript compiler modules, `LanguageService`, `Program`, `SourceFile`, or other compiler-owned object graphs across requests. The same residency rule applies to allocator-heavy Context Plane retrieval: `rh_context` and compatibility `controller_context` execute Context Pack search, source materialization, and structural/CodeGraph fan-in inside the manifest-attested short-lived `forge-context-pack` sidecar, with the exact serialized MCP read policy and repository/session identity. The canonical Runtime remains the request/closure authority and may combine the returned bounded plain-data projection with semantic/readiness evidence, but it must not execute the Context Pack implementation in-process or preserve its transient JSC allocator lifetime. Compiler-intensive verification gates that measure TypeScript latency or run the TypeScript compiler share the existing repository `heavy-check` serialization fence, so acceptance latency is measured without same-repository compiler/JSC contention; this is scheduling metadata only and does not create a second execution authority.
+- Independent Windows/WSL host rescue is an emergency availability boundary outside both the source checkout and Controller Home. It owns one configuration/lock root and may start or restart only the exact canonical Runtime, loopback-only Secure-Tunnel Connector, its own WSL watchdog unit, and one configured OpenAI Secure Tunnel alias. That connector runs without local MCP auth because OpenAI Secure Tunnel is the external authorization boundary; it must never be reused as a public ingress. The rescue boundary never owns a Runtime release, Controller database, schedule, work execution, secret value, compatibility fallback, or arbitrary shell RPC. Windows is a cold-start client only; the WSL rescue lock serializes every rescue mutation.
 - 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.
+- Cognitive Plane owns advisory learned memory inside the existing Controller SQLite authority. Normal repository/Work admission establishes the semantic Project/Workspace binding when portable identity is available: an authored `.forge/project-engineering.json` `projectId` is preferred, canonical Git remote supplies a stable source fingerprint and only supplies the Project id when no authored id exists, and ProjectPlacement remains ForgeInstance-local. Repository registration alone never creates semantic Project authority. Existing Project identity/workspace is preserved, while contract/remote aliases or repository-placement conflicts block instead of silently rebinding. Learning scope is authored by the model: Project is the default home for project-specific observations; Workspace is valid only when the model explicitly chooses `workspace` plus portable intent for a genuinely cross-project abstraction. Forge does not auto-promote from repetition, category, score or execution outcome and does not auto-materialize Requirement candidates from learned patterns. Cognitive memory cannot mutate Project contracts, lifecycle, authorization, acceptance or verification authority; any durable product/architecture change still enters the normal Requirement/Plan/Work path explicitly.
+- Work lifecycle is a semantic CAS record: `open`, `completed`, or `cancelled`. `work-contract-store.ts` owns locked persistence and one-time legacy normalization; `work_complete` never admits or blocks Git, verification, review, or delivery. Repository execution and recovery own their own real safety conditions. 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. Finalizer-owned validation may use one bounded Process attach window to settle freshly launched short checks inside the same delivery transaction; the budget is bounded and shared across that validation call, never becomes polling/re-execution authority, and a still-running check remains an explicit Process dependency. Finalization never derives cleanup authority from `skipped` stage projections: `cleanup=false` is represented by the durable terminal resource disposition, and a later cleanup request may re-arm retained managed resources only from that canonical provenance. Implementation-review authority is bound to the exact Work candidate rather than a moving target-branch ancestor. If the target advances after review, delivery may preserve review authority only when the integrated revision proves identical Work content, identical changed-path identity, unchanged architecture evidence, and exact transferable verification authority; otherwise delivery returns to a fresh exact review without broadening the original Work scope.
 - 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.
+- `rh_work` remains a thin semantic-context and transport compatibility boundary. Controller identity, claim/disposition/release, and provider orchestration are internal recovery mechanics delegated to `work-controller-operations.ts`; ordinary model-facing operations never require their authority fields. Requirement and Plan APIs persist optional semantic context only: Plan approval, acceptance, dependencies, and steps do not select or authorize Work execution. Frozen-client compatibility decoding stays at the outer `work-adapter.ts` boundary and enters the same canonical Requirement/Plan/Work primitives without restoring lifecycle gates.
+- Direct Work ownership is durable across replaceable MCP request/transport and canonical Runtime bindings. A modern sessionless request may mechanically rebind an exact direct Work only when controller id/type, authenticated principal, exact Work identity, and the positively current canonical Runtime all still match, no ControllerRound relay owns the round, and the caller did not present a conflicting opaque capability. This rebind preserves the existing Work-bound capability digest; a Runtime epoch change advances the claim-generation fence. Relay-bound ControllerRounds, cross-principal/controller recovery, stale Runtime instances, and explicitly wrong capabilities remain hard-fenced and require their existing exact authority/recovery contracts.
+- Production Browser session identity is owned only by Controller-home SQLite `ComputerSurfaceTarget` authority. Legacy Browser session JSON is import-only migration input and is never a steady-state fallback when Controller execution context is absent; handoff sidecars return interaction results and never write Browser session state directly.
+
+## Kernel V2 module and migration contract
+
+Kernel V2 converges Forge toward a domain-first modular monolith. Directory placement is not cosmetic: it encodes dependency direction and semantic ownership.
+
+```text
+apps / composition roots
+        |
+        v
+adapters / providers --------> protocols
+        |                         ^
+        v                         |
+packages/kernel/* ----------> public ports/contracts
+packages/plugin-runtime/* --> neutral plugin/provider contracts
+```
+
+- `packages/kernel/<domain>` owns durable domain semantics such as Work, Controller, Scheduler, Resources, Identity, and Execution. Each domain exposes one intentional public API; sibling modules do not deep-import its infrastructure or persistence internals.
+- Kernel Identity defines portable `ScopeRef` separately from node-local `ExecutionPlacement`. Requirement/Plan/Work identity may survive repository registration, checkout, host, or ForgeInstance changes; `repoId`/`checkoutId` are migration-era placement fields and must not define semantic Work identity. New Work records persist both forms, while legacy Work records are deterministically projected without deriving semantic scope from a local repository id. Repository mutation binds a concrete checkout through WorkHandle/resource fences at execution time; when a Thin semantic Work has no legacy checkout placement, Forge uses the actual repository target for that mutation and does not write the mechanical checkout back into semantic Work state.
+- `ExecutionPlacement.forgeInstanceId` is the canonical node target for Work execution. Repository admission and managed-worktree materialization preserve it alongside repository/checkout placement. ChatGPT continuation may select Browser vs WSL bridge only after the target Forge instance matches the currently installed Forge identity; a mismatch is a typed placement blocker and never falls back to the dispatcher host. Cross-instance selection belongs to the ChatGPT Connector boundary, not a second scheduler or provider-session identity.
+- ChatGPT MCP connector discovery names are instance-derived (`forge-<stable-instance-token>`) by default. The old shared `forge` name is migration-only; endpoint/tunnel/session rotation must not change the semantic `forgeInstanceId`, while rerunning setup migrates legacy shared connector names without changing the instance identity.
+- Syncable semantic records use bounded revision/provenance metadata with optimistic-concurrency preconditions. The current Controller SQLite revision/audit mechanism is the local persistence implementation; SQLite files, leases, sessions, and runtime ownership are not portable semantic state.
+- `packages/protocols` owns wire/provider-neutral contracts that must be usable without importing Runtime, MCP, CLI, UI, or concrete provider implementations.
+- `packages/plugin-runtime` owns provider-neutral plugin dispatch, resource, receipt, and provider-selection semantics. It may depend on neutral protocols/ports, never on concrete adapters or Runtime implementation modules.
+- `adapters/*` implement outward-facing mechanisms and may depend inward on Kernel/plugin/protocol contracts. Concrete provider identity, filesystem discovery, OAuth/tunnel details, Browser/ChatGPT host mechanics, and SQLite implementations belong here when they are mechanism rather than domain authority.
+- `apps/*` and Runtime composition roots wire concrete implementations. Composition may know both sides of a port; business semantics must not leak upward into the composition root.
+- Legacy `src/cli/*` and `src/runtime/*` code is migrated by owner, not mechanically by path. A legacy file that still owns current semantics must be moved/split into its target module; a retained legacy path may only be a thin compatibility facade delegating to the new owner.
+
+### Single-authority rule
+
+For each durable fact or lifecycle transition there is exactly one mutable authority. A projection, cache, transport session, compatibility record, provider live handle, UI model, or diagnostic snapshot may derive from that authority but must not independently decide or persist competing state. When two implementations appear to own the same semantic transition, Kernel V2 resolves the duplication by choosing one owner and deleting/merging the other rather than synchronizing two authorities.
+
+### Migration-debt lifecycle
+
+Compatibility exists to move consumers to the new owner, not to preserve old architecture indefinitely. Every retained compatibility shim, legacy import allowlist, translation layer, or migration-only assertion must identify: the replacement owner, the bounded legacy consumers, and a machine-observable removal condition. New production consumers of a deprecated owner are forbidden. Once the final consumer is gone or the removal condition is met, the compatibility code and its gate/allowlist entry are removed in the same coherent slice.
+
+A fallback must never become a second semantic authority. Capability negotiation may select an explicitly supported provider/version, and safety boundaries may refuse unsafe or ambiguous execution, but missing architecture capability is repaired at the owning general layer rather than hidden behind silent fallback, duplicate persistence, or an alternate lifecycle path.
+
+### Architecture enforcement hierarchy
+
+Architecture checks should prove the invariant at the highest semantic level available:
+
+1. compiler/type contracts and package/public-API visibility;
+2. AST/import/dependency-graph direction and cycle checks;
+3. focused semantic contract tests for behavior that static structure cannot express;
+4. path existence/removal checks for finite migrations;
+5. raw source-text/regex assertions only as temporary migration fences when no stronger representation exists.
+
+Source-line-count limits are review heuristics, not architecture truth, and must not be permanent merge gates. Text assertions that merely require a spelling or forbid a provider name should be replaced by typed contracts or structural dependency checks as the migrated owner stabilizes. Architecture debt checks are shrinking ledgers: a retired dependency causes its allowlist/assertion to be deleted, never preserved for historical symmetry.
+
+### Kernel V2 delivery cadence
+
+Within one migration slice, gather facts in batches, decide ownership once, implement a coherent patch, then review the whole slice for authority/dependency drift before running focused checks. Repeated full-suite validation after each small move is discouraged because it slows structural work without increasing semantic confidence. Milestone/candidate boundaries receive broader cross-module review, multi-review where useful, and whole-candidate validation. Runtime baseline activation is deliberately later than source integration: a locally passing partial slice does not become the active baseline until the integrated candidate satisfies the Kernel V2 architecture contract.
+
+Validation scheduling is derived from each check's concrete resource effects, not from a blanket assumption that every analysis gate writes the workspace or shared build cache. Proven source-read-only/no-emit checks declare reads (plus only the Git/temp/host resources they actually use) so resource-compatible gates may share one validation wave; missing or unknown effect metadata remains conservative. This projection never weakens the underlying lease conflict rules or creates a second scheduling authority.
 
 ## Runtime and MCP boundary
 
 - Canonical Runtime is activated as one immutable whole release with a previous release retained for rollback.
+- A compiled `standalone-binary` release has a closed manifest-owned execution surface: the long-lived Runtime bundle, its exact release-owned Bun interpreter, Process Runner, Check Runner, Scheduler Worker, and periodic cleanup are immutable artifacts with identities and release canaries. The signed compiled `forge-runtime` entrypoint is a supervision/identity boundary, not the long-lived JS VM. Runtime execution never resolves Bun from Homebrew, `~/.bun`, PATH, an ambient checkout, or Bun virtual `import.meta.url`; scheduler/cleanup source entrypoints remain development/source-backed mechanisms only.
+- Canonical Scheduler idle execution is event/deadline driven, not a generic control-plane poll loop. Execution-job/lease/policy mutations and terminal Check Process persistence advance the existing `wake-signal.json` notification revision and wake immediately; lifecycle truth remains in the existing Job, Process, and Work stores, and sibling scheduler health-state writes are not wake events. With no active execution, the loop does not run a full control-plane tick merely to satisfy the five-second reconciliation cadence; it waits for an authoritative mutation notification or the 30-second schedule-admission deadline, while coarse wake polling exists only as lost-filesystem-event protection. Five-second reconciliation still runs whenever active/event-driven ticks occur. Heartbeat persistence remains health/readiness evidence and must not become scheduler work-admission authority.
 - 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`.
+- MCP tool schemas may remain frozen for the lifetime of an already-open host conversation even when Runtime reconnects onto a newer release. A versioned frozen-session wire decoder may therefore translate only explicitly bounded historical carriers into the current semantic/controller API; it owns no lifecycle or persistence, may not restore retired verify/review/finalize/ControllerRound operations, and must preserve current CAS/authority checks. The pre-Thin `semantic.v1` and current-conversation enrollment carriers are such a migration decoder. Retire that decoder only after the minimum supported MCP client contract no longer advertises those carriers and release reconnect canaries prove no supported frozen-session consumer remains.
+- Work-attributed verification is an application service, not an MCP/Local Bridge implementation detail: all Work verification resolves the Work checkout/check registry, first reuses an exact-current authoritative pass/fail receipt or reconciles an already-terminal Work-bound Process with the same verification fingerprint, and only then runs a new Process when no current authority exists. Terminal receipt identity and Work evidence remain centralized in `work-verification-service.ts`; repeated verify calls for an unchanged candidate do not re-execute the check.
+- First-party external providers have one desired-contract reconciliation boundary: Controller plugin registry/manifest sync reconstructs the current Forge-owned permissions/capabilities/actions from source while preserving installed provider identity, transport target, lifecycle identity, provider/protocol version and enabled state. The canonical external-registration store remains the only fingerprint/revision persistence authority; manifest reads/execution never create a second registration authority or silently mutate durable state.
+- Product bootstrap has one instance-level desired/observed lifecycle authority behind the Bootstrap Control API. CLI setup, Local Bridge readiness, packaged Runtime install/upgrade/repair projection, and doctor observation consume that same authority rather than persisting parallel setup state. Browser/tunnel/provider implementations remain adapters beneath this API.
+- WSL ChatGPT browser bootstrap may create only a dedicated Forge-controlled Chromium profile when the runtime explicitly supports unpacked-extension startup. Ordinary user Chrome profiles are observational/existing-capability surfaces only; unsupported automatic extension loading must fail closed with a resumable user action.
+- Workspace and Project are portable semantic identities, not aliases for Repository or checkout placement. Cross-node sync may transfer only bounded revisioned semantic projections for Workspace/Project/Requirement/Plan/Work; destination nodes persist imported facts as semantic replicas and never acquire source-node SQLite state, leases, controller/browser sessions, check receipts, raw logs, secrets, or execution placement. Import uses optimistic revision checks and fails atomically on local semantic-authority conflict.
+- The structured Context Plane is advisory runtime state, not Kernel authority. Typed preference/policy/procedure/capability-intent/credential-reference records are scoped, provenance-bearing and budgeted; resolver output may influence deterministic provider preference only where the current request did not specify one. AGENTS.md remains the stable repository constitution, dynamic context is rendered on demand, raw credential material is forbidden, and loss/corruption of Context records must degrade to default routing without mutating Requirement/Plan/Work/approval authority.
+- Host/platform discovery is an adapter concern, never product identity. User/profile roots, executable locations, browser products, drive mounts, service-manager availability, and Recovery deployment locations are discovered or explicitly bound; static known paths are bounded fallbacks only and may not encode a developer username, one WSL mount root, or one browser installation as semantic authority.
+- Runtime and Connector persistence consume a typed platform `ServiceManagerHost`. `launchd`, `systemd-user`, and portable-session mechanics live behind that host boundary; Runtime composition does not import OS service implementations to decide product semantics.
+- A materialized package Runtime is Controller-Home/release scoped and does not require a fake repository root. Repository overlay remains optional and is required only for development/repository-scoped surfaces that actually need repository semantics. Controller-scoped Browser/plugin execution likewise uses controller scope directly rather than manufacturing a repository record.
+- The documented Node package runtime is a first-class product path. Normal package/bootstrap/Browser execution may not depend on unguarded Bun-only runtime APIs; executable prerequisites resolve through typed discovery with explicit missing/unsupported recovery. Plugin catalog trust is policy data: first-party allowlists are packaged/configurable policy and non-first-party providers require explicit Controller-Home trust rather than source edits.
 
 ### Controller facade and handoff boundary
 
@@ -118,10 +295,32 @@ Explicit **Scale** is the opt-in coordination form of this existing model, not a
 
 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.
 
+## Engineering Workloop boundary
+
+Engineering evidence is optional model/project context layered over semantic Requirement/Plan/Work records; it is not a lifecycle or admission plane. Forge owns durable facts, execution capabilities, resource fencing, source identity, verification facts, receipts, and recovery mechanics. The model owns requirement interpretation, product/architecture decisions, root-cause judgment, verification/review strategy, semantic acceptance, and whether another action is required.
+
+`EngineeringWorkProfile` is Kernel-owned generic method/risk policy and must not contain project-domain facts. `.forge/project-engineering.json` is the default source-controlled `ProjectEngineeringContract`: it may name project authority files, UX/performance/non-regression constraints, named checks and journeys, platform/tooling requirements, Skill references, explicit Skill-to-kind bindings, and project exceptions. The Controller MCP policy treats this exact source-controlled contract path as writable while keeping sibling `.forge/**` controller/config/secret paths denied. Controller state stores only a source-bound receipt containing the repository-relative path, project/contract identity, contract version, exact source revision, SHA-256 content digest and repository provenance time; it never persists a mutable copy that could become a second project authority. Skills own reusable professional methods such as iOS/Swift engineering, debugging and review technique. Semantic tools such as SourceKit-LSP, other language servers, compilers and CodeGraph provide factual source/build/navigation evidence but never own product intent. AGENTS/CLAUDE guidance remains thin repository/directory routing and local-guidance evidence; its wording is not proof that a Skill or semantic tool actually participated.
+
+Context Closure is a derived `rh_context` evidence layer, not another context database or lifecycle. It binds the exact source revision to current source/test paths, dirty/Work context, applicable repository guidance, ProjectEngineeringContract provenance, detected language/platform, project-declared Skill references/bindings, semantic-provider evidence and bounded recent related changes. Explicit Skill bindings own kind coverage when present; legacy `skillRefs` retain name-based compatibility matching. Skill/tool absence is explicit degraded evidence. Cross-file ownership/protocol/architecture claims require matching semantic navigation evidence or an explicit compiler/build fallback; a registered provider alone is not proof.
+
+`engineering-work-profile-v1` maps Work risk into `low | normal | high | critical` solely to organize optional evidence and project guidance. Product DoD, Context Closure, design decisions, critique, semantic-tool output, validation, review, and journey evidence never admit or deny a repository mutation, delivery, or semantic Work completion. The model and project policy decide when they are useful. Capability admission remains limited to security/access, destructive authorization, secrets, dirty ownership, resource fencing, source CAS, concurrency, Git consistency, and external-effect idempotency.
+
+Every created Work may persist an `EngineeringContextReceipt` containing profile version, source identity, structured receipt ids, conditional semantic-tool/journey flags and bounded missing-evidence lists. The Controller-facing `rh_work start` surface may expose this context but does not accept caller-supplied receipt ids as safety authority. Provenance validation protects the integrity of recorded evidence; it does not turn absence, staleness, or a project-methodology disagreement into a Forge mutation gate. Stage7B/C may automate context, skill, tool, Product DoD, design, or critique evidence production only as optional assistance.
+
 ## 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.
 
+### Computer and macOS provider boundary
+
+`Computer` is the user-facing interaction product boundary. Browser and Desktop remain distinct semantic subdomains inside that product: Browser owns DOM/tab/navigation/session/transaction semantics, while Desktop owns generic application observation, input, capture, and native-platform interaction. Browser may consume provider-native support through `computer.browser_automation.v1`, but neither the internal `browser` adapter identity nor concrete provider identity such as `desktop_operator` is a second user product or routing/session authority. Internal adapters remain exactly addressable only for trusted composition and migration.
+
+On macOS, Forge Desktop Operator is the independently released native Computer provider. Its Git repository, app bundle identity, user LaunchAgent, socket endpoint, live native handles, and TCC permissions remain provider-owned and release-independent. Its trusted registration is explicitly provider-only: normal plugin discovery exposes `computer`, while diagnostics and lifecycle composition may still address `desktop_operator` exactly. Forge owns trusted catalog selection, registration, capability/action policy, authorization, provider selection, and the `forge computer setup|status|doctor|update|uninstall` product facade. The stable Desktop Operator bundle/LaunchAgent identity must not be renamed merely to match product wording because TCC identity and provider lifecycle are intentionally independent from Forge Runtime releases. Durable application interaction-target authority is Forge-owned in Controller SQLite. Public Computer actions use a stable `target_id`; provider session/handle identities are live bindings only. Rebind, target use, and retirement serialize on the same target-scoped authority lease, and a provider restart may rebuild a binding only after the stable application identity is re-verified. Rebinding occurs before semantic dispatch; once a non-idempotent provider mutation is dispatched, an unknown transport outcome is never automatically replayed. A host application or browser discovery result is not a Computer capability proof: a capability is supported only when the current platform has a compatible provider, and it is ready only when that provider is registered, enabled, declares the capability, and has recorded healthy evidence. On an unsupported platform, status and setup fail before probing a foreign provider; Runtime must not create a legacy provider binding or retry a foreign transport.
+
+`computer.console.unlock.v1` is a protected Computer capability, not a widening of `computer.input.v1`. Forge owns its provider-neutral contract, provider selection/negotiation, and explicit single-use authorization boundary; Desktop Operator owns macOS lock-state observation, exact `loginwindow` binding, bounded physical input, attempt limiting, and authoritative locked-to-unlocked postcondition verification. Raw macOS credentials never enter ChatGPT, MCP arguments, or Forge Runtime. The frozen 19-tool ChatGPT deployment ABI does not grow dedicated console-unlock tools: refreshed clients invoke typed `computer/console_unlock_prepare` and `computer/console_unlock` actions through the existing stable `plugin_action_execute` dispatcher. Those actions use the explicitly restricted `direct_non_persistent` lane: manifest/schema validation and per-invocation authorization still apply, but Work attribution is forbidden and the invocation bypasses plugin request indexes, receipts, Process/ExecutionJob state, evidence, and replay. While the console is unlocked, prepare asks Desktop Operator to collect the credential in a provider-local secure field and returns only a short-lived opaque single-use handle; unlock later consumes that handle while the console is locked. The old atomic `computer_console_unlock_prepare` / `computer_console_unlock` handlers remain registered only on the explicit full compatibility surface and enter the same canonical protected execution functions without becoming part of the stable connector schema. Results are allowlisted projections and cannot echo credential material. Ordinary `desktop_key`, `desktop_type_text`, batch, pointer, screenshot, application activation, shell, and compatibility paths cannot target the lock screen through this capability.
+
+Trusted `ExternalPluginRegistration` is the endpoint/lifecycle authority for an installed Computer provider. A release-independent Desktop Operator install receipt may refresh only installed release metadata when it proves the same already-trusted socket, verified LaunchAgent, exact trusted executable binding, bundle identity, and provider manifest; the receipt's own program-name hint is only self-consistency evidence, never lifecycle authority. The receipt is evidence, never a second endpoint/lifecycle authority, and contradictory matching evidence fails explicitly. Its local JSONL transport uses a platform-local endpoint (a Unix-domain socket on Unix or a Windows named pipe on Windows), not a browser-discovery proxy or a second readiness authority. A Computer provider must resolve only from a trusted `ExternalPluginRegistration`; Runtime no longer binds an unregistered Desktop Operator socket as a compatibility provider. Provider protocol negotiation prefers provider-neutral `computer_execute`; legacy `macos_browser_automation` is compatibility-only and cannot become Browser authority. Forge uninstall must complete the provider-owned native uninstall lifecycle before forgetting a registered provider, so package/registration cleanup cannot orphan a running native service.
+
 ### 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.
@@ -176,3 +375,9 @@ Research notes, tasks, reviews, archived architecture pages, plans and Git histo
 - 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.
+
+ChatGPT Supervisor browser submission requires a positive read-back of the exact ProseMirror composer payload after Browser `fill` and before Send/Enter. A transport-level successful `fill`/keyboard receipt alone is not completion; a missing/mismatched composer observation fails closed without submitting the existing effect. Payload retention alone is insufficient: the provider must select the installed, connected **forge** app (not the distinct Plugin Creator development package) from ChatGPT's @-mention UI and confirm the non-editable ProseMirror `app-mention-name="forge"` and exact `app://asdk_app_6ac09022b26081918f20ff868c773824` path before Send/Enter. The payload plus a trailing standalone `@` paragraph must be inserted in a single ProseMirror transaction before typing `forge`; adding ` @forge` after the fact loses the separator and fails to open autocomplete. The legacy `@forge` text prefix is removed from the provider payload; only the exact structured app chip activates Forge. A literal `@forge`, unavailable picker, missing app or similar-named Forge Recovery app is never accepted as binding; fail without sending or replaying the Supervisor effect. Outcome-unknown Send reconciliation likewise retains the exact bound chip as part of its precondition. Both before preparing a prompt and after plugin selection, the Browser delivery owner read-attests the live native-tab URL and session identity against the target conversation/project, so a stale saved session cannot silently direct a Supervisor effect to another conversation. Selection logic is implemented in the existing Browser delivery owner; availability in the target account/conversation and a real live completion receipt remain independent acceptance requirements.
+
+Workflow Supervisor's Computer delivery now has one two-phase boundary: `ComputerChatgptConversationTarget.prepare` may prepare the local composer, select reasoning and bind the exact Forge App chip, but must **never** click Send. Only a verified `ready` allows Supervisor's existing effect authority to append `effect_dispatch_started`; `dispatch` then rechecks the prepared editor and performs the one permitted Send. Failed preparation records `effect_preflight_rejected` in the **same Supervisor effect event log**, with zero provider generations consumed. The ledger permits at most one preparation attempt for the same effect and active Runtime release, and at most three distinct failed release identities in total. An unchanged broken Runtime cannot retry indefinitely after a process restart; a later verified Runtime revision can get a bounded opportunity without minting another effect. Uncertain post-Send outcomes remain in the established read-only reconciliation path and may never be re-sent merely because local preparation later succeeds. Browser transport preparation failures and provider send attempts are not interchangeable budget units.
+
+Supervisor fresh-conversation bootstrap uses one provider-owned Chrome tab per distinct Supervisor task. A ChatGPT Project URL is a scope only and **never** proves a tab belongs to a given bootstrap identity: the Chrome Extension may reuse only the task-keyed ephemeral tab mapping or the exact provider/tab/window binding already persisted by Controller's Computer target authority. On a service-worker restart the Controller binding is passed as an attachment hint and verified against the project before reuse. An absent or mismatched pinned tab fails closed without creating a second possibly duplicate conversation. New unbound bootstrap identities create dedicated background tabs; iOS and Android tasks sharing one Project must never claim each other's surface binding index. The enrollment prompt is a complete structured Supervisor effect with exact goal, immutable effect marker and end marker; Computer must read back the complete text and bound Forge app chip before the first Send.

package/docs/architecture/EVOLUTION.md

@@ -40,3 +40,16 @@ Earlier V4–V8 Controller, Local Bridge, Supervisor, Issue/Task/Job and recover
 - 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.
+
+## 2026-08-31 — Independent Windows/WSL host rescue
+
+- Added an emergency host-rescue boundary outside the Forge checkout and Controller Home so a broken Runtime, Connector, or existing Recovery deployment can still be reached from Windows through WSL.
+- Restricted the host-facing surface to a fixed set of status/start/restart/verification actions, with one WSL-side lock for every mutation; no arbitrary shell RPC, source mutation, release selection, or Controller-database ownership was added.
+- Kept the Windows scheduled task as a cold-start trigger and the WSL rescue service as the sole long-lived reconciliation owner. Tunnel credentials remain in tunnel-client's separately permissioned store rather than rescue configuration.
+
+## 2026-09-02 — Kernel V2 governance moves from textual fences to structural authority
+
+- Defined Kernel V2 as a domain/authority migration toward a modular monolith with explicit Kernel, protocol, plugin-runtime, adapter, and composition-root dependency direction.
+- Made compatibility a shrinking migration debt with a replacement owner, bounded consumers, and an objective removal condition rather than a permanent parallel layer.
+- Established an architecture-enforcement hierarchy that prefers compiler/type/package and AST/dependency-graph proofs over raw string/regex assertions or source-line-count gates.
+- Changed the migration cadence to batch facts, implement coherent slices, review architecture centrally, run focused checks at slice boundaries, and reserve broad multi-review/validation plus Runtime baseline activation for integrated candidate boundaries.

package/docs/architecture/decisions/20260801-controller-home-sqlite-state.md

@@ -18,7 +18,8 @@ an ORM or a premature table per product concept:
 - `control_plane_records` has a namespace, scope, record key, schema version,
   monotonic revision, JSON payload, and timestamps;
 - its primary key gives one atomic identity per durable fact;
-- `control_plane_audit` records each authoritative write or legacy import;
+- `control_plane_audit` records each authoritative row mutation or legacy import; aggregate compatibility writers must not advance revision or audit history for unchanged sibling rows;
+- hot-path candidate reads may prefilter authoritative JSON rows in SQLite to avoid materializing known-irrelevant records, but the domain layer must still validate every returned candidate and the filter never becomes lifecycle authority;
 - SQLite WAL, foreign-key enforcement, a busy timeout, and `BEGIN IMMEDIATE`
   make cross-process writes serializable; and
 - `control_plane_schema` records schema migrations independently from payload