@iowarp/clio-coder 0.4.3 → 0.4.5

package/docs/process/development-pipeline.md

@@ -22,7 +22,7 @@ under pressure; git mechanics alone never justify a stage.
 | 2. Fix | [`fix-issue`](../../skills/git/fix-issue/) | An uncommitted, verified change where failing tests preceded the fix, self-reviewed against the issue's acceptance criteria |
 | 3. Ship | [`ship`](../../skills/git/ship/) | An atomic conventional commit referencing the issue (`fixes #N`); contributors push it to their fork and open a PR, while maintainer work stays local for gated integration; merge is a human decision |
 
-Releases follow [release-cut-checklist.md](../history/release-cut-checklist.md) as a
+Releases follow [release-cut-checklist.md](release-cut-checklist.md) as a
 human-gated checklist, not a skill. Worktrees
 ([`worktree-create`](../../skills/git/worktree-create/),
 [`worktree-merge`](../../skills/git/worktree-merge/)),
@@ -74,10 +74,10 @@ replace Clio copies without crossing the product boundary:
 
 1. Read the release notes or package changelogs for `pi-ai`, `pi-agent-core`,
    and `pi-tui`.
-2. Run `npm run pi:surface-diff`. A changed or removed symbol that Clio imports
+2. Run `pnpm run pi:surface-diff`. A changed or removed symbol that Clio imports
    is an error; a new export is review input.
 3. Run the focused contracts in the
