@iowarp/clio-coder 0.3.3 → 0.3.4

package/docs/scientific-validation.md

@@ -1,11 +1,15 @@
 # Clio Coder Scientific Validation Contracts
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive numerical tolerance calculator and HPC queue execution simulator is located at [docs/html/validation_blueprint.html](html/validation_blueprint.html) (Version: 0.3.3).
+> **Interactive Spec Available:** An interactive numerical tolerance calculator and HPC queue execution simulator is located at [docs/html/validation_blueprint.html](html/validation_blueprint.html) (Version: 0.3.4).
 
 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. In v0.3.3, core Clio 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 **scientific validation contract files** as an opt-in signal for a higher evidence bar. In v0.3.4, 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.
+
+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.
+
+`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`.
 
 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.
 
@@ -51,6 +55,20 @@ notes: |
   Re-run check_grid.py after job completion is observed.
 ```
 
+The `validators` values above are intentionally advisory shell-like prose. Preview the exact catalog proposal with `clio-coder verifiers author`, or declare the Python validator manually without granting free-form shell interpretation:
+
+```yaml
+# .clio-coder/verifiers.yaml
+version: 1
+checks:
+  - id: validate-grid
+    description: Validate the generated regional grid
+    command: [python, tools/check_grid.py, out/region_west.nc]
+    cwd: .
+    timeoutMs: 120000
+    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`).
@@ -77,7 +95,7 @@ Comparing floating-point values in scientific computations must accommodate roun
 
 ## 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 v0.3.3:
+The following labels are useful project conventions for validation contracts and reports. They are not a closed, core-enforced enum in v0.3.4:
 
 - **`HDF5` / `NetCDF` / `Zarr`:** Multi-dimensional scientific array files.
 - **`FITS`:** Flexible Image Transport System (used in astrophysics).

package/docs/session-lifecycle.md

@@ -1,6 +1,6 @@
 # Session Lifecycle
 
-This document is the authoritative specification for Clio Coder interactive and headless session lifecycles, on-disk ledger structures, tree-based conversation branching, checkpoints, and recovery protocols in `v0.3.3`.
+This document is the authoritative specification for Clio Coder interactive and headless session lifecycles, on-disk ledger structures, tree-based conversation branching, checkpoints, and recovery protocols in `v0.3.4`.
 
 Source implementations: `src/engine/session.ts` and `src/domains/session/`.
 
@@ -39,11 +39,11 @@ export interface ClioSessionMeta {
   piMonoVersion: string;
   platform: string;
   nodeVersion: string;
-  sessionFormatVersion?: number; // CURRENT_SESSION_FORMAT_VERSION = 3
+  sessionFormatVersion?: number; // CURRENT_SESSION_FORMAT_VERSION = 4
 }
 ```
 
-Format version `CURRENT_SESSION_FORMAT_VERSION = 3` (`src/engine/session.ts:66`) is stamped on all sessions created in `v0.3.3`. Sessions with missing or earlier format versions trigger schema migrations in `src/domains/session/migrations/` on `/resume`.
+Format version `CURRENT_SESSION_FORMAT_VERSION = 4` (`src/engine/session.ts`) is stamped on all sessions created since the working-set layer landed. Version 4 adds the `contextEviction` and `contextRecall` ledger kinds. `runMigrations` in `src/domains/session/migrations/` rejects both directions on `/resume`: a missing or earlier version names the remedy (remove the session directory), and a version from the future says the session was written by a newer Clio and must not be read by this build.
 
 ---
 

package/docs/skills-marketplace.md

@@ -1,7 +1,7 @@
 # Skills Marketplace
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/skills_blueprint.html](html/skills_blueprint.html) (Version: 0.3.3).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/skills_blueprint.html](html/skills_blueprint.html) (Version: 0.3.4).
 
 The Skills Hub (`/skill`) shows project skills, user skills, and the marketplace. Every marketplace row comes from the same local lookup that `clio-coder skills install <name>` and `/skill <name>` resolve through, so the hub lists nothing it cannot install.
 

package/docs/tool-usage.md

@@ -1,11 +1,11 @@
 # Tool Usage Reference
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive seven-plane tool atlas and observation envelope truncation/offload calculator is located at [docs/html/tool_usage_blueprint.html](html/tool_usage_blueprint.html) (Version: 0.3.3).
+> **Interactive Spec Available:** An interactive seven-plane tool atlas and observation envelope truncation/offload calculator is located at [docs/html/tool_usage_blueprint.html](html/tool_usage_blueprint.html) (Version: 0.3.4).
 
 This is the deep usage reference behind the deliberately terse tool descriptions in the prompt envelope. Toolkit v2 keeps rich guidance out of tool descriptions and puts it here, where `context(scope="docs", query=...)` retrieves it section by section. Each tool below has its own self-contained `##` section covering the argument surface, defaults, truncation and continuation behavior, and concrete calls. Source of truth is `src/tools/`.
 
