@iowarp/clio-coder 0.3.3 → 0.3.6

package/docs/prompt-envelope-and-tools.md

@@ -1,7 +1,7 @@
 # Prompt Envelope and Tools
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/tools_blueprint.html](html/tools_blueprint.html) (Version: 0.3.3).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/tools_blueprint.html](html/tools_blueprint.html) (Version: 0.3.6).
 
 Clio Coder keeps the model-facing envelope stable and moves enforcement into the runtime registry and safety policy.
 
@@ -78,6 +78,8 @@ Three tools sit in a plane for containment rather than class. `git` is read-only
 
 Registration is conditional on wiring: `context` gains its workspace scope only when a session contract is bound, `dispatch`/`monitor`/`steer` register only with a dispatch contract, and `ask_user` registers only when an interactive handler exists. Dispatch tool profiles narrow the surface for workers: `minimal-local` is `read`, `grep`, `find`, `ls`, `git`, `context`, `code_nav`; `science-local` adds `verify`; `full-agent` keeps everything.
 
+`ask_user` keeps its typed `exposure: local | outward` admission fact separate from caller prose. The registry uses exposure only in the enforced autonomy mapping. After admission, the host carries the normalized fact into the shared decision-presentation classifier; question text, headers, options, summaries, and requested color or severity words cannot select a consequence tier. The resulting presentation object contains no admission disposition and cannot grant authority.
+
 ### Consolidated call shapes
 
 Several tools absorb what used to be separate tools:
@@ -85,9 +87,9 @@ Several tools absorb what used to be separate tools:
 - `find(pattern, path?, order?, limit?, include_ignored?)` locates paths by glob pattern (`*`, `**`, `?`, `[abc]`), default limit 500. `order="path"` (default) returns fd's native order; `order="mtime"` returns newest first from a bounded candidate set instead of statting the whole tree, and reports `details.candidates` when the candidate cap made the ordering approximate.
 - `grep(pattern, path?, mode?, glob?, ignore_case?, literal?, context?, limit?, include_ignored?)` searches file contents with ripgrep, degrading to a bounded pure-Node search when rg is absent. `mode=content` (default) returns line-referenced matches, `mode=files` returns matching paths, `mode=count` returns per-file counts. Context lines are consumed from rg's `--json` stream.
 - `context(scope="workspace"|"docs"|"skills")` is the one OBSERVE entry point for material about the working environment: the session workspace snapshot, retrieval over Clio's bundled documentation (`query` required), and skill listing or loading (`name` optional, `include_tree` for the skill's resource files).
-- `verify(check?, path?, args?, browser?, cwd?, timeout_ms?)` runs declared verification. `verify()` with no arguments lists declared checks grouped by source (package.json verification scripts today), `verify(check="<script>")` runs one through the safe-exec spine with no shell, and `verify(check="frontend", path=...)` validates an HTML/CSS/JS artifact without granting shell access.
+- `verify(check?, path?, args?, browser?, cwd?, timeout_ms?)` runs declared verification. `verify()` lists package.json verification scripts and strict version-1 `.clio-coder/verifiers.yaml` entries through the same `{id, description, command, cwd, timeoutMs, tags, source}` projection. `verify(check="<id>")` runs a package script or the catalog's exact argv/cwd/timeout through safe-exec with no shell. Model `args`, cwd, timeout, output-cap, and environment fields cannot mutate a project entry. `verify(check="frontend", path=...)` validates an HTML/CSS/JS artifact without granting shell access.
 - `artifact(kind="plan"|"review"|"report", content, ...)` writes named artifacts behind one surface: Markdown documents (default `.clio-coder/artifacts/PLAN.md`/`REVIEW.md`/`REPORT.md`; `path` may override inside the workspace) that terminate the turn, because writing the artifact is the answer. Skills are not artifacts; a `SKILL.md` is written with the ordinary write tool and validated by the skills loader.
