@iowarp/clio-coder 0.4.6 → 0.4.7

package/docs/process/development-pipeline.md

@@ -18,27 +18,27 @@ under pressure; git mechanics alone never justify a stage.
 
 | Stage | Skill | Output |
 | --- | --- | --- |
-| 1. File | [`file-ticket`](../../skills/git/file-ticket/) | A labeled GitHub issue with evidence and acceptance criteria |
-| 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 |
+| 1. File | [`file-ticket`](../../library/skills/git/file-ticket/) | A labeled GitHub issue with evidence and acceptance criteria |
+| 2. Fix | [`fix-issue`](../../library/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`](../../library/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](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/)),
-[`branch-closeout`](../../skills/git/branch-closeout/),
-[`resolve-merge-conflicts`](../../skills/git/resolve-merge-conflicts/), and
-[`tdd`](../../skills/coding/tdd/) are à-la-carte tools reached for when the
+([`worktree-create`](../../library/skills/git/worktree-create/),
+[`worktree-merge`](../../library/skills/git/worktree-merge/)),
+[`branch-closeout`](../../library/skills/git/branch-closeout/),
+[`resolve-merge-conflicts`](../../library/skills/git/resolve-merge-conflicts/), and
+[`tdd`](../../library/skills/coding/tdd/) are à-la-carte tools reached for when the
 situation calls for them, not stages every change passes through. An RCA
 written as the closing comment on the issue (`rca` label) is an artifact of
 hard bugs, not a mandatory toll booth. Batch ticket creation from a PRD
-bypasses stage 1 and uses [`backlog`](../../skills/planning/backlog/)
+bypasses stage 1 and uses [`backlog`](../../library/skills/planning/backlog/)
 instead; everything downstream is identical.
 
 ## Closeout
 
 A merged PR is not operationally finished until its local scaffolding is
-closed. The reusable [`branch-closeout`](../../skills/git/branch-closeout/) skill automates this verification and teardown safely. After the human merge decision:
+closed. The reusable [`branch-closeout`](../../library/skills/git/branch-closeout/) skill automates this verification and teardown safely. After the human merge decision:
 
 1. Fetch and prune, confirm the PR's merged state, and identify the resulting
    commit on `origin/main`. Direct ancestry proves an ordinary merge; a squash
@@ -142,13 +142,13 @@ 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 `pnpm run skills:pin`. Runtime roots are
+The marketplace copy under `library/skills/git/` is the committed source of truth,
+pinned in `library/skills/registry.yaml` by `pnpm run skills:pin`. Runtime roots are
 gitignored, so each developer installs locally:
 
 ```bash
-cp -r skills/git/file-ticket .clio-coder/skills/   # Clio Coder
-cp -r skills/git/file-ticket .claude/skills/       # Claude Code
+cp -r library/skills/git/file-ticket .clio-coder/skills/   # Clio Coder
+cp -r library/skills/git/file-ticket .claude/skills/       # Claude Code
 ```
 
 The other pipeline skills are model-invoked from the marketplace catalog the

package/docs/process/documentation-coverage.md

@@ -12,7 +12,7 @@ treated as current operator guidance.
 ## Headline
 
 - Markdown pages audited: **51**.
-- Dedicated HTML blueprints now present: **51**.
+- Dedicated HTML blueprints present after that audit: **51**.
 - Pages without a blueprint: **0**. Every Markdown page has one visual
   counterpart, so there are no exception reasons to record.
 - Pages with one or more source disagreements at `ff56ea3e`: **42**.
@@ -98,3 +98,30 @@ The source-alignment pass corrected all findings across the 42 affected
 Markdown pages. The table preserves what the audit found at `ff56ea3e`; it does
 not describe outstanding Markdown debt. Every HTML blueprint now renders the
 complete corrected counterpart and identifies its Markdown source explicitly.
+
+## Clio Coder 0.4.7 documentation refresh
+
+The 0.4.7 pass was a source-alignment pass, not a re-measurement of the 0.4.2
+audit above, whose table stands as the historical record.
+
+Pages carrying new or rewritten sections in this pass: `README.md`,
+`architecture/context-engine.md`, `architecture/library.md`,
+`architecture/model-catalog.md`, `architecture/pi-boundary.md`,
+`architecture/safety-model.md`, `architecture/session-lifecycle.md`,
+`architecture/tui-design.md`, `architecture/worker-context.md`,
+`guide/commands-and-modes.md`, `guide/configuration-reference.md`,
+`guide/extensions-and-sharing.md`, `guide/harness-extensions.md`,
+`guide/interop.md`, `guide/plugins.md`, `guide/resource-library.md`,
+`guide/skills-marketplace.md`, and `process/scientific-validation.md`, each with
+its paired blueprint.
+
+Two standing rules this pass reaffirmed. Every asserted behavior is anchored to
+the function or contract that implements it, named inline, rather than inferred
+from a UI label or a neighbouring paragraph. And a value that appears only in a
+test fixture is not a product default: the compiled defaults in
+`src/core/defaults.ts` are the authority for what ships unset.
+
+Per-run verification evidence for the refresh lives with the maintenance records
+for that sprint, not in this page. This page tracks documentation coverage, and
+run logs age out of usefulness faster than the docs they checked.
+

package/docs/process/documentation-guide.md

@@ -46,7 +46,8 @@ Classify claims clearly:
 | [configuration-reference.md](../guide/configuration-reference.md) | `src/core/defaults.ts`, `src/cli/**`, `src/tools/**`, `src/domains/agents/recipe-schema.ts`, `src/domains/providers/models/local-models/**` | Audited inventory of every settings key, environment variable, CLI flag, project-file key, frontmatter key, tool argument, and model tag with defaults and precedence. |
 | [safety-model.md](../architecture/safety-model.md) | `src/domains/safety/**`, `src/tools/registry.ts`, `src/tools/policy.ts`, `src/tools/verify/**`, `src/entry/orchestrator.ts`, `src/domains/dispatch/write-boundary.ts` | Operating posture, `resolveEffectiveAutonomy` / `resolveBaselineAutonomy`, detect-and-rollback write boundaries, approval axes, damage control, typed validation. |
 | [prompt-envelope-and-tools.md](../architecture/prompt-envelope-and-tools.md) | `src/domains/prompts/compiler.ts`, `src/interactive/chat-loop.ts`, `src/core/tool-names.ts`, `src/tools/registry.ts`, `src/tools/observation.ts`, `src/tools/agent-tools.ts` | Prompt envelope reuse, canonical tool delivery via single `agent-tools.ts` adapter, seven-plane tool surface, observation envelope, strict `ToolName` keying. |
-| [tool-usage.md](../guide/tool-usage.md) | `src/tools/agent-tools.ts`, `src/tools/registry.ts`, `src/tools/observation.ts` | In-depth reference for all 21 canonical tools, including conditional registration, parameters, typical payloads, normalizers, and error examples. |
+| [tool-usage.md](../guide/tool-usage.md) | `src/tools/agent-tools.ts`, `src/tools/registry.ts`, `src/tools/observation.ts` | In-depth reference for all 24 canonical tools, including conditional registration, parameters, typical payloads, normalizers, and error examples. |
+| [panes-and-files.md](../guide/panes-and-files.md) | `src/interactive/panes-runtime.ts`, `src/interactive/yazi-bridge.ts`, `src/domains/mux/operations.ts`, `src/domains/mux/yazi/theme.ts`, `src/cli/panes.ts` | Operator path to panes and the files pane: install, settings, doctor rows, `/files` and `Alt+E`, presets, what `/quit` closes, theme boundary, troubleshooting. |
 | [provider-adapter-cookbook.md](../architecture/provider-adapter-cookbook.md) | `src/domains/providers/registry.ts`, `src/domains/providers/types/runtime-descriptor.ts` | RuntimeDescriptor, probe(), probeReasoning(), synthesizeModel(), thinking mechanisms. |
 | [pi-boundary.md](../architecture/pi-boundary.md) | `src/engine/**`, `src/tools/truncate.ts`, `tests/boundaries/check-boundaries.ts` | Which Pi SDK capabilities Clio delegates to, which Clio-specific adapters remain, and the boundary tests that keep the split explicit. |
 | [alcf-provider.md](../architecture/alcf-provider.md) | `src/domains/providers/runtimes/cloud/alcf.ts`, `src/engine/alcf-oauth.ts` | Globus PKCE OAuth, openAuthStorage(), Sophia vLLM, Metis API, chatTemplateKwargsUnsupported. |
@@ -55,6 +56,7 @@ Classify claims clearly:
 | [fleet-dispatch.md](../guide/fleet-dispatch.md) | `src/domains/dispatch/**` | Multi-node SSH dispatch: process-safe admission, capacity leases, fleet contracts v1 through v5, v4 write boundaries, v5 plan and gate steps, bounded check/repair loops (`loop_bound_exhausted`), deterministic code steps, attestation, and receipts v20. |
 | [capacity-and-scheduling.md](../architecture/capacity-and-scheduling.md) | `src/domains/scheduling/**`, `src/domains/dispatch/capacity-lease.ts`, `src/domains/dispatch/reservation-store.ts` | Multi-process capacity leases (`dispatch-admission.json`), heartbeat TTLs, cross-process transaction locks (`dispatch-admission.json.lock`), and cluster drain controls. |
 | [worker-dispatch-mechanics.md](../architecture/worker-dispatch-mechanics.md) | `src/worker/**` | NDJSON parent-child socket protocols, control/bulk lane demuxing, watchdog timers, worker attestation (13 protocol fields), permission parking, exit codes. |
+| [worker-context.md](../architecture/worker-context.md) | `src/worker/spec-contract.ts`, `src/domains/dispatch/**`, `src/worker/**` | Worker context inheritance: isolated, fork, and splice context modes for native workers, historical message selection, and token limits. |
 | [fleet-demo-runbook.md](fleet-demo-runbook.md) | `src/domains/dispatch/**` | Multi-node fleet demo: SSH setup, C++ build/repair workflow, reviewer gates, and receipt verification v20. |
 | [session-lifecycle.md](../architecture/session-lifecycle.md) | `src/engine/session.ts`, `src/domains/session/**` | Session lifecycle, on-disk ledger format v4 (`current.jsonl`), tree branching (`tree.json`), active-path lineage selection, `/fork`, `/resume`, checkpoints, and write-ahead protected-artifact journal. |
 | [acp.md](../architecture/acp.md) | `src/engine/acp/**`, `src/cli/acp.ts` | Agent Client Protocol (ACP) server over stdio, tool mediation, non-stall permission handling, timeout bounds, and error taxonomy. |
@@ -65,19 +67,25 @@ Classify claims clearly:
 | [documentation-coverage.md](documentation-coverage.md) | `src/**` | Complete source-to-documentation mapping matrix and subsystem coverage status. |
 | [tui-design.md](../architecture/tui-design.md) | `src/interactive/theme/tokens.ts`, `src/interactive/theme/glyphs.ts` | TUI color system, glyph vocabulary (`contextReserve`), structural layouts, state choreography, code ink. |
 | [installation-and-lifecycle.md](../guide/installation-and-lifecycle.md) | `src/cli/paths.ts`, `src/cli/doctor.ts`, `src/cli/uninstall.ts`, `src/cli/removal.ts` | Installation, upgrade, reset, uninstallation, launcher ownership and what `--remove-binary` will and will not remove, partial-failure behavior, configuration folders (`credentials.yaml` `0o600`), and permissions. |
-| [release-cut-checklist.md](../history/release-cut-checklist.md) | `scripts/check-release.mjs`, `tests/smoke/installed-package.test.ts`, `.github/workflows/`, `package.json` | Historical v0.4.1 release procedure retained as evidence; future releases must draft and verify their own checklist. |
-| [development-pipeline.md](development-pipeline.md) | `skills/git/**`, `.github/**`, `scripts/check-release.mjs`, `package.json` | Issue-to-PR development lifecycle, validation, release inheritance, and the human merge boundary. |
+| [release-cut-checklist.md](release-cut-checklist.md) | `scripts/check-release.mjs`, `tests/smoke/installed-package.test.ts`, `.github/workflows/`, `package.json` | Standard release procedure: local candidate preparation, release gate verification, fast-forward landing on main, annotated tag publication, and npm publish. |
+| [release-cut-checklist.md (v0.4.1)](../history/release-cut-checklist.md) | `scripts/check-release.mjs`, `tests/smoke/installed-package.test.ts`, `.github/workflows/`, `package.json` | Historical v0.4.1 release procedure retained as evidence; future releases must draft and verify their own checklist. |
+| [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. |
 | [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 eight `clio-coder trace` subcommands: `runs`, `phases`, `tail`, `procs`, `inspect`, `prune`, read-only `sql`, and `ui`. |
+| [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`. |
 | [eval-runner.md](eval-runner.md) | `src/domains/eval/**`, `src/cli/eval.ts` | Local YAML eval tasks, dual token accountings (`tokens.*` wire vs `receiptUsage.*` journal), fail-closed null totals, EvalArtifactV4 format, `verify.measure` task outcome recording. |
 | [evals-internal.md](evals-internal.md) | `src/domains/eval/**`, `evals/**` | Private suite handling, measurement design, and the boundary between shipped reference inputs and external campaigns. |
 | [extensions-and-sharing.md](../guide/extensions-and-sharing.md) | `src/domains/extensions/**`, `src/domains/resources/**`, `src/domains/share/**`, `src/cli/extensions.ts`, `src/cli/share.ts` | Prompt, skill, agent, fleet, and reserved theme resources; extension manifests; portable share archives. |
+| [library.md](../architecture/library.md) | `src/domains/plugins/**`, `src/domains/resources/library.ts`, `src/cli/library.ts` | Package kinds, catalog resolution, integrity, scope selection, and trust. |
 | [resource-library.md](../guide/resource-library.md) | `src/domains/resources/library.ts`, `src/cli/library.ts` | Catalog schemas, private and remote source policy, checksum pins, resource installation, and update checks. |
-| [skills-marketplace.md](../guide/skills-marketplace.md) | `src/interactive/overlays/skills-hub.ts`, `src/domains/resources/skills/marketplace.ts` | Skills Hub marketplace discovery through the install resolver, empty state, install actions, publishing flow. |
+| [skills-marketplace.md](../guide/skills-marketplace.md) | `src/interactive/overlays/library.ts`, `src/interactive/overlays/library-tabs.ts`, `src/domains/resources/skills/marketplace.ts` | Skills marketplace discovery through library overlays, catalog inspection, install actions, publishing flow. |
+| [plugins.md](../guide/plugins.md) | `src/domains/plugins/**`, `src/domains/resources/library.ts`, `src/cli/library.ts` | Portable domain bundles, library installation, enable/disable states, drift detection, pins, and package lifecycle. |
+| [authoring-plugins.md](../guide/authoring-plugins.md) | `library/**`, `src/domains/plugins/**`, `src/domains/resources/library-validation.ts` | Plugin and package structure, root plugin.json manifests, resource mapping, validation, and authoring guidelines. |
+| [harness-extensions.md](../guide/harness-extensions.md) | `src/domains/extensions/**`, `src/domains/plugins/**`, `src/interactive/**` | Harness extension lifecycle, command handlers, dynamic reload, and interaction with the Clio execution environment. |
+| [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`). |
 | [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. |
@@ -133,8 +141,8 @@ Clio Coder maintains two complementary documentation formats:
 
 Blueprint coverage is explicit rather than inferred from document style. The
 page-level audit lives in
-[`documentation-coverage.md`](documentation-coverage.md). All 51 Markdown pages
-have a dedicated blueprint. `docs/html/index.html` groups those counterparts by
+[`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.

package/docs/process/eval-runner.md

@@ -14,6 +14,9 @@ Source of truth: [src/domains/eval/](../../src/domains/eval/) and [src/cli/eval.
 The CLI commands under `clio-coder eval` support running, validating, reporting, comparing, and gating evaluation suites.
 
 ```bash
+clio-coder eval validate --package <path|kind:name> [--eval <name>] [--user|--project]
+clio-coder eval run --package <path|kind:name> [--eval <name>] [--user|--project] [--out <path>]
+clio-coder eval skill <name|path> [--scenario <id>] [--json]
 clio-coder eval validate --suite <suite.yaml>
 clio-coder eval run --suite <suite.yaml> [--trials <n>] [--target <id>] [--model <id>] [--out <path>] [--clio-coder-entry <path>]
 clio-coder eval run --task-file <tasks.yaml> [--repeat <n>] [--out <path>] [--clio-coder-entry <path>]
@@ -24,8 +27,9 @@ clio-coder eval inventory --json
 ```
 
 ### Command Roles
-* **`validate`**: Validates the structure and constraints of a Suite v2 YAML file without executing it.
-* **`run`**: Runs a Suite v2 (via `--suite`) or a compatibility v1 task file (via `--task-file`). Outputs a text summary and writes an eval artifact under `<dataDir>/evals/` and evidence under `<dataDir>/evidence/eval-<evalId>/`.
+* **`validate`**: Validates the structure and constraints of a Suite v2 YAML file (via `--suite`) or package evaluations (via `--package <path|kind:name> [--eval <name>]`) without executing them.
+* **`run`**: Runs a Suite v2 (via `--suite`), a compatibility v1 task file (via `--task-file`), or a packaged evaluation (via `--package <path|kind:name> [--eval <name>]`). Outputs a text summary and writes an eval artifact under `<dataDir>/evals/` and evidence under `<dataDir>/evidence/eval-<evalId>/`.
+* **`skill`**: Evaluates an individual skill directory or catalog entry against its baseline scenarios declared in `evals.md`.
 * **`report`**: Formats and prints a report from a saved `evalId`. Supports multiple `--format` outputs:
   * `text` (default): Human-readable stdout summary.
   * `json`: Raw JSON structure of the artifact.
@@ -41,7 +45,8 @@ Exit codes:
 | Command | Success | Failure |
 | --- | --- | --- |
 | `eval validate` | `0` when validation passes | `2` for validation issues |
-| `eval run` | `0` when all task repetitions pass | `1` when any task fails, `2` for invalid configs |
+| `eval run` | `0` when all task repetitions pass | `1` when any task/gate fails (including package evals), `2` for invalid configs or load errors |
+| `eval skill` | `0` when all scenarios pass | `1` for failures/regressions, `3` for unmeasured harness state or evidence errors, `2` for invalid arguments |
 | `eval report` | `0` when artifact loads | `1` if artifact cannot be read, `2` for invalid ID |
 | `eval compare` | `0` when both artifacts compare and the behavioral hard gate passes | `1` for a hard regression or unreadable artifact, `2` for invalid ID |
 | `eval gate` | `0` when correctness, safety, and hard threshold assertions pass | `1` for hard failures, unreadable inputs, and malformed threshold files; `2` for an invalid eval ID or usage error |

package/docs/process/performance-methodology.md

@@ -62,7 +62,7 @@ exit. This keeps diagnostic output from corrupting the temporary shell without
 changing the measured endpoints.
 
 ```bash
-CLIO_CODER_RENDER_TRACE=/tmp/clio-render.jsonl \
+CLIO_CODER_RENDER_TRACE=/tmp/clio-coder-render.jsonl \
 CLIO_CODER_TRACE_BOOT=1 \
 CLIO_CODER_INTERACTIVE=1 \
 node dist/cli/index.js

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

@@ -78,6 +78,10 @@ Run deterministic local checks on the candidate commit before requesting authori
    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

package/docs/process/scientific-validation.md

@@ -122,3 +122,26 @@ Clio Coder integrates scientific validation contracts directly into its safety m
 - **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 call `limitation` before it can conclude the turn.
+
+## Verification boundaries and limitation receipts
+
+File readback establishes artifact inspection, not executed scientific validation. When an agent or worker modifies files but cannot execute the outstanding checks with its admitted tools and approved scope:
+
+1. **The generic `limitation` tool**:
+   - Clio provides the pure canonical `limitation` tool (`src/tools/limitation.ts`), recording a `limitation` tool_call and tool_result receipt in the session ledger.
+   - Arguments:
+     - `scope` (required string): What could not be verified, in one sentence.
+     - `reason` (required enum): One of `no-runner`, `blocked`, `out-of-scope`, `environment`, or `other`.
+     - `paths` (optional array of strings): Repository-relative file paths left unverified.
+   - A prose disclaimer or text summary in conversation is not a limitation receipt; only a successful `limitation` tool call registers a typed receipt in the session ledger.
+
+2. **Recipe instructions vs generic harness**:
+   - Bundled scientific recipes (such as Materio research agents in `library/plugins/materio`) explicitly instruct workers via `<clio_verification_boundary>` in their recipe bodies to call `limitation` when external checks cannot run. This boundary instruction is authored recipe content, not an unconditional harness envelope injected into every worker.
+
+3. **Finish gate enforcement**:
+   - At high rigor (such as when a valid `validation.yaml` contract is present), the finish gate monitors workspace mutations within the recent active turn window (up to 80 entries since the last user message).
+   - 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`.
+

package/evals/scalar-decision-machinery.ts

@@ -24,7 +24,7 @@ if (!python) throw new Error("Pass an existing Python interpreter with NumPy; th
 const fixture = JSON.parse(readFileSync(new URL("./fixtures/scalar-decision.json", import.meta.url), "utf8"));
 const grader = fileURLToPath(new URL("./scalar-decision-grader.py", import.meta.url));
 const { restore } = await isolateClioEnv();
-const root = mkdtempSync(join(tmpdir(), "clio-scalar-decision-"));
+const root = mkdtempSync(join(tmpdir(), "clio-coder-scalar-decision-"));
 
 function grade(source: string, value: string) {
 	const policy = value === fixture.pythonPolicy ? "python-int" : value === fixture.numpyPolicy ? "numpy-integer" : null;

package/examples/extensions/README.md

@@ -0,0 +1,67 @@
+# Local scientific extensions
+
+These installable examples use the harness extension lifecycle, separately from
+library recipes. They require a Clio build containing operator runtime API v1.
+The manifests retain the current package compatibility minimum, 0.4.7; use this
+implementation or a later release that includes it (the original 0.4.7 release
+predates the runtime field).
+
+From the repository root:
+
+```bash
+clio-coder extensions discover examples/extensions/lab-status --json
+clio-coder extensions install examples/extensions/lab-status --project
+clio-coder extensions run lab-status dashboard
+clio-coder extensions run lab-status dashboard --json
+```
+
+In Clio, reload through `/extensions reload`, then invoke
+`/ext:lab-status:dashboard`. Core renders the panel, owns scrolling and Escape,
+and displays the status with the extension's owner label. The default record is
+`jobs.synthetic.json`: **SYNTHETIC FIXTURE**, two completed jobs and one running
+job. These are deterministic demonstration records, not measured cluster facts.
+
+Pass a local JSON record filename as the argument to inspect your own data:
+
+```bash
+clio-coder extensions run lab-status dashboard -- /absolute/path/experiment.json
+```
+
+The record has `experiment` and `jobs` fields. Each job supplies a string `id`,
+positive integer `ranks`, `state` (`queued`, `running`, `completed`, `failed`) and
+nonnegative finite `elapsedSeconds`. Set `synthetic: true` for simulated data.
+Records without that marker are labeled local reported data, not independently
+verified results. Files are regular local files up to 32 KiB and at most 100 jobs.
+The example performs no SSH, scheduler query, submission, provider request or
+credential access. Turn observations repeat the last explicit snapshot; invoke
+the dashboard again to refresh the file. Runtime state resets on reload.
+
+The separate measurement package keeps the existing model tool contract:
+
+```bash
+clio-coder extensions install examples/extensions/measurements --project
+```
+
+Start a new session. The admitted model tool is
+`extension_measurements__summarize`, with input such as
+`{"values":[1,2,3],"units":"seconds"}`. That input is a **synthetic deterministic
+example**, with mean 2 and sample standard deviation 1. A one-value input returns
+`null` for sample standard deviation. Numeric overflow errors instead of
+reporting null or invented valid measurements. Execution still passes the tool
+registry's safety, autonomy and approval rules. Native worker recipes must
+explicitly admit the qualified tool. Installing a runtime never adds tools to
+existing model schemas.
+
+Update source, reinstall with `--force`, then reload operator runtimes at idle.
+Disable and remove exact copies with `--project` or `--user`:
+
+```bash
+clio-coder extensions disable lab-status --project
+clio-coder extensions enable lab-status --project
+clio-coder extensions remove lab-status --project
+```
+
+Do not edit installed package bytes in place. Whole-tree digest drift revokes
+calls; mixed tool/UI packages need a new session even when only UI bytes change.
+Installed runtime code has your account's filesystem/network authority. A child
+process gives bounded teardown and fresh module caches, not an OS sandbox.

package/examples/extensions/lab-status/clio-coder-extension.json

@@ -0,0 +1,14 @@
+{
+	"id": "lab-status",
+	"name": "Local experiment status",
+	"version": "1.0.0",
+	"description": "Inspect a local experiment record; default data is explicitly synthetic.",
+	"compatibility": { "clio": ">=0.4.7" },
+	"runtime": {
+		"api": 1,
+		"entrypoint": "extension.mjs",
+		"commands": [{ "name": "dashboard", "description": "Show synthetic jobs or a named local JSON experiment file." }],
+		"events": ["session_open", "turn_end"],
+		"ui": ["status", "panel"]
+	}
+}

package/examples/extensions/lab-status/extension.mjs

@@ -0,0 +1,68 @@
+import { open } from "node:fs/promises";
+import path from "node:path";
+
+let lastStatus = { text: "Synthetic fixture available; invoke dashboard", tone: "neutral" };
+async function readRecord(file) {
+	const handle = await open(file, "r");
+	try {
+		const info = await handle.stat();
+		if (!info.isFile() || info.size > 32768) throw new Error("Expected a regular local JSON record, at most 32 KiB");
+		const buffer = Buffer.alloc(32769);
+		const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+		if (bytesRead > 32768) throw new Error("Experiment record exceeds 32 KiB");
+		const data = JSON.parse(buffer.subarray(0, bytesRead).toString("utf8"));
+		if (
+			typeof data.experiment !== "string" ||
+			data.experiment.length > 120 ||
+			!Array.isArray(data.jobs) ||
+			data.jobs.length > 100
+		)
+			throw new Error("Invalid experiment record");
+		for (const job of data.jobs) {
+			if (
+				typeof job.id !== "string" ||
+				job.id.length > 80 ||
+				!["queued", "running", "completed", "failed"].includes(job.state) ||
+				!Number.isInteger(job.ranks) ||
+				job.ranks < 1 ||
+				!Number.isFinite(job.elapsedSeconds) ||
+				job.elapsedSeconds < 0
+			)
+				throw new Error("Invalid job record");
+		}
+		return data;
+	} finally {
+		await handle.close();
+	}
+}
+/** @param {import('@iowarp/clio-coder/extensions').ExtensionApi} api */
+export default function extension(api) {
+	api.handle("dashboard", async (args, context) => {
+		const file = args.trim()
+			? path.resolve(context.snapshot.workspace, args.trim())
+			: new URL("./jobs.synthetic.json", import.meta.url);
+		const data = await readRecord(file);
+		context.signal.throwIfAborted();
+		const label = data.synthetic === true ? "SYNTHETIC FIXTURE" : "LOCAL RECORD (reported, not independently verified)";
+		const completed = data.jobs.filter((job) => job.state === "completed").length;
+		lastStatus = { text: `${label}: ${completed}/${data.jobs.length} completed`, tone: "neutral" };
+		const rows = data.jobs.map((job) => [job.id, String(job.ranks), job.state, String(job.elapsedSeconds)]);
+		return {
+			text: `${label}\n${data.experiment}\n${completed}/${data.jobs.length} completed\n${rows.map((row) => row.join(" | ")).join("\n")}\nSource: ${file}`,
+			status: lastStatus,
+			panel: {
+				title: data.experiment,
+				sections: [
+					{
+						kind: "text",
+						text: `${label}\nSource: ${file}\nThis extension reads records only. It never submits or queries cluster jobs.`,
+					},
+					{ kind: "metrics", items: [{ label: "Completed", value: `${completed}/${data.jobs.length}` }] },
+					{ kind: "table", columns: ["Job", "MPI ranks", "State", "Elapsed s"], rows },
+				],
+			},
+		};
+	});
+	api.on("session_open", () => ({ text: "", status: lastStatus }));
+	api.on("turn_end", () => ({ text: "", status: lastStatus }));
+}

package/examples/extensions/lab-status/jobs.synthetic.json

@@ -0,0 +1,9 @@
+{
+	"synthetic": true,
+	"experiment": "Synthetic stencil scaling fixture",
+	"jobs": [
+		{ "id": "fixture-1", "ranks": 8, "state": "completed", "elapsedSeconds": 42 },
+		{ "id": "fixture-2", "ranks": 16, "state": "completed", "elapsedSeconds": 24 },
+		{ "id": "fixture-3", "ranks": 32, "state": "running", "elapsedSeconds": 9 }
+	]
+}

package/examples/extensions/measurements/clio-coder-extension.json

@@ -0,0 +1,28 @@
+{
+	"id": "measurements",
+	"name": "Measurement summary",
+	"version": "1.0.0",
+	"description": "Count, mean, min, max and sample standard deviation of supplied finite measurements.",
+	"compatibility": { "clio": ">=0.4.7" },
+	"capabilities": {
+		"tools": [
+			{
+				"name": "summarize",
+				"description": "Summarize supplied measurements without inventing physical units or provenance.",
+				"runtime": "node",
+				"entrypoint": "summarize.cjs",
+				"timeoutMs": 10000,
+				"maxOutputBytes": 16384,
+				"inputSchema": {
+					"type": "object",
+					"properties": {
+						"values": { "type": "array", "items": { "type": "number" }, "minItems": 1, "maxItems": 1000 },
+						"units": { "type": "string", "maxLength": 40 }
+					},
+					"required": ["values"],
+					"additionalProperties": false
+				}
+			}
+		]
+	}
+}

package/examples/extensions/measurements/summarize.cjs

@@ -0,0 +1,23 @@
+const { values, units } = JSON.parse(process.argv[2]);
+if (!Array.isArray(values) || values.length < 1 || values.length > 1000 || !values.every(Number.isFinite))
+	throw new Error("Expected 1-1000 finite measurements");
+let mean = 0;
+let m2 = 0;
+for (const [index, value] of values.entries()) {
+	const delta = value - mean;
+	mean += delta / (index + 1);
+	m2 += delta * (value - mean);
+}
+if (!Number.isFinite(mean) || !Number.isFinite(m2))
+	throw new Error("Numerical overflow; rescale the supplied measurements");
+console.log(
+	JSON.stringify({
+		count: values.length,
+		mean,
+		min: Math.min(...values),
+		max: Math.max(...values),
+		sampleStandardDeviation: values.length > 1 ? Math.sqrt(m2 / (values.length - 1)) : null,
+		units: units ?? null,
+		source: "caller-supplied measurements; provenance not independently verified",
+	}),
+);

package/library/README.md

@@ -0,0 +1,109 @@
+# Clio Coder Library
+
+The Clio Coder library is the canonical home of shareable packages, contributor entry points, and the generated distribution index.
+
+## Package Kinds
+
+The library organizes shareable packages by kind into dedicated directories:
+
+| Kind | Directory | What an author shares | How it is used |
+| --- | --- | --- | --- |
+| **Skill** | `library/skills/` | A procedure and supporting knowledge for the agent | `/skill <skill-name>` |
+| **Agent** | `library/agents/` | A worker recipe: role, tools, budget, and result contract | `/run <agent-id> <task>` or dispatch |
+| **Prompt** | `library/prompts/` | Reusable task text and parameterized instructions | `/<derived-prompt-name> [arguments]` |
+| **Fleet** | `library/fleets/` | An executable multi-agent coordination recipe | `/fleet run <name>` or preview |
+| **Plugin** | `library/plugins/` | A cohesive bundle of resources released together | Inspect contents, invoke member recipes |
+
+## Browsing and Managing Packages
+
+```bash
+# Discover packages in the catalog
+clio-coder library list
+clio-coder library search <query>
+
+# Install packages
+clio-coder library install skill:<name> --project
+clio-coder library install plugin:materio --project
+
+# Inspect installed packages
+clio-coder library skills --all --json
+
+# Read every discovered recipe with its owner, origin and invocation
+clio-coder library recipes --json
+clio-coder library recipes <query> --kind agent
+```
+
+`library recipes` reads the same bounded, body-free inventory Clio reads through `context(scope="library")`, so the operator and the model agree about which recipes exist, who owns them, where they came from and how each one is actually invoked. Both are reads: installation, removal and activation stay operator actions through `library install` and `/library`, and `/skill <name>` stays the way a skill is activated.
+
+In an interactive session, `/library` opens the recipe browser.
+
+## Using These Packages From Another Agent
+
+The same sources are usable by Claude Code and Codex with no converted copy and no duplicated recipe body.
+
+```bash
+# Claude Code: the repository is a standard marketplace
+claude plugin marketplace add iowarp/clio-coder
+claude plugin install tdd@clio-coder
+
+# Codex: .agents/skills already links the canonical trees, so a session
+# started in a clone sees all 39 skills. For every repository:
+ln -s "$PWD/library/skills" ~/.agents/skills/clio-coder
+ln -s "$PWD/library/plugins/materio/skills" ~/.agents/skills/materio
+```
+
+`.claude-plugin/marketplace.json` is generated by `pnpm run library:pin` from the pinned packages in `registry.yaml` and verified by `pnpm run library:check`. It is never edited by hand.
+
+A package is published there only when a peer host would load a real skill surface from it and nothing it would default-scan into a native component. Agent-, prompt- and fleet-only packages, and packages that keep Clio recipes in a top-level `agents/` directory, stay valid first-class library packages with no peer-host projection; `library:pin` prints which ones and why. See [coding agent interoperability](../docs/guide/interop.md) for what each host actually loads.
+
+## Authoring Templates
+
+Working, valid authoring templates for all five package kinds live in `library/_authoring/templates/`:
+
+- `library/_authoring/templates/skill/`: Single skill package with house metadata, triggers, and evals.
+- `library/_authoring/templates/agent/`: Standalone agent recipe with strict v1 format, custom audience, and `skills: []`.
+- `library/_authoring/templates/prompt/`: Reusable prompt with path-derived invocation and argument placeholders.
+- `library/_authoring/templates/fleet/`: Multi-agent coordination contract with a valid DAG and documented prerequisites.
+- `library/_authoring/templates/plugin/`: Composite bundle demonstrating an agent binding a contained skill, prompts, and assets.
+
+Templates are authoring reference models; they live outside the five catalog kind roots and never enter `library/registry.yaml`.
+
+## Contributing Packages
+
+Every native installable package carries a portable `plugin.json` manifest.
+The optional `extensions["ai.iowarp.clio"]` metadata declares a Clio-specific
+kind, resource paths and components; conventional plugin packages can expose
+`skills/` without it. The key is metadata inside the interoperable manifest,
+and does not name a marketplace service or require a directory. Supported
+foreign plugin manifests enter through the separate reviewed import route.
+
+1. **Choose package kind**: Decide whether your contribution is a single-kind package (`skill`, `agent`, `prompt`, `fleet`) exposing exactly one public recipe, or a composite `plugin` bundle combining multiple resources.
+2. **Copy authoring template**: Copy from `library/_authoring/templates/<kind>/` into your authoring tree.
+3. **Author resources**:
+   - Single-kind packages expose exactly one public resource file under their resource root (`skills`, `agents`, `prompts`, or `fleets`).
+   - Place `README.md` at the package root, outside the resource root, so it is not discovered as a second recipe.
+   - Packages may carry explicitly invoked scripts (e.g. for offline evaluation or verification). Runtime tools and session hooks belong to the separate harness extension lifecycle.
+4. **Validate**:
+   ```bash
+   clio-coder library validate <package-path> --json
+   ```
+   Validates manifest schema, resource payloads, package reference markers, and loader compatibility in a read-only pass.
+5. **Pin and check**:
+   ```bash
+   pnpm run library:pin   # regenerates full-tree pins in library/registry.yaml
+   pnpm run library:check # verifies all package bytes against library/registry.yaml
+   ```
+   For curated skills under `library/skills/`, maintainers also run:
+   ```bash
+   pnpm run skills:pin    # updates normalized skill-body provenance in library/skills/registry.yaml
+   pnpm run skills:check  # verifies skill provenance records
+   ```
+   *Full-tree pins* cover every distributed byte for runtime package integrity; *normalized skill hashes* record advisory provenance for audited instructions.
+6. **Try in isolated project**:
+   ```bash
+   clio-coder library register <package-path> --project
+   clio-coder library install <kind>:<name> --project
+   ```
+7. **Submit a focused fork PR**: Push to your fork and submit a PR against `main`.
+
+Built-in agent recipes and baseline fleets remain product-owned under `src/domains/agents/builtins/` and `src/domains/agents/fleets/`.

package/library/_authoring/templates/agent/README.md

@@ -0,0 +1,28 @@
+# Benchmark Scout Agent Template
+
+This template demonstrates a valid standalone **agent** package for Clio Coder.
+
+## Package Structure
+
+```text
+benchmark-scout/
+  README.md                     # Documentation (outside resource root)
+  plugin.json                   # Portable manifest declaring kind: agent
+  agents/
+    benchmark-scout.md          # Agent recipe (strict v1 format)
+```
+
+> **Important**: Place `README.md` at the package root, never inside the `agents/` resource root. Single-kind packages expose exactly one public candidate in their declared resource directory.
+
+## Recipe Constraints
+
+- Must use version 1 schema (`version: 1`).
+- Standalone agents declare `skills: []` and cannot bind external package skills.
+- Must declare `audience: custom` (only built-in recipes can use other audiences).
+- Valid budget, tools (required and optional), capability class, category, and result contract.
+
+## Validation
+
+```bash
+clio-coder library validate .
+```