-In Clio Coder v0.3.3, `src/tools/agent-tools.ts` serves as the single agent-tool adapter across both orchestrator and worker runtimes. Both surfaces resolve their executable tools through the exact same `effectiveToolNames` narrowing, ensuring that attested tool schemas never drift from the tools available at runtime. Tools are keyed strictly by the `ToolName` union with no alias table. Argument leniency for weak-model callers is provided exclusively by per-tool `prepareArguments` normalizers declared on `ToolSpec`.
+In Clio Coder v0.3.4, `src/tools/agent-tools.ts` serves as the single agent-tool adapter across both orchestrator and worker runtimes. Both surfaces resolve their executable tools through the exact same `effectiveToolNames` narrowing, ensuring that attested tool schemas never drift from the tools available at runtime. Tools are keyed strictly by the `ToolName` union with no alias table. Argument leniency for weak-model callers is provided exclusively by per-tool `prepareArguments` normalizers declared on `ToolSpec`.
 
 ## Observation envelope: truncation notices, offload, next hints, and the turn budget
 
@@ -21,7 +21,7 @@ Truncated text results append exactly one notice line:
 
 Segments that do not apply are omitted. `<total>` renders as `N+` when the search stopped early at its item limit, so the true total was never counted. `next:` is an exact argument fragment (for example `limit=200` or `offset=451`); re-issue the same call with that argument changed to continue.
 
-Offload: when the byte cap cut content that was already collected, the complete rendering is written to `<clio-coder state dir>/scratch/<sessionId>/<toolCallId>.txt` and the notice's `full:` segment names the path. Read it with `read` using offset/limit. Tools offload only when the byte cap cut collected content; a bare item-limit truncation continues via `next` and does not offload. `read` never offloads, because the source file is directly re-addressable via `offset`.
+Offload: when the byte cap cut content that was already collected, the complete rendering is written to `<clio-coder state dir>/scratch/<sessionId>/<sha256 of the captured text>.txt` and the notice's `full:` segment names the path. Read it with `read` using offset/limit. Tools offload only when the byte cap cut collected content; a bare item-limit truncation continues via `next` and does not offload. `read` never offloads, because the source file is directly re-addressable via `offset`.
 
 JSON-format results (code_nav, context scope=docs/workspace) never get an appended notice. An oversize JSON payload is replaced whole by the parseable stub `{"error":"result exceeded <cap>","offloadPath":"...","next":"..."}` so the model never receives JSON cut mid-document. Empty results are also valid JSON with empty arrays and `next` populated.
 
@@ -102,17 +102,24 @@ Arguments:
 - `command` (required).
 - `cwd` (optional). Working directory; resolved against the session workspace and rejected when it escapes it. The safety net blocks an escaping cwd at admission, and the tool enforces the same rule itself.
 - `timeout_ms` (optional). Default 300000 (5 minutes).
+- `output_policy` (optional). Canonical model-context disposition: `full`, `bounded`, `summary`, or `metadata-only`. Omission is exactly `bounded`.
 
 Workspace containment: commands whose filesystem targets resolve outside the session workspace escalate to `system_modify` and ask for one-shot confirmation at every autonomy level (headless runs deny asks). Recognized targets are shell redirects, `tee`/`mkdir`/`touch` path operands, `cp`/`mv`/`ln` destinations, in-place `sed -i` operands, and any `cd`/`pushd` whose directory leaves the workspace, since a `cd` outside re-bases every relative path that follows it. Inside-workspace equivalents stay plain `execute` with no new prompts.
 
-Output shaping is tail-biased: the display keeps the LAST 16KB / 2000 lines, because the failing assertion, compiler error, and exit summary live at the end. Before truncating, the full output is spilled to the per-session scratch file and the appended note names the path; read it with offset/limit. A command producing more than 16MB of output is stopped with an error. A timeout or nonzero exit returns the shaped output plus a status line (`bash: command timed out after <ms>ms`, `bash: command failed (exit N)`).
+The default `bounded` policy keeps a tail-biased model excerpt under the 16KB result budget, because the failing assertion, compiler error, and exit summary usually live at the end. `summary` is useful for noisy builds and test runs: code deterministically selects a bounded head, tail, and error-like lines, applies Clio's repository secret redactor, and records the source hash and algorithm in summary provenance. `metadata-only` is appropriate when the model needs only outcome and termination facts; stdout and stderr stay out of model context while the operator presentation, retained byte size, and retrieval path remain available. `full` is for output known to be small. It is admitted only when the complete captured result and its facts fit the bounded result/context budget; otherwise the result explicitly records a typed downgrade to tail-biased `bounded` and provides retrieval. Do not use `full` as the routine default.
 