-- `dispatch(task?, tasks?, mode?, ...)` supports a first-class singular assignment (`task`) and a batch (`tasks`), never both. `task` is worker instructions; `briefing` is optional bounded parent context/data and cannot replace it. Briefing stays a separate dynamic message and receipt provenance, never part of the receipt task. A shared top-level briefing applies to strings and objects without an override; an object-level briefing wins. Blank values are omitted, the cap is 12,000 UTF-8 bytes, and approval pins the exact canonical value. Ordinary handles enter one registered event consumer immediately. Synchronous calls auto-wait for stream-and-receipt completion; `detach:true` returns ids after durable batch registration while the same consumer continues. Review and compete retain gate-sensitive direct drains. Task objects may include `persona` and `tool_profile`. Pipeline output is threaded as bounded data. A successful native or ACP run requires a nonempty receipt-sealed final output; exit zero without one fails as `worker_final_output_missing`, with unfinished text retained only as partial diagnostics. `dispatch(list=true)` renders the catalog.
+- `dispatch(task?, tasks?, mode?, ...)` supports a first-class singular assignment (`task`) and a batch (`tasks`), never both. `task` is worker instructions; `briefing` is optional bounded parent context/data and cannot replace it. Briefing stays a separate dynamic message and receipt provenance, never part of the receipt task. A shared top-level briefing applies to strings and objects without an override; an object-level briefing wins. Blank values are omitted, the cap is 12,000 UTF-8 bytes, and approval pins the exact canonical value. Ordinary handles enter one registered event consumer immediately. Synchronous calls auto-wait for stream-and-receipt completion; `detach:true` returns ids after durable batch registration while the same consumer continues. Review and compete retain gate-sensitive direct drains. Task objects may include `persona`, `tool_profile`, and a typed `budget: {toolCalls, readReserve, retryRevision?}`. The budget must fit the recipe's authored range and the operator lifetime cap. `retryRevision` is the only authority for a later retry, result-contract revision, or review revision to grow its phase. Pipeline output is threaded as bounded data. A successful native or ACP run requires a nonempty receipt-sealed final output; exit zero without one fails as `worker_final_output_missing`, with unfinished text retained only as partial diagnostics. `dispatch(list=true)` renders the catalog.
 - `monitor(run_id?, mode?)` is read-only visibility into known synchronous and detached runs: `list` enumerates, `status` reports one, `peek` returns the in-process event tail, `receipt` exposes the stored evidence, and `wait` observes one run without collecting or canceling it. `collect` is the authoritative terminal batch operation over a detached batch or run-id list; collect before final synthesis. Completed output reports receipt integrity, evidence verification, briefing provenance, and bounded project-context provenance as different fields.
 - `steer(run_id, action, message?)` controls a running worker: `guide` writes a canonical trimmed steering message to an HTTP or SDK worker and `cancel` terminates it. Successfully written steers gain ordered byte/hash/timestamp provenance; after the runtime accepts the guidance, `clio_steer_received` acknowledges the exact matching sequence, and prose is never stored in ledger or receipt. Single-shot subprocess runtimes and ACP remain non-steerable. Interactive operators can steer synchronous live-input runs; parent-model steering requires detached ids because model tools are sequential.
 
