@iowarp/clio-coder 0.4.3 → 0.4.4

package/docs/architecture/safety-model.md

@@ -97,7 +97,7 @@ Escalation can never hang a run. Every escalated ask resolves by an operator dec
 ## Operating Posture and Visible Tools
 
 Clio operates under a single operating posture. The canonical catalog contains
-21 built-in tools organized in seven planes; each plane is one policy unit for
+24 built-in tools organized in seven planes; each plane is one policy unit for
 action class, size posture, and concurrency, asserted at bootstrap by
 `src/tools/policy.ts` so the classifier and registered specs cannot drift apart
 silently. Dependency wiring, target capability, worker profile, and recipe
@@ -105,17 +105,17 @@ policy determine which subset is visible in a particular context.
 
 | Plane | Tools | Action class |
 | --- | --- | --- |
-| OBSERVE | `read`, `grep`, `find`, `ls`, `code_nav`, `context`, `credential_present` | `read` |
+| OBSERVE | `evidence`, `read`, `grep`, `find`, `ls`, `code_nav`, `context`, `credential_present` | `read` |
 | MUTATE | `write`, `edit` | `write` |
 | EXECUTE | `bash`, `verify` | `execute` |
 | EXECUTE | `git` | `read` |
 | ORCHESTRATE | `dispatch`, `steer` | `dispatch` |
-| ORCHESTRATE | `monitor`, `tasks`, `ledger`, `panes` | `read` |
+| ORCHESTRATE | `monitor`, `tasks`, `ledger`, `panes`, `limitation`, `decide` | `read` |
 | RETRIEVE | `web_fetch` | `read` |
 | INTERACT | `ask_user` | `read` |
 | ARTIFACT | `artifact` | `write` |
 
-`git` is read-only inspection on the safe-exec spine, so it carries the read class despite living in the EXECUTE plane. `monitor` does not mutate a run or the workspace. The model-facing `tasks` tool is an intentional bookkeeping exception to the everyday meaning of "read": board mutations append full `taskLedger` snapshots to Clio's session ledger, and any action may reconcile the project-local `.clio-coder/user-tasks.json` inbox while `pick` and linked `done` update its durable correlation. Those Clio-owned ledger and inbox mutations intentionally remain audited with `actionClass: "read"`, so task planning and pickup stay available at every autonomy level without an approval card. `ledger` reads a worker-local mirror and posts through the dispatch control lane; it registers only for a worker with an agent-ledger port. `panes` controls Clio-owned terminal panes and registers only when a pane host and live mux are available. Both are read class and sequential because their coordination state must not interleave. This classification grants no source-workspace, command-execution, or run-mutation authority; those operations still require their own tools and action classes. `gateway` is a design-reserved name only (see `src/core/tool-names.ts`), not a registered tool.
+`git` is read-only inspection on the safe-exec spine, so it carries the read class despite living in the EXECUTE plane. `monitor` does not mutate a run or the workspace. The model-facing `tasks` tool is an intentional bookkeeping exception to the everyday meaning of "read": board mutations append full `taskLedger` snapshots to Clio's session ledger, and any action may reconcile the project-local `.clio-coder/user-tasks.json` inbox while `pick` and linked `done` update its durable correlation. Those Clio-owned ledger and inbox mutations intentionally remain audited with `actionClass: "read"`, so task planning and pickup stay available at every autonomy level without an approval card. `ledger` reads a worker-local mirror and posts through the dispatch control lane; it registers only for a worker with an agent-ledger port. `panes` controls Clio-owned terminal panes and registers only when a pane host and live mux are available. Both are read class and sequential because their coordination state must not interleave. `evidence` reads canonical evidence bundles, trust status, gate decisions, and findings; it touches no workspace, and it is sequential because `run` mode may materialize a bundle under Clio's data directory. `limitation` records a typed receipt of what a turn could not verify and why; it touches no filesystem and runs no shell, so it is read class and parallel. `decide` appends the model's own design decision, with its rejected alternatives and rationale, to the session decision board; dispatch seals every active decision's ref onto the run envelope and receipt, and commit seams write them as `Clio-Decision:` trailers. It is read class and sequential. This classification grants no source-workspace, command-execution, or run-mutation authority; those operations still require their own tools and action classes. `gateway` is a design-reserved name only (see `src/core/tool-names.ts`), not a registered tool.
 
 Target capability, dispatch tool profiles, and recipe constraints can further narrow the tools available to a run. That narrowing is convenience and budget control; safety still lives in code gates.
 
@@ -263,7 +263,7 @@ Prefer typed tools over Bash:
 - `verify(check="<id>")` runs either a declared package.json verification script (the `test*/lint*/build*/typecheck*/check*/format*/ci*` family) or an exact version-1 `.clio-coder/verifiers.yaml` argv vector through bounded execution helpers with no shell; `verify()` lists both sources through one canonical check projection.
 - `verify(check="frontend", path=...)` validates frontend artifacts without granting arbitrary shell access.
 
-A package-script check and the frontend validator are in the no-prompt set at `auto-edit`: both are bounded by the verification-script family and a fixed argv shape. A project-catalog check is not. The engine resolves the check id against `.clio-coder/verifiers.yaml` on every call and treats the declared argv exactly like a bash command string: the damage-control rules and the zero-access read guard scan it, and it is tagged unrecognized, so `auto-edit` parks it for one confirmation that shows the argv and `full-auto` runs it. `.clio-coder/verifiers.yaml` and `.clio-coder/safety.yaml` are read-only to the model's `write`, `edit`, and bash redirect paths through the default path policy: both files are operator authority, and a model that could author either one could widen its own permissions in two tool calls.
+A package-script check and the frontend validator are in the no-prompt set at `auto-edit`: both are bounded by the verification-script family and a fixed argv shape. A project-catalog check is not. The engine resolves the check id against `.clio-coder/verifiers.yaml` on every call and treats the declared argv exactly like a bash command string: the damage-control rules and the zero-access read guard scan it, and it is tagged unrecognized, so `auto-edit` parks it for one confirmation that shows the argv and `full-auto` runs it. `.clio-coder/verifiers.yaml`, `.clio-coder/safety.yaml`, `.clio-coder/skills/`, and the user-scoped `<configDir>/skills/` are read-only to the model's `write`, `edit`, and bash redirect paths through the default path policy: these files and skill roots are operator authority, and a model that could author them could change its own permissions or active instructions. Skill installs go through `clio-coder skills install`.
 
 The project verifier catalog is an executable authority supplied by the repository, not by model prose. Its schema rejects unknown fields, shell strings, invalid or duplicate IDs, oversized values, absolute or escaping working directories, unsupported versions, and collisions with package-provider IDs. It also refuses the common shell executables (`sh`, `bash`, `zsh`, and the like) as argv[0], which is a tripwire against the obvious mistake rather than a sandbox: `python3 -c`, `node -e`, and `env bash -c` pass the schema, so the authority boundary is the fact that the catalog file is operator-owned and read-only to the model, and that every catalog check is scanned by the damage-control rules and parked at `auto-edit`. A catalog entry fixes argv, repository-relative cwd, and timeout. Tool-call `args`, `cwd`, timeout, output-cap, or environment-shaped fields cannot widen it. Safe-exec uses `spawn` without a shell, filters the child environment to the Clio allowlist, honors cancellation, and reports exact argv and termination evidence.
 