-Reach for bash for builds, git, package managers, and anything without a dedicated tool. Prefer the dedicated tools over their shell equivalents: grep/find/read/ls get envelope truncation, exact continuation hints, and the shared ignore policy that `cat`, shell `grep`, and shell `find` do not. Prefer `verify` over bash for declared package.json verification scripts, since verify produces typed evidence.
+Presentation is independent from model context. The operator-facing display remains folded and tail-biased under every policy. When the display or selected context omits captured content, the terminal result writes one per-session scratch artifact and names it in the result. Live updates use the selected policy, remain bounded, and never write per-update artifacts. Every terminal result records requested and applied context modes, captured/displayed/context bytes, truncation or downgrade state, and any offload path. Exit code, signal, timeout, abort, and output-cap facts survive every policy. Scratch retrieval may contain the raw retained output; the deterministic `summary` projection is the redacted surface.
+
+A command producing more than 16MB of combined output is stopped with an error. UTF-8 decoding spans process chunks, and a code point split by the hard byte cap is discarded rather than replaced with an invalid character. Raw NUL bytes are removed from model context under every policy, which leaves multi-byte code points and ANSI escape sequences whole; the operator presentation and the scratch artifact keep the captured bytes, and the result still records the omission and its retrieval path. A timeout, abort, output cap, or nonzero exit preserves captured diagnostics and appends a status line such as `bash: command timed out after <ms>ms` or `bash: command failed (exit N)` before canonical shaping.
+
+Reach for bash for builds, git, package managers, and anything without a dedicated tool. Prefer the dedicated tools over their shell equivalents: grep/find/read/ls get envelope truncation, exact continuation hints, and the shared ignore policy that `cat`, shell `grep`, and shell `find` do not. Prefer `verify` over bash for declared package scripts and project-catalog entries, since verify produces typed evidence.
 
 ```text
 bash(command="git status --short")
 bash(command="git log --oneline -10")
 bash(command="npm run build", timeout_ms=600000)
+bash(command="npm run test", timeout_ms=600000, output_policy="summary")
+bash(command="make artifact", output_policy="metadata-only")
 ```
 
 ## grep: search file contents with ripgrep