@@ -107,7 +109,7 @@ The six content-returning OBSERVE tools (`read`, `grep`, `find`, `ls`, `code_nav
 
 Unknown segments are omitted. `<total>` renders as `N+` when the search was killed early at its limit, meaning matches beyond it exist but were never counted. `next` is always an exact continuation call fragment such as `limit=200` or `offset=451`, never prose. Untruncated results get no notice. Empty results are standardized: `grep` returns `No matches found`, `find` returns `No files found matching pattern`, `ls` returns `(empty directory)`, and the JSON-format tools return valid JSON with empty arrays and `next` populated.
 
-**Offload on truncation.** When a byte cap cuts collected content, the tool spills its full rendering to the per-session scratch file (`<stateDir>/scratch/<sessionId>/<toolCallId>.txt`) and reports the path in the notice, so no collected match, path, or line is ever unrecoverable. Two deliberate exceptions exist: `read` never offloads because the source file is directly re-addressable via `next: offset=N`, and a bare item-limit truncation without a byte cut continues via `next` alone, since an offload would only duplicate the body.
+**Offload on truncation.** When a byte cap cuts collected content, the tool spills its full rendering to the per-session scratch file (`<stateDir>/scratch/<sessionId>/<sha256 of the captured text>.txt`) and reports the path in the notice, so no collected match, path, or line is ever unrecoverable. Two deliberate exceptions exist: `read` never offloads because the source file is directly re-addressable via `next: offset=N`, and a bare item-limit truncation without a byte cut continues via `next` alone, since an offload would only duplicate the body.
 
 **Always-valid JSON.** `code_nav` and the JSON scopes of `context` declare `format: "json"`. A JSON payload must parse or be replaced whole; it is never cut mid-document. An oversize payload is offloaded and the body is replaced by the parseable stub:
 
@@ -133,7 +135,7 @@ Tool descriptions are tiered by how much a wrong call costs. The hot tools the m
 
 Clio uses two context-protection mechanisms.
 
-1. Tool results are capped at the source and again at the registry boundary. OBSERVE tools use the envelope caps above. Exact mutation tools (`write`, `edit`, `artifact`) use 8KB; `steer` and `credential_present` use 4KB; `ask_user` has a 20KB policy. Summary-kind tools (`bash`, `git`, `verify`, `dispatch`, `monitor`) use 16KB at the registry boundary. `web_fetch` is bounded at 16KB after shaping and may read more before it: its `max_bytes` argument defaults to 600KB and is hard-capped at 5MB. Tools without an explicit result-size policy use an approximately 18KB generic backstop. Over-cap generic results are shown briefly and, when possible, saved under `<stateDir>/scratch/<sessionId>/<toolCallId>.txt` with an `offloadPath` detail and a 10MB scratch-file cap.
+1. Tool results are capped at the source and again at the registry boundary. OBSERVE tools use the envelope caps above. Exact mutation tools (`write`, `edit`, `artifact`) use 8KB; `steer` and `credential_present` use 4KB; `ask_user` has a 20KB policy. Summary-kind tools (`bash`, `git`, `verify`, `dispatch`, `monitor`) use 16KB at the registry boundary. Bash also exposes the canonical per-call `output_policy`: omitted/`bounded` keeps its diagnostic tail, `summary` selects stable redacted head/error/tail evidence, `metadata-only` keeps facts and retrieval without stdout/stderr context, and `full` succeeds only inside the same hard result budget or records a typed downgrade. This model-context choice does not change the folded tail-biased operator presentation. `web_fetch` is bounded at 16KB after shaping and may read more before it: its `max_bytes` argument defaults to 600KB and is hard-capped at 5MB. Tools without an explicit result-size policy use an approximately 18KB generic backstop. Over-cap generic results are shown briefly and, when possible, saved under `<stateDir>/scratch/<sessionId>/<sha256 of the captured text>.txt` with an `offloadPath` detail and a 10MB scratch-file cap.
 2. Auto-compaction uses one pressure threshold. The default threshold is 0.8. When pressure crosses the threshold, Clio first masks stale tool observations and stale thinking older than `excludeLastTurns`. If pressure remains above the threshold, it runs the LLM summary compaction path and replays from the compacted session view.
 
 Manual `/context compact`, `CLIO_CODER_FORCE_COMPACT=1`, and overflow recovery force the LLM summary path directly.

package/docs/provider-adapter-cookbook.md

@@ -1,7 +1,7 @@
 # Provider Adapter Cookbook
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive runtime adapter descriptor builder and probe sequence capability checklist is located at [docs/html/provider_adapter_blueprint.html](html/provider_adapter_blueprint.html) (Version: 0.3.3).
+> **Interactive Spec Available:** An interactive runtime adapter descriptor builder and probe sequence capability checklist is located at [docs/html/provider_adapter_blueprint.html](html/provider_adapter_blueprint.html) (Version: 0.3.6).
 
 This cookbook guides developers through implementing custom model runtimes and inference server integrations within Clio Coder. It explains the runtime descriptor interfaces, probing protocols, model synthesis, and how to configure reasoning and thinking behaviors.
 

package/docs/release-cut-checklist.md

@@ -1,6 +1,6 @@
-# v0.3.3 Release-Cut Checklist
+# v0.3.6 Release-Cut Checklist
 
-The ordered steps that turn the prepared `v0.3.3` branch into a published
+The ordered steps that turn the prepared `v0.3.6` branch into a published
 release. Everything above the line marked **AUTHORIZATION BOUNDARY** is
 repeatable and reversible and is run locally before the cut. Everything below
 it is external or irreversible and needs an explicit decision from the
@@ -11,13 +11,14 @@ state of every step.
 
 | Item | State |
 | --- | --- |
-| Branch | `v0.3.3`, local only; no remote `v0.3.3` branch |
-| `package.json` version | `0.3.3`; the top `CHANGELOG.md` heading is `## 0.3.3 - 2026-08-21` |
-| `main` | `e6c2571e`, the published `v0.3.2` commit; it is an ancestor of `v0.3.3` and moves only at Part 4. |
-| `origin/main` | `e6c2571e`, matching the published `v0.3.2` commit |
-| Tags | none for 0.3.3, local or remote |
-| GitHub Release | none for 0.3.3 |
-| npm registry | `@iowarp/clio-coder@0.3.3` absent; `latest` is `0.3.2` |
+| Branch | `v0.3.6`, local only; pushed with the explicit refspec `refs/heads/v0.3.6` when the operator decides, never as a bare name that a tag could shadow |
+| `package.json` version | `0.3.6`; the top `CHANGELOG.md` heading is `## 0.3.6 - 2026-08-23` |
+| `main` | `590fda7d`, which already carries the v0.3.5 content and the CI diet; it is an ancestor of `v0.3.6` and moves only at Part 4. |
+| `origin/main` | `590fda7d`, matching `main` with the v0.3.5 content and the CI diet |
+| Tags | none for 0.3.6, local or remote |
+| GitHub Release | none for 0.3.6 |
+| npm registry | `@iowarp/clio-coder@0.3.6` absent; `latest` is `0.3.4` |
+| npm history | `@iowarp/clio-coder` has published versions 0.3.0 through 0.3.4, with `latest` at 0.3.4. Version 0.3.5 was published and withdrawn, so `@iowarp/clio-coder@0.3.5` can never be reused. |
 | Commit provenance identity | Post-release maintainer follow-up, not a gate: verifying `clio-coder@iowarp.ai` on IOWarp-controlled GitHub and GitLab identities (such as `clio-coder-bot` or `iowarp-clio`, with `assets/clio-coder-avatar-512.png` as the avatar) only changes how those platforms render the trailers. |
 
 ---
@@ -38,13 +39,14 @@ Run against the exact final candidate with `NO_COLOR` unset and
    integrity, version coherence between `package.json` and the top
    `CHANGELOG.md` heading, the forbidden-file list, the required runtime
    resources, and the tarball and unpacked size budgets)
