@iowarp/clio-coder 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -2,6 +2,104 @@
 
 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.4 - 2026-09-05
+
+Trust spine: typed claims, executable validation, and decision provenance. Answers the NSF "Beyond Code" findings where the harness still trusted prose or sniffed files.
+
+### Added
+- A Deno test validates that class tokens used across Workbench components exist in the stylesheet (#311).
+- Lint holds `docs/guide/configuration-reference.md` against `DEFAULT_SETTINGS`: the new `configuration-reference` hygiene check fails when a settings key has no row in the settings-key table or a row names a key path the defaults no longer carry.
+- The `limitation` tool records what a turn could not verify and why. The finish contract settles on a successful `limitation` receipt inside the same window as the mutation scan; the seven prose patterns that used to satisfy it are gone, so wording alone can no longer pass the gate. The tool is on the six mutating recipes, and the operating contract tells the model to call it.
+- One strict loader for the version-1 scientific validation contract (`src/domains/safety/validation-contract.ts`), shared by rigor, `verifiers author`, doctor, and the startup hint. Rigor rises to `high` only when the contract parses; an invalid contract is diagnosed with the field and cap named, and `VALIDATION.md` is advisory prose that never raises rigor on its own.
+- The `decide` tool records a design choice with the alternatives the model rejected and why, as an `origin: "agent"` decision-ledger entry beside operator `ask_user` answers. A repeat key supersedes the earlier agent decision; an operator decision is never overwritten by the model. Dispatch seals every active decision ref onto the run request, envelope, and receipt under integrity coverage, and Clio-controlled commits carry one `Clio-Decision: <interviewId>/<key>` trailer per ref from the receipt or the live board.
+- Recorded decisions reach the surfaces that cite them. Evidence resolves a sealed receipt's `decisionRefs` against the linked session's active path, records the resolved arguments in `overview.json`, and raises a resolved or missing-reference finding per ref in both readable documents. Handoff and oracle briefings carry each decision's alternatives and rationale, and wiki page writers receive up to twelve active decisions matching their page's sources and cite the refs in the body and optional `decisions` frontmatter.
+- The read-only `evidence` tool shares the CLI inventory and trust projections, with overview, findings, and verified gate decisions for provenance inspections. Provenance requires this tool, and Verifier can use it. Accountability reports unverified successful runs and ungrounded validation claims in `/view`, `clio-coder usage`, and the observability contract. Historical index rows contribute zero to the new counters when the required fields are absent.
+- Verifier catalog version 2 adds two executable check kinds beside `command`. `numeric-compare` runs the command, parses its stdout as a JSON object of numbers or number arrays, and judges it against a repository-relative reference file under `relative`, `absolute`, or `ulp` tolerances (every named bound must hold; missing keys, shape and length mismatches, `NaN`, and infinity fail), reporting each key's worst deviation and the tolerance it failed. `perf-budget` judges the measured wall time against `budget: {wallTimeMs, tolerance?}` or a baseline that `clio-coder verifiers baseline <id>` records, reporting measured time, effective budget, and ratio. The `verify` tool and dispatch host verification both run the judgement and seal the report (`report` on the host-verification check, under receipt integrity); a failing judgement is a check failure with the report in the detail. Version 1 catalogs still load with every check as `kind: command`. `verifiers add` and `edit` take `--kind`, `--reference`, `--tolerance`, `--budget-ms`, `--budget-relative`, and `--baseline`; `verifiers author` lists an incomplete `numeric-compare` check for every validation-contract artifact that declares `numerical_tolerances`, with the command left for the operator.
+- Operator tasks carry optional acceptance through repeatable `--expect` and `--verify` flags in the CLI and `/tasks add`. Shared dispatch normalizers validate paths and bounded checks, pickup persists required board evidence, and high rigor requires a passing receipt or a limitation naming each acceptance check.
+- An opt-in `--strict` switch for `scripts/smoke-real-home.sh` causes the real-home release smoke to fail when doctor exits 1 on failing rows, while default runs continue to tolerate operator fleet state (#293).
+- A current release-cut checklist in `docs/process/release-cut-checklist.md` and paired blueprint for maintainers to verify and publish releases (#298).
+- ACP registry submission assets including `assets/acp-registry/agent.json` and `assets/acp-registry/icon.svg` with submission documentation in `docs/architecture/acp.md` (#314).
+
+### Changed
+- Retry admission rebinds a held plan-reservation member under the async state-file lock, so a dispatch attempt waiting on the cross-process capacity lock yields the event loop instead of spinning in `Atomics.wait` (#319). Plan preparation still takes the synchronous lock because the tool registry's `prepareAdmissionArguments` hook cannot yield.
+- Document that headless Antigravity reports permission_mode always-proceed under mode plan and sandbox, and that Clio grades enforcement as approximated (#281).
+- The runs.json ledger carries version 1 on RunEnvelope records, treating legacy unversioned rows as version 1 and skipping records with any other version.
+- Claude CLI workers now accept the built-in recipes. The `claude-code` runtime declares its external agent loop the way Antigravity does, so a recipe budget is admitted as `external-one-shot` with the per-tool count recorded as unobserved instead of refusing the dispatch. Claude Code CLI stays under Subscriptions in `configure --list` and keeps its `claude-cli` auth status; retries and orchestrator eligibility are unchanged (#280).
+- The Claude Code CLI worker now uses the same hardened transport as the Antigravity worker. `claude` receives only the allowlisted environment instead of the whole process environment, so provider keys and Clio gates no longer reach it. The user turn travels on stdin rather than argv; system text remains in `--append-system-prompt`. The admitted `cwd` is honored and refused when it escapes the workspace root, stdout is read through the bounded line reader (1 MiB per line, 8 MiB total) and a violation ends the run as an error, and cancellation terminates the POSIX process group even when the immediate CLI exits before its descendants. Windows retains direct-child cancellation (#279).
+- The dispatch board reads observability's run projection. One fold owns lifecycle events, worker progress, receipt trust, retries, cancellation, fleet positions, and evidence readiness; the board keeps ordering, selection, and rendering. Terminal status and accounting come from the same projection the observability contract publishes.
+
+### Fixed
+- ACP permission cancellation now aborts the active turn before releasing parked tools, preventing an extra provider request while Workbench settles an unanswered approval (#341).
+- The deterministic behavioral machinery suite declares the `default` target used by its dispatch fixture, so all 26 cases produce an artifact that `eval report` and self-comparison can load with strict execution provenance validation (#342).
+- Compete respects a candidate receipt's effective read-only autonomy when finalizing work. Generated `.clio-coder/codewiki.json` and `.clio-coder/state.json` are excluded from writer staging and judge branch diffs even when the caller's `.gitignore` update is uncommitted or the runtime files were already staged. Authored edits, including tracked Clio project configuration, still commit and apply; unrelated staged and unstaged caller changes remain intact (#347).
+- Host verification memoization and batch deduplication now include the check identity, kind, execution timeout, numerical tolerances, performance bounds, and reference or baseline contents. Different judgments cannot inherit an earlier pass, while identical valid checks retain evidence reuse and provenance (#333).
+- Host numerical verification now judges bounded command stdout, matching ordinary verify. JSON diagnostics on stderr cannot supply a missing measurement or invalidate valid stdout; stderr remains available in the command artifact (#334).
+- High-rigor task acceptance now requires validation evidence from the owning workspace. Verifier receipts retain declaration source and execution details, so a passing same-named examples check cannot satisfy a root check. Intended package and catalog checks, exact root package commands, and scoped limitation receipts remain supported (#335).
+- Skills with an allowed-tools list, including coding-standards and the related coding workflows, can record the finish contract's limitation receipt. Explicit tool denials and restrictions on unrelated actions remain enforced (#336).
+- Slash argument completion now reads loaded agent recipes, configured targets and known models, installed skills, and session tasks from the interactive app contracts (#303).
+- Workbench desktop notification mute preference now persists in local storage across page reloads (#322).
+- ACP close and reopen starts a fresh conversation on the same child process, clearing provider history and turn ancestry while switching the task board to the new session. Explicit session loading still restores the saved conversation and tasks (#312).
+- Sessions without interactive ask_user now receive one passive marketplace reminder per matching skill per session, including its installation command, without starting an interview or recording a decline (#317).
+- Setting interface.panes.enabled=embedded refuses with a visible reason instead of silently degrading to guest detection (#294).
+- ACP production stdout now uses the bounded queue through its output guard, waits for drain before sending more frames, and closes with a typed error when stalled output exceeds the existing 1 MiB UTF-8 byte budget, including the first frame that stalls the stream (#309).
+- Dispatch to a subprocess worker no longer fails at prompt compilation when the recipe offers the canonical `context` tool. The Claude CLI declares tool support, so `context` survived tool narrowing while the compiler correctly treated the subprocess surface as unattached, and every built-in recipe that lists `context` (architect, scout, oracle, researcher, and others) was refused with a `hasCanonicalContext` mismatch. The attached-context fact is now derived from the runtime kind, and bound skills are neither promised in the prompt nor stamped on the worker spec for a runtime that never receives Clio's tools.
+- Ollama eviction now releases only models this Clio process successfully pinned on the same server, preserving models loaded by operators or other clients (#313).
+- Deprecation warnings for the legacy lmstudio-native runtime id now route through warnLegacyNaming, reporting the planned v0.7.0 removal and deduping per process.
+- Fleet run preview diagnostics and approval overlays now format cost totals through the shared formatter so amounts at or above one cent render with two decimals instead of four.
+- Default path policy now marks project and user skill roots read-only for workers and the orchestrator, alongside the existing skill-authority guard; operator installs continue through the CLI (#300).
+- Scratch offload sweeps now report non-ENOENT filesystem errors in a skipped count instead of silently swallowing them.
+- Model discovery no longer treats target status with an undefined model source as a live catalog.
+- The upgrade command now gates test seams behind NODE_ENV=test so testing environment variables are ignored in production.
+- Marketplace offer reminders now collapse catalog descriptions to one line, strip square-bracketed directive markers, and cap description text at 200 characters (#316).
+- Damage-control no longer treats command quotations in `dispatch` and `tasks` prose as shell execution. Execute-class calls still use the same blocked command patterns (#286).
+- Doctor state storage inspection now shares the lifecycle presenter byte formatting helper instead of keeping a private copy with differing units, printing consistent byte sizes across doctor, reset, and uninstall.
+- The `coding-standards` skill (0.4.0) declares an `allowed-tools` surface again (`read`, `grep`, `find`, `ls`, `code_nav`, `bash`, `write`, `edit`) instead of no narrowing at all, so a solo run can both read and write code.
+- ACP delegation usage now carries `totalTokens` and `costUsd`, merged with the same rule the ACP server uses: an explicit total or cost from the peer is taken as reported, otherwise the total is the sum of input, output, and cache tokens and the cost stays 0.
+- The dispatch typed-intent reason-code table now documents `legacy_scope_inferred` as the warn that `path-scope.ts` emits when prose inference resolves a leading `../` run against the dispatch root, instead of calling it an unemitted compatibility id.
+- The `muse-glimmer-30b` catalog notes, runtime preference, and guidance now say the reasoning strength dial is driven per request through `chatTemplateKwargs.byLevel` on llama.cpp and reported as undeliverable on LM Studio, instead of claiming no per-request field exists.
+- `clio-coder eval run` spawns a `clio-coder-run` task as an argv instead of a `sh -c` line, so the task deadline reaches the Clio process itself and the exit code the runner reports is Clio's own. Through dash the shell stayed the parent: the deadline's SIGTERM stopped the shell while Clio finished the turn, wrote its report artifact, sealed a succeeded receipt with exit 0, and exited 0, and the item was recorded as `runner_failed` beside an ok receipt with `receipt.outcomeMatchesExit` false. A run the deadline reaches is now canceled, and its receipt records the cancellation with the exit status the runner reports. The SIGKILL grace after that SIGTERM is five seconds, long enough for Clio's coordinated shutdown to seal the interrupted run's receipt. The context-init and context-index eval runners now spawn through the same argv form. (#275)
+
+### Removed
+- Retired slash command hints for former command spellings are removed so unrecognized commands fall through to the standard unknown command error.
+- The unused `--kv-cache-mode` command-line flag and its run override field are removed because no runtime reads them.
+
+## 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.
+- The trace viewer shows each run's `source` (`dispatch` or `session`) as a small badge beside the run id on the run list and beside the status on the run page, matching the SOURCE column `clio-coder trace runs` already prints. The list filter matches the badge text, so typing `session` narrows the list to interactive turns. A mirror whose rows carry no `source` field renders no badge. Contract: `apps/trace-viewer/tests/client-smoke.test.mjs`. (#289)
+
+### 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.
+- Every catalog SKILL.md that describes headless `ask_user` now states the same behavior the `clio-coder run` help text does: the tool is not registered, so any call is refused as an unregistered tool rather than answered. Fifteen skills take a patch bump for the correction.
+
+### 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

package/CONTRIBUTING.md

@@ -32,12 +32,21 @@ 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
 ```
 
+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
@@ -74,22 +83,34 @@ below together with `.github/workflows/release.yml` and
 [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` and
-   bump `version` in `package.json` when opening the release branch. Before the
-   cut, retitle that section `## <version> - YYYY-MM-DD`.
-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`;
+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:
 
@@ -105,7 +126,7 @@ 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: 10 MB tarball, 50 MB unpacked, set in `check-release.mjs`.
@@ -122,14 +143,22 @@ 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
 
@@ -170,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:

package/README.md

@@ -138,7 +138,13 @@ The complete interactive and CLI reference is
 Clio stores each model connection as a named **target**: runtime, endpoint,
 model, credentials, and any verified capability overrides. Interactive chat,
 proactive memory, fleet defaults, and individual worker profiles can route
-independently.
+independently. A LiteLLM target keeps the gateway in charge of physical routing,
+authentication, and backend residency; distinct model routes can share one URL.
+Set `context.memory.target` and `context.memory.model` to opt into a dedicated
+memory model. Unset memory roles remain rules-only; a configured route can fall
+back to active chat when unavailable and request capacity permits.
+`context.compaction.model` selects a dedicated summary model; leaving it unset
+uses active chat. An invalid explicit compaction model fails visibly.
 
 | Target family | Supported routes |
 | --- | --- |
@@ -147,7 +153,7 @@ independently.
 | Cloud APIs | OpenAI, Anthropic, Google, Groq, Mistral, DeepSeek, OpenRouter, Amazon Bedrock |
 | Institutional gateways | Argonne ALCF Sophia and Metis over Globus OAuth |
 | Subscriptions | ChatGPT Plus/Pro through `openai-codex`; Claude Pro/Max through `anthropic-max` |
-| Worker integrations | Claude SDK, Claude Code, Google Antigravity, and configured ACP agents |
+| Worker integrations | Claude SDK, Claude Code, experimental Google Antigravity delegation, and configured ACP agents |
 
 The interactive wizard is the easiest path:
 
@@ -222,11 +228,24 @@ directory. See [Context Engine](docs/architecture/context-engine.md),
 [Proactive Memory](docs/guide/proactive-memory.md) for the detailed contracts.
 
 The local skills marketplace may offer a matching shipped skill during a
-request. Promotion installs are restricted to Clio's own catalog or this
-repository and do not activate the skill automatically. Manual installs remain
-available for a source you deliberately choose. See
+request. Every promotion install requires an explicit bound operator answer,
+including in full-auto. Promotion installs retain their catalog source gate,
+and installation does not activate the skill. Active
+project and user skill trees are operator-owned: main and worker tool admissions
+refuse direct and recognized shell mutations. Draft skill changes outside those
+roots, then use the operator's installation or update workflow. This bounded
+command inspection does not confine arbitrary programs or dynamic shell paths.
+Manual installs remain available for a source you deliberately choose. See
 [Skills Marketplace](docs/guide/skills-marketplace.md).
 
+For a repository architecture map, run `clio-coder context index` followed by
+`clio-coder context map`. The latter writes a deterministic JSON seed from the
+index's directory areas and imports. The operator-installed `archify` remote
+skill validates and delivers the interactive diagram; Clio ships its wrapper
+and pinned install metadata, while the renderer comes from upstream. Source
+citations require a pinned GitHub revision. Validation can still report
+composition warnings that need human edits.
+
 ## Delegate with bounds
 
 Clio's orchestrator can send focused assignments to worker agents instead of
@@ -289,6 +308,16 @@ clio-coder trace phases <run-id>
 clio-coder trace tail <run-id>
 ```
 
+`clio-coder usage report` preserves known failed-compaction spending and labels
+missing coverage. Adapter prices are estimates, and numeric spending ceilings
+bound the known sum; absent telemetry does not prove a call was free. Eval's
+provider-health checks are opt-in and separate from task success. Partial or
+mixed session/stdout evidence and inherited fork history are not reconciled;
+full reconciliation is deferred to v0.4.5 or later, and 0.4.3 does not add an
+automatic cost-comparison rejection. See the
+[Eval Runner](docs/process/eval-runner.md#token-accounting--provenance) for source
+and timing limits.
+
 Evidence helps you audit a run; it does not prove that generated code is
 scientifically correct. Domain validation, reference results, and human review
 remain part of the job. The detailed boundaries are in
@@ -354,7 +383,7 @@ clio-coder --version
 From source, pinned to this version:
 
 ```bash
-git clone --branch v0.4.2 https://github.com/iowarp/clio-coder.git
+git clone --branch v0.4.4 https://github.com/iowarp/clio-coder.git
 cd clio-coder
 npm ci
 npm run install:local

package/dist/{acp-TMDQZDIG.js → acp-WNAYYF4F.js}

@@ -6,32 +6,31 @@ import {
 } from "./chunk-2VTFPG5O.js";
 import {
   runClioCommand
-} from "./chunk-2HFQNRV3.js";
-import "./chunk-M2DAX4F6.js";
-import "./chunk-ZTJUVLTU.js";
+} from "./chunk-UEPWCCTY.js";
+import "./chunk-4WR7VSYB.js";
 import "./chunk-I7XBWTYH.js";
-import "./chunk-ZW55JB7N.js";
+import "./chunk-3ODX73FK.js";
+import "./chunk-ZTJUVLTU.js";
 import {
   printError
-} from "./chunk-VPKWYKEY.js";
-import "./chunk-5TSRNF4G.js";
-import "./chunk-34BHNEE3.js";
+} from "./chunk-JCI2ROMZ.js";
+import "./chunk-GHS5EBTQ.js";
 import "./chunk-D7E7WCDF.js";
-import {
-  MAX_TIMER_DELAY_MS
-} from "./chunk-EBY63B7G.js";
 import "./chunk-IWHMRKLL.js";
 import "./chunk-UXCU4E3T.js";
 import "./chunk-LL4KHSZI.js";
 import "./chunk-S66XZJOF.js";
-import "./chunk-WNP7O5WZ.js";
+import {
+  MAX_TIMER_DELAY_MS
+} from "./chunk-EBY63B7G.js";
+import "./chunk-ID64D7PE.js";
 import "./chunk-336NSSKI.js";
 import "./chunk-IKCO5N3L.js";
 import "./chunk-3I7MS7N2.js";
 import "./chunk-APJ265NV.js";
-import "./chunk-BYP5D4HI.js";
 import "./chunk-WEPFGWHJ.js";
 import "./chunk-YXLYO42X.js";
+import "./chunk-BYP5D4HI.js";
 import {
   init_esm_shims
 } from "./chunk-3R73A4XB.js";
@@ -127,4 +126,4 @@ async function runAcpCommand(args, options = {}) {
 export {
   runAcpCommand
 };
-//# sourceMappingURL=acp-TMDQZDIG.js.map
+//# sourceMappingURL=acp-WNAYYF4F.js.map

package/dist/{agents-5N5NG3XG.js → agents-3OKXHLOI.js}

@@ -1,87 +1,90 @@
 import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
+import "./chunk-JQLNNIKT.js";
+import "./chunk-GWZNEVM2.js";
+import "./chunk-5ICU3EUH.js";
+import {
+  ConfigDomainModule,
+  loadDomains
+} from "./chunk-72YIHOZQ.js";
+import "./chunk-4WR7VSYB.js";
 import {
   SafetyDomainModule
-} from "./chunk-54ODD65L.js";
-import "./chunk-F2I26BDK.js";
-import "./chunk-DYHAXKHD.js";
-import "./chunk-QQLGQY2A.js";
+} from "./chunk-5636DCO5.js";
 import {
-  ensureClioState
-} from "./chunk-XQRY4DTA.js";
-import "./chunk-3KIPBMUA.js";
+  AgentsDomainModule
+} from "./chunk-RZDWV63N.js";
+import "./chunk-7UGL4MB5.js";
+import "./chunk-DR52UMZW.js";
+import "./chunk-ODGTEFFI.js";
+import "./chunk-OEJSLEPW.js";
+import "./chunk-RKKLTLYB.js";
+import "./chunk-2ASED4PZ.js";
 import {
-  ConfigDomainModule,
-  loadDomains
-} from "./chunk-CYZW7JHJ.js";
+  ensureClioState
+} from "./chunk-IGLP3ODT.js";
 import "./chunk-3M6DQK6S.js";
-import "./chunk-M2DAX4F6.js";
-import "./chunk-4O6MANBS.js";
 import "./chunk-LCGCVYZ4.js";
-import "./chunk-RVG5JXAL.js";
+import "./chunk-2ZSONWVL.js";
+import "./chunk-NDDGJUXD.js";
+import "./chunk-YECAMM3D.js";
+import "./chunk-V76WTFTW.js";
 import "./chunk-3DPEIQKN.js";
+import "./chunk-TQAHXW6Y.js";
+import "./chunk-5MEZN6CB.js";
+import "./chunk-NEKRRTYW.js";
+import "./chunk-JEIYHLOR.js";
+import "./chunk-I7XBWTYH.js";
+import "./chunk-3ODX73FK.js";
+import "./chunk-4O6MANBS.js";
 import {
-  AgentsDomainModule
-} from "./chunk-P75RZCJW.js";
-import "./chunk-CRFOIAX3.js";
-import "./chunk-DR52UMZW.js";
-import "./chunk-O3YUNJZ2.js";
-import "./chunk-NDDGJUXD.js";
-import "./chunk-XGDPUNND.js";
-import "./chunk-3F7VUY77.js";
-import "./chunk-RKKLTLYB.js";
-import "./chunk-HLAFFSEK.js";
-import "./chunk-77QIVUZB.js";
+  printError
+} from "./chunk-JCI2ROMZ.js";
 import "./chunk-5PSMVOLM.js";
-import "./chunk-QSNYB6ZV.js";
-import "./chunk-QDC3K2U3.js";
-import "./chunk-IDNA72AH.js";
-import "./chunk-FVDGR2ZL.js";
-import "./chunk-VN3SHNBN.js";
-import "./chunk-FSP7CMNU.js";
-import "./chunk-HHV2GANA.js";
+import "./chunk-6QOTUPRG.js";
+import "./chunk-6Q3CYFD3.js";
 import {
   isUserVisibleAgent
-} from "./chunk-PGF63K6I.js";
-import "./chunk-IKOZFYBN.js";
-import "./chunk-UL3WSD3F.js";
+} from "./chunk-KFV5L5SK.js";
+import "./chunk-NXYCB2VD.js";
 import "./chunk-ECH6PKUQ.js";
+import "./chunk-DXKJURES.js";
+import "./chunk-HHV2GANA.js";
+import "./chunk-GYV6VZOC.js";
+import "./chunk-UL3WSD3F.js";
 import "./chunk-5B2AEOW5.js";
-import "./chunk-K6BSR66V.js";
-import "./chunk-XPLRXC72.js";
-import "./chunk-NEKRRTYW.js";
-import "./chunk-JWJGP5DQ.js";
-import "./chunk-I7XBWTYH.js";
-import "./chunk-ZW55JB7N.js";
-import {
-  printError
-} from "./chunk-VPKWYKEY.js";
-import "./chunk-5TSRNF4G.js";
-import "./chunk-72GZI5EV.js";
-import "./chunk-MQXIVJ35.js";
+import "./chunk-QSNYB6ZV.js";
+import "./chunk-54X7T7DK.js";
+import "./chunk-I5FWO7L5.js";
+import "./chunk-6XLNIQDB.js";
+import "./chunk-4NSRCOYP.js";
+import "./chunk-QDC3K2U3.js";
+import "./chunk-2JH2WHGE.js";
+import "./chunk-KXDSS5WJ.js";
+import "./chunk-GHS5EBTQ.js";
+import "./chunk-D7E7WCDF.js";
+import "./chunk-HAXOFFRH.js";
 import "./chunk-R346GLFC.js";
-import "./chunk-PMZVFWSR.js";
 import "./chunk-BTK3SSSK.js";
-import "./chunk-IHXBNWMM.js";
-import "./chunk-34BHNEE3.js";
-import "./chunk-D7E7WCDF.js";
-import "./chunk-HJWWJ6IL.js";
+import "./chunk-PMZVFWSR.js";
 import "./chunk-F4EKGO4N.js";
-import "./chunk-JIEGK6UF.js";
-import "./chunk-EBY63B7G.js";
-import "./chunk-6EJMN2Y3.js";
+import "./chunk-XPLRXC72.js";
 import "./chunk-IWHMRKLL.js";
 import "./chunk-UXCU4E3T.js";
 import "./chunk-LL4KHSZI.js";
 import "./chunk-S66XZJOF.js";
-import "./chunk-WNP7O5WZ.js";
+import "./chunk-TOIVGRUX.js";
+import "./chunk-U6TMQNSI.js";
+import "./chunk-EBY63B7G.js";
+import "./chunk-6EJMN2Y3.js";
+import "./chunk-ID64D7PE.js";
 import "./chunk-336NSSKI.js";
 import "./chunk-IKCO5N3L.js";
 import "./chunk-3I7MS7N2.js";
 import "./chunk-APJ265NV.js";
-import "./chunk-BYP5D4HI.js";
 import "./chunk-WEPFGWHJ.js";
 import "./chunk-NUGM5KR6.js";
 import "./chunk-YXLYO42X.js";
+import "./chunk-BYP5D4HI.js";
 import {
   init_esm_shims
 } from "./chunk-3R73A4XB.js";
@@ -141,4 +144,4 @@ function renderLine(spec) {
 export {
   runAgentsCommand
 };
-//# sourceMappingURL=agents-5N5NG3XG.js.map
+//# sourceMappingURL=agents-3OKXHLOI.js.map