@iowarp/clio-coder 0.3.6 → 0.3.7

package/docs/proactive-memory.md

@@ -1,6 +1,6 @@
 # Proactive task memory
 
-> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.3.6).
+> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.3.7).
 
 Clio's proactive task memory protects long-running work from behavioral state
 decay: a requirement, environment fact, failed attempt, or diagnosis can still

package/docs/prompt-envelope-and-tools.md

@@ -1,7 +1,7 @@
 # Prompt Envelope and Tools
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/tools_blueprint.html](html/tools_blueprint.html) (Version: 0.3.6).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/tools_blueprint.html](html/tools_blueprint.html) (Version: 0.3.7).
 
 Clio Coder keeps the model-facing envelope stable and moves enforcement into the runtime registry and safety policy.
 

package/docs/provider-adapter-cookbook.md

@@ -1,7 +1,7 @@
 # Provider Adapter Cookbook
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive runtime adapter descriptor builder and probe sequence capability checklist is located at [docs/html/provider_adapter_blueprint.html](html/provider_adapter_blueprint.html) (Version: 0.3.6).
+> **Interactive Spec Available:** An interactive runtime adapter descriptor builder and probe sequence capability checklist is located at [docs/html/provider_adapter_blueprint.html](html/provider_adapter_blueprint.html) (Version: 0.3.7).
 
 This cookbook guides developers through implementing custom model runtimes and inference server integrations within Clio Coder. It explains the runtime descriptor interfaces, probing protocols, model synthesis, and how to configure reasoning and thinking behaviors.
 

package/docs/release-cut-checklist.md

@@ -1,6 +1,6 @@
-# v0.3.6 Release-Cut Checklist
+# v0.3.7 Release-Cut Checklist
 
-The ordered steps that turn the prepared `v0.3.6` branch into a published
+The ordered steps that turn the prepared `v0.3.7` branch into a published
 release. Everything above the line marked **AUTHORIZATION BOUNDARY** is
 repeatable and reversible and is run locally before the cut. Everything below
 it is external or irreversible and needs an explicit decision from the
@@ -11,14 +11,15 @@ state of every step.
 
 | Item | State |
 | --- | --- |