-9. Step 8 again under the other supported Node major. Both Node 22 and
-   Node 24 must be green; the repo is developed against 22.22.3 and 24.9.0.
-10. `npm run test:lifecycle` for the twenty-case lifecycle matrix against a real
-    `npm pack` installed into a temporary prefix. Case 9 needs `--live` plus
-    `CLIO_CODER_LIFECYCLE_URL` and `CLIO_CODER_LIFECYCLE_MODEL` naming a target
-    whose model is already resident; report it separately when no such target
-    is available.
+9. Optional: step 8 again under Node 24. Hosted CI gates on Node 22 alone,
+   the `engines` floor; the weekly `flake-hunt` workflow carries Node 24.
+   Repeat locally only when the cut touches runtime-sensitive code.
+10. `npm run live:smoke -- --target <id>` for one real headless turn through
+    the built binary against a configured target, which is the one release
+    check a deterministic suite cannot give. The packaged-install lifecycle
+    (pack, install into a clean prefix, run the installed launcher) is
+    `tests/smoke/pack-install.test.ts` and already ran under step 5.
 11. `npm pack --dry-run`, then a real `npm pack` into a temporary directory.
     Inspect the complete file list: `skills/`, `docs/*.md`, the builtin
     agents, the model catalogs, and `damage-control-rules.yaml` are present;
@@ -58,22 +60,22 @@ Run against the exact final candidate with `NO_COLOR` unset and
 ## Part 2: version and notes (repeatable)
 
 13. Files carrying a version reference, to update together if the number
-    changes: `package.json` and `package-lock.json`, the `## 0.3.3 - <date>`
-    heading in `CHANGELOG.md`, the `(Version: 0.3.3)` markers in `docs/*.md`,
-    the `Blueprint (v0.3.3)` titles in `docs/html/*.html`, the `--branch`
+    changes: `package.json` and `package-lock.json`, the `## 0.3.6 - <date>`
+    heading in `CHANGELOG.md`, the `(Version: 0.3.6)` markers in `docs/*.md`,
+    the `Blueprint (v0.3.6)` titles in `docs/html/*.html`, the `--branch`
     pin in the README install block (the hygiene lint checks it), and the
     measured-at figures in `scripts/check-release.mjs` if the package size
     moved materially.
-14. Confirm the `## 0.3.3` section of `CHANGELOG.md` describes every
+14. Confirm the `## 0.3.6` section of `CHANGELOG.md` describes every
     user-visible behavior change, including the ones that alter existing
     behavior, and carries no Workbench release narrative. The release workflow
     uses this section verbatim as the GitHub Release body.
 15. Re-run `npm run ci:release` after any version edit and commit as one
-    commit on `v0.3.3`.
+    commit on `v0.3.6`.
 
 ## Part 3: present the gate
 
-16. Report to the operator before touching `main`: the exact final `v0.3.3`
+16. Report to the operator before touching `main`: the exact final `v0.3.6`
     SHA and clean status, the commits added since the handoff SHA, the gate
     commands with pass/fail totals for both Node majors, the package version
     and changelog heading, the tarball audit, the clean-install results and any
@@ -92,35 +94,36 @@ confirming the exact SHA and the commands.
 ## Part 4: fast-forward `main`
 
 17. `git fetch origin` immediately before integrating; require `origin/main`
-    to be an ancestor of the reviewed `v0.3.3` tip and confirm no other
+    to be an ancestor of the reviewed `v0.3.6` tip and confirm no other
     worktree has `main` checked out.
-18. `git checkout main && git merge --ff-only v0.3.3`. No merge commit, no
+18. `git checkout main && git merge --ff-only v0.3.6`. No merge commit, no
     rebase, no reset. Verify `main` equals the reviewed SHA and is clean.
 19. `git fetch origin` once more; stop on any unexpected remote movement. Then
     `git push origin main`. Never `--force` or `--force-with-lease`.
 
 ## Part 5: exact-SHA CI, tag, GitHub Release
 
-20. Wait for the `ci` workflow the `main` push triggers. Both the Node 22 and
-    Node 24 jobs must succeed on the exact release SHA. A red or pending run
-    blocks the tag; a flake is rerun only with concrete evidence, never
-    silenced with an unrelated change.
-21. Reconfirm that tag `v0.3.3` and the GitHub Release do not exist, then
-    `git tag -a v0.3.3 -m "Clio Coder 0.3.3"` on the green SHA and
-    `git push origin v0.3.3`.
-22. The tag push triggers `.github/workflows/release.yml`, which requires a
-    successful `ci` run for the tagged SHA, verifies the tag matches
-    `package.json`, builds and audits the artifact, extracts the `## 0.3.3`
-    section of `CHANGELOG.md` as the release body, and attaches the tarball.
+20. The `main` push triggers the `ci` workflow. It is a useful signal but no
+    longer a gate on tagging, because `release.yml` runs the same gate on the
+    tagged tree itself. A red run still blocks the cut; investigate it rather
+    than tagging around it, and never silence a flake with an unrelated
+    change.
+21. Reconfirm that tag `v0.3.6` and the GitHub Release do not exist, then
+    `git tag -a v0.3.6 -m "Clio Coder 0.3.6"` on the green SHA and
+    `git push origin refs/tags/v0.3.6`.
+22. The tag push triggers `.github/workflows/release.yml`, which verifies the
+    tag matches `package.json`, runs `npm run ci:release` on the tagged tree,
+    extracts the `## 0.3.6` section of `CHANGELOG.md` as the release body, and
+    attaches the tarball.
     Do not create a release by hand. Verify the run's SHA, the notes, the
     attached tarball, and the URL.
 
 ## Part 6: npm publication (irreversible)
 
 23. `npm whoami` and confirm the registry and account; reconfirm