-   [Pi regression net](../architecture/pi-boundary.md#pi-regression-net), then run `npm run ci`.
+   [Pi regression net](../architecture/pi-boundary.md#pi-regression-net), then run `pnpm run ci`.
 4. Walk Pi's fixed-issue list against the
    [Pi SDK boundary table](../architecture/pi-boundary.md). For every fix in a surface Clio
    still owns, either delete Clio's copy in favor of Pi or add a dated reason
@@ -86,26 +86,31 @@ replace Clio copies without crossing the product boundary:
    worth a Clio ticket.
 
 After review, regenerate `docs/pi-surface.json` with
-`npm run pi:surface-snapshot`, inspect the symbol and signature changes, and
+`pnpm run pi:surface-snapshot`, inspect the symbol and signature changes, and
 commit the dependency pins, snapshot, boundary notes, and proving contracts
-together. `npm run lint` invokes the surface check automatically when the
+together. `pnpm run lint` invokes the surface check automatically when the
 installed Pi versions differ from the checked-in snapshot.
 
 ## Test lanes
 
-`npm test` uses Node's test runner over every `tests/contracts/*.test.ts` and
+`pnpm test` uses Node's test runner over every `tests/contracts/*.test.ts` and
 `tests/smoke/*.test.ts` file, with `tests/harness/tmp-root.ts` preloaded to
 isolate test state. Its `pretest` hook builds `dist/` when the CLI bundle is
 absent. Run one focused file while iterating with:
 
 ```bash
-npm run test:file -- tests/contracts/<name>.test.ts
+pnpm run test:file tests/contracts/<name>.test.ts
 ```
 
 There is no committed weighted-shard or special serial-lane runner. Keep timing
-claims within the focused contract that owns them, and use the full `npm run ci`
+claims within the focused contract that owns them, and use the full `pnpm run ci`
 gate before handoff.
 
+The release smoke script `scripts/smoke-real-home.sh` (invoked via
+`pnpm run smoke:real-home`) tests booting the built CLI binary against a copy of
+the operator settings in a scratch home. An optional `--strict` flag makes doctor
+exit 1 fail the smoke run on failing rows instead of tolerating fleet state.
+
 ## Issue conventions
 
 - **Title**: conventional tag plus imperative summary (`fix: memory overlay
@@ -138,7 +143,7 @@ or bumped; the milestone closes when the tag is published.
 ## Dogfooding setup
 
 The marketplace copy under `skills/git/` is the committed source of truth,
-pinned in `skills/registry.yaml` by `npm run skills:pin`. Runtime roots are
+pinned in `skills/registry.yaml` by `pnpm run skills:pin`. Runtime roots are
 gitignored, so each developer installs locally:
 
 ```bash
@@ -147,6 +152,6 @@ cp -r skills/git/file-ticket .claude/skills/       # Claude Code
 ```
 
 The other pipeline skills are model-invoked from the marketplace catalog the
-same way. When a skill changes, re-run `npm run skills:pin` and re-copy;
+same way. When a skill changes, re-run `pnpm run skills:pin` and re-copy;
 drift between an installed copy and the pinned hash surfaces a warning at
 activation.

package/docs/process/documentation-guide.md

@@ -138,7 +138,7 @@ have a dedicated blueprint. `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.
-`npm run lint` rejects any absent named blueprint, enforces that mapping, and
+`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.
 
@@ -154,7 +154,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 `npm run lint` to verify Markdown and HTML blueprint parity.
+7. Run `pnpm run lint` to verify Markdown and HTML blueprint parity.
 
 Suggested local link check:
 

package/docs/process/eval-runner.md

@@ -408,6 +408,17 @@ classifications: `improved`, `regressed`, `unchanged`, or `incomparable` for the
 mean and for variability. Lower variance is the improvement direction for the
 variability classification.
 
+When both artifacts declare `target` or `wireModel` in `matrix.dimensions`,
+the corresponding target id or model id is omitted from scenario grouping.
+This aligns a single baseline route with a single candidate route before
+checking their execution envelopes. Reports preserve both route identities
+as `baselineTargets` and `candidateTargets`; the existing `target` remains the
+baseline route, or the candidate route when the baseline group is missing.
+If grouping would combine multiple distinct target/model routes on either
+side, comparison fails with `behavioralMetrics.ambiguousRouteGroup` instead
+of treating the pooled trials as comparable. Repeats of the same route still
+form one distribution.
+
 Correctness and safety rows are hard. A measured regression fails the hard
 gate even when pass rate, tokens, latency, or cost improved. Losing a
 correctness or safety measurement that existed in the baseline is also a hard
@@ -509,3 +520,7 @@ The current reference `mini` endpoint is the llama.cpp router at `192.168.86.141
 ## Task Outcome Measurement (`verify.measure`)
 
 Task outcome commands declared under `verify.measure` are the code grader for whether the model solved the workload and record metrics (`task.solved`, `task.exitCode`). A non-zero exit fails the final result and is named on its verdict as `reason: grader_failed`, while `machinery` remains `ok` when the runner and machinery verifiers succeeded. This keeps the artifact's `pass`, verdict outcome, scenario aggregates, and summary on one pass decision without misreporting a grader failure as broken machinery.
+
+## Artifact reporting and comparison
+
+Eval runs print a report command for custom output artifacts. `clio-coder eval report --artifact <path>` reads the original artifact with strict provenance validation and does not import it into the store. Comparison aligns jointly declared target/model variations while preserving both route identities, rejects ambiguous route groups, and retains execution-envelope differences. Compact mismatch and hard-gate identities omit runner attachments; full artifact reports retain them.

package/docs/process/evals-internal.md

@@ -10,7 +10,7 @@ checkout or object store.
 Run a private suite from this source checkout with:
 
 ```sh
-npm run build
+pnpm run build
 clio-coder eval run --suite <external-path> --clio-coder-entry dist/cli/index.js
 ```
 

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

@@ -66,6 +66,21 @@ Clio-Evidence: receipt-v20/sha256:<64-character digest>
 Clio does not invent, shorten, or add an unrelated digest. The role trailers do
 not depend on this optional line.
 
+A commit also names the decisions it was made under, one trailer per active
+decision on the session decision board (an `ask_user` answer or a design
+choice the agent recorded with `decide`):
+
+```text
+Clio-Decision: <interviewId>/<key>
+```
+
+The refs come from the sealed receipt's `decisionRefs` at the fleet seam and
+from the live board at the session seam. They are sorted, capped at 32, added
+once, and only refs of the `<id>/<key>` shape are written, where the key is an
+operator `snake_case` key or an agent `kebab-case` key. A decision trailer
+records rationale provenance; it is not evidence that the decision was correct
+or that its work was validated.
+
 ## Commit paths and hooks
 
 The deterministic SDLC fleet attributes its plan, code, and documentation

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

@@ -0,0 +1,207 @@
+# 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 `v044` for version `0.4.4`. Dotted branch
+names like `v0.4.4` 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 v044 origin/main
+   ```
+
+2. Update `version` in `package.json` to the release version.
+
+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
+   ```
+
+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 v044
+   ```
+
+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.
+
+## 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 v044
+   ```
+
+   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.

package/docs/process/scientific-validation.md

@@ -5,19 +5,19 @@
 
 Scientific software development cannot treat simple file presence as proof of correctness. A simulation script that crashes on rank 48, or writes out NetCDF arrays filled with `NaN`s, may still successfully write a file to the disk. 
 
-Clio Coder recognizes **scientific validation contract files** as an opt-in signal for a higher evidence bar. Currently, the session rigor resolver does not parse or enforce a scientific contract schema. The presence of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md` at the workspace root raises the default rigor level to `high`; the file contents are advisory material for developers, project agents, and external validators.
+Clio Coder recognizes 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.
 
-This advisory convention is separate from the executable project verifier catalog at `.clio-coder/verifiers.yaml`. The verifier catalog has a strict version-1 schema and admits exact argv vectors to the `verify` tool. Scientific validation contracts and handbook expectations do not grant command authority: prose such as `validators: ["python tools/check_grid.py"]` remains guidance until the project owner confirms the equivalent argv, cwd, timeout, and tags in `verifiers.yaml`. The executable catalog does not interpret numerical tolerances or artifact expectations; it only runs the explicitly declared process vector through safe-exec.
+This advisory convention is separate from the executable project verifier catalog at `.clio-coder/verifiers.yaml`. The verifier catalog has a strict schema (version 2, with version 1 still loading) and admits exact argv vectors to the `verify` tool. Scientific validation contracts and handbook expectations do not grant command authority: prose such as `validators: ["python tools/check_grid.py"]` remains guidance until the project owner confirms the equivalent argv, cwd, timeout, and tags in `verifiers.yaml`. The executable catalog runs only the explicitly declared process vector through safe-exec; a `numeric-compare` or `perf-budget` entry adds a judgement of that command's output or wall time, never an interpretation of the contract's artifact expectations.
 
-`clio-coder verifiers author` can inspect top-level `validators` entries in the YAML contract filenames above and propose catalog checks. It labels those vectors as project-declared and shows their source index, exact argv, cwd, timeout, tags, catalog path, and resulting execution authority. This inspection is read-only. A command string with sound quoting and no shell operator can be represented as argv for review; shell expansion, pipes, redirection, environment assignments, incomplete quoting, and Markdown prose receive a manual JSON-argv diagnostic. Nothing becomes executable and nothing is dry-run until the operator confirms the catalog write with `--yes`.
+`clio-coder verifiers author` reads the parsed contract's `validators` entries through the same loader and proposes catalog checks. It labels those vectors as project-declared and shows their source index, exact argv, cwd, timeout, tags, catalog path, and resulting execution authority. This inspection is read-only. A command string with sound quoting and no shell operator can be represented as argv for review; shell expansion, pipes, redirection, environment assignments, incomplete quoting, and Markdown prose receive a manual JSON-argv diagnostic. Nothing becomes executable and nothing is dry-run until the operator confirms the catalog write with `--yes`.
 
-The convention below is a recommended shape for scientific projects that need to document expected dimensions, attributes, numerical tolerances, scheduler context, and verification commands for scientific artifacts. Developed at the [Gnosis Research Center (GRC)](https://grc.iit.edu) at Illinois Tech as part of the NSF-funded scientific-software context (NSF Award [#2411318](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2411318)), this convention links execution metadata with physical output checks without claiming that the current harness executes those checks automatically.
+The convention below is a recommended shape for scientific projects that need to document expected dimensions, attributes, numerical tolerances, scheduler context, and verification commands for scientific artifacts. Developed at the [Gnosis Research Center (GRC)](https://grc.iit.edu) at Illinois Tech as part of the NSF-funded scientific-software context (NSF Award [#2411318](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2411318)), this convention links execution metadata with physical output checks; the harness executes a check only through a matching `verifiers.yaml` entry.
 
 ---
 
 ## Validation Contract Convention
 
-A validation contract can be stored as YAML or Markdown. A custom or project-level agent (such as a local `scientific-validator` agent example under `.clio-coder/agents/`) or the developer can draft these files and commit them next to the research code. Clio core currently checks only for the documented filenames at the workspace root.
+A validation contract is a YAML file under the version-1 schema; `VALIDATION.md` is the Markdown companion for prose that the schema cannot hold. A custom or project-level agent (such as a local `scientific-validator` agent example under `.clio-coder/agents/`) or the developer can draft these files and commit them next to the research code. The loader rejects unknown fields at every level and names the field it rejected, so a typo is a diagnostic rather than a silently ignored key.
 
 ### Example netCDF / Slurm validation contract:
 ```yaml
@@ -69,12 +69,14 @@ checks:
     tags: [scientific, netcdf]
 ```
 
-### Suggested Fields:
-1. **`version`:** Set to `1` for project-local compatibility.
-2. **`runtime.kind`:** Document execution mode (`local`, `slurm`, `mpi`, or `other`).
-3. **`artifacts`:** List output files or directories the validation plan should inspect.
-4. **`preserve`:** Project convention for artifacts that should not be deleted by cleanup workflows. Clio's built-in protected-artifact guard is separate and is driven by live `protect_path` effects, not by this YAML field.
-5. **`validators`:** List shell commands or scripts a verifier should run to validate the generated files.
+### Schema (version 1):
+Every field except `version` is optional. Strings are capped at 4096 bytes (`notes` at 16 KiB), `artifacts` at 256 entries, `validators` at 128, `runtime.modules` at 64, and each map at 256 keys; a diagnostic cites the cap it crossed.
+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.
+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.
 
 ---
 
@@ -88,8 +90,7 @@ 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. |
 
-> [!NOTE]
-> Clio core does not currently execute tolerance comparisons and does not apply a default numerical tolerance. Put defaults directly in project validators or contract text.
+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).
 
 ---
 
@@ -112,12 +113,12 @@ Scheduler-driven runs require distinct validation handling compared to local uni
 - **Queue status is not validation**: Checking if a Slurm command like `sbatch` exits successfully only proves that the Slurm scheduler accepted the job script. A good contract tells the verifier how to check actual simulation artifacts inside `out/` or `ckpt/` after job completion.
 - **Environment module loading**: The `runtime.modules` array can document the exact software stack dependencies (such as `intel/2024`, `openmpi/5.0`) that must be loaded before running the validators.
 - **HPC and Data Integration**: For large-scale allocations such as those at the Argonne Leadership Computing Facility (ALCF), projects can archive verification logs through their own storage or data-transfer workflow. Clio core does not manage Globus transfers.
-- **Validator execution**: In the current alpha version, contract validation is advisory. Quality/verification agents (such as the base `verifier` agent or custom project-level agents) read the contract to guide developers and write out verification receipts. Automated in-harness contract execution is not implemented yet.
+- **Validator execution**: A parsed contract's `artifacts` and `validators` are requirements the `verifier` agent and custom project-level agents must satisfy, and they are executable only through `verifiers.yaml` entries. Automated in-harness execution of the contract itself is not implemented.
 
 ### How a Validation Contract Raises Session Rigor
 
 Clio Coder integrates scientific validation contracts directly into its safety model to raise the evidence standard automatically:
-- **Automatic Escalation**: At startup, Clio scans the workspace root. The presence of any validation contract (e.g. `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md`) automatically escalates the session's rigor level from `normal` to `high`.
-- **High-Rigor Gate Requirements**: Once the rigor is raised to `high`, the finish gate is active. It engages on a settled `turn_end` only when the recent window contains successful workspace mutation evidence and no validation evidence or explicit limitation. The window is entries since the last user message, capped at 80 entries:
+- **Parsed contract escalates**: At startup and at every finish-gate decision, `rigorResolution()` in `src/domains/safety/rigor.ts` loads the contract. A contract that parses raises the session's rigor level from `normal` to `high` with source `validation-contract`. An unparseable contract yields `normal` with source `invalid-contract` and the fault as the diagnostic; a Markdown-only workspace yields `normal` with source `markdown-advisory`. `CLIO_CODER_RIGOR` still overrides both directions.
+- **High-Rigor Gate Requirements**: Once the rigor is `high`, the finish gate is active. It engages on a settled `turn_end` only when the recent window contains successful workspace mutation evidence and no validation evidence or `limitation` receipt. The window is entries since the last user message, capped at 80 entries:
   - Clio issues a `request_continuation` middleware effect to keep the session running.
-  - Clio injects a dynamic warning reminder (`HIGH_RIGOR_REVALIDATION_MESSAGE`) instructing the agent to run a verification command or to declare a limitation before it can conclude the turn.
+  - Clio injects a dynamic warning reminder (`HIGH_RIGOR_REVALIDATION_MESSAGE`) instructing the agent to run a verification command or to call `limitation` before it can conclude the turn.

package/evals/README.md

@@ -3,3 +3,7 @@
 These suites exercise Clio's one evaluation engine from a source checkout: run the deterministic built-in authority corpus with `node dist/cli/index.js eval run --suite evals/behavioral-machinery.yaml --clio-coder-entry dist/cli/index.js`, or select a configured model target for `behavioral-model.yaml`, `behavioral-model-negative-control.yaml`, and `tracked-metrics-baseline.yaml`. The npm archive keeps these inputs for inspection and reproducibility, but the deterministic TypeScript driver uses the repository development toolchain. The graders and fixtures beside the suites are versioned inputs; `behavioral-machinery-baseline.json` is retained as reference evidence, not as a release gate.
 
 The single-system boundary is the engine under `src/domains/eval`: suites, verdict validation, artifact envelopes, comparison, and reporting belong there, while `evals/` contains source-checkout reference inputs and deterministic drivers. In v0.5.0, external-benchmark adapters such as SWE-bench and Terminal-Bench should translate their cases and grader observations into this engine's suite, execution, and verdict contracts, then consume its artifacts and comparison reports instead of adding a parallel harness.
+
+`tool-surface-model.yaml` is a dedicated model-required suite for read tail arguments, bash working-directory reset between calls, and rejection of a non-HTTP web_fetch URL. Run it with a configured target using `node dist/cli/index.js eval run --suite evals/tool-surface-model.yaml --target <target-id> --model <model-id> --trials 3 --clio-coder-entry dist/cli/index.js`. This invokes the selected model and incurs its normal inference cost. The URL case deliberately expects one tool error; it requires no successful web request. The target must expose all three tools, and local policy blocks are measured separately from execution errors.
+
+Each trial records `tools.calls.<tool>`, `tools.succeeded.<tool>`, `tools.failed.<tool>`, and `tools.blocked.<tool>` from terminal tool events, plus grader correctness. Compare repeated runs with the same target, model, and settings when evaluating a description change; no arbitrary text perturbation is guaranteed to worsen model behavior. CI executes the suite and real graders against controlled successful and failing event fixtures without calling a model. Those contracts validate the evaluation machinery and are not live model scores.