@moretea-labs/forge 1.7.1 → 1.8.0

package/docs/architecture/CURRENT.md

@@ -18,6 +18,10 @@ Semantic Controller
 
 Quality is prioritized over interactive performance; performance is prioritized over durability machinery that does not materially improve ordinary coding.
 
+## Runtime performance acceptance
+
+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 evidence (60 seconds warmup, 5 minutes observation, mean <=5%, 10-second-window p95 <=10%, one core = 100%). The long read-only observation does not hold the exclusive Recovery mutation lock: every sample is fenced to exact Runtime/release identity, while final verification and 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).
+
 ## 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.
@@ -36,11 +40,39 @@ Quality is prioritized over interactive performance; performance is prioritized
 - Complete small files and complete matched symbols are preferred over arbitrary line windows.
 - CodeGraph is discovery/relationship evidence, not semantic-completeness authority. Stale structural evidence must be labeled and current changed files remain raw-source authoritative.
 - TypeScript Language Service navigation provides compiler-backed definition/reference/implementation lookup for TypeScript symbols through `rh_context`. Swift uses the same bounded `semantic_navigation` route with SourceKit-LSP, but only on explicit symbol requests and only when SwiftPM, BSP (`buildServer.json`), or compilation-database build settings are already available; Forge never performs an implicit build/index just to answer context. Xcode projects use `xcode-build-server` as the build-settings bridge. Because a present BSP can still return generic inferred flags instead of target settings, explicit Swift navigation verifies xcode-build-server compiler-option quality before starting SourceKit; obviously fallback options are rejected as incomplete. Manual `.compile` data produced from real `xcodebuild` output is validated locally, while automatic xcode-build-server mode uses a short cached BSP probe. SourceKit sessions are started lazily, serialized per repo/workspace, kept for a short two-minute idle TTL, and resynchronize changed open files; the first explicit Xcode semantic request has a bounded cold-start budget while warm requests retain the tighter interactive budget. Ordinary `rh_context` calls do not start either the BSP probe or SourceKit. Missing/stale/fallback build settings degrade explicitly to lexical/CodeGraph evidence rather than returning a false complete closure.
-- The default 19-tool MCP schemas are a deployment ABI because approved ChatGPT apps may retain a frozen action/input snapshot. Core quality capabilities therefore need a path through already-stable facade fields. `rh_context` supports precise `@tsnav` and `@swiftnav` directives in `query` as compatibility paths; refreshed clients may use the existing structured `semantic_navigation` field.
+- 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.
 
 ## 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.
+
+### 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.
+
+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.
@@ -60,23 +92,41 @@ The low-level repository command facade classifies these operations as `durable`
 
 ## 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.
+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. Placement is a separate concern from Work creation: when continuity requirements already select a mutating durable Goal Work and a fresh trusted repository observation says the canonical checkout is dirty, admission must persist isolated-worktree placement before mutation so unrelated changes cannot enter that Work's ownership or later verification. Physical checkout isolation is also the Work execution boundary: a shared canonical-checkout Work and a disjoint isolated-checkout Work do not conflict merely because they share a repository id; same semantic scope and explicit overlapping resource claims remain stronger blockers, while the no-target shared mutation fallback serializes only shared-checkout writers. A bounded Direct Control mutation may still intentionally reuse a dirty current checkout; dirty state alone never promotes Direct work into Durable Work.
 
-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.
+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.
+
+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.
+
+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 always 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. Observe-only low/normal Work with no prior Design receipt records the blocker without fabricating an impossible supersession authority or `revisit_required` state; it remains governed by its existing risk profile. 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.
 
 ### Persistent autonomous continuation
 
-A scheduled unattended workflow is one durable **Work + ChatGPT conversation lineage**, not one browser tab and not one schedule occurrence. The existing authorities compose into one lifecycle:
+A scheduled unattended workflow follows one durable **Requirement/Plan/Step/Work/ControllerRound semantic lineage**. Provider conversations, browser tabs, ControllerSession transport ids, and schedule occurrences are replaceable delivery or wake state; none of them is the durable goal identity. The authorities compose into one lifecycle:
 