-    `@iowarp/clio-coder@0.3.3` is still absent.
+    `@iowarp/clio-coder@0.3.6` is still absent.
 24. Obtain the operator's explicit dist-tag decision. `latest` makes this the
-    default install for every user; `--tag next` keeps `0.3.2` as the default.
+    default install for every user; `--tag next` keeps `0.3.4` as the default.
 25. Run `npm publish` (or `npm publish --tag next`) once. `prepublishOnly`
     re-runs `ci:release` as a safety net; it is not a substitute for Part 1.
 26. A published version cannot be replaced. `npm unpublish` is restricted and
@@ -128,13 +131,13 @@ confirming the exact SHA and the commands.
 
 ## Part 7: post-publish verification and follow-ups
 
-27. `npm view @iowarp/clio-coder@0.3.3` and the selected dist-tag.
+27. `npm view @iowarp/clio-coder@0.3.6` and the selected dist-tag.
 28. On a clean machine, `npm install -g @iowarp/clio-coder` from the registry
     rather than from a local tarball, then repeat step 12 against it, plus
     `configure` to a real target and one real turn when one is authorized.
     This is the only step that tests what users actually receive.
-29. From an installation of 0.3.2, verify `clio-coder upgrade` finds and
-    applies 0.3.3.
+29. From an installation of 0.3.4, verify `clio-coder upgrade` finds and
+    applies 0.3.6.
 30. Record the SHA, CI URL, tag, GitHub Release URL, npm version and dist-tag,
     tarball evidence, and the post-publish verification in the release report.
 31. Maintainer follow-up, independent of the release: verify the commit

package/docs/safety-model.md

@@ -1,7 +1,7 @@
 # Clio Coder Safety Model
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/safety_blueprint.html](html/safety_blueprint.html) (Version: 0.3.3).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/safety_blueprint.html](html/safety_blueprint.html) (Version: 0.3.6).
 
 Clio Coder's safety posture is code-enforced, not prompt-only. As the orchestrator coding agent in the [IOWarp](https://iowarp.ai) ecosystem developed by the [Gnosis Research Center](https://grc.iit.edu) at Illinois Tech under NSF Award [#2411318](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2411318), Clio gates execution by target capabilities, the tool registry, the safety policy engine, project policies, protected-artifact checks, and audit receipts.
 
