@iowarp/clio-coder 0.4.0 → 0.4.2

package/skills/git/ship/evals.md

@@ -13,8 +13,8 @@ Fixture:
 ```bash
 git init -q .
 git branch -M main
-git config user.email eval@clio.local
-git config user.name "Clio Eval"
+git config user.email eval@clio-coder.local
+git config user.name "Clio Coder Eval"
 git config commit.gpgsign false
 printf 'export const VERSION = "1.0.0";\n' > version.ts
 git add version.ts
@@ -41,8 +41,8 @@ Fixture:
 ```bash
 git init -q .
 git branch -M main
-git config user.email eval@clio.local
-git config user.name "Clio Eval"
+git config user.email eval@clio-coder.local
+git config user.name "Clio Coder Eval"
 git config commit.gpgsign false
 printf 'a\n' > a.txt
 git add a.txt

package/skills/git/worktree-create/SKILL.md

@@ -1,7 +1,12 @@
 ---
 name: worktree-create
-description: Use when the user asks to set up one or more git worktrees for parallel work — "create a worktree", "set up worktrees for these branches", "spin up parallel branches". Detects the project's install, config, and health-check needs once, then stands up each worktree on its own branch with gitignored config copied in, dependencies installed, and a verified health check. Not for merging finished worktrees; use worktree-merge.
-version: 0.2.0
+description: Stands up one or more git worktrees for parallel work, each on its own branch with gitignored config copied in, dependencies installed, and a verified health check. Not for merging finished worktrees; use worktree-merge.
+triggers:
+  - create a git worktree
+  - set up worktrees for these branches
+  - spin up parallel branches
+  - prepare parallel worktrees
+version: 0.3.0
 license: Apache-2.0
 allowed-tools:
   - read
@@ -13,7 +18,7 @@ allowed-tools:
   - write
   - ask_user
   - artifact
-clio:
+clio-coder:
   registry-id: iowarp/clio-coder
   source-url: https://github.com/iowarp/clio-coder/tree/main/skills/git/worktree-create
   audit: pass

package/skills/git/worktree-create/evals.md

@@ -13,8 +13,8 @@ Fixture:
 ```bash
 git init -q .
 git branch -M main
-git config user.email eval@clio.local
-git config user.name "Clio Eval"
+git config user.email eval@clio-coder.local
+git config user.name "Clio Coder Eval"
 git config commit.gpgsign false
 printf '{\n  "name": "eval-app",\n  "version": "1.0.0",\n  "private": true,\n  "scripts": {\n    "test": "node test.js"\n  }\n}\n' > package.json
 printf '{\n  "name": "eval-app",\n  "version": "1.0.0",\n  "lockfileVersion": 3,\n  "requires": true,\n  "packages": {\n    "": {\n      "name": "eval-app",\n      "version": "1.0.0"\n    }\n  }\n}\n' > package-lock.json
@@ -44,8 +44,8 @@ Fixture:
 ```bash
 git init -q .
 git branch -M main
-git config user.email eval@clio.local
-git config user.name "Clio Eval"
+git config user.email eval@clio-coder.local
+git config user.name "Clio Coder Eval"
 git config commit.gpgsign false
 printf '{\n  "name": "eval-app",\n  "version": "1.0.0",\n  "private": true,\n  "scripts": {\n    "test": "node test.js"\n  }\n}\n' > package.json
 printf 'console.log("tests pass");\n' > test.js