-1. A Schedule occurrence mechanically selects its already-bound active Work and requests `external_controller_wake`; it never invents semantic work.
-2. The ChatGPT launcher resolves the Work's durable conversation binding, opens or reattaches only the execution tab/session needed for this round, submits the continuation prompt, and records dispatch evidence. Dispatch is transport evidence only; it is not a Controller claim or semantic completion.
-3. The launched ChatGPT Controller claims the exact Work and independently reconstructs current Plan/Work/Schedule/Handoff/source/runtime evidence before deciding what to do. Chat history is useful transport context but is never the durable source of truth.
-4. ChatGPT performs semantic reasoning while Forge performs deterministic context, edit, process, provider, verification, and finalize operations. Forge may automatically execute checks or lifecycle mechanics that ChatGPT explicitly requests, but it never infers that acceptance is satisfied.
-5. Before a Controller round ends, ChatGPT records exactly one semantic disposition: `continue_immediately`, `wait`, `wait_for_user` with an active Handoff, or `goal_complete`. The exact Controller claim/release lineage fences this transition.
-6. Round-owned automation resources are cleaned only after the round reaches its settlement boundary. User-owned browser tabs are preserved; a Forge-owned ephemeral ChatGPT tab may be closed while the Work's conversation id/url binding remains durable for the next wake.
-7. `wait` keeps a persistent Work active and schedulable. A later Schedule wake must recover the same Work and same conversation lineage without requiring the user to restate the remaining task. `goal_complete` is the semantic terminal path and terminal Work automatically stops its continuation schedule.
+1. A Schedule occurrence mechanically selects an already-bound active Work and requests `external_controller_wake`; it never invents semantic work. The occurrence fences replay of that wake, not the goal itself.
+2. Scheduler resolves the Work-scoped durable `ControllerBinding` (interaction target) and the currently retained Controller delivery session. A changed MCP/provider session updates delivery binding without changing Work, binding, Requirement, Plan, or ControllerRound identity.
+3. The provider host may reuse a healthy conversation/browser session, or create/reattach a successor delivery session when the prior one is unavailable. Conversation and browser identities are adapter state only. Dispatch evidence proves a provider effect, not a Controller claim or semantic completion.
+4. The launched Controller claims the exact Work and independently reconstructs bounded current Requirement/Plan/Step/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.
+5. The Controller performs semantic reasoning while Forge performs deterministic context, edit, process, provider, verification, and finalize operations. Forge may automatically execute explicitly requested checks or lifecycle mechanics, but it never infers that acceptance is satisfied.
+6. Before a Controller round ends, the Controller records exactly one semantic disposition: `continue_immediately`, `wait`, `wait_for_user` with an active Handoff, or `goal_complete`. ControllerRound authority and claim generation fence this transition independently of transport replacement.
+7. Round-owned delivery resources are cleaned only after the round reaches its settlement boundary. User-owned browser tabs are preserved; Forge-owned ephemeral tabs or provider sessions may be replaced without losing durable continuation authority.
+8. `wait` keeps the semantic goal resumable but quiescent. Scheduler computes the current ControllerRound semantic fingerprint from stable Requirement revision/state, Work lifecycle/evidence facts, and active Handoff semantics; persistence timestamps and record ordering are excluded. Interval/manual wakes with an unchanged fingerprint are recorded as `semantic_wait` and stop before provider dispatch. One meaningful semantic change may admit one successor round for the exact active Work. When the previous Work is terminal, only semantic Controller admission may create a successor Work; Scheduler never invents one. The successor records `predecessorWorkId` and preserves Requirement/Plan lineage. One already-approved dependency-satisfied next Plan step may be mechanically resolved, but multiple executable successors require an explicit Controller choice. `goal_complete` terminates the semantic goal and its continuation lane without creating another Work.
 
