@iowarp/clio-coder 0.3.0

package/docs/middleware-and-components.md

@@ -0,0 +1,148 @@
+# 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.3.0).
+
+Clio Coder has two related but separate surfaces:
+
+1. **Components**: deterministic inventory of files that can affect harness behavior.
+2. **Middleware**: an experimental hook/effect contract around tool, turn, and compaction lifecycle points.
+
+The components surface is active and user-facing through `clio-coder components`. The middleware runtime is intentionally conservative in the current alpha: the hook/effect types, validation helpers, declarative rule engine, built-in registrations, and a receipted hook-file surface exist, but arbitrary repository or user middleware packages are not a shipped public extension point. Enforcing guard registrations ride the same hook runtime at the composition root: the loop guard, protected-artifacts guard, dispatch dedup, file and skill observers, tool-prose checks, and finish-contract assessor form the middleware tier of the safety net (see [safety-model.md](safety-model.md)).
+
+---
+
+## Component scanner
+
+Source: `src/domains/components/scan.ts` and `src/domains/components/types.ts`.
+
+The scanner reads files, computes SHA-256 hashes, and emits a stable `ComponentSnapshot`:
+
+```ts
+interface ComponentSnapshot {
+  version: 1;
+  generatedAt: string;
+  root: string;
+  components: HarnessComponent[];
+}
+```
+
+It does not execute scanned files.
+
+### Component kinds
+
+`COMPONENT_KINDS` currently contains:
+
+| Kind | Typical source | Authority |
+| --- | --- | --- |
+| `prompt-fragment` | `src/domains/prompts/fragments/**/*.md` | advisory |
+| `agent-recipe` | `src/domains/agents/builtins/*.md` | advisory |
+| `tool-implementation` | `src/tools/*.ts` | enforcing |
+| `tool-helper` | selected helper files such as `src/tools/registry.ts` | enforcing |
+| `runtime-descriptor` | `src/domains/providers/runtimes/**/*.ts` | runtime-critical |
+| `safety-rule-pack` | `damage-control-rules.yaml` | enforcing |
+| `config-schema` | `src/core/defaults.ts`, `src/core/config.ts` (scanner list in `src/domains/components/scan.ts`) | runtime-critical |
+| `session-schema` | session entry/contract files | runtime-critical |
+| `receipt-schema` | dispatch receipt/integrity files | runtime-critical |
+| `context-file` | `CLIO-CODER.md`, `CONTRIBUTING.md`, `SECURITY.md` | advisory |
+| `doc-spec` | currently `docs/specs/**/*.md` if present | descriptive |
+| `middleware` | reserved kind | enforcing |
+| `memory` | reserved kind | advisory |
+| `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.
+
+### Reload classes
+
+| Reload class | Meaning |
+| --- | --- |
+| `hot` | Can be reread during an active process where supported. |
+| `next-dispatch` | Affects the next fleet worker dispatch. |
+| `restart-required` | Low-level schemas/rules/runtimes should be treated as restart-bound. |
+| `static` | Descriptive specs and suites. |
+
+---
+
+## Component CLI
+
+```bash
+clio-coder components
+clio-coder components --json
+clio-coder components snapshot --out before.json
+clio-coder components diff --from before.json --to after.json
+```
+
+Snapshots are useful in reviews because they show behavior-affecting changes even when the raw diff is broad.
+
+---
+
+## Middleware contract
+
+Source: `src/domains/middleware/types.ts`, `validate.ts`, `budget.ts`, and `runtime.ts`.
+
+Supported hooks:
+
+| Hook ID | Current use |
+| --- | --- |
+| `before_tool` | Guard and annotate a tool call before execution. Rejected or parked attempts still reach loop detection. |
+| `after_tool` | Observe or annotate a completed tool result. File mutation and skill activation observers listen here and cannot change the result. |
+| `turn_start` | Inject visible `<system-reminder>` text into the accepted request. |
+| `turn_end` | Buffer reminders for the next request, including stalled-turn, tool-prose, and finish-contract advisories. |
+| `on_compaction` | Observe compaction events. Effects from this hook are discarded by design. |
+
+Supported effect kinds:
+
+| Effect | Current meaning |
+| --- | --- |
+| `inject_reminder` | Structured reminder payload. |
+| `annotate_tool_result` | Append deterministic annotation to a tool result. |
+| `block_tool` | Hard-block a tool before execution. |
+| `protect_path` | Register a protected artifact path in session state. |
+| `request_continuation` | Ask the chat loop for one bounded automatic continuation. |
+| `require_tool` | Require a specific tool for the next turn. |
+| `lock_tools` | Lock available tools to the current subset. |
+
+Declarative rules run before coded registrations. Scoped registrations match by hook and, for tool hooks, by tool name. Hook failures emit diagnostics and later hooks still run.
+
+Middleware hook budgets are phase-aware through `DEFAULT_MIDDLEWARE_HOOK_BUDGETS_MS`:
+- `before_tool`: 25 ms
+- `after_tool`: 25 ms
+- `turn_start`: 50 ms
+- `turn_end`: 75 ms
+- `on_compaction`: 150 ms
+
+Per-phase budgets can be overridden via `CLIO_CODER_HOOK_BUDGET_<PHASE>_MS` or global `CLIO_CODER_HOOK_BUDGET_MS`. Warmup grace exempts initial calls (`DEFAULT_HOOK_BUDGET_WARMUP_CALLS = 1`), and steady-state warnings trigger when at least 3 of the last 5 post-warmup calls exceed budget (`DEFAULT_HOOK_BUDGET_WINDOW = 5`, `DEFAULT_HOOK_BUDGET_THRESHOLD = 3`). Overruns are reported but do not abort the turn. The orchestrator and workers share the middleware contract, but worker guard state is process-local.
+
+Middleware reminders are visible request text, not hidden prompt state. `turn_start` reminders flush into the same accepted request; `turn_end` reminders flush once on the next request. The built-in stalled-turn rule can request one automatic continuation for a user prompt, then stops rather than looping forever.
+
+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.
+
+---
+
+## Validation helpers
+
+Middleware validators enforce closed fields and known enum values. Minimal valid rule object:
+
+```json
+{
+  "id": "lab.require-validation",
+  "source": "builtin",
+  "description": "Require validation after generated artifact writes.",
+  "enabled": true,
+  "hooks": ["turn_end"],
+  "effectKinds": ["request_continuation"]
+}
+```
+
+Minimal valid effect object examples:
+
+```json
+{ "kind": "block_tool", "reason": "protected path", "severity": "hard-block" }
+```
+
+```json
+{ "kind": "protect_path", "path": "out/checkpoint.nc", "reason": "validated output" }
+```
+
+The current `MiddlewareRuleSource` is only `builtin`. Hook files compile into coded registrations on the same runtime, but they are not custom declarative rule sources and do not grant new tool authority.

package/docs/model-catalog.md

@@ -0,0 +1,189 @@
+# Model Catalog, Runtime Refresh, and Field Notes
+
+> [!TIP]
+> **Interactive Spec Available:** An interactive dashboard mapping capabilities, probe discovery, and target resolution is located at [docs/html/models_blueprint.html](html/models_blueprint.html) (Version: 0.3.0).
+
+Clio Coder treats a selectable model as the intersection of three sources:
+
+1. **Configured targets** in `settings.yaml` (`targets[]`, `defaultModel`, and optional `wireModels`).
+2. **Live runtime probes** (`probe()` / `probeModels()`), which discover models that appeared after Clio started.
+3. **Catalog knowledge** from pi-ai provider catalogs, Clio's bundled local YAML knowledge base under `src/domains/providers/models/**`, and user/project model-catalog overlays.
+
+## Runtime refresh controls
+
+- `/targets`: `r` probes the selected target; `R` probes all targets.
+- `/model` or `/models`: `r` refreshes the selected row's target; `R` refreshes all targets.
+- `clio-coder models`: probes live targets by default before printing the CLI model list. Use `--offline` to skip live probing. Former `--probe` and `--no-probe` flags are gone.
+
+Configured `wireModels` and a target `defaultModel` remain selectable before a
+live catalog is known; Clio labels those rows as `configured` or `default`.
+Once a target returns a live catalog, that catalog is authoritative and models
+the runtime no longer reports stop resolving. Live probe discoveries are labeled
+`live` and carry load-state metadata when the runtime exposes it. This preserves
+operator-curated defaults while still letting runtime discovery take over after
+newly installed local models or newly entitled cloud models appear. Catalog YAML
+entries are loaded when the provider domain is built, so bundled or overlay
+edits require a restart or rebuild before they affect capability and quirk
+matching.
+
+Live provider probes are the preferred source for loaded context and per-model metadata. Clio keeps a 128k local-coding context recommendation, but it no longer treats that recommendation as provider truth for unknown local models: effective context comes from live probe data, an explicit target override, a model catalog/KB entry, or the runtime descriptor default. If the live target is below the recommendation, Clio reports a warning rather than silently inflating the displayed window.
+
+`probeCapabilitiesForModel` is the one exact-id selector. When a router serves several models, capability resolution queries `probeCapabilitiesForModel` to ensure probe data is extracted only from the `/v1/models` row keyed to its own exact wire model ID.
+
+Transient probe failures preserve the last-good catalog, load states,
+capabilities, and notes for the same target identity, but the target health is
+reported as down or unavailable with the probe error as the reason. Worker
+dispatch canonicalizes requested model ids against the live catalog when one is
+available, so a short alias can resolve to the canonical live id before the
+worker spec and receipt are written.
+
+## Benchmarking Models
+
+Model and config benchmark adapters ship under [benchmarks/community/](../benchmarks/community/). These adapters (such as `bench:swe`, `bench:scicode`, and the fleet benchmark `bench:tb`) drive Clio through the CLI or `clio-coder eval`. 
+
+For example, to run the fleet benchmark:
+```sh
+npm run bench:tb -- --limit 3
+```
+
+The benchmarks record context-window, thinking, sampling, weight quantization, and KV-cache settings so sweeps can be compared consistently.
+
+## What "sanctioned" means
+
+A model family is "sanctioned" only when we can say what was tested and under which runtime. It is not a blanket endorsement. For each family, capture:
+
+- exact model id / artifact / quantization;
+- provider or runtime surface (`lmstudio-native`, `ollama-native`, `llamacpp`, `openrouter`, `openai-codex`, etc.);
+- hardware and serving configuration;
+- context window and max output actually exercised;
+- tool-use, reasoning, vision, embeddings/rerank/FIM behavior where relevant;
+- quirks needed by the engine (thinking mechanism, sampling, KV cache);
+- failures and "do not use this route yet" notes.
+
+Engine-visible quirks belong in catalog YAML entries under `quirks.kvCache`, `quirks.sampling`, and `quirks.thinking`. Bundled entries under `src/domains/providers/models/**/*.yaml` are for curated Clio-supported families. User/lab/project experiments should start as overlays before they are promoted into source. Free-form notes can live alongside catalog entries and in this docs area for later cookbooks/blog posts.
+
+## Local catalog overlays
+
+Use model-catalog overlays when a local endpoint needs per-model facts that the
+runtime cannot reliably probe, but the model is not yet ready to become bundled
+Clio catalog knowledge.
+
+Overlay roots are loaded in this order, with later roots winning equally
+specific `matchPatterns`:
+
+1. Bundled Clio catalog: `src/domains/providers/models/**` or packaged `dist/providers-models`.
+2. User overlay: `$CLIO_CODER_CONFIG_DIR/model-catalog.d` or the platform config equivalent.
+3. Project overlay: `.clio-coder/model-catalog.d` under the current working directory.
+4. Extra overlay roots from `CLIO_CODER_MODEL_CATALOG_DIRS`, separated by the platform path delimiter.
+
+Longest matching pattern still wins across all roots. This means a broad project
+overlay such as `qwen` will not replace a more specific bundled entry such as
+`qwen3.6-35b-a3b`; an equal match does replace it. Missing overlay directories
+are ignored, so operators can create them only when needed.
+
+Overlay files are ordinary YAML lists using the same schema as the bundled
+catalog:
+
+```yaml
+- family: ornith-1.0-35b-local
+  matchPatterns:
+    - ornith-1.0-35b
+    - Ornith-1.0-35B-Q4_K_M-262K
+  capabilities:
+    chat: true
+    tools: true
+    toolCallFormat: qwen
+    reasoning: true
+    thinkingFormat: qwen-chat-template
+    structuredOutputs: json-schema
+    vision: false
+    audio: false
+    embeddings: false
+    rerank: false
+    fim: false
+    contextWindow: 262144
+    maxTokens: 65536
+  quirks:
+    sampling:
+      thinking:
+        temperature: 0.6
+        topP: 0.95
+        topK: 20
+    thinking:
+      mechanism: always-on
+      guidance: |
+        The serving endpoint separates Qwen-style thinking into
+        reasoning_content while content contains the final answer.
+```
+
+Use `settings.yaml` `wireModels` for target inventory. Use overlays for
+per-model semantics and quirks. Promote an overlay into the bundled catalog only
+after the model behavior is verified and useful beyond one operator's target.
+
+## Field note template
+
+Use this shape when testing a subscription model, homelab GPU target, research-lab allocation, or new local runtime:
+
+```md
+## <model family or exact model> on <runtime>
+
+- Date:
+- Operator / lab:
+- Runtime target:
+- Provider / endpoint:
+- Hardware:
+- Model id / artifact:
+- Quantization / precision:
+- Context / max output tested:
+- Auth / subscription tier:
+
+### Serving config
+- Command or UI settings:
+- GPU layers / tensor parallel / KV cache:
+- Sampler defaults:
+
+### Smoke tests
+- Tool calling:
+- Reasoning control:
+- Long-context behavior:
+- Vision / embeddings / rerank / FIM:
+- Latency / throughput notes:
+
+### Outcome
+- Status: candidate | verified | limited | avoid
+- Recommended Clio runtime:
+- Required catalog quirks:
+- Known failures:
+- Follow-up benchmarks:
+```
+
+## Reasoning Controls and Thinking Replay Semantics
+
+The Context Engine evaluates thinking mechanisms per model target and manages live reasoning streams. Depending on the runtime capabilities, Clio Coder employs specific thinking replay semantics to ensure chain-of-thought data is preserved or replayed correctly in the conversation history:
+
+- **Ollama Native (`ollama-native`):** Ollama utilizes the native `thinking` field in the request and response payloads. The engine handles Ollama-specific effort levels and streams reasoning increments cleanly through the native thinking channel.
+- **LM Studio Native (`lmstudio-native`):** Because LM Studio does not expose a native reasoning field, the engine replays prior thinking blocks by prepending them to assistant message payloads. These are formatted as a text-prepended part wrapped in `<think>` and `</think>` tags.
+- **OpenAI Completions (`openai-completions`):** The OpenAI-compatible completions provider preserves reasoning blocks within assistant messages. It replays thinking blocks via the `reasoning_content` parameter in the message history, ensuring that the model maintains its chain-of-thought across conversational turns without stripping the data.
+- **Anthropic OAuth / API (`anthropic-max`):** Uses the `anthropic-extended` thinking format. The engine supports Anthropic's native extended thinking block protocol, streaming thinking increments and outputting them wrapped appropriately or natively depending on target capabilities.
+- **Reasoning-Never Models (`thinking.mechanism: none`):** When a model is configured or cataloged with `thinking.mechanism: none`, it is treated as a reasoning-never model. For these models, Clio must not send any thinking fields or parameters in requests, must not replay thinking blocks, must not surface thinking events to the TUI, and must not preserve or log reasoning token usage in metrics.
+
+---
+
+## Subscription Catalog Models
+
+Subscription models are registered and managed as standard HTTP/cloud targets:
+
+- **`openai-codex` (ChatGPT Plus/Pro OAuth):** Maps to catalog-backed Codex model ids surfaced by `clio-coder configure --list` and `clio-coder models` via a browser-minted subscription OAuth token, supporting complete chat, vision, and tool-use capabilities.
+- **`anthropic-max` (Claude Pro/Max OAuth):** Powers chat and workers using catalog-backed Claude model ids surfaced by `clio-coder configure --list` and `clio-coder models`. It relies on pi-ai's `anthropic` OAuth provider. During auth initialization, it alerts the operator to usage-terms caveat via:
+  `Connects with your Claude Pro/Max subscription via OAuth (the same path Claude Code uses). Using subscription credentials outside Anthropic's first-party apps may not align with their terms of service; enable at your own discretion.`
+
+---
+
+## Promotion path
+
+1. Capture raw field notes in docs or a lab notebook.
+2. Add or update a user/project catalog overlay with capabilities and quirks.
+3. Add focused unit/integration coverage when behavior changes engine routing.
+4. Refresh `/models` with `R` and verify the selected row reports the expected source/caps.
+5. Promote the cleaned overlay into the bundled catalog only when the model family is ready to bless for Clio users.
+6. Promote the cleaned field note into a cookbook, guideline, or community blog post.

package/docs/observability.md

@@ -0,0 +1,233 @@
+# Observability Viewer
+
+> [!TIP]
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/observability_blueprint.html](html/observability_blueprint.html) (Version: 0.3.0).
+
+`/view` is the interactive artifact viewer for a Clio session. It keeps the live transcript compact while preserving a full inspection path for durable artifacts.
+
+```text
+/view
+/view <id-or-filter>
+/view verify <runId>
+```
+
+`/view` opens a full-screen split viewer. The left pane groups artifacts by category and supports type-to-filter. The right pane renders the selected artifact with pager controls. `Tab` or `Shift+Tab` switches between the artifact list and details. `Left` and `Right` jump to the previous or next non-empty category from either pane; `Up` and `Down` select artifacts in the list or scroll details in the content pane. Category jumps honor the active filter and wrap at the ends. `v` verifies a selected receipt. `o` shows the absolute backing path through the notice channel when the selected artifact has one; pathless artifacts produce a warning notice instead. In the list pane, `Esc` clears a non-empty filter before a second `Esc` closes the viewer.
+
+---
+
+## The Evidence Spine End-to-End
+
+Clio Coder operates on a single, unified accountability spine that connects in-loop execution diagnostics with durable forensic evidence. The spine operates at two distinct layers:
+
+1. **Live Layer (In-Loop Assessment)**: During a session, the safety domain executes a cheap in-memory scan over the last 80 entries on every `turn_end` hook. It detects validation commands, dispatch receipts, protected artifacts, and requested inspections to check if completion claims are backed by evidence. The live kinds are mapped to the canonical evidence taxonomy.
+2. **Forensic Layer (Post-Completion Aggregator)**: When a run completes, the observability domain aggregates the session ledger, receipts, transcripts, and audit logs into a rich forensic bundle.
+
+```mermaid
+graph TD
+    dispatch[Dispatch Completed/Failed Event] --> obs[Observability Bus Subscriber]
+    obs --> build[Asynchronous buildEvidence]
+    build --> bundle[Write Forensic Bundle to dataDir]
+    build --> index[Append row to evidence-index.json in stateDir]
+    index --> view[Surfaced in /view Accountability Panel]
+```
+
+### Auto-Build on Dispatch Completion
+
+The observability extension subscribes to the `dispatch.completed` and `dispatch.failed` channels via the `SafeEventBus` (in `src/domains/observability/extension.ts`). When a run terminates, the domain initiates the forensic builder without blocking the event bus or TUI rendering.
+
+The builder runs `buildEvidence({ dataDir, stateDir, runId })` to read the state files and compile a detailed bundle under `<dataDir>/evidence/run-<runId>/`. If a headless run is executing, the observability stop hook (`stop()`) flushes all in-flight build promises before the process exits, ensuring no data is lost. Any build failures are swallowed and logged to stderr to prevent compiler or file-lock issues from crashing the main run.
+
+### The Sidecar Index
+
+After building the forensic bundle, the domain appends a metadata row to the sidecar index file located at `<stateDir>/evidence-index.json`. The file is kept as a JSON array acting as a bounded ring (capped at 1000 rows). 
+
+To prevent concurrent Clio processes from corrupting the index, writes are queued within the process and serialize across processes using the shared state-file locking mechanism.
+
+An `EvidenceIndexRow` has the following schema:
+```json
+{
+  "runId": "4f89d2a9c12",
+  "evidenceId": "run-4f89d2a9c12",
+  "tags": ["test-failure", "session-linked"],
+  "firstPassSuccess": false,
+  "findingCount": 2,
+  "generatedAt": "2026-06-25T14:30:00.000Z"
+}
+```
+
+---
+
+## Artifact Categories and Path Layouts
+
+Clio resolves directories under platform-specific XDG defaults (on Linux, these default to `~/.config/clio-coder/`, `~/.local/share/clio-coder/`, and `~/.local/state/clio-coder/`).
+
+| Category | Description | Backing Path |
+| --- | --- | --- |
+| **Accountability** | Rolling first-pass-success rate and failure-cause histogram. | `<stateDir>/evidence-index.json` |
+| **Evidence bundles** | Deterministic run or session overviews, findings, totals, and linked files. | `<dataDir>/evidence/<evidenceId>/` |
+| **Receipts** | Durable run receipts verified by SHA-256 integrity digests. | `<stateDir>/receipts/<runId>.json` |
+| **Dispatch outputs** | Logs and ledger records detailing worker execution. | `<stateDir>/runs.json` and `<stateDir>/receipts/<runId>.json` |
+| **Task ledgers** | Per-turn task-board goals, active runs, and required validation evidence. | `<stateDir>/sessions/<cwdHash>/<sessionId>/current.jsonl` |
+| **Tool outputs** | Offloaded large outputs or execution logs. | `<stateDir>/scratch/<sessionId>/<toolCallId>.txt` |
+| **Protected artifacts** | Validation-protected artifact metadata and its absolute artifact path when available. | Session ledger record plus the protected workspace path |
+| **Compaction** | Summaries of compacted history sessions. | `<stateDir>/sessions/<cwdHash>/<sessionId>/current.jsonl` |
+| **Prompt manifests** | One validated record per prompt compile: `systemPromptHash`, previous hash, token estimate, thinking dial at compile time, per-section token estimates, and per-fragment content hashes. Identifies the exact compiled prompt and supports hash diffs without storing prompt text. Malformed records appear as an explicit read-error artifact. | `<stateDir>/sessions/<cwdHash>/<sessionId>/prompt-manifest.jsonl` |
+| **Safety audit rows** | Current-session safety and permission decisions, with malformed ledger lines surfaced separately. | `<stateDir>/audit/<date>.jsonl` |
+
+---
+
+## The Accountability Panel
+
+The first category in the TUI split viewer is **Accountability**. It reads the sidecar index directly to present a live summary without loading heavy forensic logs.
+
+### First-Pass Success Rate
+A run is marked as a first-pass success when:
+- The terminal dispatch outcome succeeded.
+- The run had zero dispatch retries (attempt 0).
+- The built bundle contains validation evidence, meaning the `no-validation` tag is absent.
+
+The TUI displays this rate as:
+`first-pass success: <succeeded-attempts>/<total-attempts> (<pct>%)`
+
+### Failure-Cause Histogram
+The TUI lists the top failure causes sorted by frequency (descending), then by tag name (ascending). The histogram filters out provenance and quality tags (such as `audit-linked`, `session-linked`, and `no-validation`) and displays only real failure causes:
+- `timeout`
+- `auth-failure`
+- `missing-dependency`
+- `build-failure`
+- `test-failure`
+- `blocked-tool`
+
+---
+
+## Receipt Integrity Verification
+
+Pressing `v` on a selected receipt or running `/view verify <runId>` performs cryptographic integrity checks:
+
+1. **Read Receipt**: Reads the receipt JSON from `<stateDir>/receipts/<runId>.json`.
+2. **Resolve Ledger**: Looks up the run envelope inside `<stateDir>/runs.json`.
+3. **Verify Integrity**: Recomputes the SHA-256 digest over the strict v15 receipt and reconstructible ledger fields. The digest covers every current field, including steering, routing intent and decision, route quality, worker identity, execution role, and result-contract conformance. Every version other than 15 fails verification; there is no historical receipt reader.
+4. **Report Result**: The viewer reports `ok` or the verification failure reason. It does not rename or delete the receipt. Startup orphan recovery may quarantine corrupt orphan receipt files as `<name>.json.corrupt`, but `/view verify` is read-only.
+
+---
+
+## Receipt Fields for Dispatch Provenance
+
+A receipt carries optional provenance and context blocks that answer "what happened" for a chained (pipeline), composed (persona override), escalated, briefed, steered, or external run. Those optional blocks remain absent when unused. Current receipts carry strict integrity v15 and an explicit `outcomeCode: null` when no classified deterministic failure occurred. Automation consumers must treat the optional blocks below as absent by default and `outcomeCode` as nullable; older receipt versions are invalid.
+
+Receipt integrity verification and evidence verification are independent.
+`receipt_integrity=verified/v15/sha256` means Clio called the receipt verifier
+against the ledger envelope; merely finding an embedded digest is not enough.
+`evidence_verification=<verified|unverified|not_applicable|unknown>/<basis>`
+describes validation evidence inside that verified receipt. Likewise,
+`briefing` authenticates parent-supplied dispatch data, while
+`project_context` authenticates the separately rendered bounded project
+message. Model-facing dispatch and collect output name all four concepts
+separately and never substitute one hash for another.
+
+The evidence bundle renders these sets in `transcript.md` (human sentences) and `trace.cleaned.jsonl` (structured run rows), `clio-coder evidence inspect` prints them as a `provenance <runId>:` block, and the `dispatch` tool appends a compact suffix to each run line plus additive keys on `details.runs[]`. A timed-out or denied escalation also raises an `escalation` finding in the bundle.
+
+The base provenance sets, steering, routing, quality, worker identity, and result-conformance coverage all enter in v0.2.9. These fields are labeled `experimental`: their strict v15 shape is frozen for the release, but the labels stay experimental until the schema is promoted post-1.0. For the complete version registry and migration contract across all artifacts, see [artifact-versions.md](artifact-versions.md).
+
+| Field path | Type | When present | Meaning | Status |
+| --- | --- | --- | --- | --- |
+| `pipeline.fromRunId` | `string \| null` | Pipeline step after the first | Run whose final output was threaded in as input data; `null` when the upstream run id is unknown | experimental |
+| `pipeline.position` | `number` | Pipeline step after the first | 1-based index of this step in the chain | experimental |
+| `pipeline.inputBytes` | `number` | Pipeline step after the first | UTF-8 byte length of the threaded upstream text before the 12000-char cap | experimental |
+| `pipeline.inputTruncated` | `boolean` | Pipeline step after the first | `true` when the 12000-char cap clipped the threaded input | experimental |
+| `briefing.bytes` | `number` | A bounded parent briefing was sent | UTF-8 byte count of the exact canonical briefing content | experimental |
+| `briefing.contentHash` | `string` | A bounded parent briefing was sent | SHA-256 of exact canonical briefing content; prose is not copied into the receipt | experimental |
+| `projectContext.tier` | `"none" \| "bounded"` | Current receipts | Effective project-context policy | experimental |
+| `projectContext.chars` | `number` | Bounded project context | Character count of the rendered project-context message | experimental |
+| `projectContext.contentHash` | `string` | Nonempty bounded project context | SHA-256 of the rendered project-context message | experimental |
+| `steering[].sequence` | `number` | A steer was successfully written | Stable 1-based order within the run | experimental |
+| `steering[].bytes` | `number` | A steer was successfully written | UTF-8 bytes of the exact canonical trimmed steer | experimental |
+| `steering[].contentHash` | `string` | A steer was successfully written | SHA-256 of the canonical steer; prose is not persisted | experimental |
+| `steering[].sentAt` | `string` | A steer was successfully written | Write timestamp | experimental |
+| `steering[].acknowledged` | `boolean` | A steer was successfully written | Whether a worker acknowledgement was actually observed | experimental |
+| `steering[].acknowledgedAt` | `string` | Acknowledgement was observed | Acknowledgement timestamp | experimental |
+| `outcomeCode` | five-value stable string union or `null` | Every v15 terminal receipt | Non-null for `vram_capacity_fit_failure`, `worker_tool_call_cap_exhausted`, `loop_guard_tools_disabled_exhausted`, `result_contract_exhausted`, or `worker_final_output_missing`; otherwise `null`. Each non-null code denotes terminal deterministic failure and is incompatible with `outcome: "succeeded"`. Dispatch retry policy consumes this code only, never diagnostic prose. | experimental |
+| `personaOverride.promptHash` | `string` | Ad-hoc specialist whose persona replaced the recipe body | Hash of the composed static prompt; equals `staticCompositionHash` for the run | experimental |
+| `safety.decisions.escalationRequested` | `number` | Run saw at least one permission escalation | Parked permission asks handed to the operator | experimental |
+| `safety.decisions.escalationApproved` | `number` | Run saw at least one permission escalation | Escalations the operator approved | experimental |
+| `safety.decisions.escalationDenied` | `number` | Run saw at least one permission escalation | Escalations the operator denied | experimental |
+| `safety.decisions.escalationTimedOut` | `number` | Run saw at least one permission escalation | Escalations resolved by the timeout fallback (no operator decision) | experimental |
+| `safety.toolTelemetry.coverage` | `"complete" \| "partial" \| "unavailable"` | Current dispatch receipts | Whether Clio can account for the runtime's complete tool start/finish stream | experimental |
+| `safety.toolTelemetry.ingestionErrors` | `number` | Current dispatch receipts | Malformed or lost frames, event-fold/source errors, and drain timeouts that make otherwise mediated telemetry incomplete | experimental |
+| `safety.toolTelemetry.unfinished` | `{ tool, count }[]` | Current dispatch receipts | Tool starts that had no matching finish when the receipt sealed | experimental |
+| `safety.toolTelemetry.workspaceMutationPossible` | `boolean` | Current dispatch receipts | Whether incomplete or unavailable telemetry could conceal a shared-workspace mutation; retry admission fails closed when true | experimental |
+| `autonomyEnforcement.grade` | `string` | Always in v0.3.0 | The autonomy grade level enforced for the run | experimental |
+| `autonomyEnforcement.autonomy` | `string` | Always in v0.3.0 | The effective autonomy level name (e.g. auto-edit, suggest, read-only, full-auto) | experimental |
+| `autonomyEnforcement.externalMode` | `string` | When running external worker | The execution mode of the external worker runtime | experimental |
+| `autonomyEnforcement.dangerousBypass` | `boolean` | When running external worker | Whether a safety bypass was explicitly activated | experimental |
+| `validationGrounding.claimed` | `number` | Validation grounding evaluated | Count of validations claimed by worker | experimental |
+| `validationGrounding.grounded` | `number` | Validation grounding evaluated | Count of claimed validations matched against executed commands | experimental |
+| `validationGrounding.ungrounded` | `string[]` | Validation grounding evaluated | Claim names with no matching execution, stably ordered and bounded | experimental |
+| `validationGrounding.basis` | `"no-command-executed" \| "unmatched-command"` | Validation grounding evaluated | Why the unmatched claims are unmatched. Only `no-command-executed` takes a quality label away | experimental |
+| `capabilityMismatch.verdict` | `"refuse" \| "flag"` | Capability assessment evaluated | Mismatch verdict for agent capability class versus task shape | experimental |
+| `capabilityMismatch.agentId` | `string` | Capability assessment evaluated | Dispatched agent ID | experimental |
+| `capabilityMismatch.capabilityClass` | `string` | Capability assessment evaluated | Admitted agent capability class | experimental |
+| `capabilityMismatch.taskType` | `string` | Capability assessment evaluated | Classified task shape | experimental |
+| `capabilityMismatch.suggestedAgentId` | `string \| null` | Capability assessment evaluated | Installed recipe that can do this work, or null when none is installed | experimental |
+| `capabilityMismatch.detail` | `string` | Capability assessment evaluated | Human-readable explanation of the mismatch | experimental |
+
+Only Clio-owned native/SSH worker wrappers and the Claude SDK path may transport worker-authored outcome events. ACP and black-box subprocess output cannot self-assert an outcome code; Clio may still assign `worker_final_output_missing` at its trusted finalization seam.
+
+The escalation counters appear together and only when `escalationRequested` is present (at least one escalation occurred), so a deny-all or non-escalating run keeps its `safety.decisions` block unchanged.
+
+---
+
+## Worked Example: End-to-End Spine Flow
+
+Here is a step-by-step trace of how a run passes through the spine.
+
+### 1. Dispatch Completion
+A dispatched task to execute tests finishes. The dispatch domain persists the run envelope and the receipt, then emits the completion event:
+```json
+{
+  "runId": "abc1234",
+  "status": "completed",
+  "exitCode": 0,
+  "lineage": { "attempt": 0 }
+}
+```
+
+### 2. Forensic Build
+The observability domain catches the event and triggers `buildAndIndexEvidence`. It generates the overview under `<dataDir>/evidence/run-abc1234/overview.json`:
+```json
+{
+  "version": 1,
+  "evidenceId": "run-abc1234",
+  "source": { "kind": "run", "runId": "abc1234" },
+  "tags": ["session-linked"],
+  "totals": {
+    "toolCalls": 5,
+    "toolErrors": 0
+  }
+}
+```
+
+### 3. Sidecar Append
+Observability maps the result into an index row and writes it to `<stateDir>/evidence-index.json`. Because there was a successful validation tool call, `firstPassSuccess` is `true`:
+```json
+{
+  "runId": "abc1234",
+  "evidenceId": "run-abc1234",
+  "tags": ["session-linked"],
+  "firstPassSuccess": true,
+  "findingCount": 0,
+  "generatedAt": "2026-06-25T14:31:00.000Z"
+}
+```
+
+### 4. Surfacing in /view
+When the operator opens the TUI split viewer `/view`, the Accountability panel reads the index and displays:
+```text
+# Accountability
+
+first-pass success: 1/1 (100%)
+
+## Top failure causes
+
+none
+```