@moretea-labs/forge 1.8.0 → 1.8.1

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/20260907-assistant-learning-loop.md

@@ -4,6 +4,8 @@ Status: Accepted implementation decision; live promotion certification remains r
 
 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.

package/docs/architecture/decisions/20260907-controller-round-transition-policy.md

@@ -210,13 +210,15 @@ The implementation step must add focused failures at least at:
 
 Assertions must cover status, lifecycleStage, `roundCount`, `repeatedStateCount`, provider-failure epoch/history, `authorityId`, `claimGeneration`, provider dispatch/effect receipt identity, duplicate-effect count and durable revision/CAS behavior.
 
-## Real Supervisor acceptance sequence
+## ControllerRound validation Supervisor Work acceptance sequence
 
-Production validation uses the existing Supervisor lineage. It may not manufacture a new Work/Requirement/relay to make the test pass.
+Here, “Supervisor” is the historical name of the existing long-lived **ControllerRound validation Work lineage**. It is not the cross-assistant-turn Workflow Supervisor defined by `20260916-workflow-supervisor-authority.md` and owns no outer WorkflowRun scheduling authority.
+
+Production validation uses that existing ControllerRound validation Work lineage. It may not manufacture a new Work/Requirement/relay to make the test pass.
 
 1. Build and activate one exact candidate Runtime containing the transition policy.
 2. Verify required provider/plugin capability on that installed Runtime before relay mutation.
-3. Re-read the exact existing Supervisor Work, Requirement, relay scope, authority, blocked class, budgets and current record revision.
+3. Re-read the exact existing ControllerRound validation Supervisor Work, Requirement, relay scope, authority, blocked class, budgets and current record revision.
 4. Submit verified provider/environment recovery evidence for the existing `consecutive_failures` block.
 5. Prove the same semantic round is rearmed without changing `roundCount`, `repeatedStateCount`, relay scope or per-round authority, and without erasing historical failure evidence.
 6. Prove provider dispatch occurs at most once and exact Controller claim succeeds.
@@ -252,7 +254,7 @@ Do not:
 - treat Browser/ChatGPT registration as Kernel-specific lifecycle logic,
 - infer successful dispatch from a transport session id,
 - reopen semantic terminal states from stalled recovery,
-- create another Supervisor/relay to avoid the blocked lineage, or
+- create another ControllerRound validation Supervisor Work/relay to avoid the blocked lineage, or
 - keep parallel mutation tables in Scheduler/Launcher/MCP while claiming a central policy exists.
 
 This ADR is the acceptance authority for the r3 ControllerRound recovery-convergence implementation.
@@ -294,3 +296,16 @@ Current outer composition demonstrates why this is necessary:
 ### Completion assertion
 
 A static regression should fail if Scheduler, Launcher, MCP compatibility or provider adapters acquire a new direct ControllerRound status/blocker mutation table or write ControllerRound relay records outside the canonical apply executor. This is an architecture boundary, not a code-style preference.
+
+
+## Workflow Supervisor boundary clarification
+
+ControllerRound transition authority remains lower-layer execution authority. Any provider-observed `controller_turn_settled` event in this ADR is a mechanical liveness fallback for an exact claimed round. It must not be reused as the outer Workflow Supervisor's assistant-message commit event or next-turn scheduling authority. The latter requires the completed `FORGE_WORKFLOW_SUPERVISOR_V1` block, exact END marker, conversation identity and causal submission-effect evidence defined in [`20260916-workflow-supervisor-authority.md`](20260916-workflow-supervisor-authority.md).
+
+## 2026-09-16 amendment: settled Controller turns cannot silently strand nonterminal Work
+
+User-free continuation is a P0 lifecycle invariant. A provider may submit a typed `controller_turn_settled` fact only after the exact assistant turn is observably complete; prompt submission itself is not completion evidence. The provider supplies bounded completion evidence, never a disposition.
+
+The canonical ControllerRound transition policy decides the consequence. If the current round is still `claimed`, its Work is nonterminal, and no explicit stop state exists, the policy records the existing `continue_immediately -> pending_release` lifecycle while preserving round/repeated/failure budgets. If an active control-plane Handoff proves a user decision is required, the same policy closes as `wait_for_user`. If `wait`, `wait_for_user`, `goal_complete`, `blocked`, `failed`, or another already-closed state won the race first, settled-turn replay is idempotent and changes nothing. Terminal Work is retired through the existing terminal-work transition.
+
+This amendment does not create a second Scheduler or semantic Controller. It changes the default for one previously ambiguous state only: **a completed Controller turn may not leave a still-running Work silently claimed merely because the model failed to call the explicit continue helper.** The provider-specific observation and same-conversation dispatch mechanics remain adapter responsibilities, while all durable lifecycle mutation continues through this provider-neutral policy.

