@iowarp/clio-coder 0.3.0 → 0.3.2

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.0).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/tools_blueprint.html](html/tools_blueprint.html) (Version: 0.3.2).
 
 Clio Coder keeps the model-facing envelope stable and moves enforcement into the runtime registry and safety policy.
 
@@ -13,9 +13,28 @@ The chat loop compiles one provider-facing system prompt for a session. The comp
 
 The compiled prompt is reused byte-for-byte on ordinary submits. It recompiles only when that key changes or when config hot-reload invalidates the prompt cache. Path-scoped project rules can therefore recompile the prompt when a matching file enters working context. When recompilation changes the text, the session ledger records a `promptRecompiled` entry with the previous hash, new hash, and token estimate.
 
+The disk fragments under `src/domains/prompts/fragments/` are layered by who reads them. `identity.clio` and `operating.contract` are constitutional: they render for every reader, name no tool, and state what is always true about Clio and her harness. `operating.delegation` (fleet coordination, receipts, spot-checks, shared `[worker result]` notes) renders only when `dispatch` is on the session's tool surface, and `operating.skills` (skill-shaped tasks, `/skill <name>` suggestions) only when `context` is; a fragment that teaches a tool is absent when the tool is, the same rule the Fleet block follows. `identity.docs-routing`, the directive to call `context(scope="docs")` before answering a question about Clio herself, follows the `context` gate too, while `identity.self-awareness` (installed paths, code outranks docs, configuration locations) names no tool and is unconditional. `operating.worker` (the assigned-task contract) renders only for dispatched workers, which never see the coordinator fragments. `safety.<level>` states what runs, what is approval-required, and what is blocked at the effective autonomy, in the safety net's action-class vocabulary (read, write, command, `system_modify`, `git_destructive`) and never by tool name, so the same body is true on every surface; the session and every worker read that one body, and what "approval-required" resolves to is the only role text (one operator confirmation for the session, the worker's `onPermission` routing for a worker).
+
 Prompt extensions can add dynamic fragments for project rules, the operator profile, and Clio source-tree awareness. Pending skill requests and middleware reminders are visible text in the user message, not hidden prompt machinery.
 
-The Tool Contract section of the prompt renders a fixed set of base lines plus one optional guidance sentence per tool, sourced from the tool registry (`ToolMetadata.promptHint` in `src/tools/registry.ts`, assigned in `src/tools/bootstrap.ts`). The base lines cover the complete-surface rule, tool-free answering, orientation preferences, a deterministic routing order (structured observation before bash, task board for multi-step work, bounded dispatch with receipt synthesis, validation before final claims), failure recovery through `context(scope="docs")` instead of blind retries, and the skill-listing gate (skill-shaped tasks or explicit operator skill requests only). The chat loop derives the hint list once from the session's frozen tool surface at compile time, and the compiler renders the hints sorted by tool name, so the compiled text depends only on which hinted tools are on the surface. Today five tools carry hints: `ask_user`, `code_nav`, `context`, `dispatch`, and `tasks`. Removing a tool from the surface removes its hint with no compiler change; adding a hint to a tool is a deliberate prompt-text change that must land with updated prompt contract tests and a CHANGELOG note.
+## Prompt template expansion
+
+Prompt templates expand into the operator's user message before submission. They do not alter the compiled system prompt or bypass the trust check on project-scope compatibility roots. The prompt-root locations, frontmatter fields, and trust rules are documented in [extensions-and-sharing.md](extensions-and-sharing.md#prompt-templates).
+
+Arguments after `/template-name` use shell-style command argument parsing. Single or double quotes keep spaces inside one argument. The template body may use `$1` through `$9` for positional arguments, `$@`, and `$ARGUMENTS` for every parsed argument joined with spaces, as well as argument slices. A positional placeholder with no matching argument expands to an empty string. Template names that collide with built-in slash commands fail closed with a diagnostic and are excluded from `/prompts`.
+
+## Directory-scoped handbook overrides
+
+In addition to project root `CLIO-CODER.md` handbooks, Clio supports directory-scoped `CLIO-CODER.override.md` files:
+- An override handbook replaces inherited project instructions for its containing directory and all descendants.
+- Sibling directories outside the subtree continue to inherit from the root handbook or their own local overrides.
+- Deeper subtrees within the directory may add further localized guidance.
+- Prompt blocks preserve explicit source paths for attribution and debugging.
+- Malformed override files fail closed rather than injecting partial guidance, and context resets never delete override files.
+
+`wiki.page` and `wiki.plan` (`src/domains/prompts/fragments/wiki/*.md`) load through this same loader, with the same id/version/content-hash contract as every other fragment, but they are consumed differently: `context/wiki/prompts.ts` reads them by id, substitutes per-dispatch `{{token}}` placeholders (a page's path, title, and relative path; the plan file's path), and sends the result as a wiki-generation dispatch's `task`, never as a compiled system prompt. `{{token}}` substitution has no home in the fragment loader itself, the same division `identity.self-awareness`'s `{TOKEN}` placeholders use in `compiler.ts`: the loader hands back a raw body, and the one caller that needs live values fills them in. Both files' bodies open and close on a standalone `---` line that predates their frontmatter and was kept unchanged as body text so the substituted prompt stays byte-identical to what the old hand-rolled `readFileSync` produced.
+
+The Tool Contract section of the prompt renders a fixed set of base lines plus one optional guidance sentence per tool, sourced from the tool registry (`ToolMetadata.promptHint` in `src/tools/registry.ts`, assigned in `src/tools/bootstrap.ts`). The base lines cover the complete-surface rule, the harness model (direct tools, fleet workers, skills as distinct capability sets), the capability-inventory rule, tool-free answering, the narrow-orientation tool list, validation before final claims, and failure recovery through `context(scope="docs")` instead of blind retries. Delegation, the tasks board, and skill listing are not restated here: `operating.delegation`, the `tasks` hint, and `operating.skills` each say their rule once and render exactly when their tool is on the surface. The one fleet-routing sentence (`FLEET_ROUTING_GUIDANCE`) renders when `dispatch` carries a hint and says only that the `agent` id is pinned from the Fleet section and `agent:"auto"` is a fallback. The chat loop derives the hint list once from the session's frozen tool surface at compile time, and the compiler renders the hints sorted by tool name, so the compiled text depends only on which hinted tools are on the surface. Today five tools carry hints: `ask_user`, `code_nav`, `context`, `dispatch`, and `tasks`. Removing a tool from the surface removes its hint with no compiler change; adding a hint to a tool is a deliberate prompt-text change that must land with updated prompt contract tests and a CHANGELOG note.
 
 ## One tool surface per session
 
@@ -29,7 +48,9 @@ Providers that cannot call tools receive no schemas, and the prompt tells the mo
 
 ## Canonical worker harness
 
-Native and mediated dispatch workers use a separate prompts-domain compiler over the same loaded fragment table. Its stable system prompt has exactly five sections: identity-lite, the shared operating contract plus assigned-task rules, a tool contract sliced to the final canonical toolkit, safety for the single effective autonomy, and one final persona. A request persona override replaces only the recipe body; eligible bound-skill instructions are composed inside that same final persona and never widen tools.
+Native and mediated dispatch workers use a separate prompts-domain compiler over the same loaded fragment table. Its stable system prompt has five fixed sections plus one optional trailing one: identity-lite, the constitutional operating contract plus the `operating.worker` assigned-task contract, a tool contract sliced to the final canonical toolkit, the same `safety.<level>` fragment the session reads for the single effective autonomy under a worker one-liner that carries the run's permission routing, one final persona, and the operator-editable layer when either of its parts renders non-empty: active project rules scoped to this run's inferred working context, and the operator profile. A request persona override replaces only the recipe body; eligible bound-skill instructions are composed inside that same final persona and never widen tools.
+
+The operator-editable layer reaches a worker through `additionalFragments`, the same channel `compile()` uses for the session, so nothing splices into an existing section. The operator profile renders unconditionally, capped, the same as it does for the session: it governs how the worker should do the task (validation preference, commit-message style, local-only paths), not only how the orchestrator talks to the operator. Project rules are scoped to the worker's working context rather than shipped wholesale. That context is `writeRoots`, when the caller sets them, plus path-like tokens recalled from the task and briefing text, since the model-facing dispatch tool has no structured path field. A missed path token means a rule can go unseen; it can never fabricate one, because `selectActiveRules` still requires a real glob match.
 
 The compiler runs after target capability and tool-profile admission. Its canonical tool names are the same names transported in `WorkerSpec.allowedTools` and attached as schemas; routine non-Scout work removes `code_nav`, narrow profiles remove their excluded schemas and guidance, tool-incapable targets get an explicit no-tools contract, and Claude SDK aliases are filtered from the same canonical set. ACP's external inventory is unknown, so ACP bounded-role admission continues to validate the unchanged raw persona rather than fabricating a complete native schema list.
 
@@ -65,7 +86,7 @@ Several tools absorb what used to be separate tools:
 - `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.
-- `artifact(kind="plan"|"review"|"report", content, ...)` writes named artifacts behind one surface: Markdown documents (default `PLAN.md`/`REVIEW.md`/`REPORT.md` at the project root; `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.
+- `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.
 - `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.

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.0).
+> **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.2).
 
 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.
 
