@iowarp/clio-coder 0.4.0 → 0.4.2

package/docs/documentation-guide.md

@@ -1,167 +0,0 @@
-# Documentation Standards and Codebase Alignment
-
-> [!TIP]
-> **Interactive Spec Available:** An interactive documentation link linter, phrasing/claim evaluator, and alignment portal is located at [docs/html/documentation_blueprint.html](html/documentation_blueprint.html) (Version: 0.4.0).
-
-Clio Coder is an experimental community alpha. Documentation should help contributors and early users work from the source of truth without overstating maturity. When docs drift, prefer the current source and tests over older prose or aspirational roadmap notes.
-
----
-
-## Source-first documentation rule
-
-Before changing public docs, inspect the relevant implementation:
-
-1. `git log --oneline -- <area>` for recent intent and release context.
-2. `src/**` for current behavior.
-3. `tests/**` for executable contracts and edge cases.
-4. `README.md`, `CHANGELOG.md`, and `docs/*.md` for existing public wording.
-
-Classify claims clearly:
-
-| Claim class | How to word it |
-| --- | --- |
-| Shipped and tested | State directly and link to source/tests. |
-| Implemented but experimental | Say alpha/experimental and name sharp edges. |
-| Typed contract exists, default runtime is inert | Say the schema exists but no public loader/rules are active. |
-| Planned/future | Put in roadmap language; do not present as available behavior. |
-
----
-
-## Documentation map
-
-| Guide | Primary source references | What it should cover |
-| --- | --- | --- |
-| [README.md](../README.md) | `CHANGELOG.md`, package metadata, release receipts | Product overview, install, first run, alpha framing, and release status. |
-| [docs/README.md](README.md) | This docs directory | Documentation hub. |
-| [commands-and-modes.md](commands-and-modes.md) | `src/cli/index.ts`, `src/cli/args.ts`, `src/interactive/slash-commands.ts`, `src/domains/dispatch/**` | CLI commands, headless run flags (`--session`, `--continue`, `--json-events`), session continuity, `--json` wire projection promise, slash commands, keybindings, live steering. |
-| [context-engine.md](context-engine.md) | `src/domains/context/**`, `src/domains/session/context-accounting.ts`, `src/domains/session/context-ledger.ts`, `src/domains/session/compaction/` | Context window resolution, per-model probe capabilities, token accounting, snapshots, the three compaction mechanisms, model-driven `clio-coder context init`, format v4 session enforcement. |
-| [context-working-set.md](context-working-set.md) | `src/domains/context/working-set/**`, `src/domains/session/entries.ts`, `src/interactive/turn-context.ts` | Working-set vocabulary, eviction as a projection, the `contextEviction` / `contextRecall` records, the marker contract, the `age-horizon` and `structural-v1` policies, recall semantics, and the operator surfaces. |
-| [architecture.md](architecture.md) | `tests/boundaries/check-boundaries.ts`, `src/core/domain-loader.ts`, `src/engine/**`, `src/worker/**` | Source layout, 5 enforced boundary rules (dependency direction vs import form), runtime flow mermaid diagram, event/audit model, detect-and-rollback write boundaries. |
-| [dispatch-architecture-rationale.md](dispatch-architecture-rationale.md) | `src/domains/dispatch/**`, `tests/boundaries/check-boundaries.ts` | Design rationale, not behavior: invariants that cross the seams a dispatch split would use, what any future split must preserve, the one dispatch→eval import, and the closed barrel-import decision. |
-| [configuration-and-targets.md](configuration-and-targets.md) | `src/core/defaults.ts`, `src/core/config.ts`, `src/domains/providers/**`, `src/cli/configure.ts`, `src/cli/targets.ts`, `src/cli/models.ts`, `src/cli/auth.ts` | TargetDescriptor, contextWindowProvenance (`configured`, `discovered`, `catalog`, `runtime-default`), settings.yaml, strict validation, saved defaults vs live routing. |
-| [safety-model.md](safety-model.md) | `src/domains/safety/**`, `src/tools/registry.ts`, `src/tools/policy.ts`, `src/tools/verify/**`, `src/entry/orchestrator.ts`, `src/domains/dispatch/write-boundary.ts` | Operating posture, `resolveEffectiveAutonomy` / `resolveBaselineAutonomy`, detect-and-rollback write boundaries, approval axes, damage control, typed validation. |
-| [prompt-envelope-and-tools.md](prompt-envelope-and-tools.md) | `src/domains/prompts/compiler.ts`, `src/interactive/chat-loop.ts`, `src/core/tool-names.ts`, `src/tools/registry.ts`, `src/tools/observation.ts`, `src/tools/agent-tools.ts` | Prompt envelope reuse, canonical tool delivery via single `agent-tools.ts` adapter, seven-plane tool surface, observation envelope, strict `ToolName` keying. |
-| [tool-usage.md](tool-usage.md) | `src/tools/agent-tools.ts`, `src/tools/registry.ts`, `src/tools/observation.ts` | In-depth reference for all 20 worker tools: parameters, typical payloads, `prepareArguments` normalizers, and error examples. |
-| [provider-adapter-cookbook.md](provider-adapter-cookbook.md) | `src/domains/providers/registry.ts`, `src/domains/providers/types/runtime-descriptor.ts` | RuntimeDescriptor, probe(), probeReasoning(), synthesizeModel(), thinking mechanisms. |
-| [alcf-provider.md](alcf-provider.md) | `src/domains/providers/runtimes/cloud/alcf.ts`, `src/engine/alcf-oauth.ts` | Globus PKCE OAuth, openAuthStorage(), Sophia vLLM, Metis API, chatTemplateKwargsUnsupported. |
-| [environment-variables.md](environment-variables.md) | `src/core/guardrails.ts`, `src/core/xdg.ts`, `src/domains/providers/knowledge-base-path.ts` | Comprehensive env var matrix: guardrail overrides, directory layout (CLIO_CODER_HOME), debug toggles, and internal plumbing. |
-| [built-in-agents.md](built-in-agents.md) | `src/domains/agents/**`, `src/domains/agents/builtins/*.md`, `src/domains/dispatch/**` | Builtin agent recipes, discovery roots, frontmatter schema, fleet contract shadowing (`.clio-coder/fleets/<name>.md`), active route automation. |
-| [fleet-dispatch.md](fleet-dispatch.md) | `src/domains/dispatch/**` | Multi-node SSH dispatch: process-safe admission, capacity leases, Contract v4 write boundaries (detect-and-rollback), bounded check/repair loops (`loop_bound_exhausted`), deterministic code steps, attestation, receipts v16. |
-| [capacity-and-scheduling.md](capacity-and-scheduling.md) | `src/domains/scheduling/**`, `src/domains/dispatch/capacity-lease.ts`, `src/domains/dispatch/reservation-store.ts` | Multi-process capacity leases (`dispatch-admission.json`), heartbeat TTLs, cross-process transaction locks (`dispatch-admission.json.lock`), and cluster drain controls. |
-| [worker-dispatch-mechanics.md](worker-dispatch-mechanics.md) | `src/worker/**` | NDJSON parent-child socket protocols, control/bulk lane demuxing, watchdog timers, worker attestation (13 protocol fields), permission parking, exit codes. |
-| [fleet-demo-runbook.md](fleet-demo-runbook.md) | `src/domains/dispatch/**` | Multi-node fleet demo: SSH setup, C++ build/repair workflow, reviewer gates, receipt verification v16. |
-| [session-lifecycle.md](session-lifecycle.md) | `src/engine/session.ts`, `src/domains/session/**` | Session lifecycle, on-disk ledger format v4 (`current.jsonl`), tree branching (`tree.json`), active-path lineage selection, `/fork`, `/resume`, checkpoints, and write-ahead protected-artifact journal. |
-| [acp.md](acp.md) | `src/engine/acp/**`, `src/cli/acp.ts` | Agent Client Protocol (ACP) server over stdio, tool mediation, non-stall permission handling, timeout bounds, and error taxonomy. |
-| [artifact-versions.md](artifact-versions.md) | `src/domains/dispatch/receipt-integrity.ts`, `src/engine/session.ts`, `src/worker/spec-contract.ts`, `src/domains/agents/fleet-contract.ts`, `src/domains/eval/schema/`, `src/domains/observability/trace-store.ts` | Version registry and migration policies for all 9 serialized artifact schemas across Clio Coder. |
-| [exit-codes-and-output.md](exit-codes-and-output.md) | `src/cli/**`, `src/entry/**` | Global process exit codes (0, 1, 2, 3), `--help` standard on stdout, machine-readable JSON streaming (`--json`, `--json-events`), and headless stdout deliverable contracts. |
-| [troubleshooting.md](troubleshooting.md) | `src/core/**`, `src/cli/**`, `src/domains/**` | Actionable error remediation and diagnostics keyed by exact user-facing messages. |
-| [glossary.md](glossary.md) | `src/domains/dispatch/types.ts`, `src/tools/**`, `src/domains/agents/**`, `src/core/**` | Canonical definitions of 45 core architectural concepts mapped to `src/` types. |
-| [documentation-coverage.md](documentation-coverage.md) | `src/**` | Complete source-to-documentation mapping matrix and subsystem coverage status. |
-| [tui-design.md](tui-design.md) | `src/interactive/theme/tokens.ts`, `src/interactive/theme/glyphs.ts` | TUI color system, glyph vocabulary (`contextReserve`), structural layouts, state choreography, code ink. |
-| [installation-and-lifecycle.md](installation-and-lifecycle.md) | `src/cli/paths.ts`, `src/cli/doctor.ts`, `src/cli/uninstall.ts`, `src/cli/removal.ts` | Installation, upgrade, reset, uninstallation, launcher ownership and what `--remove-binary` will and will not remove, partial-failure behavior, configuration folders (`credentials.yaml` `0o600`), and permissions. |
-| [release-cut-checklist.md](release-cut-checklist.md) | `scripts/check-release.mjs`, `tests/smoke/pack-install.test.ts`, `benchmarks/internal/`, `package.json` | Ordered release-cut steps with an explicit authorization boundary: everything external or irreversible is marked not run and needs an operator decision. |
-| [observability.md](observability.md) | `src/domains/observability/**`, `src/interactive/view/**`, `src/domains/dispatch/**`, `src/core/bus-events.ts` | `/view` artifact browsing, receipt verification, worker diagnostics, event routing, and cost snapshots. |
-| [evidence-and-memory.md](evidence-and-memory.md) | `src/domains/evidence/**`, `src/domains/memory/**`, `src/cli/evidence.ts`, `src/cli/memory.ts` | Evidence corpus layout, findings, memory lifecycle and prompt injection. |
-| [proactive-memory.md](proactive-memory.md) | `src/domains/memory/**` | Proactive task memory architecture, session task bank, intervention rules, and handoff carrying. |
-| [trace-store.md](trace-store.md) | `src/cli/trace.ts`, `src/domains/observability/trace-store.ts` | WAL SQLite trace mirror database schema, rowid cursor queries, rebuildability, 6 `clio-coder trace` subcommands (`runs`, `phases`, `tail`, `procs`, read-only `sql` SELECT, `ui`). |
-| [eval-runner.md](eval-runner.md) | `src/domains/eval/**`, `src/cli/eval.ts` | Local YAML eval tasks, dual token accountings (`tokens.*` wire vs `receiptUsage.*` journal), fail-closed null totals, EvalArtifactV4 format, `verify.measure` task outcome recording. |
-| [evals-internal.md](evals-internal.md) | `src/domains/eval/**` | Private context index determinism and target smoke matrices. External model benchmarks are documented under `benchmarks/`. |
-| [extensions-and-sharing.md](extensions-and-sharing.md) | `src/domains/extensions/**`, `src/domains/resources/**`, `src/domains/share/**`, `src/cli/extensions.ts`, `src/cli/share.ts` | Prompt and skill resources, extension manifests, portable share archives. |
-| [skills-marketplace.md](skills-marketplace.md) | `src/interactive/overlays/skills-hub.ts`, `src/domains/resources/skills/marketplace.ts` | Skills Hub marketplace discovery through the install resolver, empty state, install actions, publishing flow. |
-| [model-catalog.md](model-catalog.md) | `src/domains/providers/catalog.ts`, `src/domains/providers/models/**`, `src/domains/providers/probe/**`, `src/domains/providers/model-capabilities.ts` | Model catalog, live probes (`--offline` toggle), exact-id selector `probeCapabilitiesForModel`, field-note promotion. |
-| [middleware-and-components.md](middleware-and-components.md) | `src/domains/components/**`, `src/domains/middleware/**`, `src/cli/components.ts` | Active component snapshots, phase-aware middleware hook budgets (`DEFAULT_MIDDLEWARE_HOOK_BUDGETS_MS`). |
-| [scientific-validation.md](scientific-validation.md) | `src/domains/safety/rigor.ts`, `src/domains/safety/finish-contract.ts` | Advisory validation-contract patterns for scientific artifacts and HPC assumptions. |
-| [evolution.md](evolution.md) | `src/domains/evolution/**`, `src/cli/evolve.ts` | Falsifiable Change Manifest JSON templates, evidence-linked validation, and `clio-coder evolve`. |
-| [config-knobs-audit.md](config-knobs-audit.md) | `src/cli/config.ts` | Point-in-time inventory of legacy environment variables (Historical Appendix). |
-
----
-
-## Style conventions
-
-### Alpha framing
-
-Use direct, honest language:
-
-- "experimental community alpha"
-- "source-build path"
-- "current runtime is conservative/inert"
-- "advisory contract"
-- "planned/future milestone"
-
-Avoid phrases that imply managed production stability, full plugin maturity, or automatic scientific validation when the current code does not provide it.
-
-### Markdown structure
-
-- Prefer short sections with tables for command and schema references.
-- Use fenced examples that can be copied.
-- Keep links relative and repository-portable; do not use absolute `file:///home/...` links.
-- Mention source file paths in backticks instead of editor-specific absolute URLs.
-
-### GitHub alerts
-
-Use alerts sparingly:
-
-> [!NOTE]
-> Context or caveats that prevent misinterpretation.
-
-> [!WARNING]
-> Sharp edges, alpha limitations, or behavior that can surprise contributors.
-
-> [!CAUTION]
-> Safety, data loss, or security-sensitive constraints.
-
----
-
-## Blueprint Coverage & Format Strategy
-
-Clio Coder maintains two complementary documentation formats:
-
-1. **Markdown Documents (`docs/*.md`)**: The single canonical reference for coding agents, developers, and maintainers. They optimize for retrievability, exact enumerations, schema tables, typed TypeScript contracts, and source citations (`src/...:line`).
-2. **Interactive HTML Blueprints (`docs/html/*.html`)**: Visual reference cards and client-side simulators designed for human operators exploring dynamic behaviors (such as safety rule evaluation, token compaction calculation, YAML target validation, and prompt structure).
-
-### Blueprint Creation Policy
-
-Not every markdown document earns a standalone interactive HTML blueprint. Reference specifications—such as `artifact-versions.md`, `exit-codes-and-output.md`, `glossary.md`, `troubleshooting.md`, `session-lifecycle.md`, `acp.md`, `capacity-and-scheduling.md`, and `documentation-coverage.md`—are authoritative tabular contracts and state machine specifications. Building client-side JavaScript simulators for these documents would duplicate runtime validation logic and introduce synchronization hazards across releases. These pages are therefore linked directly from `docs/html/index.html` as Markdown Reference Specifications with explicit visual distinction from interactive simulator blueprints.
-
----
-
-## Update checklist
-
-When a feature changes:
-
-1. Identify the source owner (`src/cli`, `src/interactive`, `src/tools`, or a domain).
-2. Check whether public CLI help changed.
-3. Update the mapped guide in the same PR.
-4. If behavior affects safety, sessions, receipts, prompts, targets, or dispatch, update both README-level user docs and the deeper guide.
-5. Run a lightweight link check for changed Markdown.
-6. For release docs, verify version badges/sections match `package.json` and `CHANGELOG.md`.
-
-Suggested local link check:
-
-```bash
-python3 - <<'PY'
-import pathlib, re
-for md in list(pathlib.Path('docs').glob('*.md')) + [pathlib.Path('README.md')]:
-    text = md.read_text()
-    for m in re.finditer(r'\[[^\]]+\]\(([^)]+)\)', text):
-        link = m.group(1)
-        if link.startswith(('http://', 'https://', 'mailto:', '#')):
-            continue
-        target = link.split('#')[0]
-        if target and not (md.parent / target).exists():
-            line = text.count('\n', 0, m.start()) + 1
-            print(f'{md}:{line}: missing {link}')
-PY
-```
-
----
-
-## Community documentation priorities
-
-Clio users tend to be early adopters running real repositories, local models, and scientific/HPC code. Good docs should therefore prioritize:
-
-- reproducible first-run and target configuration;
-- local model/runtime field notes with exact versions and serving settings;
-- safety receipts and redaction guidance for issue reports;
-- small examples for project-local `CLIO-CODER.md`, `.clio-coder/safety.yaml`, prompts, skills, and agents;
-- clear labels for experimental surfaces such as middleware and scientific validation contracts.