-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.
+`ControllerHost` is the provider-neutral delivery port. ChatGPT Browser and Windows/WSL bridge implementations live in `adapters/chatgpt` behind one delivery contract; they own provider navigation/mutation/confirmation but never Work or ControllerRound semantics. Provider-specific prompt rendering may treat instructions explicitly scoped to a different Controller host/runtime as non-gating for the current host, but it must preserve the underlying repository engineering, acceptance, safety, permission, and authority constraints. The owning `ControllerRound` is the sole durable provider-dispatch receipt authority. Schedule occurrences may project the same dispatch receipt id for replay/debug evidence, while Browser/tab settlement records are resource-cleanup evidence only and cannot overrule the ControllerRound dispatch outcome.
+
+A provider authentication, consent, or permission blocker is `wait_for_user`, not rejection. The ChatGPT adapter creates one bounded Handoff for the exact Work/round; resolving that Handoff wakes a fresh repository-event occurrence. The prior occurrence remains non-replayable. Conversation/session replacement during that recovery is normal delivery-state turnover and must preserve the same semantic Work/relay lineage.
+
+Machine-observable continuation health is derived from existing durable records rather than a new authority database: Requirement/Plan/Step, Schedule occurrence, WorkContract, Work-scoped ControllerBinding, ControllerSession, ControllerRound relay/disposition, provider dispatch receipt, verification/finalization receipts, and delivery cleanup evidence. Health reporting must distinguish `wake requested`, `provider dispatch attempted/confirmed/outcome_unknown`, `Controller claimed`, `semantic disposition recorded`, `lease released`, `verification/finalize outcome`, `delivery cleanup`, and `waiting/next eligible`; none of those states may be substituted for another.
+
+If a non-idempotent provider submit may have committed but cannot be confirmed, the owning ControllerRound persists `provider_dispatch_outcome_unknown` and exits all automatic replay/re-arm paths. Known pre-submit/provider failures remain ordinary failures and may follow bounded retry policy; an ambiguous submit requires explicit reconciliation evidence before any replacement dispatch is admitted.
 
 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.
 
@@ -84,13 +134,14 @@ Explicit **Scale** is the opt-in coordination form of this existing model, not a
 
 ## 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.
 - 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.
+- 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.
@@ -98,15 +149,77 @@ Explicit **Scale** is the opt-in coordination form of this existing model, not a
 - 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.
 
+## 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.
+- `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.
+
 ## 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: Process Runner, Check Runner, Scheduler Worker, and periodic cleanup are immutable executable components with artifact identities and release canaries. Scheduler/cleanup source entrypoints remain a development/source-backed execution mechanism only; compiled Runtime must never fall back to checkout paths or Bun virtual `import.meta.url` paths.
 - 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`.
