@moretea-labs/forge 1.8.0 → 1.8.2

package/docs/architecture/decisions/20260918-stable-candidate-release-lifecycle.md

@@ -0,0 +1,234 @@
+# ADR: Stable A / Candidate B and ReleaseSession authority
+
+- **Status:** Accepted source architecture; authority boundary refined 2026-09-20; live cutover remains a separate release operation
+- **Date:** 2026-09-18
+- **Authority:** [`../CURRENT.md`](../CURRENT.md) and executable Runtime/Recovery contracts
+
+## Decision
+
+Forge self-hosting has two lanes during a release session:
+
+```text
+Stable A (fixed known-good package Runtime)
+  source read/edit/build/static verification + Recovery control
+  remains running and is never upgraded by the session
+
+Candidate B (one isolated Controller Home)
+  copied SQLite snapshot + independent token/config/port/service label
+  portable immutable release materialized once and tree-hashed
+  all candidate canaries on the exact artifact later promoted to A
+
+ReleaseSession (release domain)
+  sole durable normal-release lifecycle authority
+  durable receipt/fence journal
+  final semantic routing decision: B or still-healthy A
+
+Standalone Recovery provider
+  physical Candidate B preparation and verification
+  fenced Runtime activation / rollback
+  Watchdog health recovery only
+```
+
+Candidate B never shares A's Controller Home, `control-plane.sqlite`, release
+authority, token file, TCP port, service label, Runtime incarnation, Supervisor
+socket or writer claim. B is not a second production authority: its Home is a
+bounded test clone. New compiled release manifests are deployment-portable and
+omit Controller Home; deployment binding belongs to release authority/service
+contract instead. The exact verified B artifact is promoted byte-for-byte into
+A's immutable release store. A remains the execution plane until an approved
+ReleaseSession reaches one final cutover.
+
+No source build, static gate, architecture review or ordinary test may stop or
+activate Stable A. After the source batch is accepted, ReleaseSession may boot
+and restart only isolated Candidate B while A remains continuously available.
+The sole production cutover happens only after B passes Recovery, MCP,
+Scheduler, Supervisor and controller canaries. Final certification then covers
+A→B→C continuation, failed startup, Recovery interruption, Runtime restart,
+MCP reconnection, stale Supervisor writer and return-to-A rollback.
+
+## Incarnation and writer fence
+
+`runtime-incarnation.json` is the Controller-Home durable writer epoch. Runtime
+ownership acquires it monotonically with `runtimeInstanceId`, PID and
+`fencingGeneration`; a child claim contains the same generation. A write is
+valid only when owner, incarnation and whole-release authority all match.
+Crash/hard-stop replacement advances the generation, making every old Runtime,
+Scheduler worker, Gateway request and process writer stale without relying on
+their `close()` handlers.
+
+Supervisor's Unix socket has only ephemeral owner evidence containing the same
+incarnation. A live socket is a hard writer conflict. A non-connectable socket
+can be reconciled only as stale evidence for a different incarnation; the
+historical `WORKFLOW_SUPERVISOR_WRITER_ALREADY_PRESENT` condition is therefore
+an acceptance case, not a fallback branch.
+
+Every service/Recovery/child boundary starts from the shared private-authority
+environment sanitizer. It strips `FORGE_CONTROLLER_*`, `FORGE_RUNTIME_*`,
+`FORGE_RELEASE_*`, `FORGE_SUPERVISOR_*`, `FORGE_WRITER_*` (including
+`FORGE_WRITER_SLOT`) and related process identity. The exact selected release
+contract may then add its own values. No ambient host claim is inherited.
+
+## Recovery bundle and known-good
+
+Known-good schema v2 means all of the following validate together:
+
+1. immutable release manifest identity;
+2. Recovery-owned SQLite `VACUUM INTO` snapshot with SHA-256 and inspection
+   counts/schema;
+3. a hashed declarative Runtime service-contract snapshot.
+
+The bundle lives below `Recovery/bundles/known-good/<attestationId>`. Recovery
+creates its data before atomically publishing the known-good record, then
+prunes unreferenced bundles only after publication. A crash leaves at most an
+orphan for the same Recovery owner to clean; it never publishes a metadata-only
+known-good record. Release retention uses this exact validator. Legacy schema-1
+records remain audit history only and have no retention or rollback authority.
+
+## ReleaseSession state
+
+`Recovery/state/release-sessions/<id>.json` is the durable storage path for the
+ReleaseSession transaction journal; that path is not a second authority. The
+ReleaseSession domain owns semantic phase progression and a per-record revision
+CAS, while the executing Recovery provider holds the existing mutation lock for
+physical operations. Authority decisions read the complete journal through a
+process-local cache that is invalidated by atomic session writes and directory
+changes; bounded inventories are diagnostic/projection surfaces only and may
+never decide whether an active or prior-attempt session exists. Terminal session
+records remain durable evidence, while their Candidate B homes are physically
+retired once; an already-absent home is an idempotent no-op and is not emitted as
+a fresh cleanup event. A stateless ReleaseCoordinator derives the next action
+from the persisted phase and has no second daemon, scheduler, Work, or durable
+coordinator state. Only one non-terminal ReleaseSession may exist per Forge
+instance. An interrupted `source_frozen` preparation resumes that same session
+when the frozen source and Stable A identity still match.
+
+Recovery's own bundle handoff acquires that same exclusive operation lock before
+changing the immutable release pointer and holds it through activation verification
+or exact rollback. New Gateway requests are fenced during this interval and the
+admission marker is cleared on every exit. Open read-only MCP streams are transport
+connections, not in-flight mutation evidence; HTTP request counts cannot add a
+second quiescence gate. The existing service handoff still proves the previous
+process has stopped and the exact replacement is serving before acceptance.
+
+ReleaseSession separates wire compatibility from semantic authority. One-way migration also reconciles historical legacy `soaking` records without guesswork: Candidate B is terminalized as `known_good` only when exact durable lineage proves it became a later Stable A, or current RuntimeReleaseAuthority `previous` references that exact release identity; missing proof fails closed. Multiple later ReleaseSession attempts that all name the same exact Candidate B as Stable A are corroborating acceptance evidence, not branches. Successor proof is derived from one pre-migration inventory snapshot, so rewrite order cannot manufacture or erase acceptance evidence. Its
+storage `schemaVersion` remains 1 so the immediately previous Recovery release
+can still inventory the record after an exact rollback; current code requires
+`semanticEpoch=2`. The migration boundary rewrites legacy epoch-1/epoch-less
+records once and thereafter steady-state code consumes only epoch 2. The
+`transaction` field is additive on the wire and ignored by the prior reader.
+RuntimeReleaseAuthority schema 2 is the physical active/previous pointer plus
+rollback SQLite artifact only; it carries no ReleaseSession transaction state.
+
+```text
+source_frozen → built → static_verified → candidate_booted
+  → candidate_verified → cutover_eligible → cutover_attempting
+  → cutover_committed → soaking → known_good
+                         ↘ rolled_back / failed
+```
+
+`static_verified` requires type, runtime-architecture, architecture-sync and
+bootstrap receipts from the frozen source revision. `candidate_verified`
+requires Recovery restart, MCP, Scheduler, Supervisor and controller receipts
+from isolated B. `cutover_eligible` is impossible while A and B collide on Home
+or port. Before the first production activation, a transient failure to obtain a
+fresh Stable A verification leaves the same ReleaseSession `cutover_eligible` so
+the exact candidate can be retried after observation recovers; proven Stable A
+identity drift is a real precondition failure. After those exact pre-cutover
+checks and immutable Candidate promotion, Recovery may arm a bounded mechanical
+drain marker in the existing Package Connector service root. The marker is tied
+to the exact serving Stable A Connector generation (`releaseId`, `installedAt`,
+and endpoint) plus the Recovery owner lifetime; that generation rejects new MCP
+POST/stream admission with retryable 503 while already-admitted responses,
+initialization and the existing session-idle window drain. The zero-active
+request/stream gate is unchanged. A Candidate or rollback Connector rebind
+changes the service generation before strict MCP verification, so the
+replacement process is not trapped behind the predecessor marker. Recovery
+clears the marker on every cutover exit; owner-liveness and TTL checks bound any
+orphaned marker. This marker is transport fencing only, not ReleaseSession
+state, release intent or another lifecycle owner. `cutover_attempting` permits
+exactly one fenced production cutover; verified return to exact A terminalizes
+`rolled_back` and is never retried. If observation is interrupted after the
+rollback authority commit but before the ReleaseSession phase write,
+reconciliation requires the exact `release-session-rollback:<sessionId>:`
+authority operation plus matching Stable A, candidate and transaction identities;
+it then records `rolled_back` without replaying the rollback effect.
+Physical service handoff follows the same effect rule: a launchd/systemd helper
+error or timeout is not itself authority that the requested stop/start failed.
+Recovery performs bounded observation of the exact service identity and may
+continue the same fenced transaction only when the physical effect is proven;
+otherwise that transaction fails. Before stopping Stable A, Recovery may build
+the rollback SQLite snapshot while A is still serving, but only under a
+long-lived SQLite `data_version` observer. Any commit by another SQLite
+connection during or after that speculative snapshot invalidates it; after
+quiescence the release store discards it and falls back to the stopped-state
+snapshot. Recovery also computes the bounded SHA-256 of that snapshot while A
+is still serving. RuntimeReleaseAuthority persists this whole-database identity;
+on rollback, a fresh live `VACUUM INTO` snapshot is compared against it. Only an
+identical whole-database snapshot may be restored from the cutover backup. Any
+SQLite change, including domain tables outside `control_plane_audit`, preserves
+the newer live database while the Runtime release rolls back. Legacy backups
+without whole-database identity also preserve live state. This optimization
+therefore removes normal-path database copy/hash cost from the outage window
+without weakening rollback or losing post-cutover durable state.
+
+During the stop/start critical section, readiness convergence is intentionally
+narrow: canonical Runtime owner/status, exact release/artifact authority and the
+local `/ready` endpoint. Recovery Gateway/watchdog/tunnel probes, Connector
+transport probes, execution canaries, known-good inspection and MCP protocol
+verification are not activation-readiness inputs. After Runtime readiness,
+Recovery rebinds the persistent Connector and then runs strict whole-Runtime
+verification exactly once. There is no second readiness polling phase after
+Connector rebinding. Once the physical candidate authority is published, the
+ReleaseSession rollback transaction is durably captured before Candidate B is
+started, so every later start/Connector/acceptance failure already has exact
+Stable A rollback identity. Recovery never replays a cutover merely because a
+helper response was lost.
+Automatic source reconciliation is also revision-bounded: once an immutable
+source revision has any terminal ReleaseSession, the daemon will not create a
+second automatic ReleaseSession for that same revision. Explicit human release
+operations remain available, and a changed source revision becomes eligible for
+a new automatic attempt. This rule is derived from ReleaseSession history; it
+introduces no retry ledger or second release authority.
+
+Successful cutover enters `soaking` as soon as the canonical live Runtime observation proves the expected release/artifact identity is running, ready and non-stale. Cutover reconciliation does not rerun the expensive full verification suite after activation. Only the existing full verification + performance observation + recoverable release/SQLite/service bundle attestation may terminalize `known_good`. A definitive runaway-CPU rejection is an acceptance
+failure, so Recovery executes the existing exact Stable A rollback transaction
+instead of leaving Candidate B in `soaking` for repeated performance sampling.
+Transient/unknown observations remain non-terminal and may be reconciled against
+the same ReleaseSession. The state machine records redacted receipt ids and
+summaries, never tokens, raw database payloads or browser messages.
+
+## Persistent-state contract
+
+| State | Semantic owner / writer | Terminal & retention | Recovery |
+| --- | --- | --- | --- |
+| `runtime-incarnation.json` | Canonical Runtime ownership acquisition | latest epoch; superseded generations remain stale | next owner CAS-reconciles |
+| Supervisor socket owner evidence | Canonical Runtime/Supervisor composition | deleted with socket; ephemeral | probe then remove only stale non-connectable socket |
+| known-good bundle | Standalone Recovery | bounded live attestations; prune only after state commit | validate release + DB + service contract offline |
+| RuntimeReleaseAuthority | Runtime Root physical release store | schema 2; active/previous release identity and previous SQLite backup only | physical publish/rollback; no release-phase or transaction intent |
+| ReleaseSession | Release domain / stateless ReleaseCoordinator | wire schema 1 + current semantic epoch 2; `known_good`, `rolled_back`, `failed`; bounded session retention is physical cleanup | revision CAS resumes the same session; Recovery provider executes physical effects |
+| Candidate B Home | ReleaseSession semantic authority / Recovery physical provider | explicit retired cleanup after evidence retention; soaking and terminal sessions are physically reclaimable only after candidate owner quiescence | no deletion/rebuild of A; B can be inspected independently |
+| Process Runtime terminal lease | Process Runtime lease authority | terminal evidence and lease release are separate idempotent phases | terminal observation/wait/cancel and full maintenance retry exact lease release until settled |
+
+All bundle and session data is local Controller state. It contains no secrets:
+the service contract records a token *path*, while each B token is an independently generated private credential and is never copied from A. SQLite data follows the Controller Home's existing privacy/backup policy.
+
+## Verification
+
+- Ordinary repository Work terminalizes at accepted source delivery and cannot depend on Runtime staging, activation, soak or known-good;
+- release-level gates execute once for the frozen ReleaseSession candidate rather than once per contributing Work;
+- Candidate lane derivation/build cannot mutate A; Candidate boot/restart touches only B's isolated service/Home;
+- byte-identical release-tree identity is required for B→A promotion; no production rebuild is allowed;
+- stale Runtime generation and release claims cannot write;
+- every Recovery restart/release transition proves service, Runtime owner, TCP listener and Supervisor writer quiescence before authority may change;
+- Recovery restart/cutover readiness polling is bounded to fenced Runtime identity plus local readiness; strict whole-Runtime verification remains a single post-Connector acceptance gate;
+- the normal cutover prebuilds and hashes its rollback SQLite snapshot while Stable A is live and reuses it only when one SQLite-wide `data_version` observer proves no intervening commit; otherwise stopped-state backup remains the fail-closed fallback;
+- rollback restores the cutover SQLite snapshot only when whole-snapshot SHA-256 matches a fresh live snapshot; any database-wide change preserves live SQLite, while `auditEventCount` remains compatibility/diagnostic evidence only;
+- ReleaseSession captures exact rollback transaction identity immediately after the physical authority publish and before Candidate B starts;
+- private writer environment cannot cross service or child boundaries;
+- stale or missing known-good bundle material cannot protect a release;
+- ReleaseSession cannot advance past static/candidate gates or a stale CAS;
+- no-op automatic reconciliation does not fork a Recovery worker, and terminal source revisions are not autonomously replayed;
+- definitive runaway-CPU rejection restores Stable A through the existing ReleaseSession rollback authority rather than repeating soak measurement;
+- terminal Process observation and full maintenance both reconcile any exact leftover workspace lease; `completed_unknown` cannot permanently fence a checkout;
+- periodic Runtime maintenance is the production retention caller; its rotating removal phase reaches release history without starving the other cleanup classes, while committed Runtime authority protects active/previous release trees, the serving Connector release and the previous rollback SQLite backup; historical known-good evidence alone does not pin release trees;
+- final live release testing remains a separate, one-shot governed operation.