package/docs/architecture/decisions/20260916-workflow-supervisor-authority.md

@@ -0,0 +1,249 @@
+# Workflow Supervisor authority above the ChatGPT-turn / Forge execution boundary
+
+Status: **Accepted architecture contract; production Runtime integration implemented, live unattended canary proof remains pending.**
+
+Date: 2026-09-16
+
+## Context
+
+Forge already has durable authorities for repository Work, Controller ownership, ControllerRound transition, Scheduler occurrences, provider recovery, verification evidence, Outcome and Experience. Those authorities are inside the Forge execution/control plane. They can record that more semantic work is required and can prepare or dispatch a lower-layer continuation while the controlling call stack is alive.
+
+That does not solve the outer lifecycle gap for a ChatGPT Web controller. A typical development loop is:
+
+```text
+ChatGPT assistant turn
+  -> calls Forge
+  -> Forge Work / ControllerRound executes
+  -> Forge returns evidence
+  -> ChatGPT reasons over the evidence
+  -> assistant response commits
+  -> original assistant/MCP call stack ends
+  X  no durable authority outside that call stack owns starting the next assistant turn
+```
+
+A ControllerRound continuation record is therefore not, by itself, an assistant-turn scheduler. Likewise, an MCP session, Browser session, Work lease, Schedule occurrence, or conversation binding is not the authority to decide and durably execute the next outer ChatGPT turn.
+
+The missing authority is a **Workflow Supervisor** above the ChatGPT-turn / Forge execution boundary. It is part of Forge's general autonomous-workflow architecture, but it is not another Work, ControllerRound, Scheduler, or MCP lifecycle owner.
+
+## Decision
+
+Introduce one logical `WorkflowRun` supervised by one durable **Workflow Supervisor**. The Supervisor owns only cross-turn continuation of the original Goal. It delegates each semantic turn to ChatGPT and delegates repository execution to Forge.
+
+```text
+Original Goal / logical WorkflowRun
+              |
+              v
+       Workflow Supervisor
+       durable single writer
+              |
+              v
+        ChatGPT assistant turn
+              |
+              v
+       Forge Controller / Work
+              |
+              v
+       repository execution
+```
+
+V1 is a **TypeScript/Bun Supervisor authority co-hosted inside the Canonical Forge Runtime process**. It has its own dedicated Supervisor persistence and Unix socket under the exact configured Controller Home, and only the Supervisor composition opens/writes that database. Authority separation is therefore defined by persistence/protocol/single-writer boundaries, not by inventing a second OS daemon. The existing Canonical Runtime launchd/systemd/portable lifecycle starts and stops Supervisor with the rest of the Runtime. Go or another runtime is reconsidered only if later packaging, restart-recovery or operability evidence proves a material benefit without changing this protocol or authority contract. ChatGPT Web is the first execution target, not the definition of the Supervisor.
+
+### Authority matrix
+
+| Concern | Authority | What it may decide | What it must not decide |
+| --- | --- | --- | --- |
+| 1. Forge Work completion | Forge Work finalization / completion receipt | Whether one Work has satisfied its declared Work contract and delivery gates | Whether the original multi-turn Goal is globally DONE |
+| 2. ControllerRound continuation | Canonical provider-neutral ControllerRound transition policy | Lower-layer round transitions and fenced continuation obligations | Whether a new outer assistant turn should be scheduled after the caller has disappeared |
+| 3. MCP / execution-session recovery | MCP/session/Controller ownership recovery authorities | Rebind transport, recover session/claim, preserve exact lower-layer authority | Goal semantics, outer turn scheduling, or user escalation |
+| 4. ChatGPT assistant-turn commit | Workflow Supervisor completion contract, based on a complete final assistant message | Whether one supervised assistant turn committed a valid completion proposal | Goal acceptance merely because the page stopped generating |
+| 5. Next assistant-turn startup | Workflow Supervisor | Reserve/reconcile and submit one next turn to the exact execution target | Forge Work internals or repository mutation |
+| 6. Long-lived Goal completion | Requirement/Goal semantics plus the WorkflowRun `completionContract` | Validate that a model `DONE` proposal actually satisfies the original Goal and required gates | Treat one Work, patch, test, round or model assertion as sufficient by itself |
+| 7. Stagnation / no-progress detection | Workflow Supervisor using execution-quality / evidence observations | Detect repeated checkpoints, no new evidence, repeated failure/verification/recovery patterns | Rewrite lower-layer verification gates or silently terminate the Goal |
+| 8. Workflow strategy adaptation | Semantic Controller, guided by Supervisor correction policy and Experience/evaluation evidence | Choose a different execution strategy for the same Goal; later evaluate cross-Work candidates | Create a second execution state machine or promote policy without evidence |
+
+The separation is deliberate. A lower layer may report facts upward, but it does not acquire the upper layer's lifecycle authority by exposing more states.
+
+## Logical WorkflowRun contract
+
+The generic upper-layer contract is intentionally small:
+
+```text
+WorkflowRun
+  objective
+  executionTarget
+  completionContract
+  continuationPolicy
+  userBlockerPolicy
+```
+
+`executionTarget` is an adapter identity. Initial support is ChatGPT Web; future targets may include ChatGPT Work, Forge local, Forge Cloud, browser/desktop automation, or another agent runtime.
+
+`completionContract` is a read/validation contract for the original Goal and required evidence. For Forge-backed development Goals it may consult Requirement/Plan/Work receipts and semantic acceptance, but it does not mutate those lower authorities.
+
+`continuationPolicy` defines the fixed enrollment/continuation template, exact target identity, recovery bounds and correction policy. It never accepts model-generated executable `next_prompt` content.
+
+`userBlockerPolicy` validates whether a `NEEDS_USER` proposal is a genuine user-only action, authorization, consent/legal decision, or equivalent blocker with no autonomous recovery path.
+
+### Namespace boundary
+
+Forge already persists `workflow_run` for the declarative Workflow asset interpreter. That record is a checkpoint for executing a versioned Workflow asset; it is not the long-lived autonomous development Goal described here.
+
+V1 Supervisor storage therefore uses a **dedicated Supervisor persistence authority/namespace**. It must not alias or reinterpret the existing declarative `workflow_run` record. Any future convergence requires an explicit migration and authority contract rather than a same-name shortcut.
+
+## Assistant completion proposal protocol
+
+Every supervised ChatGPT turn ends with exactly one machine-readable terminal block at the end of the assistant response:
+
+```text
+<<<FORGE_WORKFLOW_SUPERVISOR_V1>>>
+{
+  "action": "CONTINUE",
+  "conversation_id": "<exact ChatGPT conversation id>",
+  "task_id": "<stable conversation-scoped Supervisor task id>",
+  "supervisor_state": "running",
+  "active_scope": "requirement:<id>",
+  "source_effect_id": "fx_...",
+  "checkpoint": "...",
+  "reason": "...",
+  "evidence": ["..."]
+}
+<<<END_FORGE_WORKFLOW_SUPERVISOR_V1>>>
+```
+
+`action` is exactly one of:
+
+- `CONTINUE`: the original Goal is not complete and autonomous work remains.
+- `DONE`: a terminal **proposal** that requires `completionContract` validation.
+- `NEEDS_USER`: a blocker **proposal** that requires `userBlockerPolicy` validation.
+
+Each newly rendered Supervisor prompt also requires exactly one concise user-visible status line before the control block, derived only from that same action:
+
+- `CONTINUE` → `🔄 仍在执行，无需你操作`
+- `NEEDS_USER` → `⏸ 需要你处理，暂时不要关闭会话`
+- `DONE` → `✅ 已完成，可以关闭此会话`
+
+This is presentation, not lifecycle authority or persisted state. In particular, completion wording is reserved for `DONE`; a model cannot make work complete by printing it, and the existing `completionContract` validation remains authoritative.
+
+The exact `<<<END_FORGE_WORKFLOW_SUPERVISOR_V1>>>` marker is required before the Supervisor accepts the turn as committed. Prompt delivery, `Stop generating`, spinner/loading state, button state, DOM stability, a text-stability timer, Work completion, ControllerRound closure, or transport disconnection are not assistant-turn commit authority.
+
+Every newly rendered Supervisor enrollment or continuation message also carries a machine-readable marker containing its daemon-minted `submission_effect_id` and instructs the assistant to echo exact `conversation_id`, stable `task_id`, `supervisor_state`, and `active_scope` together with `source_effect_id`. `supervisor_state` is redundant by design (`CONTINUE -> running`, `DONE -> done`, `NEEDS_USER -> needs_user`) so each response is independently classifiable. `active_scope` identifies the current durable lower-layer relay authority, normally `requirement:<id>` or `goal:<id>`; it never replaces that authority. The assistant may only echo these immutable/observed identities; it does not mint, rewrite or interpret them as executable prompt authority. A completion is commit-eligible only when `source_effect_id` matches the exact applied outbound effect for the exact task and conversation and the echoed identities match the registered task/scope. Already-reserved pre-upgrade effects remain parse-compatible so a Runtime upgrade does not strand an unknown remote effect.
+
+The Supervisor never executes arbitrary model-provided `next_prompt`. Enrollment, normal continuation, recovery correction and stagnation correction use Supervisor-owned fixed templates. The normal same-conversation continuation is intentionally context-light. It does not repeat the original objective, checkpoint payload, Requirement/Plan/AGENTS text, or lower-layer authority context already present in the conversation. Its semantic instruction is bounded to one coherent safe work wave:
+
+```text
+Continue using the context already present in this same conversation.
+Complete one coherent safe work wave and persist/checkpoint durable progress.
+Use CONTINUE while autonomous work remains; use DONE only after the completion contract is satisfied; use NEEDS_USER only for a genuine user-only blocker.
+Echo the immutable effect/task/conversation/scope identities and end with the FORGE_WORKFLOW_SUPERVISOR_V1 control block.
+```
+
+Enrollment, recovery and correction prompts may include bounded original-objective, checkpoint, validation-result or lower-layer recovery context because those turns are specifically reconstructing durable state. Implementations may localize the wording, but not delegate prompt-chain control back to the assistant.
+
+## DONE and NEEDS_USER validation
+
+A model control block is evidence, not terminal authority.
+
+For `DONE`, the Supervisor validates the configured `completionContract`. A Forge-backed development run must preserve the distinction between Requirement acceptance, Plan/Work delivery, verification/review evidence and outer Goal completion. Missing required evidence causes the `DONE` proposal to be rejected and converted into continuation/correction evidence; it does not lower the gate.
+
+For `NEEDS_USER`, the Supervisor validates `userBlockerPolicy`. Test failures, tool failures, MCP errors, session replacement, provider recovery, implementation failures and ordinary Forge recovery are autonomous failure/recovery facts, not user blockers. A false `NEEDS_USER` proposal is rejected and routed to recovery/correction. Only a validated user-only blocker makes the WorkflowRun quiescent for user action.
+
+## Single writer and event journal
+
+The long-lived Supervisor authority hosted by Canonical Runtime is the **only durable writer** for Supervisor task/run state. Chrome Extension, Native Messaging transport, Forge execution, and lower schedulers submit observations or execute authorized effects; they never independently mutate Supervisor state.
+
+V1 owns a dedicated `supervisor.sqlite` authority under the Forge user-data root instead of reusing `control-plane.sqlite`, generic `control_plane_records`, the declarative `workflow_run` namespace, or a collection of mutable status JSON files. It reuses only the runtime-neutral SQLite mechanics already proven by Forge: Bun/Node driver adaptation, WAL, foreign keys, bounded busy waiting, lifecycle integrity checks, statement finalization and short `BEGIN IMMEDIATE` write transactions.
+
+The core schema keeps the exactly-once invariants relational rather than burying them in opaque JSON payloads. It has explicit task, append-oriented event and outbound-effect facts (`tasks`, `events`, `effects` or schema-equivalent names), with database-level uniqueness for committed completion fingerprints and for the one successor effect derived from a committed completion. Supervisor task identity is stable per exact conversation; Requirement and Work changes advance `active_scope` rather than minting a second outer-turn identity for the same conversation. Bounded discovered-conversation metadata may be persisted in the same Supervisor database so Runtime/browser restarts do not erase project inventory, but discovery rows are observations only and cannot reserve effects or terminalize a task by themselves. Durable journal facts include at least:
+
+- enrollment / turn submission intent;
+- assistant turn committed;
+- continuation effect reserved;
+- external effect observed `applied`, `not_applied`, or `unknown`;
+- completion/blocker proposal validation;
+- recovery/correction decisions;
+- verified terminalization.
+
+Current state is derived from those durable facts. The Canonical Forge Runtime owns the one long-lived process lifecycle and starts the Supervisor server in-process; Supervisor still owns its separate SQLite and Unix-JSONL socket authority. The Chrome Native Messaging host is only a bounded stdin/stdout-to-socket relay; it does not open `supervisor.sqlite`, make continuation/terminal decisions, or become a second writer. Relay processes may reconnect or respawn without changing WorkflowRun identity.
+
+## Exactly-once continuation and external-effect reconciliation
+
+Each supervised outbound turn is assigned a daemon-minted `submission_effect_id`, and the exact fixed outbound message embeds that id in its machine-readable marker. The completion of that turn is causally tied to that applied effect and must echo it as `source_effect_id`. When a stable provider message id is unavailable, the completion fingerprint is derived from:
+
+```text
+task identity
++ exact conversation identity
++ source_effect_id
++ canonical full assistant-response hash
++ control-block hash
+```
+
+This prevents two different turns with identical assistant text from colliding.
+
+For a valid `CONTINUE`, one short SQLite transaction consumes/idempotently records the committed assistant completion and reserves the one successor `submission_effect_id`. Database uniqueness makes duplicate observations converge on the same logical successor effect. The transaction does not claim that the external ChatGPT send committed.
+
+`DONE` and `NEEDS_USER` proposals have a different boundary because their contracts may read Forge or other authoritative evidence. The daemon first journals the proposal idempotently, releases the SQLite write transaction, performs the required read-only completion/blocker validation, then uses another short transaction either to record validated terminalization or to reserve a correction/continuation effect. No SQLite write lock is held across Forge, browser or other external evidence reads.
+
+External send outcome uses the same three-way rule as Forge's non-idempotent effect reconciliation:
+
+- `applied`: the exact effect marker/fixed outbound message is observed in the exact conversation; acknowledge it and never resend.
+- `not_applied`: affirmative preserved-baseline proof establishes that the exact source completion is still the latest committed assistant turn, the latest user message is still the previously applied source/baseline message, and the target `submission_effect_id` marker is absent; only then may retry reuse the same reserved effect identity.
+- `unknown`: any conflicting, newer, partial or otherwise insufficient observation stays reconciliation-only; do not blindly resend.
+
+The crash windows before reservation, after reservation/before send, after send/before acknowledgement, and after acknowledgement must all converge through this journal plus remote observation. Daemon restart, extension reload, Chrome restart, tab close/reopen/discard/freeze, Native Messaging reconnect and Forge/MCP session replacement never create a new original Goal or a second continuation for the same committed completion.
+
+## ChatGPT Web adapter boundary
+
+The Chrome Extension is a discovery/assistant-observation adapter, not a state authority or outbound sender. Native macOS Browser transport is the single sender: it uses trusted input, confirms the composer contains the exact fixed prompt before it clicks Send, and waits for the exact committed user message before recording the effect outcome. It may:
+
+- locate or open only an allowlisted exact conversation id/URL;
+- obtain repository-derived ChatGPT Project scopes from the Supervisor and scan visible project links for canonical `/c/<id>` conversation identities;
+- publish bounded project/conversation discovery observations; the Supervisor alone decides whether an unbound discovered conversation receives one enrollment effect;
+- read the final complete assistant response, its echoed identity/state fields and `source_effect_id`, and forward bounded evidence;
+- rediscover a closed/discarded tab without changing durable task identity.
+
+It must not select durable tasks by mutable title, open the Supervisor database, decide `CONTINUE/DONE/NEEDS_USER`, invent prompts, weaken Forge gates, or depend on private ChatGPT APIs. A repository/project title is only a bounded discovery selector; exact conversation URL/id becomes the stable execution target before any enrollment effect exists. Transient generation UI may help avoid pointless reads but is never commit evidence.
+
+Existing conversations require an explicit enrollment handshake. A conversation may be explicitly bound by a current Work or discovered inside the repository-derived ChatGPT Project scope. In either case the Supervisor persists exact conversation identity and one conversation-stable task, then reserves one fixed enrollment effect. A discovered conversation that has not yet recovered a durable Requirement must use a bootstrap enrollment turn that recovers the original task from conversation history plus Forge durable state and emits the exact `active_scope` before repository mutation. Repeated project scans never reserve a second bootstrap for an already enrolled conversation. A pre-enrollment response without the END marker is never retroactively imported as a committed supervised turn.
+
+## Relationship to existing Forge continuation
+
+The cross-turn dependency described in this section is superseded by [Supervisor turn authority](20261001-supervisor-turn-authority.md): ControllerRound remains initial admission and direct non-ChatGPT provider-effect authority, while enrolled ChatGPT turns use only the Supervisor causal effect ledger. Exact-conversation Supervisor lookup occurs before lower ControllerRound readiness, so an already-enrolled conversation cannot be stranded by a retired lower round. Every nonterminal Supervisor task must retain one mechanically derivable causal obligation; Runtime restart repairs missing enrollment/successor/terminal settlement from the existing ledger rather than adding lifecycle state. Schedule occurrences hand exact trigger identity into ControllerRound; Scheduler-owned continuation-dispatch persistence has been removed. ControllerRound is not the authority that reactivates ChatGPT after the outer assistant call stack is gone, and it is not proof that the long-lived WorkflowRun progressed or completed.
+
+The existing Scheduler remains only an execution/occurrence scheduler. Once an exact Requirement-backed ChatGPT conversation binding exists, lower Scheduler/maintenance/direct-continuation paths must not submit the next outer ChatGPT turn; Workflow Supervisor is the single outer writer.
+
+Standalone Supervisor lifecycle and release-bound live proof are reachable from the six-tool ChatGPT facade as the `controller.workflow_supervisor` core capability on `capability_execute`. Its `start/list/get/stop/proof` actions route into the same `WorkflowSupervisorControlPlane` adapter and dedicated Supervisor persistence. Newly generated autonomous turns carry typed automation metadata on their real Forge calls; the old receipt-only `rh_work repair` carrier is migration-only for already-issued prompts. The retained internal/compatibility `supervisor_task` definition is not a second facade or authority. ReleaseSession keeps Candidate B's isolated Runtime canaries separate from the real external multi-turn proof: after cutover the session remains `soaking` until the exact active release has durable `CONTINUE → CONTINUE → DONE` proof spanning a Runtime reconnect; only then may it become known-good.
+
+No Supervisor state is added to Work, ControllerRound, relay, MCP session or existing declarative Workflow asset records in V1. Integration is through typed observations/read-only completion evidence and authorized execution effects.
+
+## Stagnation and strategy evolution
+
+P0 is cross-turn liveness and correctness: durable Supervisor, exactly-once/restart recovery and real unattended Avela development canaries.
+
+After P0 proof, P1 may consume existing execution-quality and Experience evidence to detect repeated checkpoint/evidence/failure/verification/recovery patterns. First confirmed stagnation injects one fixed root-cause correction while keeping the same original Goal and gates. It does not immediately escalate to the user.
+
+Only after P0/P1 evidence should P2 perform cross-Work strategy comparison, policy candidate trials, evaluation and bounded promotion. Existing Experience/evaluation authorities are reused rather than replaced.
+
+## First P0 canary
+
+The current P0 canary also exercises the Forge ChatGPT Project itself: the adapter must discover the repository-matched project conversations by exact `/c/<id>` identity, persist the inventory across Runtime restart, enroll each unbound nonterminal conversation at most once, and allow each conversation to recover its own durable `active_scope`. The historical Avela three-conversation canary remains valid evidence for exact-conversation isolation; promotion/excluded conversations must remain outside any configured discovery scope.
+
+P0 is not complete when Forge can send one automatic `continue` or merely list browser tabs. It is complete only after a real project/conversation canary demonstrates multi-turn unattended progress with no user continuation messages, correct conversation isolation, no duplicate bootstrap/continuation, restart recovery, technical-failure recovery, MCP-session replacement, validated `DONE`, and validated `NEEDS_USER`, without lowering Forge verification/review/authorization gates.
+
+## Consequences
+
+- Forge gains one missing upper lifecycle authority instead of stretching lower state machines upward.
+- The external protocol remains deliberately smaller than Forge's internal lifecycles.
+- Exactly-once is treated as an external-effect reconciliation problem, not as a SQLite uniqueness problem pretending the network does not exist.
+- ChatGPT remains the semantic reasoner, but model assertions do not bypass durable Goal or blocker evidence.
+- The system can later add execution targets without making Chrome Extension behavior part of the kernel.
+
+
+## Restart-safe remote effect generations
+
+The remote ChatGPT send boundary is recovered from the Supervisor journal, never from browser-local shadow state. Each reserved effect keeps one stable `submission_effect_id`; retries do **not** mint a replacement effect. Instead, every authorized send attempt appends an `effect_dispatch_started` event carrying a monotonically increasing dispatch generation. Generation 1 is allowed before any prior dispatch. A later generation is allowed only when a canonical `effect_not_applied` event was committed after the previous dispatch. `effect_unknown` never authorizes a resend.
+
+`not_applied` is a daemon-validated fact, not a caller assertion. The generic observation RPC may record only `applied` or `unknown`. The browser reconciliation path may commit `effect_not_applied` only when the exact conversation remains on the preserved dispatch baseline, the target effect marker is absent, and, for continuation/correction effects, the latest complete assistant response hashes to the exact source completion while the latest user message is the exact applied source-effect prompt. Any drift, partial response, conflicting message, missing baseline, or other ambiguity is recorded as `unknown` and remains reconciliation-only.
+
+Raw ChatGPT page bodies are ephemeral verifier input. The Supervisor persists bounded hashes and a fixed allowlist of small browser evidence fields, not arbitrary `latest_user_text` or `latest_assistant_response` payloads. This keeps restart evidence durable without turning the event journal into a conversation mirror.
+
+Daemon restart, Native Messaging respawn, extension reload, Chrome tab reopen/discard recovery, and Forge/MCP session replacement therefore reconstruct the same task/effect chain from `supervisor.sqlite`. The relay and extension may disappear and return freely; neither owns retry generations, terminal state, or durable recovery policy. Verified `DONE` and `NEEDS_USER` remain quiescent because terminal tasks expose no browser continuation command.

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.