@@ -266,27 +273,87 @@ dispatch(tasks=["Refactor step 1", "Refactor step 2"], mode="sequential", timeou
 
 ## verify: run declared verification checks
 
-One EXECUTE entry point for declared verification. Sources: `src/tools/verify/index.ts`, `src/tools/verify/scripts.ts`, `src/tools/verify/frontend.ts`.
+One EXECUTE entry point for declared verification. Sources: `src/tools/verify/index.ts`, `src/tools/verify/catalog.ts`, `src/tools/verify/scripts.ts`, `src/tools/verify/authoring.ts`, `src/tools/verify/frontend.ts`.
 
 Arguments:
 
-- `check` (optional). A declared package.json script name or `"frontend"`. Omit to list available checks.
+- `check` (optional). A declared project-catalog ID, package.json script name, or `"frontend"`. Omit to list available checks.
 - `path` (check=frontend). Artifact file under the workspace root.
-- `args` (optional). Extra arguments passed to the script after `--`. A JSON-string array is tolerated and parsed.
+- `args` (package scripts only). Extra arguments passed after `--`. A JSON-string array is tolerated and parsed. Project-catalog checks ignore this field.
 - `browser` (check=frontend). `auto` (default), `required`, or `off`.
-- `cwd` (optional). Working directory.
-- `timeout_ms` (optional). Default 120000.
+- `cwd` (package scripts only). Package working directory. Project catalogs are always discovered at the session workspace root, and a project check uses its declared `cwd`.
+- `timeout_ms` (package scripts and frontend only). Default 120000. A project check uses its declared `timeoutMs`.
+- `max_output_bytes` (package scripts and frontend only). Default 600000. Project checks retain the safe-exec default cap.
+
+`verify()` lists checks grouped as `package.json` and `.clio-coder/verifiers.yaml`. Both providers project through the same canonical metadata: `{id, description, command, cwd, timeoutMs, tags, source}`. Package scripts must match the verification family `test*/lint*/build*/typecheck*/check*/format*/ci*` (a family prefix, optionally followed by `:`, `.`, or `-` and a suffix, e.g. `test:unit`). `verify(check="typecheck")` runs `npm run typecheck` through the safe-exec spine with no shell. A package script name outside the family is rejected with a pointer to run it through bash.
+
+### Project verifier catalog
+
+Projects may commit a versioned executable catalog at `.clio-coder/verifiers.yaml`:
+
+```yaml
+version: 1
+checks:
+  - id: rust-workspace
+    description: Run the Rust workspace tests
+    command: [cargo, test, --workspace]
+    cwd: .
+    timeoutMs: 600000
+    tags: [rust, test]
+```
+
+Version 1 is strict. Every root and check field shown above is required, unknown fields fail, and duplicate IDs fail. A project ID uses lowercase letters, digits, `.`, `_`, `:`, or `-`, begins with a letter or digit, and is at most 64 UTF-8 bytes. `frontend` is reserved. Descriptions are trimmed single-line text capped at 512 bytes. `command` is a nonempty argv array with at most 64 entries and 4096 bytes per entry. A shell command string is invalid, and explicit shell executables such as `sh`, `bash`, `pwsh`, and `cmd` are rejected. `cwd` is a repository-relative existing directory capped at 512 bytes; absolute paths, `..` escapes, and symbolic-link escapes fail. `timeoutMs` is a positive integer capped at 900000. A check may carry at most 16 distinct lowercase tags of at most 32 bytes each. The whole file is capped at 262144 bytes and may contain at most 128 checks. YAML aliases are disabled.
+
+Provider IDs share one namespace. If a catalog ID collides with a discovered package script, listing and execution fail and identify both source files. Catalog parsing also fails closed before any package or project check runs.
+
+`verify(check="rust-workspace")` spawns exactly `cargo` with `test` and `--workspace`; it does not interpolate model text or invoke a shell. Model-supplied `args`, `cwd`, `timeout_ms`, `max_output_bytes`, or undeclared environment fields cannot widen or replace the catalog entry. Safe execution passes only Clio's small environment allowlist, applies cancellation and the declared timeout, and shapes output at the standard 600000-byte cap. Execution details retain the compatible command string plus exact `argv`, `cwd`, `exitCode`, `durationMs`, `aborted`, `timedOut`, and `outputCapped` evidence, along with the check's declared source, command, cwd, timeout, description, and tags.
+
+### Guided catalog authoring
+
+An empty `verify()` result points to `clio-coder verifiers author`. The authoring command inspects only command-bearing files at the workspace root:
+
+- verification-family package scripts, projected exactly as `npm run <script>` and shown as already active rather than duplicated into the catalog;
+- `Cargo.toml`, projected to Cargo's package or workspace test vector;
+- visible build and test entries in `CMakePresets.json`, projected to the corresponding `cmake --build --preset` or `ctest --preset` vector;
+- declared Python runners in `pyproject.toml`, `pytest.ini`, `tox.ini`, `noxfile.py`, or the pytest section of `setup.cfg`;
+- a module directive in `go.mod`, projected to `go test ./...`;
+- top-level `validators` entries in the documented YAML scientific-validation files.
+
+Every proposal records its source path and location and labels the command origin as `project-declared` or `toolchain-defined`. Project-declared examples include a package script, a Python entry point, and an exact validation-contract command. Toolchain-defined examples include Cargo's test command, a named CMake preset invocation, a configured Python runner, and Go's module test command. Validation command strings are converted to argv only when their quoting is complete and they contain no shell operators, expansion, redirection, or environment assignment. Ambiguous entries and `VALIDATION.md` prose receive a manual-entry diagnostic. Directory names such as `build`, `tests`, `python`, or `cargo` never imply a command.
+
+`discover` and every mutating command first print an authority preview. Each check shows the destination or active source path, source provenance, exact JSON argv vector, repository-relative cwd, timeout, tags, and effective execution authority. Preview and discovery do not create `.clio-coder`, write a file, or run a check. A mutating command without `--yes` ends after the preview. Repeating the reviewed command with `--yes` is the explicit write decision; the serialized YAML must pass the production catalog parser before the atomic write is reachable.
+
+```text
+clio-coder verifiers discover
+clio-coder verifiers author
+clio-coder verifiers author --exclude cmake-build-debug --rename go-test=go-suite
+clio-coder verifiers author --dry-run go-suite --yes
+clio-coder verifiers validate
+```
+
+`validate` reads the committed file with the same parser used by `verify()`. `dry-run <id>` is an explicit request to execute one admitted check through the production `verify` path. `author --dry-run <id> --yes` writes only after confirmation and starts the selected dry run only after the write is accepted by production discovery.
+
+Later changes use the same preview and confirmation boundary. `edit` preserves the ID unless `rename` is requested. Renames and additions reject collisions with catalog IDs and active package-script IDs. Removals state that the deleted command will no longer be executable through catalog authority. Generated IDs are stable for a stable ordered signal set; a collision receives the first available deterministic `-2`, `-3`, and later suffix.
+
+```text
+clio-coder verifiers add --id validate-grid --description "Validate the regional grid" --command '["python","tools/check_grid.py","out/region_west.nc"]'
+clio-coder verifiers add --id validate-grid --description "Validate the regional grid" --command '["python","tools/check_grid.py","out/region_west.nc"]' --tags scientific,netcdf --yes
+clio-coder verifiers edit validate-grid --timeout-ms 300000
+clio-coder verifiers rename validate-grid validate-regional-grid --yes
+clio-coder verifiers remove validate-regional-grid --yes
+```
 
-`verify()` with no check lists declared checks grouped by source; today the only source is package.json scripts whose names match the verification family `test*/lint*/build*/typecheck*/check*/format*/ci*` (a family prefix, optionally followed by `:`, `.`, or `-` and a suffix, e.g. `test:unit`). `verify(check="typecheck")` runs `npm run typecheck` through the safe-exec spine with no shell; output is capped at 600000 bytes and `details = {command, cwd, exitCode, durationMs, timedOut, outputCapped}`. A script name outside the family is rejected with a pointer to run it through bash.
+The `add` command is the explicit path for an unsupported or ambiguous project. `--command` must be a JSON argv array, so manual entry still cannot turn a shell command string into executable catalog authority.
 
 `verify(check="frontend", path=<file>)` validates an HTML, CSS, or JavaScript artifact without shell access. The path must stay inside the workspace root and end in `.html`, `.htm`, `.css`, `.js`, `.mjs`, or `.cjs`. Checks per type: HTML tag balance (comment-aware, HTML5 optional end tags honored), inline and referenced script syntax (classic scripts parsed in-process, modules via `node --check`), inline and linked CSS brace/string/comment balance, local script and stylesheet references resolved and existence-checked (external and root-relative references are skipped), and an optional headless browser load. `browser="auto"` warns when no chromium/chrome/edge executable is on PATH, `"required"` fails, `"off"` skips. Each check reports pass, warn, fail, or skip; any fail makes the whole result an error. `details = {action: "verify", check: "frontend", path, browserMode, status, checks}`.
 
-Prefer verify over bash for the verification family: the typed result feeds the finish contract as validation evidence.
+Prefer verify over bash for the verification family and project catalog: the typed result feeds the finish contract as validation evidence.
 
 ```text
 verify()
 verify(check="typecheck")
 verify(check="test", args=["tests/contracts/dispatch.test.ts"])
+verify(check="rust-workspace")
 verify(check="frontend", path="site/index.html", browser="off")
 ```
 

package/docs/trace-store.md

@@ -1,7 +1,7 @@
 # Trace store contract
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive trace database viewer, schema inspector, and SQL query validator simulator is located at [docs/html/trace_blueprint.html](html/trace_blueprint.html) (Version: 0.3.3).
+> **Interactive Spec Available:** An interactive trace database viewer, schema inspector, and SQL query validator simulator is located at [docs/html/trace_blueprint.html](html/trace_blueprint.html) (Version: 0.3.4).
 
 Clio's trace database is a rebuildable, queryable mirror. Receipts, session
 ledgers, gate artifacts, and evidence remain the source of truth. Removing

package/docs/troubleshooting.md

@@ -1,6 +1,6 @@
 # Troubleshooting & Error Remediation
 
-This guide provides concrete, actionable remediation procedures for operational errors, permission denials, target connection failures, and system diagnostics in Clio Coder `v0.3.3`.
+This guide provides concrete, actionable remediation procedures for operational errors, permission denials, target connection failures, and system diagnostics in Clio Coder `v0.3.4`.
 
 ---
 

package/docs/tui-design.md

@@ -1,7 +1,7 @@
 # Clio TUI Design System
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive color/glyph token laboratory and terminal transcript preview renderer is located at [docs/html/tui_design_blueprint.html](html/tui_design_blueprint.html) (Version: 0.3.3).
+> **Interactive Spec Available:** An interactive color/glyph token laboratory and terminal transcript preview renderer is located at [docs/html/tui_design_blueprint.html](html/tui_design_blueprint.html) (Version: 0.3.4).
 
 This document is the reference specification for the Clio Coder TUI visual layout, styling, and behavior. It describes color semantics, the glyph vocabulary, structural recipes, and state choreography for all surfaces under [src/interactive/](../src/interactive/).
 

package/docs/worker-dispatch-mechanics.md

@@ -1,7 +1,7 @@
 # Worker Dispatch Mechanics
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive NDJSON protocol timeline stream and heartbeat watchdog simulator is located at [docs/html/worker_dispatch_blueprint.html](html/worker_dispatch_blueprint.html) (Version: 0.3.3).
+> **Interactive Spec Available:** An interactive NDJSON protocol timeline stream and heartbeat watchdog simulator is located at [docs/html/worker_dispatch_blueprint.html](html/worker_dispatch_blueprint.html) (Version: 0.3.4).
 
 This document describes the design and lifecycle of Clio Coder dispatched workers, focusing on the spawning sequence, execution isolation, the standard input/output NDJSON communication loop, and permission escalation routing.
 
@@ -213,6 +213,16 @@ Receipts carry exactly one integrity version (`RUN_RECEIPT_INTEGRITY_VERSION = 1
 - **Strict Primitive Handling**: `undefined` object properties are omitted; non-finite numbers (`NaN`, `Infinity`) or `bigint` throw an explicit serialization error.
 - **Coverage**: Includes every current receipt field and reconstructible ledger field, including route intent/decision/quality, execution role, worker identity, result-contract conformance, node/reroute/gate/plan provenance, briefing, steering, and `outcomeCode`.
 
+Integrity is only the artifact-integrity axis of the canonical trust status.
+The other axes are validation grounding, independent review, context
+provenance, autonomy enforcement, and completion evidence. Sealing proves that
+the receipt matches its covered ledger facts; it does not verify correctness,
+establish context authorship, turn a correlated review into an independent
+one, or prove completion. Every non-absent canonical fact retains a named
+source and authority plus bounded references to detailed artifacts. The full
+state vocabulary and compatibility map are documented in
+[`evidence-and-memory.md`](evidence-and-memory.md#canonical-trust-status).
+
 ### 5.3 Acceptance Coverage
 
 The assignment contract's acceptance scenarios map to deterministic contract

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@iowarp/clio-coder",
-	"version": "0.3.3",
+	"version": "0.3.4",
 	"description": "Coding agent for HPC and scientific-software developers, part of IOWarp's CLIO ecosystem of agentic science.",
 	"keywords": [
 		"ai",
@@ -77,7 +77,7 @@
 		"pretest": "test -f dist/assets/codewiki.json && [ -z \"$(find src -newer dist/assets/codewiki.json -type f -print -quit)\" ] || npm run build",
 		"test": "node scripts/shard-tests.mjs",
 		"test:coverage": "node scripts/test-coverage.mjs --experimental-test-coverage --test-coverage-include='src/**/*.ts' --test-coverage-exclude='src/**/*.d.ts' 'tests/contracts/**/*.test.ts' 'tests/smoke/**/*.test.ts'",
-		"test:repeat": "node tests/harness/repeat-tests.mjs",
+		"test:repeat": "node scripts/repeat-tests.mjs",
 		"test:trace-viewer": "npm --prefix apps/trace-viewer test",
 		"trace:ui": "node apps/trace-viewer/server.mjs",
 		"ci": "npm run typecheck && npm run lint && npm run skills:check && npm run build && npm run test && npm run test:trace-viewer",
@@ -86,15 +86,12 @@
 		"prepublishOnly": "npm run ci:release",
 		"skills:pin": "node --import tsx scripts/pin-skills.ts",
 		"skills:check": "node --import tsx scripts/pin-skills.ts --check",
-		"//": "below here: real providers or a live model target, cost money and/or time, never run in CI",
-		"test:live": "node scripts/live-smoke.mjs",
-		"test:live-eval": "node scripts/live-eval-recon.mjs",
-		"test:live-eval:fleet-dispatch": "node scripts/live-eval-fleet-dispatch.mjs",
-		"test:live-verify:dispatch-routing": "node scripts/live-verify-dispatch-routing.mjs",
-		"test:lifecycle": "node --import tsx scripts/lifecycle-matrix.mjs",
-		"bench:swe": "python3 benchmarks/community/swe-bench-lite/swebench_clio.py",
-		"bench:scicode": "python3 benchmarks/community/scicode/scicode_clio.py",
-		"bench:tb": "python3 benchmarks/community/clio_fleet.py"
+		"//": "below here: a real model target, chosen with --target <id>; costs money and/or GPU time, never run in CI",
+		"live:smoke": "node --import tsx benchmarks/internal/live-smoke.ts",
+		"live:recon": "node --import tsx benchmarks/internal/live-recon.ts",
+		"live:fleet-dispatch": "node --import tsx benchmarks/internal/live-fleet-dispatch.ts",
+		"live:tui": "node --import tsx benchmarks/internal/pty-drive.ts",
+		"live:home": "node --import tsx benchmarks/internal/live-home.ts"
 	},
 	"dependencies": {
 		"@anthropic-ai/claude-agent-sdk": "0.3.186",

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

@@ -1,7 +1,7 @@
 ---
 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.3
+version: 0.1.4
 license: Apache-2.0
 clio:
   registry-id: iowarp/clio-coder
@@ -24,17 +24,15 @@ local-vs-contribute boundary.
 ## Commands
 
 ```bash
-npm run typecheck         # tsc -p tsconfig.tests.json (includes tests/)
-npm run lint              # biome check .
-npm run check:boundaries  # import boundary rules (tsx, no build)
+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 test:live         # local live provider smoke; requires CLIO_CODER_LIVE_SMOKE=1
-npm run test:live -- --delegation  # adds local opencode/copilot ACP checks
+npm run live:smoke -- --target <id>   # one real turn against a configured target; never in CI
 ```
 
 ## Which layer catches what
@@ -44,7 +42,7 @@ npm run test:live -- --delegation  # adds local opencode/copilot ACP checks
 | 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 check:boundaries` | enforces rule1/2/3 |
+| 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 |
 
@@ -54,8 +52,9 @@ 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`). If `npm run check:boundaries` reports a
-violation, fix the import — never silence the check:
+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.
@@ -70,9 +69,9 @@ 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 and `check:boundaries` run
-  `node --import tsx --test` and import `src/**` directly, so they always run the
-  latest source with zero build step. Iterate here whenever the change is pure
+- **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
@@ -98,7 +97,7 @@ restart the process (against a freshly built `dist/`).
 1. Write the change.
 2. `npm run typecheck` and `npm run lint`.
 3. Run the narrowest layer from the table above.
-4. `npm run check:boundaries` if you touched imports.
+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
@@ -113,8 +112,10 @@ node --import tsx --test --test-only tests/contracts/<file>.test.ts  # it.only
 
 ## What NOT to do
 
-- Don't reintroduce `tests/unit|integration|e2e/` or a pty harness — that
-  taxonomy was deliberately removed.
+- 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`).
@@ -126,5 +127,7 @@ node --import tsx --test --test-only tests/contracts/<file>.test.ts  # it.only
 
 ## Harness reference
 
-Driving the real CLI, the mock provider, and ACP over stdio, plus the throwaway
-probe pattern: **see `references/harness.md`**.
+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`.

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

@@ -7,7 +7,7 @@ the gap (it cites the dead unit/integration/e2e taxonomy), then WITH it.
 Prompt: "I changed pure logic in `src/domains/dispatch/validation.ts`. What do I
 run and why?"
 Expected:
-- `npm run test:file -- 'tests/contracts/**/*.test.ts'` (and `check:boundaries` if imports changed).
+- `npm run test:file -- 'tests/contracts/**/*.test.ts'` (and `npm run lint` if imports changed).
 - Explains contracts import `src` via tsx, so no build is needed.
 - Does NOT suggest `test:unit` / `test:e2e` (those don't exist).
 
@@ -26,14 +26,14 @@ Expected:
   interactive testing. Distinguishes this from config hot-reload (classify.ts).
 
 ## T4 — boundary violation
-Prompt: "`check:boundaries` says a domain imports another domain's extension.ts.
+Prompt: "`npm run lint` says a domain imports another domain's extension.ts.
 Quickest fix?"
 Expected:
 - Route through the target domain's `index.ts` contract (rule3). Does NOT
   suggest a `biome-ignore` or exclude.
 
 ## Baseline failure modes to watch for (RED)
-- Cites `test:unit`/`test:integration`/`test:e2e` or a pty harness.
+- Cites `test:unit`/`test:integration`/`test:e2e`, or a PTY other than `tests/harness/pty.ts`.
 - Claims smoke tests run against source (they run against `dist/`).
 - Invents a hot-reload feature that reloads a running session's code.
 

package/skills/meta/clio-test/references/harness.md

@@ -1,18 +1,20 @@
 # Clio test harness reference
 
-How to drive the real Clio binary, a mock provider, and the ACP surface in
-tests. All of this is non-interactive — there is no pty harness in v0.2.2.
+How to drive the real Clio binary, a mock provider, the ACP surface, and a
+real pseudo-terminal in tests. Every model here is a stub; these are machinery
+tests. A run against a real model is `benchmarks/internal/SKILL.md`.
 
 ## Contents
 - The spawn harness (`runCli`, `makeScratchHome`)
 - Mocking a provider (OpenAI-compatible SSE fixture)
 - ACP over JSON-RPC/stdio
+- The PTY (`openPty`, `runInPty`)
 - One-off probes (no test file)
 
 ## The spawn harness
 
-`tests/harness/spawn.ts` is the only harness. It spawns `node dist/cli/index.js`,
-so **build first** (or keep `npm run dev` running) before `test:smoke`.
+`tests/harness/spawn.ts` spawns `node dist/cli/index.js` with piped stdio, so
+**build first** (or keep `npm run dev` running) before running smoke.
 
 ```ts
 import { makeScratchHome, runCli } from "../harness/spawn.js";
@@ -76,11 +78,38 @@ client (see `createJsonRpcProcessClient` in the smoke test): `initialize` →
 non-spec discriminator breaks strict clients like Zed, so the smoke test asserts
 every emitted variant is in the v1 set.
 
+## The PTY
+
+Piped stdio reports no terminal width and no TTY, so the TUI refuses to start
+and every width-sensitive path collapses to 80 columns. `tests/harness/pty.ts`
+opens a real pseudo-terminal through `node-pty` (a devDependency, never
+shipped):
+
+```ts
+import { openPty, runInPty, stripAnsi, visibleLines } from "../harness/pty.js";
+
+// Scripted: type on a schedule, stop when the output matches, bounded by a timeout.
+const run = await runInPty(process.execPath, [CLI], { cols: 120, rows: 40, cwd, env,
+  readyWhen: /ctx /, input: [{ afterMs: 200, data: "/quit\r" }], until: /bye/, timeoutMs: 20_000 });
+
+// Controllable: write, resize, pause output, wait for a matcher, wait for exit.
+const session = await openPty(process.execPath, [CLI], { cols: 140, rows: 44, cwd, env });
+await session.waitForOutput((out) => /ctx /.test(stripAnsi(out)), 30_000);
+session.write("/quit\r");
+await session.waitForExit(10_000);
+```
+
+Use it only for what a pipe cannot show: width, raw mode, SIGINT through a
+terminal, the alternate-screen and keyboard-protocol teardown. The three
+suites that need it are `tests/smoke/tui-width-matrix.test.ts`,
+`instant-shell-pty.test.ts`, and `render-trace-pty.test.ts`. Anything else
+belongs on `runCli`.
+
 ## One-off probes (no test file)
 
 To poke at Clio without writing a permanent test, drop a throwaway script in
-`/tmp` and run it with tsx. Delete it when done — never leave probes under
-`tests/` or `scripts/`.
+your scratch directory and run it with tsx. Delete it when done — never leave
+probes under `tests/`, `scripts/`, or `benchmarks/`.
 
 ```ts
 // /tmp/probe.ts

package/skills/meta/clio-test/references/test-map.md

@@ -1,4 +1,4 @@
-# Where Clio's tests live (v0.2.2)
+# Where Clio's tests live
 
 Three layers under `tests/`. Add a new test next to the closest existing file;
 create a new file only for a genuinely new domain cluster.
@@ -7,10 +7,17 @@ create a new file only for a genuinely new domain cluster.
 
 | Layer | Path | Runner | Build needed |
 |---|---|---|---|
-| contracts | `tests/contracts/*.test.ts` | `node --import tsx --test` | no (imports `src`) |
-| smoke | `tests/smoke/*.test.ts` | `node --import tsx --test` | **yes** (spawns `dist/`) |
-| boundaries | `tests/boundaries/*.test.ts` | `node --import tsx --test` | no |
-| harness (not a test) | `tests/harness/spawn.ts` | imported by smoke | — |
+| contracts | `tests/contracts/*.test.ts` | `npm run test:file -- <glob>` (tsx + scratch root) | no (imports `src`) |
+| smoke | `tests/smoke/*.test.ts` | `npm run test:file -- <glob>` | **yes** (spawns `dist/`) |
+| boundaries | `tests/boundaries/check-boundaries.ts` | `npm run lint` (hygiene) | no |
+| harness (not tests) | `tests/harness/*.ts` | imported by contracts and smoke | — |
+
+The harness modules: `spawn.ts` (run the built CLI with pipes), `scratch-env.ts`
+(isolated Clio home), `pty.ts` (a real pseudo-terminal), `openai-compat-fixture.ts`
+and `fake-lmstudio-server.ts` (stub providers), `fake-ssh.ts` (stub fleet node),
+`clock.ts` (steppable clock), plus dispatch, receipt, and module-graph helpers.
+Everything under `tests/` stubs the model. Real-model runs are
+`benchmarks/internal/` and never run under `npm test`.
 
 ## Contract test files
 
@@ -33,18 +40,21 @@ create a new file only for a genuinely new domain cluster.
 | Area | File |
 |---|---|
 | non-interactive CLI + ACP-over-stdio end-to-end | `tests/smoke/cli.test.ts` |
-| import boundary rules (rule1/2/3) | `tests/boundaries/boundaries.test.ts` |
-| boundary checker implementation | `tests/boundaries/check-boundaries.ts` |
+| the package as installed from `npm pack` | `tests/smoke/pack-install.test.ts` |
+| TUI at real terminal sizes, NO_COLOR, Ctrl-C teardown (PTY) | `tests/smoke/tui-width-matrix.test.ts` |
+| instant shell before hydration, SIGTERM through the lease (PTY) | `tests/smoke/instant-shell-pty.test.ts` |
+| committed-frame render trace under PTY backpressure (PTY) | `tests/smoke/render-trace-pty.test.ts` |
+| import boundary rules (rule1/2/3), run under `npm run lint` | `tests/boundaries/check-boundaries.ts` |
 
 ## Running a subset
 
 ```bash
 # all contracts
-node --import tsx --test 'tests/contracts/**/*.test.ts'
+npm run test:file -- 'tests/contracts/**/*.test.ts'
 # one file
-node --import tsx --test tests/contracts/skills.test.ts
+npm run test:file -- tests/contracts/skills.test.ts
 # only it.only / describe.only within a file
-node --import tsx --test --test-only tests/contracts/skills.test.ts
+npm run test:file -- --test-only tests/contracts/skills.test.ts
 ```
 
 ## Writing tests

package/skills/registry.yaml

@@ -61,8 +61,8 @@ skills:
     sha256: 386ebfdac9379ebf5630fa7a9af259bb45f473f7d3d679b0a7ef4164f5fc4dea
   - name: clio-test
     path: meta/clio-test
-    version: 0.1.3
-    sha256: 99683ea7d7bf5bf57788e58ee6c66e01a4e30ec8d3d7d0a1f8b2b85caff4ae5a
+    version: 0.1.4
+    sha256: 90ca1fe7660cd8c3d835801883ebd55d2d17cb652b8585b28ddb82aec642336e
   - name: credentials
     path: meta/credentials
     version: 0.1.2

package/skills/skill-marketplace.json

@@ -109,7 +109,7 @@
 			"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.",
 			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/meta/clio-test",
-			"version": "0.1.3",
+			"version": "0.1.4",
 			"audit": "pass",
 			"category": "meta"
 		},