@@ -72,12 +72,12 @@ export const myCustomRuntime: RuntimeDescriptor = {
 
 ## 2. Probing Mechanisms
 
-Probes discover the current state of a target inference server when Clio starts or when `/targets` / `/models` are refreshed.
+Probes discover the current state of a target inference server when Clio starts or when `/targets` or `/model` are refreshed.
 
 ### 2.1 Endpoint Probing (`probe`)
 The `probe` method validates endpoint reachability and collects loaded models:
 
-* **Inputs:** `TargetDescriptor` (which holds target `url`, optional `apiKey`, and connection metadata) and `ProbeContext` (which provides timeout signals and credentials).
+* **Inputs:** `TargetDescriptor` (which holds target `url`, optional `apiKey`, and connection metadata) and `ProbeContext` (which provides timeout signals and credentials). Request paths that resolve OAuth through `providers.auth.resolveForTarget` must pass `{ signal }`; Pi 0.84's `AuthOperationOptions` keeps cancellation attached while Clio waits for or mutates its credential store.
 * **Return Value:** A `ProbeResult` indicating:
   * `ok`: True if reachable.
   * `serverVersion`: String identifier of the backend (e.g. `"Ollama/0.1.48"`).
@@ -92,6 +92,23 @@ Clio caches this result under the session's provider cache, preventing redundant
 ### 2.3 Exact-ID Capability Selection (`probeCapabilitiesForModel`)
 `probeCapabilitiesForModel` is the one exact-id selector during capability resolution. When a router target serves several models, `probeCapabilitiesForModel` matches `probeModelCapabilities` keyed strictly to the requested wire model ID. A router serving multiple models thus answers only from the `/v1/models` row keyed to its own wire model, preventing capability flags or token limits from bleeding across different models on the same target.
 
+### 2.4 LM Studio as a reference adapter
+
+The built-in `lmstudio` adapter is an example of one canonical descriptor with a compatibility
+alias. Its descriptor declares `aliases: ["lmstudio-native"]`, while registry listing and persisted
+configuration use only `lmstudio`. The probe first requires the exact `/lmstudio-greeting` body for
+a directly configured target. It lists keys, loaded instance ids, capabilities, and echoed load
+configuration through `GET /api/v1/models` (<https://lmstudio.ai/docs/developer/rest/list>), falls
+back to `/api/v0/models` for older servers, and uses `/v1/models` only when neither native model
+shape is available.
+
+Chat synthesis stays on the ordinary `openai-completions` family and joins the target URL to
+`/v1/chat/completions` (<https://lmstudio.ai/docs/developer/openai-compat/chat-completions>). Native
+REST is reserved for model management through the documented load and unload operations
+(<https://lmstudio.ai/docs/developer/rest/load> and
+<https://lmstudio.ai/docs/developer/rest/unload>). This split avoids a second streaming parser while
+still exposing runtime-specific residency and capability data.
+
 ---
 
 ## 3. Model Synthesis
@@ -111,6 +128,42 @@ The `synthesizeModel` method acts as the factory that creates the `pi-ai` compat
   2. Instantiate the adapter client (e.g., building a `pi-ai` OpenAI or Anthropic provider instance).
   3. Bind custom prompt templates and FIM (Fill-in-the-Middle) properties where supported.
 
+
+### 3.1 Stream Filters and Sentinel Stripping
+
+When a model family requires response parsing or sentinel stripping before the payload reaches the core logic, Clio applies runtime-agnostic stream filters during model synthesis. For example, if the resolved model family is `gemma-4`, a dedicated `createGemmaChannelFilter` is applied to intercept and reclassify `<|channel>thought` markers directly from the `text_delta` stream into `thinking_delta` events, dropping orphan channel closers and own-thought labels seamlessly.
+
+### 3.2 OpenAI-compatible sampling and vLLM budgets
+
+Catalog entries keep Clio's family knowledge in `quirks.sampling`, using the typed names
+`temperature`, `topP`, `topK`, `minP`, `presencePenalty`, `frequencyPenalty`, and
+`repeatPenalty`. The OpenAI-completions engine adapter translates those names once and passes the
+result through Pi's `StreamOptions.samplingParams`; it does not patch sampler fields into the final
+JSON body. Request-level `samplingParams` win per key, matching Pi's merge contract, while an
+explicit request temperature still wins over the catalog temperature.
+
+For a `vllm` target, model synthesis opts into Pi's
+`OpenAICompletionsCompat.supportsThinkingTokenBudget`. Clio supplies the selected family's
+`quirks.thinking.budgetByLevel` as Pi `thinkingBudgets`, and Pi emits the top-level
+`thinking_token_budget` while retaining at least 1,024 tokens beneath `max_tokens` for the final
+answer. llama.cpp and LM Studio do not receive that vLLM-only field. Their remaining payload hooks
+are limited to runtime deltas such as `chat_template_kwargs`, prompt-cache flags, LM Studio TTL and
+draft-model settings, and the exact reasoning-effort spelling their servers accept.
+
+Local OpenAI-compatible model synthesis also declares
+`OpenAICompletionsCompat.supportsFinishReason: false`. Pi then infers `stop` or `toolUse` at the end
+of a complete stream when a local server omits `finish_reason`, instead of turning an otherwise
+valid answer into a provider error. Explicit finish reasons remain authoritative when supplied.
+
+Anthropic thinking is assembled by Pi, not by Clio. Pi's `streamSimple` maps the agent's thinking
+level onto `thinking.type: "adaptive"` plus `output_config.effort` (read from the model's
+`thinkingLevelMap` and `compat.forceAdaptiveThinking`) or onto a bounded `budget_tokens` for
+budget-based models. Clio's `onPayload` hook no longer rewrites those fields; it only sets the
+OpenAI Responses `reasoning.summary` verbosity, which the agent loop cannot express as an option.
+`tests/contracts/thinking-runtime.test.ts` captures the wire payload Pi builds and proves Clio
+leaves it untouched.
+
+
 ---
 
 ## 4. Configuring Reasoning & Thinking Formats
@@ -121,7 +174,7 @@ Clio supports diverse thinking mechanisms. If your model family uses a custom fo
 | --- | --- |
 | `none` | **Reasoning-Never:** Clio strips thinking request fields (e.g., effort levels), avoids replaying thinking blocks in history, emits no TUI thinking events, and records no reasoning token usage metrics. |
 | `ollama-native` | Standard Ollama native thinking streams. |
-| `lmstudio-native` | Assistant thinking is prepended to output payloads wrapped in `<think>` and `</think>` tags. |
+| `lmstudio` | Uses OpenAI-compatible chat and consumes streamed `reasoning`; thinking control uses only `reasoning_effort`. |
 | `openai-completions` | Replays thinking blocks via `reasoning_content` message parameters. |
 | `anthropic-max` | Anthropic extended thinking block protocol. |
 

package/docs/release-cut-checklist.md

@@ -1,138 +1,156 @@
-# v0.3.0 Release-Cut Checklist
+# v0.3.2 Release-Cut Checklist
 
-The ordered steps that turn the prepared `v0.3.0` branch into a published
+The ordered steps that turn the prepared `v0.3.2` branch into a published
 release. Everything above the line marked **AUTHORIZATION BOUNDARY** is
-repeatable and reversible and was run during the hardening sessions. Everything
-below it is external or destructive, was deliberately **not run**, and needs an
-explicit decision from the operator.
-
-Nothing in this checklist has been performed against `main`, a remote, a tag,
-or the npm registry.
+repeatable and reversible and is run locally before the cut. Everything below
+it is external or irreversible and needs an explicit decision from the
+operator. Issue #112 is the release umbrella and carries the live state of
+every step; this page is the procedure.
 
 ## Status of the prepared tree
 
 | Item | State |
 | --- | --- |
-| Branch | `v0.3.0`, local only |
-| `package.json` version | `0.3.0`, **not bumped by the hardening sessions** |
-| `main` | untouched |
-| Remotes | not contacted |
-| Tags | none created |
-| npm registry | not contacted |
+| Branch | `v0.3.2`, local only; no remote `v0.3.2` branch |
+| `package.json` version | `0.3.2`; the top `CHANGELOG.md` heading is `## 0.3.2 - 2026-08-20` |
+| `main` | fast-forwarded prematurely to `c4c344ba` during Eneko's port integration and pushed. It is an ancestor of `v0.3.2`, must not move backward, and is fast-forwarded again only at Part 4. |
+| `origin/main` | `c4c344ba`, the same premature push |
+| Tags | none for 0.3.2, local or remote |
+| GitHub Release | none for 0.3.2 |
+| npm registry | `@iowarp/clio-coder@0.3.2` absent; `latest` is `0.3.1` |
+| 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. |
 
 ---
 
-## Part 1: verification (repeatable, already run)
+## Part 1: verification (repeatable)
+
+Run against the exact final candidate with `NO_COLOR` unset and
+`TERM=xterm-256color`, so the color-sensitive tests see a real terminal.
 
 1. `npm run typecheck`
-2. `npm run lint`
-3. `npm run check:boundaries`
+2. `npm run lint` (Biome plus the hygiene checks, which include the boundary invariants and the skills pin check)
+3. `npm run skills:check`
 4. `npm run build`
 5. `npm run test`
 6. `npm run test:trace-viewer`
-7. `npm run ci` (runs 1, 2, `skills:check`, 4, 5, 6)
-8. `npm run ci` again under the other supported Node major. Both Node 22 and
+7. `npm run ci` (runs 1 through 6)
+8. `npm run ci:release` (7 plus `scripts/check-release.mjs`: dist shebang
+   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.
-9. `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.
-10. `npm run ci:release`, which adds `scripts/check-release.mjs`: dist shebang
-    integrity, the forbidden-file list, the required runtime resources, and the
-    tarball and unpacked size budgets.
-
-## Part 2: version and notes (repeatable, NOT run)
-
-These edit the working tree only. They are reversible with `git checkout` and
-are listed here because the hardening sessions were explicitly scoped out of
-performing them.
-
-11. Decide the released version. The tree currently reads `0.3.0` in
-    `package.json`. If that is the number to publish, no bump is needed; confirm
-    it deliberately rather than by default.
-12. Files carrying a version reference, to update together if the number
-    changes:
-    - `package.json` (`version`)
-    - `CHANGELOG.md` (the `## 0.3.0 - <date>` heading and its date)
-    - `docs/environment-variables.md` and `docs/tui-design.md` (the
-      `(Version: 0.3.0)` markers on the interactive-blueprint tips)
-    - `docs/html/*.html` (the `Blueprint (v0.3.0)` titles)
-    - `scripts/check-release.mjs` (the measured-at figures in the budget
-      comment, if the package size moved materially)
-13. Confirm the `## 0.3.0` section of `CHANGELOG.md` describes every
-    user-visible behavior change in the release, including the ones that alter
-    existing behavior:
-    - unknown slash commands now fail instead of reaching the model as chat
-    - `--remove-binary` launcher ownership is identity, not a path shape
-    - `reset` and `uninstall` exit 1 on partial failure instead of reporting
-      success
-14. Re-run `npm run ci:release` after any version edit.
-15. Commit the version and notes as one commit on `v0.3.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.
+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;
+    `docs/html/`, `apps/workbench`, `.superpowers`, `tests/`, `scripts/`,
+    `benchmarks/`, scratch files, and source maps are absent. Record the
+    filename, packed and unpacked sizes, integrity, and shasum.
+12. Install that tarball into a clean temporary prefix with empty XDG roots and
+    verify `--version`, `--help`, an empty-state non-TTY launch, `doctor`, and
+    `uninstall --dry-run` without developer-local state.
+
+## 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.2 - <date>`
+    heading in `CHANGELOG.md`, the `(Version: 0.3.2)` markers in `docs/*.md`,
+    the `Blueprint (v0.3.2)` 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.2` 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.2`.
+
+## Part 3: present the gate
+
+16. Report to the operator before touching `main`: the exact final `v0.3.2`
+    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
+    deferred live check, confirmation that no tag, GitHub Release, or npm
+    version exists yet, the proposed commands for Parts 4 through 6, and the
+    proposed npm dist-tag. The dist-tag is the operator's call; never guess it.
 
 ---
 
 ## AUTHORIZATION BOUNDARY
 
 Every step below leaves the local checkout, is externally visible, or cannot be
-undone by a local `git` command. **None of them has been run.**
-
-## Part 3: clean-install verification (external, NOT run)
-
-16. **NOT RUN** — `npm pack` and install the resulting tarball into a fresh
-    temporary prefix on a machine that has never had Clio installed, with empty
-    XDG roots. `npm run test:lifecycle` covers this on the development machine;
-    a second machine is what proves no developer-local state is load-bearing.
-17. **NOT RUN** — From that install, verify: `clio-coder --version`, `clio-coder --help`,
-    an empty-state non-TTY launch, `clio-coder configure` to a real target,
-    `clio-coder doctor`, one real turn, and `clio-coder uninstall --dry-run`.
-18. **NOT RUN** — Inspect the artifact by hand: `tar -tzf` the tarball, confirm
-    no source maps, no `scripts/`, no `tests/`, no `benchmarks/`, no
-    `apps/trace-viewer`, and that `skills/`, `docs/*.md`, `docs/html/`, the
-    builtin agents, the model catalogs, and `damage-control-rules.yaml` are all
-    present.
-
-## Part 4: branch integration (destructive to history, NOT run)
-
-19. **NOT RUN** — Decide how `v0.3.0` reaches `main`. The hardening sessions
-    were forbidden to merge, rebase, or modify `main`, so no integration
-    strategy has been chosen or attempted.
-20. **NOT RUN** — Integrate, then re-run `npm run ci:release` on the integrated
-    result. A gate that passed on the branch has not passed on the merge.
-
-## Part 5: tag and push (external, NOT run)
-
-21. **NOT RUN** — `git tag -a v0.3.0 -m "..."`.
-22. **NOT RUN** — `git push origin <branch>`.
-23. **NOT RUN** — `git push origin v0.3.0`.
-
-## Part 6: publication (external and irreversible, NOT run)
-
-24. **NOT RUN** — `npm publish`. Note that `prepublishOnly` runs
-    `npm run ci:release`, so publication re-gates the tree; that is a safety
-    net and not a substitute for step 20.
-25. **NOT RUN** — Decide the dist-tag. Publishing to `latest` makes this the
-    default install for every user. An experimental release may warrant
-    `--tag next` instead; the CLI and README both describe v0.3.0 as
-    experimental, which argues for it.
-26. **NOT RUN** — A published version cannot be replaced. `npm unpublish` is
-    restricted and time-limited, and a mistake is corrected by publishing a
-    higher version, not by removing the wrong one.
-
-## Part 7: post-publish verification (external, NOT run)
-
-27. **NOT RUN** — On a clean machine, `npm install -g @iowarp/clio-coder` from
-    the registry rather than from a local tarball, then repeat step 17 against
-    it. This is the only step that tests what users actually receive.
-28. **NOT RUN** — Verify `clio-coder upgrade` finds and applies the published
-    version from an installation of the previous release.
-29. **NOT RUN** — Publish the GitHub release with the `CHANGELOG.md` section
-    for this version.
+undone by a local `git` command. None of them runs without the operator
+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.2` tip and confirm no other
+    worktree has `main` checked out.
+18. `git checkout main && git merge --ff-only v0.3.2`. 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.2` and the GitHub Release do not exist, then
+    `git tag -a v0.3.2 -m "Clio Coder 0.3.2"` on the green SHA and
+    `git push origin v0.3.2`.
+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.2`
+    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.2` 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.1` 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
+    time-limited; a mistake is corrected by publishing a higher version.
+
+## Part 7: post-publish verification and follow-ups
+
+27. `npm view @iowarp/clio-coder@0.3.2` 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.1, verify `clio-coder upgrade` finds and
+    applies 0.3.2.
+30. Close #112 with the SHA, CI URL, tag, GitHub Release URL, npm version and
+    dist-tag, tarball evidence, and the post-publish verification.
+31. Maintainer follow-up, independent of the release: verify the commit
+    provenance email `clio-coder@iowarp.ai` on IOWarp-controlled GitHub and
+    GitLab identities such as `clio-coder-bot` or `iowarp-clio`, and upload
+    `assets/clio-coder-avatar-512.png` as the account avatar where PNG is
+    required. Commit data itself cannot carry a logo, so this affects only how
+    those platforms render the trailers, never whether attributed commits or
+    the release work. Clio never creates accounts or performs remote
+    operations for this.
 
 ---
 
 ## Rollback
 
-There is no rollback for step 24. If a defect is found after publication, the
-correction is a patch release. Before step 24, every step is reversible:
-steps 21 through 23 by deleting the local and remote tag and force-updating the
-branch, and steps 11 through 15 by `git reset`.
+There is no rollback for step 25. Before it, every step is reversible: steps
+21 and 22 by deleting the local and remote tag and the draft release, steps 17
+through 19 by a new forward commit on `main` (never by rewriting it), and
+everything in Parts 1 and 2 by `git checkout`.

package/docs/safety-model.md

@@ -1,11 +1,11 @@
 # 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.0).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/safety_blueprint.html](html/safety_blueprint.html) (Version: 0.3.2).
 
 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.
 
-Source of truth: `src/domains/safety/**`, `src/tools/registry.ts`, `src/tools/bootstrap.ts`, `src/tools/policy.ts`, `src/entry/orchestrator.ts`, `src/domains/dispatch/write-boundary.ts`, and `damage-control-rules.yaml`.
+Source of truth: `src/domains/safety/**`, `src/tools/registry.ts`, `src/tools/bootstrap.ts`, `src/tools/policy.ts`, `src/entry/orchestrator.ts`, `src/domains/dispatch/write-boundary.ts`, `src/interactive/view/artifacts.ts`, and `damage-control-rules.yaml`.
 
 ---
 
@@ -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.0, 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.2, 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
 
@@ -27,12 +27,15 @@ In Clio Coder v0.3.0, effective autonomy resolution is strictly centralized in `
 | `system_modify` | deny | ask | ask | ask |
 | `git_destructive` | net block | net block | net block | net block |
 | `unknown` | deny | ask | ask | ask |
+| `read`: a gate declaring `exposure: outward` | allow | ask | ask | allow |
 
 - **`read-only`**: Clio inspects and answers. Mutating calls are auto-denied with a rejection telling the model to propose the change instead; approvals are never invoked. Denials render as `[autonomy]` notices.
 - **`suggest`**: every non-read action parks for one-shot approval. The operator drives.
 - **`auto-edit`**: workspace edits and recognized commands run; unrecognized bash asks instead of blocking.
 - **`full-auto`**: bash runs without prompting; the net is the protection, not the prompt. `system_modify` still asks because it reaches outside the workspace; `unknown` still asks because the net cannot reason about calls it cannot classify.
 
+The exposure tier is the one row keyed by the call rather than by its action class. A call may declare `exposure: outward` when answering it publishes or sends something the operator cannot quietly take back: filing an issue or a PR, posting a comment, pushing a branch, cutting a release. Today `ask_user` is the only tool that declares one, so a skill marks its own confirmation step outward and `auto-edit` parks that gate for the operator instead of answering it. Acting on the workspace without asking is not the same permission as publishing without asking. `suggest` parks it too, because the dial is ordered and a stricter level must never gate a surface less than the looser one below it. `full-auto` answers outward gates like everything else, `read-only` still answers them because the outward effect being confirmed is denied there anyway, and the tier only ever adds an ask: it never widens a row the action class already denied. The tier is declared, never inferred, because only the caller knows whether the step it is confirming leaves the machine; a value the schema does not recognize reads as `outward` and the call is then rejected, so a misspelled tier costs one prompt rather than silently downgrading the gate.
+
 The `system_modify` confirm is level-invariant, so it is enforced and attributed as a safety-net confirm rail: the overlay, notices, and audit ledger name the net (reason code `system-modify-confirm`, policy source `builtin-classifier`), not the autonomy level. The matrix row above is unchanged in outcome at every level; only `read-only` converts the ask to a denial. `unknown` remains in the autonomy mapping because the registry substitutes a registered tool's base action class after the net evaluates.
 
 The level is persisted as `autonomy` in `settings.yaml`, hot-reloads, and is edited in the `/settings` Autonomy & Safety section.
@@ -72,7 +75,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 with a standard, unified visible toolset. The 19 built-in tools are 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 the registered specs can never drift apart silently.
+Clio operates under a single operating posture with a standard, unified visible toolset. The 20 built-in tools are 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 the registered specs can never drift apart silently.
 
 | Plane | Tools | Action class |
 | --- | --- | --- |
@@ -86,10 +89,14 @@ Clio operates under a single operating posture with a standard, unified visible
 | 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` and `tasks` never mutate a run or the workspace, so they stay read class inside the ORCHESTRATE plane. `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. 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.
 
+### Workspace artifact reads
+
+The `/view` workspace category treats a recorded successful write as a durable fact, not as permanent read authority over that pathname. Immediately before every file load, the viewer resolves both the recorded workspace root and selected target through the live filesystem, checks canonical path-segment containment, and reads the canonical target. It does not cache the canonical workspace root between provider construction and load. A file or ancestor directory swapped to a symlink outside the current workspace is refused without reading the outside target. An `ENOENT` from re-resolution or loading keeps the durable `file no longer on disk (recorded at ...)` result instead of dropping the artifact row.
+
 ---
 
 ## Skill tool surface narrowing
@@ -137,7 +144,7 @@ Every tool call entering the safety engine passes through a strict 10-step evalu
 2. **Write-Root Containment**: Verifies that mutations remain within configured write boundaries (`evaluateWriteRoots`).
 3. **Hard Blocks**: Enforces unconditional blocks against destructive actions (such as `git_destructive` operations and zero-access credentials).
 4. **Invalid Project Policy Fail-Closed**: If `.clio-coder/safety.yaml` contains parsing or schema errors, execution tools fail closed.
-5. **Path Policy Enforcement**: Evaluates `zeroAccessPaths`, `readOnlyPaths`, and `noDeletePaths`.
+5. **Path Policy Enforcement**: Evaluates `zeroAccessPaths`, `readOnlyPaths`, `noWritePaths`, and `noDeletePaths`.
 6. **Bash Zero-Access Protocol**: Rejects shell commands attempting to read, exfiltrate, or redirect from protected credential files. A safe presence-check exception (`grep -sq "^NAME=" <file>`) is permitted for environment probing without exposing secrets.
 7. **Ask Rails**: Evaluates rules requiring confirmation (such as project `requireConfirmation` or unanalyzable command substitutions `$(...)`).
 8. **System Modify Checks**: Assesses operating-system level modification commands targeting system roots (`/etc`, `/usr`, `/var`, `/bin`, `/sbin`, `/run`), exempting temporary write paths (`/var/tmp`, `/var/folders`).
@@ -159,6 +166,8 @@ zeroAccessPaths:
   - .env
 readOnlyPaths:
   - vendor/
+noWritePaths:
+  - third_party/generated/
 noDeletePaths:
   - out/validated/
 commands:
@@ -181,7 +190,7 @@ commands:
 Accepted root keys:
 
 ```text
-version | commands | tasks | disableDefaultPathPolicy | zeroAccessPaths | readOnlyPaths | noDeletePaths
+version | commands | tasks | disableDefaultPathPolicy | zeroAccessPaths | readOnlyPaths | noWritePaths | noDeletePaths
 ```
 
 `tasks` is an alias for command policy entries. Unknown keys, wrong types, duplicate command IDs, absolute `cwd`, `..`-escaping `cwd`, and invalid path-policy entries make the policy invalid.
@@ -192,9 +201,20 @@ Path-policy behavior:
 | --- | --- |
 | `zeroAccessPaths` | Blocks read, write, and delete. |
 | `readOnlyPaths` | Allows read, blocks write/delete. |
+| `noWritePaths` | Allows read, blocks write/delete. Separate from `readOnlyPaths` so the default policy can name directories Clio reads as a matter of course and must never author. |
 | `noDeletePaths` | Blocks delete. |
 | `disableDefaultPathPolicy` | Uses only project path policy rather than merging default damage-control paths. Note: This cannot disable built-in zero-access protection for critical system paths like `.git/config` and `credentials.yaml`. |
 
+The default damage-control policy populates `noWritePaths` from the interop
+agent registry: `~/.claude/`, `.claude/`, `~/.codex/`, `.codex/`, `~/.config/opencode/`,
+`.opencode/`, `~/.gemini/`, `.gemini/`, `~/.copilot/`, `~/.cursor/`, `.cursor/`,
+`~/.antigravitycli/`, `.antigravitycli/`, `~/.agents/`, and `.agents/`. Clio never writes
+into another coding agent's directory. It reads those roots for skills, prompts, and
+rule prose and has no reason to author them. A `write` or `edit` targeting any of
+these paths is refused at every posture including `auto-edit` and `full-auto`, with reason
+code `path-policy:noWritePaths`. Reads remain allowed. `.clio-coder/` is Clio's own directory
+and is untouched. `.github/` is deliberately not blocked.
+
 Command entry notes:
 
 | Field | Meaning |
@@ -232,7 +252,7 @@ After step execution, the orchestrator compares the working checkout against the
 
 Fleet dispatch is admitted only when the requested worker scope is a subset of the orchestrator scope and requested actions fit the worker scope.
 
-Dispatch workers can run the same HTTP, native, or pi-ai-backed runtimes as the orchestrator, driven through the [pi SDK family](https://www.npmjs.com/package/@earendil-works/pi-agent-core) (including `@earendil-works/pi-agent-core` and its TUI and AI wrappers). Clio observes and governs those tool calls directly, so every worker run is subject to the same safety mapping and receipt accounting as an interactive turn.
+Dispatch workers can run the same HTTP or native runtimes as the orchestrator. Clio observes and governs those tool calls directly, so every worker run is subject to the same safety mapping and receipt accounting as an interactive turn.
 
 Three integration paths exist for driving Claude Code, ranging from fully enforced to advisory gating: