@iowarp/clio-coder 0.4.1 → 0.4.2

package/docs/{context-working-set.md → architecture/context-working-set.md}

@@ -1,11 +1,14 @@
 # Working Set
 
-The working set is the part of the session ledger the model actually receives on the next request. When context pressure crosses `compaction.threshold`, Clio narrows that view before it considers summarizing anything: selected tool-result bodies and closed-turn thinking blocks stop being replayed, and a one-line marker takes each body's place. Nothing is deleted. The ledger keeps every byte the tools produced, the transcript keeps showing them, and the model can ask for any evicted body back by ref.
+> **Visual blueprint:** The source checkout includes the complete
+> [Working Set visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/context_working_set_blueprint.html).
+
+The working set is the part of the session ledger the model actually receives on the next request. When context pressure crosses `context.compaction.threshold`, Clio narrows that view before it considers summarizing anything: selected tool-result bodies and closed-turn thinking blocks stop being replayed, and a one-line marker takes each body's place. Nothing is deleted. The ledger keeps every byte the tools produced, the transcript keeps showing them, and the model can ask for any evicted body back by ref.
 
 Source of truth is `src/domains/context/working-set/` (`contract.ts`, `fold.ts`, `project.ts`, `marker.ts`, `protect.ts`, `engine.ts`, `recall.ts`, `policies/`), the ledger records in `src/domains/session/entries.ts`, and the compaction stage in `src/interactive/turn-context.ts` (`runAutoCompact`).
 
 > [!WARNING]
-> This is an experimental community alpha surface. The default policy is `structural-v1`; `age-horizon` reproduces the selection Clio made before this layer existed and stays available.
+> This is an experimental community alpha surface. The default policy is `structural-v1`; `age-horizon` preserves the old age-based selection except for the current low-yield token floor and stays available.
 
 ## Vocabulary
 
@@ -109,7 +112,7 @@ Rule order is the policy. Each rung emits candidates newest-first, every candida
 
 Rungs 1 through 5 are unconditional: redundant content is free to drop, whatever the pressure. Rung 6 is the only one that looks at token counts, and it stops the moment the projected size reaches `context.workingSet.target × contextWindow`. Newest-first within a rung is a cost decision: evicting the youngest safe unit keeps the cold region after the eviction point small, so the turn that pays for the event pays least.
 