package/docs/architecture/decisions/20260919-autonomous-work-liveness.md

@@ -0,0 +1,62 @@
+# Autonomous Work liveness invariant
+
+Date: 2026-09-19
+Status: accepted
+
+## Problem
+
+Forge could retain a non-terminal Work indefinitely after its execution carrier and
+Controller ownership disappeared. A current Plan protected that Work from stale
+authority retirement, but nothing materialized the already-existing semantic
+decision that the Work was ready to continue. The visible result was an unfinished
+conversation/task with no process, no live Controller owner and no next round.
+
+## Decision
+
+Global Scheduler's normal reconciliation cadence owns materialization, not semantic
+planning.
+
+For every active runnable Work with no active execution and no live Controller
+owner:
+
+1. If the Work is Plan-bound, projectAutonomousGoalProgression() is the sole
+   authority deciding whether the current Work is WORK_READY_TO_CONTINUE.
+2. If the Work is not Plan-bound, reconciliation may perform only the lower-level
+   mechanical liveness wake when Work/Requirement/ControllerRound state contains
+   no terminal or explicit wait authority. It never invents Plan authority.
+3. Existing retained ControllerSession identity and ControllerBinding are reused.
+   A retained session is identity evidence, not a live ownership lease.
+4. ControllerRound remains the sole provider-effect fence. The progression
+   idempotency key, or a deterministic planless Work occurrence key, becomes the
+   occurrence identity, so repeated scheduler ticks converge rather than replay.
+5. If Workflow Supervisor owns the outer ChatGPT turn, Scheduler only ensures the
+   idempotent Supervisor enrollment effect. It must not dispatch a competing
+   provider prompt.
+6. Existing semantic wait, wait_for_user, blocked/failed round state, live
+   execution, live Controller ownership and terminal Work/Requirement state all
+   suppress automatic continuation.
+
+No new lifecycle state, watchdog table, polling daemon, retry authority or
+Process-specific continuation path is introduced.
+
+## Baseline boundary
+
+Liveness reconciliation does not re-check the repository integration baseline in
+the middle of an already-running isolated Work. For Plan-bound Work it evaluates
+Goal Progression against the Plan's frozen source revision. Baseline drift remains
+an admission/replan boundary after the independent Work reaches its semantic
+boundary; it is not a reason to repeatedly interrupt execution.
+
+## Recovery boundary
+
+The existing periodic stalled-ControllerRound recovery remains responsible for
+already-open rounds whose provider dispatch or closure was abandoned. The new
+normal reconciliation path handles the previously invisible case where no round
+exists at all.
+
+## Acceptance
+
+A runnable ownerless Work converges to exactly one existing Controller continuation
+authority within the normal Scheduler reconciliation cadence. Repeated ticks and
+runtime re-entry cannot duplicate provider dispatch, and explicit waits remain
+stable.

