@iowarp/clio-coder 0.4.1 → 0.4.3

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

@@ -1,13 +1,13 @@
 ---
 name: clio-coder-test
-description: Use when writing or modifying Clio Coder's own source under src/, or verifying a change end-to-end against the real test harness. Covers the three real layers (contracts / smoke / boundaries), choosing which to run for a given change, the mock-provider and ACP-over-stdio harness, and the hot-reload dev loop for picking up latest code. Activate on any src/ edit, before declaring a change verified, or when asked whether Clio still works.
+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.1.5
+version: 0.3.0
 license: Apache-2.0
 clio-coder:
   registry-id: iowarp/clio-coder
@@ -20,120 +20,127 @@ clio-coder:
 
 # Clio Test
 
-Clio's test suite has exactly three layers: **contracts**, **smoke**, and
-**boundaries**.
+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, PR),
-that is `clio-coder-dev`, not this skill. **REQUIRED SUB-SKILL:** `clio-coder-dev` for the
-local-vs-contribute boundary.
+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 (includes tests/ and benchmarks/internal/)
-npm run lint              # biome check . && scripts/check-hygiene.ts (import boundaries, skill pins, doc drift)
-npm run test:file -- 'tests/contracts/**/*.test.ts'  # contract tests (tsx, import src directly, no build)
-npm run test:file -- 'tests/smoke/**/*.test.ts'      # spawn dist/cli/index.js end-to-end (NEEDS a build)
-npm run test              # contracts + smoke, sharded across processes (the full gate)
-npm run build             # tsup -> dist/
-npm run dev               # tsup --watch -> rebuilds dist/ on save
-npm run ci                # typecheck && lint && skills:check && build && test && test:trace-viewer
-npm run live:smoke -- --target <id>   # one real turn against a configured target; never in CI
+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
 ```
 
-## Which layer catches what
+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` | `npm run test:file -- 'tests/contracts/**/*.test.ts'` | contract tests import `src` via tsx; no build |
-| dispatch / providers / prompts / safety / config / persistence / acp behavior | `npm run test:file -- 'tests/contracts/**/*.test.ts'` | each has a file in `tests/contracts/` |
-| skills loader / activation | `npm run test:file -- 'tests/contracts/**/*.test.ts'` | `tests/contracts/skills.test.ts`, `skill-activation-compaction.test.ts` |
-| any `src/` import edit | `npm run lint` | the hygiene check enforces rule1/2/3 |
-| `src/cli/*` or `src/entry/*` user-facing flow | build, then `npm run test:file -- 'tests/smoke/**/*.test.ts'` | smoke spawns the real `dist/cli/index.js` |
-| ACP surface (`src/cli/acp.ts`, engine ACP) | build, then `npm run test:file -- 'tests/smoke/**/*.test.ts'` | smoke drives `clio-coder acp` over JSON-RPC/stdio |
-
-**See `references/test-map.md`** for exactly where each test lives and how to run
-a single file.
+| 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 three rules (also the Hard
-Invariants in `CLIO-CODER.md`), run by `scripts/check-hygiene.ts` under
-`npm run lint`. If it reports a violation, fix the import — never silence the
-check:
-
-- **rule1**: only `src/engine/**` may value-import `@earendil-works/pi-*`. Outside
-  engine, use Clio contracts or type-only imports that erase at compile time.
-- **rule2**: `src/worker/**` never imports `src/domains/**`. Cross through
-  `src/worker/spec-contract.ts`.
-- **rule3**: `src/domains/<x>/**` never imports `src/domains/<y>/extension.ts`.
-  Go through the target domain's `index.ts` contract.
-
-## The hot-reload dev loop (picking up latest code)
-
-There are two independent reload mechanisms; know which applies.
-
-**Source reload for tests.** This is the "pick up latest code" loop:
-
-- **Fast loop — no build.** The contracts glob runs `node --import tsx --test`
-  and imports `src/**` directly, and the hygiene lint reads source statically,
-  so both always see the latest source with zero build step. Iterate here whenever the change is pure
-  logic or a contract.
-- **Full loop — needs `dist/`.** The smoke glob spawns `dist/cli/index.js`, so it
-  only sees code that has been built. Keep `npm run dev` (`tsup --watch`) running
-  in another pane; it rebuilds `dist/` on every save, so the smoke lane
-  picks up your latest source without a manual `npm run build`.
-
-**Config reload for a running session.** Clio classifies a settings change
-(`src/domains/config/classify.ts`) into three buckets:
-
-- `hotReload` (theme, keybindings, `safetyLevel`, `defaultMode`) — applies live
-  via the `config.hotReload` bus, no restart.
-- `nextTurn` (model, thinking level, budget, skills, compaction…) — applies
-  before the next turn.
-- `restartRequired` (credentials, runtime enable/disable, `budget.concurrency`)
-  — needs a process restart. Unknown fields fail closed to this bucket.
-
-**There is no in-process reload of Clio's own code in a running session.** ESM
-modules load once; to run changed harness code in an interactive session,
-restart the process (against a freshly built `dist/`).
+`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. Write the change.
-2. `npm run typecheck` and `npm run lint`.
-3. Run the narrowest layer from the table above.
-4. `npm run lint` if you touched imports.
-5. If you touched CLI/entry/ACP: `npm run build` (or rely on `dev` watch), then
-   `npm run test:file -- 'tests/smoke/**/*.test.ts'`.
-6. `npm run ci` before calling it done. Report exactly what ran and what is
-   unverified.
+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.
 
-When debugging a single test:
+For one test file or an `it.only` while debugging:
 
 ```bash