@@ -13,7 +13,7 @@ Source of truth: `src/domains/safety/**`, `src/tools/registry.ts`, `src/tools/bo
 
 The `autonomy` setting (`read-only` | `suggest` | `auto-edit` | `full-auto`) is an enforced dial. It controls exactly one thing: which action classes run immediately, which park for operator approval, and which are auto-denied. The safety net (damage-control rules, path policy, protected artifacts, loop guard, dispatch scope admission) is independent of the dial and identical at every level. When a `[safety-net]` notice appears at full-auto, that is the always-on net working as designed, not a contradiction of the level.
 
-In Clio Coder v0.3.3, effective autonomy resolution is strictly centralized in `src/entry/orchestrator.ts` through `resolveEffectiveAutonomy` and `resolveBaselineAutonomy`. Every admission surface (tool registry admission, dispatch plan provenance, and ACP session snapshots) delegates to this pair of functions so that fallback paths cannot diverge across execution contexts. `resolveBaselineAutonomy` evaluates dispatch settings overrides, headless CLI options, and configuration settings before applying the default `auto-edit` level. `resolveEffectiveAutonomy` combines any active ACP session autonomy level with the baseline resolution.
+In Clio Coder v0.3.6, effective autonomy resolution is strictly centralized in `src/entry/orchestrator.ts` through `resolveEffectiveAutonomy` and `resolveBaselineAutonomy`. Every admission surface (tool registry admission, dispatch plan provenance, and ACP session snapshots) delegates to this pair of functions so that fallback paths cannot diverge across execution contexts. `resolveBaselineAutonomy` evaluates dispatch settings overrides, headless CLI options, and configuration settings before applying the default `auto-edit` level. `resolveEffectiveAutonomy` combines any active ACP session autonomy level with the baseline resolution.
 
 ### Autonomy levels
 
@@ -40,6 +40,27 @@ The `system_modify` confirm is level-invariant, so it is enforced and attributed
 
 The level is persisted as `autonomy` in `settings.yaml`, hot-reloads, and is edited in the `/settings` Autonomy & Safety section.
 
+### Consequence tier is presentation, not authority
+
+Every operator decision also receives one closed consequence tier. The tier explains what the already-required decision can affect. It never decides whether a call runs, never changes the autonomy level, and never overrides a safety-net verdict. Registry admission still follows the enforcement path below before any presentation is built.
+
+| Consequence tier | Trusted facts that select it | Operator-facing meaning |
+| --- | --- | --- |
+| Conversational answer | A local `ask_user` question that records an answer | Records an answer without granting tool authority. |
+| Workspace authority | A main-agent one-shot approval whose bounded scope is the workspace | Authorizes only the presented call. Workspace changes can be reviewed and reverted when the action class supports that. |
+| Outward consequence | Typed `exposure: outward` | The answer concerns a step that can reach people or systems outside the workspace. The interview itself does not publish or send anything. |
+| Safety-net confirmation | An always-on confirm rail | The safety net requires a one-shot operator decision independently of the autonomy level. |
+| System change | `system_modify`, destructive, unknown, or otherwise system-scoped consequences | The effect reaches outside the workspace or cannot be safely bounded, and reversibility is unknown. |
+| Worker escalation | An authenticated dispatched-worker origin | The parked decision belongs to the named worker run and returns only to that exact request. |
+
+The classifier reads the request kind, the enforced safety or autonomy axis, normalized local or outward exposure, derived reversibility and scope, authenticated main-agent or worker origin, and whether the surface records an answer or grants one-shot authority. Model-authored questions, reasons, summaries, option labels, titles, and color names do not enter the classifier. Worker and system facts take conservative precedence, and an unknown action class uses the system tier. An interview that has reached outward exposure keeps that tier for later rounds and durable replay, so a later local declaration cannot visually lower it.
+
+These three concepts answer different questions:
+
+- The autonomy level decides when the registry allows, parks, or denies an action class.
+- The safety-net axis identifies an always-on rule that can block or require confirmation at every autonomy level.
+- The consequence tier explains the scope, reversibility, requester, and effect of a decision that the enforced axes have already produced.
+
 ---
 
 ## Enforcement path
@@ -132,6 +153,8 @@ Shell operators split two ways. Unrecognized sequencing and redirection (`||`, `
 
 Bash `cwd` is resolved under the workspace root. Escaping the workspace is blocked unless a reviewed project policy permits the exact command/cwd combination.
 
+Bash `output_policy` changes only the canonical model-context disposition after execution; it never changes command classification, autonomy, cwd containment, environment filtering, process-group termination, or the 16 MiB capture ceiling. Omitted/`bounded` retains the diagnostic tail. `summary` uses a deterministic code path with repository secret redaction and bounded head, tail, and error-like lines. `metadata-only` retains success/failure, exit, signal, timeout, abort, output-cap, byte-size, and retrieval facts without stdout or stderr in model context. `full` is appropriate only for known-small results and records a typed downgrade plus retrieval when the hard result budget cannot admit it. Operator presentation remains independently tail-biased, and only the terminal result may write its single retained scratch artifact.
+
 ---
 
 ## Policy Engine Evaluation Order
@@ -230,9 +253,17 @@ Command entry notes:
 Prefer typed tools over Bash:
 
 - `git` (op=status/diff/log) uses fixed command vectors.