-| Branch | `v0.3.6`, local only; pushed with the explicit refspec `refs/heads/v0.3.6` when the operator decides, never as a bare name that a tag could shadow |
-| `package.json` version | `0.3.6`; the top `CHANGELOG.md` heading is `## 0.3.6 - 2026-08-23` |
-| `main` | `590fda7d`, which already carries the v0.3.5 content and the CI diet; it is an ancestor of `v0.3.6` and moves only at Part 4. |
-| `origin/main` | `590fda7d`, matching `main` with the v0.3.5 content and the CI diet |
-| Tags | none for 0.3.6, local or remote |
-| GitHub Release | none for 0.3.6 |
-| npm registry | `@iowarp/clio-coder@0.3.6` absent; `latest` is `0.3.4` |
-| npm history | `@iowarp/clio-coder` has published versions 0.3.0 through 0.3.4, with `latest` at 0.3.4. Version 0.3.5 was published and withdrawn, so `@iowarp/clio-coder@0.3.5` can never be reused. |
+| Branch | `v0.3.7`, pushed to `origin` under the explicit refspec `refs/heads/v0.3.7`; sixteen feature and docs commits, the version-bump commit, and the fix commits the interactive release testing produced, ahead of `main` |
+| `package.json` version | `0.3.7`; the top `CHANGELOG.md` heading is `## 0.3.7 - 2026-08-24` |
+| `main` | `9b54219d`, the v0.3.6 release SHA; it is an ancestor of `v0.3.7` and moves only at Part 4 |
+| `origin/main` | `9b54219d`, matching `main` |
+| Tags | `v0.3.6` exists on `9b54219d`; none for 0.3.7, local or remote |
+| GitHub Release | `v0.3.6` published 2026-08-24; none for 0.3.7 |
+| npm registry | `@iowarp/clio-coder@0.3.7` absent; `latest` is `0.3.6` |
+| npm history | Published versions 0.3.0 through 0.3.4 and 0.3.6. Version 0.3.5 was published and withdrawn and can never be reused. |
+| Milestone | `v0.3.7` holds the thirteen issues this branch closes (#155, #204, #206 through #216); the ten off-map items (#156, #158 through #164, #198, #199) moved to `v0.3.8` on 2026-08-24 |
 | Commit provenance identity | Post-release maintainer follow-up, not a gate: verifying `clio-coder@iowarp.ai` on IOWarp-controlled GitHub and GitLab identities (such as `clio-coder-bot` or `iowarp-clio`, with `assets/clio-coder-avatar-512.png` as the avatar) only changes how those platforms render the trailers. |
 
 ---
@@ -53,35 +54,50 @@ Run against the exact final candidate with `NO_COLOR` unset and
     `docs/html/`, `apps/workbench`, `.superpowers`, `tests/`, `scripts/`,
     `benchmarks/`, scratch files, and source maps are absent. Record the
     filename, packed and unpacked sizes, integrity, and shasum.
-12. Install that tarball into a clean temporary prefix with empty XDG roots and
-    verify `--version`, `--help`, an empty-state non-TTY launch, `doctor`, and
-    `uninstall --dry-run` without developer-local state.
+12. Install that tarball into a clean temporary prefix with an empty
+    `CLIO_CODER_HOME` and verify `--version`, `--help`, an empty-state non-TTY
+    launch, `doctor`, and `uninstall --dry-run` without developer-local state.
+13. Interactive release testing, which this cut added because the release is
+    almost entirely interactive surface: a tester agent drives the step-12
+    install through real TUI sessions in a throwaway repository, one session
+    per shipped feature, against local targets for the main session and a
+    cloud target for council members and advice, and writes a per-feature
+    PASS / FAIL / BLOCKED table with evidence. A FAIL on a deterministic
+    behavior (a refusal, a file, a receipt field, CLI output) blocks the cut;
+    a BLOCKED(model) on a model decision does not.
 
 ## Part 2: version and notes (repeatable)
 
-13. Files carrying a version reference, to update together if the number
-    changes: `package.json` and `package-lock.json`, the `## 0.3.6 - <date>`
-    heading in `CHANGELOG.md`, the `(Version: 0.3.6)` markers in `docs/*.md`,
-    the `Blueprint (v0.3.6)` titles in `docs/html/*.html`, the `--branch`
+14. Files carrying a version reference, to update together if the number
+    changes: `package.json` and `package-lock.json`, the `## 0.3.7 - <date>`
+    heading in `CHANGELOG.md`, the `(Version: 0.3.7)` markers in `docs/*.md`,
+    the `Blueprint (v0.3.7)` titles in `docs/html/*.html`, the `--branch`
     pin in the README install block (the hygiene lint checks it), and the
     measured-at figures in `scripts/check-release.mjs` if the package size
-    moved materially.
-14. Confirm the `## 0.3.6` section of `CHANGELOG.md` describes every
-    user-visible behavior change, including the ones that alter existing
-    behavior, and carries no Workbench release narrative. The release workflow
-    uses this section verbatim as the GitHub Release body.
-15. Re-run `npm run ci:release` after any version edit and commit as one
-    commit on `v0.3.6`.
+    moved materially. For 0.3.7 the tarball measured 6.5 MB packed and
+    37.9 MB unpacked, inside the 10 MB and 50 MB ceilings set for 0.3.6.
+15. Confirm the `## 0.3.7` section of `CHANGELOG.md` describes every
+    user-visible behavior change under `### Added`, and every change to an
+    existing behavior under `### Changed`, and carries no Workbench release
+    narrative. The release workflow uses this section verbatim as the GitHub
+    Release body.
+16. `docs/artifact-versions.md` lists every persisted artifact this release
+    added or re-versioned: run receipt integrity v19, fleet contract v5, the
+    fleet run record, the checkout writer lease, the out-of-turn usage ledger,
+    and the library pin file.
+17. Re-run `npm run ci:release` after any version edit and commit as one
+    commit on `v0.3.7`.
 
 ## Part 3: present the gate
 
-16. Report to the operator before touching `main`: the exact final `v0.3.6`
+18. Report to the operator before touching `main`: the exact final `v0.3.7`
     SHA and clean status, the commits added since the handoff SHA, the gate
-    commands with pass/fail totals for both Node majors, the package version
-    and changelog heading, the tarball audit, the clean-install results and any
-    deferred live check, confirmation that no tag, GitHub Release, or npm
-    version exists yet, the proposed commands for Parts 4 through 6, and the
-    proposed npm dist-tag. The dist-tag is the operator's call; never guess it.
+    commands with pass/fail totals, the package version and changelog heading,
+    the tarball audit, the clean-install results, the interactive test table,
+    and any deferred live check, confirmation that no tag, GitHub Release, or
+    npm version exists yet, the proposed commands for Parts 4 through 6, and
+    the npm dist-tag. The dist-tag is the operator's call; for 0.3.7 the
+    operator chose `latest` on 2026-08-24.
 
 ---
 
@@ -93,54 +109,53 @@ confirming the exact SHA and the commands.
 
 ## Part 4: fast-forward `main`
 
-17. `git fetch origin` immediately before integrating; require `origin/main`
-    to be an ancestor of the reviewed `v0.3.6` tip and confirm no other
+19. `git fetch origin` immediately before integrating; require `origin/main`
+    to be an ancestor of the reviewed `v0.3.7` tip and confirm no other
     worktree has `main` checked out.
-18. `git checkout main && git merge --ff-only v0.3.6`. No merge commit, no
+20. `git checkout main && git merge --ff-only v0.3.7`. No merge commit, no
     rebase, no reset. Verify `main` equals the reviewed SHA and is clean.
-19. `git fetch origin` once more; stop on any unexpected remote movement. Then
-    `git push origin main`. Never `--force` or `--force-with-lease`.
+21. `git fetch origin` once more; stop on any unexpected remote movement. Then
+    `git push origin main`. Never `--force` or `--force-with-lease`. The push
+    closes the thirteen milestone issues through their `Fixes` trailers.
 
 ## Part 5: exact-SHA CI, tag, GitHub Release
 
-20. The `main` push triggers the `ci` workflow. It is a useful signal but no
-    longer a gate on tagging, because `release.yml` runs the same gate on the
-    tagged tree itself. A red run still blocks the cut; investigate it rather
-    than tagging around it, and never silence a flake with an unrelated
-    change.
-21. Reconfirm that tag `v0.3.6` and the GitHub Release do not exist, then
-    `git tag -a v0.3.6 -m "Clio Coder 0.3.6"` on the green SHA and
-    `git push origin refs/tags/v0.3.6`.
-22. The tag push triggers `.github/workflows/release.yml`, which verifies the
+22. The `main` push triggers the `ci` workflow. It is a useful signal but not
+    a gate on tagging, because `release.yml` runs the same gate on the tagged
+    tree itself. A red run still blocks the cut; investigate it rather than
+    tagging around it, and never silence a flake with an unrelated change.
+23. Reconfirm that tag `v0.3.7` and the GitHub Release do not exist, then
+    `git tag -a v0.3.7 -m "Clio Coder 0.3.7"` on the green SHA and
+    `git push origin refs/tags/v0.3.7`.
+24. The tag push triggers `.github/workflows/release.yml`, which verifies the
     tag matches `package.json`, runs `npm run ci:release` on the tagged tree,
-    extracts the `## 0.3.6` section of `CHANGELOG.md` as the release body, and
-    attaches the tarball.
-    Do not create a release by hand. Verify the run's SHA, the notes, the
-    attached tarball, and the URL.
+    extracts the `## 0.3.7` section of `CHANGELOG.md` as the release body, and
+    attaches the tarball. Do not create a release by hand. Verify the run's
+    SHA, the notes, the attached tarball, and the URL.
 
 ## Part 6: npm publication (irreversible)
 
-23. `npm whoami` and confirm the registry and account; reconfirm
-    `@iowarp/clio-coder@0.3.6` is still absent.
-24. Obtain the operator's explicit dist-tag decision. `latest` makes this the
-    default install for every user; `--tag next` keeps `0.3.4` as the default.
-25. Run `npm publish` (or `npm publish --tag next`) once. `prepublishOnly`
-    re-runs `ci:release` as a safety net; it is not a substitute for Part 1.
-26. A published version cannot be replaced. `npm unpublish` is restricted and
+25. `npm whoami` and confirm the registry and account; reconfirm
+    `@iowarp/clio-coder@0.3.7` is still absent.
+26. Obtain the operator's explicit dist-tag decision. `latest` makes this the
+    default install for every user; `--tag next` keeps `0.3.6` as the default.
+27. Run `npm publish` once. `prepublishOnly` re-runs `ci:release` as a safety
+    net; it is not a substitute for Part 1.
+28. A published version cannot be replaced. `npm unpublish` is restricted and
     time-limited; a mistake is corrected by publishing a higher version.
 
 ## Part 7: post-publish verification and follow-ups
 
-27. `npm view @iowarp/clio-coder@0.3.6` and the selected dist-tag.
-28. On a clean machine, `npm install -g @iowarp/clio-coder` from the registry
+29. `npm view @iowarp/clio-coder@0.3.7` and the selected dist-tag.
+30. On a clean machine, `npm install -g @iowarp/clio-coder` from the registry
     rather than from a local tarball, then repeat step 12 against it, plus
     `configure` to a real target and one real turn when one is authorized.
     This is the only step that tests what users actually receive.
-29. From an installation of 0.3.4, verify `clio-coder upgrade` finds and
-    applies 0.3.6.
-30. Record the SHA, CI URL, tag, GitHub Release URL, npm version and dist-tag,
+31. From an installation of 0.3.6, verify `clio-coder upgrade` finds and
+    applies 0.3.7.
+32. Record the SHA, CI URL, tag, GitHub Release URL, npm version and dist-tag,
     tarball evidence, and the post-publish verification in the release report.
-31. Maintainer follow-up, independent of the release: verify the commit
+33. Maintainer follow-up, independent of the release: verify the commit
     provenance email `clio-coder@iowarp.ai` on IOWarp-controlled GitHub and
     GitLab identities such as `clio-coder-bot` or `iowarp-clio`, and upload
     `assets/clio-coder-avatar-512.png` as the account avatar where PNG is
@@ -153,7 +168,7 @@ confirming the exact SHA and the commands.
 
 ## Rollback
 
-There is no rollback for step 25. Before it, every step is reversible: steps
-21 and 22 by deleting the local and remote tag and the draft release, steps 17
-through 19 by a new forward commit on `main` (never by rewriting it), and
+There is no rollback for step 27. Before it, every step is reversible: steps
+23 and 24 by deleting the local and remote tag and the draft release, steps 19
+through 21 by a new forward commit on `main` (never by rewriting it), and
 everything in Parts 1 and 2 by `git checkout`.

package/docs/resource-library.md

@@ -0,0 +1,59 @@
+# Resource Library
+
+The resource library extends the existing local skills marketplace catalog to carry agent recipes, prompt templates, and fleet contracts. It does not change the Agent Skills format, discovery roots, trust gating, or existing skill installation sources.
+
+## Catalog schema
+
+A catalog is a JSON or YAML list, or an object whose `skills` property contains the list. The historical property name remains accepted so every existing skill marketplace index works unchanged.
+
+```yaml
+skills:
+  - kind: fleet
+    name: release
+    description: Build and verify a release.
+    sourceUrl: ./fleets/release.md
+    requires:
+      - agent:release-builder
+      - skill:ship
+```
+
+`kind` accepts `skill`, `agent`, `prompt`, or `fleet` and defaults to `skill`. `requires` accepts typed references with those same four prefixes. Clio resolves requirements recursively across the selected catalog and the private catalog. Missing, malformed, and cyclic requirements are refused with stable `library_requirement_*` diagnostics. A requirement is satisfied when its typed reference exists in `<configDir>/library-pins.yaml` or its kind-specific destination exists. Add output lists satisfied and unsatisfied requirements separately. Requirements are reported without installation unless `library add` receives `--with-requirements`. That flag installs only the unsatisfied dependencies in dependency order before the requested entry.
+
+## Private catalog and remote gating
+
+`library.catalog` selects a private catalog and defaults to `<configDir>/library.yaml`. Relative sources in that file resolve beside the catalog. `library.remote` records an optional git remote URL. `library.sync` defaults to false, and no git process is started while it remains false.
+
+The private catalog repository must name its git remote `library`. Clio checks it with `git remote get-url library`. Run `clio-coder library remote confirm <url>` once after reviewing the configured URL. When `library.remote` is unset, confirmation records the URL as both the configured and confirmed remote. A confirmation that differs from an existing `library.remote` refuses with `library_remote_mismatch`. A missing confirmation or a later settings change refuses synchronization and publishing with `library_remote_unconfirmed`.
+
+When `library.sync` is false, both `library sync` and `library push` refuse with `library_sync_disabled` before any process starts. When synchronization is enabled, `library sync` runs `git fetch library` followed by `git merge --ff-only FETCH_HEAD`, and `library push` runs `git push library`. Both commands execute git as an argument vector without a shell.
+
+## CLI
+
+```text
+clio-coder library list [--kind k] [--json]
+clio-coder library search <query> [--kind k] [--json]
+clio-coder library add <ref> [--from <catalog|path>] [--with-requirements] [--yes] [--json]
+clio-coder library use <kind> <name>
+clio-coder library push
+clio-coder library sync
+clio-coder library remote confirm <url>
+```
+
+`library add` prints every destination and SHA-256 hash before it writes. It writes nothing until `--yes` is present. `library use` prints the invocation to paste into the relevant surface.
+
+## In the TUI
+
+The Skills Hub carries one tab per kind. `/library <kind>` opens it on that kind's tab and `/library` alone opens it on Skills, which is also where `/skill` opens. Each tab lists the entries this same discovery finds, with the requirements an entry still needs named in the warning token. Installing from a row runs the same plan-then-write pair `library add` runs, behind a confirmation that states every destination and hash and writes nothing when it is cancelled, and an entry with unresolved requirements is refused by name before an install-with-requirements confirmation offers to write them all. `Enter` on an installed row leads where that kind is invoked from: the composer for an agent, a prompt, or a skill, and the `/fleet run` approval preview for a fleet. See [skills-marketplace.md](skills-marketplace.md) for the key table.
+
+## Installation roots and validation
+
+| Kind | User installation root | Validation before write |
+| --- | --- | --- |
+| skill | `<configDir>/skills/<name>/SKILL.md` | Existing skill loader and installer |
+| agent | `<configDir>/agents/<name>.md` | Agent recipe schema and policy |
+| prompt | `<configDir>/prompts/<name>.md` | Prompt template loader |
+| fleet | `<configDir>/fleets/<name>.md` | Fleet contract parser |
+
+Every installed item records a kind-qualified hash in `<configDir>/library-pins.yaml`. Agent recipes become visible through `clio-coder agents`. User fleet contracts participate between built-in and project fleet precedence, so a project contract still wins. Prompts use the existing user prompt root.
+
+Share archives may carry agent and fleet entries. Import always validates these formats before writing, and fleet entries land in the user fleet root.

package/docs/safety-model.md

@@ -1,7 +1,7 @@
 # Clio Coder Safety Model
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/safety_blueprint.html](html/safety_blueprint.html) (Version: 0.3.6).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/safety_blueprint.html](html/safety_blueprint.html) (Version: 0.3.7).
 
 Clio Coder's safety posture is code-enforced, not prompt-only. As the orchestrator coding agent in the [IOWarp](https://iowarp.ai) ecosystem developed by the [Gnosis Research Center](https://grc.iit.edu) at Illinois Tech under NSF Award [#2411318](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2411318), Clio gates execution by target capabilities, the tool registry, the safety policy engine, project policies, protected-artifact checks, and audit receipts.
 
