@iowarp/clio-coder 0.3.1 → 0.3.3

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.1).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/tools_blueprint.html](html/tools_blueprint.html) (Version: 0.3.3).
 
 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.
 

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.1).
+> **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).
 
 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,142 +1,156 @@
-# v0.3.0 Release-Cut Checklist
+# v0.3.3 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.3` 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. This page is the procedure and the release report carries the live
+state of every step.
 
 ## 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.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` |
+| 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.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`
+    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
+    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`.
+
+## Part 3: present the gate
+
+16. Report to the operator before touching `main`: the exact final `v0.3.3`
+    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)
-
-Push the branch first and wait for `ci` to go green on that commit. The release
-workflow verifies that a successful `ci` run exists for the tagged SHA and fails
-the tag push outright if one does not.
-
-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.3` 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
+    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.
+    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.
+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.
+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.3` 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.
+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
+    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.1).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/safety_blueprint.html](html/safety_blueprint.html) (Version: 0.3.3).
 
 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.1, 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.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.
 
 ### Autonomy levels
 
@@ -89,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
@@ -248,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:
 

package/docs/scientific-validation.md

@@ -1,11 +1,11 @@
 # 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.1).
+> **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).
 
 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.1, 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.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.
 
 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.
 
@@ -77,7 +77,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.1:
+The following labels are useful project conventions for validation contracts and reports. They are not a closed, core-enforced enum in v0.3.3:
 
 - **`HDF5` / `NetCDF` / `Zarr`:** Multi-dimensional scientific array files.
 - **`FITS`:** Flexible Image Transport System (used in astrophysics).