-- `verify(check="<script>")` runs a declared package.json verification script (the `test*/lint*/build*/typecheck*/check*/format*/ci*` family) through bounded execution helpers with no shell; `verify()` with no arguments lists the declared checks.
+- `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.
+
+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.
+
+`clio-coder verifiers discover` and `clio-coder verifiers author` do not grant authority during inspection. They read only declared package, Cargo, CMake preset, Python runner, Go module, and YAML validation-command signals and render exact argv vectors with provenance. The preview names the catalog path, cwd, timeout, tags, and authority consequence for every check. Toolchain conventions are labeled separately from literal project declarations. Ambiguous validation prose and directory-only hints are rejected with a JSON argv manual-entry path.
+
+Authoring validation serializes the proposed catalog in memory and passes it to the production catalog parser. Discovery, revision, and preview cannot reach the filesystem writer or verifier executor. A reviewed mutating CLI invocation must be repeated with `--yes` before an atomic catalog write is reachable. An optional authoring dry run begins only after that decision and goes through the production `verify` execution path. Editing, renaming, and removal use the same preview boundary; collisions fail before writing, and removal explicitly revokes that catalog command's execution authority.
+
 The frontend check accepts `.html`, `.htm`, `.css`, `.js`, `.mjs`, and `.cjs` under the workspace root. It checks HTML tag balance, local script/style references, JavaScript syntax, CSS brace/comment/string balance, and optionally loads HTML with an available headless Chromium/Chrome/Edge executable (`browser: auto|required|off`).
 
 The `edit` tool also carries conservative matching rules. It preserves
@@ -276,7 +307,7 @@ Evidence raises a warn-level external-bypass finding for bypassed runs and an in
 
 ## Approvals
 
-An `ask` can come from either axis: a safety-net confirm rail (damage-control `ask` rule, project `requireConfirmation`, `system_modify`) or the autonomy mapping. The permission overlay names the asking axis on its `Asked by:` line, and the transcript carries an `[approval]` notice for every parked call.
+An `ask` can come from either axis: a safety-net confirm rail (damage-control `ask` rule, project `requireConfirmation`, `system_modify`) or the autonomy mapping. The permission overlay names the authenticated requester and asking axis on its `Requested by:` lines, and the transcript carries an `[approval]` notice for every parked call.
 
 Every approvable ask has one canonical identity: a `requestId` minted at the approvals plane. The `PermissionRequested` and `PermissionResolved` bus payloads and the audit permission rows all carry it, along with `origin` (who asked), `axis` (which rail or level), and `decidedBy` (who or what answered), so a request joins its resolution on one key across the bus, the ledger, and receipts, and every request resolves exactly once. Worker escalations forward their full decision provenance (reasons, reason code, rule id, policy source), so the overlay names the real asking rail for a worker exactly as it does for the main agent.
 
@@ -284,9 +315,10 @@ How an ask resolves depends on the context:
 
 ### Interactive TUI Behavior
 
-In interactive mode, a permission request opens a queued overlay prompt immediately in the TUI.
-- **Queued Overlays:** If multiple tools or worker dispatches require permission during a single turn, the TUI queues the requests. Closing one overlay automatically pops the next permission overlay in the queue.
-- **Operator Options:** The operator can grant permission once, which resumes only the parked tool call without changing the overall operating posture; the one-shot grant is scoped to the presented request's `requestId`. Denying rejects only the presented request and advances the queue; the next parked call re-presents. Cancel-all is reserved for shutdown, an aborted turn, headless runs, and transport failure, where no operator can answer.
+In interactive mode, a permission request opens a queued overlay prompt immediately in the TUI, and the composer rail switches to `CONFIRM` with the same keys for as long as the prompt owns the keyboard.
+- **Queued Overlays:** If multiple tools or worker dispatches require permission during a single turn, the TUI queues the requests. Closing one overlay automatically pops the next permission overlay in the queue. Each queued request retains its consequence tier and authenticated requester. A request that arrives while a different overlay (a picker, `/context`, the fleet board) holds the screen is announced with an `[approval]` notice and re-presented the moment that overlay closes.
+- **Operator Options:** `Enter` grants permission once, which resumes only the parked tool call without changing the overall operating posture; the one-shot grant is scoped to the presented request's `requestId`. `Esc` denies only the presented request and advances the queue; the next parked call re-presents. `s` denies it and ends the turn. Cancel-all is reserved for shutdown, an aborted turn, headless runs, and transport failure, where no operator can answer.
+- **Enter never doubles as send:** `Enter` allows only from an empty composer. While the composer holds a draft, `Enter` does nothing, both surfaces say `[Backspace] clear draft` in its place, and only deletion keys reach the editor. An operator who typed a message and pressed the habitual send key cannot approve a parked call by accident; on a safety rail the ambiguous key resolves away from allow.
 
 ### Deterministic Headless Behavior
 
@@ -344,10 +376,19 @@ On every settled `turn_end`, the finish-contract assessor scans entries since th
 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 verification scripts and the frontend check), passed dispatch receipts, and protected-artifact validation records.
+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`.
 4. Otherwise, the contract engages with `unvalidated_mutation`.
 
+The finish assessment projects only onto the canonical completion-evidence
+axis. `validation_evidence` becomes `evidenced`, `unvalidated_mutation` becomes
+`incomplete`, `explicit_limitation` becomes `limited`, and `no_mutation`
+becomes `not_applicable`. The worker receipt's autonomy grade belongs to the
+separate autonomy-enforcement axis. Even `enforced` autonomy cannot promote
+completion evidence. The canonical state vocabulary, attribution rules, and
+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.
 

package/docs/scientific-validation.md

@@ -1,11 +1,15 @@
 # Clio Coder Scientific Validation Contracts
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive numerical tolerance calculator and HPC queue execution simulator is located at [docs/html/validation_blueprint.html](html/validation_blueprint.html) (Version: 0.3.3).
+> **Interactive Spec Available:** An interactive numerical tolerance calculator and HPC queue execution simulator is located at [docs/html/validation_blueprint.html](html/validation_blueprint.html) (Version: 0.3.6).
 
 Scientific software development cannot treat simple file presence as proof of correctness. A simulation script that crashes on rank 48, or writes out NetCDF arrays filled with `NaN`s, may still successfully write a file to the disk. 
 
-Clio Coder recognizes **scientific validation contract files** as an opt-in signal for a higher evidence bar. In v0.3.3, core Clio does not parse or enforce a scientific contract schema. The presence of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md` at the workspace root raises the default rigor level to `high`; the file contents are advisory material for developers, project agents, and external validators.
+Clio Coder recognizes **scientific validation contract files** as an opt-in signal for a higher evidence bar. In v0.3.6, the session rigor resolver does not parse or enforce a scientific contract schema. The presence of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md` at the workspace root raises the default rigor level to `high`; the file contents are advisory material for developers, project agents, and external validators.
+
+This advisory convention is separate from the executable project verifier catalog at `.clio-coder/verifiers.yaml`. The verifier catalog has a strict version-1 schema and admits exact argv vectors to the `verify` tool. Scientific validation contracts and handbook expectations do not grant command authority: prose such as `validators: ["python tools/check_grid.py"]` remains guidance until the project owner confirms the equivalent argv, cwd, timeout, and tags in `verifiers.yaml`. The executable catalog does not interpret numerical tolerances or artifact expectations; it only runs the explicitly declared process vector through safe-exec.
+
+`clio-coder verifiers author` can inspect top-level `validators` entries in the YAML contract filenames above and propose catalog checks. It labels those vectors as project-declared and shows their source index, exact argv, cwd, timeout, tags, catalog path, and resulting execution authority. This inspection is read-only. A command string with sound quoting and no shell operator can be represented as argv for review; shell expansion, pipes, redirection, environment assignments, incomplete quoting, and Markdown prose receive a manual JSON-argv diagnostic. Nothing becomes executable and nothing is dry-run until the operator confirms the catalog write with `--yes`.
 
 The convention below is a recommended shape for scientific projects that need to document expected dimensions, attributes, numerical tolerances, scheduler context, and verification commands for scientific artifacts. Developed at the [Gnosis Research Center (GRC)](https://grc.iit.edu) at Illinois Tech as part of the NSF-funded scientific-software context (NSF Award [#2411318](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2411318)), this convention links execution metadata with physical output checks without claiming that the current harness executes those checks automatically.
 
@@ -51,6 +55,20 @@ notes: |
   Re-run check_grid.py after job completion is observed.
 ```
 
+The `validators` values above are intentionally advisory shell-like prose. Preview the exact catalog proposal with `clio-coder verifiers author`, or declare the Python validator manually without granting free-form shell interpretation:
+
+```yaml
+# .clio-coder/verifiers.yaml
+version: 1
+checks:
+  - id: validate-grid
+    description: Validate the generated regional grid
+    command: [python, tools/check_grid.py, out/region_west.nc]
+    cwd: .
+    timeoutMs: 120000
+    tags: [scientific, netcdf]
+```
+
 ### Suggested Fields:
 1. **`version`:** Set to `1` for project-local compatibility.
 2. **`runtime.kind`:** Document execution mode (`local`, `slurm`, `mpi`, or `other`).
@@ -77,7 +95,7 @@ Comparing floating-point values in scientific computations must accommodate roun
 
 ## Common Scientific Artifact Families
 
-The following labels are useful project conventions for validation contracts and reports. They are not a closed, core-enforced enum in v0.3.3:
+The following labels are useful project conventions for validation contracts and reports. They are not a closed, core-enforced enum in v0.3.6:
 
 - **`HDF5` / `NetCDF` / `Zarr`:** Multi-dimensional scientific array files.
 - **`FITS`:** Flexible Image Transport System (used in astrophysics).

package/docs/session-lifecycle.md

@@ -1,6 +1,6 @@
 # Session Lifecycle
 
-This document is the authoritative specification for Clio Coder interactive and headless session lifecycles, on-disk ledger structures, tree-based conversation branching, checkpoints, and recovery protocols in `v0.3.3`.
+This document is the authoritative specification for Clio Coder interactive and headless session lifecycles, on-disk ledger structures, tree-based conversation branching, checkpoints, and recovery protocols in `v0.3.6`.
 
 Source implementations: `src/engine/session.ts` and `src/domains/session/`.
 
@@ -39,11 +39,11 @@ export interface ClioSessionMeta {
   piMonoVersion: string;
   platform: string;
   nodeVersion: string;
-  sessionFormatVersion?: number; // CURRENT_SESSION_FORMAT_VERSION = 3
+  sessionFormatVersion?: number; // CURRENT_SESSION_FORMAT_VERSION = 4
 }
 ```
 
-Format version `CURRENT_SESSION_FORMAT_VERSION = 3` (`src/engine/session.ts:66`) is stamped on all sessions created in `v0.3.3`. Sessions with missing or earlier format versions trigger schema migrations in `src/domains/session/migrations/` on `/resume`.
+Format version `CURRENT_SESSION_FORMAT_VERSION = 4` (`src/engine/session.ts`) is stamped on all sessions created since the working-set layer landed. Version 4 adds the `contextEviction` and `contextRecall` ledger kinds. `runMigrations` in `src/domains/session/migrations/` rejects both directions on `/resume`: a missing or earlier version names the remedy (remove the session directory), and a version from the future says the session was written by a newer Clio and must not be read by this build.
 
 ---
 

package/docs/skills-marketplace.md

@@ -1,7 +1,7 @@
 # Skills Marketplace
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/skills_blueprint.html](html/skills_blueprint.html) (Version: 0.3.3).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/skills_blueprint.html](html/skills_blueprint.html) (Version: 0.3.6).
 
 The Skills Hub (`/skill`) shows project skills, user skills, and the marketplace. Every marketplace row comes from the same local lookup that `clio-coder skills install <name>` and `/skill <name>` resolve through, so the hub lists nothing it cannot install.