@@ -13,7 +13,7 @@ Source of truth: `src/domains/safety/**`, `src/tools/registry.ts`, `src/tools/bo
 
 The `autonomy` setting (`read-only` | `suggest` | `auto-edit` | `full-auto`) is an enforced dial. It controls exactly one thing: which action classes run immediately, which park for operator approval, and which are auto-denied. The safety net (damage-control rules, path policy, protected artifacts, loop guard, dispatch scope admission) is independent of the dial and identical at every level. When a `[safety-net]` notice appears at full-auto, that is the always-on net working as designed, not a contradiction of the level.
 
-In Clio Coder v0.3.6, effective autonomy resolution is strictly centralized in `src/entry/orchestrator.ts` through `resolveEffectiveAutonomy` and `resolveBaselineAutonomy`. Every admission surface (tool registry admission, dispatch plan provenance, and ACP session snapshots) delegates to this pair of functions so that fallback paths cannot diverge across execution contexts. `resolveBaselineAutonomy` evaluates dispatch settings overrides, headless CLI options, and configuration settings before applying the default `auto-edit` level. `resolveEffectiveAutonomy` combines any active ACP session autonomy level with the baseline resolution.
+In Clio Coder v0.3.7, effective autonomy resolution is strictly centralized in `src/entry/orchestrator.ts` through `resolveEffectiveAutonomy` and `resolveBaselineAutonomy`. Every admission surface (tool registry admission, dispatch plan provenance, and ACP session snapshots) delegates to this pair of functions so that fallback paths cannot diverge across execution contexts. `resolveBaselineAutonomy` evaluates dispatch settings overrides, headless CLI options, and configuration settings before applying the default `auto-edit` level. `resolveEffectiveAutonomy` combines any active ACP session autonomy level with the baseline resolution.
 
 ### Autonomy levels
 

package/docs/scientific-validation.md

@@ -1,11 +1,11 @@
 # 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.6).
+> **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.7).
 
 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.6, the session rigor resolver does not parse or enforce a scientific contract schema. The presence of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md` at the workspace root raises the default rigor level to `high`; the file contents are advisory material for developers, project agents, and external validators.
+Clio Coder recognizes **scientific validation contract files** as an opt-in signal for a higher evidence bar. In v0.3.7, 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.
 
@@ -95,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.6:
+The following labels are useful project conventions for validation contracts and reports. They are not a closed, core-enforced enum in v0.3.7:
 
 - **`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.6`.
+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.7`.
 
 Source implementations: `src/engine/session.ts` and `src/domains/session/`.
 
@@ -127,6 +127,42 @@ The `/fork` command (`src/domains/session/tree/fork.ts:forkFromParentTurn`) init
 3. Traces ancestry up to `parentTurnId` and copies exactly the active path entries (excluding later unanchored sidecars) into the new session ledger.
 4. Stamps `parentSession` and `parentTurnId` in the new session header.
 
+### Handoff (`/handoff <goal>`)
+
+`/handoff` mints a successor session seeded with a reviewed document describing
+what the current session settled. It is a session operation and only that: it
+writes no memory promotion candidate, touches no memory record, and never calls
+the task-memory bank.
+
+The rule that makes the document trustworthy is read-ledger validation. Clio folds
+this session's persisted `read`, `edit`, `write`, `ls`, `find`, `grep`, and
+`artifact` tool calls (plus its `fileEntry` records) into a set of
+workspace-relative paths, through `filterEntriesToActivePath` so an abandoned
+`/tree` branch contributes nothing, exactly as the task board folds its own inputs.
+Every path the extraction round names is checked against that set and never against
+the filesystem. A file that exists on disk but that this session never opened is
+still an invention, so it is dropped and listed in the review document under
+`dropped (not in this session's read ledger)`.
+
+Extracted decisions merge with the session's settled decision board
+(`src/domains/session/decision-board.ts`); board entries win on conflict and are
+marked as settled. Superseded board decisions are history and do not travel.
+
+On accept, the new session opens with one `custom` entry of type `handoffSeed`
+carrying the reviewed document, the originating session id, and the goal. It
+projects into the model's replay as one user-role context message labelled as a
+handoff from the named session, on the same seam compaction and branch summaries
+use; it is never written as a fabricated user turn. The old session's
+`skillActivation` entries are replayed into the new session so loaded skills carry
+forward. The old session gains exactly one `custom` entry of type `handoffNote`
+recording the target session id, and is otherwise untouched. Esc during review
+cancels the whole handoff with nothing written in either session.
+
+The extraction round itself runs on the out-of-turn seam `/btw` uses: one call
+against the session's live target and model, the compiled message history as
+read-only input, no tools, and no entry in the ledger. Its provider usage is
+reported to `/cost` under a handoffs row and excluded from the turn count.
+
 ### Streaming Turn Settlement During Session Transitions
 
 When an operator issues `/new`, `/resume`, `/tree`, or `/fork` while an assistant turn is actively streaming, `settleChatBeforeSessionSwitch` (`src/interactive/session-switch-settlement.ts`) cancels the in-flight stream and awaits completion. This guarantees that partial assistant records and completed tool executions seal cleanly into the active session ledger before the session writer is replaced, preventing orphaned records in new sessions or unanswered prompts in original sessions (#114). Synchronous session transitions when chat is idle continue to execute immediately.

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.6).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/skills_blueprint.html](html/skills_blueprint.html) (Version: 0.3.7).
 
 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.
 
@@ -28,18 +28,31 @@ skills/ catalog.
 
 The CLI reports the same state as `no local skill marketplace catalog or index configured`. A marketplace source that exists but fails (an unreadable index, a broken catalog package) is a diagnostic row in the hub, not a silent omission.
 
+The same index machinery can also describe agent recipes, prompt templates, and fleet contracts through typed entries and requirements. See [resource-library.md](resource-library.md) for the schema, private catalog, installation roots, and `clio-coder library` commands. Those kinds render on their own tabs in the hub, described below.
+
 ## Using the hub
 
 | Key | Action |
 |---|---|
 | type | Filter all groups |
-| `Enter` | Insert `/skill <name> ` into the editor for the task text |
+| `←`/`→` | Switch tabs |
+| `Enter` | Use the selected row: insert `/skill <name> ` into the editor for the task text, or the invocation the row's kind is called by |
 | `Tab` | Toggle the detail pane (split layout on wide terminals) |
-| `i` | Install the selected marketplace skill into the project scope through the local marketplace resolver |
+| `i` | Install the selected row through the resolver its kind installs by |
 | `PgUp`/`PgDn` | Scroll the detail pane |
 
 Invoking an uninstalled marketplace skill with `/skill <name>` prompts before installing it. `i` runs the same install path eagerly from the hub.
 
+## Tabs
+
+The hub carries one tab per resource library kind: Skills, Agents, Prompts, and Fleets. `←` and `→` move between them, which is the key vocabulary the Settings Center already uses to move between sections. The frame title names the active tab and the footer states its row count, so the numbers on screen always describe the tab being read. `/skill` opens the hub on Skills. `/library <kind>` opens it on that kind's tab, and `/library` alone opens it on Skills.
+
+The Skills tab is unchanged. The other three list the entries of their kind from `discoverLibrary()`, which is the same discovery `clio-coder library list --kind <kind>` reads, so the hub and the CLI never disagree about what exists. Each row carries the entry's origin and version, whether it is installed or available, the short form of its recorded pin hash, and, in the warning token, the names of any requirements it still needs. An entry the catalog refuses outright, because a requirement is missing, malformed, or cyclic, appears as a diagnostic row rather than being omitted.
+
+`Enter` uses the selected row. An agent inserts `/run <agent> ` into the composer, a prompt inserts its `/<id> ` invocation, a skill does what the Skills tab does, and a fleet closes the hub and opens the `/fleet run` approval preview for that contract. A row that is not installed says so instead and points at `i`.
+
+`i` installs, through the same plan-then-write pair `clio-coder library add` runs. A framed confirmation states every destination path and SHA-256 hash before anything is written, which is the TUI spelling of the CLI's `--yes` gate; `Esc` there leaves every destination untouched. An entry whose requirements are not all installed is refused by name on the first `i`, and a second `i` opens the install-with-requirements confirmation, which names every entry it would write in dependency order.
+
 The CLI `clio-coder skills` commands manage local skill discovery, validation, and
 creation. Extension resource roots and share archives are documented in
 [extensions-and-sharing.md](extensions-and-sharing.md); this page owns the TUI

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.6).
+> **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.7).
 
 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.6, `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.7, `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
 
@@ -234,8 +234,13 @@ Dispatches one or more tasks to Clio fleet agents and returns per-run receipt su
 Arguments:
 
 - `task` (required for the singular form unless `list:true`). One worker assignment/instruction string. It is distinct from briefing.