-node --import tsx --test tests/contracts/<file>.test.ts   # one file
-node --import tsx --test --test-only tests/contracts/<file>.test.ts  # it.only
+npm run test:file -- tests/contracts/<file>.test.ts
+npm run test:file -- --test-only tests/contracts/<file>.test.ts
 ```
 
-## What NOT to do
-
-- Don't reintroduce `tests/unit|integration|e2e/`; that taxonomy was
-  deliberately removed. Don't add a second pseudo-terminal: `tests/harness/pty.ts`
-  is the one PTY, used by the three `*-pty`/`tui-width-matrix` smoke suites and
-  by `benchmarks/internal/pty-drive.ts`.
-- Don't add `scripts/diag-*.ts` or `scripts/verify-*.ts`. A test belongs in
-  `tests/`; a one-off probe belongs in `/tmp` and gets deleted (see
-  `references/harness.md`).
-- Don't silence a boundary violation with `// biome-ignore` or an exclude. Fix
-  the import.
-- Don't assert against a simulated TUI. Test real commands via the spawn harness.
-- Don't commit with red tests. If a pre-existing test fails on state that
-  predates your change, report it and ask — don't delete or skip it.
+## 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
 
-Driving the real CLI, the mock provider, ACP over stdio, and the PTY, plus the
-throwaway probe pattern: **see `references/harness.md`**. Driving the real
-binary against a real model (headless, PTY, tmux, herdr) is a different claim
-and lives in `benchmarks/internal/SKILL.md`.
+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-coder-test/evals.md

@@ -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

@@ -1,126 +1,102 @@
 # Clio test harness reference
 