-The long-trace sweep found that targets 0.4 and an exhaustive rung 6 produced identical results because the usable candidate pool ran out first. Relative to the 0.6 default, 0.4 reduced cold-prefix tokens by 2.8% at 64k and 7.3% at 128k, did not reduce summaries, and lowered retention covered by 0.00072 at 128k. The default therefore remains 0.6. The replay README records the full grid and the numeric reopening rule.
+A historical local long-trace sweep found that targets 0.4 and an exhaustive rung 6 produced identical results because the usable candidate pool ran out first. Relative to the 0.6 default, 0.4 reduced cold-prefix tokens by 2.8% at 64k and 7.3% at 128k, did not reduce summaries, and lowered retention covered by 0.00072 at 128k. The default therefore remained 0.6. The generated grid and reopening calculation were local artifacts and are not versioned in this repository; use the replay commands in [Commands and Modes](../guide/commands-and-modes.md#working-set-replay) to measure the current tree.
 
 The facts the rungs read come from `path-index.ts`, one deterministic pass over the active-path entries producing one observation per tool result that names a path: which file, which line range, which paths a listing surfaced, whether the call failed, and where in the turn sequence it sits. Tools that observe no path (dispatch, web fetch, tasks, ask user, context) produce no observation. There are no content fingerprints.
 
@@ -117,13 +120,13 @@ The facts the rungs read come from `path-index.ts`, one deterministic pass over
 
 Recall is explicit and by ref. There is no auto-readmission: the marker tells the model exactly which call brings the body back, and the model decides.
 
-`resolveRecall(entries, view, ref, activeLeafTurnId)` resolves a ref against the fold at the live leaf and returns the original body byte-exact, read with the same field precedence the projection would have used. It fails in three typed ways, and each message names the nearest valid ref when one exists:
+`resolveRecall(entries, view, ref, activeLeafTurnId)` resolves a ref against the fold at the live leaf and returns the original body byte-exact, read with the same field precedence the projection would have used. It fails in three typed ways:
 
 - `invalid_ref` when the ref is empty or carries whitespace.
 - `not_on_active_path` when the session has no such turn on this branch, which includes a ref from a branch `/tree` abandoned.
 - `not_evicted` when the unit is still in context. An assistant turn reports separately that thinking is not recallable.
 
-Both messages end with the refs that can be recalled on the active path (tool results only, up to eight, then a count), because a failed recall is usually a mistyped ref and the listing is what the next call needs.
+The `not_on_active_path` and `not_evicted` messages end with the refs that can be recalled on the active path (tool results only, up to eight, then a count). `invalid_ref` reports only the malformed value. Clio deliberately lists valid refs instead of guessing a nearest ref, because similar time-ordered identifiers can name unrelated results.
 
 An LLM summary also preserves recall discovery across its cut. When an evicted tool result falls before `firstKeptTurnId`, the generated checkpoint carries a `<recallable-refs>` block with the same `ref (tool path)` rows used by recall failures, bounded to eight rows plus a remaining count. Results that stay after the cut keep their ordinary markers and are not repeated in the block.
 
@@ -131,7 +134,7 @@ An LLM summary also preserves recall discovery across its cut. When an evicted t
 
 That also makes recall the churn signal. `churn = recalls / itemsEvicted` over the active path. A high churn number means the policy keeps evicting content the session still needs, which is a reason to change the policy rather than to raise the threshold.
 
-The procedural replay does not synthesize churn from path reuse. Its reference graph maps each earlier observation to every later reread or discovery of the same path, while a real `contextRecall` is an explicit model choice of one ref. A later reread already returns current content at the tail, so also injecting the old body would duplicate data and misread stale or superseded observations as recall demand. Replay reports `recallTokens` as a one-time demand bound per evicted item and waits for explicit `contextRecall` records before reporting recall count, churn, or tail growth. The graph-density measurements and reopening condition are in the replay README.
+The procedural replay does not synthesize churn from path reuse. Its reference graph maps each earlier observation to every later reread or discovery of the same path, while a real `contextRecall` is an explicit model choice of one ref. A later reread already returns current content at the tail, so also injecting the old body would duplicate data and misread stale or superseded observations as recall demand. Replay reports `recallTokens` as a one-time demand bound per evicted item and waits for explicit `contextRecall` records before reporting recall count, churn, or tail growth. Graph-density measurements and reopening calculations are generated local artifacts rather than a versioned replay README.
 
 An offloaded result returns its pointer, never the file. The model gets the same `full: <path>` promise the original tool result ended with and reads it with `read` when it wants it.
 
@@ -164,7 +167,7 @@ context:
 | `context.workingSet.protectLastTurns` | `6` | integer ≥ 1 | Recent turns whose observations and thinking are never evicted. |
 | `context.workingSet.minEvictableTokens` | `200` | integer ≥ 0 | Results below this body estimate are never evicted. The default protects low-yield bodies; marker break-even is enforced separately. |
 
-`compaction.excludeLastTurns` governs only the temporary legacy mask path; working-set protection uses `protectLastTurns`. Settings validation is strict, so an unknown key under this block fails startup with its exact path.
+The retired `compaction.excludeLastTurns` key is not accepted by settings v2. The temporary legacy mask uses a compiled six-turn fallback; working-set protection uses `context.workingSet.protectLastTurns`. Settings validation is strict, so an unknown key under this block fails startup with its exact path.
 
 `CLIO_CODER_LEGACY_MASK=1` restores the destructive stale-observation stage for one release as a compatibility escape hatch. It rewrites the ledger, and it is removed in the next release.
 
@@ -181,14 +184,14 @@ context:
 These are tracked follow-ups, not available behavior:
 
 - **Auto-readmission.** Nothing brings an evicted body back on its own. There are no path fingerprints and no registry of what the model is likely to need next.
-- **Cost model and deferred scheduling.** Pressure is the only trigger, and it is `compaction.threshold`, not `target`. The replay tables price every applied event by the cold prefix it re-prefills (about 29k tokens per event at a 64k budget), and batching from the threshold down to the target is what keeps one event per cycle; a trigger at the target would make every turn above 60% with one newly redundant read an event of its own, and no row in the sweep shows fewer summaries in return. There is no break-even horizon, no deferred eviction plan, and no piggybacking beyond the fact that the working-set stage already runs first inside `runAutoCompact`.
+- **Cost model and deferred scheduling.** Pressure is the only trigger, and it is `context.compaction.threshold`, not `target`. Historical local replay tables priced every applied event by the cold prefix it re-prefilled (about 29k tokens per event at a 64k budget), and batching from the threshold down to the target kept one event per cycle; a trigger at the target would make every turn above 60% with one newly redundant read an event of its own. Those tables are not versioned benchmark results. There is no break-even horizon, no deferred eviction plan, and no piggybacking beyond the fact that the working-set stage already runs first inside `runAutoCompact`.
 - **Intra-turn eviction.** Eviction runs before a request is sent. A single turn whose tool results overflow the window is handled by the observation envelope's caps and by summary compaction, not by this layer.
 - **Worker runtimes.** Dispatched workers replay their own ledgers without the working-set stage.
 - **Digests.** A marker carries tool, size, and a first-line preview. The generated summaries from #165 are not embedded in it.
 
 ## See also
 
-- `clio-coder context replay --sessions <path>...` replays Clio ledgers, and `--synthetic <ids>` replays the seeded procedural corpora, through the same fold, projection, and policy code with `none`, `random`, and `oracle` controls; `clio-coder context working-set --session <id|path>` prints one session's fold and path index. Both are described under [Working-set replay](commands-and-modes.md#working-set-replay). Generated replay tables are local artifacts rather than versioned benchmark results.
+- `clio-coder context replay --sessions <path>...` replays Clio ledgers, and `--synthetic <ids>` replays the seeded procedural corpora, through the same fold, projection, and policy code with `none`, `random`, and `oracle` controls; `clio-coder context working-set --session <id|path>` prints one session's fold and path index. Both are described under [Working-set replay](../guide/commands-and-modes.md#working-set-replay). Generated replay tables are local artifacts rather than versioned benchmark results.
 - [context-engine.md](context-engine.md) for context window resolution, token accounting, and how this stage sits ahead of summary compaction.
 - [session-lifecycle.md](session-lifecycle.md) for the ledger format, active-path lineage, and branching.
-- [glossary.md](glossary.md) for the one-line definitions of these terms.
+- [glossary.md](../guide/glossary.md) for the one-line definitions of these terms.

package/docs/{dispatch-architecture-rationale.md → architecture/dispatch-architecture-rationale.md}

@@ -1,12 +1,15 @@
 # Dispatch Architecture Rationale
 
+> **Visual blueprint:** The source checkout includes the complete
+> [Dispatch Architecture Rationale visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/dispatch_rationale_blueprint.html).
+
 Why `src/domains/dispatch/` is one domain, why one import out of it looks
 irregular and is allowed to, and why the repository has no barrel-only import
 convention. No code moved as a result of this document. It exists so that a
 later split is argued from invariants rather than from file counts.
 
-Counts verified against the current tree: 65 TypeScript files in
-`src/domains/dispatch/`, a 137-line barrel at `src/domains/dispatch/index.ts`,
+Counts verified against the current tree: 85 TypeScript files in
+`src/domains/dispatch/`, a 199-line barrel at `src/domains/dispatch/index.ts`,
 and one dispatch → eval import.
 
 ---
@@ -28,7 +31,7 @@ split would use. They cross them.
 | Write-boundary attribution is per scheduling *window*, so the compiler refuses a wave with two writers | scheduling, write boundaries, plan compilation | `execution-plan.ts`, `write-boundary.ts` |
 | A loop's later nodes are `unneeded`, decided by the scheduler, not the plan | plan compilation, scheduling, receipts | `fleet-plan.ts`, `execution-scheduler.ts` |
 | Staleness revalidation re-runs a verification a later workspace step invalidated | scheduling, plan compilation, code steps | `execution-scheduler.ts` |
-| Receipt integrity v16 seals normalized routing intent | routing, receipts | `receipt-integrity.ts`, `routing-intent.ts` |
+| Receipt integrity v20 seals normalized routing intent | routing, receipts | `receipt-integrity.ts`, `routing-intent.ts` |
 
 The write-boundary and loop rows are the sharpest. Both are properties of a
 *wave*, which is a scheduling concept computed by the plan compiler and enforced
@@ -80,7 +83,7 @@ outward, because that is the one seam the invariants above actually respect.
 `../eval/artifacts/store.js`. The eval barrel does not export it. This is the
 only dispatch → eval import in the domain.
 
-This is coupling worth recording, not a violation. It breaks none of the five
+This is coupling worth recording, not a violation. It breaks none of the six
 enforced boundary rules, and the direction is defensible: the routing quality
 reducer treats an eval artifact as evidence, so it must parse one, and
 `parseEvalArtifactV4` is the strict fail-closed parser rather than a convenience
@@ -104,10 +107,10 @@ The evidence that decides it:
 
 - Measured across `src/domains/**`, counting an import as cross-domain when the
   importing file and the resolved target sit in different `src/domains/<name>`
-  directories: **110** cross-domain subpath imports against **29** cross-domain
-  barrel imports. Direct subpath import is the majority pattern by roughly four
+  directories: **228** cross-domain subpath imports against **41** cross-domain
+  barrel imports. Direct subpath import is the majority pattern by roughly six
   to one, not an exception to a rule.
-- All five enforced boundary rules
+- All six enforced boundary rules
   (`tests/boundaries/check-boundaries.ts`) constrain dependency **direction**:
   who may depend on whom. Not one constrains import **form**. There is no rule
   to be half-consistent with.
@@ -116,11 +119,11 @@ The evidence that decides it:
   it. A barrel-only rule would have to widen the agents barrel for no reason but
   import style.
 
-A barrel-only sixth rule would require widening many barrels to re-export
+A barrel-only seventh rule would require widening many barrels to re-export
 symbols currently reached directly. Every one of those is a public-surface
 addition justified by nothing but import style, and it would rewrite every
 affected import site for no behavioral gain. A boundary rule should protect an
 invariant. "Always import through the barrel" protects a preference.
 
-What is *not* permitted is anything the five direction rules forbid, and those
+What is *not* permitted is anything the six direction rules forbid, and those
 stay enforced by the boundary checker that `npm run lint` runs.

package/docs/{dispatch-typed-intent.md → architecture/dispatch-typed-intent.md}

@@ -1,5 +1,8 @@
 # Typed Dispatch Intent: Migration and Refusal Policy
 
+> **Visual blueprint:** The source checkout includes the complete
+> [Typed Dispatch Intent: Migration and Refusal Policy visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/dispatch_typed_intent_blueprint.html).
+
 Typed dispatch intent is the structured declaration of what a dispatched worker
 may read, may write, is expected to produce, and must verify. It replaces the
 practice of reconstructing that answer from optional `writeRoots` plus path-like
@@ -11,8 +14,8 @@ omitted, partial, versioned differently, or contradictory, lists the stable
 reason codes an operator or integrator can branch on, and states the measurable
 condition under which the legacy inference fallback may be proposed for removal.
 
-Related pages: [tool-usage.md](tool-usage.md) for the `dispatch` tool arguments,
-[fleet-dispatch.md](fleet-dispatch.md) for fleet contracts,
+Related pages: [tool-usage.md](../guide/tool-usage.md) for the `dispatch` tool arguments,
+[fleet-dispatch.md](../guide/fleet-dispatch.md) for fleet contracts,
 [artifact-versions.md](artifact-versions.md) for the serialization registry, and
 [safety-model.md](safety-model.md) for how a resolved write boundary is enforced.
 
@@ -25,21 +28,30 @@ Related pages: [tool-usage.md](tool-usage.md) for the `dispatch` tool arguments,
   "intent": {
     "read_roots":     ["src/domains/dispatch/"],
     "write_roots":    ["src/domains/dispatch/", "tests/contracts/"],
-    "relevant_paths": ["docs/dispatch-typed-intent.md"],
+    "relevant_paths": ["docs/architecture/dispatch-typed-intent.md"],
     "expected_outputs": ["src/domains/dispatch/intent-compatibility.ts"],
     "verification":   [{ "check": "typecheck" }, { "check": "lint", "timeout_ms": 60000 }]
   }
 }
 ```
 
-Every path is a repository-relative POSIX path under the boundary grammar in
-`src/core/path-boundary.ts`. A trailing `/` means the subtree; no trailing `/`
-means that exact file. Absolute paths, `..`, `.` segments, backslashes, and
-globs are refused rather than interpreted. Each list is normalized,
-deduplicated, and sorted by code point, holds at most 32 entries, and each entry
-is at most 512 UTF-8 bytes. `verification` holds at most 8 entries and every
+The three scope fields, `read_roots`, `write_roots`, and `relevant_paths`, use
+the repository-relative POSIX boundary grammar in `src/core/path-boundary.ts`.
+A trailing `/` means the subtree; no trailing `/` means that exact file.
+Absolute paths, `..` segments, interior `.` segments, backslashes, and globs
+are refused in those fields. An entry that is exactly `.` or `./` is accepted
+as the repository root and normalizes out of the list. Expected outputs use a
+separate normalizer: it rejects absolute paths, backslashes, root escapes, and
+an empty normalized path, but it normalizes interior `.` and repeated `/`
+segments and does not interpret or reject glob characters. Each list is
+normalized, deduplicated, and sorted by
+code point, holds at most 32 entries, and each entry is at most 512 UTF-8 bytes.
+`verification` holds at most 8 entries and every
 `check` is a declared id resolved from package scripts or
-`.clio-coder/verifiers.yaml`, never a shell command.
+`.clio-coder/verifiers.yaml`, never a shell command. The one exception is
+`{ "check": "none" }`, which models write to mean "no verification"; it
+normalizes to an empty list instead of costing a refused round unless the
+workspace actually declares a verifier whose id is `none`.
 
 Normalization is in `src/domains/dispatch/intent.ts`. The normalized object
 carries `version: 2` and a `pathProvenance` array binding every policy-bearing
@@ -56,7 +68,7 @@ Each rule resolves to exactly one of three decisions.
 | Decision | Meaning | Where it surfaces |
 | :--- | :--- | :--- |
 | **accept** | The request is unambiguous. | Nothing is reported. |
-| **warn** | The request is compatible, but its policy-bearing scope rests on something weaker than a declaration. The dispatch runs with the authority it would have had anyway. | The approval artifact renders the full resolved scope before a supervised dispatch runs; `pathScope` is sealed on the receipt. |
+| **warn** | The request is compatible, but the classifier identified a weaker declaration or a scope-replacement tradeoff. The dispatch runs with the authority it would have had anyway. | Current admission publishes the typed-scope replacement warning. Legacy provenance still appears in the approval artifact and sealed `pathScope`; the absent-intent and missing-verification classifier findings are not emitted as standalone warnings. |
 | **refuse** | The request states two incompatible things about authority, or states one this build cannot interpret. | Terminal admission error carrying the reason code. The dispatch never runs. |
 
 The invariant that separates `warn` from `refuse`: **a warning is never the
@@ -67,7 +79,7 @@ touch, the answer is a refusal, never the union of the two.
 
 ### 2.1 Omitted intent
 
-Accepted, with a warning. Policy-bearing scope is resolved by
+Accepted without a standalone runtime warning. Policy-bearing scope is resolved by
 `legacyPathScope()`: legacy `writeRoots` become the write boundary with
 provenance `derived`, and path-like tokens in the task (confidence `medium`) and
 briefing (confidence `low`) become working-context paths with provenance
@@ -77,7 +89,10 @@ Inferred paths select project rules and compile worker context. They never
 become write boundaries and never add a verification requirement. The only path
 into a write boundary without a declaration is the explicit legacy `writeRoots`
 field, which the caller had to set on purpose. This is what makes omission a
-warning rather than a refusal: nothing about it can widen authority.
+compatible rather than a refusal: nothing about it can widen authority. The pure
+compatibility classifier can return `intent_absent_legacy_inference`, but the
+production dispatch path deliberately treats omitted intent as ordinary. The
+approval artifact and receipt provenance remain the operator-visible record.
 
 An absolute or malformed path token in prose is not silently dropped. It throws
 `DispatchPathScopeInferenceError` with code `legacy_scope_path_absolute` or
@@ -90,13 +105,15 @@ Accepted. Every field is independently optional and an omitted list normalizes
 to empty. A declaration is not required to be complete to be authoritative:
 declaring only `write_roots` is a complete statement about write scope.
 
-One partial shape gets a warning. Intent that declares `write_roots` or
+The pure classifier identifies one partial shape as a warning. Intent that declares `write_roots` or
 `expected_outputs` but no `verification` describes work that changes the tree
 with nothing the orchestrator itself runs to prove the change is sound
-(`intent_partial_verification_absent`).
+(`intent_partial_verification_absent`). Current production admission keeps only
+terminal refusals from this classifier, so it does not emit that finding as an
+operator diagnostic.
 
-One partial shape is refused. An `expected_outputs` entry outside every declared
-`write_root` (`intent_outputs_outside_write_roots`) means the write boundary
+One partial shape is refused when both lists are non-empty. An `expected_outputs`
+entry outside every declared `write_root` (`intent_outputs_outside_write_roots`) means the write boundary
 would block exactly the artifact the task is required to produce. Refusing that
 at admission costs a rejected call; accepting it costs a full worker run that
 cannot succeed.
@@ -119,8 +136,9 @@ is the same: restate the fields on a fresh dispatch call.
 
 Refused. Three contradictions are enumerated.
 
-- **Legacy against declared write scope.** `writeRoots` and `intent.write_roots`
-  resolving to different trees is `intent_write_roots_contradiction`. Neither the
+- **Legacy against declared write scope.** When both lists are non-empty,
+  `writeRoots` and `intent.write_roots` resolving to different trees is
+  `intent_write_roots_contradiction`. Neither the
   union nor the legacy field wins; the caller drops `writeRoots` and declares
   once.
 - **Narrowed against enclosing scope.** A per-task intent in a batch, or any
@@ -135,19 +153,20 @@ Refused. Three contradictions are enumerated.
 
 The declared-versus-inferred case is not a contradiction and is not refused.
 When a request declares intent, prose inference stops resolving scope entirely;
-paths mentioned only in prose are reported as omitted through
-`typed_scope_replaced_inferred_paths` and take no part in rule selection or
-authority. Declared always outranks inferred.
+paths mentioned only in prose take no part in rule selection or authority.
+`typed_scope_replaced_inferred_paths` reports the useful subset that looks like
+a source or documentation path, or ends in a directory separator, capped at 12
+entries for the transcript. Declared always outranks inferred.
 
 ---
 
 ## 3. Producer Compatibility Table
 
 Every producer that can reach a worker passes through `validateJobSpec()` in
-`src/domains/dispatch/validation.ts`, which is where the classifier runs. The
-rules above therefore hold for every row below, including the rows that cannot
-declare intent yet: those rows resolve scope by inference and are refused only
-when they state a contradiction.
+`src/domains/dispatch/validation.ts`. When an `intent` property is present, that
+validator runs the classifier and retains its terminal refusals. Requests with
+no intent skip compatibility classification and resolve scope through the legacy
+inference path, whose malformed-path errors remain terminal.
 
 | Dispatch producer | Source | Typed intent | Behavior without declaration | Refuses on |
 | :--- | :--- | :--- | :--- | :--- |
@@ -155,13 +174,13 @@ when they state a contradiction.
 | **`dispatch` tool, batch `tasks[]`** | `src/tools/dispatch-arguments.ts` | Declared per task, shallow-merged over the top-level default | Same as singular, per task | All codes, plus `intent_scope_widening` against the top-level ceiling |
 | **`dispatch` modes parallel / sequential / pipeline / detached** | `src/tools/dispatch-admission.ts` | Inherited unchanged from the task that declared it | Legacy inference | All codes |
 | **`dispatch` mode compete, candidates** | `src/tools/dispatch-admission.ts` | Inherited unchanged from the single base task | Legacy inference | All codes. `verification` is refused for the mode (`verification_unsupported_for_mode`) |
-| **`dispatch` mode compete, judge** | `src/tools/dispatch-admission.ts` | None. The judge is a fresh read-only request | Legacy inference over the judge's own task | All codes |
+| **`dispatch` mode compete, judge** | `src/tools/dispatch-admission.ts` | None. The judge is a fresh read-only request | Legacy inference over the judge's own task | Legacy inference errors only |
 | **`dispatch` mode council, members** | `src/tools/dispatch-admission.ts` | Inherited, narrowed to read-only: declared write roots arrive as read roots | Legacy inference | All codes. `verification` is refused for the mode (`council_verification_unsupported`) |
-| **`dispatch` mode council, synthesis judge** | `src/tools/dispatch-admission.ts` | None. Fresh read-only request | Legacy inference over the judge's own task | All codes |
+| **`dispatch` mode council, synthesis judge** | `src/tools/dispatch-admission.ts` | None. Fresh read-only request | Legacy inference over the judge's own task | Legacy inference errors only |
 | **`dispatch` review gate, builder** | `src/tools/dispatch-admission.ts` | Inherited unchanged | Legacy inference | All codes |
-| **`dispatch` review gate, reviewer** | `src/tools/dispatch-admission.ts` | None on the request. `expected_outputs` and `verification` reach the reviewer as rendered *requirements*, never as evidence | Legacy inference over the reviewer's own task | All codes |
+| **`dispatch` review gate, reviewer** | `src/tools/dispatch-admission.ts` | None on the request. `expected_outputs` and `verification` reach the reviewer as rendered *requirements*, never as evidence | Legacy inference over the reviewer's own task | Legacy inference errors only |
 | **`dispatch` `apply_winner`** | `src/tools/dispatch-admission.ts` | Not applicable. Branch application runs no worker | Not applicable | Branch-shape refusals only |
-| **`from_scout` continuation** | `src/tools/dispatch-scout-admission.ts` | **None today.** The compiled continuation plan carries no intent | Legacy inference per step | Contradiction codes only |
+| **`from_scout` continuation** | `src/tools/dispatch-scout-admission.ts` | **None today.** The compiled continuation plan carries no intent | Legacy inference per step | Legacy inference errors only |
 | **Fleet contract agent step (v4+ `writes:`)** | `src/domains/dispatch/fleet-run.ts` | Declared. The contract's `writes:` compiles to `relevant_paths` | Legacy inference for pre-v4 contracts and readonly steps | All codes |
 | **Fleet contract gate / plan step** | `src/domains/dispatch/fleet-run.ts` | Declared, same path (`writes` is the gate path or the plan step's boundary) | Legacy inference when undeclared | All codes |
 | **Fleet delegation-plan spliced step** | `src/domains/dispatch/fleet-run.ts` | Declared from the validated plan task's `writes` | Legacy inference when the task declares none | All codes |
@@ -169,14 +188,14 @@ when they state a contradiction.
 | **ACP delegation target** | `src/domains/dispatch/extension.ts` | Accepted and carried into the plan, but the external agent runs its own tool surface | Legacy inference | All codes, plus a hard refusal of any resolved `writeRoots` on this transport |
 | **Custom agent recipe** | `src/domains/agents/` | Not a producer. A recipe narrows the tool surface and capability class; it never declares dispatch scope | Not applicable | Not applicable |
 | **Extension-authored `DispatchRequest`** | Any `DispatchContract` consumer | Declared, if the extension builds one through `declaredScopeIntent()` or the normalizer | Legacy inference | All codes |
-| **`clio-coder run --agent`** | `src/cli/run.ts` | **None today** | Legacy inference | Contradiction codes only |
-| **`clio-coder wiki generate`** | `src/cli/wiki-generate.ts` | **None today.** Sets legacy `writeRoots` | Legacy inference plus a derived write boundary | Contradiction codes only |
-| **`clio-coder bootstrap generate`** | `src/cli/bootstrap-generate.ts` | **None today** | Legacy inference | Contradiction codes only |
-| **Interactive slash commands, overlays, watchdog** | `src/interactive/` | **None today** | Legacy inference | Contradiction codes only |
+| **`clio-coder run --agent`** | `src/cli/run.ts` | **None today** | Legacy inference | Legacy inference errors only |
+| **`clio-coder wiki generate`** | `src/cli/wiki-generate.ts` | **None today.** Sets legacy `writeRoots` | Legacy inference plus a derived write boundary | Legacy inference errors only |
+| **`clio-coder bootstrap generate`** | `src/cli/bootstrap-generate.ts` | **None today** | Legacy inference | Legacy inference errors only |
+| **Interactive slash commands, overlays, watchdog** | `src/interactive/` | **None today** | Legacy inference | Legacy inference errors only |
 
-"All codes" means every code in section 5 that can apply to the row's shape.
-"Contradiction codes only" means the row cannot declare intent, so only the
-`intent_absent_legacy_inference` warning and the legacy inference errors apply.
+"All codes" means every terminal code in section 5 that can apply to the row's
+shape. "Legacy inference errors only" means the row cannot declare intent, so
+only malformed or absolute prose-path inference can refuse it.
 
 ---
 
@@ -208,8 +227,8 @@ filesystem, no clock, no environment, and no package layout. The supported
 version set is a compiled-in constant, not a lookup. A source checkout, a global
 npm install, and a bundled `dist/` therefore classify identical input
 identically, which is what makes the version policy verifiable rather than
-environmental. `tests/contracts/dispatch-intent-compatibility.test.ts` asserts it
-by classifying the same input from two different working directories.
+environmental. `tests/contracts/dispatch-admission.test.ts` covers the current
+normalization and compatibility boundary.
 
 The one input that is legitimately environmental is the *verification catalog*:
 `check` ids resolve from the project's `package.json` scripts and
@@ -221,16 +240,18 @@ Clio installation. An undeclared id fails closed with
 
 ## 5. Reason Codes
 
-Every code is stable and appears as the prefix of its diagnostic, in the form
-`<code>: <what is wrong and what to do about it>`.
+Active refusal codes are stable and appear as the prefix of their diagnostic, in
+the form `<code>: <what is wrong and what to do about it>`. The table also marks
+classifier-only findings and compatibility identifiers that have no current
+producer.
 
 | Code | Decision | Meaning |
 | :--- | :--- | :--- |
-| `intent_absent_legacy_inference` | warn | No typed intent; scope came from legacy inference. |
-| `intent_partial_verification_absent` | warn | Declares tree-changing work with no verification requirement. |
+| `intent_absent_legacy_inference` | classifier-only warn | No typed intent; scope came from legacy inference. Production admission does not emit it. |
+| `intent_partial_verification_absent` | classifier-only warn | Declares tree-changing work with no verification requirement. Production admission does not emit it. |
 | `typed_scope_replaced_inferred_paths` | warn | Typed intent was declared, so prose-only paths took no part in scope. |
-| `legacy_scope_inferred` | warn | Legacy dispatch resolved policy-bearing scope with no declaration. |
-| `legacy_scope_empty` | warn | Legacy dispatch inferred no policy-bearing path at all. |
+| `legacy_scope_inferred` | retained compatibility id | Accepted by the event projection for older producers; no current source emits it. |
+| `legacy_scope_empty` | retained compatibility id | Accepted by the event projection for older producers; no current source emits it. |
 | `intent_version_unsupported` | refuse | `intent.version` names a version this build does not speak. |
 | `intent_malformed` | refuse | Not a normalized intent for a reason other than its version. |
 | `intent_write_roots_contradiction` | refuse | Legacy `writeRoots` and `intent.write_roots` name different trees. |
@@ -253,7 +274,8 @@ Every code is stable and appears as the prefix of its diagnostic, in the form
 ## 6. Examples
 
 Typed intent is the default for every example below. A call that omits it still
-works; it just resolves its scope from weaker evidence.
+works without a dedicated warning; it resolves its scope from weaker evidence
+recorded in the approval artifact and receipt.
 
 ### 6.1 Main-agent call, single writer
 

package/docs/{evidence-and-memory.md → architecture/evidence-and-memory.md}

@@ -1,9 +1,9 @@
 # Evidence Corpus and Long-Term Memory
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.4.0). Use it to design, validate, and simulate memory proposals, approval loops, pruning rules, and token budgets.
+> **Visual blueprint:** The source checkout includes the complete
+> [Evidence Corpus and Long-Term Memory visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/memory_blueprint.html).
 
-Clio Coder treats run claims and agent lessons as structured artifacts to support reproducibility and scientific provenance. In evaluations such as [SWE-bench](https://www.swebench.com), capturing granular execution evidence is essential for validating agent claims. Evidence corpora are deterministic directories built from run ledgers, receipts, sessions, audits, and eval artifacts. In v0.4.0, forensic evidence auto-builds on dispatch run completion: when a run finalizes, the observability domain automatically compiles the evidence bundle under `<dataDir>/evidence/run-<id>/` and updates a compact sidecar index row in `<stateDir>/evidence-index.json`. Long-term memory records are local, evidence-linked, and only injected after explicit approval. Use the TUI [`/view`](observability.md) command for interactive inspection of receipts, dispatch output, durable tool output, compaction summaries, and session accountability before building or citing evidence.
+Clio Coder treats run claims and agent lessons as structured artifacts to support reproducibility and scientific provenance. In evaluations such as [SWE-bench](https://www.swebench.com), capturing granular execution evidence is essential for validating agent claims. Evidence corpora are deterministic directories built from run ledgers, receipts, sessions, audits, and eval artifacts. Currently, forensic evidence auto-builds on dispatch run completion: when a run finalizes, the observability domain automatically compiles the evidence bundle under `<dataDir>/evidence/run-<id>/` and updates a compact sidecar index row in `<stateDir>/evidence-index.json`. Long-term memory records are local, evidence-linked, and only injected after explicit approval. Use the TUI [`/view`](observability.md) command for interactive inspection of receipts, dispatch output, durable tool output, compaction summaries, and session accountability before building or citing evidence.
 
 Source of truth: `src/domains/evidence/**`, `src/domains/memory/**`, `src/cli/evidence.ts`, and `src/cli/memory.ts`.
 
@@ -15,11 +15,17 @@ Source of truth: `src/domains/evidence/**`, `src/domains/memory/**`, `src/cli/ev
 clio-coder evidence build --run <runId>
 clio-coder evidence build --session <sessionId>
 clio-coder evidence build --eval <evalId>
-clio-coder evidence inspect <evidenceId>
+clio-coder evidence inspect <evidenceId> [--json]
 clio-coder evidence list
+clio-coder evidence inventory --json
 ```
 
-`clio-coder evidence inspect <id>` requires a valid evidence artifact ID. If the requested artifact does not exist on disk, it outputs `error: evidence artifact not found: <id> (see clio-coder evidence list)` and exits with code 1.
+`clio-coder evidence inspect <id>` requires a valid evidence artifact ID. If the requested artifact does not exist on disk, it exits with code 1 and prints the error and remedy on separate lines:
+
+```text
+error: evidence artifact not found: <id>
+  run `clio-coder evidence list` to see local bundles
+```
 
 Evidence IDs are deterministic:
 
@@ -76,7 +82,7 @@ Eval evidence adds `eval-result.json` and uses empty receipt/protected-artifact
 
 Session ledger entries are attributed to a run by the run id the producer stamped on the entry at write time. Rows built from those entries carry that provenance in a `runLink` field (`{ kind, confidence, candidateRunIds? }`) in `tool-events.jsonl` and `protected-artifacts.json`; a write-time stamp is `kind: "entry-run-id"`, `confidence: "exact"`. Entries written without run context fall back to timestamp windowing, labeled `kind: "timestamp-window"`, `confidence: "best-effort"`, and printed as `link=timestamp-window` in the transcript. Concurrent dispatch runs share one clock and their windows overlap, so an entry inside more than one window has no owner the bundle can name. Such an entry is reported in the bundle of every run it may belong to, with `runId: null`, `kind: "ambiguous-timestamp-window"`, and a `candidateRunIds` list, plus a `best-effort-link` finding counting them. It is never dropped and never claimed as exact.
 
-When a run was chained (pipeline), composed with a persona override, or escalated for a permission, `transcript.md` and `trace.cleaned.jsonl` surface the receipt's provenance field sets, and `clio-coder evidence inspect` prints them as a `provenance <runId>:` block. The block is the detail behind the canonical trust projection, never a second reading of it: it is printed only for a run whose seal the projection verified, its `autonomy:` line carries the policy name, external mode, and bypass flag and never the axis word (`mediated`, `approximated`, `bypassed` are the trust summary's to print), and a run whose seal was rejected or retired gets no block at all, so the output never publishes a value the projection reported as `absent`. The field paths, types, and stability labels are documented in the [receipt provenance schema](./observability.md#receipt-fields-for-dispatch-provenance).
+When a run was chained (pipeline), composed with a persona override, or escalated for a permission, `transcript.md` and `trace.cleaned.jsonl` surface the receipt's provenance field sets, and `clio-coder evidence inspect` prints them as a `provenance <runId>:` block. The block is the detail behind the canonical trust projection, never a second reading of it: it is printed only for a run whose seal the projection verified, its `autonomy:` line carries the policy name, external mode, and bypass flag and never the axis word (`mediated`, `approximated`, `bypassed` are the trust summary's to print), and a run whose seal was rejected or retired gets no block at all, so the output never publishes a value the projection reported as `absent`. The field paths, types, and stability labels are documented in the [receipt provenance schema](observability.md#receipt-fields-for-dispatch-provenance).
 
 ### Task and decision provenance
 
@@ -86,7 +92,7 @@ Session evidence retains the two operator-facing bookkeeping ledgers instead of
 
 ## Evidence Tag Taxonomy and Failure Causes
 
-Clio Coder classifies every run, session, and eval record using a closed set of 25 canonical tags. These tags distinguish general execution characteristics (such as lineage linkages) from actual failure causes.
+Clio Coder classifies every run, session, and eval record using a closed set of 29 canonical tags. These tags distinguish general execution characteristics, such as lineage linkages, from actual failure causes.
 
 ### Complete Taxonomy
 
@@ -131,8 +137,8 @@ A subset of the taxonomy represents actual failure causes (governed by the `FAIL
 1. **`timeout`**: Triggered if the run outcome is `"timed_out"` or `"stalled"`, or if the error/failure text contains `"timed out"` or `"timeout"`.
 2. **`auth-failure`**: Triggered if failure text contains keywords like `"auth"`, `"api key"`, `"credential"`, or `"unauthorized"`.
 3. **`missing-dependency`**: Triggered if failure logs contain `"module not found"`, `"missing package"`, or `"missing dependency"`.
-4. **`build-failure`**: Triggered in receipt summaries when a non-zero receipt exit is paired with build tool names in `toolStats` (e.g. `build`, `compile`, `make`, `cmake`, `cargo`, `gradle`, `ninja`, `tsc`). Forensic evidence can also classify a non-zero run from build language in the recorded task text.
-5. **`test-failure`**: Triggered in receipt summaries when a non-zero receipt exit is paired with test or lint tool names in `toolStats` (e.g. `pytest`, `ctest`, `jest`, `vitest`, `test`, `lint`, `typecheck`). Forensic evidence can also classify a non-zero run from validation language in the recorded task text.
+4. **`build-failure`**: Triggered in receipt summaries when a non-zero receipt exit is paired with build tool names in `toolStats` (e.g. `build`, `compile`, `make`, `cmake`, `cargo`, `gradle`, `ninja`, `tsc`). Forensic evidence may also classify it from termination diagnostics in `outcomeDetail` or the recorded failure message. The task text is never causal evidence.
+5. **`test-failure`**: Triggered in receipt summaries when a non-zero receipt exit is paired with test or lint tool names in `toolStats` (e.g. `pytest`, `ctest`, `jest`, `vitest`, `test`, `lint`, `typecheck`). Forensic evidence may also classify it from termination diagnostics in `outcomeDetail` or the recorded failure message. Validation words in the task text are never causal evidence.
 6. **`blocked-tool`**: Triggered if tool execution statistics show a blocked count greater than `0`.
 
 ---
@@ -152,12 +158,13 @@ Each run receipt (persisted under `<stateDir>/receipts/<runId>.json`) carries an
 ### Computation and Lifecycle
 - **Circular Dependency Prevention**: To prevent circular dependencies, `findingsSummary` is calculated **cheaply in-memory** at receipt-record time using the draft envelope and tool statistics (in `src/domains/dispatch/receipt-findings.ts`). It never reads from disk or calls `buildEvidence`.
 - **First-Pass Success**: Calculated as `true` only if the terminal outcome was `"succeeded"`, the lineage attempt was `0` (no dispatch retries), the tool stats confirm at least one successful validation tool was executed, and no failure-cause tags were detected.
-- **Cryptographic Coverage**: Current receipts use strict v19 and authenticate every current receipt field, including briefing and steering provenance, routing intent and decision, route quality, worker identity, execution role, result-contract conformance, council provenance, and fleet gate provenance, against the reconstructed ledger. Every version other than v19 is rejected; there is no historical receipt reader.
+- **Cryptographic Coverage**: Current receipts use strict v20 and authenticate every current receipt field, including dispatch intent path provenance, resolved path scope, briefing and steering provenance, routing intent and decision, route quality, worker identity, execution role, result-contract conformance, council provenance, and fleet gate provenance, against the reconstructed ledger. Only v20 is authenticated as current evidence. Lower versions are reported as retired and are neither migrated nor read as evidence.
 
 | Version | Verification policy | Compatibility policy |
 |---|---|---|
-| v19 | Current canonical projection; every current receipt and reconstructible ledger field is authenticated | Accepted |
-| Any other version | No reader | Rejected; remove or archive the incompatible state rather than expecting migration |
+| v20 | Current canonical projection; every current receipt and reconstructible ledger field is authenticated | Accepted |
+| v1 through v19 | Historical sealed shape unsupported by this build | Reported as retired; not migrated and not read as evidence |
+| Malformed, unversioned, or future version | No current reader | Invalid; archive incompatible state rather than expecting migration |
 
 Receipt integrity and evidence verification answer different questions. The
 former proves that a receipt matches its ledger envelope; the latter records
@@ -234,10 +241,10 @@ prints the tier, summary, and every axis before those diagnostic records, while
 their detailed domain artifacts remain in the receipt, gate, audit, and trace
 files.
 
-The canonical aggregate is an additive projection for downstream work. Receipt
-integrity remains version 18, evidence bundles remain version 1, gate decisions
-remain version 2, and no persisted receipt field or cryptographic algorithm
-changes.
+The canonical aggregate is an additive projection for downstream work. Evidence
+bundles remain version 1 and gate decisions remain version 2. Receipt integrity
+is independently versioned and currently uses v20; that version adds dispatch
+intent path provenance and resolved path scope while retaining SHA-256 sealing.
 
 ### Trust projection
 

package/docs/{middleware-and-components.md → architecture/middleware-and-components.md}

@@ -1,7 +1,7 @@
 # Middleware and Component Registry
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive dashboard with an interactive component scanner and a dynamic hook-and-effect pipeline is located at [docs/html/middleware_blueprint.html](html/middleware_blueprint.html) (Version: 0.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Middleware and Component Registry visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/middleware_blueprint.html).
 
 Clio Coder has two related but separate surfaces:
 
@@ -51,7 +51,10 @@ It does not execute scanned files.
 | `eval-suite` | reserved kind | descriptive |
 
 > [!WARNING]
-> The current scanner still looks for `doc-spec` files under `docs/specs/`. Most public docs now live flat under `docs/*.md`, so public docs may not appear as `doc-spec` components until the scanner is updated.
+> The current scanner still looks for `doc-spec` files under `docs/specs/`.
+> Public reference pages now live under `docs/guide/`, `docs/architecture/`,
+> `docs/process/`, and `docs/history/`, so they do not appear as `doc-spec`
+> components unless the scanner's dedicated root is updated.
 
 ### Reload classes
 
@@ -124,17 +127,20 @@ These ship in every interactive session. Each is one bounded behavior with a vis
 | --- | --- | --- |
 | `nudge.stalled-turn` | `turn_end` | The one declarative rule. A turn that called no tools and ended on an announced action ("Next I will inspect `src/cli/index.ts`") is continued once with a reminder to perform it or say plainly that it is finished. Questions, "let me know", conditional offers ("if you want me to"), and completion statements are not announcements. |
 | `observer.skills-reminder` | `turn_start`, `turn_end` | Once per session, on the first substantive turn, when installed or installable skills exist, injects one line teaching the suggestion protocol: list with `context(scope="skills")`, open the reply with `Suggested skill: /skill <name>` when one matches, then continue the task in the same turn. Only the operator loads a skill. At `turn_end`, a reply that made the suggestion and stopped with only listing calls behind it is continued once (#184): the suggestion is not the task. Greetings do not spend the session's one reminder; a resumed or forked session never gets one. |
+| `observer.marketplace-offer` | `turn_start`, `after_tool` | On coordinator sessions, locally matches a substantive request against undeclined, uninstalled skills in Clio's marketplace and offers each matching skill at most once per session. Ordinary autonomy asks the operator through a tag-bound `ask_user` choice; `Not now` lasts for the session and `Never offer this skill` persists for that skill version. `full-auto` installs the match at project scope without the question. Both consented and autonomous installs pass the Clio-marketplace source gate, and installation never activates the skill; activation remains operator-gated. |
 | `observer.task-board-reminder` | `turn_start` | Once per session, when the operator's text literally enumerates three or more steps (`1)`, `2.`, `step 3:`, or three bulleted lines), injects one line asking for `tasks action="plan"` before the first edit. Prose that merely mentions numbers never counts. |
 | `nudge.open-tasks` | `turn_end` | A settled work turn (one that called tools) that ends while the session task board still has pending or active tasks is continued once with the open list. Pure conversation turns, aborted or errored turns, and boards where every remaining task is blocked do not trigger. |
 | `nudge.detached-dispatch` | `turn_end` | A settled turn that ends while a detached dispatch batch has every run terminal and uncollected is continued once, naming the ready batches; `monitor mode="collect"` clears it, including across resume. Batches with runs still in flight, and surfaces without `monitor`, do not trigger. |
 | `nudge.read-only-exploration` | `after_tool`, `turn_end` | After nine or more read-only calls (`read`, `grep`, `find`, `ls`, `code_nav`, read-only shell) in one user turn without a successful Scout dispatch, injects one advisory to delegate broad reconnaissance to Scout. One advisory per user turn, and only on surfaces that have `dispatch`. |
 | `rail.unbacked-worker-claim` | `after_tool`, `turn_end` | A reply that reports worker or Scout results in a turn with no `dispatch` call gets one warning that the claim is not backed by a receipt. A `[worker result]` note the operator shared is receipt-backed and exempt. No continuation: the operator decides. |
 | `observer.watchdog` | `after_tool`, `turn_end` | Opt-in through `watchdog.enabled` (default off). A turn that changed the tree is reviewed by one read-only `verifier` dispatch briefed with the turn's coalesced diff (per-path last-write-wins, bounded to 12 KiB) and the task board's current scope. Its failed checks become one transcript notice naming the count and the first three; a passing report emits nothing. `watchdog.cadenceToolCalls: N` also fires it every N tool calls inside the turn. One run in flight at a time; an overlapping trigger is dropped and counted. It emits no middleware effects, never continues a turn, and never mutates. Turns with no file mutations, headless runs, and ACP runs never fire it. |
-| `observer.memory-intervention` | `after_tool` | Every `memory.intervention.everyNTools` tool calls, asks a background model for a bounded reflection over the recent window and injects it as a reminder when it arrives. Governed by the `memory.intervention` settings block. |
+| `observer.memory-intervention` | `before_tool`, `after_tool`, `turn_start`, `turn_end`, `on_compaction` | Tracks bounded task memory throughout the turn. Repeated failures and post-compaction knowledge can inject rules-only reminders without a model. Interval, error-streak, and loop triggers queue a detached background reflection at `turn_end`; it uses the configured memory route and can deliver a bounded reminder with the next submitted turn. Governed by the `context.memory` settings block. |
 
 Two coded controls sit beside the registrations rather than among them. `tool-choice-control` turns `require_tool` and `lock_tools` effects into the provider's tool-choice field for the next round: a required tool clears when that tool starts, a lock lasts until the next submitted turn and outranks later requirements. `hook-receipts` is the durable ring (200 entries, throttled to one write per two seconds) of user-defined hook executions that `clio-coder config inspect` reads.
 
-User-defined hook declarations load from three places: `<extensionRoot>/hooks.yaml`, `.clio-coder/hooks.yaml`, and `.clio-coder/hooks.local.yaml`. A hook can be `prompt`, `effect`, or `command`. Command hooks run an argv array without a shell, under the workspace with a timeout and bounded output, and every hook execution emits a receipt.
+User-defined hook declarations load from three places: `<extensionRoot>/hooks.yaml`, `.clio-coder/hooks.yaml`, and `.clio-coder/hooks.local.yaml`. A hook can be `prompt`, `effect`, or `command`. Command hooks run an argv array without a shell, under the workspace with a timeout and bounded output, and every hook execution emits a receipt. Project files are read from disk; extension declarations come from the committed extension snapshot, which captured the `hooks.yaml` bytes during install-digest verification, so a file rewritten after verification is never reopened. A receipt for an extension hook carries the package provenance, the declarations digest, and the extension generation that admitted it.
+
+User hooks are one owned registration set. The extensions domain publishes nothing when it starts. After the guard registrations and before the turn-end assessors, the composition root prepares boot generation 1 and its user hooks, checks that both candidates are current, and publishes their references in adjacent assignment-only calls. `/resources extensions reload` uses the same paired path for later generations. A replacement for an older or equal generation is refused during preparation; after final validation neither publication primitive can refuse or call out. Conflict diagnostics and the reload event run only after both references are live. An owned registration that would take a builtin or host id is dropped with a `registration_conflict` diagnostic; a later host registration with the same id evicts the owned one. Evaluation captures the registration list once per hook occurrence, so an asynchronous phase that started before a reload finishes against the list it started with.
 
 ---