@moretea-labs/forge 1.7.2 → 1.8.1

package/docs/architecture/decisions/20260917-cognitive-memory-foundation.md

@@ -0,0 +1,82 @@
+# Generic Cognitive Plane and associative memory foundation
+
+Status: Accepted and implemented Kernel V2 architecture foundation. Ongoing evolution must preserve the single Cognitive authority, bounded recall, and advisory-only policy boundary.
+
+## Problem
+
+The previous assistant learning loop persisted bounded `ExperienceRecord` and `OutcomeObservation` facts and reused them through lexical context injection. That is useful operational memory, but it is not a general learning substrate: it over-centers error/outcome feedback, stores most meaning as prose, has weak cross-memory association, and makes the model perform too much recall work through context/tool round trips.
+
+Forge needs a domain-independent cognitive substrate that can learn from good examples, successful practice, explicit knowledge, novelty, corrections, contradictions, preferences, principles and procedures as well as failures. It must improve retrieval and information density without creating a second lifecycle/authority system.
+
+## Learning admission is not authority promotion
+
+Forge follows **learn early, trust gradually**. The model decides whether an observation would change future similar judgement/action and therefore deserves advisory memory. Repeated independent evidence may justify stronger confidence or a broader abstraction, but Forge never converts a repetition count, kind, keyword, score or failure frequency into semantic admission/generalization authority.
+
+`LearningSignal.admissionSource` records provenance (`explicit_human`, `controller_observation`, `verified_outcome`, `execution_quality`, or `system_inference`); `kind` is open descriptive vocabulary; `portability` records semantic intent, not policy authority. Project-specific learning normally stays Project-local. When the model explicitly judges a distilled lesson genuinely cross-project, it may author Workspace advisory memory with portable intent regardless of admission-source category. Forge validates reachable scope/provenance/evidence and mechanical resource bounds only; it never auto-promotes a memory.
+
+Confidence and utility are deliberately orthogonal. `confidence` measures evidentiary/semantic strength of the claim. `utility` is the initial retrieval-usefulness prior and may later be adjusted by context usage feedback without changing factual confidence. `salience` is only extraction-time importance. None of these scores grants policy authority.
+
+Cognitive Memory remains advisory. Hard invariants continue to live in normal repository/project authority such as AGENTS, project contracts, architecture decisions, Requirements, Plans, Work acceptance, authorization, and verification gates. Learning never promotes itself into those authorities.
+
+
+## Authority boundary
+
+The Cognitive Plane owns knowledge representation, association, consolidation and model projection. It does **not** own Requirement, Plan, Work, ControllerRound, Scheduler, safety, authorization, acceptance or repository lifecycle decisions. A cognitive record can advise a Controller; it cannot terminalize Work, bypass fencing or mutate hard policy.
+
+Cognitive writes pass through an application `CognitiveWriteAuthorityPort` supplied by trusted composition. Controller-origin writes reuse reachable semantic Work/Requirement/Project/Workspace placement plus evidence checks; ordinary model-authored learning may be carried as optional `cognition_settlement` metadata on the successful MCP tool outcome that closes a meaningful task boundary. The MCP server settles it only after the primary result, so a learning failure cannot turn an already-applied repository/process/external effect into a retry signal. Persistence helpers are not a transport-facing write authority. MCP does not receive a parallel `memory.*` lifecycle.
+
+## Canonical storage
+
+Canonical cognitive metadata stays in the existing Controller SQLite authority. Memory units, evidence references and graph edges use structured tables instead of duplicating whole records into generic JSON payloads. Large immutable content is content-addressed under a SHA-256 CAS and referenced by digest/size/media type.
+
+There is one durable truth. Existing `ExperienceRecord` remains a compatibility authority during migration and is projected transiently into `MemoryUnit` at recall; it is not copied into a second durable cognition row. New generic memories use the cognition store directly through the authority-bearing application service.
+
+Derived concept/term indexes are rebuildable projections. Future vector/ANN, compact adjacency, bitmap, Float16/BLOB or other machine-native indexes follow the same rule: they may accelerate recall but never become a second truth. Corrupt/missing derived indexes are rebuilt from canonical memory.
+
+## Representation
+
+`MemoryUnit` is the high-information-density knowledge atom. It carries stable identity, scope, open facets, concepts, concise canonical text, provenance/evidence, confidence, utility, temporal validity, counter-evidence and a hot/warm/cold tier hint. Facets are descriptive rather than a lifecycle enum, allowing one unit to be both a principle, procedure and successful pattern.
+
+`MemoryEdge` represents explicit relations such as `supports`, `contradicts`, `causes`, `derived_from`, `supersedes` or `analogous_to`. Relation vocabulary is open but validated. `CognitiveIR` is the machine-readable semantic boundary between durable knowledge and model projection; it is not CPU bytecode and does not replace provenance.
+
+`LearningSignal` makes learning trigger-neutral. Kinds such as knowledge, success, failure, novelty, correction, contradiction, pattern, preference, principle and procedure are useful descriptive examples, not a closed taxonomy or admission list. Failure is one possible observation source, not the definition of learning.
+
+## Retrieval and working memory
+
+One bounded associative activation path combines stable-id seeds, exact concepts plus rebuildable lexical parts, lexical candidates, optional configured semantic-provider candidates, graph spreading, scope prior, recency, confidence, utility and usage feedback. All reachable scopes compete in that ranking. Consolidated patterns retain `derived_from` provenance but share one ordinary recall slot with those sources. Multi-cue natural language can qualify long memories without lowering the global cue threshold. No vector semantics are claimed without a configured provider. Candidate, depth, item and byte budgets are mechanical retrieval bounds, never semantic sufficiency thresholds.
+
+The normal Controller hot path receives one compact initial `ActivationPack`; it does not simulate association with repeated MCP `memory.search` calls. The model decides whether that working set is enough. If not, the same `rh_context` surface supports progressive semantic expansion through a narrower query or explicit `knowledge_query`/`knowledge_limit`; routine micro-steps reuse the current set. Legacy Experience is admitted as transient candidates and de-duplicated by scope-qualified memory identity, never by bare id. Model-facing projection stays semantic typed JSON/text because ChatGPT consumes semantics, while machine-native binary/index encodings remain internal.
+
+Scope-qualified identity survives the entire model-facing boundary: activation, AssistantContext item identity, ControllerRound snapshot and usage accounting all use the same scope-qualified memory address, so equal bare ids in different Work/Requirement/Plan/Project scopes cannot collide. Project knowledge is optional enrichment rather than a prerequisite for Cognitive recall; Work/Requirement/Plan memory remains available without a Project binding, while repository/project knowledge sources still require an explicit Project identity.
+
+Temporal validity is part of candidate selection, not merely post-selection filtering. Canonical SQL reads exclude retracted, expired and not-yet-valid memories/edges before bounded `LIMIT` is applied, preventing inactive rows from starving live recall. If canonical memory exists while concept/term projections are missing or structurally corrupt, the cognition persistence owner rebuilds those derived indexes from canonical memory before normal activation proceeds and records the recovery in activation gaps.
+
+## Consolidation and compression
+
+Consolidation compresses **representation**, not semantics or provenance. Related traceable memories may form a warm consolidated representation plus `derived_from` edges, but Forge does not invent a higher-level abstraction or decide a broader scope. Independent repetition is evidence the model may use when distilling/generalizing; there is no fixed repeat threshold for local learning or Workspace generalization. Source memories stay addressable, and original evidence or CAS payload can be expanded when a summary is disputed, stale or insufficient.
+
+Hot/warm/cold are retrieval/retention hints, not three durable authorities. Working memory is intentionally small; long-term storage is not capped to an arbitrary `1000` learned facts. Capacity pressure is handled by compact indexes, CAS de-duplication, consolidation and bounded activation rather than deleting knowledge merely to imitate human forgetting.
+
+### Cross-project promotion
+
+Portable `WorkspaceIdentity` is the existing cross-Project semantic boundary; no `global`/organization memory scope or second policy store is introduced. Project onboarding happens through the normal semantic placement path rather than repository registration. An authored `.forge/project-engineering.json` `projectId` is preferred; a canonical Git remote contributes a portable source fingerprint and becomes the stable Project-id source only when no authored project id exists. Later admissions preserve an existing Project's Workspace and reject source aliases or conflicting ForgeInstance-local placements rather than rebinding. Project-local observations should be distilled into Project lessons. Workspace advisory memory is written only when the model explicitly chooses Workspace scope plus portable intent because the abstraction is genuinely cross-project; this decision may be based on one strong source or many independent observations, but Forge has no automatic promotion formula.
+
+Workspace memory remains advisory learned guidance and acquires no lifecycle, policy or acceptance authority. Forge never turns repeated failures, categories, scores or consolidated clusters into a Workspace lesson or Requirement candidate on its own. If learned knowledge implies a durable product/architecture change, the model/user explicitly enters the existing Requirement/Plan/Work authority. Project product/domain contracts, authored architecture, authorization and verification gates remain higher semantic authority and are never rewritten by learning.
+
+Work-bound learning may be recorded at Controller-round closure but is not Controller lifecycle authority. The same writer is reached by lifecycle-free `learning_record` and one optional cognition-settlement field injected across the entire Controller MCP tool surface, including ordinary repository/edit/process work. Settlement occurs only after a successful primary tool result; settlement failure is surfaced separately so a completed primary effect is never misreported as failed and retried. With a selected reachable Work, Forge server-derives Work/Requirement provenance without fabricating a ControllerRound; otherwise Project/Workspace learning remains lifecycle-free. The active model emits typed semantic deltas, possibly in multiple transport-bounded batches; Forge derives source identity/time, validates scope/provenance/evidence and persists them without deciding their semantic meaning.
+
+## Usage feedback and audit
+
+`assistant_context_usage` is canonical ControllerRound evidence about whether each exact claim-time context item was used or rejected. It does not mutate factual confidence merely because an item was useful or irrelevant. A bounded rebuildable projection feeds future activation: `used` raises retrieval applicability, ordinary rejection lowers applicability, and stale/contradicted rejection contributes an explainable conflict penalty. Confidence changes only through supporting/counter evidence. The projection is scope-qualified, Project-aware, deterministic and idempotent; no second usage truth table is introduced.
+
+`rh_context operation=search` is the read-only Cognitive audit surface. Explicit `knowledge_*` filters can inspect memory by reachable scope, concept, facet, source, source Work or exact memory id and return canonical provenance/confidence/utility/evidence/counter-evidence, relations/supersession, recent usage and query-time activation reasons/path. Knowledge-only audit may run without source-code retrieval; mixed audit never contributes to `ContextClosureReceipt` or mutation readiness. Audit is advisory observation, not write/lifecycle authority.
+
+## Transport and encoding
+
+Internal representation may use SQLite native columns, BLOBs, compact graph structures, vector encodings, bitmaps, varints or other machine-oriented formats when benchmarks justify them. The ChatGPT/MCP boundary remains compact semantic structured data. Base64-wrapped bytecode or machine code is not a model-facing optimization.
+
+The performance target is the complete path: large long-term memory -> bounded local association -> small high-relevance working-memory pack -> one Controller context injection. Serialization micro-optimizations are subordinate to recall quality, round-trip count, latency and context bytes.
+
+## Evolution boundary
+
+This foundation supplies memory and learning primitives, not uncontrolled self-modification. Strategy evolution may use learned recurring patterns, normal Requirement/Plan/Work context, isolated candidates, shadow/canary evidence, and promotion receipts when the model judges them useful. A promotion receipt is a deterministic immutable evaluation attestation, not lifecycle or mutation authority: it is minted only by re-evaluating existing bounded evidence and has no clock-driven state, store, scheduler, policy writer, source writer, Requirement-creation authority, or approval authority. It may be attached to an exact review record as evidence; raw MCP review arguments cannot inject arbitrary trusted architecture evidence. Review, verification, and finalization are optional capability/evidence carriers, never prerequisite authorities for Git delivery or semantic Work completion.

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

@@ -0,0 +1,221 @@
+# 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. `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 terminal cleanup only after evidence retention | 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;
+- 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,72 @@
+# 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 (2026-09-26, Slice 2 partial)
+
+- `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.
+- Still open in this slice: generalizing the durable Process/result/artifact/evidence stores to domain-handle scope, making `repository_command_execute` a translation-only facade over the host lane, and the instance-scoped recovery *apply* split (its audit record and several repository-repair actions still require RepositoryContext).
+
+### 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.