@iowarp/clio-coder 0.4.7 → 0.4.9

package/docs/process/documentation-guide.md

@@ -1,8 +1,5 @@
 # Documentation Standards and Codebase Alignment
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Documentation Standards and Codebase Alignment visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/documentation_blueprint.html).
-
 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.
 
 ---
@@ -33,7 +30,7 @@ Classify claims clearly:
 | --- | --- | --- |
 | [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. |
-| [documentation-guide.md](documentation-guide.md) | `docs/**`, `src/**`, `tests/**` | Documentation structure, source ownership, writing rules, and blueprint policy. |
+| [documentation-guide.md](documentation-guide.md) | `docs/**`, `src/**`, `tests/**` | Documentation structure, source ownership, writing rules, and rendering policy. |
 | [commands-and-modes.md](../guide/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](../architecture/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](../architecture/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. |
@@ -72,7 +69,7 @@ Classify claims clearly:
 | [development-pipeline.md](development-pipeline.md) | `library/skills/git/**`, `.github/**`, `scripts/check-release.mjs`, `package.json` | Issue-to-PR development lifecycle, validation, release inheritance, and the human merge boundary. |
 | [git-commit-provenance.md](git-commit-provenance.md) | `src/core/commit-attribution.ts`, `src/core/git-commit-attribution.ts`, `src/domains/dispatch/fleet-commit-attribution.ts` | Evidence-aware commit roles, trailers, managed hook chaining, and receipt v20 attribution. |
 | [observability.md](../architecture/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. |
-| [performance-methodology.md](performance-methodology.md) | `src/interactive/render-trace.ts`, `src/interactive/**`, `tests/contracts/rendering-invariants.test.ts`, `tests/smoke/real-binary-boot.test.ts` | Reproducible terminal and model-path performance endpoints, trace interpretation, measurement controls, and reporting rules. |
+| [performance-methodology.md](performance-methodology.md) | `src/interactive/render-trace.ts`, `src/interactive/**`, `tests/extended/rendering-invariants.test.ts`, `tests/smoke/real-binary-boot.test.ts` | Reproducible terminal and model-path performance endpoints, trace interpretation, measurement controls, and reporting rules. |
 | [evidence-and-memory.md](../architecture/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](../guide/proactive-memory.md) | `src/domains/memory/**` | Proactive task memory architecture, session task bank, intervention rules, and handoff carrying. |
 | [trace-store.md](../architecture/trace-store.md) | `src/cli/trace.ts`, `src/domains/observability/trace-store.ts` | WAL SQLite trace mirror database schema, rowid cursor queries, rebuildability, and nine `clio-coder trace` subcommands: `runs`, `phases`, `tail`, `procs`, `code-steps`, `inspect`, `prune`, read-only `sql`, and `ui`. |
@@ -88,6 +85,7 @@ Classify claims clearly:
 | [interop.md](../guide/interop.md) | `src/cli/interop.ts`, `src/domains/interop/**`, `src/interactive/overlays/interop.ts` | External coding agent interoperability: host discovery, resource inspection, safe adoption of prompts and skills into the library. |
 | [model-catalog.md](../architecture/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](../architecture/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`). |
+| [tool-audit-v0.4.9.md](tool-audit-v0.4.9.md) | `src/tools/**`, `src/core/safe-exec.ts`, `src/domains/gateway/mcp/**` | Individual tool purpose, placement, contracts, implementation bounds, scientific integrity, and landed disposition. |
 | [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](../history/config-knobs-audit.md) | `src/cli/config.ts` | Point-in-time inventory of legacy environment variables (Historical Appendix). |
@@ -130,25 +128,21 @@ Use alerts sparingly:
 
 ---
 
-## Blueprint coverage and format strategy
-
-Clio Coder maintains two complementary documentation formats:
+## One source, generated presentation
 
-1. **Markdown documents (`docs/guide/**/*.md`, `docs/architecture/**/*.md`, `docs/process/**/*.md`, and `docs/history/**/*.md`)**: The canonical reference for coding agents, developers, and maintainers, with `docs/README.md` as the hub. They optimize for retrievability, exact enumerations, schema tables, typed TypeScript contracts, and source citations (`src/...:line`).
-2. **HTML blueprints (`docs/html/*_blueprint.html`)**: One visual counterpart per Markdown page for human readers. Each blueprint carries the complete canonical prose plus navigation and copy affordances, and declares its source in `meta[name="clio-markdown-source"]`.
+The Markdown tree is the canonical reference for people and agents. The web
+application generates the reading view, navigation, search index and heading
+outline from those same files. It supplies the theme, code-copy controls and
+safe diagram rendering. Do not author or regenerate parallel HTML documents.
 
-### Blueprint Creation Policy
+Keep `docs/README.md` organized around reader goals. Its linked tables define
+the navigation groups; all discovered Markdown pages also appear in the full
+inventory. Use descriptive headings and relative links so the renderer can
+create stable anchors and keep navigation inside the application.
 
-Blueprint coverage is explicit rather than inferred from document style. The
-page-level audit lives in
-[`documentation-coverage.md`](documentation-coverage.md). Every canonical Markdown page
-has a dedicated blueprint. Recheck the complete inventory during each release cut. `docs/html/index.html` groups those counterparts by
-the same Guide, Architecture, Process, and History tree, while a source meta tag
-provides the one-to-one machine-readable mapping. Every mapping must remain
-unique, complete, and free of orphaned Markdown or HTML pages.
-`pnpm run lint` rejects any absent named blueprint, enforces that mapping, and
-compares every extractable `clio-coder <command>` string and `CLIO_CODER_*`
-name in each counterpart.
+`pnpm run lint` checks source-corpus coverage and rejects links to retired HTML.
+The web documentation tests walk every page, verify its rendered heading targets
+and internal links, and check that unsafe content cannot become executable HTML.
 
 ---
 
@@ -162,7 +156,7 @@ When a feature changes:
 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`.
-7. Run `pnpm run lint` to verify Markdown and HTML blueprint parity.
+7. Run `pnpm run lint` and the web documentation tests to verify corpus coverage, links and rendering.
 
 Suggested local link check:
 

package/docs/process/eval-runner.md

@@ -1,8 +1,5 @@
 # Clio Coder Local Evaluation Runner
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Clio Coder Local Evaluation Runner visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/eval_blueprint.html).
-
 The local evaluation runner executes repository-local YAML task suites as deterministic subprocess checks. It is useful for comparing harness changes, prompts, tools, or local workflows.
 
 Source of truth: [src/domains/eval/](../../src/domains/eval/) and [src/cli/eval.ts](../../src/cli/eval.ts).

package/docs/process/evals-internal.md

@@ -1,8 +1,5 @@
 # Internal Eval Suites
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Internal Eval Suites visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/evals_internal_blueprint.html).
-
 Private suites should live outside this repository. Keep datasets, prompts,
 live fleet coordinates, calibration outputs, and raw run artifacts in a private
 checkout or object store.

package/docs/process/evolution.md

@@ -1,8 +1,5 @@
 # Evolution and Change Manifests
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Evolution and Change Manifests visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/evolution_blueprint.html).
-
 Clio Coder uses change manifests to make harness changes reviewable, falsifiable, and rollback-friendly. CLIO stands for Context Layer for Input/Output, named for the Greek muse of history. A manifest is JSON, generated or checked with `clio-coder evolve manifest`, and should describe what changed, why, what evidence supports it, what could regress, how to validate it, and how to roll it back.
 
 Source of truth: `src/domains/evolution/manifest.ts`, `src/domains/evolution/validate.ts`, and `src/cli/evolve.ts`.

package/docs/process/fleet-demo-runbook.md

@@ -1,8 +1,5 @@
 # Fleet Demo Runbook
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Fleet Demo Runbook visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/fleet_demo_blueprint.html).
-
 A repeatable multi-node demonstration: one orchestrator drives a real
 CMake/C++ fix through a reviewer-gated dispatch across SSH nodes, and every
 worker's receipt (including the remote ones) verifies afterward. The steps
@@ -54,12 +51,12 @@ clio-coder doctor
 
 Doctor probes each node over its real SSH channel: reachability, a
 version-matched `clio-coder` on the remote path, path parity for the project root,
-and a writable remote state dir. Those rows are read-only diagnostics: the
-current command does not create or refresh `fleet-preflight.json`, so it does
-not make a passing node dispatch-eligible. Placement can still consume an
-existing preflight record, but admission fails closed when that record is
-missing or stale after a host, project, or version change. There is currently
-no mutating doctor command that refreshes it.
+and a writable remote state dir. Those rows are read-only diagnostics: plain
+`clio-coder doctor` does not create or refresh `fleet-preflight.json`. Run
+`clio-coder doctor --fix` to record passing preflight results into
+`fleet-preflight.json` and make verified nodes dispatch-eligible. Placement can
+still consume an existing preflight record, but admission fails closed when that
+record is missing or stale after a host, project, or version change.
 
 Confirm the durable view:
 

package/docs/process/git-commit-provenance.md

@@ -1,8 +1,5 @@
 # Git Commit Provenance
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Git Commit Provenance visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/git_commit_provenance_blueprint.html).
-
 Clio Coder adds evidence-aware role trailers to commits created through Clio.
 The feature is enabled by default:
 

package/docs/process/performance-methodology.md

@@ -1,8 +1,5 @@
 # Performance Measurement Methodology
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Performance Measurement Methodology visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/performance_methodology_blueprint.html).
-
 Clio Coder treats performance observations as diagnostic evidence, not as a
 reason to weaken behavior. Event ordering, persistence, permissions, terminal
 restoration, accessibility, output contracts, and installed-package behavior
@@ -75,7 +72,7 @@ The measurement snapshot below was originally backed by
 suite. Their names remain in the dated command transcripts below only to make
 the recorded method auditable; the commands are not current invocations.
 Current correctness coverage lives in
-`tests/contracts/rendering-invariants.test.ts`, and
+`tests/extended/rendering-invariants.test.ts`, and
 `tests/smoke/real-binary-boot.test.ts` exercises the built binary. Neither is a
 replacement glass-latency benchmark. `CLIO_CODER_RENDER_TRACE` remains the
 supported way to capture a live render trace for a fresh measurement campaign.

package/docs/process/release-cut-checklist.md

@@ -1,223 +1,116 @@
 # Release-Cut Checklist
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Release-Cut Checklist visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/release_checklist_blueprint.html).
-
-This document provides the standard procedure for cutting a release of Clio Coder.
-Releases are cut from an annotated tag on canonical main. The GitHub release is
-produced by GitHub Actions, while package publication to npm is an authorized manual
-step performed by a maintainer. Everything before the authorization boundary is local,
-repeatable, and reversible. Every step following the authorization boundary affects
-canonical remote state or publishes immutable packages.
-
-## Part 1: Candidate Preparation on a Local Compact Branch
-
-Maintainers prepare release candidates on a local-only compact branch named after
-the version without punctuation, such as `v046` for version `0.4.6`. Dotted branch
-names like `v0.4.6` are forbidden because dotted names belong exclusively to immutable
-tags. The canonical repository hosts only `main`, and no release candidate branch is
-ever pushed to canonical origin.
-
-1. Ensure the working tree is clean and updated from canonical origin:
-
-   ```bash
-   git checkout -b v046 origin/main
-   ```
-
-2. Update `version` in `package.json` and `assets/acp-registry/agent.json` to the
-   release version. Update the README's source-install tag and remove any
-   development-only notices. Keep historical release records, protocol schema
-   versions, dependency versions, and migration fixtures unchanged.
-
-3. Retitle the active changelog section in `CHANGELOG.md` from `## Unreleased` to
-   `## <version> - YYYY-MM-DD`. The release gate in `scripts/check-release.mjs` requires
-   the first version header to match the version in `package.json`.
-
-4. Commit the release candidate preparation locally:
-
-   ```bash
-   git commit -am "chore(release): prepare <version>"
-   ```
-
-## Part 2: Local Candidate Verification Gate
-
-Run deterministic local checks on the candidate commit before requesting authorization.
-
-1. Execute the release gate:
-
-   ```bash
-   pnpm run ci:release
-   ```
-
-   This gate runs `pnpm run ci` followed by `node scripts/check-release.mjs`. It verifies
-   type checking, Biome formatting, hygiene rules, architecture boundary invariants,
-   the build, the contract and smoke test suites, trace-viewer tests, and dist integrity.
-   The packaging audit checks executable entry shebangs, ensures forbidden files like
-   source maps and caches are omitted, verifies runtime resources from `scripts/release-manifest.json`,
-   and enforces size limits (10 MB packed, 50 MB unpacked).
-
-2. Optionally validate a live model turn against a configured target:
-
-   ```bash
-   node dist/cli/index.js run --target <id> --autonomy read-only "Reply with exactly: CLIO_LIVE_OK"
-   ```
-
-3. Run the real-home smoke test against the operator configuration:
-
-   ```bash
-   pnpm run smoke:real-home --target <id> --strict
-   ```
-
-   This runs `scripts/smoke-real-home.sh` using a copy of operator settings in a scratch
-   `CLIO_CODER_HOME`. The `--strict` flag ensures any failing rows from `clio-coder doctor`
-   fail the smoke run.
-
-4. Inspect the npm package contents with a dry run:
-
-   ```bash
-   npm pack --dry-run
-   ```
-
-   Confirm the complete `library/` tree and `.claude-plugin/marketplace.json`
-   accompany `dist/`, `src/`, and the documented runtime resources. The repository's
-   `.agents/skills/` symlinks are clone conveniences and are not tarball contents.
-
-5. Validate an installed tarball in a clean temporary directory:
-
-   Create a temporary directory, pack the tarball, install it via npm, and verify
-   installed binary lifecycle commands in an isolated environment with an empty `CLIO_CODER_HOME`:
-
-   ```bash
-   clio-coder --version
-   clio-coder --help
-   clio-coder doctor
-   clio-coder uninstall --dry-run
-   ```
-
-## Part 3: Candidate Review and Authorization Boundary
-
-Before touching any remote ref, summarize the candidate for maintainer review:
-- Candidate commit SHA
-- Results of `pnpm run ci:release`
-- Verification output from real-home smoke and installed package testing
-- Changelog contents and target npm version
-
-Every step below changes canonical remote refs, creates a release, or publishes
-an immutable package. Do not execute any of them without explicit maintainer authorization.
-
-## Part 4: Fast-forward Canonical Main
-
-1. Fetch the latest remote status from origin:
-
-   ```bash
-   git fetch origin
-   ```
-
-2. Confirm `origin/main` is an ancestor of the local candidate branch.
-
-3. Fast-forward local `main` to the candidate commit:
-
-   ```bash
-   git checkout main
-   git merge --ff-only v046
-   ```
-
-4. Verify that local `main` matches the reviewed candidate SHA exactly.
-
-5. Push `main` to canonical origin:
-
-   ```bash
-   git push origin refs/heads/main:refs/heads/main
-   ```
-
-   No release branch is ever pushed to origin.
-
-## Part 5: Tagging and GitHub Release
-
-1. Wait for GitHub Actions CI on canonical `main` to finish green for the pushed SHA.
-
-2. Create an annotated git tag matching the version:
-
-   ```bash
-   git tag -a v<version> -m "Clio Coder <version>"
-   ```
-
-3. Push only the release tag to canonical origin:
-
-   ```bash
-   git push origin refs/tags/v<version>
-   ```
-
-4. Pushing the tag triggers `.github/workflows/release.yml`. The workflow:
-   - Verifies the tag matches `package.json`.
-   - Runs `pnpm run ci:release` on the tagged commit.
-   - Packs the release tarball with `npm pack`.
-   - Extracts the version changelog section from `CHANGELOG.md`.
-   - Creates the GitHub Release with the tarball attached using `gh release create`.
-
-5. Inspect the GitHub Actions workflow run and confirm the GitHub release is published.
-
-6. Reconcile the release milestone against the tagged commits and each ticket's
-   acceptance evidence. `Fixes #123` or `Resolves #123` in a commit closes that
-   ticket when the commit reaches default-branch `main`; a bare `#123`, changelog
-   mention, tag, or GitHub release does not. Verify the resulting issue state.
-   Explicitly close completed tickets missed by automatic closure and retain
-   their implementing commit and validation references. Carry incomplete work
-   forward with its remaining criteria, then close the reconciled milestone.
-   Never infer completion from a release-note mention alone.
-
-## Part 6: Package Publication to npm
-
-Publishing to npm is a manual maintainer step performed from the tagged commit.
-
-1. Confirm authentication and registry status:
-
-   ```bash
-   npm whoami
-   ```
-
-2. Confirm the version does not already exist on npm:
-
-   ```bash
-   npm view @iowarp/clio-coder@<version>
-   ```
-
-3. Publish the package from the tagged checkout:
-
-   ```bash
-   npm publish
-   ```
-
-   The `prepublishOnly` lifecycle script sets `CLIO_CODER_RELEASE_CONTEXT=publish` and
-   re-executes `pnpm run ci:release` as a mandatory release-mode verification gate before
-   files are uploaded. When publishing a pre-release channel, append `--tag <channel>`.
-
-## Part 7: Post-Publish Verification and Branch Closeout
-
-1. Verify package availability on npm:
-
-   ```bash
-   npm view @iowarp/clio-coder version
-   ```
-
-2. On a clean machine, install the package globally and run basic lifecycle checks:
-
-   ```bash
-   npm install -g @iowarp/clio-coder@<version>
-   clio-coder --version
-   clio-coder doctor
-   ```
-
-3. Remove the local compact candidate branch:
-
-   ```bash
-   git branch -d v046
-   ```
-
-   The canonical repository remains in its steady state containing only `main` and immutable tags.
-
-## Part 8: Rollback and Error Recovery
-
-npm package publication is irreversible. A published version cannot be removed or overwritten.
-Any issue discovered after publication must be resolved through a subsequent release. Prior
-to pushing git tags or publishing to npm, local candidate commits can be amended or reset freely.
+Qualify one committed candidate and its exact npm tarball. Publication uses a fast
+preflight of that evidence. Development investigations are separate and are never
+implicitly repeated by a publish lifecycle hook.
+
+## Prepare locally
+
+1. Inspect `git status --short --branch`. Preserve operator work. Use one local
+   candidate branch; do not push main, candidate branches, or tags without authorization.
+2. Set the approved version in `package.json` and `assets/acp-registry/agent.json`,
+   date the matching top changelog section, and align the README install tag.
+3. Commit all candidate changes. Qualification refuses tracked or untracked source
+   changes. Ignored operator files are not candidate inputs; ignored `dist/` bytes
+   are verified through the actual npm package.
+4. Install once with `pnpm install --frozen-lockfile`. Record cold installation time
+   separately when comparing hosted gate times.
+
+## Qualify the candidate
+
+```bash
+pnpm run ci:release
+```
+
+This runs:
+
+- The routine gate: root types, lint/hygiene and library pins, one build, core
+  safety/session/provider/accounting/extension contracts, three real CLI/ACP/process
+  smoke files, and the web authentication and runtime boundary tests.
+- Web TypeScript checks and the shipped dependency advisory/package audit.
+- One exact npm tarball install with normal lifecycle scripts, installed resources,
+  lazy chunks, CLI and extension/library behavior, both web workers and a real Chrome
+  boot/reconnect against that installed server.
+- Native invocation timing with delayed real HTTP headers, durable call timing and
+  eval first-call selection.
+
+No real model, npm login or publication occurs. An unavailable registry or advisory
+service fails qualification. Chrome must be installed at `/usr/bin/google-chrome` on
+Linux. Windows subprocess semantics have a separate narrow CI lane; a Linux pass is
+not evidence of a full Windows or macOS pass.
+
+The command prints the qualified SHA, tarball path and SHA-256. Evidence lives outside
+the checkout under `~/.cache/clio-coder/qualification/<checkout-id>/`, bounded to one
+candidate per checkout. Starting qualification deletes the earlier receipt. A failed
+or cancelled run cannot leave an older qualification available for publication.
+Qualification also repacks after testing and refuses changed package bytes.
+
+Do not run the full suite, rebuild, repack for manual installation, or repeat the
+routine gate afterward. Relevant development regressions should be exercised while
+implementing the change, before qualifying the final committed candidate.
+
+## Review and authorize remote changes
+
+Present the exact commit, package digest, verification results and release notes.
+Every remote main/tag update, GitHub release and npm publication requires explicit
+maintainer authorization.
+
+After authorization, fetch origin, check that `origin/main` is an ancestor of the
+candidate, and fast-forward local main. Verify the SHA is unchanged. Fetch once more
+and stop on unexpected remote movement before pushing only main. After required CI
+passes for that SHA, create and push only the annotated version tag matching
+`package.json`. Never use a dotted release-tag name for a branch.
+
+A temporary `ci-scratch-*` branch is permitted only when explicitly authorized for
+hosted verification. Its CI runs candidate qualification. Delete that owned remote
+branch after inspection. Routine main/PR CI runs `pnpm run ci` as `ci (22)` and cancels superseded
+runs. The required `ci (24)` check tests only engine, provider and durable-session
+compatibility on the other supported Node major, without another build or full gate.
+
+## GitHub release
+
+The tag workflow qualifies the exact tagged source with read-only permissions. It
+uploads the tested tarball and checksum. A separate `release` job has `needs: qualify`,
+verifies the downloaded checksum and creates the release using the matching changelog
+section. Only that job has `contents: write`. Failure or cancellation of qualification
+prevents release creation. No retries, `continue-on-error`, independent repacking or
+npm publication are part of the workflow.
+
+## Publish after authorization
+
+From the unchanged locally qualified checkout, with the same Node version:
+
+```bash
+pnpm run release:preflight
+npm publish
+```
+
+`prepublishOnly` performs the same fast preflight. It checks the clean source SHA,
+Node version, qualification age (maximum 24 hours), original tarball digest, current
+npm package digest, and dated matching release notes. Current packaging includes
+ignored build output, so changing a chunk also invalidates the qualification. Missing,
+stale or changed inputs fail closed and require `pnpm run ci:release` again.
+
+Use normal npm authentication separately when publication is authorized. Confirm the
+version is available before publishing; do not log in or publish merely to test this
+pipeline. No `--ignore-scripts`, bypass flags or hand-authored "already tested" markers.
+
+Verify npm availability and installation after publication, reconcile completed and
+outstanding milestone issues, and close out the local candidate branch only after its
+work is proven on canonical main. Published tags are immutable.
+
+## Optional development investigations
+
+```bash
+pnpm run test:file -- tests/extended/<file>.test.ts
+pnpm run test:full
+pnpm run test:web:full
+pnpm --filter @iowarp/clio-coder-web verify
+pnpm run smoke:real-home -- --target <configured-target-id> --strict
+```
+
+The full root/web suites, browser viewport/accessibility matrix, live models, native
+host interoperability and operator-home checks support development and investigations.
+They are not publication gates. Keep scratch outside the checkout, bound it, clean it,
+and retain subprocess ownership until children settle. Never move an unresolved
+correctness failure out of a required gate to obtain a green release.

package/docs/process/scientific-validation.md

@@ -1,8 +1,5 @@
 # Clio Coder Scientific Validation Contracts
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Clio Coder Scientific Validation Contracts visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/validation_blueprint.html).
-
 Scientific software development cannot treat simple file presence as proof of correctness. A simulation script that crashes on rank 48, or writes out NetCDF arrays filled with `NaN`s, may still successfully write a file to the disk. 
 
 Clio Coder recognizes a **scientific validation contract** as an opt-in signal for a higher evidence bar. One strict loader in `src/domains/safety/validation-contract.ts` reads the first of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, or `validation.yml` at the workspace root and parses it under the version-1 schema below. A contract that parses raises the default rigor level to `high`. A contract that does not parse (empty, malformed YAML, unknown field, unsupported version, over the 256 KiB cap) leaves rigor at `normal` and is diagnosed with the exact fault: `clio-coder doctor` reports it in the `validation contract` row, the interactive session prints it once at startup, and `clio-coder verifiers author` repeats it. A Markdown `VALIDATION.md` is recognized as present but is never parsed and never raises rigor on its own; it is advisory prose for developers, project agents, and external validators.
@@ -74,7 +71,7 @@ Every field except `version` is optional. Strings are capped at 4096 bytes (`not
 1. **`version`:** Required, exactly `1`.
 2. **`task`:** One string describing the work the contract covers.
 3. **`runtime`:** `kind` is required and one of `local`, `slurm`, `mpi`, or `other`; `nodes` and `ranks` are positive integers, `walltime` is a string, and `modules` is a list of strings.
-4. **`artifacts`:** Each entry needs `path`; `format` is a string, `expected_dimensions` maps names to non-negative integers, `expected_attributes` maps names to strings, `numerical_tolerances` holds `relative`, `absolute` (finite non-negative numbers), and `ulp` (non-negative integer), and `preserve` is a boolean. `preserve` is a project convention for cleanup workflows; Clio's built-in protected-artifact guard is separate and is driven by live `protect_path` effects, not by this field.
+4. **`artifacts`:** Each entry needs `path`; `format` is a string, `expected_dimensions` maps names to non-negative integers, `expected_attributes` maps names to strings, `numerical_tolerances` holds `relative`, `absolute` (finite non-negative numbers), and `ulp` (non-negative integer at most 9007199254740991), and `preserve` is a boolean. `preserve` is a project convention for cleanup workflows; Clio's built-in protected-artifact guard is separate and is driven by live `protect_path` effects, not by this field.
 5. **`validators`:** A list of command strings a verifier should satisfy. They remain prose until the project declares matching `verifiers.yaml` entries.
 6. **`notes`:** Free text.
 
@@ -90,10 +87,30 @@ Comparing floating-point values in scientific computations must accommodate roun
 | **`absolute`** | $|val - ref| \le absolute$ | Additive difference check. Used when reference value is close to `0`. |
 | **`ulp`** | $StepsBetween(val, ref) \le ulp$ | Unit in the Last Place. Measures floating-point representation steps. |
 
-Tolerances become executable through a `kind: numeric-compare` entry in `.clio-coder/verifiers.yaml` (catalog version 2). The entry's `command` prints a JSON object of `string -> number | number[]` on stdout, `reference` names a repository-relative JSON file of the same shape, and `tolerance` names at least one of `relative`, `absolute`, or `ulp`. A value passes only when it satisfies every tolerance given; a key missing on either side fails with the key named, arrays compare elementwise and fail on length mismatch, and any `NaN` or infinity fails. The report lists each key's worst deviation and which tolerance it failed, and it is recorded on the `verify` result and on the host-verification check of a dispatch receipt. Clio applies no default tolerance: the catalog entry states it. `clio-coder verifiers author` proposes one such entry for every contract artifact that declares `numerical_tolerances`, with the command left for the operator to fill, so nothing runs until the operator confirms an exact argv. A `kind: perf-budget` entry judges the command's wall time the same way against a `budget` or a recorded baseline; see [Tool usage](../guide/tool-usage.md#project-verifier-catalog).
+Tolerances become executable through a `kind: numeric-compare` entry in `.clio-coder/verifiers.yaml` (catalog version 2). The entry's `command` prints a JSON object of `string -> number | number[]` on stdout, `reference` names a repository-relative JSON file of the same shape, and `tolerance` names at least one of `relative`, `absolute`, or `ulp`. The catalog's `tolerance.combine` is `all` (default) or `any`: each value must satisfy all configured bounds or at least one. This is not an additive absolute-plus-relative formula. A key missing on either side fails, and arrays compare elementwise with length mismatches failing. `tolerance.nonFinite` is `fail` (default) or `match`; matching allows NaN paired with NaN and same-signed infinities. `ulp` is capped at `Number.MAX_SAFE_INTEGER` (9007199254740991). Relative deviation against zero is zero for equality and undefined otherwise; an absolute bound under `combine: any` can admit near-zero values. The report lists each key's worst deviation and which tolerance it failed, and it is recorded on the `verify` result and on the host-verification check of a dispatch receipt. Clio applies no default tolerance: the catalog entry states it. `clio-coder verifiers author` proposes one such entry for every contract artifact that declares `numerical_tolerances`, with the command left for the operator to fill, so nothing runs until the operator confirms an exact argv. A `kind: perf-budget` entry judges the command's wall time the same way against a `budget` or a recorded baseline; see [Tool usage](../guide/tool-usage.md#project-verifier-catalog).
 
 ---
 
+## Inspectable verification evidence
+
+Numeric reports include effective `combine`, `nonFinite`, a readable `rule`, per-key worst deviations and held/violated bounds, plus reference source/path/hash/bytes and actual extracted-payload hash/bytes. Non-finite report fields serialize as `"NaN"`, `"Infinity"`, and `"-Infinity"` rather than null. Input still follows the numeric JSON parser; those report strings do not authorize strings in numeric payloads. Judged output and numeric reference/baseline files have a 32 MiB ceiling. A capped, aborted, timed-out, or failed execution cannot be judged from partial output. Numeric payloads also cap keys at 4096 and elements at 1000000. These are capture/parser bounds, not claims that peak process memory equals 32 MiB.
+
+`judgement.execution` records `succeeded`, `failed`, `timed-out`, `aborted`, or `output-capped`. `judgement.validation` records `passed`, `failed`, `exit-code` for an ordinary command, or `not-run`. `judgement.scientificValidity` always says `"not established by this check"`. Direct verify and host-declared dispatch verification retain these distinctions and reference provenance. Passing a declared comparison cannot establish that its reference, units, model, or sampling design is correct.
+
+`clio-coder verifiers baseline <id>` writes version-2 performance baselines after a clean run, recording `wallTimeMs`, `check`, `recordedAt`, and `environment`: hostname, platform, arch, CPU model/count, total memory bytes, and Node version. Version-1 baselines remain readable without environment metadata. A performance report records baseline path/hash/bytes and `environment` with baseline/current records and `differing` field names. Environment differences are informational; the declared wall-time budget still decides the pass. A single baseline measurement is not a statistical performance campaign.
+
+The executable tolerance example is:
+
+```yaml
+tolerance:
+  absolute: 1.0e-9
+  relative: 1.0e-6
+  combine: any
+  nonFinite: fail
+```
+
+`combine` and `nonFinite` belong to the version-2 executable verifier catalog. They are not additional fields in version-1 advisory `artifacts[].numerical_tolerances`.
+
 ## Common Scientific Artifact Families
 
 The following labels are useful project conventions for validation contracts and reports. They are not a closed, core-enforced enum in the current source tree:
@@ -143,5 +160,5 @@ File readback establishes artifact inspection, not executed scientific validatio
    - If mutating tool calls occurred in that window without executed validation evidence or a `limitation` receipt, `finishContractRegistration` (`src/domains/safety/finish-contract-registration.ts`) emits a `request_continuation` middleware effect accompanied by a reminder (`HIGH_RIGOR_REVALIDATION_MESSAGE`). At normal rigor, it emits an advisory reminder without blocking.
    - The gate checks structural evidence presence; it does not grade the empirical correctness of scientific code. Runtime turn budgets, deadline limits, operator cancellation, and tool failures still apply.
    - A limitation receipt never converts missing or failing checks into a pass; it formally records the limitation so callers and operators know the scientific result is incomplete.
-   - Verified by contracts `tests/contracts/materio-plugin.test.ts` and `tests/contracts/safety-policy-remediation.test.ts`.
+   - Verified by contracts `tests/extended/materio-plugin.test.ts` and `tests/extended/safety-policy-remediation.test.ts`.