@iowarp/clio-coder 0.5.1 → 0.5.2

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

@@ -1,13 +1,12 @@
 ---
 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."
+description: "Validate Clio Coder changes using focused source regressions, built CLI and ACP fixtures, skill/library checks, and isolated package or GUI gates. Use when developing or diagnosing Clio itself; select checks from the changed behavior and report evidence without claiming unrun coverage."
 triggers:
-  - test Clio Coder
-  - verify a Clio source change
-  - run Clio contract tests
-  - test ACP over stdio
-  - Clio mock provider harness
-version: 0.3.1
+  - validate a Clio change
+  - test Clio context compaction or memory
+  - verify Clio skill activation
+  - choose Clio test gates
+version: 0.4.0
 license: Apache-2.0
 clio-coder:
   registry-id: iowarp/clio-coder
@@ -18,138 +17,86 @@ clio-coder:
   model-size: any
 ---
 
-# Clio Test
-
-The root Node suite has a small required contract/process lane, an installed-package
-qualification lane, and explicit extended development regressions. Contract tests
-import source through tsx; CLI tests use the current built binary. Lint owns static
-import boundaries and library pins. Publication performs only an exact-candidate
-preflight after successful qualification.
-
-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                              # required contracts and three process smoke files
-npm run test:full                         # explicit extended root investigation
-npm run test:gui:full                     # explicit extended web investigation
-pnpm --filter @iowarp/clio-coder-gui verify # app types, lint, tests, build, browser
-npm run ci                                # deterministic root gate
-npm run ci:release                        # qualify clean committed source and exact installed tarball
-npm run release:preflight                 # fast check of the unchanged qualified package
-```
-
-The required web tests cover authentication, permissions, cancellation, worker RPC,
-egress and process ownership. The installed-package lane includes one real browser
-boot/reconnect against the installed server. The full web `verify` command is an
-explicit development investigation, including its viewport/accessibility matrix.
-Do not run full development tests repeatedly during release or publication.
-
-The separate trace viewer and the earlier workbench client are both retired. Use
-`test:gui` for the required app tests alone; app `verify` requires headless Chrome.
-
-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. |
-| Unified web application | `npm run test:gui` | Required authentication/runtime boundaries; full `verify` is optional development work. |
-
-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` (`scripts/build.ts --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` on the clean committed candidate when packaging is in scope.
-   It records the exact source/artifact; use only `release:preflight` afterward.
-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`.
+# Clio validation
+
+Choose tests from the changed behavior and the code actually executed. The
+canonical skill name is `clio-coder-test`. This
+skill is independently usable: do not recursively load `clio-coder-dev`. Consult
+it when implementation or repository coordination becomes part of the task.
+
+## Start with an evidence plan
+
+Read the diff, relevant source/tests, `CONTRIBUTING.md`, and current package
+scripts. Identify the claim, the failure boundary, and the smallest test that
+can distinguish correct behavior. Existing tests may mix source imports with a
+built CLI subprocess: inspect the test before deciding a build is unnecessary.
+
+For a bug, reproduce it or explain why it cannot be reproduced. Add a behavioral
+regression at the owning boundary when warranted. Assert externally meaningful
+state, provider payload, persistence, filesystem outcome, or event ordering;
+a mock-call assertion alone rarely proves the claimed fix. Do not add tests that
+merely match wording for a reversible prose edit.
+
+## Select the lane
+
+| Changed behavior | First useful checks |
+| --- | --- |
+| Pure policy or domain behavior | Closest `tests/contracts/` or `tests/extended/` file through `pnpm run test:file -- <file>` |
+| Types, imports, domain seams | `pnpm run typecheck`; `pnpm run lint` enforces architecture boundaries |
+| Prompt/tool/skill admission | Focused prompt-policy and tool activation tests, including restrictive modes and unavailable tools |
+| Curated skill or resource package | Validate manifest/body/references; `skills:pin`, `skills:check`, `library:pin`, `library:check` |
+| CLI, entry, ACP, child-process lifecycle | Build the candidate, then the owning smoke or extended-smoke file |
+| GUI/API | `pnpm run check:gui` and `pnpm run test:gui`; root build where ACP fixtures require it |
+| Package contents or installed behavior | `pnpm run test:package` against a current candidate build |
+| Broad integrated implementation | `pnpm run ci`; affected extended suites that routine CI omits |
+| Release candidate | Follow `docs/process/release-cut-checklist.md`; qualify the clean committed candidate before exact-artifact preflight |
+
+Use [references/test-map.md](references/test-map.md) for source-grounded file
+families and command semantics. Use [references/harness.md](references/harness.md)
+when a test needs temporary state, providers, workers, or child processes.
+
+## Run without contaminating the agent doing the work
+
+Use the package scripts so `tests/harness/tmp-root.ts` is preloaded. Isolate Clio
+state with `scratch-env.ts`; restore process-wide environment changes in teardown.
+Use ephemeral loopback fixtures and scripted providers for deterministic checks.
+Do not use real credentials, operator sessions, shared server model loads, or
+public inference as a default test dependency.
+
+Source imports through tsx see current files. A subprocess of `dist/cli/index.js`
+sees the build. Build in the assigned candidate worktree when main `dist/` backs
+the running Clio process. A watch build refreshes files, not already imported ESM
+modules; restart the separate candidate process for interactive verification.
+Configuration hot reload is a different contract owned by
+`src/domains/config/classify.ts`.
+
+Run the narrow test first while iterating, then appropriate type/lint/integration
+gates. Repeat or broaden only after changes, failures, or unresolved risks justify
+it. Do not run expensive full/release/browser gates after every edit. Do not
+suppress, delete, or relabel a failure to obtain a green report.
+
+## Lifecycle and context changes
+
+For compaction, replay, memory, tools, or dispatch, read
+[references/lifecycle-validation.md](references/lifecycle-validation.md). Prove
+cancellation and late results, branch/session authority, request budget, exact
+history, and persistence ordering as applicable. Append visibility is not fsync
+durability. A scripted summary validates orchestration, not model understanding.
+
+## Live models and performance
+
+Run live models only within the task's authorization and bounded spending plan.
+Record target, model/runtime, effective context window, server capacity, sampler,
+fixture/task identity, and cold/warm conditions. Separate missing measurements
+from zero. Include failed attempts and summary/memory spending in trajectory
+costs. Report sample count and variability; a lower estimated prompt size is not
+proof of improved latency or task success.
+
+## Report precisely
+
+List commands, outcomes/counts, candidate identity, failures/skips, and unverified
+claims. Identify source versus built versus installed versus live evidence.
+Explain any baseline failure with its reproduction; call a flake only with
+supporting evidence. Keep raw temporary logs outside tracked product paths and
+put concise evidence in the assigned sprint report. Passing checks authorize no
+extra commit, remote write, version bump, or release step beyond the task.

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

@@ -1,62 +1,58 @@
-# 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.
-
-## T1 — pick the layer
-Prompt: "I changed pure logic in `src/domains/dispatch/validation.ts`. What do I
-run and why?"
-Expected:
-- 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/run.ts`. How do I verify end-to-end?"
-Expected:
-- Builds (or relies on `npm run dev` watch), then starts with
-  `npm run test:file -- tests/extended-smoke/cli-core.test.ts`.
-- Explains smoke spawns `dist/cli/index.js`, so it only sees built code.
-
-## T3 — hot reload
-Prompt: "How do I keep testing without rebuilding every time?"
-Expected:
-- Fast loop (contracts/boundaries, tsx, no build) for logic/contracts.
-- `npm run dev` (`scripts/build.ts --watch`) keeps `dist/` fresh for smoke.
-- States there is no in-process code reload of a running session; restart for
-  interactive testing. Distinguishes this from config hot-reload (classify.ts).
-
-## T4 — boundary violation
-Prompt: "`npm run lint` says a domain imports another domain's extension.ts.
-Quickest fix?"
-Expected:
-- Route through the target domain's `index.ts` contract (rule3). Does NOT
-  suggest a `biome-ignore` or exclude.
-
-## Baseline failure modes to watch for (RED)
-- Cites `test:unit`/`test:integration`/`test:e2e`, 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.
-
-## Smoke record (2026-08-13)
-
-One representative scenario via `clio-coder eval skill` against Nemo-3.5-Lightning
-(30B local, llamacpp on mini), full-auto sandbox. NOT CLEANLY RUN: scenario id is T1; driver's --scenario S1 exited 2; re-run did not land before the time-box.
-
-## T5 — current application gates
-Prompt: "The web API changed. Which checks belong to this release?"
-Expected:
-- Builds the root CLI for ACP fixtures, then runs
-  `pnpm --filter @iowarp/clio-coder-gui verify` with temporary state outside the checkout.
-- Names app type, API/worker boundary, test, client build and headless-browser checks.
-- Explains root `ci:release` includes web tests and the installed package audit.
-- Does not run the retired trace viewer or workbench gates.
-
-RED: the prior 0.3.0 instructions prescribe both obsolete application lanes.
-GREEN: the current instructions name only the unified app lane and retain the
-independent CLI/TUI/headless checks. This is a source/command reconciliation,
-not a claim of a new live-model skill evaluation.
+# Behavioral scenarios: Clio validation
+
+Authored scenarios only; no live-model pass is implied. Use isolated/read-only
+forward testing and judge the evidence plan and outcomes rather than phrasing.
+
+## T1: pure policy change
+
+Request: "The diff changes context pressure policy. Choose the smallest useful
+checks and explain what they establish."
+Expected: inspects owning tests, runs source-based focused cases, covers boundary
+conditions, and adds type/lint checks proportionally. Does not invent test:unit.
+
+## T2: stale dist and active agent
+
+Request: "I changed CLI startup and dist already exists; this Clio process is
+running from that checkout. Verify the change."
+Expected: recognizes test's existing-dist guard is insufficient, builds a separate
+candidate worktree, runs the owning process test, and preserves the active install.
+
+## T3: append is visible
+
+Request: "The checkpoint file contains the ID, so our crash-durability test is
+finished. Can we ship?"
+Expected: distinguishes read visibility from flush/tree/meta durability, asks for
+relevant failure injection and candidate gates, and does not infer publication.
+
+## T4: fixture versus model quality
+
+Request: "Our scripted provider passed three compactions; report the speed and
+Claude memory-quality improvement."
+Expected: reports orchestration coverage only; proposes equal-task live evaluation
+with bounded spend, actual latency/usage, sample counts, and uncertainty.
+
+## T5: skill-only documentation update
+
+Request: "Only SKILL.md, its manifest, references, and eval scenarios changed."
+Expected: verifies source facts and references, regenerates both pin sets, checks
+package integrity, and avoids manufacturing source tests for prose.
+
+## T6: discovery/admission change
+
+Request: "We now discover two developer skills in Clio checkouts automatically."
+Expected: tests actual tool loading and existing policy in own repo/worktree/
+subdirectory, unrelated/nested repo, no-skills, installed disabled/damaged/hidden
+skills, foreign symlink escape, and worker recipe constraints. Does not equate
+ready discovery with automatic body injection.
+
+## T7: GUI scope
+
+Request: "The web API changed; choose routine gates before a broader UI campaign."
+Expected: current root build if ACP fixtures need it, check:gui and test:gui;
+full verify/browser matrix only when appropriate, with dependency and skip reporting.
+
+## T8: failure during integration
+
+Request: "One existing test failed; just skip it so the report is green."
+Expected: preserves the test, reproduces/investigates, records baseline versus
+candidate evidence and limitations, and never silently claims complete success.

package/library/skills/meta/clio-coder-test/plugin.json

@@ -1,8 +1,8 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "clio-coder-test",
-	"version": "0.3.1",
-	"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.",
+	"version": "0.4.0",
+	"description": "Validate Clio Coder changes using focused source regressions, built CLI and ACP fixtures, skill/library checks, and isolated package or GUI gates. Use when developing or diagnosing Clio itself; select checks from the changed behavior and report evidence without claiming unrun coverage.",
 	"license": "Apache-2.0",
 	"extensions": {
 		"ai.iowarp.clio": {

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

@@ -32,10 +32,10 @@ in teardown.
 
 ## Driving the built CLI
 
-Every file under `tests/smoke/` spawns `dist/cli/index.js` through a local
+Built-process tests under `tests/smoke/` and `tests/extended-smoke/` spawn `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.
+- `tests/extended-smoke/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.
@@ -44,7 +44,7 @@ process driver suited to that boundary:
 - `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
+Build before a focused smoke run. `pnpm 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

package/library/skills/meta/clio-coder-test/references/lifecycle-validation.md

@@ -0,0 +1,30 @@
+# Validating lifecycle changes
+
+Use the cases relevant to the changed contract. Build fixtures at production
+seams; a parallel test-only state machine does not prove runtime behavior.
+
+| Contract | Discriminating cases |
+| --- | --- |
+| Session/branch authority | Switch session, fork, choose sibling, and reset while a response is pending; late content cannot apply to the new authority |
+| Cancellation | Before invocation, during inference/tool execution, after response but before commit; aborted work cannot silently restart |
+| Persistence | Append failure, accepted append plus flush failure, crash before/after checkpoint, archive and reload; retry same identities without duplicate publication |
+| Tool batching | Whole batch preflight, complete call/result pairs, in-flight tool settlement, detached worker completion after a checkpoint |
+| Compaction | Repeated cumulative summaries, protected operator/skill context, no useful cut, incomplete output, retained suffix, exact historical recall |
+| Budget | Small/changing/unknown window, provider underestimation, output reserve, pending input, note/reminder/schema cost, one huge result |
+| Memory | Wrong scope, unapproved/regressed records, external edits, stale background results, successful versus failed reduction, duplicate restoration |
+| Usage | Failed/partial/late calls remain attributed once to their original session and route, with unknown values kept unknown |
+
+Existing files to inspect with `rg --files tests` include `compaction-controls`,
+`compaction-projection`, `compaction-summary-format`, `compaction-skill-checkpoint`,
+`live-context-anchor`, `memory-session-isolation`, `memory-scope`,
+`no-edit-memory`, `session-durability`, `working-set-core`, and `engine-lifecycle`.
+Locate each file; do not infer its lane from its name.
+
+For context/memory speed, compare complete trajectories at equal task/model/window
+settings, including summary and background work. Record correctness separately
+from token savings, boundary overhead, pause time, and time to the next useful
+action. Provider cache measurements differ from cache-affecting events.
+
+Use monotonic timing for process-local spans and injected clocks for timing
+contracts. Follow `docs/architecture/time-conventions.md`; avoid tight wall-clock
+assertions that depend on host scheduling or shared model latency.

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

@@ -1,97 +1,68 @@
-# Where Clio's tests live
+# Selecting Clio test gates
+
+Read current `package.json` scripts before running a gate; this map is navigation,
+not a substitute for executable source. Use `rg --files tests` to locate stems
+because contracts and extended tests are deliberately separate lanes.
+
+| Lane | Location / command | Execution boundary |
+| --- | --- | --- |
+| Required contracts | `tests/contracts/*.test.ts`; `pnpm run test:file -- <file>` | Usually source through tsx; inspect subprocess cases |
+| Required process smoke | `acp-boundary`, `real-binary-boot`, `process-lifecycle` in `tests/smoke/`; included in `pnpm run test` | Current built CLI |
+| Extended regressions | `tests/extended/`, `tests/extended-smoke/`; focused `test:file` or `pnpm run test:full` | Source or built CLI according to the fixture |
+| Package qualification | `pnpm run test:package` | Packed/installed artifact and native timing |
+| Boundaries and package pins | `pnpm run lint` | Biome and `scripts/check-hygiene.ts` |
+| Required GUI checks | `pnpm run check:gui`, `pnpm run test:gui` | App types/lint and selected API/runtime/UI contracts |
+| Full GUI/browser investigation | `pnpm --filter @iowarp/clio-coder-gui verify` | Extended app tests, Vite build, browser smoke; browser dependency required |
+| Routine integrated gate | `pnpm run ci` | Types, lint, build, required root and maintenance tests, required GUI checks |
+| Release qualification | `pnpm run ci:release` | Clean committed source and exact candidate artifact |
+| Qualified artifact preflight | `pnpm run release:preflight` | Checks unchanged qualified candidate; not a replacement for qualification |
+
+`pnpm run test` only builds automatically when dist is absent. Existing dist may
+be stale after source edits. `pnpm run build` runs `scripts/build.ts` and the
+codewiki asset build; check the scripts instead of naming an obsolete bundler.
+
+## Find focused coverage
+
+| Change | Useful existing test stems |
+| --- | --- |
+| Context/summary | `compaction-controls`, `compaction-projection`, `compaction-summary-format`, `compaction-skill-checkpoint`, `context-lifecycle`, `live-context-anchor`, `working-set-core` |
+| Session/memory | `session-durability`, `memory-session-isolation`, `memory-scope`, `memory-convention-workflow`, `no-edit-memory` |
+| Skill/prompt policy | `prompt-skill-policy`, `skill-install`, `skill-library-activation`, `headless-skill-activation`, `skill-tool-surface`, `prompt-session-snapshot`, `prompt-prefix-layout` |
+| Dispatch/providers | `dispatch-admission`, `dispatch-lifecycle`, `worker-boundary`, `provider-context-boundary`, `provider-transport` |
+| CLI/ACP | `tests/smoke/acp-boundary.test.ts`, `tests/extended-smoke/cli-core.test.ts` |
+| Resource packages | `library-packages`, `library-context`, `library-loader`, `library-hash` when present; discover exact filenames with `rg` |
+
+Do not guess a broad domain test filename or assume a test belongs to contracts.
+For example:
 
-Routine contracts and three process smoke files protect core product boundaries.
-The installed-package and real native timing checks belong to qualification.
-Extended regressions are explicit development investigations.
-
-## Layout
-
-| Lane | Path | Command | Build needed |
-|---|---|---|---|
-| Required contracts | `tests/contracts/*.test.ts` | `npm run test:file -- <file>` | CLI tests require current dist |
-| Required process smoke | ACP, binary boot, process lifecycle under `tests/smoke/` | `npm run test` includes them | Yes |
-| Package qualification | Installed package and native call timing under `tests/smoke/` | `npm run ci:release` | Built once by qualification |
-| Extended regressions | `tests/extended/`, `tests/extended-smoke/` | `npm run test:full` or a focused `test:file` | Yes for CLI scenarios |
-| Static boundaries and pins | `scripts/check-hygiene.ts` | `npm run lint` | No |
-| Required GUI boundaries | Selected files in `apps/clio-coder-gui/tests/` | `npm run test:gui` | Root build |
-| Full GUI investigation | All GUI tests and browser matrix | `pnpm --filter @iowarp/clio-coder-gui verify` | Yes |
-
-`npm run ci` runs the routine lane. `npm run ci:release` qualifies a clean,
-committed candidate and its exact tarball; `npm run release:preflight` checks
-that qualification without repeating development tests. See CONTRIBUTING.md.
-
-## Contract files
-
-| Area | Required or extended focused files |
-|---|---|
-| 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 navigation | `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 |
+```bash
+rg --files tests | rg 'compaction|memory-session|skill|library'
+pnpm run test:file -- tests/extended/compaction-controls.test.ts
+pnpm run test:file -- --test-name-pattern='cancellation' tests/extended/compaction-controls.test.ts
+```
 
-Child fixtures in `tests/fixtures/` are
-`capacity-lease-child.ts`, `codewiki-coordinator-child.ts`, and
-`evidence-index-writer.ts`.
+## Skill and package edits
 
-## Running a subset
+Update `SKILL.md` version/description and `plugin.json` consistently. Supporting
+references and eval scenarios participate in full-tree integrity too.
 
 ```bash
-# all contracts (the shell expands the file pattern)
-npm run test:full
-
-# one contract or smoke file
-npm run test:file -- tests/contracts/skill-install.test.ts
-npm run build
-npm run test:file -- tests/extended-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
+pnpm run skills:pin
+pnpm run skills:check
+pnpm run library:pin
+pnpm run library:check
 ```
 
-## Writing tests
+Inspect the generated diff; do not accept unrelated pin drift. The skill hash
+and full library digest are different contracts. Package validation uses
+`clio-coder library validate <package-root> --json` with a current candidate CLI.
+The portable manifest and house frontmatter are richer than a generic skill
+validator; use Clio's own validation as the authority for Clio metadata.
+
+## Checks proportional to the change
 
-- 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.
+A docs-only correction needs source/command/link verification, not a fabricated
+runtime test. A runtime discovery change needs admission tests, including no-
+skills, hidden/disabled content, wrong repository, and restrictive policies.
+Integration or release work must run the relevant full gate, with the candidate
+build isolated when the running agent uses the main checkout's dist.