-- `tasks` (required for the batch form unless `list:true`). Array of task strings or `{task, agent, target, model, cwd, briefing}` objects. Per-item fields override the top-level defaults below. Supplying both `task` and `tasks` is an error.
-- `mode` (optional). `parallel` (default) runs items concurrently; `sequential` runs them one at a time, each completing before the next dispatches. A single task always runs down the sequential path.
+- `tasks` (required for the batch form unless `list:true`). Array of task strings or `{task, agent, target, model, cwd, briefing, intent, gate}` objects. Per-item fields override the top-level defaults below. Supplying both `task` and `tasks` is an error.
+- `mode` (optional). `parallel` (default) runs items concurrently; `sequential` runs them one at a time, each completing before the next dispatches. `pipeline`, `compete`, and `council` select their named topologies. A single ordinary task always runs down the sequential path.
+- `roster` (council only). Names one `workers.rosters` entry. Supply exactly one of `roster` or `members`.
+- `members` (council only). Supplies two to five inline `{label,target,model?,thinking?}` entries.
+- `synthesis` (council only). Accepts `none`, `judge`, or `vote`; the default is `none`.
+- `rounds` (council only). Accepts an integer from 1 through 3; the default is 1.
+- `judge` (council only with judge synthesis, or compete). Accepts optional `agent`, `model`, `target`, and `node` route fields.
 - `detach` (optional boolean). For parallel fan-out, returns the durable batch id and assignment ids after registration while the shared event consumer continues in the background. An assignment id equals its first attempt's run id. This is the parent model's route to mid-run monitor/steer; ordinary synchronous, sequential, and pipeline calls auto-wait for each assignment's terminal attempt.
 - `list` (optional boolean). Returns the agent catalog instead of dispatching.
 - `agent` (optional). Default agent recipe for items that do not name one; default `coder`. `agent_id` is accepted as an alias inside items.
@@ -248,13 +253,15 @@ Arguments:
 - `cwd` (optional). Default agent working directory.
 - `timeout_ms` (optional). Aborts the whole dispatch; in sequential mode remaining tasks are skipped and the skip is reported.
 - `briefing` (optional string, top-level default or per-task override). Parent-composed context/data, not worker instructions: it cannot replace `task`. It is trimmed and omitted when blank, rejected above 12,000 UTF-8 bytes, sent as its own delimited untrusted dynamic message, and retained only as byte/hash provenance. The shared value applies to string tasks and object tasks without an override; an object-level briefing wins.
+- `intent` (optional object, top-level default or per-task override). Declares `read_roots`, `write_roots`, `relevant_paths`, `expected_outputs`, and `verification`. Path arrays contain normalized repository-relative POSIX paths. Verification entries contain a declared `check` id and optional `timeout_ms`; ids are resolved from package scripts and `.clio-coder/verifiers.yaml` before approval. Checks are ids, not shell commands.
+- `gate` (optional string, top-level default or per-task override). Exact shorthand for `intent.verification=[{check: gate}]`. Supplying it together with `intent.verification` is refused.
 - `max_output_bytes` (optional). Summary byte budget; default 20000, split across runs with at least 1024 bytes each.
 
 Argument tolerance: `tasks` sent as a JSON string is parsed and a single object or bare string is wrapped into an array. The top-level singular `task` is first-class. Briefing-only calls fail with guidance that briefing is context and cannot replace a task.
 
 Output is one batch-shaped summary even for a single task: a header `dispatch (<mode>) total=N failed=M`, the assignment id list, then one terminal-attempt receipt line per assignment (run id, agent, exit code, target, model, tokens, receipt path, verification state, failure message if any) followed by the worker's final assistant text. `details = {mode, assignmentIds, receiptCount, failedCount, runs[]}`, and each `runs[]` entry carries distinct `assignmentId` and terminal `runId` fields plus the structured `verification` state and `receiptIntegrity` result. There is no `runIds` compatibility alias. Any terminal attempt with a nonzero exit turns the whole result into an error carrying the same summary. A run that succeeded without a single successful tool call carries a `note=` marker; do not treat such a run as validated work.
 
-The summary separates four things that must never be conflated: `receipt_integrity=verified/v15/sha256` comes only from verification against the ledger; `evidence_verification=<state>/<basis>` describes validation evidence; `briefing=bytes:<n> sha256:<hash>` authenticates parent-supplied data; and `project_context=...` authenticates the independently rendered bounded project message. A tampered receipt renders a head-anchored `RECEIPT INTEGRITY FAILED` banner. A read-only Scout can have verified integrity with `not_applicable/read-only-agent` evidence. Missing briefing is `briefing=none`, never a project-context hash.
+The summary separates five things that must never be conflated: `receipt_integrity=verified/v19/sha256` comes only from verification against the ledger; `host_verification=<status>` describes orchestrator-executed declared checks; `evidence_verification=<state>/<basis>` describes worker-tool validation evidence; `briefing=bytes:<n> sha256:<hash>` authenticates parent-supplied data; and `project_context=...` authenticates the independently rendered bounded project message. A tampered receipt renders a head-anchored `RECEIPT INTEGRITY FAILED` banner. A read-only Scout can have verified integrity with `not_applicable/read-only-agent` evidence. Missing briefing is `briefing=none`, never a project-context hash.
 
 Exit zero is insufficient without a durable deliverable. A successful native or ACP run must seal a nonempty `output.state="final"`. Otherwise it fails with `worker_final_output_missing`; any unfinished text remains partial diagnostics and automatic retry is suppressed. Live tool-use preambles never replace a missing receipt answer.
 