package/docs/architecture/decisions/20260924-thin-semantic-working-context.md

@@ -0,0 +1,74 @@
+# Thin semantic working context and revision authority
+
+Status: accepted architecture; canonical cutover is implemented in current source with final verification pending. Frozen-client compatibility projections remain where required.
+
+## Decision
+
+Forge exposes only three cross-domain model-authored semantic records: Requirement, Plan, and optional Work. Requirement is stable intent, Plan is model-authored strategy/decisions/progress, and Work is an independently resumable semantic unit. Workflow, Schedule, Connection/Grant, Process, ControllerRound, repository state, and domain handles remain operational, security, execution, or domain facts rather than additional working-memory authorities.
+
+Each semantic record has one stable identity, one portable semantic scope and one monotonic semantic revision. ForgeInstance is the root authority; repository/checkout identity is execution placement or optional domain context, never synthetic semantic ownership. Model-facing writes use expected-revision compare-and-swap. A stale write fails with the current semantic record/revision and never silently merges. The append-only requirement_revision, plan_semantic_revision, and work_semantic_revision records are immutable history evidence, not independently mutable authorities; Controller storage revisions remain internal persistence concurrency metadata.
+
+Plan semanticContext is the model-facing semantic authority once present. Legacy PlanContract goal/step/lifecycle fields remain migration/execution compatibility data and cannot implicitly rewrite semanticContext. Requirement/source basis revisions are provenance and staleness hints only. Source movement is observed at concrete mutation boundaries and does not make Plan working memory an execution gate. Thin Plan `scopeKey` is descriptive discovery/lineage metadata only, never an ownership mutex; current model-facing replanning revises the same stable Plan id rather than superseding it.
+
+New Work records materialize semanticState from creation. Mechanical Work status, phase, verification, review, delivery, cleanup, provider, recovery, and completion receipts do not rewrite semanticState. Pre-semantic legacy Work may infer an initial semantic state from its historical terminal status until its first semantic revision; that revision materializes the state and ends the fallback. Work resultRefs are model/user-selected references only. Mechanical completion and check receipts are exposed separately.
+
+ResumeContext is a derived read bundle assembled on demand from the latest relevant semantic records plus current source/resource facts, unresolved human requests, active durable handles, and pertinent receipts. It is never persisted as a fourth aggregate, and conversation text or projection caches are never authority.
+
+## Concurrency and migration boundary
+
+Semantic CAS protects authored context. Git/worktree, Process/resource leases, authorization grants, effect identities, and other concrete fences protect the resources they actually own. Verification is Work-bound evidence and is never gated by a Work-wide ControllerSession claim; durable checks are admitted by the Work's declared check set and then fenced by immutable execution identity plus Process Runtime resource claims. A semantic revision must be applied to the latest persisted aggregate inside the same storage transaction so a concurrent mechanical update cannot be overwritten merely because the semantic revision did not change.
+
+The source still contains legacy Requirement waiting/continue, Plan approval/PlanStep/supersession data, Work finalization, and ControllerRound machinery for frozen-client compatibility and historical delivery continuity. These mechanisms are not current model-facing semantic authorities and cannot be consulted as semantic-write gates. `plan_approve` and `plan_accept_step` are compatibility no-ops; Work completion, verification, review, and terminal state never claim, complete, release, or reopen Plan item state. ControllerRound identity may fence the frozen transport/resume envelope but cannot authorize Requirement/Plan/Work semantic writes, and a frozen client may carry that exact authority through the bounded `session_id` compatibility carrier as long as the canonical principal/Work/round comparison still decides the claim.
+
+Plan items are now authored working memory with no execution authority at all. No active path records a Plan item Work link, promotes item status, requires Plan approval/acceptance, or selects a successor from Plan dependencies: Work start/continue/completion read Plan and Plan item references as provenance only, and `plan.step.retry:<workId>` is a read-only compatibility report. Predecessor obligation continuity, Plan-source drift and Plan-finalization no longer gate Plan admission, Revision, Work execution or Requirement completion. Legacy `PlanContract.steps`/status/obligation fields remain migration-readable data; the retired PlanStep execution plane, obligation-continuity enforcement, Plan-bound Work refresh/retirement helpers and the PlanStep progression projector are deleted, and the architecture check forbids reintroducing them.
+
+No Runtime/Recovery release transition is part of this decision.
+
+## Thin capability substrate consolidation (2026-09-24)
+
+### 0. Execution target and host-local command lane (historical 2026-09-26 Slice 2)
+
+**Command entrypoints superseded on 2026-10-15 by `1861b541d`.** The only model-visible general terminal tool is `execute_command`, defaulting to repository/workspace placement with explicit `scope=host` subject to the original `process:exec` Grant. `dry_run=true` replaces separate preview; process lifecycle tools attach to handles. The old `repository_command_execute`, `process_exec`, `work_execute`, `repository_command_preview` and the `local_system` generic command action are no longer public. The bullets below record the historical slice, **not current tool-selection guidance**. Canonical entry and gates: `adapters/mcp/tool-mapping/repository-tools.ts`, `adapters/mcp/server.ts`, `adapters/mcp/toolset-names.ts`, `scripts/check-runtime-architecture.mjs`.
+
+- `ProcessScope` is the canonical Process/Operation storage scope. Repository placement is optional context; the ForgeInstance scope is a sibling partition (`<controllerHome>/instance`) so a non-repository process never needs a synthetic repository identity.
+- The Process Runtime owns an instance-level handle index (`process_handle_index`) recording processId -> target (`forge_instance` | `repository`) -> principal. Attachment resolves its target from the handle, never by scanning repositories or replaying placement inputs.
+- `process_get`/`process_wait`/`process_logs`/`process_cancel` are addressed by `process_id`. An explicit `repo_id` is still accepted and validated against the recorded target.
+- Instance-level handles are principal-bound and ForgeInstance-bound: an opaque handle id locates a record and never authorizes attachment on its own.
+- `process_exec` is the canonical host-local command lane: the target is the serving ForgeInstance, `cwd` is an execution argument, and neither a repository nor a Work is required. It never parses command text to prove path safety; narrow path/repository guarantees remain with typed filesystem/source/git capabilities.
+- Host process execution requires one explicit canonical Grant for `process:exec` whose typed target is the exact ForgeInstance. Missing instance identity, principal, or grant fails closed with no fallback host, container, or checkout.
+- Distinct-by-design from the narrow typed `local_system` plugin lane: `execute_command` is a bounded, target-grant-scoped, typed-argv action whose path operands must stay inside a registered workspace target, while `process_exec` is the deliberately broad raw host capability with no path sandbox and a process handle. Consolidating the two into one owner (or retiring the narrow lane's command action) is an explicit open obligation of this slice, not a settled decision.
+- Already satisfied (reconciled 2026-09-26, source evidence only): a Work-bound repository command defaults cwd to the resolved Work/checkout identity and an authorized explicit cwd outside it is served by the host lane; `git worktree remove` already resolves the owning repository/checkout (`selectTerminalCleanupTarget`) and never selects the removed target checkout as current; `process_get`/`process_wait`/`process_logs`/`process_cancel` resolve by handle with `repo_id` optional.
+- Done — semantic storage identity (Slice 1 remainder): Requirement was already ForgeInstance-scoped (`scope: 'controller'`). Plan is repository-optional: `PlanContract.repoId` (and its revision/summary/input carriers) is optional provenance, `PlanContractStoreLocation` accepts a portable `scopeKey` (`semantic` is the reserved ForgeInstance scope, mirroring the workspace/instance partitions), and `plan_create` with zero enabled repositories creates the Plan in that scope — one repository stays authoritative, several keep the explicit ambiguity error. Plan and Work were already resolvable by stable id across scopes without a repository (`findControlPlaneRecordsByKey`). Work remains repository-bound on purpose: its execution semantics (WorkHandle, leases, checkout/delivery) have no meaning without a target, so its `repoId` is not a fake identity. `rh_status` is now instance-scoped: with zero or several repositories the summary resolves no repository target, reports `repositoryContext: null`, keeps runtime/tool-surface/source-coherence readiness, lists active Plans from the semantic scope, reports Work/handoff sections as unavailable rather than inventing a repository, downgrades `detail_level: detail` to the instance summary (reporting `requestedDetailLevel`), and fails closed with `REPOSITORY_CONTEXT_REQUIRED_FOR_REPAIR`/`..._FOR_DETAIL` only where repository context is genuinely required. `rh_inbox` (legacy Handoff) stays repository-scoped until Slice 7 replaces it with UserRequest.
+- Done — ephemeral workspace scope and typed command target: `workspace_*` is a reserved workspace scope key (`controller-home.ts` `WORKSPACE_SCOPE_PREFIX`/`scopedOperationRoot`). An arbitrary workspace is now a `RepositoryCommandScopeTarget` (`workspaceScopeKey` + root + workspace checkout coordinate) instead of a fabricated `RepositoryRecord`; `resolveEphemeralWorkspaceTarget` no longer builds a repository record. Process/Operation records, lightweight receipts, logs, GC, handle-index targets, command audit, git-command audit, access policy, approval requests, work-handle mirrors and execution leases for a workspace target live in `<controllerHome>/workspaces/<workspaceId>`, and attachment resolves by handle or by the workspace id. Repository and `__controller__` scopes keep their established roots and payload fields byte-for-byte; repository-semantic checks (bound-session mutation, default-branch delivery, work-handle authority, `repositoryGitStatus`) now run only when a repository target exists. Workspace preview/execute payloads report `scopeId` + `workspace` and never a `repoId`. Bounded read-only fallbacks still resolve facts written to the old repository location (process records, lightweight receipts, access policy, approval requests). Residual: `ResolvedExecutionIdentity.repositoryId` still carries the workspace scope key as its required field name, and the controller lock scope key for a workspace is still spelled `{ scope: 'repository', repoId }`; both are naming/typing debt rather than repository identity or repository storage. Repository-semantic behavior for a workspace target (mutation authority, delivery guards) is now explicitly "not applicable" rather than evaluated against a fabricated repository.
+- Open obligation — Grant target matching: exact matching with explicit wildcard only is blocked by `PluginCapabilityAuthorizationGrant.repoId` and `target.identityFingerprint` being optional while plugin queries always normalize `repoId`. Making matching exact requires migrating the stored plugin grants and the query normalization together; tightening only `grant-store.ts` would deny live plugin capabilities.
+- Historical remaining items: generalizing durable Process/result/artifact/evidence stores to domain-handle scope and the instance-scoped recovery *apply* split (its audit record and several repository-repair actions still require RepositoryContext). The earlier `repository_command_execute` facade proposal was retired rather than preserved as another execution layer; the single `execute_command` uses the existing Process Runtime.
+
+### 1. Mode-free capability surface
+- Capabilities (`read`, `search`, `edit`, `command`, `process`, `git`, `workspace`, `browser`, `computer`, `plugin`, `API`, `agent`, `schedule`, `release`, `recovery`) remain domain-shaped public capabilities and compose without mandatory Requirement, Plan, Work, task-size thresholds, or mode tokens.
+- Shared invocation conventions are deliberately small: principal/target, typed arguments, optional expected revision, timeout/cancellation, idempotency token, and result or typed handle.
+- A direct task may acquire Work durability later by attaching existing semantic refs/handles/receipts without replaying prior effects.
+
+### 2. Mechanical authority consolidation
+- Canonical `Grant` is the single authorization fact for principal + capability/action set + target/resource scope + constraints + expiry/revocation. Plugin authorization reads/revokes/reconciles canonical Grant first; the old plugin grant JSON is migration seed/compatibility projection only. Repository ID is optional locator metadata, not mandatory scope.
+- `OwnedResource` records Forge-created worktrees/branches and cleanup provenance. Creating/recovering a managed workspace records ownership; cleanup receipts settle that ownership idempotently.
+- Optimistic CAS and native Git/OS conflict semantics are default; short exclusive claims exist only for concrete shared mutable resources (Git refs/index, release promotion, physical input, mutable provider target).
+- Work is not a mutex. ControllerSession/ControllerRound remains only where transport, external-effect, or destructive resource fencing needs an exact mechanical identity; it is not a semantic mutation lock.
+
+### 3. Continuity, schedule, and user requests
+- Open Work is durable context, not an autonomous execution loop instruction.
+- `ScheduleDefinition` (authored trigger, target, policy, action, stop conditions, enabled) is split from `ScheduleRuntimeState` (lastTriggeredAt, consecutiveFailures, nextEligibleAt, occurrences, observation data). Scheduler records triggers, timing, bounded backoff and dispatch facts; internal watcher/provider failures do not manufacture human Handoffs.
+- `UserActionRequest` / `UserDecisionRequest` is the canonical person-only blocker/decision authority and coalesces repeated occurrences by rootCauseKey. Legacy Handoff is written only as a compatibility/UI projection after the UserRequest exists.
+- A Schedule occurrence is continuation input, not a human blocker: semantic/model-owned schedules record trigger, decision and occurrence identity without manufacturing Handoff/UserRequest state.
+- Workflow Supervisor observes outstanding external-turn effects and may reserve one exactly-once provider resume for an applied-but-uncompleted effect. It does not own recursive provider retry depth or Scheduler retry policy.
+
+### 4. Completion vs release/recovery
+- `work_complete` records only the model/user semantic decision and result references. Source integration, git merge, publication, release activation, and resource cleanup are separate capabilities/effects.
+- `finalize`, `verify`, `review`, `controller_claim`, controller disposition/release, and plan approval/step-acceptance are not Work operations. After Runtime/Connector rollover they are rejected rather than translated.
+- Pre-cutover `work_finalize` Worker payloads and review-candidate preparation are hard-rejected as well; a restart cannot replay them. Typed repository execution owns Git effects directly.
+- Periodic cleanup does not treat semantic `completed`/`cancelled` as deletion authorization. A dirty managed worktree is retained in place; cleanup never auto-commits, archives, discards, or force-removes uncommitted bytes merely because Work became terminal.
+- Cleanup debt is derived from owned-resource facts, acts only on resources proven Forge-owned, and is retryable/idempotent independently of Work completion.
+
+### 5. Compatibility surface and projections
+- There is no frozen lifecycle envelope after the cutover. Clients reconnect to the current MCP schema and use explicit semantic CAS operations.
+- Deprecated route/work-mode/operational-plan surfaces are compatibility projections only. They may report concrete continuity/placement needs and available capabilities, but must not prescribe task-size modes, worker choice, validation policy, review lifecycle, or next engineering method.
+- Activity/status/Handoff/legacy PlanStep data are derived or compatibility views. A stale projection is repairable cache debt, never a reason to reject a canonical semantic CAS or concrete resource/effect operation.