package/docs/release-cut-checklist.md

@@ -1,193 +0,0 @@
-# v0.3.8 Release-Cut Checklist
-
-The ordered steps that turn the prepared `v0.3.8` branch into a published
-release. Everything above the line marked **AUTHORIZATION BOUNDARY** is
-repeatable and reversible and is run locally before the cut. Everything below
-it is external or irreversible and needs an explicit decision from the
-operator. This page is the procedure and the release report carries the live
-state of every step.
-
-## Status of the prepared tree
-
-| Item | State |
-| --- | --- |
-| Branch | After the release-cut evidence commit, `v0.3.8` is 30 commits ahead of `main`: the 29-commit candidate through `9b7b80cc` plus the final documentation and verification-evidence commit. The candidate includes the original implementation, the four release-test fixes (#233, #235, #238, #239), the WTF-P extension-resource merge, the `$ARGUMENTS` fidelity fix (#240), and the extension-agent resolution fix (#241). `origin/v0.3.8` remains at `af6546b2`, 17 commits behind the final local tip. |
-| `package.json` version | `0.3.8`; `package-lock.json` agrees at both version fields; the top changelog heading is `## 0.3.8 - 2026-08-29`. |
-| `main` | `598be99c`, the v0.3.7 release SHA; it is an ancestor of the final `v0.3.8` candidate and moves only at Part 4. |
-| `origin/main` | `598be99c`, matching local `main` and still an ancestor of the final candidate. |
-| Tags | `v0.3.7` exists on `598be99c`; no `v0.3.8` tag exists locally or remotely. The redundant `wtfp-safety` tag was deleted. The eight local `tmp-032-*` recovery tags remain and must never be pushed. |
-| GitHub Release | `v0.3.7` is published; no GitHub Release exists for `v0.3.8`. |
-| npm registry | `@iowarp/clio-coder@0.3.8` is absent; `latest` is `0.3.7`; the 0.3.8 dist-tag is undecided. |
-| npm history | Published versions are 0.3.0 through 0.3.4, 0.3.6, and 0.3.7. Version 0.3.5 was published and withdrawn and can never be reused. |
-| Milestone | `v0.3.8` has six open issues, all fixed on the branch: #233, #235, #238, #239, #240, and #241. They close from their `Fixes` trailers when the final candidate reaches `main`. |
-| Interactive release test | The original three-round report is `docs/release-notes/v0.3.8-release-test.md` (57 PASS / 8 FAIL / 3 PARTIAL / 6 OBSERVATION / 2 NOT RUN). The continuation is `docs/release-notes/v0.3.8-verification.md` (44 PASS / 6 non-blocking FAIL / 7 OBSERVATION / 1 NOT RUN), which closes the blocker, verifies the three later merges, and carries the final `CUT` verdict. |
-| Commit provenance identity | Still a post-release maintainer follow-up rather than a release gate; unchanged from 0.3.7. |
-
----
-
-## Part 1: verification (repeatable)
-
-Run against the exact final candidate with `NO_COLOR` unset and
-`TERM=xterm-256color`, so the color-sensitive tests see a real terminal.
-
-1. `npm run typecheck`
-2. `npm run lint` (Biome plus the hygiene checks, which include the boundary invariants and the skills pin check)
-3. `npm run skills:check`
-4. `npm run build`
-5. `npm run test`
-6. `npm run test:trace-viewer`
-7. `npm run ci` (runs 1 through 6)
-8. `npm run ci:release` (7 plus `scripts/check-release.mjs`: dist shebang
-   integrity, version coherence between `package.json` and the top
-   `CHANGELOG.md` heading, the deterministic 26-scenario behavioral machinery
-   corpus against its checked baseline, the forbidden-file list, the required
-   runtime resources, and the tarball and unpacked size budgets). A baseline
-   mismatch prints reviewable evidence and names prompt- or recipe-affected
-   corpus results. For an intentional change, inspect that diff, run
-   `node benchmarks/eval/check-behavioral-release.mjs --update` (with `TMPDIR` on a disk-backed path if `/tmp` is a small tmpfs),
-   review `benchmarks/eval/behavioral-machinery-baseline.json`, and commit it
-   with the change.
-9. Optional: step 8 again under Node 24. Hosted CI gates on Node 22 alone,
-   the `engines` floor; the weekly `flake-hunt` workflow carries Node 24.
-   Repeat locally only when the cut touches runtime-sensitive code.
-10. `npm run live:smoke -- --target <id>` for one real headless turn through
-    the built binary against a configured target, which is the one release
-    check a deterministic suite cannot give. The packaged-install lifecycle
-    (pack, install into a clean prefix, run the installed launcher) is
-    `tests/smoke/pack-install.test.ts` and already ran under step 5.
-11. `npm pack --dry-run`, then a real `npm pack` into a temporary directory.
-    Inspect the complete file list: `skills/`, `docs/*.md`, the builtin
-    agents, the model catalogs, and `damage-control-rules.yaml` are present;
-    `docs/html/`, `apps/workbench`, `.superpowers`, `tests/`, `scripts/`,
-    `benchmarks/`, scratch files, and source maps are absent. Record the
-    filename, packed and unpacked sizes, integrity, and shasum.
-12. Install that tarball into a clean temporary prefix with an empty
-    `CLIO_CODER_HOME` and verify `--version`, `--help`, an empty-state non-TTY
-    launch, `doctor`, and `uninstall --dry-run` without developer-local state.
-13. Before interactive release testing, run the model-required public
-    behavioral corpus manually against the release target and built CLI:
-    `node dist/cli/index.js eval run --suite benchmarks/eval/behavioral-model.yaml --target mini --clio-coder-entry dist/cli/index.js`
-    and
-    `node dist/cli/index.js eval run --suite benchmarks/eval/behavioral-model-negative-control.yaml --target mini --clio-coder-entry dist/cli/index.js`.
-    Retain both Artifact v4 files as release evidence. The positive corpus must
-    report its scenario and role rows without an undeclared envelope mismatch;
-    the negative control must still record violated exploration and safety
-    labels. These model-dependent runs are manual and are never required by
-    ordinary deterministic CI. Continue with interactive release testing,
-    which this cut added because the release is
-    almost entirely interactive surface: a tester agent drives the step-12
-    install through real TUI sessions in a throwaway repository, one session
-    per shipped feature, against local targets for the main session and a
-    cloud target for council members and advice, and writes a per-feature
-    PASS / FAIL / BLOCKED table with evidence. A FAIL on a deterministic
-    behavior (a refusal, a file, a receipt field, CLI output) blocks the cut;
-    a BLOCKED(model) on a model decision does not.
-
-## Part 2: version and notes (repeatable)
-
-14. Files carrying a version reference, to update together if the number
-    changes: `package.json` and `package-lock.json`, the `## 0.3.8 - <date>`
-    heading in `CHANGELOG.md`, the `(Version: 0.3.8)` markers in `docs/*.md`,
-    the `Blueprint (v0.3.8)` titles in `docs/html/*.html`, the `--branch`
-    pin in the README install block (the hygiene lint checks it), and the
-    measured-at figures in `scripts/check-release.mjs` if the package size
-    moved materially. For 0.3.7 the tarball measured 6.5 MB packed and
-    37.9 MB unpacked; re-measure for 0.3.8, inside the 10 MB and 50 MB ceilings set for 0.3.6.
-15. Confirm the `## 0.3.8` section of `CHANGELOG.md` describes every
-    user-visible behavior change under `### Added`, and every change to an
-    existing behavior under `### Changed`, and carries no Workbench release
-    narrative. The release workflow uses this section verbatim as the GitHub
-    Release body.
-16. `docs/artifact-versions.md` lists every persisted artifact this release
-    added or re-versioned. For 0.3.8 that is run receipt integrity v20, which
-    adds `pathProvenance` on dispatch intent and the resolved `pathScope`, and
-    whose entry must also record that a receipt below v20 is reported as
-    retired rather than invalid, and the durable assignment record, which now
-    carries its owner pid, process birth token, and acquisition time.
-17. Re-run `npm run ci:release` after any version edit and commit as one
-    commit on `v0.3.8`.
-
-## Part 3: present the gate
-
-18. Report to the operator before touching `main`: the exact final `v0.3.8`
-    SHA and clean status, the commits added since the handoff SHA, the gate
-    commands with pass/fail totals, the package version and changelog heading,
-    the tarball audit, the clean-install results, the interactive test table,
-    and any deferred live check, confirmation that no tag, GitHub Release, or
-    npm version exists yet, the proposed commands for Parts 4 through 6, and
-    the npm dist-tag. The dist-tag is the operator's call; for 0.3.7 the
-    operator chose `latest` on 2026-08-24; 0.3.8's dist-tag is undecided.
-
----
-
-## AUTHORIZATION BOUNDARY
-
-Every step below leaves the local checkout, is externally visible, or cannot be
-undone by a local `git` command. None of them runs without the operator
-confirming the exact SHA and the commands.
-
-## Part 4: fast-forward `main`
-
-19. `git fetch origin` immediately before integrating; require `origin/main`
-    to be an ancestor of the reviewed `v0.3.8` tip and confirm no other
-    worktree has `main` checked out.
-20. `git checkout main && git merge --ff-only v0.3.8`. No merge commit, no
-    rebase, no reset. Verify `main` equals the reviewed SHA and is clean.
-21. `git fetch origin` once more; stop on any unexpected remote movement. Then
-    `git push origin main`. Never `--force` or `--force-with-lease`. The push
-    closes the six milestone issues through their `Fixes` trailers.
-
-## Part 5: exact-SHA CI, tag, GitHub Release
-
-22. The `main` push triggers the `ci` workflow. Require that exact-SHA run to
-    finish green before tagging; `release.yml` then runs the same gate again on
-    the tagged tree itself. A red run blocks the cut: investigate it rather than
-    tagging around it, and never silence a flake with an unrelated change.
-23. Reconfirm that tag `v0.3.8` and the GitHub Release do not exist, then
-    `git tag -a v0.3.8 -m "Clio Coder 0.3.8"` on the green SHA and
-    `git push origin refs/tags/v0.3.8`.
-24. The tag push triggers `.github/workflows/release.yml`, which verifies the
-    tag matches `package.json`, runs `npm run ci:release` on the tagged tree,
-    extracts the `## 0.3.8` section of `CHANGELOG.md` as the release body, and
-    attaches the tarball. Do not create a release by hand. Verify the run's
-    SHA, the notes, the attached tarball, and the URL.
-
-## Part 6: npm publication (irreversible)
-
-25. `npm whoami` and confirm the registry and account; reconfirm
-    `@iowarp/clio-coder@0.3.8` is still absent.
-26. Obtain the operator's explicit dist-tag decision. `latest` makes this the
-    default install for every user; `--tag next` keeps `0.3.7` as the default.
-27. Run `npm publish` once. `prepublishOnly` re-runs `ci:release` as a safety
-    net; it is not a substitute for Part 1.
-28. A published version cannot be replaced. `npm unpublish` is restricted and
-    time-limited; a mistake is corrected by publishing a higher version.
-
-## Part 7: post-publish verification and follow-ups
-
-29. `npm view @iowarp/clio-coder@0.3.8` and the selected dist-tag.
-30. On a clean machine, `npm install -g @iowarp/clio-coder` from the registry
-    rather than from a local tarball, then repeat step 12 against it, plus
-    `configure` to a real target and one real turn when one is authorized.
-    This is the only step that tests what users actually receive.
-31. From an installation of 0.3.7, verify `clio-coder upgrade` finds and
-    applies 0.3.8.
-32. Record the SHA, CI URL, tag, GitHub Release URL, npm version and dist-tag,
-    tarball evidence, and the post-publish verification in the release report.
-33. Maintainer follow-up, independent of the release: verify the commit
-    provenance email `clio-coder@iowarp.ai` on IOWarp-controlled GitHub and
-    GitLab identities such as `clio-coder-bot` or `iowarp-clio`, and upload
-    `assets/clio-coder-avatar-512.png` as the account avatar where PNG is
-    required. Commit data itself cannot carry a logo, so this affects only how
-    those platforms render the trailers, never whether attributed commits or
-    the release work. Clio never creates accounts or performs remote
-    operations for this.
-
----
-
-## Rollback
-
-There is no rollback for step 27. Before it, every step is reversible: steps
-23 and 24 by deleting the local and remote tag and the draft release, steps 19
-through 21 by a new forward commit on `main` (never by rewriting it), and
-everything in Parts 1 and 2 by `git checkout`.

package/docs/time-conventions.md

@@ -1,101 +0,0 @@
-# Time and Clock Conventions
-
-This document defines the canonical time and clock conventions for `clio-coder`. These policies establish consistent rules for measuring durations, recording instants, converting timezones, and managing concurrency across the codebase.
-
-This policy is promoted from Section 10 of the repository time audit conducted on 2026-08-15.
-
----
-
-## 1. Which Clock for What Purpose
-
-### Monotonic clocks for durations
-
-All durations must be measured using `performance.now()` without exception. This rule applies to latency measurements, elapsed run times, time-to-first-token (TTFT), execution budgets, timeouts, stall watchdogs, retry backoff intervals, and rendering metrics.
-
-Whenever a value answers the question "how long did this take" or "how long until", it must originate from the monotonic clock. Monotonic clocks are unaffected by Network Time Protocol (NTP) adjustments, system suspend or resume events, and Daylight Saving Time (DST) transitions.
-
-### Wall clocks for anchored instants
-
-Wall clock reads via `Date.now()` or `new Date()` are reserved exclusively for anchoring instants that a human operator or an external machine will inspect. These include timestamps such as `startedAt`, `endedAt`, `createdAt`, and `expiresAt`. Wall clocks must never be used to measure durations or elapsed intervals.
-
-### Combined anchor and span pattern
-
-When both an anchor instant and a duration are required, code must follow the pattern established in `src/domains/dispatch/code-step.ts:291-306`:
-
-```ts
-const startedAtMs = Date.now();                      // wall anchor, for the record
-const clock = process.hrtime.bigint();               // monotonic span
-const startedAt = new Date(startedAtMs).toISOString();
-// ... operation executes ...
-const durationMs = Number((process.hrtime.bigint() - clock) / 1_000_000n);
-const endedAt = new Date(startedAtMs + durationMs).toISOString();
-```
-
-The wall clock anchors the starting instant for human correlation. The monotonic clock measures the elapsed span. The ending timestamp `endedAt` is derived by adding the monotonic span to the initial wall anchor. This derivation guarantees that `endedAt - startedAt === durationMs` remains true regardless of any wall-clock adjustments that occur during execution.
-
-### Injectable clock seams
-
-Every module that reads a clock must accept an optional injectable clock interface in its configuration or options, defaulting to the system clock. Injectable clock seams allow test suites to run deterministically without relying on real-time passage or introducing timing races.
-
-### Cross-host timestamp boundaries
-
-A timestamp produced on one host must never be compared directly against a clock read on another host. Systems must receive-stamp incoming events upon arrival on the local host, maintain an explicit clock offset, or order events using sequence numbers rather than timestamps. Code must never subtract timestamps across host boundaries.
-
-### Sequence numbers over timestamps for ordering
-
-When ordering operations under concurrency, code must prefer monotonic sequence numbers over timestamps. Components such as the agent ledger (`src/domains/session/agent-ledger-store.ts`) and the execution scheduler (`src/domains/dispatch/execution-scheduler.ts`) rely on sequence numbers to remain correct by construction. Timestamps are reserved for human display and coarse windowing. Any attribution logic that relies on timestamps must report ambiguity explicitly rather than returning null.
-
----
-
-## 2. Where UTC Is Converted
-
-### Storage, transport, and comparisons in UTC
-
-The system stores UTC, transports UTC, and compares UTC. Conversion to local time occurs once, strictly at the render call site.
-
-1. On disk and across the wire, timestamps are always represented as canonical ISO-8601 strings produced by `toISOString()`. Every store validates timestamps upon reading using the exact round-trip check from `src/domains/dispatch/capacity-lease.ts:80-84`.
-2. In memory, instants are stored as epoch milliseconds or canonical ISO-8601 strings. Localized or pre-formatted date strings must not be held in memory models.
-3. At the user interface render boundary, UTC instants are converted to the operator's local timezone.
-4. Whenever a converted local timestamp is displayed, the underlying canonical UTC instant must remain accessible. For example, a table row displays local time while the associated detail pane preserves the exact ISO-8601 string so that the two representations can always be reconciled.
-
----
-
-## 3. Formatter Policy
-
-All operator-facing time formatting is consolidated in `src/interactive/format-time.ts`. The module provides three standardized formatting functions:
-
-| Function | Output Format | Timezone and Locale Frame | Purpose |
-|---|---|---|---|
-| `clockLocal(instant)` | `HH:MM:SS` | Operator local timezone using `en-GB` locale with 24-hour cycle (`hourCycle: "h23"`) | Renders time-of-day for logs, tree selectors, and message pickers |
-| `dateLocal(instant)` | `YYYY-MM-DD` | Operator local timezone using `en-CA` locale | Renders calendar dates for session selectors, welcome dashboards, and export filenames |
-| `relative(instant, now)` | `"3m ago"` (falls back to `dateLocal`) | Operator local timezone | Renders relative recency ladders with automatic fallback to calendar dates |
-
-Both `Intl.DateTimeFormat` instances are constructed at module scope. The module automatically rebuilds formatters if `process.env.TZ` changes during runtime.
-
-Machine surfaces such as filenames, IDs, structured log fields, and receipt records bypass the formatting module entirely and use canonical `toISOString()`.
-
----
-
-## 4. Test Determinism and Receipt Integrity
-
-### Test clock harness
-
-Test suites must rely on the steppable clock helper in `tests/harness/clock.ts`. Every factory function that reads a clock must default to the harness clock in test environments. Real-time passage in tests is opt-in and requires explicit configuration.
-
-### Receipt integrity digests
-
-Persisted fields such as `startedAt` and `endedAt` participate in receipt integrity digests (`src/domains/dispatch/receipt-integrity.ts`). Any timestamp normalization, derivation, or adjustment must occur before the receipt digest is sealed. Timestamps must never be rewritten after receipt creation.
-
----
-
-## 5. State-Root and Audit-Filename Assumptions
-
-### Host-scoped state root and coordination
-
-The state root directory is host-scoped. Durable locks and capacity leases carry a metadata payload containing `{host, pid, birthToken}`.
-
-A coordination record created by a foreign host is never adjudicated against the local process table. This follows the host-scoping pattern implemented in `src/tools/compete-worktrees.ts:207-215`, `src/domains/dispatch/orphan-recovery.ts:140-149`, and `src/core/run-identity.ts:23`.
-
-### Audit filename semantics
-
-The date in an audit log filename (such as `audit-YYYY-MM-DD.jsonl`) is a human-facing label indicating the local calendar date on which the audit log was opened. It does not represent machine-read data. All individual audit event records contained within the file store canonical UTC ISO-8601 timestamps.

package/skills/meta/clio-test/SKILL.md

@@ -1,133 +0,0 @@
----
-name: clio-test
-description: Use when writing or modifying Clio Coder's own source under src/, or verifying a change end-to-end against the real test harness. Covers the three real layers (contracts / smoke / boundaries), choosing which to run for a given change, the mock-provider and ACP-over-stdio harness, and the hot-reload dev loop for picking up latest code. Activate on any src/ edit, before declaring a change verified, or when asked whether Clio still works.
-version: 0.1.4
-license: Apache-2.0
-clio:
-  registry-id: iowarp/clio-coder
-  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/meta/clio-test
-  audit: pass
-  provenance: designed
-  eval-status: scenarios-recorded
-  model-size: any
----
-
-# Clio Test
-
-Clio's test suite has exactly three layers: **contracts**, **smoke**, and
-**boundaries**.
-
-For the question of whether a change may leave your machine (commit, push, PR),
-that is `clio-dev`, not this skill. **REQUIRED SUB-SKILL:** `clio-dev` for the
-local-vs-contribute boundary.
-
-## Commands
-
-```bash
-npm run typecheck         # tsc -p tsconfig.tests.json (includes tests/ and benchmarks/internal/)
-npm run lint              # biome check . && scripts/check-hygiene.ts (import boundaries, skill pins, doc drift)
-npm run test:file -- 'tests/contracts/**/*.test.ts'  # contract tests (tsx, import src directly, no build)
-npm run test:file -- 'tests/smoke/**/*.test.ts'      # spawn dist/cli/index.js end-to-end (NEEDS a build)
-npm run test              # contracts + smoke, sharded across processes (the full gate)
-npm run build             # tsup -> dist/
-npm run dev               # tsup --watch -> rebuilds dist/ on save
-npm run ci                # typecheck && lint && skills:check && build && test && test:trace-viewer
-npm run live:smoke -- --target <id>   # one real turn against a configured target; never in CI
-```
-
-## Which layer catches what
-
-| Change site | Run first | Why |
-|---|---|---|
-| pure logic in `src/domains/<x>/*.ts` | `npm run test:file -- 'tests/contracts/**/*.test.ts'` | contract tests import `src` via tsx; no build |
-| dispatch / providers / prompts / safety / config / persistence / acp behavior | `npm run test:file -- 'tests/contracts/**/*.test.ts'` | each has a file in `tests/contracts/` |
-| skills loader / activation | `npm run test:file -- 'tests/contracts/**/*.test.ts'` | `tests/contracts/skills.test.ts`, `skill-activation-compaction.test.ts` |
-| any `src/` import edit | `npm run lint` | the hygiene check enforces rule1/2/3 |
-| `src/cli/*` or `src/entry/*` user-facing flow | build, then `npm run test:file -- 'tests/smoke/**/*.test.ts'` | smoke spawns the real `dist/cli/index.js` |
-| ACP surface (`src/cli/acp.ts`, engine ACP) | build, then `npm run test:file -- 'tests/smoke/**/*.test.ts'` | smoke drives `clio-coder acp` over JSON-RPC/stdio |
-
-**See `references/test-map.md`** for exactly where each test lives and how to run
-a single file.
-
-## Boundary rules you must not break
-
-`tests/boundaries/check-boundaries.ts` enforces three rules (also the Hard
-Invariants in `CLIO-CODER.md`), run by `scripts/check-hygiene.ts` under
-`npm run lint`. If it reports a violation, fix the import — never silence the
-check:
-
-- **rule1**: only `src/engine/**` may value-import `@earendil-works/pi-*`. Outside
-  engine, use Clio contracts or type-only imports that erase at compile time.
-- **rule2**: `src/worker/**` never imports `src/domains/**`. Cross through
-  `src/worker/spec-contract.ts`.
-- **rule3**: `src/domains/<x>/**` never imports `src/domains/<y>/extension.ts`.
-  Go through the target domain's `index.ts` contract.
-
-## The hot-reload dev loop (picking up latest code)
-
-There are two independent reload mechanisms; know which applies.
-
-**Source reload for tests.** This is the "pick up latest code" loop:
-
-- **Fast loop — no build.** The contracts glob runs `node --import tsx --test`
-  and imports `src/**` directly, and the hygiene lint reads source statically,
-  so both always see the latest source with zero build step. Iterate here whenever the change is pure
-  logic or a contract.
-- **Full loop — needs `dist/`.** The smoke glob spawns `dist/cli/index.js`, so it
-  only sees code that has been built. Keep `npm run dev` (`tsup --watch`) running
-  in another pane; it rebuilds `dist/` on every save, so the smoke lane
-  picks up your latest source without a manual `npm run build`.
-
-**Config reload for a running session.** Clio classifies a settings change
-(`src/domains/config/classify.ts`) into three buckets:
-
-- `hotReload` (theme, keybindings, `safetyLevel`, `defaultMode`) — applies live
-  via the `config.hotReload` bus, no restart.
-- `nextTurn` (model, thinking level, budget, skills, compaction…) — applies
-  before the next turn.
-- `restartRequired` (credentials, runtime enable/disable, `budget.concurrency`)
-  — needs a process restart. Unknown fields fail closed to this bucket.
-
-**There is no in-process reload of Clio's own code in a running session.** ESM
-modules load once; to run changed harness code in an interactive session,
-restart the process (against a freshly built `dist/`).
-
-## Iteration loop
-
-1. Write the change.
-2. `npm run typecheck` and `npm run lint`.
-3. Run the narrowest layer from the table above.
-4. `npm run lint` if you touched imports.
-5. If you touched CLI/entry/ACP: `npm run build` (or rely on `dev` watch), then
-   `npm run test:file -- 'tests/smoke/**/*.test.ts'`.
-6. `npm run ci` before calling it done. Report exactly what ran and what is
-   unverified.
-
-When debugging a single test:
-
-```bash
-node --import tsx --test tests/contracts/<file>.test.ts   # one file
-node --import tsx --test --test-only tests/contracts/<file>.test.ts  # it.only
-```
-
-## What NOT to do
-
-- Don't reintroduce `tests/unit|integration|e2e/`; that taxonomy was
-  deliberately removed. Don't add a second pseudo-terminal: `tests/harness/pty.ts`
-  is the one PTY, used by the three `*-pty`/`tui-width-matrix` smoke suites and
-  by `benchmarks/internal/pty-drive.ts`.
-- Don't add `scripts/diag-*.ts` or `scripts/verify-*.ts`. A test belongs in
-  `tests/`; a one-off probe belongs in `/tmp` and gets deleted (see
-  `references/harness.md`).
-- Don't silence a boundary violation with `// biome-ignore` or an exclude. Fix
-  the import.
-- Don't assert against a simulated TUI. Test real commands via the spawn harness.
-- Don't commit with red tests. If a pre-existing test fails on state that
-  predates your change, report it and ask — don't delete or skip it.
-
-## Harness reference
-
-Driving the real CLI, the mock provider, ACP over stdio, and the PTY, plus the
-throwaway probe pattern: **see `references/harness.md`**. Driving the real
-binary against a real model (headless, PTY, tmux, herdr) is a different claim
-and lives in `benchmarks/internal/SKILL.md`.