@moretea-labs/forge 1.7.2 → 1.8.1

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

@@ -1,12 +1,12 @@
 # ADR: Whole-Forge-Runtime Release Identity and Exit Policy
 
 - **Status:** Accepted and aligned with the Canonical Forge Runtime
-- **Date:** 2026-08-03; revised 2026-08-09
+- **Date:** 2026-08-03; revised 2026-08-09 and 2026-09-18
 - **Authority:** [`../CURRENT.md`](../CURRENT.md), [`../CURRENT.md`](../CURRENT.md)
 
 ## Decision
 
-One immutable release identity binds the complete `forge-runtime` process and every bounded child it launches:
+One immutable release identity binds the stable `forge-runtime` supervisor launcher, the manifest-attested Runtime interpreter/bundle pair, and every bounded child the Canonical Runtime launches:
 
 ```text
 ReleaseIdentityBinding {
@@ -25,11 +25,17 @@ Authority order is:
 3. an owning Git checkout only for explicit developer launches;
 4. never an ambient parent repository.
 
-The OS service manager starts and automatically restarts the single `forge-runtime` root process after unexpected process death. The service executes from the stable physical path `ControllerHome/runtime/service/active-forge-runtime`; that file is an atomic byte-for-byte mirror of the signed entrypoint in the selected immutable release, not a symlink into `runtime/releases/<releaseId>`. Release assets and semantic identity remain bound by the selected manifest and `FORGE_RELEASE_*` environment. The fixed physical executable path is required so macOS TCC descendants inherit one stable responsible-process identity across releases instead of creating one permission principal per release directory. Module readiness failure does not create component restart authority. A release transition stops and starts the complete Runtime, refreshes the stable mirror from the selected release before launch, verifies binary whole-Runtime readiness, and on failure restores the previous complete release together with its matching stable mirror and bound SQLite backup.
+The OS service manager starts and automatically restarts one stable `forge-runtime` supervisor launcher after unexpected service death. The service executes from the stable physical path `ControllerHome/runtime/service/active-forge-runtime`; that file is an atomic byte-for-byte mirror of the signed launcher in the selected immutable release, not a symlink into `runtime/releases/<releaseId>`. The launcher validates the manifest-bound Runtime bundle plus the co-located release-owned Bun interpreter, starts exactly one interpreter child, forwards lifecycle and diagnostic signals, waits for that child, and mirrors its abnormal terminal outcome. The launcher carries no Scheduler, Gateway, Work, or release-transition authority and never imports the long-lived Runtime bundle into its compiled JSC VM. Release assets and semantic identity remain bound by the selected manifest and `FORGE_RELEASE_*` environment. The fixed physical launcher path remains the macOS TCC responsible-process boundary inherited by Runtime descendants across releases instead of creating one permission principal per release directory. Module readiness failure does not create component restart authority. A release transition stops and starts the complete Runtime service, refreshes the stable launcher mirror from the selected release before launch, verifies whole-Runtime readiness through the child-owned Runtime status/owner record, and on failure restores the previous complete release together with its matching stable mirror and bound SQLite backup.
 
 Standalone Recovery remains independently installed. It may diagnose the service, repair the service definition or tunnel, and perform authorized offline whole-Runtime rollback when the primary Runtime cannot start. It never becomes a second scheduler, Gateway, state writer, or component owner.
 
-The immutable release carries every helper executable or library needed by those bounded children. This includes the Process/Check runners, Browser/Desktop helpers, external-plugin probe, and the matching CodeGraph Node executable, read-only sidecar, and compiled library tree. CodeGraph is invoked once per bounded context query by `forge-runtime`; it is not a daemon, service, recovery owner, readiness authority, or persistent state writer. Its only durable input is the repository-owned `.codegraph/` index selected for the request.
+Runtime release activation is a recoverable transaction inside the single `ControllerHome/runtime/releases/authority.json` authority. While a candidate is being activated, the authority carries bounded pre-activation rollback context for the prior active/previous release bundle and bound SQLite backup. Successful whole-Runtime verification commits by clearing that transaction context without minting a second release authority; failed or interrupted activation aborts through the same authority and restores the pre-activation bundle. Standalone Recovery reconciles an interrupted transaction on restart rather than creating a new activation owner.
+
+Recovery known-good attestations are bounded recovery authority, not detached historical labels. A live known-good record binds its matching immutable Runtime release, a checked Recovery-owned SQLite snapshot, and a hashed declarative service contract; release retention uses that same invariant. Schema-1 metadata-only history has no recovery or retention authority. Once a bounded bundle retires, ordinary bounded retention may remove its artifact. Recovery projections distinguish physically recoverable bundles from stale/unavailable evidence.
+
+A Runtime startup failure before Gateway readiness writes one latest-only diagnostic receipt containing the startup stage and reason. This receipt is diagnostic evidence only, never lifecycle authority, and a later successful whole-Runtime startup clears it.
+
+The immutable release carries every execution dependency needed by the Runtime and its bounded children. This includes the exact Bun interpreter that hosts the long-lived Runtime bundle, the Process/Check runners, Browser/Desktop helpers, external-plugin probe, and the matching CodeGraph Node executable, read-only sidecar, and compiled library tree. The Runtime interpreter is a hashed executable artifact and release-canary target, not a PATH-resolved host dependency or separate lifecycle authority. CodeGraph is invoked once per bounded context query by the Runtime; it is not a daemon, service, recovery owner, readiness authority, or persistent state writer. Its only durable input is the repository-owned `.codegraph/` index selected for the request.
 
 The CodeGraph artifact group is all-or-nothing in `manifest.json`: canonical co-located paths and SHA-256 identities are declared for the Node executable, sidecar, and library directory. A missing platform bundle fails release staging before publication. At runtime, an unavailable or failed structural query produces typed degraded context evidence and fails a mode's required-context condition; it does not create a second Runtime readiness state or restart authority.
 
@@ -38,7 +44,7 @@ CodeGraph child cleanup is owned by the initiating bounded query through timeout
 ## Exit policy
 
 - explicit authorized stop remains stopped;
-- unexpected root-process death is handled by the OS service manager;
+- unexpected launcher death is handled by the OS service manager; unexpected Runtime-child termination is mirrored by the launcher so the same service restart policy applies;
 - incomplete readiness is reported as degraded or failed whole-Runtime readiness;
 - stale Workers cannot renew Leases or publish under a replacement Runtime/release fence;
 - uncertain external writes are reconciled from receipts and are never replayed blindly.
@@ -48,6 +54,9 @@ CodeGraph child cleanup is owned by the initiating bounded query through timeout
 - immutable release identity never follows ambient Git HEAD;
 - advancing a developer checkout cannot alter the active release identity;
 - failed activation restores the previous release and matching SQLite backup;
+- interrupted activation reconciles to one committed or aborted release transaction without a second release authority;
+- bounded known-good attestations cannot advertise a missing immutable release as usable recovery authority;
+- pre-Gateway startup failure remains diagnosable after process exit without preserving stale Runtime lifecycle state;
 - service restart preserves durable Work, Process and evidence identities;
 - a release missing any CodeGraph artifact fails closed before activation, a bounded query times out or exits without leaving a child owner, and a complete previous-release rollback restores the matching CodeGraph artifact group;
 - no component-level restart, slot selection, ingress fallback or Supervisor authority exists.

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

@@ -6,7 +6,7 @@
 
 ## Decision
 
-ChatGPT remains the semantic Controller. Forge may persist and execute an explicit end-of-round Controller disposition, but it must never infer that a Requirement, Goal, or Work should continue.
+ChatGPT remains the semantic Controller for goal interpretation, completion, waiting, and user-blocking decisions. The original stabilization rule that Forge may continue only after an explicit `continue_immediately` disposition is amended for V2 autonomous session continuation: once the exact Controller turn is provider-observed as settled, a still-nonterminal Work with no explicit stopping disposition has a Kernel-owned continuation obligation. This default is mechanical lifecycle policy, not semantic goal acceptance. Explicit `wait`, `wait_for_user`, `goal_complete`, active user-decision handoff, terminal Work, or bounded failure/budget state always wins and stops automatic continuation.
 
 The supported dispositions are:
 
@@ -19,7 +19,9 @@ goal_complete
 
 `continue_immediately` creates a durable `controller_round_relay` record under the existing Controller Home SQLite authority. It does not create a second scheduler, daemon, lifecycle owner, or autonomous agent. The current ChatGPT controller must own the exact live Work lease when it submits the disposition. Dispatch begins only after that lease is explicitly released.
 
-A ChatGPT wake is a two-stage mechanical lifecycle: `dispatched -> claimed`. Browser prompt submission proves only transport dispatch. The round becomes `claimed` only when an authenticated ChatGPT Controller acquires the exact Work lease. Neither state is semantic acceptance. A claimed round must still end with an explicit ChatGPT disposition. If the lease disappears without a disposition, Forge may mechanically re-dispatch after the bounded liveness grace; it must not infer whether the Goal should continue or complete.
+A ChatGPT wake is a two-stage mechanical lifecycle: `dispatched -> claimed`. Browser prompt submission proves only transport dispatch. The round becomes `claimed` only when an authenticated ChatGPT Controller acquires the exact Work lease. Neither state is semantic acceptance. A claimed round normally ends with an explicit ChatGPT disposition. If the provider proves the exact assistant turn has settled and no explicit disposition exists, Kernel policy closes that nonterminal round as `continue_immediately`; it never infers `goal_complete`. If an explicit stop state already exists, settled-turn replay is a no-op. Lease disappearance without either a disposition or exact turn-settled evidence remains abandonment/recovery, not implicit progress.
+
+**2026-09-16 authority clarification:** this `turn settled` fact is a lower-layer ControllerRound liveness fallback only. It does not prove that a ChatGPT Web assistant response committed the Workflow Supervisor completion protocol, and it does not own cross-assistant-turn scheduling after the caller has ended. The outer commit/start authority is defined by [`20260916-workflow-supervisor-authority.md`](20260916-workflow-supervisor-authority.md), which requires the complete terminal control block and exact END marker plus causal effect identity.
 
 The relay reuses the existing ChatGPT controller-browser launcher path. The originating Work's durable ChatGPT conversation binding is inherited automatically and then carried forward by stable relay scope, so later rounds and later Works under the same Requirement/Goal can reuse the same ChatGPT conversation without making chat history authoritative. Requirement, Work, Handoff and evidence state remain the source of truth.
 
@@ -27,7 +29,8 @@ A Requirement-bound relay scope is `requirement:<requirementId>`. A Goal without
 
 ## Lifecycle authority
 
-- `rh_work controller_disposition` records the Controller's explicit semantic decision.
+- `rh_work controller_disposition` records the Controller's explicit semantic decision; explicit stop dispositions override the default autonomous continuation rule.
+- exact provider-observed Controller-turn settlement is evidence only; Kernel transition policy alone may convert a still-claimed, nonterminal round with no stop disposition into the existing `continue_immediately` lifecycle.
 - `controller_release` is the only transition that may consume a pending immediate relay for that Work.
 - the canonical ChatGPT launcher performs the next-round dispatch;
 - Controller Session ownership, principal/session/instance fences, Handoff authority and external-effect policy remain unchanged and cannot be bypassed by Relay;

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.

package/docs/architecture/decisions/20260907-assistant-learning-loop.md

@@ -0,0 +1,37 @@
+# Assistant learning loop
+
+Status: Accepted implementation decision; live promotion certification remains required after focused implementation validation.
+
+Implementation note: Xiaohongshu platform-specific publishing choreography is migrated into versioned Workflow assets; Core retains only generic Workflow execution, reconciliation, evidence, and learning authorities; this decision document is not an operational state store.
+
+2026-09-17 evolution: this loop is now a compatibility producer/consumer of the generic Cognitive Plane. `ExperienceRecord` remains canonical during migration and is transiently adapted at recall; it is not copied into a second durable memory authority. General cognition is defined by `20260917-cognitive-memory-foundation.md` and is not limited to publication outcomes or failures.
+
+Forge self-defect observed during this delivery: an accidentally isolated Work was terminalized before its active controller lease was released, so cleanup was blocked until a separate controller_release; a subsequent maintenance diagnosis also reported accumulated terminal edit-session/temp ownership records. Treat this as one lifecycle-cleanup root-cause family rather than adding per-call workarounds. Maintenance diagnosis for this state took 25-35 seconds despite no source investigation, so cleanup ownership cardinality is also a performance concern. Track under the existing lifecycle-cleanup/maintenance root-cause issue if present; otherwise create one before this delivery closes. Do not create a duplicate authority for the same defect family.
+
+The accepted user outcome is two consecutive, evidence-linked assistant rounds for one explicitly bound project/account. The first-party Xiaohongshu workflow is the concrete certification case for this implementation; production execution must enter through rh_work rather than direct platform choreography, with Workflow Runtime as the sole external-effect owner and canonical receipt producer. Operational priors remain mechanical only. Controller reasoning produces observations, hypotheses and lessons; no autonomous compiler, scheduler, authorization owner or database is introduced.
+
+## Ownership and persistence
+
+Kernel Memory owns the experience contract and application service. Its Controller Home adapter is the sole writer of `assistant_experience` records, scoped by portable project identity, with version 1 payloads, transactional revision CAS and bounded provenance. The active Controller claim authorizes writes; source Work/round and retained evidence must match the requested lineage. Observations default to 30 days and hypotheses to 90 days. Lessons require expiry or explicit durable applicability rationale. Supersession and retraction are terminal for recall; audit history remains in the existing SQLite audit authority. Central maintenance invokes bounded retirement after expiry/retraction grace. No chat-history reconstruction is allowed.
+
+Outcome observations are typed evidence linked to an existing Work and retained receipt, not a campaign lifecycle. Missing metrics are explicit null values with reasons; cumulative snapshots are never summed automatically. Source removal invalidates dependent recall. Payloads are metadata-only and exclude credentials, cookies, binaries and raw logs. Schema rollback is whole Runtime plus its paired Controller Home backup.
+
+## Context and trust
+
+Project contracts register exact knowledge sources. Repository mirrors remain projections of their repository originals; independent Brain documents retain their own authority. Context reads only registered sources within explicit roots, with realpath containment, bounded bytes/time/candidate counts, content digests and visible gaps. Chinese lexical retrieval is supported. Retrieved text and experience are advisory data, never instructions granting authority or weakening current task constraints. No persistent search index is required in v1.
+
+Provider-neutral round preparation composes bounded context; host adapters only render it. Current Work and project identity must be revalidated after claim. Knowledge failure cannot silently permit a publish that needs missing product constraints. Account/channel applicability is exact; omission never widens access to account-specific experience.
+
+## Workflow and recovery
+
+Preserve Workflow migration B/C/D/E obligations. The interpreter remains subordinate to Work, Process, provider effects and existing resource fencing. Outputs referenced by later steps must be retained with checkpoint identity. An effect dispatched before checkpoint failure is reconciled through the existing receipt authority before replay. Assets pin version/digest and inputs; changing them cannot reuse a run. Site choreography stays versioned asset data.
+
+## Concurrency, time and capacity
+
+All experience mutations run in one SQLite transaction with expected revisions and bounded rows per project. Explicit timestamps drive expiry and tests; invalid/future observations fail validation. Reads filter scope before ranking and share existing Context item/byte/token ceilings. Read failures are visible gaps. Central lifecycle maintenance owns physical cleanup; retrieval does not become another persistent writer. No new process, cross-node replication or provider identity is introduced.
+
+## Delivery and retirement
+
+Execution-quality observations reuse ControllerRound semantic fingerprints and exact check evidence. They are bounded advisory signals, not a `normal/degraded` persistent state or a second Supervisor. Legitimate wait/investigation is not failure; same-source pass/fail indicates possible flakiness, not proven code regression. Controller diagnosis and accepted design return-to-design gates retain semantic authority. Cross-task strategy A/B remains the existing benchmark's responsibility; differing task difficulty cannot establish policy superiority.
+
+Keep existing operational-memory semantics and Workflow acceptance obligations. Replace modern Brain promotion's deleted-file inference with terminal Work evidence; retain old Git import only behind an explicit legacy flag until consumers migrate. No partial Runtime activation is part of this change. Focused fault tests and whole-candidate gates precede delivery; actual two-round publication and metrics evidence precede the claim that live assistant capability is complete.