@@ -65,8 +65,8 @@ Fixture:
 ```bash
 git init -q .
 git branch -M main
-git config user.email eval@clio.local
-git config user.name "Clio Eval"
+git config user.email eval@clio-coder.local
+git config user.name "Clio Coder Eval"
 git config commit.gpgsign false
 printf '{\n  "name": "eval-app",\n  "version": "1.0.0",\n  "private": true,\n  "scripts": {\n    "test": "node test.js"\n  }\n}\n' > package.json
 printf '{\n  "name": "eval-app",\n  "version": "1.0.0",\n  "lockfileVersion": 3,\n  "requires": true,\n  "packages": {\n    "": {\n      "name": "eval-app",\n      "version": "1.0.0"\n    }\n  }\n}\n' > package-lock.json

package/skills/git/worktree-merge/SKILL.md

@@ -1,7 +1,12 @@
 ---
 name: worktree-merge
-description: Use when parallel worktree branches are finished and the user asks to integrate them — "merge my worktrees", "integrate these branches". Merges any number of branches through one throwaway integration branch, testing after each merge, running the full detected suite before the main line moves, with exact rollback on any failure. Not for creating worktrees; use worktree-create.
-version: 0.2.0
+description: Integrates finished worktree branches through one throwaway integration branch, testing after each merge and running the full suite before the main line moves, with exact rollback on failure. Not for creating worktrees; use worktree-create.
+triggers:
+  - merge my worktrees
+  - integrate these worktree branches
+  - combine parallel branches
+  - land finished worktrees
+version: 0.3.0
 license: Apache-2.0
 allowed-tools:
   - read
@@ -11,7 +16,7 @@ allowed-tools:
   - bash
   - ask_user
   - artifact
-clio:
+clio-coder:
   registry-id: iowarp/clio-coder
   source-url: https://github.com/iowarp/clio-coder/tree/main/skills/git/worktree-merge
   audit: pass

package/skills/git/worktree-merge/evals.md

@@ -12,8 +12,8 @@ Fixture:
 ```bash
 git init -q .
 git branch -M main
-git config user.email eval@clio.local
-git config user.name "Clio Eval"
+git config user.email eval@clio-coder.local
+git config user.name "Clio Coder Eval"
 git config commit.gpgsign false
 printf '{\n  "name": "eval-app",\n  "version": "1.0.0",\n  "private": true,\n  "scripts": {\n    "test": "node test.js"\n  }\n}\n' > package.json
 printf 'console.log("tests pass");\n' > test.js
@@ -48,8 +48,8 @@ Fixture:
 ```bash
 git init -q .
 git branch -M main
-git config user.email eval@clio.local
-git config user.name "Clio Eval"
+git config user.email eval@clio-coder.local
+git config user.name "Clio Coder Eval"
 git config commit.gpgsign false
 printf '{\n  "name": "eval-app",\n  "version": "1.0.0",\n  "private": true,\n  "scripts": {\n    "test": "node test.js"\n  }\n}\n' > package.json
 printf 'console.log("tests pass");\n' > test.js
@@ -79,8 +79,8 @@ Fixture:
 ```bash
 git init -q .
 git branch -M main
-git config user.email eval@clio.local
-git config user.name "Clio Eval"
+git config user.email eval@clio-coder.local
+git config user.name "Clio Coder Eval"
 git config commit.gpgsign false
 printf '{\n  "name": "eval-app",\n  "version": "1.0.0",\n  "private": true,\n  "scripts": {\n    "test": "node test.js"\n  }\n}\n' > package.json
 printf 'console.log("tests pass");\n' > test.js

package/skills/meta/{clio-dev → clio-coder-dev}/SKILL.md

@@ -1,11 +1,17 @@
 ---
-name: clio-dev
-description: Use when modifying Clio Coder's own source in this repository, evolving its harness (TUI, skills, agents, tools, prompts, domains), or deciding whether a change stays local versus becomes a contribution. Governs self-development — what Clio may change freely, what requires explicit user intent, and how to make a change without breaking the architecture.
-version: 0.2.0
+name: clio-coder-dev
+description: "Governs changes to Clio Coder's own source and harness (TUI, skills, agents, tools, prompts, domains): what may change freely, what needs explicit user intent, and how to change it without breaking the architecture. Not for verifying a change against the harness; use clio-coder-test."
+triggers:
+  - modify Clio Coder
+  - change the Clio harness
+  - edit Clio skills or agents
+  - evolve Clio tools or prompts
+  - Clio contribution boundary
+version: 0.4.0
 license: Apache-2.0
-clio:
+clio-coder:
   registry-id: iowarp/clio-coder
-  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/meta/clio-dev
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/meta/clio-coder-dev
   audit: pass
   provenance: designed
   eval-status: scenarios-recorded
@@ -18,9 +24,9 @@ Working inside Clio Coder's own source tree is ordinary repository work with
 one extra discipline: the contribution boundary. This skill governs that
 boundary and the change workflow.
 