+- 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 +231,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
+
+The V2 Engineering Workloop is a policy/evidence layer on the existing Requirement → Plan → Work → Controller/Process lifecycle, not a second lifecycle. Forge owns lifecycle, durable Work state, routing/policy gates, source/evidence identity, resource fencing, verification facts and recovery mechanics. ChatGPT Controller owns requirement interpretation, product/architecture decisions, root-cause judgement, semantic acceptance and whether another round 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 and explicit project exceptions. 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 refs, semantic-provider evidence and bounded recent related changes. 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`. `readonly/low` keeps the shortest valid path. `medium` maps to normal: required evidence gaps are recorded but Stage7A does not yet block legacy-compatible normal admission. `high` enforces exact source identity plus source-bound Project Contract, Context Closure, Product DoD, Design Decision and independent critique before mutation. `destructive` maps to critical and additionally requires semantic-tool evidence before mutation. Focused validation, fresh review and applicable real journeys are completion requirements rather than pre-mutation design substitutes.
+
+Every created Work may persist an `EngineeringContextReceipt` containing profile version, source identity, structured receipt ids, conditional semantic-tool/journey flags and bounded missing-admission/missing-completion lists. The Controller-facing `rh_work start` surface exposes the resolved profile and missing evidence but does not accept caller-supplied receipt ids as authority. `verifiedEngineeringEvidence` is an internal trusted input only, populated by Forge evidence authorities after source/provenance verification; raw MCP fields, prose, chat memory, test names, or syntactically valid invented ids cannot satisfy admission. A Project Contract receipt from another source revision fails closed. Stage7B/C automate Context/Skill/tool resolution and Product DoD/Design/critique receipt production so stricter governance does not turn low-risk edits into manual choreography.
+
 ## 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 bounded explicit compatibility fallback may support an old unregistered provider during migration, but it is never the primary endpoint authority and must not survive as a second discovery path after its compatibility window. 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.

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

package/docs/architecture/decisions/20260831-independent-windows-wsl-host-rescue.md

@@ -0,0 +1,59 @@
+# Independent Windows/WSL host rescue
+
+Status: accepted
+
+Date: 2026-08-31
+
+## Decision
+
+Forge has one canonical Runtime, one Controller Home, and one OpenAI Secure
+Tunnel authority on the Windows host's WSL distribution. A damaged Forge
+checkout, Runtime, Controller, MCP gateway, or normal Recovery deployment must
+not prevent the host from starting that canonical set.
+
+The rescue implementation is therefore copied at bootstrap time to:
+
+```text
+C:\ProgramData\ForgeRecovery\
+/home/<user>/.forge-recovery/
+```
+
+It has a Windows PowerShell wrapper and WSL shell agent, both exposing only
+named actions. The WSL agent holds the one mutation lock and owns one systemd
+user watchdog. The Windows logon task may wake WSL and submit `full_recover`,
+but it creates no second watchdog and does not own Runtime state.
+
+## Boundaries
+
+- The rescue configuration stores only exact paths, service units, and tunnel
+  identity. It contains no Runtime API key or OAuth token.
+- `tunnel-client` remains the credential owner. Its runtime-key reference must
+  resolve outside any retired repo-local Controller Home before that home is
+  retired.
+- The Secure Tunnel Connector is loopback-only and runs with `--auth none`.
+  OpenAI Secure Tunnel is the external authorization boundary; an OAuth gateway
+  is required only for a separately configured HTTPS/public connector.
+- The rescue agent may start/restart only the configured canonical Runtime and
+  Connector units, its own unit, and its configured tunnel alias. It cannot
+  accept a command string or select an alternate host/release/controller.
+- Controller Home migration remains an explicit stop-copy-verify-cutover
+  transaction. The rescue agent can recover canonical services after cutover;
+  it does not copy databases or make authority decisions.
+
+## Failure handling and removal
+
+The watchdog tolerates a failed reconciliation cycle and retries through its
+single systemd unit. Concurrent Windows/manual/service calls serialize through
+the external lock and fail with a retryable lock-busy result instead of racing.
+If the rescue package itself is compromised or needs retirement, disable
+`com.moretea.forge.independent-recovery.service`, unregister `Forge Independent
+Recovery WSL`, and remove only the two explicitly named external rescue roots
+after a verified replacement is installed. This removal never deletes a
+Controller Home, Runtime release, tunnel profile, or source checkout.
+
+## Verification
+
+Focused tests cover canonical unit derivation, safe path/argument validation,
+and credential-free generated configuration. Operational acceptance requires
+the recoverable Runtime, Connector, tunnel, and WSL-user-service restart drills
+documented in `docs/operations/windows-wsl-host-rescue.md`.

package/docs/architecture/decisions/20260904-ios-device-migration-baseline.md

@@ -0,0 +1,120 @@
+# iOS physical-device migration baseline
+
+Status: accepted migration baseline
+Date: 2026-09-04
+Issue: #47 / T9
+
+This decision freezes the ownership map for migrating the current in-process physical-iPhone implementation to one independently operated `ios-device` provider service. It does **not** define a second plugin protocol. The generic Forge plugin/action/registration contracts remain authoritative.
+
+## Authority dependency
+
+This migration consumes the existing generic plugin architecture instead of copying it:
+
+- Forge plugin/action semantics and authorization use `src/runtime/plugins/types.ts` and the normal plugin store;
+- an independently installed provider is addressed through the existing `ExternalPluginRegistration` / external-adapter boundary;
+- provider transport, lifecycle, capability negotiation, protocol version fencing and registration revisioning stay generic plugin concerns;
+- legacy MCP names may translate into canonical typed iOS actions, but the translation is never runtime or device authority.
+
+The issue's historical `ISS-20260802-3EC105` protocol decision is therefore satisfied by the current generic plugin implementation. This document records only iOS ownership and migration choices.
+
+## Product and process boundaries
+
+### `ios-development`
+
+`ios-development` is repository-development tooling owned by the Forge Runtime release. It includes Xcode/toolchain status, project/scheme discovery, build/test, Simulator lifecycle/screenshot, smoke review and the Xcode-facing App Store Connect authentication reference. Its current implementation is composed by `src/runtime/plugins/ios-adapter.ts` over `src/runtime/safe-tooling/ios-development.ts`.
+
+It may start bounded build/test/simulator child processes. It does not own a physical phone, a WDA session, a CoreDevice trusted tunnel, or a durable physical-device interaction.
+
+### `ios-device`
+
+`ios-device` is the one physical-device resource domain. The exact paired phone is the resource identity; CoreDevice identifiers, hardware UDID and reviewed provider aliases may all name that same resource. `InteractionSessionRecord.provider = "ios-device"` is the shared ownership domain and `engine = "coredevice" | "agent-device"` selects an implementation engine inside that domain, not another owner.
+
+The target migration has one independently operated `ios-device` provider process for physical-device transport/runtime work. That provider may host CoreDevice, RemoteXPC/HID and agent-device/WDA engines, but those engines must serialize against the same exact-phone ownership fence. Forge remains the semantic/controller side and must not run a competing long-lived physical-device owner after cutover.
+
+The provider release is independently versioned from the Forge Runtime release and is selected/verified through the generic external-plugin registration boundary. Forge release activation must not silently replace provider device state.
+
+## State and resource ownership
+
+| Concern | Sole owner after migration | Boundary |
+| --- | --- | --- |
+| Requirement/Work/controller authority | Forge Controller | Never exported to `ios-device`. |
+| Physical-phone ownership and live backend handles | `ios-device` provider | One exact phone, one mutation owner across CoreDevice and agent-device engines. |
+| Durable semantic InteractionSession identity | Forge iOS/Controller layer | Engine is metadata inside the one `ios-device` provider domain; provider-local session/WDA handles are not second durable authority. |
+| CoreDevice discovery, trusted tunnel and RemoteXPC/HID transport | `ios-device` provider | No parallel Forge-side tunnel owner after cutover. |
+| agent-device/WDA process/session runtime | `ios-device` provider | Capability/version contract is reviewed and fail-closed. |
+| WDA signing execution and provider runtime signing state | `ios-device` provider | Forge may pass bounded non-secret configuration/reference; signing runtime state is not mirrored into a second owner. |
+| App-specific semantic locators and assertions | Forge app adapters | Provider receives semantic/typed operations and returns observations; transport code does not learn JD or other app business semantics. |
+| Bounded/redacted acceptance evidence | Forge | Provider observations are evidence inputs, not semantic acceptance authority. |
+| Xcode build/test/simulator state | `ios-development` in Forge | Separate from physical-device ownership. |
+| App Store Connect account/release actions | App Store Connect adapter | Separate remote-account authority; not part of `ios-device`. |
+
+`interactionMayOwnTarget()` and the target-alias rules are the current migration fence: old records that cannot prove they refer to a different phone fail closed rather than allowing CoreDevice and agent-device to acquire the same device concurrently.
+
+## Existing module migration map
+
+`KEEP` means the responsibility stays in Forge. `MOVE` means the responsibility belongs in the independent `ios-device` provider. `REWRITE` means the current in-process module is useful evidence/behavior but is not itself the final service boundary. `DELETE` is conditional on the stated removal criterion.
+
+| Current path / responsibility | Decision | Target owner and rationale |
+| --- | --- | --- |
+| `src/runtime/plugins/ios-adapter.ts` | KEEP, then shrink | Keep the public Forge iOS composition facade and `ios-development` actions. Physical-device actions become provider-backed composition after T10 rather than a second in-process backend. |
+| `src/runtime/safe-tooling/ios-development.ts` | KEEP | Repository/Xcode/Simulator development tooling remains Forge-owned. |
+| `src/runtime/plugins/interaction-session.ts` | KEEP | Forge keeps durable semantic interaction identity and exact target/alias fencing. `engine` remains implementation metadata, never separate device ownership. |
+| `src/runtime/plugins/ios-agent-device.ts` | MOVE + REWRITE | Move physical agent-device/WDA lifecycle, command execution, signing runtime and provider session handling behind the `ios-device` service. Preserve reviewed behavior, not the current monolithic in-process shape. |
+| `src/runtime/plugins/ios/agent-device-capabilities.ts` | MOVE | Provider-side version/help negotiation and contract fingerprinting belong next to the executable being negotiated. Forge consumes the declared capability result. |
+| `src/runtime/plugins/ios/agent-device-failures.ts` | MOVE, preserve semantics | Transport/session failure classification must be owned with the provider lifecycle. Preserve the semantic-vs-session-death distinction and unknown-outcome fencing. |
+| `src/runtime/plugins/ios/agent-device-provider.ts` | MOVE | This is already a provider abstraction; it becomes part of the service-side backend contract rather than a competing Forge device owner. |
+| `src/runtime/plugins/ios/agent-device-typed-provider.ts` | MOVE | Typed agent-device client loading/execution belongs in the service process. |
+| `src/runtime/plugins/ios-physical-device.ts` | MOVE + REWRITE | CoreDevice physical-phone discovery, launch/install, screenshot and device/session mechanics move behind `ios-device`. Forge retains only canonical action semantics/authorization and normalized evidence. |
+| `src/runtime/plugins/ios/remote-xpc-hid.ts` | MOVE | Trusted-tunnel discovery, RemoteXPC keyboard/pasteboard/HID and coordinate transport are provider mechanics tied to the live phone. |
+| `src/runtime/plugins/ios/app-adapters.ts` including JD | KEEP | App-specific semantics remain Forge-owned. JD search/navigation selectors and assertions must not move into transport/service code. |
+| `src/runtime/plugins/app-store-connect-adapter.ts` | KEEP, separate | Store/account release API authority is unrelated to physical-device transport. |
+| `adapters/mcp/runtime-gateway/legacy-ios-tool-adapter.ts` | KEEP temporarily, then DELETE | This is the **only** migration proxy for legacy iOS MCP names. It translates to canonical plugin actions and owns no execution/device state. Remove when no exposed legacy iOS tool/caller depends on it. |
+| current iOS physical-device regression tests | REWRITE/SPLIT | Keep Forge tests for semantic action, authorization, interaction ownership and evidence; move provider lifecycle/transport/WDA/CoreDevice contract tests with the service. Cross-boundary integration tests verify one owner, not two implementations. |
+
+## Signing, WDA and CoreDevice rules
+
+1. WDA signing is provider execution state. Team/bundle/signing configuration may be supplied through a bounded configuration/reference, but Forge and the provider must not both maintain mutable signing-session authority.
+2. `agent-device` version/help detection remains capability negotiation. A preferred version is support guidance; an unsupported/unreviewed contract fails closed rather than guessing CLI flags.
+3. CoreDevice trusted-tunnel/RSD discovery and RemoteXPC/HID live handles stay with the provider that owns the physical phone.
+4. A semantic action failure such as element-not-found may preserve the physical session. Transport/session death invalidates the live provider binding. An unknown non-idempotent mutation outcome is fenced and is never replayed merely by switching engines.
+5. A screenshot or lifecycle read is observation evidence only. It cannot be promoted into proof that a semantic mutation completed.
+
+## App-adapter boundary
+
+`src/runtime/plugins/ios/app-adapters.ts` is the semantic extension point. The JD adapter remains here because its bundle identity, snapshot depth, semantic targets and interaction expectations are application knowledge. The `ios-device` provider must remain app-agnostic: it owns snapshot/input/session/transport mechanics and returns typed observations.
+
+Adding another app must therefore not require a provider-service release unless the app exposes a genuinely new transport capability.
+
+## Single migration proxy
+
+During migration there is exactly one compatibility translation layer: `adapters/mcp/runtime-gateway/legacy-ios-tool-adapter.ts`.
+
+It may map a bounded legacy MCP name/argument shape to a canonical iOS plugin action. It may not:
+
+- discover or select a device;
+- own an InteractionSession;
+- launch WDA/CoreDevice services;
+- hold signing or tunnel state;
+- perform the plugin action itself;
+- introduce another approval or evidence authority.
+
+Removal condition: once the stable MCP/tool surface and all maintained callers use canonical typed plugin actions directly, repository search and compatibility tests must show no maintained legacy iOS tool consumer. The adapter and its legacy-only tests are then deleted in the same slice.
+
+## Migration sequence
+
+1. **T9, this baseline:** freeze ownership and the keep/move/rewrite/delete map. No protocol redesign.
+2. **T10 / #48:** establish the independent `ios-device` service using the generic plugin/provider boundary, while the legacy MCP translation remains the only proxy.
+3. **T11 / #49:** move persistent device identity, provider/WDA/session/signing lifecycle behind that service while preserving Forge InteractionSession authority and one-phone fencing.
+4. **T12 / #50:** move reusable semantic interaction-engine behavior without moving app semantics; JD remains a Forge app adapter.
+5. **T13 / #51:** validate recovery/performance/core upgrade behavior and prove no dual owner during provider restart or engine failure.
+6. **T14 / #52:** complete physical-device Debug build/install/log collection through the converged boundary.
+7. Remove the compatibility proxy only after maintained legacy consumers reach zero.
+
+## Acceptance invariants
+
+- `ios-development` and `ios-device` have different resource/process/release authority and cannot silently acquire one another's state.
+- One exact physical phone has one `ios-device` mutation owner even when multiple backend engines exist.
+- Forge owns semantic app targeting, authorization, durable controller/interaction identity and acceptance evidence; provider owns live device/session/transport mechanics.
+- Signing/WDA/CoreDevice tunnel state has one provider owner.
+- Exactly one migration proxy exists and it is translation-only.
+- The migration reuses the generic plugin registration/action protocol and introduces no iOS-specific competing protocol authority.

package/docs/architecture/decisions/20260904-repository-runtime-data-boundary.md

@@ -0,0 +1,42 @@
+# Repository / Runtime Data Boundary
+
+Status: accepted for Kernel V2
+
+## Decision
+
+The Git working tree is an authored product and engineering surface, not a Runtime database or cache root. Forge keeps four storage classes distinct:
+
+1. **Repository-authored truth**: source, tests, human-maintained product/architecture/research/deferred-goal documents, and declarative project configuration. Git owns history. A path under `plans/` or `tasks/` is not source merely because of its directory name; generated lifecycle projections remain machine state.
+2. **Durable machine authority**: Requirement/Plan/Work/Controller/session/lease/evidence state lives in Controller Home SQLite or a Controller-owned repository namespace.
+3. **Provider artifacts and rebuildable cache**: browser profiles/captures/downloads, interaction state, check receipts, generated caches and similar machine output live below Controller Home and carry explicit retention/GC rules.
+4. **Ephemeral scratch**: short-lived process scratch lives in the OS temporary directory and must be removable after process ownership expires.
+
+Repository-local `.ai/harness/*`, `.forge/*`, `_ops/`, `.repo-harness/`, and `.codegraph/` machine state may exist only as explicit migration inputs/compatibility links to Controller Home. New physical Runtime writers must not be added under the repository root. `forge.config.json` is the small declarative project opt-in marker and contains no mutable Runtime state.
+
+## Lifecycle and Retention
+
+- **Authority retirement is immediate.** When a Plan is superseded/cancelled/finalized, any non-terminal Work that still derives execution authority from that terminal Plan must be rebound through an explicit successor transaction or terminalized. It must disappear from current/admission projections immediately even though its history row remains durable.
+- **History retention is separate from authority.** Requirement/Plan/Work terminal records remain queryable for bounded audit, lineage, rollback/recovery and acceptance evidence. A retained historical row is never considered active merely because it still exists in SQLite.
+- **Physical GC is last.** Terminal/no-op records and artifacts may be deleted only after no active authority, successor obligation, audit reference, rollback window or recovery hold depends on them and the configured age/count/size retention policy is satisfied. SQLite deletion/compaction must not be the mechanism that makes authority non-current.
+- Human-readable Requirement/Plan/Work views are optional read-only projections. If materialized at all they have one stable identity per projected view, explicit source revision/freshness, are fully regenerable from Controller Home, and are replaced rather than accumulated. They never participate in lifecycle transitions. Human-authored plans may remain in Git only when they are independently useful design documents, not because PlanContract requires a Markdown twin.
+- Provider artifacts use bounded age/size/ownership retention. Durable semantic history is retained in the Control Plane, not by accumulating filesystem snapshots or `*-archive` trees in the repository.
+- Compatibility links are transitional API surfaces. They do not make the repository the storage authority.
+
+## Enforcement
+
+`check:repository-hygiene` is part of the governed task gate. It rejects retired live roots and known physical Runtime/cache namespaces in the source tree. Runtime storage initialization migrates Browser provider state and interaction sessions into the repository's Controller Home namespace. Controller check evidence, test checkpoints/receipts, and check locks are written directly under the repository's Controller Home `checks/` namespace. New check execution keeps `.ai/harness/checks` absent; public evidence uses a `controller-home://checks/...` locator rather than exposing an absolute machine path or creating a repository compatibility link. Controller worklog events are likewise Controller-owned runtime evidence: new writes use the repository Controller Home `controller/worklog.jsonl` namespace and never recreate `.ai/harness/controller/worklog.jsonl`; explicit human exports under `tasks/reports/` remain repository-authored deliverables. Durable EditSession writes must first bind the compatibility `.ai/harness/edit-sessions` locator to Controller Home; a durable-bound session fails before mutation when that binding is absent, and its atomic recovery backups stay inside the bound EditSession namespace.
+
+Legacy check storage has one bounded retirement path. When a registered repository still contains a physical `.ai/harness/checks` directory, the first Controller-owned check execution moves the entire directory to that repository's Controller Home `quarantine/legacy-checks/<unique-id>` namespace before creating new evidence. A canonical compatibility symlink is removed without touching its Controller Home target. Foreign symlinks, non-directory entries, and paths without a matching repository registry authority remain fail-closed. Quarantine preserves historical bytes for manual recovery but is not a check-evidence authority and is never recreated as a repository link.
+Retirement is idempotent under concurrent Runner startup: if another owner wins the
+rename, unlink, or empty-directory removal race, the losing owner observes the
+already-converged Controller Home state rather than manufacturing a second failure.
+Retired legacy-check entries share the central Runtime quarantine retention policy
+with Local Job quarantine; full maintenance uses one bounded scan/removal budget
+across both namespaces.
+
+The retired `.codegraph` cache follows the same boundary but remains a
+rebuildable cache rather than evidence. Its legacy copy/symlink migration is
+serialized by the existing Controller lock using the exact repository-cache
+identity, so concurrent initializers converge on one Controller Home target
+instead of racing `copy`/`remove` operations or creating a second cache
+authority.