-How to drive the real Clio binary, a mock provider, the ACP surface, and a
-real pseudo-terminal in tests. Every model here is a stub; these are machinery
-tests. A run against a real model is `benchmarks/internal/SKILL.md`.
-
-## Contents
-- The spawn harness (`runCli`, `makeScratchHome`)
-- Mocking a provider (OpenAI-compatible SSE fixture)
-- ACP over JSON-RPC/stdio
-- The PTY (`openPty`, `runInPty`)
-- One-off probes (no test file)
-
-## The spawn harness
-
-`tests/harness/spawn.ts` spawns `node dist/cli/index.js` with piped stdio, so
-**build first** (or keep `npm run dev` running) before running smoke.
-
-```ts
-import { makeScratchHome, runCli } from "../harness/spawn.js";
-
-const scratch = makeScratchHome();
-try {
-  await runCli(["doctor", "--fix"], { env: scratch.env });   // bootstrap config
-  const res = await runCli(["targets", "--json"], { env: scratch.env, timeoutMs: 20_000 });
-  // res = { code, signal, stdout, stderr }
-  const parsed = JSON.parse(res.stdout) as { targets: unknown[] };
-} finally {
-  scratch.cleanup();
-}
-```
-
-- `runCli(args, { env, cwd, timeoutMs, input })` → `Promise<{ code, signal, stdout, stderr }>`.
-  Default `timeoutMs` is 15_000; raise it for `run`/`acp`.
-- `makeScratchHome()` → `{ dir, env, cleanup }`. The `env` sets `CLIO_CODER_HOME`,
-  `CLIO_CODER_DATA_DIR`, `CLIO_CODER_CONFIG_DIR`, `CLIO_CODER_CACHE_DIR`, and
-  `CLIO_CODER_REQUIRE_HOME_PREFIX=1`. **Always pass `env: scratch.env`** so the test
-  never touches the developer's real config, and always `cleanup()` in `finally`.
-- Bootstrap a scratch home with `runCli(["doctor", "--fix"], …)` before commands
-  that need settings.
-
-Useful flags seen in smoke tests: `--no-context-files`, `--no-skills`,
-`--skill <path>`, `--json`. For the live CLI surface, run `clio-coder --help` and
-`clio-coder <command> --help` rather than hardcoding a command list here.
-
-## Mocking a provider
-
-To exercise an agent `run` without a real model, stand up an in-process
-OpenAI-compatible server that streams one SSE chunk, then point a target at it by
-patching `settings.yaml`. This is the pattern in `tests/smoke/cli.test.ts`:
-
-```ts
-// 1. Start a fixture that replies with a fixed string over text/event-stream.
-const fixture = await startOpenAICompatFixture("mock reply");
-// 2. Patch the scratch settings.yaml: add an `openai-compat` target whose
-//    url is fixture.url, set orchestrator.target/model to it, and supply the
-//    apiKeyEnvVar it expects.
-seedOpenAICompatOrchestrator(join(scratch.dir, "config"), fixture.url);
-// 3. Run, providing the key env var the target references.
-const res = await runCli(["--no-context-files", "run", "hello"], {
-  env: { ...scratch.env, CLIO_CODER_TEST_OPENAI_KEY: "sk-test" },
-  timeoutMs: 20_000,
-});
-// res.stdout === "mock reply\n"
-await closeServer(fixture.server);
-```
-
-The fixture also records `fixture.requests`, so you can assert what Clio sent
-(e.g. that an explicit `--skill` was injected into the prompt).
-
-## ACP over JSON-RPC/stdio
-
-`clio-coder acp` speaks ACP v1 over stdio. Drive it with a line-delimited JSON-RPC
-client (see `createJsonRpcProcessClient` in the smoke test): `initialize` →
-`session/new` → `session/prompt` → `session/close`. Streaming arrives as
-`session/update` notifications whose `update.sessionUpdate` must be a v1 variant
-(`agent_message_chunk`, `tool_call`, `plan`, `current_mode_update`, …). A
-non-spec discriminator breaks strict clients like Zed, so the smoke test asserts
-every emitted variant is in the v1 set.
-
-## The PTY
-
-Piped stdio reports no terminal width and no TTY, so the TUI refuses to start
-and every width-sensitive path collapses to 80 columns. `tests/harness/pty.ts`
-opens a real pseudo-terminal through `node-pty` (a devDependency, never
-shipped):
-
-```ts
-import { openPty, runInPty, stripAnsi, visibleLines } from "../harness/pty.js";
-
-// Scripted: type on a schedule, stop when the output matches, bounded by a timeout.
-const run = await runInPty(process.execPath, [CLI], { cols: 120, rows: 40, cwd, env,
-  readyWhen: /ctx /, input: [{ afterMs: 200, data: "/quit\r" }], until: /bye/, timeoutMs: 20_000 });
-
-// Controllable: write, resize, pause output, wait for a matcher, wait for exit.
-const session = await openPty(process.execPath, [CLI], { cols: 140, rows: 44, cwd, env });
-await session.waitForOutput((out) => /ctx /.test(stripAnsi(out)), 30_000);
-session.write("/quit\r");
-await session.waitForExit(10_000);
-```
-
-Use it only for what a pipe cannot show: width, raw mode, SIGINT through a
-terminal, the alternate-screen and keyboard-protocol teardown. The three
-suites that need it are `tests/smoke/tui-width-matrix.test.ts`,
-`instant-shell-pty.test.ts`, and `render-trace-pty.test.ts`. Anything else
-belongs on `runCli`.
-
-## One-off probes (no test file)
-
-To poke at Clio without writing a permanent test, drop a throwaway script in
-your scratch directory and run it with tsx. Delete it when done — never leave
-probes under `tests/`, `scripts/`, or `benchmarks/`.
-
-```ts
-// /tmp/probe.ts
-import { makeScratchHome, runCli } from "/abs/path/to/repo/tests/harness/spawn.js";
-const scratch = makeScratchHome();
-await runCli(["doctor", "--fix"], { env: scratch.env });
-const out = await runCli(["skills", "list", "--json", "--all"], { env: scratch.env, cwd: process.cwd() });
-console.log(out.stdout.slice(0, 400));
-scratch.cleanup();
-```
-
-```bash
-npx tsx /tmp/probe.ts
-```
+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.