@@ -262,11 +269,11 @@ Sealed receipts are the durable evidence; worker prose remains advisory until ve
 
 ```text
 dispatch(list=true)
-dispatch(agent="debugger", task="Adversarially verify the strict v15 receipt boundary", briefing="Prior receipt R1 cited receipt-integrity.ts and left these claims unresolved", detach=true)
+dispatch(agent="debugger", task="Adversarially verify the strict v19 receipt boundary", briefing="Prior receipt R1 cited receipt-integrity.ts and left these claims unresolved", detach=true)
 dispatch(tasks=["Run the contract tests in tests/contracts/dispatch.test.ts and report each failure with its assertion"])
 dispatch(tasks=[
   {agent: "researcher", task: "Map every caller of finalizeObservation and summarize the envelope shapes"},
-  {agent: "coder", task: "Fix the failing assertion in tests/contracts/safety.test.ts; run verify(check=\"test\") before finishing"}
+  {agent: "coder", task: "Fix the failing assertion in tests/contracts/safety.test.ts", intent: {write_roots: ["tests/contracts"], verification: [{check: "test"}]}}
 ], mode="parallel")
 dispatch(tasks=["Refactor step 1", "Refactor step 2"], mode="sequential", timeout_ms=600000)
 ```

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.6).
+> **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.7).
 
 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.6`.
+This guide provides concrete, actionable remediation procedures for operational errors, permission denials, target connection failures, and system diagnostics in Clio Coder `v0.3.7`.
 
 ---
 

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.6).
+> **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.7).
 
 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.6).
+> **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.7).
 
 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.
 
@@ -207,11 +207,11 @@ The coordinator classifies failures into 13 explicit categories (`src/domains/di
 
 ### 5.2 Canonical Receipt Integrity Serialization
 
-Receipts carry exactly one integrity version (`RUN_RECEIPT_INTEGRITY_VERSION = 15`); any other version is invalid. It computes a cryptographic SHA-256 digest over a strictly sorted, canonical JSON representation (`serializeCanonical` in `src/domains/dispatch/receipt-integrity.ts`).
+Receipts carry exactly one integrity version (`RUN_RECEIPT_INTEGRITY_VERSION = 19`); any other version is invalid. It computes a cryptographic SHA-256 digest over a strictly sorted, canonical JSON representation (`serializeCanonical` in `src/domains/dispatch/receipt-integrity.ts`).
 
 - **Object Key Sorting**: Keys are sorted lexicographically before serialization (`Object.keys(obj).sort()`).
 - **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`.
+- **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/council provenance, briefing, steering, task worktree application, and `outcomeCode`.
 
 Integrity is only the artifact-integrity axis of the canonical trust status.
 The other axes are validation grounding, independent review, context

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@iowarp/clio-coder",
-	"version": "0.3.6",
+	"version": "0.3.7",
 	"description": "Coding agent for HPC and scientific-software developers, part of IOWarp's CLIO ecosystem of agentic science.",
 	"keywords": [
 		"ai",

package/src/cli/fleet-commands.ts

@@ -0,0 +1,37 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { discoverDeclaredProjectCommands } from "../tools/verify/authoring.js";
+
+function quoted(value: string): string {
+	return JSON.stringify(value);
+}
+
+export function runFleetCommands(args: ReadonlyArray<string>): number {
+	if (args.length !== 1 || args[0] !== "init") {
+		process.stderr.write("clio-coder fleet: commands: usage: clio-coder fleet commands init\n");
+		return 2;
+	}
+	const destination = join(process.cwd(), ".clio-coder", "fleets", "commands.yaml");
+	if (existsSync(destination)) {
+		process.stderr.write(`clio-coder fleet: commands init: destination already exists: ${destination}\n`);
+		return 2;
+	}
+	const entries = discoverDeclaredProjectCommands(process.cwd());
+	const lines = [
+		"# Draft fleet command registry.",
+		"# Every entry was discovered from a project declaration. Uncommenting an entry confirms its exact invocation.",
+		"# version: 1",
+		"# commands:",
+	];
+	for (const entry of entries) {
+		lines.push(
+			`#   ${entry.id}:`,
+			`#     argv: [${entry.command.map(quoted).join(", ")}]`,
+			`#     description: ${quoted(`Discovered from ${entry.provenance.path}: ${entry.provenance.detail}`)}`,
+		);
+	}
+	mkdirSync(dirname(destination), { recursive: true });
+	writeFileSync(destination, `${lines.join("\n")}\n`, { flag: "wx" });
+	process.stdout.write(`${destination}\n`);
+	return 0;
+}