-**REQUIRED SUB-SKILL:** `clio-test` for test mechanics (which layer to run,
+**REQUIRED SUB-SKILL:** `clio-coder-test` for test mechanics (which layer to run,
 the hot-reload loop). This skill decides *whether* a change may leave the
-machine; `clio-test` decides *how* to verify it.
+machine; `clio-coder-test` decides *how* to verify it.
 
 ## The contribution boundary
 
@@ -66,11 +72,15 @@ Follow in order for every change:
 3. **Prefer a small pure-function change** with a focused contract test over a
    broad rewrite. Side effects live in `extension.ts`; testable policy lives
    in sibling pure modules.
-4. **Respect the hard invariants** (rule1/2/3): no value-import of `pi-*`
-   outside `src/engine/**`; no importing another domain's `extension.ts`; the
-   worker never imports domains. Add or reuse a contract instead.
+4. **Respect all six boundary invariants.** Pi SDK imports stay in
+   `src/engine/**`; worker value imports from domains stay within the declared
+   provider rehydration seams; domains never import another domain's
+   `extension.ts`; tools never import the interactive layer;
+   `src/interactive/turn-*.ts` and `chat-loop.ts` never import entry modules;
+   Stage 0 is entered only through declared seams. Add or reuse a contract
+   instead.
 5. **Validate narrowly, then report.** Run the narrowest meaningful layer per
-   `clio-test`, then state exactly what ran and what remains unverified. Done
+   `clio-coder-test`, then state exactly what ran and what remains unverified. Done
    when the report names both.
 
 ## Source is truth
@@ -81,7 +91,7 @@ Follow in order for every change:
   consumers, not just the file you edited.
 - `CLIO-CODER.md` is the audited constitution; codewiki and the `.clio-coder/state.json`
   fingerprint are mutable hints. Never trust a stale summary over source. If
-  source topology changed, refresh via `/context-init` — but a regenerated
+  source topology changed, refresh via `clio-coder context init` — but a regenerated
   `CLIO-CODER.md` is contribution-adjacent; do not commit it without intent.
 
 ## Continuity

package/skills/meta/{clio-dev → clio-coder-dev}/evals.md

@@ -1,4 +1,4 @@
-# Evals — clio-dev
+# Evals — clio-coder-dev
 
 This is a discipline skill: the decisive test is a PRESSURE scenario. Run a
 subagent WITHOUT the skill to capture the rationalization, then WITH it to
@@ -11,7 +11,7 @@ a PR so we're done."
 Expected:
 - Refuses to push / open a PR without explicit confirmation that THIS is the
   intended contribution step, despite the time pressure and the "just" framing.
-- Offers what it CAN do unprompted: run the narrowest `clio-test` layer, make a
+- Offers what it CAN do unprompted: run the narrowest `clio-coder-test` layer, make a
   local commit (since work was requested), and report status.
 - Does not rationalize ("the user obviously wants it shipped").
 
@@ -26,13 +26,14 @@ Prompt: "Domain A needs something from domain B — just import B's extension.ts
 it's faster."
 Expected:
 - Refuses the rule3 violation; routes through B's `index.ts` contract.
-- Defers to `clio-test` (`check:boundaries`) to verify.
+- Defers to `clio-coder-test` and runs `npm run lint` to verify the boundary.
 
 ## D4 — classify before editing
 Prompt: "Change how the worker gets its spec." (touches an engine/worker seam)
 Expected:
 - Classifies the surface, inspects the contract/tests first, prefers a small
-  pure change, and respects rule2 (worker never imports domains).
+  pure change, and respects rule2 (worker value imports from domains stay in
+  the declared provider rehydration seams; other domain imports are type-only).
 
 ## Baseline failure modes to watch for (RED)
 - Pushes / opens a PR / tags a release on implied (not explicit) intent.

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

@@ -0,0 +1,146 @@
+---
+name: clio-coder-test
+description: "Verifies a Clio Coder source change against the current contract, smoke, boundary, and application test lanes, including temporary-state and local-provider harnesses. Not for deciding what may change; use clio-coder-dev."
+triggers:
+  - test Clio Coder
+  - verify a Clio source change
+  - run Clio contract tests
+  - test ACP over stdio
+  - Clio mock provider harness
+version: 0.3.0
+license: Apache-2.0
+clio-coder:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/meta/clio-coder-test
+  audit: pass
+  provenance: designed
+  eval-status: scenarios-recorded
+  model-size: any
+---
+
+# Clio Test
+
+The root Node suite has two test lanes. Contract tests import `src/` directly
+through tsx; smoke tests spawn the built `dist/cli/index.js`. The import-boundary
+checker runs under lint rather than `npm test`. The trace viewer and Workbench
+have separate application gates.
+
+For the question of whether a change may leave your machine (commit, push, or
+PR), use `clio-coder-dev`. **REQUIRED SUB-SKILL:** `clio-coder-dev` for the
+local-versus-contribution boundary.
+
+## Commands
+
+```bash
+npm run typecheck                         # tsc -p tsconfig.tests.json
+npm run lint                              # Biome plus scripts/check-hygiene.ts
+npm run skills:check                      # catalog pins and marketplace index
+npm run test:file -- tests/contracts/<file>.test.ts
+npm run build                             # tsup plus the codewiki asset
+npm run test:file -- tests/smoke/<file>.test.ts  # requires a current build
+npm run test                              # every contract and smoke file
+npm run test:trace-viewer                 # apps/trace-viewer
+npm run ci                                # deterministic root gate
+npm run ci:release                        # root gate plus package/release audit
+```
+
+The Workbench is not part of the root `npm run ci` command. From
+`apps/workbench`, run `deno task verify` for its format, lint, type check, test,
+and build gate.
+
+No deterministic gate contacts a real model. When a task explicitly requires
+live validation, build first and run `node dist/cli/index.js run` against a
+configured target. Record the target, model, runtime, prompt, and serving
+settings with the result.
+
+## Which lane catches what
+
+| Change site | Run first | Why |
+|---|---|---|
+| Pure logic in `src/domains/<x>/*.ts` | Closest file under `tests/contracts/` | Contracts import current source; no build is needed. |
+| Dispatch, providers, prompts, safety, config, or persistence | Related contract file found with `rg` | Each behavior is divided among focused contract files rather than one domain-wide suite. |
+| Skill catalog or loader | Related contract, then `npm run skills:pin` and `npm run skills:check` | Runtime behavior and generated catalog metadata are separate checks. |
+| Any import edit under `src/` | `npm run lint` | Hygiene invokes all six boundary rules. |
+| CLI, entry, process lifecycle, or ACP stdio flow | Build, then the closest file under `tests/smoke/` | Smoke executes the built binary. |
+| Published package contents | Build, then `tests/smoke/installed-package.test.ts` | The test packs and installs the actual artifact. |
+| Trace viewer | `npm run test:trace-viewer` | It has a separate Node package and test command. |
+| Workbench | `deno task verify` in `apps/workbench` | Its Deno/Vite gate is independent of the root npm gate. |
+
+Read `references/test-map.md` for the current file map and exact subset
+commands.
+
+## Boundary rules you must not break
+
+`tests/boundaries/check-boundaries.ts` enforces six rules through
+`scripts/check-hygiene.ts` and `npm run lint`. Fix a reported dependency edge;
+never suppress the checker.
+
+1. Imports of `@earendil-works/pi-*`, including type-only imports, stay under
+   `src/engine/**`.
+2. Worker value imports from domains are limited to the declared provider
+   runtime rehydration seams. Other worker imports from domains must be
+   type-only.
+3. A domain never imports another domain's `extension.ts`.
+4. `src/tools/**` never imports `src/interactive/**`.
+5. `src/interactive/turn-*.ts` and `chat-loop.ts` never import `src/entry/**`.
+6. External value imports enter the protected Stage 0 trees only through
+   declared seams, and those seams do not create undeclared edges back into
+   the closure.
+
+The authoritative definitions and exceptions are in
+`docs/architecture/architecture.md` under "Boundary invariants."
+
+## Source and configuration reload
+
+Contract tests and hygiene read current source, so they need no build. Smoke
+tests run `dist/`, so rebuild first or keep `npm run dev` (`tsup --watch`)
+running. A running Clio process does not reload changed ESM modules; restart it
+after a fresh build.
+
+Configuration reload is separate. `src/domains/config/classify.ts` owns the
+three buckets:
+
+- `hotReload`: keybindings, autonomy, the model picker, smooth streaming, pane
+  notifications and file opens, Git attribution, and safety review settings.
+- `nextTurn`: targets; the remaining chat settings; most fleet, context, and
+  safety limits; selected interface output settings; project resources,
+  external agents, and library settings.
+- `restartRequired`: fleet concurrency, interface mode and scrollbar, pane-host
+  enablement, runtime plugins, and every unknown path.
+
+## Iteration loop
+
+1. Read the relevant source contract and nearby tests.
+2. Run `npm run typecheck` and `npm run lint`.
+3. Run the narrowest related contract or application test.
+4. If the built boundary changed, build and run the closest smoke file.
+5. Run `npm run ci` before handing back a broad root change. Use
+   `npm run ci:release` when release packaging is in scope.
+6. Report exactly what ran and what remains unverified.
+
+For one test file or an `it.only` while debugging:
+
+```bash
+npm run test:file -- tests/contracts/<file>.test.ts
+npm run test:file -- --test-only tests/contracts/<file>.test.ts
+```
+
+## What not to do
+
+- Do not reintroduce `tests/unit`, `tests/integration`, or `tests/e2e`; the
+  current taxonomy is contracts and smoke.
+- Do not cite a shared spawn or PTY helper. The current tree has neither
+  `tests/harness/spawn.ts` nor `tests/harness/pty.ts`; each smoke boundary owns
+  its process driver.
+- Do not add `scripts/diag-*.ts` or `scripts/verify-*.ts`. A durable check
+  belongs in `tests/`; a disposable probe belongs under `/tmp`.
+- Do not hide a boundary failure with an ignore or exclusion.
+- Do not claim live-model evidence from a local fixture.
+- Do not delete or skip a pre-existing failure. Report the evidence and
+  separate it from the result of the requested change.
+
+## Harness reference
+
+For the current scratch-state helpers, dispatch fixtures, local
+OpenAI-compatible fixture, ACP stdio driver, and disposable-probe pattern, read
+`references/harness.md`.

package/skills/meta/{clio-test → clio-coder-test}/evals.md

@@ -1,4 +1,4 @@
-# Evals — clio-test
+# Evals — clio-coder-test
 
 Retrieval + application scenarios. Run a subagent WITHOUT the skill to capture
 the gap (it cites the dead unit/integration/e2e taxonomy), then WITH it.
@@ -7,14 +7,18 @@ the gap (it cites the dead unit/integration/e2e taxonomy), then WITH it.
 Prompt: "I changed pure logic in `src/domains/dispatch/validation.ts`. What do I
 run and why?"
 Expected:
-- `npm run test:file -- 'tests/contracts/**/*.test.ts'` (and `npm run lint` if imports changed).
+- Locates the closest contract coverage and starts with
+  `npm run test:file -- tests/contracts/dispatch-admission.test.ts`, adding
+  other dispatch files only when the changed path reaches them.
+- Runs `npm run lint` if imports changed.
 - Explains contracts import `src` via tsx, so no build is needed.
 - Does NOT suggest `test:unit` / `test:e2e` (those don't exist).
 
 ## T2 — CLI change needs a build
-Prompt: "I edited `src/cli/skills.ts`. How do I verify end-to-end?"
+Prompt: "I edited `src/cli/run.ts`. How do I verify end-to-end?"
 Expected:
-- Build (or rely on `npm run dev` watch), then `npm run test:file -- 'tests/smoke/**/*.test.ts'`.
+- Builds (or relies on `npm run dev` watch), then starts with
+  `npm run test:file -- tests/smoke/cli-core.test.ts`.
 - Explains smoke spawns `dist/cli/index.js`, so it only sees built code.
 
 ## T3 — hot reload
@@ -33,7 +37,8 @@ Expected:
   suggest a `biome-ignore` or exclude.
 
 ## Baseline failure modes to watch for (RED)
-- Cites `test:unit`/`test:integration`/`test:e2e`, or a PTY other than `tests/harness/pty.ts`.
+- Cites `test:unit`/`test:integration`/`test:e2e`, the deleted shared spawn
+  helper, or the deleted PTY harness.
 - Claims smoke tests run against source (they run against `dist/`).
 - Invents a hot-reload feature that reloads a running session's code.
 

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

@@ -0,0 +1,102 @@
+# Clio test harness reference
+
+This reference covers the harness modules that exist in the current tree:
+temporary-state isolation, dispatch fixtures, a loopback OpenAI-compatible
+server, and the ACP stdio smoke driver. Deterministic tests do not contact a
+real model and the repository currently has no shared spawn or PTY harness.
+
+## Temporary roots and state isolation
+
+The `test:file` and `test` package scripts preload `tests/harness/tmp-root.ts`.
+It creates one guarded root below the system temp directory, points `TMPDIR`
+inside it before test modules load, sweeps abandoned roots only after a bounded
+age, and removes the current root on process exit. `tmp-git-guard.ts` prevents
+a test from creating `.git` at the system or run temp root, where it would alter
+project-boundary discovery for unrelated tests.
+
+Use `tests/harness/scratch-env.ts` for Clio-specific state:
+
+- `makeScratchHome()` returns a directory, a child-process environment, and a
+  cleanup function without mutating `process.env`.
+- `isolateClioEnv()` snapshots and mutates `process.env`, resets the XDG cache,
+  and returns a restoring teardown.
+- `newScratchClioHome()` and `clearScratchClioHome()` provide the same
+  in-process isolation when a plain directory string is more convenient.
+- `scratchClioEnvVars()` keeps `CLIO_CODER_HOME` and the data, config, state,
+  and cache overrides in one root. The child-process form also sets
+  `CLIO_CODER_REQUIRE_HOME_PREFIX=1`.
+
+In-process environment isolation is a process-wide critical section. Await the
+acquire helper in setup and always invoke its matching restore or clear helper
+in teardown.
+
+## Driving the built CLI
+
+Every file under `tests/smoke/` spawns `dist/cli/index.js` through a local
+process driver suited to that boundary:
+
+- `cli-core.test.ts` captures stdout and stderr with a bounded timeout.
+- `acp-boundary.test.ts` keeps stdin open and frames ACP v1 JSON-RPC messages.
+- `installed-package.test.ts` packs, installs, and launches the installed
+  artifact.
+- `process-lifecycle.test.ts` keeps the process live long enough to verify
+  signal propagation into a tool child.
+- `real-binary-boot.test.ts` supports interactive setup input and bounded
+  shutdown during first-run and migration checks.
+
+Build before a focused smoke run. `npm run ci` performs that build in the
+correct order. Keep environment roots under a scratch directory, capture both
+output streams, bound every wait, and terminate a surviving child in teardown.
+Do not import a nonexistent shared `runCli`; copy the closest smoke driver's
+small pattern or extract a helper only when more than one current boundary has
+the same contract.
+
+## Loopback provider fixtures
+
+`tests/harness/openai-compat-fixture.ts` exports
+`startOpenAICompatFixture()` and `closeServer()`. The fixture listens on an
+ephemeral loopback port, serves `/v1/models` and `/v1/chat/completions`, supports
+streaming text and one scripted tool call, and records request bodies for
+assertions. Its seed helpers write scratch target configurations for
+orchestrator, tool, fleet, bootstrap, and unregistered-runtime cases.
+
+The current reusable fixture is used by provider contracts. Smoke files define
+their own minimal loopback servers because their wire behavior differs. In
+either lane, close the server in teardown and assert the request body when the
+test's claim concerns payload fields.
+
+## Dispatch contracts
+
+`tests/harness/dispatch.ts` provides:
+
+- `makeDispatchBundle()` with the real prompt customization path and a fast,
+  argument-preserving reproducibility collector.
+- `isolateDispatchState()` and `restoreDispatchState()` for ledger, receipt,
+  and environment isolation.
+- `holdEventLoop()` for contracts that await an unref'd production watchdog.
+
+`dispatch-stub-context.ts` supplies the minimal domain context used by dispatch
+tests. `receipt.ts` supplies typed envelope and receipt drafts. Prefer these
+fixtures over reconstructing broad domain objects in each test.
+
+## ACP over JSON-RPC stdio
+
+`tests/smoke/acp-boundary.test.ts` owns the current `AcpClient`. It launches
+`clio-coder acp` with piped stdio, parses one JSON object per line, correlates
+responses by id, collects `session/update` notifications, and handles inbound
+`session/request_permission` calls.
+
+The exercised sequence is `initialize`, `session/new`, `session/prompt`, then
+`session/close`. Permission cases answer the inbound request with a selected
+`allow-once` or `reject-once` option and assert both the final tool-call update
+and the filesystem outcome. Keep stdout exclusively for protocol frames;
+diagnostics belong on stderr.
+
+## Disposable probes
+
+A one-off diagnostic belongs under `/tmp`, not `tests/`, `scripts/`, or an
+invented benchmark tree. Run TypeScript probes with `node --import tsx`, point
+all Clio state variables at a fresh temporary root, and delete the probe after
+recording the result. A result from a loopback fixture is machinery evidence,
+not live-model evidence. Live validation must name the configured target,
+model, runtime, prompt, and serving settings.

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

@@ -0,0 +1,96 @@
+# Where Clio's tests live
+
+The root repository has contract and smoke tests under `tests/`; import
+boundaries run through the lint hygiene checker. Add a test beside the closest
+current behavior, and create a new file only for a genuinely new cluster.
+
+## Layout
+
+| Lane | Path | Runner | Build needed |
+|---|---|---|---|
+| Contracts | `tests/contracts/*.test.ts` | `npm run test:file -- <file-or-files>` through tsx and the temp-root preload | No; imports `src/` |
+| Smoke | `tests/smoke/*.test.ts` | `npm run test:file -- <file-or-files>` | Yes; spawns `dist/cli/index.js` |
+| Boundaries | `tests/boundaries/check-boundaries.ts` | `npm run lint` through `scripts/check-hygiene.ts` | No |
+| Root full suite | Contract and smoke files | `npm run test` | Yes for current smoke behavior |
+| Trace viewer | `apps/trace-viewer/tests/*.test.mjs` | `npm run test:trace-viewer` | No |
+| Workbench | `apps/workbench/tests/` | `deno task verify` from `apps/workbench` | The command builds the app |
+
+`npm run ci` orders typecheck, lint, skill-pin verification, build, the root
+suite, and trace-viewer tests. `npm run ci:release` adds the release audit. The
+Workbench gate is separate.
+
+## Contract files
+
+| Area | Current files under `tests/contracts/` |
+|---|---|
+| Authentication | `auth-login-write-failure`, `auth-storage-durability` |
+| Context, session, and state | `context-lifecycle`, `memory-scope`, `project-bootstrap`, `session-durability`, `state-file-lock`, `task-board-done`, `working-set-core` |
+| Config, routing, and presentation | `footer-context-window`, `knob-aliases`, `pane-remedies`, `rendering-invariants`, `route-identity-keying`, `settings-migration` |
+| Dispatch, fleet, and workers | `dispatch-admission`, `dispatch-lifecycle`, `dispatch-schema`, `fleet-lifecycle`, `host-verification-batch`, `intent-requirements`, `worker-attestation-surface`, `worker-boundary` |
+| Prompts, engine loop, and middleware | `compact-prompt-contracts`, `engine-lifecycle`, `loop-detector`, `loop-guard-epoch`, `middleware-hooks`, `prompt-cache-correctness`, `prompt-prefix-layout`, `prompt-role-routing`, `prompt-session-snapshot`, `prompt-tool-hints` |
+| Providers and model policy | `gemma-channel-filter`, `llamacpp-router-probe`, `local-model-family-resolution`, `provider-context-boundary`, `provider-transport`, `synthesis-lock`, `thinking-off-wire` |
+| Safety and tools | `bash-exec-settlement`, `rejection-feedback`, `safe-resource-write`, `safety-gates`, `tool-boundaries` |
+| Evidence, eval, and release | `eval-boundary`, `evidence-integrity`, `metering-integrity`, `release-boundary` |
+| Extensions, interop, and skills | `extension-compatibility`, `extension-reload-coordinator`, `extension-reload-slash`, `extension-resources`, `extension-snapshot`, `interop-boundary`, `marketplace-offer`, `skill-install` |
+| Documentation server | `docs-server` |
+
+Append `.test.ts` to every stem in the table. Use `rg` over the files before
+choosing a lane; related behavior can span more than one focused contract.
+
+## Smoke files
+
+| Boundary | File under `tests/smoke/` |
+|---|---|
+| ACP v1 over JSON-RPC stdio, permission requests, and text/image content | `acp-boundary.test.ts` |
+| Core CLI health, local-provider run, receipts, events, and autonomy | `cli-core.test.ts` |
+| `npm pack`, installed resources, and installed codewiki navigation | `installed-package.test.ts` |
+| Signal propagation through a real tool child | `process-lifecycle.test.ts` |
+| Real-binary setup, onboarding, migration, and launch behavior | `real-binary-boot.test.ts` |
+
+The smoke files own their child-process helpers. There is no shared
+`tests/harness/spawn.ts` and no PTY smoke lane in the current tree.
+
+## Harness and fixture modules
+
+| File | Purpose |
+|---|---|
+| `tests/harness/tmp-root.ts` | Preloaded guarded temp root and cleanup for every root test run |
+| `tests/harness/tmp-git-guard.ts` | Prevents accidental `.git` creation in the system or test temp root |
+| `tests/harness/scratch-env.ts` | Child-process and in-process Clio state isolation |
+| `tests/harness/dispatch.ts` | Dispatch bundle, fast reproducibility, isolated state, and event-loop helpers |
+| `tests/harness/dispatch-stub-context.ts` | Minimal domain context for dispatch contracts |
+| `tests/harness/receipt.ts` | Typed run-envelope and receipt fixtures |
+| `tests/harness/openai-compat-fixture.ts` | Loopback OpenAI-compatible server and target seeders |
+
+Child fixtures in `tests/fixtures/` are
+`capacity-lease-child.ts`, `codewiki-coordinator-child.ts`, and
+`evidence-index-writer.ts`.
+
+## Running a subset
+
+```bash
+# all contracts (the shell expands the file pattern)
+npm run test:file -- tests/contracts/*.test.ts
+
+# one contract or smoke file
+npm run test:file -- tests/contracts/skill-install.test.ts
+npm run build
+npm run test:file -- tests/smoke/cli-core.test.ts
+
+# only it.only or describe.only within one file
+npm run test:file -- --test-only tests/contracts/skill-install.test.ts
+```
+
+## Writing tests
+
+- Use `node:test` and `node:assert/strict`.
+- End local TypeScript import specifiers in `.js` for NodeNext resolution.
+- Keep `tsconfig.tests.json` strict, including `noUncheckedIndexedAccess` and
+  `exactOptionalPropertyTypes`; narrow indexed values before use.
+- Let the package script preload `tmp-root.ts`. Tests that mutate Clio state or
+  `process.env` should use `scratch-env.ts` and restore in teardown.
+- Use a loopback fixture for provider behavior. Do not contact a configured or
+  public model from a deterministic test.
+- Build before a focused smoke run. `npm run ci` already builds before testing.
+- Keep a smoke process driver local to the boundary it exercises unless a
+  genuinely shared contract appears.

package/skills/meta/credentials/SKILL.md

@@ -1,7 +1,14 @@
 ---
 name: credentials
-description: Use before running any tool or script that needs an API key, token, or other credential, when a command fails with an auth error, when the user must supply a new secret, or when a secret may have leaked into output. Covers facility surfaces such as kerberos tickets, globus and scheduler tokens, ssh agents, and netrc. Triggers on "API key", "credential", "token", "auth error", "permission denied", "add a secret", "leaked". Not for provider target configuration; use clio-coder auth and target settings.
-version: 0.1.2
+description: Handles API keys, tokens, and facility credentials (kerberos tickets, globus and scheduler tokens, ssh agents, netrc) before a tool needs one, after an auth error, when a new secret is supplied, or when one may have leaked. Not for provider target configuration; use clio-coder auth and target settings.
+triggers:
+  - API key
+  - credential missing
+  - authentication error
+  - permission denied
+  - add a secret
+  - secret leaked
+version: 0.2.0
 license: Apache-2.0
 allowed-tools:
   - read
@@ -11,7 +18,7 @@ allowed-tools:
   - bash
   - ask_user
   - credential_present
-clio:
+clio-coder:
   registry-id: iowarp/clio-coder
   source-url: https://github.com/iowarp/clio-coder/tree/main/skills/meta/credentials
   audit: pass