@iowarp/clio-coder 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -2,6 +2,133 @@
 
 All notable changes to Clio Coder are documented in this file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and versions follow Semantic Versioning; pre-1.0 minor releases may include incompatible changes.
 
+## 0.4.3 - 2026-09-05
+
+This release adds Archify architecture maps and experimental Antigravity research delegation, and tightens thinking controls, session memory, compaction and execution evidence. Usage and cost reports retain explicit coverage limits; full evidence reconciliation is deferred to v0.4.5 or later.
+
+### Added
+- Remote marketplace entries. `skills/remote.yaml` lists skills whose content lives in another repository at a pinned ref; `npm run skills:pin` publishes each into `skills/skill-marketplace.json` with `origin: "remote"`, the upstream tree as `sourceUrl`, the catalog `overlay` package whose files land on top of the clone at install, and the upstream top-level members to `exclude`. The overlay `SKILL.md` is pinned in `skills/registry.yaml`, so `skills:check` fails on its drift. Install stages the fetched tree, applies the exclusions and the overlay, validates the shaped result, and swaps it in atomically; discovery lets an overlay-bearing index entry win over its own catalog folder, and `clio-coder skills update` re-applies the same shaping. Contract: `tests/contracts/skill-remote-entries.test.ts`.
+- The `archify` skill (`skills/planning/archify/`), a remote entry pinned to `tt-a1i/archify` v2.16.0: validated interactive architecture, workflow, sequence, dataflow, and lifecycle diagrams as standalone HTML from a typed JSON spec. Clio ships only the wrapper `SKILL.md` and `evals.md`; the renderer, schemas, and brand-mark notices come from upstream at install time and never enter the npm tarball. The wrapper adds Clio's placement rule (`.clio-coder/artifacts/maps/`), the repository-evidence flow through `clio-coder context map`, and `verify(check="frontend")` after `deliver`, and omits upstream's update-awareness step because it performs a network request during a chat turn.
+- `clio-coder context map [--out <path>] [--json]` writes an archify architecture seed from the codewiki index with no model call: components are the largest directory areas (capped at 12, plus at most three external packages), connections are import edges collapsed area to area, and `meta.repository` is recorded only for a GitHub origin at a full revision; only then do components carry `sources`, each citing an indexed file and its first symbol's line, since archify accepts citations only against a pinned revision. Placement is layered with explicit routes for archify's standard profile; composition warnings may still need operator edits. Pass `--repo-root .` when the seed carries pinned repository evidence. It refuses, naming `clio-coder context index`, when no index exists. Contract: `tests/contracts/context-map-seed.test.ts`.
+- `.clio-coder/artifacts/maps/` is a placement class (human transient) in `docs/architecture/artifact-placement.md`; `docs/guide/skills-marketplace.md` documents remote entries and overlays with archify as the worked example, and `docs/architecture/context-engine.md` documents the seed's guarantees.
+- A distinct, permanently read-only `world-knowledge` shadow agent handles current open-world discovery, ecosystem comparisons, broad external context, and advisory second opinions. Its compact result contract separates supported facts and source identifiers from synthesis, uncertainties, and follow-up verification, and it reports honestly when native discovery/search is unavailable instead of treating URL retrieval as search or fabricating citations.
+- Reusable `branch-closeout` Git skill (`skills/git/branch-closeout/`) for proving merged work on canonical remotes, inspecting dirty or ignored worktree state, safely removing registered worktrees through Git, deleting local branches, optionally removing contributor fork branches, and auditing surviving repository references.
+
+### Changed
+- The local and hosted CI gate checks skill pins once through lint, removing the duplicate explicit pass. The full contract/smoke, trace-viewer and release-package checks remain in place; contributor guidance distinguishes focused checks from the complete release gate.
+- The existing `context.compaction.model` and `context.compaction.systemPrompt` overrides now take effect. An explicit model must uniquely resolve to an available, eligible summary route; invalid choices fail visibly instead of silently using chat. Custom UTF-8 prompt files are reread at compaction time, must be nonempty regular files of at most 65,536 bytes, and resolve relative paths against the session workspace. Unset controls retain the active chat route and built-in prompt; checkpoints record the selected usage route while older checkpoints remain readable (#324).
+- Antigravity external delegation remains experimental and now uses a bounded external-agent subprocess boundary: it is dispatch-only, uses the operator's existing `agy` session, sends literal prompts over structured stdin, accepts only a valid one-terminal stream, bounds and redacts all external output, runs with an allowlisted environment, cancels the POSIX process group, and attributes receipts to external delegation rather than the Gemini API. Its non-generating live `{id,label}` catalog is authoritative and round-trips through the generic model snapshot; failures distinguish missing CLI, sign-in, required CLI update, unavailable catalog, and disappeared configured models. Clio records per-tool recipe budgets as unobserved/not enforced inside the external one-shot loop and never automatically retries a generating run.
+- First-run onboarding can offer **Antigravity CLI — experimental local delegation** only after a valid primary target exists. The optional step never changes chat/background pointers or enables dangerous full access; it can create a `world-knowledge-external` fleet profile and bind `world-knowledge`. Noninteractive `configure` gains `--bind-agent <agentId>` alongside `--agent-profile`, and model/target listings preserve live labels and source/freshness.
+- Hardened the entire Git skill suite under `skills/git/` (`file-ticket`, `fix-issue`, `ship`, `worktree-create`, `worktree-merge`, `resolve-merge-conflicts`). Added formal argument contracts with structural parsing; made workflow bodies project-agnostic without hardcoding repos, remotes, or branch names while preserving the canonical-main-only policy in `CONTRIBUTING.md`; required confirmation before every outward ticket action including duplicate issue comments; decoupled unsupported RCA automation claims from `fix-issue`; separated `ship` into explicit `commit`, `pr`, maintainer-local, and `closeout` modes; corrected rebase ours/theirs reversal semantics and added conflict matrices covering binary, rename, modify/delete, and lockfile conflicts; supported configurable roots, safe path derivation, and strategy controls in worktree operations; and expanded evals across all skills.
+- Branch and worktree closeout is now an explicit final development step: prove the merged result, inspect local state, remove registered worktrees through Git, delete local scaffolding, and report every surviving branch, stash, local-only tag, and canonical remote head. The canonical repository keeps only `main`: maintainer topic and compact release-candidate branches such as `v043` stay local, contributors submit branches from their forks, and dotted names such as `v0.4.3` are reserved for immutable release tags.
+
+### Fixed
+- Dedicated memory, compaction and native worker admission now discover cold LiteLLM target metadata before resolving thinking controls; sharing a gateway URL with chat no longer hides a missing target probe. Memory keeps discovery within its existing cancellation/deadline boundary, rechecks known endpoint capacity at actual launch, and does not turn cancelled metadata into endpoint failure. Compaction now sends its intended thinking-off request through the simple stream API. Workers keep their approved route and reservation while discovery runs within the invocation's cancellation and admission deadline; late cancelled metadata cannot launch a worker. Unknown runtime declarations remain unguessed.
+- Failed or empty compaction now retains known per-stream usage in the existing out-of-turn ledger, including a successful first stream before a failed or empty second split response. Rows retain the originating session and selected route, distinguish completed/error/aborted calls, and keep missing or ambiguous zero usage unknown. For completed compactions, the checkpoint remains the sole durable accounting source; checkpoint-write ambiguity fails visibly without speculative double counting. Usage reports expose known and errored subtotals with missing coverage, and live successful accounting follows the selected compaction route. Adapter prices remain estimates, and existing numeric cost ceilings bound known spending only. Usage reports read the retained failed-compaction records; eval totals and live /cost reseeding do not yet reconcile that out-of-turn store.
+- Thinking controls now survive LiteLLM parameter filtering for declared upstream runtimes. Unanimous per-alias LM Studio metadata selects its explicit off effort, while llama.cpp keeps template controls; only a legitimately resolved effort is added to the gateway request allowance. Gateway routing, authentication and residency stay unchanged, unknown/mixed declarations are not guessed, and returned reasoning is not hidden. Qwen3.8 exposes off/low/medium/xhigh; released high/max choices normalize to xhigh without changing saved preferences or confusing the vendor template default with Clio defaults.
+- Proactive memory prefers its dedicated configured route and can use the active chat model when that route is unavailable, including a shared reasoning model with thinking requested off. A dedicated client error permits one fallback within the original remaining deadline; cancellation, scope changes, timeouts and model output do not trigger retries. Known usage and telemetry remain separate for each attempted route. Memory now consults existing endpoint capacity evidence and observed foreground/dispatch occupancy instead of treating every shared URL as a busy one-slot server; LiteLLM retains gateway routing authority. Unset memory roles stay rules-only, and fallback selection does not change saved settings.
+- Context map seeds now keep distinct directory areas, external packages, and connections identifiable when readable IDs collide. Collision suffixes preserve other existing readable IDs, and internal and external imports with matching names retain their own destinations and counts.
+- Active project and user skill trees now remain operator-owned for both main-agent and worker tool admissions, including full-auto. Direct mutations, recognized shell mutation and Clio installation commands (including `skills sync` and confirmed `library add --yes` with skill dependencies), ancestor deletion, and current symlink aliases are refused even when general default path protections are disabled. Literal shell comments and redirection targets cannot masquerade as help/version arguments to bypass that guard. Quoted search patterns remain read-only, and literal operator filenames do not hide later mutation operands. Unconfirmed library plans remain available. Marketplace matches now require the existing bound operator answer before installation at every autonomy level; operator CLI, hub and slash installation/update workflows remain available. Draft skills outside active roots. Shell command inspection remains a bounded guard rather than an operating-system sandbox; arbitrary programs, dynamic expansions, aliases and concurrent filesystem changes still require supervision (#300).
+- Native session and eval call timing now starts before each provider stream invocation, so TTFT and API duration include the request's wait for response headers and later tool-loop calls have their own clocks. Empty output does not manufacture TTFT. Historical timing values remain unchanged; stdout-only fallback timing still starts at the provider's message-start event and must not be compared as complete request latency.
+- Eval now exposes observed provider terminal reasons, retry phases, and errored-call known usage subtotals for opt-in health gates (#278). Known failed-call spend stays in total accounting, and repeated retry countdown frames do not inflate attempt counts. Missing, partial, or ambiguous all-zero failed usage remains explicitly incomplete; stream cost can reflect adapter pricing and does not certify billing. Recovered tasks keep the existing default pass policy, and retries hidden inside a runtime remain unobserved. Reported failed reasoning remains separate from output/total tokens; an ambiguous adapter estimate is not promoted to provider-reported usage.
+- Completed parallel dispatch receipts keep their sealed ledger status while finalization waits for durable persistence. Heartbeat reconciliation no longer regresses a finished run to running, stale, or dead during ledger lock contention; active workers still receive normal stall detection. Batch host checks and receipt digest verification retain their existing semantics.
+- Eval first-call TTFT now reports `{ value: null, source: "estimated" }` when timing is absent, preserving a measured zero as `{ value: 0, source: "ledger" }`. The first call is selected by its recorded timestamp across session ledgers. Stream fallback measures only observed output after a call start and leaves missing timing absent. Verdict consumers must handle nullable TTFT; historical numeric artifacts remain readable without rewriting (#277).
+- Headless runs that recover from a provider failure with a successful tool-only artifact completion no longer retain the earlier error and fail evaluation despite producing the required artifact. Terminal errors, failed artifacts, cancellation, and shutdown still fail truthfully; recovered runs retain their failure history and reported spend (#275).
+- Transient task memory and its observer state now reset on explicit session and branch switches, including same-session `/tree` navigation. Late background completions cannot mutate the successor bank, deliver reminders, or propose durable memory. Reported usage keeps its originating session identity without inflating the successor's live cost. Ordinary forward turns and compaction retain continuity; abort-ignoring transports may still finish, but their stale content is discarded (#323).
+- Eval tracked token and model-call totals no longer double-count assistant calls recorded by both the native runner's session ledger and stdout fold (#276). Tracked metrics prefer durable assistant-call facts, including timing and cache provenance, and fall back to stream calls when no durable calls exist; durable compaction and tool records remain included. Compaction usage intentionally makes tracked totals differ from stdout-only totals. Artifacts record source counts and warn when observed counts differ or an external runner mixes sources. Partial or mixed ledgers can still omit stream-only calls, and fork-inherited history is not reconciled: no shared call identity proves overlap or complete coverage, so these cases must not be treated as reconciled run totals. Full reconciliation across session, stdout, fork and out-of-turn evidence is deferred to v0.4.5 or later. This release exposes count-based diagnostics but does not automatically reject cost or efficiency comparisons on incomplete evidence.
+
+## 0.4.2 - 2026-09-02
+
+### Added
+- Accountability reaches ACP. The observability extension publishes `accountability.evidenceReady` on the bus once per run whose evidence bundle and index row landed, with the payload spread from the same `ObservabilityRunEvidence` object it hands the projection, and the ACP server forwards it as the opt-in `accountability.evidenceReady` kind (`{runId,evidenceId,firstPassSuccess,findingCount,tags}`, `terminal:true`) through the shared `forwardEvent` sender. The v0.4.2 telemetry audit found first-pass success and finding counts reached the TUI, `usage`, `evidence-detail`, and the trace viewer but no ACP event, not even opt-in (#271). Bundle prose never crosses; a failed build sends nothing. Contract: `tests/contracts/acp-evidence-ready-event.test.ts`.
+- `clio-coder trace code-steps <rootId> [--json]` reads back the deterministic code-step records every fleet code step writes to `<stateDir>/code-steps/<rootId>/`. The v0.4.2 telemetry audit found the writer had no reader anywhere (#270): each run recorded argv, cwd, env names, exit code, duration, output digest, and artifact paths that nothing surfaced. The store stays as it is; the command is the missing read surface, oldest first, verbatim under `--json`, empty state on an unknown root. Contract: `tests/contracts/trace-code-steps.test.ts`.
+- `npm run smoke:real-home` (`scripts/smoke-real-home.sh`) boots the built binary against a copy of the operator's own settings. It copies `~/.config/clio-coder/settings.yaml` (and `credentials.yaml` when present) into a scratch `CLIO_CODER_HOME`, runs `doctor` and one read-only headless turn there, fails on a doctor crash or deprecation warning, a turn that exits non-zero, a tool policy drift refusal, or a turn with no `agent_end` event, prints doctor's own failing rows for the operator, and deletes the scratch home. The 0.4.2 release smoke ran only with isolated homes and missed two bugs a real settings file exposed on first launch (the raised read cap refusing to boot, and the legacy skill metadata warning), both fixed in this release. The release checklist names it beside the isolated-home turn.
+- The files pane is a Clio Coder surface with its own verb and key. `/files` toggles a file view docked below the session and moves the keyboard into it; the same command or `Alt+E` (`clio-coder.files.toggle`, with the `Ctrl+G e` leader fallback) closes it and hands the keyboard back. `/files pick` and `/panes open files --once` borrow the pane for one selection. A pick lands in the composer as an `@file` mention and returns focus to the prompt; a pane herdr reports gone counts as closed, so the next toggle opens rather than trying to close nothing; reopening an open pane leaves any zoom that hides it and focuses it. Outside a pane host `/files` still runs the one-shot full-screen pick. The `panes` tool, `/panes open`, and the keybinding all reach one shared controller (`PanesOperations.files`). Verified end to end in a herdr 0.8.2 session on Linux x64: open, pick with `Ctrl+Y`, toggle close, key toggle, one-shot pick, and a clean `/quit` with the dock gone. Contract: `tests/contracts/panes-files.test.ts`.
+- `clio-coder panes theme` prints Clio's theme tokens as a herdr `[theme.custom]` block. herdr styles its own chrome from its config file and offers no per-pane styling on the socket, so Clio prints the block for the operator to paste rather than editing another program's configuration. The files pane itself is themed from the same tokens at open time, now across the engine's manager, mode, status, which-key, pick, input, completion, task, help, and notification surfaces instead of five keys, with every emitted document parsed as TOML in the contract test.
+- `docs/guide/panes-and-files.md` is the operator page for panes and the files pane from a clean machine: install, the two settings, what `doctor` prints at each stage, every command and key, what `/quit` closes, the theme boundary, and the exact messages with their remedies. Every quoted output is from a run of the built binary in a herdr session on this release; `docs/html/panes_files_blueprint.html` is its visual counterpart and the parity check holds both to the same command facts.
+- Installed extensions are now projected into one immutable, generation-numbered snapshot per session. The extensions domain publishes nothing when it starts; the composition root builds and validates boot generation 1 and its user-hook registrations, then publishes both with adjacent reference assignments. Every in-process consumer of extension skill, prompt, agent, and fleet roots and of extension `hooks.yaml` declarations reads that paired generation instead of re-listing and re-hashing every installed tree on each load. `/resources extensions reload` is the only in-session trigger and uses the same paired publication path, so a turn observes either the previous resources with the previous hooks or the new resources with the new hooks and never a mixture. A rejected build, a stale candidate, or a re-entrant call publishes neither side, leaves the active generation untouched, and reports bounded diagnostics. Prompt fragments, cached agent recipes, and the session prompt refresh only when the committed content digest changed.
+- Extension `hooks.yaml` declarations are now registered from the exact bytes hashed during install-digest verification and captured into the snapshot. A `hooks.yaml` rewritten after verification is never reopened; the tree fails verification on the next generation and contributes no hooks. Hook sources and hook receipts carry a structured `extension` object with the package provenance (id, scope, canonical root, manifest digest, content digest), the declarations digest, and the admitting generation, replacing the loose `extensionScope` and `installedContentDigest` fields. `hook-receipts.json` stays version 1 and older records still parse.
+- Middleware registrations declared by user hooks are owned as one unit under a strictly increasing generation. A replacement for an older or equal generation is refused, a late disposer from a superseded generation is a no-op, builtin and host registration ids are never taken by an owned set, and an in-flight asynchronous hook evaluation finishes against the registration list it started with. Collisions surface as a `registration_conflict` middleware diagnostic and interactive notice.
+- `docs/configuration-reference.md` is the audited inventory of every switch that changes what Clio Coder does at the 0.4.2 cut: 158 settings keys, 102 environment variables, 310 CLI flags across 33 commands, 60 `.clio-coder/` file keys, 22 recipe and 4 fragment frontmatter keys, 97 tool arguments on `dispatch`, `bash`, `context`, and `verify`, and 77 model knowledge-base tags, each with its default, what it controls, and what beats what when several surfaces set the same value. The audit behind it found 168 of them documented nowhere, 4 read by nothing, 13 with a second spelling, and 1 documented default that disagreed with the code; the entries below apply the result. Bounding constants are listed as code-owned invariants, not configuration.
+- The documentation tree is organized by audience (`docs/guide/` for operators, `docs/architecture/` for contributors, `docs/process/` for how the project is run, `docs/history/` for dated records) with `docs/README.md` as the hub, and every one of the 51 Markdown pages has one HTML blueprint under `docs/html/` served by `clio-coder docs`. A source-first audit pinned to `ff56ea3e` found 42 pages with at least one claim that disagreed with the code (defaults, flag names, removed knobs, file paths) and corrected all of them; the blueprints were then synchronized from the corrected Markdown, and `docs/process/documentation-coverage.md` records the per-page result. The package ships the whole Markdown tree (never `docs/html`), `context(scope=docs)` walks the subdirectories, and the `docs-parity` hygiene check fails lint when a page and its blueprint disagree on the commands and environment variables they name or when either side is missing.
+- Local model knowledge-base families and the quirks schema now declare static and thinking-level keyed chat-template kwargs (#267). Runtimes forward the merged kwargs object, preserving numeric values as numbers and letting existing thinking-control switches win on key collisions. NVIDIA Nemotron 3.5 Lightning declares static `force_nonempty_content`, Nemotron 3 Nano Omni declares numeric `reasoning_budget`, and Muse Glimmer declares level-keyed `reasoning_strength` while documenting LM Studio as unsupported.
+
+### Changed
+- `/quit` in a pane host now says what it left behind. The policy is decided (#272): docks (the files pane, the workers watch pane) close with the session, utility panes opened with `/panes open shell|logs|<argv>` stay, and `/quit` prints one line after the terminal is restored naming each pane it left, the `/panes close all` that would have taken them along, and the `herdr pane close` that closes them now. Nothing is printed when only docks were open. Contract: `tests/contracts/panes-quit-left-behind.test.ts`.
+- Tool results now use a configurable `context.toolResultMaxBytes` ceiling with a 65,536-byte default and a 4,096-byte minimum. Session overrides and configuration reloads apply to the next result, while overflow still preserves the complete text in the session scratch file and the separate 196,608-byte turn guardrail remains unchanged.
+- Chat output now defaults to each model's advertised maximum instead of a fixed 32,768-token ceiling. Models without an advertised cap retain a bounded 32,768-token fallback, explicit settings still win, and the Qwen3.6 27B and 35B catalog caps now match the vendor's documented 81,920-token maximum.
+- The files pane no longer names its engine anywhere an operator reads. The preset is `files` (`/panes open files`; `yazi` still parses as an alias so saved habits and scripts keep working), the pane label is `files`, the composer notices say "the files pane", the doctor rows read `files pane profile` and `naming files profile`, the Settings labels read Files pane, and the help overlay gains a "panes & files" topic. The engine's name survives exactly where it is a fact the operator acts on: the registry id in `clio-coder tools install yazi`, `tools status yazi`, and the `interface.panes.files.*` settings the reference already used. The model's `panes` tool enum carries `files`, `logs`, `shell`.
+- `/panes open logs` and `/panes open shell` say why the pane layer is missing and how to get it, repeating detection's reason (`HERDR_ENV is not 1, so Clio is not running inside a pane host`) and the `clio-coder --with-panes` remedy, where they previously said only that the layer was unavailable. An empty logs preset names the journal root it watched instead of "has nothing to show yet". A second `/panes open shell` or `logs` focuses the pane that is already open rather than splitting a second one, and reports `focused pane` so the difference is visible.
+- Local model knowledge now projects only engine-consumed sampling and thinking quirks. Removed structured KV cache recommendations and unused per-profile output caps; KV serving facts remain in `llamaCpp`, `measuredUnder`, and serving notes, while `capabilities.maxTokens` remains the authoritative output cap. No request default changes. Catalog authors should use those surviving provenance and capability fields instead of the five removed no-op tags.
+- Model residency now resolves only from `targets[].lifecycle`. Removed the duplicate `CLIO_CODER_RESIDENCY` process switch. Local targets remain managed by default, and SSH nodes remain observe by default through WorkerSpec lifecycle projection. Operators should replace process overrides with `targets[].lifecycle` or `fleet.nodes[].residency`; an explicit target `user-managed` opt-out remains authoritative.
+- Smooth-stream pacing and third-party project resource trust now resolve only from `interface.smoothStreaming` and `integrations.projectResources.trustProjectImports`. Removed both duplicate process environment overrides. `off` remains the smooth-stream default, and `false` remains the project-import trust default. Operators should replace environment overrides with those settings keys.
+- Guardrail limits and the run event journal now use only their version 2 settings paths under `safety.limits` and `fleet`. Removed the seven duplicate environment overrides, and the existing settings defaults remain in force. Operators should replace environment overrides with the corresponding `safety.limits`, `fleet.limits`, and `fleet.history` keys. Session-only changes and configuration hot reload now refresh the process-local projections, and the orchestrator reads the current turn budget on each attempt.
+- Removed the deprecated `CLIO_CODER_MAX_RUNS` and `CLIO_CODER_TRUST_PROJECT_SKILLS` environment spellings, the pre-fleet `--worker*` command aliases, the headless `run --runtime` alias, and eval's `--clio-entry` alias. No default behavior changes. Operators should use `fleet.history.maxRuns`, `integrations.projectResources.trustProjectImports`, and the canonical flags named by each command's help; old spellings now reject or fall through without compatibility warnings.
+- The `dispatch` tool schema serializes its `intent` and `budget` object schemas once, under `$defs`, and references them by JSON pointer from the top level and from every task; a task object now carries only what varies per task (`task`, `briefing`, `agent`, `budget`, `target`, `model`, `node`, `worktree`, `intent`, `gate`), with `persona`, `tool_profile`, `cwd`, and `apply` inherited from the batch defaults (an item that still sends one is honored). The schema went from 9,863 to 7,959 characters; under Qwen3.8-27B on dynamo the `dispatch` tool went from 2,884 to 2,357 tokens and the full-capability first turn from 9,501 to 8,923, and on the Ornith 1.5 tokenizer the schema went from 2,190 to 1,782 tokens with the per-task object alone from 635 to 201. TypeBox's validator and pi's tool-argument validator both resolve the pointers, and `tests/contracts/dispatch-admission.test.ts` still admits a batch whose tasks declare their own intent and budget.
+- Resource loads no longer re-hash installed extension trees on every skills, prompts, agents, or fleets read. An extension installed, enabled, disabled, or removed by another process while a session runs is not visible to that session until `/resources extensions reload` or a restart; previously it could appear on the next load without any explicit action. `clio-coder config inspect` reports hook and extension entries with `reload:reload` instead of `reload:restart`.
+- Updated the Pi engine SDK libraries (`pi-ai`, `pi-agent-core`, `pi-tui`) from 0.84.0 to 0.84.4. The agent loop now runs Clio's post-tool continuation guard only when another assistant turn is about to start, so a terminating tool batch no longer triggers the guard after its final result; Clio's guard was already continuation-only and needed no change. Inherited fixes include OpenAI-compatible reasoning replay and thinking-signature serialization, Anthropic server-side refusal fallback pricing, optional tool arguments sent as `null` being treated as omitted, fullscreen transcript search and half-page/line scrolling actions, the SSH-aware `PI_TUI_ESC_TIMEOUT` escape window, and lower alternate-screen per-frame allocation. While the fullscreen search overlay is focused, `ctrl+g` advances the match and the Clio leader chord is unavailable; Clio's own bindings do not otherwise overlap the new defaults. New engine lifecycle contracts lock these behaviors.
+- The delegation threshold now opens the Delegation section as a count taken before the first edit, with the dispatch call shape beside it: two or more independent file-scoped changes, or any repository-wide exploration however small the repository looks, means one `dispatch` call with `tasks` (one per change, `agent` coder, `mode` parallel, `intent` naming each file) or a `scout` dispatch before any repo-wide grep or read, and the parent keeps synthesis and validation. The Fleet block no longer carries the threshold. On the round-2 drive with Qwen3.8-27B on LM Studio at temperature 0 the bare Fleet-block threshold lost to inertia on every run (two-changes 0 of 2 dispatched, reconnaissance 0 of 2 dispatched scout); with the count up front and the call shape next to it, two-changes dispatched both workers in one parallel call on 6 of 6 runs and reconnaissance dispatched scout before any repo-wide read on 5 of 6, the miss being the run before "however small the repository looks" was added. On the final build the parent stayed off both assigned files on 2 of 2 two-changes runs, spot-checked the receipts, and ran the tests itself. Re-measured after the merge with v0.4.2's prompt hardening and the `dispatch` schema slim: two-changes 2 of 2 dispatched with the parent off both assigned files, reconnaissance 2 of 2 scout-first, inventory and docs-first 2 of 2, bad-argument recovery 2 of 2 without a same-shape retry, and the skill suggestion fired on 2 of 2 runs at 8,995 first-turn tokens.
+- `ledger` is off the session tool surface and on every worker registry. The session never binds an agent-ledger port, so on that surface the tool could only answer "no ledger" while its schema cost 444 tokens of every first turn; `registerCoreTools` takes `includeLedgerTools`, the session leaves it off, and the worker registry sets it whether or not a port is bound, because the orchestrator admits `ledger` for every batch member and signs that surface. An interim build that gated the worker side on the port refused every batch worker with `Worker attestation rejected: tool surface drift`; `tests/contracts/worker-attestation-surface.test.ts` pins both sides.
+- The compiled prompt reads the tool surface from the frozen name list only. `toolSurfaceHasTool` in `src/domains/prompts/compiler.ts` counted a registry hint as evidence that its tool was attached, so a stale hint could render the Skills or Delegation passage for a tool the model could not call; hints now render only for tools on that list and the surface gates read the same list.
+- The `context(scope="skills")` listing opens with a label instead of a second copy of the suggest-and-continue protocol; the recency anchor at the bottom, the line literal models act on, is unchanged. Every catalog skill's description is now one lead sentence saying what the skill does plus its "Not for X; use Y" routing clauses, with the trigger phrases kept in `triggers`: the 31 descriptions went from 13,116 to 7,741 characters in the listing. `skills/README.md` and `skill-craft` state the split, and every catalog version took the minor bump the versioning policy requires for a description change.
+- Recipes name `code_nav` only as "when it is among your tools": routine non-Scout dispatch removes the tool, so "when a codewiki exists, prefer `code_nav`" invited a call the worker could not make.
+- Three dispatch rejections that cost a live orchestrator a round each now either read the intent or say what to do. `intent.read_roots` or `write_roots` entries of `.` or `./` name the repository root, which an empty scope already means, so they are read as that instead of refused; a briefing that quotes an import specifier such as `./parser.js` infers `parser.js` instead of failing the whole dispatch for a dot segment (a `..` token is still refused as an escape); and the `verification_check_undeclared` and empty-`gate` errors say what an entry is (a check id `verify()` lists, never a shell command) and offer the move that always works, omitting it and running the check after the receipt. The orchestrator that put `git diff src/formatter.ts` in `verification` had retried the same shape until the loop guard disabled tool calls for the turn.
+- The model knowledge base gains an `ornith-1.5` family with an on-off thinking mechanism. The inherited `ornith` entry classified every Ornith checkpoint as always-on from a 2026-08-08 LM Studio measurement of Ornith 1.0, so a worker dispatched with thinking off still produced a full reasoning trace (1,061 of 1,518 output tokens on one debugger receipt). Measured 2026-09-02 on llama.cpp: `enable_thinking: false` answered in 4 completion tokens with no `reasoning_content`, `true` spent 79.
+- Seven more ids the mini llama.cpp router serves now resolve to a family whose thinking mechanism was measured on that runtime. Six had no family at all, and what that cost depended on how the router launched them. `gemma4-26b-moe` and `gemma4-31b-dense` run under `--reasoning off` and `muse-30b-dense` under no `--reasoning` flag at all, so the probe reported no reasoning, the resolver returned mechanism `none`, pinned the dial to off, and stripped every thinking field from the payload. `nemo3.5-30b-moe`, `nemotron3-30b-moe-omni` and `thinkingcap-27b-dense-q4` run under `--reasoning on`, so the probe reported reasoning and the resolver already guessed `on-off` and already put `enable_thinking` on the wire; what they gain here is a measured classification instead of a guess, plus sampling defaults, guidance and provenance. `qwopus3.6-35b-moe` matched the `qwopus3.6-27b-v1-preview` distill through a bare `qwopus3.6` pattern and inherited a budget-tokens dial that emits nothing on llama.cpp. Measured 2026-09-02 on a one-line arithmetic prompt, completion tokens at `chat_template_kwargs.enable_thinking` false against true: `gemma4-26b-moe` 3/99, `gemma4-31b-dense` 3/68, `nemo3.5-30b-moe` 3/120, `nemotron3-30b-moe-omni` 4/42, `thinkingcap-27b-dense-q4` 3/130, `qwopus3.6-35b-moe` 3/130, every one of them on-off; `muse-30b-dense` gave 91 tokens with 332 characters of reasoning at false against 90 with 312 at true, so it is always-on and its strength scale has no off level to reach. `reasoning_effort` moved none of the seven on llama.cpp, so `nemotron-3-nano-omni-30b-a3b-reasoning` drops its budget-tokens dial and `qwopus3.6-35b-a3b-coder` drops its four-level effort map, both for on-off, and both keep their earlier LM Studio findings in `measuredUnder`. New families cover NVIDIA Nemotron 3.5 Lightning, Meta Muse Glimmer 30B, and BottleCapAI ThinkingCap-Qwen3.6-27B. The bare `qwopus3.6` pattern is deleted rather than reordered, because the matcher ranks by pattern length and ignores file order. The `thinkingcap-27b-dense-q6` the issue names was measured on the same date and then deleted from mini, so the family is keyed to the q4 the router still serves (`tests/contracts/local-model-family-resolution.test.ts`).
+- The Gemma channel filter is keyed on the wire model id rather than on the resolved family, so it survives a Gemma id gaining a catalog entry. `capabilityFamily` returns the knowledge-base family whenever the catalog matches an id, and every Gemma entry names a build (`gemma4-26b-a4b`, `gemma-4-31b-it-qat-mtp`), never the literal `gemma-4` the gate compared against, so the filter had been running only for Gemma ids the catalog did not know. Naming `gemma4-26b-moe` and `gemma4-31b-dense` in the catalog would have turned it off for the two the mini router serves, and a llama-server that leaves the thought inline in `content` would have put `<|channel>own-think` and the private thought into visible assistant text and into turn history.
+- The prompt-optimization recording proxy keeps llama.cpp's `timings` block (`prompt_n`, `cache_n`, `prompt_ms`) beside each captured request and keeps the tail of a long stream rather than its head, and `envelope-run.ts` takes `--runtime` so a llama.cpp target can be measured. Development instruments only; nothing under `scripts/` ships.
+- The first turn of a full-capability session on this repository measured 12,950 input tokens under Qwen3.8-27B before this change, 69 percent of it tool schemas and 26 percent the `dispatch` schema alone, with the same rules restated across the Delegation fragment, the Fleet block, the Tool Contract, and the `dispatch` and `monitor` descriptions. The prompt now says each rule once: the Delegation fragment keeps receipt and spot-check discipline, the Fleet block keeps routing (including that `agent:"auto"` is a fallback, which no longer also appears in the Tool Contract), the Skills fragment is a short suggest-and-continue pointer since the first-turn `[Skills]` reminder is the channel local models act on, the identity block drops the biography and keeps the name, the vendor denial, the safety line, and the installed paths, and the operating contract drops the posture-toggle and report-artifact sentences. Every `dispatch` field keeps one discriminating sentence and the tool description states only the call shape; `monitor`, `steer`, `panes`, `ask_user`, `verify`, `bash`, `credential_present`, `web_fetch`, and `ledger` lose restated policy from their schemas. Recipe descriptions now lead with a job sentence that fits the 64-character roster line, so the Fleet section no longer ends nine of eleven lines in `...`.
+- Tool schemas reach the provider without TypeBox 1.x's string-keyed markers. `Type.Unsafe` and `Type.Optional` stamp `"~unsafe": null` and `"~optional": true` on every enum field, and unlike the older symbol keys those survive `JSON.stringify`, so 44 such keys rode along on the default surface. `wireParameterSchema` in `src/tools/agent-tools.ts` hands the agent loop a copy with every `~`-prefixed key removed; `Value.Check` validates identically with and without them and the registry keeps the original schema object.
+- Rebuilt the product README and operator documentation around the current CLI, settings-v2 contract, package layout, and experimental boundaries so new users and repository agents have one concise, accurate route into the product.
+- Compacted the main and worker system prompts by removing duplicated routing, skill, retrieval, and worker-task prose while preserving Clio identity, autonomy and safety rules, Fleet receipts and evidence, permission routing, local-model guidance, result contracts, and stable section order.
+- The `dispatch` tool schema is composed once per session from the fleet the session starts with (`src/tools/dispatch-schema.ts`). The council fields (`roster`, `members`, `synthesis`, `rounds`) are advertised only when `fleet.rosters` names a roster, the compete fields (`candidates`, `judge`, `apply_winner`) only when the fleet has more than one distinct target/model route, and the adaptive-routing fields (`routing.posture`, `minimumQuality`, `locality`, `failover`) only when `fleet.adaptiveRouting` activates a role or posture; the hard bounds (`maxCostUsd`, `deadlineMs`, `requiredCapabilities`) and the `mode` enum entries for the advertised modes stay. Admission reads every field whether or not it was advertised, so a caller that sends a hidden one is honored. `intent.write_roots` and `intent.expected_outputs` carry one-sentence descriptions saying they are paths under a write root, not prose: the interim two-changes batch (r4-mid) paid 3 and 1 dispatch rejections (`intent_outputs_outside_write_roots`, `verification_check_undeclared`) before its parallel call was admitted; the final batch (r4-final) dispatched both tasks in one parallel call with per-task intent on the first try in 2/2 runs, and the parent edited neither assigned file. On the one-route, no-roster sandbox under Qwen3.8-27B on dynamo the `dispatch` tool went from 2,357 to 1,800 tokens (1,766 before the two descriptions) and the full-capability first turn from 8,924 to 8,365 (r4-final; the same tree measured 8,323 on mini under Ornith 1.5); `tests/contracts/dispatch-schema.test.ts` pins the composition and the open schema.
+- The `coder` recipe says to make each read and verification call once. Round-3 receipts on Ornith 1.5 showed every coder run blocked five times by the identical-call loop guard (repeated `code_nav` and `git diff`) while using 17 to 30 of its 50-call budget; the final batch's four coder runs used 3, 5, 9, and 17 calls with 0, 0, 1, and 2 blocks (r4-final against 30/5, 19/5, 27/5, 17/5 in r3-final). Budgets and result contracts stay as they were: no builtin recipe reached its budget or fired contract repair in any measured run, so the guard, not the budget, was the binding knob. The worker prompt pin moves from 5,179 to 5,335 characters.
+- Thinking "off" now reaches LM Studio for effort-level families (qwen3.8 and its relatives) as `reasoning_effort: "none"`. LM Studio ignores `chat_template_kwargs.enable_thinking` for these models, so every session configured with `chat.thinkingLevel: off` on that runtime had been reasoning anyway (37k reasoning tokens in one 25-minute interactive turn), and every round-2 to round-4 main-agent measurement on dynamo ran with reasoning on. Measured on a one-line prompt: `enable_thinking:false` left 63 reasoning tokens, identical to no override; `reasoning_effort:"none"` produced 0 and a shorter rendered prompt. llama.cpp keeps the template flag alone, which it honors. The `chat.thinkingLevel` default moves from `off` to `low` in the same release (see the next entry), so a fresh home keeps the reasoning it had been getting by accident (`tests/contracts/thinking-off-wire.test.ts`).
+- `chat.thinkingLevel` defaults to `low` instead of `off`. Every measurement before the wire fix ran with reasoning on, so `off` had never actually been the shipped behavior on LM Studio. With reasoning truly off, the same three-issue interactive exercise on Qwen3.8-27B re-emitted one batch of eleven read-only calls five times and finished nothing in its first run, and even with the loop guard fixed the model plans visibly worse than it does with a low effort budget. `fleet.default.thinkingLevel` stays `off`: workers run bounded recipes where the round-4 receipts showed no benefit. Existing settings files that name a level are unaffected.
+- The identical-call loop detector retains the last 48 attempts instead of a 30-second window or the last four, and the loop guard counts repeats from the turn's last successful write or edit. A session with thinking off re-emitted the same batch of eleven read-only bash calls five times, every call admitted, and ran to the 60-call soft budget with nothing done; a batch re-emitted a third time is now blocked on its first call, while a check rerun after an edit stays a fresh call (`tests/contracts/loop-detector.test.ts`, `tests/contracts/loop-guard-epoch.test.ts`).
+- A worker confined to `write_roots` is told so: the Declared Result Requirements block says the run has no bash or verify tool, that the host runs the declared checks after it finishes, and to write the code and tests and report; the `write_roots` schema description and the Delegation section say the same to the coordinator, which now puts checks in `verification` instead of the task text. Before this, three parallel coders on Ornith 1.5 told to "run the tests" spent 40, 23, and 15 `code_nav` calls looking for a way to run them and made zero source edits; with the sentence they finished in 10, 18, and 12 calls with every file edited (`tests/contracts/intent-requirements.test.ts`).
+- A typed intent that declares no `write_roots` and no `expected_outputs` outranks the prose task classifier for a read-only recipe, so a scout survey that mentions writing a failing test is admitted instead of refused as a change-class task. An intent with a write root still refuses (`tests/contracts/dispatch-admission.test.ts`).
+- The `[dispatch scope]` notice names only tokens with a source or document extension or a trailing separator, capped at twelve; a live three-task dispatch had printed 27 omitted "paths" per task, most of them `0.5`, `4/10`, `v24.9`, `e.g`, and method names like `Store.fromText`.
+- `tasks done` on a task that was never started records the start and the completion together and names the implicit start in its notes; the evidence note stays mandatory. A live session had spent six start/done pairs of pure ceremony closing a board whose work was already done (`tests/contracts/task-board-done.test.ts`).
+- The chat panel renders a `Suggested skill: /skill <name>` line wherever the model wrote it as the suggestion row, with the rest of the message as the answer. Round-4 skill batches fired the line 2/2 per batch but opened the reply with it 1/2, 1/2, and 0/2 across three wordings, so the harness recognizes it instead (`tests/contracts/rendering-invariants.test.ts`).
+- The compact footer row names the live context window after the percent (`ctx ▰▰▱▱ 4.6% of 262.1k`) at 72 columns and wider, so a session on a 1M window and one on 128k no longer read the same. The window comes from the context ledger when one is bound and from the target capabilities otherwise; an unknown window shows the percent alone (`tests/contracts/footer-context-window.test.ts`).
+- Self-awareness names the live settings file and state directory of the resolved home rather than the XDG defaults, and the tool-inventory line says `dispatch(list:true)` answers which target and model run the session and its workers. Asked which worker would run a coder dispatch and where that is configured, the first exercise run answered from the recipe alone; the third named the fleet default target and model from the isolated home's settings.yaml. The `artifact` description says to close the task board before writing, because the artifact ends the turn. Main prompt 10,313 -> 10,504 chars (`tests/contracts/compact-prompt-contracts.test.ts`).
+
+### Fixed
+- The boot deprecation for a skill file that still carries `clio:` frontmatter names the file, and `clio-coder doctor` finds it. The warning read `'clio: skill metadata' is a deprecated Clio Coder identifier` with no path, while the doctor's `naming resources` row said installed skills were canonical, because `inspectSkillMetadataNaming` scanned only `<config>/skills` and `.clio-coder/skills` and the loader also reads every interop agent's user and project compatibility root (`.claude/skills`, `.codex/skills`, `.agents/skills`, and the rest). The operator's copy was a gitignored `.claude/skills/file-ticket/SKILL.md` in the project. The warning now reads `clio: skill metadata in <path>`, once per file, and the doctor scans the loader's roots and lists each offending path with the rename to make (`tests/contracts/settings-migration.test.ts`).
+- The engine reads runtime metadata from `model.clioCoder` again. The 2026-09-01 naming migration moved the key the synthesizer writes from `model.clio` to `model.clioCoder` (`src/domains/providers/runtimes/common/local-synth.ts`) and updated the providers domain, but `src/engine/apis/openai-completions.ts`, `src/engine/apis/lmstudio.ts`, `src/engine/apis/ollama-native.ts`, and the prompt compiler in `src/interactive/turn-context.ts` kept reading `clio`, so for every model built since the migration the engine saw no metadata at all: LM Studio targets kept receiving the `chat_template_kwargs` map the runtime ignores and never ran residency, TTL, draft-model or advertised-effort handling; family sampling profiles never reached the request; llama.cpp requests carried no `cache_prompt` and skipped residency; llama.cpp and LM Studio backend timings were not attributed; Ollama residency and quirks did nothing; and the family's thinking guidance never rendered into the Runtime prompt block. Reproduced through the OpenAI-compatible fixture with a model shaped exactly as the synthesizer shapes it, and the contract suite had not caught it because the one engine test that builds such a model had been updated to the new key without the reader following. `tests/contracts/engine-model-metadata-key.test.ts` pins the LM Studio wire (no `chat_template_kwargs`, `reasoning_effort` from the dial), the sampling profile on the request, and llama.cpp's `cache_prompt`.
+- Thinking off reaches LM Studio as `reasoning_effort: "none"` for every mechanism, not only effort-level families (#268). Measured 2026-09-02 on dynamo at temperature 0 on a one-line prompt: `chat_template_kwargs.enable_thinking: false` left 26 reasoning tokens on qwen3.8-27b, 52 on gemma-4-26b-a4b-it and 105 on nvidia-nemotron-3.5-lightning-30b-a3b, while `reasoning_effort: "none"` produced 0 on each. The resolver's on-off branch already carried the spelling; the budget-tokens branch did not, and the wire only reached it through the LM Studio payload composer that the metadata-key regression above had switched off. `resolveRequestCapability` now sets `none` for any inactive mechanism other than `none` and `always-on` on that runtime, and llama.cpp keeps the template flag alone. A family's own chat-template kwargs (#267) are no longer merged into a request the runtime drops: on LM Studio the resolver lists them under `request.undeliverableChatTemplateKwargs` with whether the family entry marks them `lmstudio: unsupported`, and runtime resolution prints one `chat-template-kwargs-undeliverable` warning per target and model, so a Nemotron 3.5 Lightning session on dynamo says it runs without `force_nonempty_content` instead of finding the key missing from the wire. `tests/contracts/thinking-off-wire.test.ts` covers on-off, budget-tokens and the shipped Gemma 4 and Nemotron 3.5 entries on both runtimes; `tests/contracts/chat-template-kwargs-diagnostic.test.ts` drives the warning through `resolveRuntimeTarget`.
+- gpt-oss reasoning from LM Studio lands in thinking content (#269). LM Studio streams the Harmony analysis channel as the OpenAI-compatible `reasoning` delta field, with `reasoning_content` absent (measured 2026-09-02 on dynamo, gpt-oss-20b and gpt-oss-120b). The OpenAI-completions stream reader already accepts `reasoning_content`, `reasoning`, and `reasoning_text`, so the text was captured; what was missing was a contract holding that and a family entry naming the field per runtime. The `openai-gpt-oss` entry now states `reasoning_content` on llama.cpp and `reasoning` on LM Studio, and `tests/contracts/lmstudio-reasoning-field.test.ts` streams all three spellings through the engine against the fixture and checks the text stays out of the answer and the Harmony effort goes out as `reasoning_effort` with no `chat_template_kwargs`.
+- `interface.panes.enabled: embedded` no longer turns every pane off. The settings overlay offered `embedded` beside `auto` and `off`, and picking it made boot print "embedded mode is not implemented yet ... this session has no panes at all" while the same operator inside herdr would have had guest panes under `auto`. Embedded mode is still unimplemented; the rung now runs the guest detection ladder and logs that it did, so the setting an operator chose because they wanted panes gives them panes (`tests/contracts/pane-remedies.test.ts`).
+- A settings file that raises `safety.limits.readBytesPerCall` above the 50 KiB default no longer refuses to start. The read tool's result-size policy cap was computed once at module import from the guardrail default, while the drift check at registration compared it against the cap installed from settings, so `clio-coder` exited with `tool policy drift: tool read policy cap 53248B sits below self cap + slack (67584B)` before the first prompt. The cap is now recomputed when the tool is registered (`tests/contracts/read-policy-cap-follows-guardrail.test.ts`).
+- `docs/architecture/artifact-versions.md` gives `<stateDir>/runs.json` (the dispatch run ledger, `RunEnvelope` in `src/domains/dispatch/state.ts`) its own registry row instead of only naming it as deliberately excluded. It has at least nine reader call sites across the eval, evidence, CLI, and TUI domains and genuinely has no version field on `RunEnvelope` to check, so the row follows this document's own existing pattern for a real but unversioned artifact (`Current Version: unversioned JSON array`, matching the Out-of-turn Usage Ledger and Library Pins rows already there) rather than inventing a version number that does not exist. Also corrected, in the same paragraph: the doc named a `detached-batch` store it deliberately excludes from its registry, but the actual on-disk file is `batches.json` (`src/domains/dispatch/batch-store.ts:55`); the sentence now names the real filename. Mirrored both changes into `docs/html/artifact_versions_blueprint.html`. Docs-only; no code or behavior changed, and `check-hygiene.ts`'s `docs-parity` check passes.
+- The trace database's `runs` table now carries an explicit `source` column (`'dispatch'` or `'session'`) instead of leaving a dispatch run and an interactive session turn indistinguishable except through the undocumented sentinel `assignment_id = "session"`. `docs/architecture/trace-store.md` named that sentinel but never called it a discriminator a reader should rely on. The column is additive, the same way `processes.host`/`processes.birth_token` were added before it: `TraceStore` (the writer) backfills it in place from the sentinel on next open, with no schema-version bump, matching this database's existing migration precedent (`ensureProcessOwnerColumns`). Because `TraceReader` and the trace-viewer's `ViewerDatabase` both open read-only and can reach a database no writer has touched yet (the viewer opened fresh against a dormant install being the realistic case), both now detect a missing column via `PRAGMA table_info` and derive the same value from the sentinel at query time rather than showing an absent field. `clio-coder trace runs`' text-mode table gains a SOURCE column; its `--json` output and the trace-viewer API carried the field automatically once the column exists, since both already `SELECT *`. `tests/contracts/trace-store-run-source.test.ts` and `apps/trace-viewer/tests/server.test.mjs` cover the read-only-before-migration, writer-then-reader, and fresh-database cases.
+- The observability projection's run summary and the interactive dispatch board no longer maintain two copies of the same DispatchCompleted/DispatchFailed field mapping. Both independently subscribed to the same three bus channels and built their own summary; `resolveFailedStatus`, mapping a failure `reason` to a terminal status, existed as two byte-for-byte identical function bodies in `src/domains/observability/projection.ts` and `src/interactive/dispatch-board.ts`, kept in sync only by a comment asking the next editor to remember to. Re-verified the two sides were not actually a wholesale duplicate before touching anything: the dispatch board's `DispatchBoardRow` carries dozens of fields (budget envelope, gate/council state, trust projection, context-window meter, retry and failover tracking) the observability summary has no concept of, driven by additional bus channels (`DispatchEnqueued`, `RunAborted`, assignment/attempt events) the summary never reads, so making the board read the projection instead of its own subscription, the audit's proposed direction, would have thrown away real state; consolidation was scoped to the two fields the discrepancy actually named. The status mapping is now `resolveDispatchFailureStatus` in the new `src/core/dispatch-outcome.ts`, imported by both. Cost provenance had a real, live divergence, not just a duplication risk: the projection validated a payload's `costProvenance` against the closed four-value set and kept the previous value otherwise, while the board accepted any truthy string via `payload.costProvenance ?? "unknown"`; both now call the new `resolveCostProvenance` in `src/domains/providers/types/cost-provenance.ts`, which applies the stricter, correct behavior on both sides. Fixing `applyTerminalTokens` to use the projection's own existing `num()` helper (already used elsewhere in the same file, just not here) for `costUsd`/`tokenCount`/`inputTokenCount`/`outputTokenCount`/`reasoningTokenCount` closes a related gap in the same code: those fields previously passed a bare `typeof === "number"` check that accepted `NaN`/`Infinity`, unlike the board's already-`Number.isFinite`-checked equivalent, so a malformed terminal payload could silently corrupt the projection's running total while the board correctly rejected it. `tests/contracts/dispatch-outcome-provenance.test.ts` pins the two shared resolvers directly; `tests/contracts/observability-run-summary.test.ts` drives the projection through a real bus end to end, including the NaN/Infinity and out-of-set-provenance cases.
+- The observability projection's notice ring (`src/domains/observability/projection.ts`) no longer classifies seven notice kinds nothing ever read. `runtime`, `middleware`, `safety`, `loop`, `tool-budget`, `context`, and `budget` notices were built from the same bus channels the interactive layer's own live notice pipeline (`bus-notices.ts` and `interactive-event-projection.ts`) already classifies independently, richer and with real behavior attached (loop-guard and tool-budget notices can cancel the active turn, which the projection's pure classifier cannot do), for the toast surface a session actually shows; the projection's copies had no reader anywhere and could silently disagree with what the operator saw. Verified one kind is a genuine, live exception: `evidence`-kind notices (evidence-build failures) are read by the Dispatch Board's per-run evidence-failure-reason lookup and have no equivalent in the interactive notice pipeline, so that kind, `pushNotice`, and the notice ring itself are unchanged; `ObservabilityNotice.kind` narrows to `"evidence"` and `.ref` narrows to `{ runId }`, its only populated field. `tests/contracts/observability-notices.test.ts` pins that the seven removed channels now produce nothing and that evidence-build-failure notices still round-trip.
+- `clio-coder config inspect` now reads the durable hook-execution receipt log it has claimed to read since the log's own doc comment was written. `hook-receipts.json` (`src/domains/middleware/hook-receipts.ts`, written on every user-defined hook execution) had zero readers anywhere in the repository, and `config inspect` only ever read hook *configuration* sources (`capturedHookSourcesFor`), never execution receipts; a doc comment at the top of the writer named `config inspect` as the reader regardless. The customization graph now carries one `hook-receipts` entry (count, capacity, an outcome tally, and the most recent receipt) sourced from `readPersistedHookReceipts`, a new reader that loads the persisted snapshot back for a process that never held the running session's in-memory ring. One rolled-up entry rather than one per receipt: the graph explains configuration provenance, and a couple hundred execution rows would swamp that rather than answer it. `tests/contracts/hook-receipts-inspect.test.ts` covers both the never-persisted and the populated case.
+- `skills-eval` and `clio-coder eval run` no longer resolve to the same artifact file when handed the same eval id. Both `writeEvalArtifact` (version-1 `EvalRunArtifact`, `src/domains/eval/store.ts`) and `writeEvalArtifactV4` (version-4 `EvalArtifactV4`, `src/domains/eval/artifacts/store.ts`) computed `<dataDir>/evals/<evalId>.json`, so one writer could silently overwrite the other's differently-shaped file; `eval inventory`'s directory listing was also miscounting every on-disk `skills-eval` artifact as an unreadable retired shape, since it reads only version 4. The legacy version-1 writer now nests under `<dataDir>/evals/skills-eval/<evalId>.json`; the documented version-4 location (`docs/architecture/artifact-versions.md`'s Eval Artifact row) is unchanged. `tests/contracts/eval-artifact-namespacing.test.ts` writes both shapes under one shared id in both orders and reads both back intact.
+- The files pane engine's per-session transport files (`.stream`, `.chooser`, `.cwd` under `<cache>/yazi/sessions/`) were never removed, so every open left three files behind for the life of the install. They are removed when the session ends, and anything older than a day is swept on the next open, which also cleans up installs that accumulated them before this release. The vendored engine configuration also loses a `title_format` key the pinned engine does not read.
+- The llama.cpp probe no longer loads a model to read its slot count. A router answers `/props?model=<id>` by loading that model, and with `--models-max 1` that evicts whatever is resident, so every probe of a fleet target's default model unloaded the chat model and the next turn prefilled from zero (the round-3 resume run on mini prefilled 11,601 tokens with `cache_n` 0 even though the resumed request was byte-identical through the tool results). The router's model list already carries the worker's flags for an unloaded model, so the worker's props are read only when the router reports it resident; `tests/contracts/llamacpp-router-probe.test.ts` pins both cases. Re-measured on the same two-turn run: the resumed turn's first request prefills 90 new tokens against 11,525 cached in 0.66 s, and the turn's wall time went from 31 s to 5.9 s.
+- A synthesis-locked worker round whose reply was tool-call markup only gets one re-prompt, delivered as a paired synthetic tool exchange, before the fallback notice stands as the run's whole output; when a result contract is active, that round costs the re-prompt rather than one of the contract's bounded repair slots. Locked rounds remove the tool surface on OpenAI-family runtimes and send `tool_choice: none` on Anthropic, whose API rejects a history carrying tool_use blocks when no tools are defined. Measured on mini with a two-call recipe that locks every run, the re-prompt recovered every Ornith 1.5 markup round and 2 of 4 on Qwen3.8-27B.
+- Headless `run --autonomy <level>` takes effect. The flag was keyed by the bare word in the session overrides, which `setAtPath` wrote as a top-level key nothing reads, so a run in a home saved at auto-edit compiled "Autonomy: auto-edit" and parked a piped bash command for approval; the override is now keyed `safety.autonomy`, the path the effective view, the prompt compiler, and admission all read. `tests/smoke/cli-core.test.ts` runs the same home with and without the flag.
+- A resumed session replays a parallel tool batch's results in the order the assistant issued the calls. The ledger records a result when its tool finishes while the live loop sends the batch by call index, so a two-call turn whose second call finished first replayed as [b, a] after being sent as [a, b], and the provider prefix cache missed from that message for the rest of the session (the round-2 two-turn run on mini swapped messages 3 and 4). Results are staged until the next non-result message and released in call order; an orphan keeps its ledger position after the known ones. The visible transcript still renders the ledger as recorded.
+- `intent.verification: [{ check: "none" }]`, the shape a model writes to say "no verification", normalizes to an empty list instead of a refused dispatch round, unless the project declares a check by that name.
+- A briefing that quotes an import specifier with a leading `../` no longer fails the whole dispatch (#266). Round-5 exercise run 3 lost a coder dispatch to `legacy_scope_path_malformed: briefing contains a malformed path token '../src/store.js'` after the orchestrator copied `import { Store } from "../src/store.js"` out of `test/store.test.ts`, then retried without the quote. The quote's origin never reaches prose inference, which is handed the task and briefing text and nothing else, so a leading `../` run is stripped and the remainder probed against the dispatch root: `../src/store.js` infers `src/store.js` when that file exists, and is otherwise dropped from inference instead of rejecting the call. That costs one `existsSync` per `../`-leading token (3 microseconds on a hit and 2 on a miss over 5,000 warm calls) and no stat for the ordinary token, which the grammar matches dozens of per dispatch. **A leading run that names nothing is dropped rather than refused**, including `../../../etc/passwd`, which is a deliberate reading of the issue rather than an oversight: a run's origin is unknowable at this layer, so "never reject the dispatch" and "still refuse a token whose `..` segments leave the repository root" cannot both hold for the same input, and only the first is decidable without an origin. Neither outcome widens authority, since an inferred path selects project rules but never becomes a write boundary and an anchored remainder carries no `..` to escape with, and neither is silent: both the drop and the rewrite are named per token in a `[dispatch scope]` notice, on the stderr diagnostic, and on the `dispatch_plan` approval artifact, which now probes the dispatch's own `cwd` rather than the orchestrator's process directory so the plan an operator approves resolves the same scope the run does. A `..` or `.` outside the leading run (`src/../../b.ts`, `../src/./b.ts`) walks back out of a segment it already anchored and keeps the refusal, and typed `intent.read_roots`, `write_roots`, and `relevant_paths` still refuse any `..` with `intent_path_escapes_root`.
+- A fresh home no longer bounds every llama.cpp endpoint to one slot until someone runs `targets --probe`. The dispatch domain probes each configured endpoint whose bound resolved to the local-native default once when it starts, in the background and without the inference-based reasoning check, and the count lands in the provider statuses and the durable slot store where admission already looks.
+- Compiled-prompt reuse now keys every resolved runtime input and the exact provider-facing attached-tool schema bytes, while handbook context, project rules, operator profile, workspace facts, and repository awareness are snapshotted per session and refreshed only by configuration invalidation or a new session; unrelated cache misses no longer admit opportunistic disk drift.
+- Tool guidance now shares one deterministic role-aware normalizer, renders Marketplace installation ownership once, and remains absent for unavailable tools and roles. Bundled `code_nav source=clio` keeps its source in continuation guidance and resolves indexed paths under the installed or explicitly overridden package root.
+- Extension manifests once again permit the documented omission of `resources` while strictly validating any value that is present. Upgrade now backs up and atomically adds verified content digests to valid pre-digest install records without changing their source, timestamp, or disabled state; invalid legacy trees remain visible but inactive. Corrupt extension state stays fail-closed but no longer traps operators: forced reinstall and removal preserve corrupt state and unverifiable package bytes before recovery. Share-imported extension packages now pass whole-tree preflight and the canonical transactional installer, so a successful import always has a verified install record before resources activate.
+- Extension admission now rejects malformed manifests, invalid or changed installed trees, escaping links, hard-linked files, and special resource entries before they can contribute resources or hooks; canonical package discovery deduplicates aliases while retaining failures as deterministic diagnostics.
+- Documentation that disagreed with the code: `integrations.externalAgents.defaults.toolGovernance` defaults to `clio-coder-policy` (the page said `clio-policy`); `CLIO_CODER_FORCE_COMPACT` compacts before every interactive turn while set, not once; `CLIO_CODER_TRUST_PROJECT_RESOURCES` can only enable trust, never revoke a setting that grants it; `CLIO_CODER_TIMING` prints only on the bannered non-interactive boot; `CLIO_CODER_RESIDENCY` also accepts `0`, `false`, `user`, and `user-managed` and is exported to SSH workers; `CLIO_CODER_RUN_JOURNAL`, `CLIO_CODER_EVAL_RUNNER_STDOUT_FILE`, and `CLIO_CODER_YAZI_PICK_TOKEN` have rows.
+- `src/tools/dispatch-schema.ts` carried one NUL byte since round 4 and diffed as binary; stripped.
+- A parallel dispatch batch runs each declared host check once, after every live member of the wave has finished, and charges a failing check by write-root coverage across the whole wave. The checks used to run per worker on the shared checkout while siblings were still editing it, so one worker's broken test sealed `host_verification_rejected` on all three receipts of a three-task batch (round-5 interactive exercise, 2026-09-02, kvlog with workers on mini `ornith1.5-35b-moe`). Exculpation always requires positive evidence: a member is cleared only when the failing check named a path and every named path falls inside its own boundary or inside a live sibling's, and a member that declared the check but no `intent.write_roots` ran with no write confinement at all, so it is charged unconditionally. A failing check that names no path, or names one no member claims, still rejects every member that declared it. A cleared member seals the new `hostVerification.status: "not_implicated"` rather than `verified`, because its `checks` array still carries the non-zero exit code and `verified` is what the trust surface, the board, and `worker evidence` all read as "the declared checks passed"; the run is not failed by it and no validator speaks for it. The receipt also seals `hostVerification.strategy: "batch-settled"` and the per-check attribution, whose `basis` names the weakest evidence behind the charge; a single-task dispatch omits both and its receipt bytes are unchanged. The barrier waits only on members that already hold a capacity lease and never on one still queued for capacity, so a batch larger than `fleet.concurrency` cannot deadlock on its own parked leases, and each later admission wave forms its own barrier instead of racing. The queued member of such a batch is admitted once the live members settle rather than when the first of them finishes, so a batch whose first member finishes inside the 60 s admission deadline and whose last does not now expires that member's admission and aborts the batch; releasing the lease before the barrier would readmit a writer into the checkout the settlement is about to judge, so that wait stands. Taking the workspace fingerprint once on the settled tree also stops the verification memo key churning between siblings (`tests/contracts/host-verification-batch.test.ts`).
+
+- ACP's per-prompt usage accumulator (`AcpServerUsage`, `src/engine/acp/server.ts:206`) carried five discrete token fields and never a combined total or a dollar figure, while the TUI and the CLI `--json`/`--json-events` dispatch stream both carry `totalTokens` and `costUsd` for the same run; an editor connected over ACP had to reconstruct the total itself and had no way at all to show cost. `mergeUsage` now reads `usage.cost.total` off the same `message_end`/`agent_end` message objects `sumRunUsage` already reads for the TUI and json-stream paths, so ACP's dollar figure is never re-derived through a separate pricing calculation, and `totalTokens` follows the same explicit-value-or-summed-fallback rule `sumRunUsage` uses. Both fields ride in the existing `clio-coder/usage` `_meta` key on the `session/prompt` result. `tests/contracts/acp-usage-meta.test.ts` pins the accumulation, including the malformed-cost and explicit-total-wins cases.
+
+### Removed
+- `CLIO_CODER_RESUME_SESSION_ID` and `CLIO_CODER_BOOTSTRAP_GENERATE_CHILD` are no longer read: nothing has set the first since headless `--session` and `--continue` replaced the self-restart, and the bootstrap scout that the second guarded against now runs as an internal dispatch. The `budgetTokens` key in seven prompt fragments' frontmatter went with them; the loader reads only `id`, `version`, `description`, and `dynamic`. `TERM_PROGRAM` is still read for OSC 9 notification routing but no longer copied into the stream-pacing environment it never consulted.
+- `CLIO_CODER_SYNTHESIS_LOCK` is no longer read, and a synthesis-locked worker round always removes the tool surface on OpenAI-family runtimes. Its `tool-choice` mode kept the schemas and sent `tool_choice: none` instead, which preserved the locked round's prefix (350 to 900 new tokens against 1,200 to 1,800 for the strip, roughly half the prefill time), but it never beat the strip on any family measured on mini with a two-call recipe that locks every run, losing on two of the three and tying on the third. Lost-result counts, strip against tool-choice: Qwen3.8-27B 1 of 5 against 2 of 5, Ornith 1.5 35B 0 of 5 against 0 of 5, Ornith 1.5 9B 2 of 5 against 3 of 5. Under tool-choice the model called a tool anyway in 4 of 5 Qwen3.8-27B runs and 2 of 5 Ornith 1.5 35B runs, with no such count taken on Ornith 1.5 9B. Setting the variable now does nothing.
+
 ## 0.4.1 - 2026-09-01
 
 This grew beyond the bug-fix-only patch originally planned. v0.4.1 is a full release led by the version-2 `settings.yaml` contract, its automatic migration, and a smaller grammar-driven slash-command surface. It adds editor and marketplace workflows; fixes the release-blocking configuration, CLI, TUI, and Workbench failures found in final testing; replaces the oversized test and CI machinery with one fast deterministic gate; consolidates evaluation around the shipping eval domain and `evals/` reference suites; and moves machine-facing names into the `clio-coder` namespace without changing the product persona.

package/CONTRIBUTING.md

@@ -32,26 +32,39 @@ Local and GitHub PR gate (fast, deterministic):
 npm run ci
 ```
 
+This runs type checking, lint (including boundaries, documentation drift and
+skill pins), one build, the contract/smoke suite, and the trace-viewer suite.
+Use `npm run skills:check` when checking skill pins on their own; it is already
+included in `lint` and `ci`.
+
 Release gate (for maintainers before tags or release artifacts):
 
 ```bash
 npm run ci:release
 ```
 
-Live LLM smoke validation (manual/opt-in):
+The release gate includes `ci` and adds the package audit. Running `ci` again
+on the same unchanged tree is unnecessary. Run a focused regression while
+developing a repair, then the full gate for the candidate being reviewed.
+
+Live provider validation (manual/opt-in, after `npm run build`):
 
 ```bash
-npm run live:smoke -- --target <configured-target-id>
+node dist/cli/index.js run \
+  --target <configured-target-id> \
+  --autonomy read-only \
+  "Reply with exactly: CLIO_LIVE_OK"
 ```
 
 ## Testing conventions
 
-CLI-facing contract tests drive the built binary through the child-process
-harness in `tests/harness/spawn.ts`: `makeScratchHome()` gives the run an
-isolated `CLIO_CODER_HOME`, and `runCli(args, { env, cwd })` spawns `dist/cli` and
-returns its captured `stdout`, `stderr`, and exit code. Rebuild `dist/` with
-`npm run build` after changing CLI source, since these tests exercise the
-built output.
+Contract tests import `src/` directly through tsx. The test scripts preload
+`tests/harness/tmp-root.ts`, which gives the run one guarded temporary root,
+and stateful tests use the helpers in `tests/harness/scratch-env.ts` to isolate
+Clio's data, config, state, and cache directories. Smoke tests exercise the
+built `dist/cli/index.js`; their files own the process drivers needed for each
+boundary. Rebuild `dist/` after changing CLI or entry-point source before
+running a focused smoke test.
 
 Do not assert a CLI subcommand's output by capturing `process.stdout.write`
 in-process. In-process stdout capture fights the node:test spec reporter:
@@ -64,28 +77,46 @@ output in-process while the reporter runs.
 ## Releasing
 
 Releases are cut from a tag. The GitHub release is created by CI; the npm
-publish is a manual maintainer step. The ordered procedure for a cut lives in
-[docs/release-cut-checklist.md](docs/release-cut-checklist.md).
-
-1. Bump `version` in `package.json` and retitle the top section of
-   `CHANGELOG.md` to the version being cut. `scripts/check-release.mjs` fails
-   when the two disagree or the heading still says `Unreleased`.
-2. Run `npm run ci:release`. It runs the full `ci` gate, then
-   `scripts/check-release.mjs`, which verifies the built `dist/` and audits
-   the exact npm package contents.
-3. Land the release commit on `main`. There is no need to wait on the `ci`
-   workflow before tagging: the release workflow runs the same gate itself.
-4. Tag and push: `git tag -a vX.Y.Z && git push origin vX.Y.Z`. The tag must
-   match `package.json`'s version; the release workflow refuses mismatches.
-5. `.github/workflows/release.yml` verifies the tag against `package.json`,
-   runs `npm run ci:release` on the tagged tree, and creates the GitHub
-   release with the tarball attached and the version's `CHANGELOG.md` section
-   as the body. It does not publish to npm.
-6. A maintainer publishes from the tagged commit with `npm publish`;
-   `prepublishOnly` runs the same `ci:release` gate first.
+publish is a manual maintainer step. The current procedure is the sequence
+below together with `.github/workflows/release.yml` and
+`scripts/check-release.mjs`. The
+[v0.4.1 release-cut checklist](docs/history/release-cut-checklist.md) is a
+historical record, not a reusable current checklist.
+
+1. During development, keep the top changelog section at `## Unreleased`. A
+   maintainer collects release work on a **local-only** compact candidate
+   branch (`v043` for `v0.4.3`) and bumps `version` there. Never push this
+   candidate branch to the canonical repository. Before the cut, retitle the
+   changelog section `## <version> - YYYY-MM-DD`.
+2. Run `npm run ci:release` on the exact candidate. It runs the full `ci` gate,
+   then `scripts/check-release.mjs`, which verifies the built `dist/` and
+   audits the exact npm package contents.
+3. Fetch `origin`, require the fetched `origin/main` to be the candidate's
+   ancestor, then fast-forward local `main` with `git merge --ff-only v043`.
+   Re-run the release gate if the candidate changed and verify local `main`
+   equals the reviewed candidate SHA.
+4. Fetch once more and stop on unexpected movement. With explicit maintainer
+   authorization, push only `refs/heads/main:refs/heads/main`; no topic or
+   release-candidate branch is pushed to canonical `origin`.
+5. Require CI for that exact `main` SHA to pass. Create the annotated tag on
+   that commit and push only it: `git tag -a v0.4.3` followed by
+   `git push origin refs/tags/v0.4.3`. The tag must match `package.json`; the
+   release workflow refuses mismatches.
+6. `.github/workflows/release.yml` verifies the tag against `package.json`,
+   runs `npm run ci:release` on the tagged tree, and creates the GitHub release
+   with the tarball attached and the version's `CHANGELOG.md` section as the
+   body. It does not publish to npm.
+7. A maintainer publishes from the tagged commit with `npm publish`;
+   `prepublishOnly` runs the same `ci:release` gate in release mode first.
+8. Verify the release and tag, then delete the local compact candidate branch.
+   The canonical remote returns to its steady state: `main` plus immutable
+   release tags and GitHub releases, with no release branch.
 
 What `scripts/check-release.mjs` enforces, and how to respond when it fails:
 
+- Development branches may open with `## Unreleased`. Exact version tags and
+  `npm publish` require `## <version> - YYYY-MM-DD`, so unfinished notes cannot
+  enter an immutable artifact.
 - Only `dist/cli/index.js` and `dist/worker/entry.js` carry a shebang. The
   shebang comes from the hashbang line in each entry source file. Never add
   a tsup `banner`; it would stamp every chunk in `dist/`.
@@ -95,10 +126,10 @@ What `scripts/check-release.mjs` enforces, and how to respond when it fails:
 - Runtime resources must resolve from the installed package root: prompt
   fragments, builtin agents, model catalogs, the Markdown guides in `docs/`, the 128px logo,
   and `damage-control-rules.yaml`. A new runtime resource must be listed in
-  both package.json `files` and the required list in `check-release.mjs`.
+  both package.json `files` and `scripts/release-manifest.json`.
   The double bookkeeping is deliberate: neither edit can silently drop a
   resource the CLI needs at runtime.
-- Size budgets: 15 MB tarball, 40 MB unpacked, set in `check-release.mjs`.
+- Size budgets: 10 MB tarball, 50 MB unpacked, set in `check-release.mjs`.
   They are a tripwire for packaging defects such as a leaked `node_modules`
   or a doubled `dist/`, not a diet. If a legitimate change exceeds them,
   raise the budget in the same PR with a justification, never as a drive-by.
@@ -112,29 +143,45 @@ that needs them runs.
 
 ## Hard Rules
 
-1. Do not push to `main`.
-2. Open pull requests against `main`.
-3. `main` requires review by `@akougkas`.
+1. The canonical repository's only branch is `main`. Maintainer topic,
+   integration, and release-candidate branches stay local and are never pushed
+   to canonical `origin`.
+2. Contributors push topic branches to their own forks and open pull requests
+   from the fork into canonical `main`; they never push a topic branch to the
+   canonical repository.
+3. A maintainer may update canonical `main` only by an explicitly authorized,
+   reviewed fast-forward from the exact locally gated candidate. Everyone else
+   changes `main` through a pull request reviewed by `@akougkas`.
 4. Keep every PR focused. Split unrelated docs, runtime, CLI, and TUI work.
 5. Update `CHANGELOG.md` for user-visible behavior, developer workflow, or
    release status changes.
 6. Run `npm run ci` before requesting review.
 7. Do not commit secrets, local config, generated `dist/`, or scratch plans.
+8. Push release tags as fully qualified `refs/tags/vX.Y.Z`; never push a
+   similarly named branch.
 
 ## Architecture Invariants
 
-The boundary checker enforces these:
-
-- Engine boundary: only `src/engine/**` value-imports pi SDK packages
-  (`@earendil-works/pi-*`, pinned in `package.json`).
-- Worker isolation: `src/worker/**` value-imports only the worker-safe
-  provider runtime rehydration modules under `src/domains/providers/**`;
-  all other worker domain imports must be type-only.
-- Domain independence: cross-domain flows go through `SafeEventBus`.
+The boundary checker enforces these six rules:
+
+- Engine boundary: only `src/engine/**` imports the
+  `@earendil-works/pi-*` packages, including type-only imports.
+- Worker isolation: `src/worker/**` may value-import only the declared
+  provider runtime rehydration seams under `src/domains/providers/**`; all
+  other worker imports from domains must be type-only.
+- Domain independence: one domain never imports another domain's
+  `extension.ts`; cross-domain behavior uses public contracts and event buses.
+- Tool substrate: `src/tools/**` never imports `src/interactive/**`.
+- Entry-point composition: `src/interactive/turn-*.ts` and `chat-loop.ts` never
+  import `src/entry/**`.
+- Stage 0 closure: external value importers enter the protected instant-shell
+  graph only through declared seams, and those seams may not create an
+  undeclared edge back into the closure.
 
 The checker runs as part of `npm run lint` (`scripts/check-hygiene.ts` imports
 `tests/boundaries/check-boundaries.ts`), so a boundary violation fails the
-same lint every PR runs.
+same lint every PR runs. The full definitions and exceptions live in
+[Architecture](docs/architecture/architecture.md#boundary-invariants).
 
 ## Branches
 
@@ -152,6 +199,44 @@ Examples:
 - `fix/session-resume-replay`
 - `docs/github-governance`
 
+Maintainer branches are local-only. A temporary release candidate uses the
+compact version spelling with no dots: `v043` for release tag `v0.4.3`. Never
+create or push a branch named `v0.4.3`; dotted `vX.Y.Z` names belong exclusively
+to immutable release tags. The compact branch is local scaffolding and is
+deleted after its reviewed commit reaches `main` and the release succeeds.
+
+Contributors use the same topic prefixes in their own forks. The pull request
+head is `<contributor-fork>:<topic>` and its base is canonical `main`. Delete
+the fork branch after merge so both the canonical repository and contributor
+forks return to a small steady state.
+
+### Branch closeout
+
+Branch and worktree cleanup is part of finishing work, not optional future
+housekeeping. Use `branch-closeout` (or `ship closeout`) to automate this
+verification and teardown safely. After a PR is merged or a release is tagged:
+
+1. Fetch and prune remote-tracking refs, then verify the PR is merged and its
+   result is represented on `origin/main`. An ancestry check is sufficient for
+   merge commits; squash and cherry-pick landings require the merged PR and
+   resulting commit as evidence rather than a matching subject alone.
+2. Confirm the source worktree has no tracked or untracked work worth keeping.
+   Remove a registered worktree with `git worktree remove <path>`, never
+   `rm -rf`; use `--force` only after explicitly authorizing disposal of the
+   remaining local artifacts.
+3. Delete the local topic or release branch. For a contributor PR, delete its
+   branch from the contributor's fork after merge. A topic branch must never be
+   created on canonical `origin`, and canonical `main` is never deleted.
+4. Preserve unfinished experiments by filing their result and next decision in
+   an issue, not by accumulating anonymous `work/`, `wip/`, or `tmp` refs.
+5. Report the remaining local branches, worktrees, stashes, local-only tags,
+   and canonical remote heads. The expected canonical head set is exactly
+   `refs/heads/main`; every additional head is a cleanup failure.
+
+For a release, first verify `refs/tags/vX.Y.Z^{commit}` equals the reviewed
+commit on `main`, then close the compact candidate branch such as `v043`.
+Published tags are never deleted, moved, or recreated during cleanup.
+
 ## Commits
 
 Use concise conventional subjects:
@@ -206,19 +291,24 @@ Agents should:
 `skills/` is the curated skills marketplace: maintainer-approved `SKILL.md`
 guides, distinct from the runtime skills any user can drop into a discovery
 root. It is not itself a discovery root, so nothing here auto-loads; skills
-activate only via `clio-coder skills install <name>`.
+activate after `clio-coder skills install <name>` or from an explicit
+`clio-coder --skill skills/<category>/<name>/SKILL.md` development path.
 
 To propose a skill:
 
-1. Add `skills/<name>/SKILL.md`. Follow the `superpowers:writing-skills`
-   methodology and Anthropic's skill-authoring guidance: a trigger-rich
-   `description` (third person, "Use when ..."), one excellent example, and
-   progressive disclosure (push heavy reference into `references/`).
-2. Include the provenance frontmatter (`registry-id`, `source-url`, `version`,
-   `license`) and ship an `evals.md` with the baseline scenarios you tested.
-3. Verify locally: `clio-coder skills validate skills/<name>/SKILL.md`, then
-   `clio-coder skills install <name>` and `clio-coder skills list`.
-4. Open a PR. A maintainer reviews against the rubric, then sets `audit: pass`
-   and the `version` to approve it for the catalog.
+1. Add `skills/<category>/<name>/SKILL.md`. Follow the local
+   [`skill-craft`](skills/meta/skill-craft/) guidance: put trigger phrases in
+   `triggers`, keep `description` to the job and explicit routing boundaries,
+   and move conditional detail into `references/`.
+2. Include the core `name`, `description`, `version`, and `license` fields plus
+   a nested `clio-coder:` block with `registry-id`, `source-url`, `provenance`,
+   and `eval-status`. Ship an `evals.md` with the baseline scenarios.
+3. Verify locally with
+   `clio-coder skills validate skills/<category>/<name>/SKILL.md`.
+4. Install the candidate by name and confirm it appears with
+   `clio-coder skills list`.
+5. Open a PR. A maintainer reviews against the rubric, sets `audit: pass`,
+   approves the catalog version, then regenerates and checks the catalog with
+   `npm run skills:pin` and `npm run skills:check`.
 
 Full catalog conventions and install options: [skills/README.md](skills/README.md).