@@ -373,26 +373,19 @@ It is critical to distinguish these two control axes:
 The effective rigor level for a session or dispatch run is resolved at boot time using the following prioritization:
 
 1. **Explicit Override**: Checked via the `CLIO_CODER_RIGOR` environment variable. It is trimmed and parsed case-insensitively. A value of `"high"` or `"normal"` overrides any other setting.
-2. **Repository-Derived Default**: If no override is present, Clio checks the workspace root for the presence of any of the following validation contract files:
-   - `.clio-coder/validation.yaml`
-   - `.clio-coder/validation.yml`
-   - `validation.yaml`
-   - `validation.yml`
-   - `VALIDATION.md`
-   
-   If any of these files are present, the default rigor level is raised to `high`. Otherwise, the default is `normal`.
+2. **Repository-Derived Default**: If no override is present, Clio loads the first of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, or `validation.yml` at the workspace root through the strict version-1 loader in `src/domains/safety/validation-contract.ts`. A contract that parses raises the default to `high`. A contract that does not parse leaves the default at `normal` and carries the fault as a diagnostic that `clio-coder doctor` and the interactive startup notices print. `VALIDATION.md` is advisory prose: it is recognized as present but never parsed and never raises rigor. `rigorResolution()` returns the rigor with its source (`override`, `validation-contract`, `invalid-contract`, `markdown-advisory`, or `none`) and the diagnostic; `resolveRigor()` is the thin wrapper that returns the rigor alone. See [Scientific Validation](../process/scientific-validation.md) for the schema.
 
 ---
 
 ### The Finish Gate and Re-Prompt Behavior
 
-On every settled `turn_end`, the finish-contract assessor scans entries since the last user message, capped at 80 entries. The trigger is action-scoped: the gate engages only when that window contains successful workspace mutation evidence and no validation evidence or explicit limitation. The model does not have to type a phrase such as `done` or `fixed`; the settled turn after mutation is the completion signal.
+On every settled `turn_end`, the finish-contract assessor scans entries since the last user message, capped at 80 entries. The trigger is action-scoped: the gate engages only when that window contains successful workspace mutation evidence and no validation evidence or `limitation` receipt. The model does not have to type a phrase such as `done` or `fixed`; the settled turn after mutation is the completion signal. The assistant's prose never enters the decision.
 
 The assessor decision order is:
 
 1. If the window has no successful mutating receipt or settled mutating `!` bash execution, the contract passes with `no_mutation`.
 2. If the window has validation evidence, the contract passes with `validation_evidence`. Evidence includes successful validation commands, `verify` checks (declared package scripts, admitted project-catalog entries, and the frontend check), passed dispatch receipts, and protected-artifact validation records.
-3. If the assistant explicitly states what could not be verified and why, the contract passes with `explicit_limitation`.
+3. If the window has a successful `limitation` tool receipt (a `limitation` tool_call paired with a non-error tool_result, carrying the scope, a reason from `no-runner`, `blocked`, `out-of-scope`, `environment`, or `other`, and optional unverified paths), the contract passes with `explicit_limitation`. A call the tool rejected leaves no receipt and does not count.
 4. Otherwise, the contract engages with `unvalidated_mutation`.
 
 The finish assessment projects only onto the canonical completion-evidence
@@ -405,11 +398,11 @@ persisted-format compatibility table are documented in
 [`evidence-and-memory.md`](evidence-and-memory.md#canonical-trust-status).
 
 - **Normal Rigor**: Clio issues a soft advisory warning (`FINISH_CONTRACT_ADVISORY_MESSAGE`) injected as a reminder for the next turn, but permits the turn to settle.
-- **High Rigor**: Clio withholds completion. The assessor emits `request_continuation` and a warning `inject_reminder` carrying `HIGH_RIGOR_REVALIDATION_MESSAGE`, instructing the model to run a verification-family command (e.g. `npm test`, `npm run build`) or explicitly declare a limitation before ending.
+- **High Rigor**: Clio withholds completion. The assessor emits `request_continuation` and a warning `inject_reminder` carrying `HIGH_RIGOR_REVALIDATION_MESSAGE`, instructing the model to run a verification-family command (e.g. `npm test`, `npm run build`) or call `limitation` before ending.
 
 #### Exemptions and Safety Precautions
 - **No-Mutation Turns**: Read-only status, alignment, and inspection turns are exempt because there is no successful workspace mutation in the recent window.
-- **Limitation Claims**: If the model explicitly states what could not be verified and why, the assessor accepts the statement as an explicit limitation and allows the turn to settle cleanly.
+- **Limitation Receipts**: A successful `limitation` tool receipt in the window settles the contract with `explicit_limitation`. The assistant's prose never does, so wording alone cannot pass the gate and a real limitation is never missed for its phrasing.
 - **Dynamic Injection**: All gate directives are injected dynamically through middleware effects. This ensures that the static system prompt prefix remains byte-stable, preserving prompt caches.
 - **Prior Hard-Block Preservation**: If a prior middleware hook has already emitted a hard block (e.g. tool-prose violation), the high-rigor continuation is suppressed so that critical error guidance is not overwritten.
 

package/docs/architecture/tui-design.md

@@ -314,7 +314,7 @@ The `/settings` overlay is a full-screen transactional control center:
 
 ### 7.2 Fleet Runs Board
 
-The `Alt+W` board renders one card per run. The default list is compact: run id, route, task, status, telemetry, retry, tool names, and proof. `Enter` opens the selected run's worker detail, which adds two rows to that card and nothing to any other:
+The `Alt+W` board renders one card per run from the observability run projection, which owns lifecycle, worker progress, receipt trust, retries, cancellation, fleet positions, and evidence readiness; the board owns only ordering, selection, and rendering. The default list is compact: run id, route, task, status, telemetry, retry, tool names, and proof. `Enter` opens the selected run's worker detail, which adds two rows to that card and nothing to any other:
 
 - **`doing`**: the phase (`◐ thinking` in `reason`, `◑ writing` in `accent`, `⚙ tool` in `action`, `◔ waiting` in `info`) followed by the running call as `<tool> <verb> <object>`, or the last finished call as `last <tool> <verb> <object>`. The verb and object come from a descriptor composed at the worker seam; raw arguments never reach the renderer.
 - **`answer`**: the newest rows of the worker's bounded prose on a `│` rail with a hanging indent under the key, then a dim row naming the lines and bytes the bounds refused and the `/view dispatch:<runId>` deep link.

package/docs/guide/built-in-agents.md

@@ -49,14 +49,14 @@ User-facing agents visible in `clio-coder agents` and `/agents`.
 
 | Agent ID | Primary tools | Purpose | Capability | Latency |
 | --- | --- | --- | --- | --- |
-| `architect` | read, grep, find, ls, code_nav, git, artifact, context, ledger | Designs a change across boundaries and slices it into a sprint: contracts, migrations, validation gates, and cut-it sprint slicing. | `artifact-write` | `deep` |
-| `coder` | read, write, edit, grep, find, ls, web_fetch, git, bash, verify, code_nav, ledger | Implements bounded code changes, repairs, and refactors, behavior-preserving by default. | `workspace-edit` | `balanced` |
+| `architect` | read, grep, find, ls, code_nav, git, artifact, context, ledger, limitation | Designs a change across boundaries and slices it into a sprint: contracts, migrations, validation gates, and cut-it sprint slicing. | `artifact-write` | `deep` |
+| `coder` | read, write, edit, grep, find, ls, web_fetch, git, bash, verify, code_nav, ledger, limitation | Implements bounded code changes, repairs, and refactors, behavior-preserving by default. | `workspace-edit` | `balanced` |
 | `debugger` | read, grep, find, ls, git, verify, code_nav, ledger | Diagnoses failing code, tests, or runs without editing, reading receipts, logs, and runtime behavior. | `verification` | `balanced` |
-| `documenter` | read, write, edit, grep, find, ls, git, verify, code_nav, context, ledger | Updates developer docs, examples, and operational runbooks. | `workspace-edit` | `balanced` |
-| `git-master` | read, write, edit, context, git, bash, grep, find, ls, code_nav, ledger | Runs bounded git operations end to end: history, commits, worktrees, integration merges, and PR prep. | `workspace-edit` | `balanced` |
-| `tester` | read, write, edit, grep, find, ls, git, verify, code_nav, ledger | Adds focused deterministic regression and coverage tests. | `workspace-edit` | `balanced` |
-| `verifier` | read, grep, find, ls, git, verify, code_nav, ledger | Runs test, lint, build, review, and release gates and reports each independently. | `verification` | `fast` |
-| `wiki-writer` | read, write, edit, grep, find, ls, code_nav, context, ledger | Plans a repository wiki or writes one wiki page against a supplied plan. | `workspace-edit` | `balanced` |
+| `documenter` | read, write, edit, grep, find, ls, git, verify, code_nav, context, ledger, limitation | Updates developer docs, examples, and operational runbooks. | `workspace-edit` | `balanced` |
+| `git-master` | read, write, edit, context, git, bash, grep, find, ls, code_nav, ledger, limitation | Runs bounded git operations end to end: history, commits, worktrees, integration merges, and PR prep. | `workspace-edit` | `balanced` |
+| `tester` | read, write, edit, grep, find, ls, git, verify, code_nav, ledger, limitation | Adds focused deterministic regression and coverage tests. | `workspace-edit` | `balanced` |
+| `verifier` | verify, evidence, read, grep, find, ls, git, code_nav, ledger | Runs test, lint, build, review, and release gates and reports each independently. | `verification` | `fast` |
+| `wiki-writer` | read, write, edit, grep, find, ls, code_nav, context, ledger, limitation | Plans a repository wiki or writes one wiki page against a supplied plan. | `workspace-edit` | `balanced` |
 
 ### Shipped Shadow and Internal Agents
 Internal orchestration helpers and internal process agents. They are hidden from default displays but visible via `clio-coder agents --all`. The full on-demand catalog has a separate shadow section and omits internal recipes; the compact session prompt likewise omits internal recipes and also excludes the operator-only `oracle`.
@@ -66,7 +66,7 @@ Internal orchestration helpers and internal process agents. They are hidden from
 | `scout` | read, grep, find, ls, context, code_nav, git, ledger | Broad repository reconnaissance with cited findings: orientation, structure and entry-point mapping, multi-file symbol hunting. | `read-only` | `fast` |
 | `researcher` | read, web_fetch, context, ledger | Extracts and compares concrete supplied URLs, standards, release notes, and papers through Clio-observed reads and URL retrieval. | `read-only` | `deep` |
 | `world-knowledge` | optional web_fetch, read, context, ledger | Current open-world discovery, ecosystem comparison, broad external context, and an advisory second opinion; reports when discovery is unavailable. | `read-only` | `deep` |
-| `provenance` | read, grep, find, ls, git, ledger | Reads receipts, diffs, and telemetry for evidence-backed handoffs. | `read-only` | `balanced` |
+| `provenance` | evidence, read, grep, find, ls, git, ledger | Reads receipts, diffs, and telemetry for evidence-backed handoffs. | `read-only` | `balanced` |
 | `oracle` | read, grep, find, ls, code_nav, context, ledger | Shadow advisor behind `/oracle` that protects consistency with prior decisions and returns the strongest challenge to a question. | `read-only` | `deep` |
 | `context-bootstrap` | read, grep, find, ls, context, code_nav | Internal agent behind `clio-coder context init` that parses repository and returns CLIO-CODER.md payload. | `read-only` | `balanced` |
 

package/docs/guide/commands-and-modes.md

@@ -103,7 +103,6 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `--temperature <n>` / `--top-p <n>` / `--top-k <n>` / `--min-p <n>` | One-run sampler overrides when the selected runtime supports them. |
 | `--presence-penalty <n>` / `--frequency-penalty <n>` / `--repeat-penalty <n>` | One-run penalty overrides when the selected runtime supports them. |
 | `--max-context-tokens <n>` | One-run context-window override for supported local runtimes. |
-| `--kv-cache-mode <mode>` | One-run KV-cache override for supported local runtimes: `f16`, `f32`, `none`, `false`, `q8_0`, `q4_0`, `q4_1`, `iq4_nl`, `q5_0`, or `q5_1`. |
 | `--json` | Stream JSONL events for main-agent runs; dispatch streams events and receipt JSON. |
 | `--json-events <mode>` | Main-agent JSON stream mode: `full` or `terminal`; implies `--json`. |
 | `--session <id>` | Append this turn to an existing session identified by `<id>`. |
@@ -182,7 +181,7 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/context` | `/context compact [instructions] \| /context recall <ref> \| /context init \| /context refresh \| /context reset` | Context hub: window overlay plus compact, recall, init, refresh, and reset |
 | `/fleet` | `/fleet run [--var <key=value>] <name>` | Open Settings → Fleet, or run a fleet contract with an approval preview |
 | `/decisions` | `/decisions` | Show settled interview decisions and operator revisions |
-| `/tasks` | `/tasks add <text> \| /tasks hand <id> \| /tasks done <id> \| /tasks drop <id>` | Show the session board or manage project operator tasks |
+| `/tasks` | `/tasks add [--expect <path>] [--verify <checkId>[:timeoutMs]] <text> \| /tasks hand <id> \| /tasks done <id> \| /tasks drop <id>` | Show the session board or manage project operator tasks |
 | `/memory` | `/memory seed` | Inspect, promote, or seed task memory |
 | `/view` | `/view [filter] \| /view verify <runId>` | Browse session artifacts and verify receipts |
 | `/panes` | `/panes show <run-or-agent> \| /panes open <preset-or-argv> \| /panes zoom [target] \| /panes close [target]` | Inspect the pane layer, watch a live run in a pane, or open a utility pane (`files`, `logs`, `shell`, `files --once`, or a command); a second open focuses the pane already there |
@@ -198,6 +197,22 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/fork` | `/fork` | Fork from an assistant turn |
 | `/export` | `/export [path]` | Export a self-contained HTML transcript by default; a `.md` path writes Markdown |
 
+Operator tasks are durable project work in `.clio-coder/user-tasks.json`. Use
+`clio-coder tasks add "Fix the solver" --expect src/solver.ts --verify test:solver:60000`
+or `/tasks add Fix the solver --expect src/solver.ts --verify test:solver:60000`.
+Both `--expect <path>` and `--verify <checkId>[:timeoutMs]` are repeatable. Expected
+outputs use repository-relative paths; verification ids must exist in the project
+verifier catalog or package scripts when added. An omitted timeout uses the
+check's declared timeout, and requested timeouts are bounded as in dispatch
+intent. If a complete value matches a declared id containing colons, it names
+that check; otherwise the final numeric suffix is the timeout. Acceptance travels
+with the task when handed and picked, and seeds the board's required validation
+evidence. Under high rigor, a turn that changes files while this task is active
+must record a passing validation receipt for every named check or a successful
+`limitation` receipt whose `paths` array includes the exact check id. A task's
+completion note alone does not satisfy acceptance. `clio-coder tasks list`,
+`hand <uN>`, `done <uN>`, and `drop <uN>` manage the same inbox as `/tasks`.
+
 Retired spellings fail closed and print their exact replacement. In particular,
 `/targets` points to `/settings targets`, `/scoped-models` points to
 `/settings chat model-picker`, and `/library`, `/prompts`, and `/extensions`

package/docs/guide/configuration-and-targets.md

@@ -312,7 +312,7 @@ The tool-prose-loop detector is keyed on the same tier, for the same reason: nar
 
 ### LM Studio transport and settings
 
-The canonical runtime id is `lmstudio`. The former `lmstudio-native` id remains an accepted alias,
+The canonical runtime id is `lmstudio`. The former `lmstudio-native` id remains an accepted alias scheduled for removal in v0.7.0,
 and `clio-coder upgrade` rewrites persisted targets to the canonical id. It also converts `ws:` URLs
 to `http:` and `wss:` URLs to `https:` because this adapter is entirely HTTP. Chat uses LM Studio's
 OpenAI-compatible `POST /v1/chat/completions` endpoint
@@ -903,6 +903,8 @@ Antigravity remains an external agent loop: Clio cannot intercept each tool call
 | `suggest` | Refused because a headless subprocess cannot pause for Clio approval |
 | `full-auto` | Capped at `accept-edits` unless the external full-access gate is explicitly enabled |
 
+Launch flags are a request to agy rather than a guarantee. Headless agy reports `permission_mode: always-proceed` even under `--mode plan --sandbox`, and Clio grades autonomy enforcement as `approximated` in execution receipts. The only Clio-enforced read-only boundary is the receipt grade.
+
 Only `full-auto` together with `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS=1` passes `--dangerously-skip-permissions`. Treat that as an external safety bypass: agy, not Clio's tool registry, controls the resulting filesystem, shell, network, prompts, and approvals. The gate is never enabled by onboarding. A `world-knowledge` dispatch remains read-only even if the caller requests a stronger posture; use another agent for mutation work.
 
 **Setup and verification:**

package/docs/guide/configuration-reference.md

@@ -196,6 +196,7 @@ Read from the process environment at boot unless the row says otherwise.
 | `CLIO_CODER_CACHE_DIR` | `platform default (`$XDG_CACHE_HOME/clio-coder`, else `~/.cache/clio-coder`)` | Absolute path for the cache root; beats `CLIO_CODER_HOME/cache` and the platform default, and the fleet-view pane child re-pins it from argv. | env > `CLIO_CODER_HOME/cache` > `XDG_CACHE_HOME` or platform default |
 | `CLIO_CODER_COMMIT_ASSISTED` | `unset` | Set by Clio to `1`/`0` per spawn from the run's attribution evidence; the managed `prepare-commit-msg` hook reads it to append the assisted trailer, and nested seams strip it. |  |
 | `CLIO_CODER_COMMIT_AUTHORED` | `unset` | Set by Clio to `1`/`0` per spawn from the run's attribution evidence; the managed `prepare-commit-msg` hook reads `1` to add the co-authored trailer, and nested seams strip it. |  |
+| `CLIO_CODER_COMMIT_DECISIONS` | `unset` | Set by Clio per spawn to the space-separated decision refs (`<interviewId>/<key>`) active on the session decision board; the managed `prepare-commit-msg` hook writes one `Clio-Decision:` trailer per well-formed ref, and nested seams strip it. |  |
 | `CLIO_CODER_CONFIG_DIR` | `platform default (`$XDG_CONFIG_HOME/clio-coder`, else `~/.config/clio-coder`)` | Absolute path for the config root; beats `CLIO_CODER_HOME/config` and the platform default, and the fleet-view pane child re-pins it from argv. | env > `CLIO_CODER_HOME/config` > `XDG_CONFIG_HOME` or platform default |
 | `CLIO_CODER_DATA_DIR` | `platform default (`$XDG_DATA_HOME/clio-coder`, else `~/.local/share/clio-coder`)` | Absolute path for the data root; beats `CLIO_CODER_HOME/data` and the platform default, and the fleet-view pane child re-pins it from argv. | env > `CLIO_CODER_HOME/data` > `XDG_DATA_HOME` or platform default |
 | `CLIO_CODER_DEBUG_SHUTDOWN` | `unset (disabled)` | Exactly `1` prints timed `[clio-coder:shutdown]` phase lines and full stack traces of failing domain `stop()` hooks to stderr during shutdown. |  |
@@ -224,8 +225,8 @@ Read from the process environment at boot unless the row says otherwise.
 | `CLIO_CODER_REDUCE_MOTION` | `unset (disabled)` | Exactly `1` makes smooth-streaming `auto` use the immediate coalescer; explicit `on` is unaffected. |  |
 | `CLIO_CODER_RENDER_TRACE` | `unset (disabled)` | File path for the versioned JSONL render-pipeline trace (timing only, no conversation text), truncated on open; off when unset or empty. |  |
 | `CLIO_CODER_REQUIRE_HOME_PREFIX` | `unset (disabled)` | Exactly `1` aborts startup when any resolved Clio directory lies outside `CLIO_CODER_HOME`; a test-harness guardrail that does nothing when `CLIO_CODER_HOME` is unset. |  |
-| `CLIO_CODER_RIGOR` | `repo-derived` | `high` or `normal` (case-insensitive) overrides the finish-contract evidence bar for the orchestrator and dispatched workers; any other value means no override. | env > workspace validation contract file (`.clio-coder/validation.yaml`, `validation.yaml`, `VALIDATION.md` raise it to `high`) > `normal`; no settings key |
-| `CLIO_CODER_RUN_OVERRIDES` | `unset` | JSON object (`maxContextTokens`, `kvCacheMode`, `sampling`) that `clio-coder run` and print modes write via `withRunOverrides` for the run's scope; workers inherit it and malformed input is dropped. |  |
+| `CLIO_CODER_RIGOR` | `repo-derived` | `high` or `normal` (case-insensitive) overrides the finish-contract evidence bar for the orchestrator and dispatched workers; any other value means no override. | env > a parsed workspace validation contract (`.clio-coder/validation.yaml` or `validation.yaml`, version 1) raises it to `high`; an invalid contract or a Markdown-only `VALIDATION.md` leaves `normal` > `normal`; no settings key |
+| `CLIO_CODER_RUN_OVERRIDES` | `unset` | JSON object (`maxContextTokens`, `sampling`) that `clio-coder run` and print modes write via `withRunOverrides` for the run's scope; workers inherit it and malformed input is dropped. |  |
 | `CLIO_CODER_SCREEN_READER` | `unset (disabled)` | Exactly `1` makes smooth-streaming `auto` use the immediate coalescer so a screen reader gets the low-motion update behavior; explicit `on` is unaffected. |  |
 | `CLIO_CODER_SHUTDOWN_HOOK_MS` | `500` | Positive integer milliseconds each shutdown and domain `stop()` hook may run before the coordinator moves on; non-positive or unparsable values use the default. |  |
 | `CLIO_CODER_SKILL_CATALOG_DIR` | `unset` | Path to a local skill catalog used by the marketplace and the provenance pin manifest; beats `<cwd>/skills` and the packaged catalog but not an explicit catalogDir option. | explicit catalogDir option > env > `<cwd>/skills` > packaged catalog |
@@ -614,7 +615,6 @@ Grouped by command. Global flags appear under `global`.
 | `--help` | Print the command's usage and exit. |
 | `--json` | Stream JSONL events for the main-agent turn (dispatch streams events plus the receipt JSON) instead of text output. |
 | `--json-events` | Main-agent JSON stream mode: `full` or `terminal`; implies `--json`. |
-| `--kv-cache-mode` | One-run KV-cache override for supported local runtimes: `f16`, `f32`, `none`, `false`, `q8_0`, `q4_0`, `q4_1`, `iq4_nl`, `q5_0`, or `q5_1`. |
 | `--max-context-tokens` | One-run context-window override (positive integer tokens) for supported local runtimes. |
 | `--min-p` | One-run min-p override (0 to 1) when the selected runtime supports it. |
 | `--model` | Wire model id for this run's main agent or dispatched worker instead of the target's default. |
@@ -885,7 +885,7 @@ Keys read from files under `.clio-coder/` in the repository.
 
 | Key | Controls | Precedence |
 |---|---|---|
-| `(presence)` | The file's presence (also `validation.yml`, root `validation.yaml`, or `VALIDATION.md`) raises the repo-derived rigor default from `normal` to `high`; its content is not read. | `CLIO_CODER_RIGOR` > presence of a validation contract > `normal` |
+| `version`, `task`, `runtime`, `artifacts`, `validators`, `notes` | The version-1 scientific validation contract (also `validation.yml`, root `validation.yaml`, or `validation.yml`). A contract that parses raises the repo-derived rigor default from `normal` to `high`; one that does not parse is diagnosed by `clio-coder doctor` and at interactive startup and leaves `normal`. `VALIDATION.md` is advisory prose and never raises rigor. Schema in [Scientific Validation](../process/scientific-validation.md). | `CLIO_CODER_RIGOR` > parsed validation contract > `normal` |
 
 ### `.clio-coder/verifiers.yaml`
 
@@ -898,7 +898,12 @@ Keys read from files under `.clio-coder/` in the repository.
 | `checks[].id` | Check id, at most 64 bytes; `frontend` is reserved for the built-in artifact check. |  |
 | `checks[].tags` | Free-form labels, at most 16 of 32 bytes, shown in the listing. |  |
 | `checks[].timeoutMs` | Required wall-clock cap for the check in ms, a positive integer at most 900000; a `verify` call may shorten it with `timeout_ms` but not exceed it. |  |
-| `version` | Catalog schema version; must equal the version this build speaks. |  |
+| `checks[].kind` | `command` (default, exit code), `numeric-compare` (stdout JSON judged against `reference` under `tolerance`), or `perf-budget` (wall time judged against `budget` or `baseline`). Requires `version: 2`. |  |
+| `checks[].reference` | `numeric-compare` only: repository-relative JSON file of `string -> number \| number[]` the command output is compared against. |  |
+| `checks[].tolerance` | `numeric-compare`: at least one of `relative`, `absolute`, `ulp`; every named bound must hold. `perf-budget` with `baseline`: `{relative}` headroom over the recorded time. |  |
+| `checks[].budget` | `perf-budget` only: `{wallTimeMs, tolerance?: {relative}}`; exclusive with `baseline`. |  |
+| `checks[].baseline` | `perf-budget` only: repository-relative JSON `{wallTimeMs}` written by `clio-coder verifiers baseline <id>`; exclusive with `budget`. |  |
+| `version` | Catalog schema version, `1` or `2`; version 1 files load with every check as `kind: command`. |  |
 
 ## Agent recipe frontmatter
 

package/docs/guide/environment-variables.md

@@ -96,10 +96,10 @@ Set by Clio for its own processes; not operator knobs.
 | --- | --- |
 | `AI_AGENT` | Clio sets this generic child-process attribution marker to `clio-coder` at both shipped entry points and reinforces it for bash tools, fleet workers, registered code steps, and command hooks. Child tooling may read it to identify the agent that launched it (`src/cli/index.ts`, `src/worker/entry.ts`, `src/core/bash-exec.ts`). |
 | `CLIO_CODER_GIT_COMMITS_ENABLED` | Carries the effective `integrations.git.commitAttribution` setting to Clio-controlled child-process seams. It is set from validated settings and is not an operator override (`src/core/git-commit-attribution.ts`). |
-| `CLIO_CODER_COMMIT_ASSISTED`, `CLIO_CODER_COMMIT_AUTHORED` | Per-spawn inputs to the managed `prepare-commit-msg` hook, which also requires `AI_AGENT=clio-coder` and `CLIO_CODER_GIT_COMMITS_ENABLED=1`; normal external shells never receive this set. Only assistance and authorship cross the environment. Testing, review, and receipt trailers are composed in process by the fleet seam, so a child shell cannot forge them by exporting a variable (`src/core/git-commit-attribution.ts`). |
+| `CLIO_CODER_COMMIT_ASSISTED`, `CLIO_CODER_COMMIT_AUTHORED`, `CLIO_CODER_COMMIT_DECISIONS` | Per-spawn inputs to the managed `prepare-commit-msg` hook, which also requires `AI_AGENT=clio-coder` and `CLIO_CODER_GIT_COMMITS_ENABLED=1`; normal external shells never receive this set. Only assistance, authorship, and the space-separated decision refs the spawn was made under cross the environment. Testing, review, and receipt trailers are composed in process by the fleet seam, so a child shell cannot forge them by exporting a variable (`src/core/git-commit-attribution.ts`). |
 | `CLIO_CODER_GIT_CONFIG_BASE_COUNT`, `CLIO_CODER_GIT_DEFAULT_HOOKS_EQUIVALENT` | Bookkeeping that lets each managed hook wrapper remove only Clio's command-scope `core.hooksPath` pair before chaining the repository's own hook of the same name. Existing `GIT_CONFIG_COUNT` entries remain in force; an explicit `core.hooksPath` is treated as composable only when it resolves exactly to the repository's default hooks directory (`src/core/git-commit-attribution.ts`). |
 | `CLIO_CODER_INTERACTIVE` | Marks the interactive TUI process; scrubbed from bash-tool children so nested invocations do not inherit it (`src/cli/clio.ts`, `src/core/bash-exec.ts`). |
-| `CLIO_CODER_RUN_OVERRIDES` | JSON envelope for run-scoped CLI options (`--max-context-tokens`, `--kv-cache-mode`, sampling flags). One typed variable instead of one env var per option; worker subprocesses inherit it (`src/core/run-overrides.ts`). |
+| `CLIO_CODER_RUN_OVERRIDES` | JSON envelope for run-scoped CLI options (`--max-context-tokens`, sampling flags). One typed variable instead of one env var per option; worker subprocesses inherit it (`src/core/run-overrides.ts`). |
 | `CLIO_CODER_EVAL_RUNNER_STDOUT_FILE` | Set by the eval runner for the `clio-coder run` child it spawns; the child appends its stdout to that path so the runner can read it after exit (`src/domains/eval/suites/run.ts`). |
 | `CLIO_CODER_YAZI_PICK_TOKEN` | Per-session token the yazi file-pane integration hands its yazi child and expects back on a pick, so a pick from another session is ignored (`src/domains/mux/yazi/session.ts`, `src/domains/mux/yazi/profile.ts`). |
 | `CLIO_CODER_WORKER_LABELS` | Comma-separated labels a dispatched worker reports as its own (`src/domains/dispatch/transport.ts`, `src/worker/entry.ts`). |

package/docs/guide/tool-usage.md

@@ -311,7 +311,7 @@ Arguments:
 Projects may commit a versioned executable catalog at `.clio-coder/verifiers.yaml`:
 
 ```yaml
-version: 1
+version: 2
 checks:
   - id: rust-workspace
     description: Run the Rust workspace tests
@@ -319,9 +319,29 @@ checks:
     cwd: .
     timeoutMs: 600000
     tags: [rust, test]
+  - id: grid-metadata
+    description: Compare the regional grid statistics against the reference
+    kind: numeric-compare
+    command: [python, tools/grid_stats.py, out/region_west.nc]
+    reference: tests/reference/region_west.json
+    tolerance: { relative: 1.0e-6, ulp: 4 }
+    cwd: .
+    timeoutMs: 120000
+    tags: [scientific, netcdf]
+  - id: solver-time
+    description: Keep the solver inside its wall-time budget
+    kind: perf-budget
+    command: [python, tools/solve.py, --small]
+    baseline: .clio-coder/baselines/solver-time.json
+    tolerance: { relative: 0.25 }
+    cwd: .
+    timeoutMs: 600000
+    tags: [scientific, performance]
 ```
 
-Version 1 is strict. Every root and check field shown above is required, unknown fields fail, and duplicate IDs fail. A project ID uses lowercase letters, digits, `.`, `_`, `:`, or `-`, begins with a letter or digit, and is at most 64 UTF-8 bytes. `frontend` is reserved. Descriptions are trimmed single-line text capped at 512 bytes. `command` is a nonempty argv array with at most 64 entries and 4096 bytes per entry. A shell command string is invalid, and explicit shell executables such as `sh`, `bash`, `pwsh`, and `cmd` are rejected. `cwd` is a repository-relative existing directory capped at 512 bytes; absolute paths, `..` escapes, and symbolic-link escapes fail. `timeoutMs` is a positive integer capped at 900000. A check may carry at most 16 distinct lowercase tags of at most 32 bytes each. The whole file is capped at 262144 bytes and may contain at most 128 checks. YAML aliases are disabled.
+Every check has a `kind`, absent or `command` by default. A version 1 file still loads and every check there is `kind: command`; the kind fields require `version: 2`. `kind: command` reads the exit code. `kind: numeric-compare` runs the command, parses its stdout as a JSON object of `string -> number | number[]`, and judges it against `reference` (a repository-relative JSON file of the same shape) under `tolerance`, which names at least one of `relative`, `absolute`, or `ulp`; a value passes only when every named tolerance holds, a key missing on either side fails with the key named, arrays compare elementwise and fail on length mismatch, and `NaN` or infinity fails. `kind: perf-budget` runs the command and judges the wall time the harness measured against either `budget: {wallTimeMs, tolerance?: {relative}}` or `baseline`, a repository-relative JSON `{wallTimeMs}` that `clio-coder verifiers baseline <id>` records from one clean run, with an optional `tolerance: {relative}` of headroom over it. Exactly one of `budget` and `baseline` is present. A command that exits non-zero, times out, or is aborted fails before any judgement. Both kinds record a structured `report` on the `verify` result details and on the host-verification check of a dispatch receipt (per-key worst deviation and the failed tolerance, or measured time, effective budget, and ratio); a failing judgement is a check failure, not a new evidence category.
+
+Version 2 keeps version 1's strictness. Every root and check field shown above is required, unknown fields fail, and duplicate IDs fail. A project ID uses lowercase letters, digits, `.`, `_`, `:`, or `-`, begins with a letter or digit, and is at most 64 UTF-8 bytes. `frontend` is reserved. Descriptions are trimmed single-line text capped at 512 bytes. `command` is a nonempty argv array with at most 64 entries and 4096 bytes per entry. A shell command string is invalid, and explicit shell executables such as `sh`, `bash`, `pwsh`, and `cmd` are rejected. `cwd` is a repository-relative existing directory capped at 512 bytes; absolute paths, `..` escapes, and symbolic-link escapes fail. `timeoutMs` is a positive integer capped at 900000. A check may carry at most 16 distinct lowercase tags of at most 32 bytes each. The whole file is capped at 262144 bytes and may contain at most 128 checks. YAML aliases are disabled.
 
 Provider IDs share one namespace. If a catalog ID collides with a discovered package script, listing and execution fail and identify both source files. Catalog parsing also fails closed before any package or project check runs.
 
@@ -348,8 +368,11 @@ clio-coder verifiers author
 clio-coder verifiers author --exclude cmake-build-debug --rename go-test=go-suite
 clio-coder verifiers author --dry-run go-suite --yes
 clio-coder verifiers validate
+clio-coder verifiers baseline solver-time
 ```
 
+`author` also lists one incomplete `numeric-compare` check for every validation-contract artifact that declares `numerical_tolerances`, with the reference and tolerance filled in and the exact `verifiers add` line to complete; the command is the operator's to supply, so the proposal never enters the catalog on its own. `baseline <id>` runs a `perf-budget` check once and writes its wall time to the check's `baseline` path; a failing or timed-out command records nothing.
+
 `validate` reads the committed file with the same parser used by `verify()`. `dry-run <id>` is an explicit request to execute one admitted check through the production `verify` path. `author --dry-run <id> --yes` writes only after confirmation and starts the selected dry run only after the write is accepted by production discovery.
 
 Later changes use the same preview and confirmation boundary. `edit` preserves the ID unless `rename` is requested. Renames and additions reject collisions with catalog IDs and active package-script IDs. Removals state that the deleted command will no longer be executable through catalog authority. Generated IDs are stable for a stable ordered signal set; a collision receives the first available deterministic `-2`, `-3`, and later suffix.
@@ -362,7 +385,7 @@ clio-coder verifiers rename validate-grid validate-regional-grid --yes
 clio-coder verifiers remove validate-regional-grid --yes
 ```
 
-The `add` command is the explicit path for an unsupported or ambiguous project. `--command` must be a JSON argv array, so manual entry still cannot turn a shell command string into executable catalog authority.
+The `add` command is the explicit path for an unsupported or ambiguous project. `--command` must be a JSON argv array, so manual entry still cannot turn a shell command string into executable catalog authority. `--kind numeric-compare` takes `--reference <path>` and `--tolerance '<json>'`; `--kind perf-budget` takes either `--budget-ms <n>` with optional `--budget-relative <r>` or `--baseline <path>` with optional `--tolerance '{"relative": r}'`. `edit` accepts the same options to change a check's kind.
 
 `verify(check="frontend", path=<file>)` validates an HTML, CSS, or JavaScript artifact without shell access. The path must stay inside the workspace root and end in `.html`, `.htm`, `.css`, `.js`, `.mjs`, or `.cjs`. Checks per type: HTML tag balance (comment-aware, HTML5 optional end tags honored), inline and referenced script syntax (classic scripts parsed in-process, modules via `node --check`), inline and linked CSS brace/string/comment balance, local script and stylesheet references resolved and existence-checked (external and root-relative references are skipped), and an optional headless browser load. `browser="auto"` warns when no chromium/chrome/edge executable is on PATH, `"required"` fails, `"off"` skips. Each check reports pass, warn, fail, or skip; any fail makes the whole result an error. `details = {action: "verify", check: "frontend", path, browserMode, status, checks}`.
 
@@ -627,6 +650,58 @@ panes(action="open", preset="logs")
 panes(action="close", target="all")
 ```
 
+## evidence: inspect canonical evidence and trust status
+
+Reads evidence bundles as JSON. Source: `src/tools/evidence.ts`. Read class; sequential, because `run` mode may materialize a bundle under Clio's data directory. It shares the inventory and trust projections behind `clio-coder evidence inventory` and `clio-coder evidence inspect`, so the model and the operator read the same record.
+
+Arguments:
+
+- `mode` (required). `list`, `inspect`, or `run`.
+- `id` (required for `inspect`). An evidence bundle id.
+- `runId` (required for `run`). A dispatch run id; the bundle is built first when none exists.
+
+`list` returns the bounded newest-first inventory: provenance, tags, totals, and a worst-run trust verdict per bundle. `inspect` returns the bundle overview, the per-run trust axes and verdict, the gate decisions, and the findings. `run` resolves `run-<runId>` and builds the bundle when it is absent; a run with no ledger row is reported absent with `artifactAbsent: true` in the details. Results are capped at 16KB, and a truncated result stays valid JSON with a `preview`. Provenance requires this tool and Verifier may use it.
+
+```text
+evidence(mode="list")
+evidence(mode="inspect", id="run-r-42")
+evidence(mode="run", runId="r-42")
+```
+
+## limitation: record what a turn could not verify
+
+Records a typed limitation receipt for the finish contract. Source: `src/tools/limitation.ts`. Read class; parallel. The tool is pure: it touches no filesystem and runs no shell, so the successful receipt in the session ledger is its whole effect.
+
+Arguments:
+
+- `scope` (required). What could not be verified, in one sentence.
+- `reason` (required). `no-runner`, `blocked`, `out-of-scope`, `environment`, or `other`.
+- `paths` (optional). Repository-relative paths left unverified.
+
+Call it once, before the final reply, when files changed and validation could not run. The finish contract accepts a successful `limitation` receipt inside the same window as the mutation scan in place of validation evidence. A rejected call (empty scope, unknown reason) leaves no receipt and does not count, and the assistant's prose never does. The six mutating recipes carry the tool and the operating contract tells the model to call it; see [the finish gate](../architecture/safety-model.md#the-finish-gate-and-re-prompt-behavior).
+
+```text
+limitation(scope="CUDA kernels changed but no GPU is available here", reason="environment", paths=["src/kernels/solve.cu"])
+```
+
+## decide: record a design decision
+
+Appends the model's own design choice to the session decision board beside operator `ask_user` answers. Source: `src/tools/decide.ts`. Read class; sequential, so two decisions in one batch cannot race the supersede lookup. The call succeeds only in a session with a decision board; a worker's call is refused.
+
+Arguments:
+
+- `key` (required). Stable kebab-case name, at most 64 bytes.
+- `value` (required). The option chosen, at most 512 bytes.
+- `alternatives` (required). One to six rejected options, at most 256 bytes each.
+- `rationale` (required). Why the choice won, at most 1024 bytes.
+- `label` (optional). Short title, at most 128 bytes.
+
+The call appends one `decisionLedger` entry with `origin: "agent"` and returns the decision ref `<interviewId>/<key>`. A repeat key supersedes the earlier agent decision with the new rationale as its correction; an operator decision with the same key is never overwritten and the call fails. Dispatch seals every active ref onto the run request, envelope, and receipt, and Clio-controlled commits carry one `Clio-Decision:` trailer per ref; see [commit provenance](../process/git-commit-provenance.md).
+
+```text
+decide(key="cache-key-shape", value="capability tuple", alternatives=["node id"], rationale="matches the existing buckets and survives fleet changes", label="Cache key")
+```
+
 ## ask_user: host-owned operator interviews
 
 Runs a host-owned interactive interview or single-question prompt with the operator, recording decisions and/or free-form answers. Source: `src/tools/ask-user.ts`. Read class; sequential.

package/docs/history/config-knobs-audit.md

@@ -34,7 +34,7 @@ Every runtime-tunable value needs both halves; the pair is one knob, not two. Th
 | `CLIO_CODER_MAX_TOOL_CALLS` | 50 | `src/engine/loop-guard.ts` → `src/engine/worker-runtime.ts` | Worker lifetime tool-call cap for a dispatched run. Different axis than the orchestrator budget despite the near-identical name. |
 | `CLIO_CODER_MAX_DISPATCH_RUNS` | 1000 | `src/domains/dispatch/state.ts` | Dispatch run-ledger retention cap. |
 | `CLIO_CODER_MAX_CONTEXT_TOKENS` | unset | `src/domains/providers/runtime-resolution.ts` | Context-window override for local runtimes. Also set internally by `clio-coder run --max-context-tokens` (see §6). |
-| `CLIO_CODER_KV_CACHE_MODE` | unset | retired | KV-cache quantization mode. Also set internally by the former `clio-coder run --kv-cache-mode` path. |
+| `CLIO_CODER_KV_CACHE_MODE` | unset | retired | KV-cache quantization mode. Also set internally by the former `clio-coder run` path. |
 | `CLIO_CODER_SAMPLING_OVERRIDES` | unset | `src/engine/apis/sampling-overrides.ts` | JSON sampling-parameter override. Set internally by print-mode sampling flags. |
 | `CLIO_CODER_READ_MAX_BYTES` | 51200 (50 KB) | `src/tools/read.ts` | Per-call byte cap for the read tool. |
 | `CLIO_CODER_OBSERVATION_TURN_BUDGET_BYTES` | 196608 (192 KB) | `src/tools/observation.ts` | Shared per-turn byte pool across all observation tools. |
@@ -93,7 +93,7 @@ All default off; all enabled with `1`.
 
 ## 6. CLI flags that bridge through env vars (Pre-consolidated State)
 
-`clio-coder run --max-context-tokens` and `--kv-cache-mode` (`src/cli/run.ts:143-234`) and the print-mode sampling flags (`src/cli/modes/print.ts:306-333`) do not plumb their values through function arguments. They mutate `process.env` (`CLIO_CODER_MAX_CONTEXT_TOKENS`, `CLIO_CODER_KV_CACHE_MODE`, `CLIO_CODER_SAMPLING_OVERRIDES`), run the command, then restore the previous value in a `finally`. The env var is the transport between the CLI layer and deep engine code.
+`clio-coder run --max-context-tokens` (`src/cli/run.ts:143-234`) and the print-mode sampling flags (`src/cli/modes/print.ts:306-333`) do not plumb their values through function arguments. They mutate `process.env` (`CLIO_CODER_MAX_CONTEXT_TOKENS`, `CLIO_CODER_KV_CACHE_MODE`, `CLIO_CODER_SAMPLING_OVERRIDES`), run the command, then restore the previous value in a `finally`. The env var is the transport between the CLI layer and deep engine code.
 
 ## 7. Script- and benchmark-only vars (Pre-consolidated State)
 

package/docs/process/development-pipeline.md

@@ -22,7 +22,7 @@ under pressure; git mechanics alone never justify a stage.
 | 2. Fix | [`fix-issue`](../../skills/git/fix-issue/) | An uncommitted, verified change where failing tests preceded the fix, self-reviewed against the issue's acceptance criteria |
 | 3. Ship | [`ship`](../../skills/git/ship/) | An atomic conventional commit referencing the issue (`fixes #N`); contributors push it to their fork and open a PR, while maintainer work stays local for gated integration; merge is a human decision |
 
-Releases follow [release-cut-checklist.md](../history/release-cut-checklist.md) as a
+Releases follow [release-cut-checklist.md](release-cut-checklist.md) as a
 human-gated checklist, not a skill. Worktrees
 ([`worktree-create`](../../skills/git/worktree-create/),
 [`worktree-merge`](../../skills/git/worktree-merge/)),
@@ -106,6 +106,11 @@ There is no committed weighted-shard or special serial-lane runner. Keep timing
 claims within the focused contract that owns them, and use the full `npm run ci`
 gate before handoff.
 
+The release smoke script `scripts/smoke-real-home.sh` (invoked via
+`npm run smoke:real-home`) tests booting the built CLI binary against a copy of
+the operator settings in a scratch home. An optional `--strict` flag makes doctor
+exit 1 fail the smoke run on failing rows instead of tolerating fleet state.
+
 ## Issue conventions
 
 - **Title**: conventional tag plus imperative summary (`fix: memory overlay

package/docs/process/git-commit-provenance.md

@@ -66,6 +66,21 @@ Clio-Evidence: receipt-v20/sha256:<64-character digest>
 Clio does not invent, shorten, or add an unrelated digest. The role trailers do
 not depend on this optional line.
 
+A commit also names the decisions it was made under, one trailer per active
+decision on the session decision board (an `ask_user` answer or a design
+choice the agent recorded with `decide`):
+
+```text
+Clio-Decision: <interviewId>/<key>
+```
+
+The refs come from the sealed receipt's `decisionRefs` at the fleet seam and
+from the live board at the session seam. They are sorted, capped at 32, added
+once, and only refs of the `<id>/<key>` shape are written, where the key is an
+operator `snake_case` key or an agent `kebab-case` key. A decision trailer
+records rationale provenance; it is not evidence that the decision was correct
+or that its work was validated.
+
 ## Commit paths and hooks
 
 The deterministic SDLC fleet attributes its plan, code, and documentation