@iowarp/clio-coder 0.4.1 → 0.4.3

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

@@ -1,69 +1,96 @@
 # Where Clio's tests live
 
-Three layers under `tests/`. Add a new test next to the closest existing file;
-create a new file only for a genuinely new domain cluster.
+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
 
-| Layer | Path | Runner | Build needed |
+| Lane | Path | Runner | Build needed |
 |---|---|---|---|
-| contracts | `tests/contracts/*.test.ts` | `npm run test:file -- <glob>` (tsx + scratch root) | no (imports `src`) |
-| smoke | `tests/smoke/*.test.ts` | `npm run test:file -- <glob>` | **yes** (spawns `dist/`) |
-| boundaries | `tests/boundaries/check-boundaries.ts` | `npm run lint` (hygiene) | no |
-| harness (not tests) | `tests/harness/*.ts` | imported by contracts and smoke | — |
+| 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 |
 
-The harness modules: `spawn.ts` (run the built CLI with pipes), `scratch-env.ts`
-(isolated Clio home), `pty.ts` (a real pseudo-terminal), `openai-compat-fixture.ts`
-and `fake-lmstudio-server.ts` (stub providers), `fake-ssh.ts` (stub fleet node),
-`clock.ts` (steppable clock), plus dispatch, receipt, and module-graph helpers.
-Everything under `tests/` stubs the model. Real-model runs are
-`benchmarks/internal/` and never run under `npm test`.
+`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 test files
+## Contract files
 
-| Area | File |
+| Area | Current files under `tests/contracts/` |
 |---|---|
-| ACP contract | `tests/contracts/acp.test.ts` |
-| context bootstrap / CLIO-CODER.md parse+render | `tests/contracts/bootstrap.test.ts` |
-| config schema + hot-reload classification | `tests/contracts/config.test.ts` |
-| dispatch (validation / admission / ledger) | `tests/contracts/dispatch.test.ts` |
-| session / memory / evidence persistence | `tests/contracts/persistence.test.ts` |
-| prompt fragments + hashing | `tests/contracts/prompts.test.ts` |
-| provider catalog / matcher / resolver | `tests/contracts/providers.test.ts` |
-| safety classification | `tests/contracts/safety.test.ts` |
-| skills loader / collisions / provenance | `tests/contracts/skills.test.ts` |
-| skill activation + compaction interplay | `tests/contracts/skill-activation-compaction.test.ts` |
-| tool registry / names / profiles | `tests/contracts/tools.test.ts` |
-
-## Smoke + boundaries
-
-| Area | File |
+| 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 |
 |---|---|
-| non-interactive CLI + ACP-over-stdio end-to-end | `tests/smoke/cli.test.ts` |
-| the package as installed from `npm pack` | `tests/smoke/pack-install.test.ts` |
-| TUI at real terminal sizes, NO_COLOR, Ctrl-C teardown (PTY) | `tests/smoke/tui-width-matrix.test.ts` |
-| instant shell before hydration, SIGTERM through the lease (PTY) | `tests/smoke/instant-shell-pty.test.ts` |
-| committed-frame render trace under PTY backpressure (PTY) | `tests/smoke/render-trace-pty.test.ts` |
-| import boundary rules (rule1/2/3), run under `npm run lint` | `tests/boundaries/check-boundaries.ts` |
+| `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
-npm run test:file -- 'tests/contracts/**/*.test.ts'
-# one file
-npm run test:file -- tests/contracts/skills.test.ts
-# only it.only / describe.only within a file
-npm run test:file -- --test-only tests/contracts/skills.test.ts
+# 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
 
-- `node:test` + `node:assert/strict`. Group with `describe` / `it`.
-- Local imports end in `.js` (NodeNext), e.g. `from "../../src/domains/x/y.js"`.
-- `tsconfig.tests.json` is strict with `noUncheckedIndexedAccess` and
-  `exactOptionalPropertyTypes`; narrow array access before use.
-- Biome rejects `delete obj.key`; use `Reflect.deleteProperty(obj, "key")` when
-  cleaning env maps or object keys.
-- Filesystem tests use a scratch home via `makeScratchHome()` (smoke) or the
-  `CLIO_CODER_HOME` / `CLIO_CODER_*_DIR` env overrides (contracts); clean up in `finally`.
+- 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,6 +1,6 @@
 ---
 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.
+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
@@ -8,7 +8,7 @@ triggers:
   - permission denied
   - add a secret
   - secret leaked
-version: 0.1.3
+version: 0.2.0
 license: Apache-2.0
 allowed-tools:
   - read

package/skills/meta/find-skills/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: find-skills
-description: Use when the user asks "is there a skill for X", "find a skill", "install a skill", "add a skill", asks whether a capability exists as an installable skill, or wants to extend the agent with functionality that might already be published. Searches with `clio-coder skills search`, browses the ecosystem read-only, and installs only through `clio-coder skills install`. Not for authoring a new skill; use skill-craft.
+description: Finds and installs published skills when the user asks whether a capability exists as a skill, searching with clio-coder skills search and installing only through clio-coder skills install. Not for authoring a new skill; use skill-craft.
 triggers:
   - find a skill
   - is there a skill for this
   - install a skill
   - add an agent skill
   - search the skills marketplace
-version: 0.1.2
+version: 0.2.0
 license: Apache-2.0
 allowed-tools:
   - bash

package/skills/meta/herdr/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: herdr
-description: Use when the user explicitly mentions Herdr or asks to launch, drive, or inspect another agent or command in a Herdr pane, tab, or workspace — including starting a second Clio Coder instance and delegating work to it. Requires HERDR_ENV=1. Not for background work a plain shell or dispatch already covers; do not activate merely because a task could benefit from parallelism.
+description: Launches, drives, or inspects another agent or command in a Herdr pane, tab, or workspace, including a second Clio Coder instance; requires HERDR_ENV=1. Not for background work a plain shell or dispatch already covers.
 triggers:
   - use Herdr
   - launch an agent in a Herdr pane
   - inspect a Herdr agent
   - start a second Clio Coder instance
   - drive a command in a Herdr workspace
-version: 0.1.1
+version: 0.2.0
 license: Apache-2.0
 allowed-tools:
   - bash

package/skills/meta/skill-craft/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: skill-craft
-description: Use when writing, reviewing, or pruning a SKILL.md — authoring a new skill, editing an installed one, or judging whether a skill's description, body, or length is earning its cost. Triggers on "write a skill", "improve this skill", "why isn't this skill firing", "is this skill too long".
+description: Writes, reviews, or prunes a SKILL.md, judging whether its description, body, and length earn their cost. Not for packaging a workflow that just happened; use workflow-distiller.
 triggers:
   - write a SKILL.md
   - create a new skill
   - improve this skill
   - why isn't this skill firing
   - prune a skill body
-version: 0.1.3
+version: 0.3.0
 license: Apache-2.0
 allowed-tools:
   - read
@@ -36,11 +36,14 @@ tool. Project skills live in `.clio-coder/skills/<name>/`; user skills in the Cl
 config dir under `skills/<name>/`. The loader validates on load; check work
 with `clio-coder skills validate`. Frontmatter contract (Agent Skills compatible):
 
-- `name`: lowercase-hyphen, ≤64 chars, must match the folder.
+- `name`: lowercase-hyphen, ≤64 chars. Catalog convention requires it to match
+  the folder; the runtime loader warns on a mismatch and uses the frontmatter
+  name.
 - `description`: required, ≤1024 chars; its craft is the section below. Quote
   it when it contains ` #` — an unquoted YAML scalar is truncated there.
-- `version` and `license`: required for catalog publication; bump the version
-  on any name or description change so drift detection can tell copies apart.
+- `version` and `license`: required for catalog publication. Follow the
+  marketplace versioning policy for body, trigger-surface, and sibling-file
+  changes; the normalized `SKILL.md` hash handles drift separately.
 - `disable-model-invocation: true`: hides the skill from the agent; only the
   user can activate it.
 - `allowed-tools` / `disallowed-tools`: a *narrowing* declaration, not a
@@ -50,7 +53,7 @@ with `clio-coder skills validate`. Frontmatter contract (Agent Skills compatible
   names only (see skills/README.md, "Claude Code interop").
 - `requires`: `skill:<name>` dependencies; the loader warns when one is
   missing. Reference an installed skill by name instead of restating its job.
-- `clio:`: the reserved publication block (`registry-id`, `source-url`,
+- `clio-coder:`: the reserved publication block (`registry-id`, `source-url`,
   `audit`, `provenance` designed|adapted|imported with `origin` when not
   designed, `eval-status`, optional `model-size` and `agents`). Required for
   catalog skills; approval is judged against it (skills/README.md).
@@ -66,17 +69,19 @@ but the user must remember it exists: cognitive load. Keep a description only
 when the agent must reach the skill on its own or another skill requires it;
 if it only ever fires by hand, set `disable-model-invocation: true`.
 
-## Description: Triggers, Not Identity
+## Description and Triggers
 
-The description is the skill's trigger surface, so every word competes with
-every other skill's description:
+Two frontmatter fields share the trigger surface, and every word in both
+competes with every other skill's:
 
-- Front-load the strongest trigger word.
-- One trigger per distinct branch. Synonyms restating one branch ("API key",
-  "credential", "token") are duplication; keep the strongest.
-- Cut identity the body already states; keep triggers, plus one "Not for X;
-  use <other-skill>" clause per real boundary.
-- Word triggers with the language the user actually types.
+- `triggers`: the phrases a user actually types, one per distinct branch.
+  Synonyms restating one branch ("API key", "credential", "token") are
+  duplication; keep the strongest.
+- `description`: one lead sentence saying what the skill does, then one
+  "Not for X; use <other-skill>" clause per real boundary. It is what the
+  agent reads in the `context(scope="skills")` listing on every skill-shaped
+  turn, so it carries no trigger list and no identity the body already
+  states.
 
 ## Body: Steps and Reference
 
@@ -113,7 +118,8 @@ Before finishing any skill, pass the body line by line:
   or split the skill; a split description must earn its permanent context
   load.
 
-Done when: description is triggers-only, every step has a checkable
+Done when: the description is one sentence plus routing clauses and the
+triggers carry the phrases, every step has a checkable
 completion criterion, no line fails the relevance/duplication/no-op pass, and
 an `evals.md` records at least one RED-GREEN scenario distinguishing
 with-skill from without.

package/skills/planning/archify/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: archify
+description: "Validated interactive system maps and diagrams as standalone HTML from a typed JSON spec, for one of five diagram types (architecture, workflow, sequence, dataflow, lifecycle). Use when the user asks to visualize architecture, a workflow, a call sequence, a data pipeline, or a state machine, or to map this repository. Not for ad hoc drawings or slide art, and not for Mermaid output; use the artifact tool for plain Markdown."
+triggers:
+  - architecture diagram
+  - system map
+  - map this repository
+  - sequence diagram
+  - data flow diagram
+  - state machine diagram
+  - visualize the architecture
+version: 0.1.0
+license: MIT
+allowed-tools:
+  - bash
+  - read
+  - write
+  - edit
+  - ls
+  - grep
+  - find
+  - code_nav
+  - verify
+  - context
+clio-coder:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/planning/archify
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/tt-a1i/archify/tree/v2.16.0/archify
+  eval-status: scenarios-recorded
+  model-size: any
+  agents:
+    - main
+    - architect
+    - documenter
+    - wiki-writer
+---
+
+# Archify
+
+Create a self-contained interactive HTML diagram from a small typed JSON
+specification. The renderer is the upstream archify package installed
+beside this file; the skill base directory is the directory that holds
+`bin/`. Every command below runs as
+`node .clio-coder/skills/archify/bin/archify.mjs ...` for a project-scope
+install, or `node <clio config dir>/skills/archify/bin/archify.mjs ...` for a
+user-scope install. No install step, no network, and no dependencies beyond
+Node 18 or later.
+
+## Fast authoring path
+
+1. Choose `architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle`
+   from the question. When ambiguous, run
+   `node <skill>/bin/archify.mjs guide "<scenario>" --json`.
+2. Read one matching schema in `schemas/`, `schemas/common.schema.json`, and
+   one matching example in `examples/`. Read only those files. The example
+   supplies field shape, never facts: author new stable ids, domain wording,
+   and layout. New workflows use `schema_version: 2`.
+3. Write the candidate JSON as the very next action. Do not plan coordinates
+   in prose. Start with one clear main path, short side branches, sparse
+   labels, and at most 12 primary nodes. Set `meta.quality_profile` to
+   `"showcase"` unless the user asks for a dense `standard` map. Start with
+   automatic routes and labels; add `via`, `channelX`, `channelY`, or
+   `labelAt` only when a diagnostic asks for one, and at most one per repair.
+4. Validate after every edit and immediately before delivery:
+
+   ```bash
+   node <skill>/bin/archify.mjs validate <type> <candidate.json> --quality showcase --json
+   ```
+
+   A showcase pass reports all artifact checks with 0 composition errors
+   and 0 warnings. If validation fails, change only the diagnosed `subject`,
+   verify `evidence`, choose from `supportedFixes`, and rerun. Stop and report
+   the unresolved diagnostics truthfully when two consecutive rounds do not
+   lower the error count.
+5. Deliver once, as the final acceptance command:
+
+   ```bash
+   node <skill>/bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json
+   ```
+
+   A non-zero exit is never success. A failed delivery preserves any previous
+   output at that path.
+
+Do not read renderer, validator, or geometry source before the first
+candidate exists. Inspect implementation only for an unsupported internal
+diagnostic or after two focused repairs fail.
+
+## Type router
+
+| Type | Use for |
+|---|---|
+| `architecture` | Components, services, boundaries, infrastructure, repository maps |
+| `workflow` | Processes, approval gates, tool calls, runbooks, CI/CD |
+| `sequence` | API call chains, request lifecycles, async traces, returns |
+| `dataflow` | Pipelines, ETL/ELT, lineage, consumers |
+| `lifecycle` | State transitions, retries, waiting and terminal states |
+
+Pasted Mermaid is read for topology and meaning, then re-authored as fresh
+archify JSON: `flowchart` becomes `workflow` (or `architecture` for a
+component map), `sequenceDiagram` becomes `sequence`, `stateDiagram` becomes
+`lifecycle`.
+
+## Authoring invariants
+
+- One obvious main path; side branches leave the nearest main-path node.
+  Remove low-value edges before adding routing controls.
+- Omit `meta.visual_preset`, `meta.subtitle`, `meta.legend`, and
+  `meta.engineering_profile` by default. Set a visual preset only when the
+  user names that style.
+- Component types are `frontend`, `backend`, `database`, `cloud`,
+  `security`, `messagebus`, and `external`. Variants are `default`,
+  `emphasis`, `security`, and `dashed`.
+- Relationship labels are semantic data. When one collides, move the label
+  or adjust spacing first, then shorten wording while preserving meaning.
+  Deleting a label is not a geometry repair.
+- Preserve exact product names, identifiers, commands, protocols, and paths.
+  `meta.locale` is `"en"` or `"zh-CN"`; omit it for any other language and
+  say that the viewer chrome falls back to English.
+- Brand identity is explicit. Put a canonical built-in id in `brand` only
+  when the node names that real product; query
+  `node <skill>/bin/archify.mjs brands "<name>" --json`. Never infer a brand
+  from a role such as "database".
+- Never accept an edge crossing an unrelated opaque node, an ambiguous shared
+  corridor, or a label masking another route.
+
+Read `references/authoring-contract.md` only when you need field enums,
+spacing math, geometry repair rules, or mode-specific placement.
+
+## Placement
+
+Write `<name>.<type>.json` and `<name>.html` to `.clio-coder/artifacts/maps/`
+unless the user names an output path. Create the directory first. An
+operator-named path is a human deliverable and lands in the working tree
+where they said. Archify creates `.archify-delivery-*` staging directories
+beside the output during `deliver`, so the output directory must be a
+writable directory inside the workspace, never a read-only or external
+location.
+
+## Repository evidence
+
+When asked to map a repository, do not author from scratch. First run:
+
+```bash
+clio-coder context map --json
+```
+
+It reads the codewiki index and writes
+`.clio-coder/artifacts/maps/<repo>.architecture.json`: an architecture spec
+whose components are the repository's largest directory areas and whose
+connections are collapsed import edges. When the origin remote is a GitHub
+URL and `HEAD` is a full revision, the seed also carries `meta.repository`
+and per-component `sources` pointing at real files and lines; otherwise it
+carries neither, because archify accepts source citations only against a
+pinned revision. If it reports that no index exists, run
+`clio-coder context index` and retry. Then refine the seed: rename labels to
+what the areas mean, drop noise edges, and keep `meta.repository` and every
+`sources` entry that came from the seed. Cite additional line ranges only
+from `code_nav mode=outline` results, never from memory, and only when
+`meta.repository` is present. Keep at most 12 primary components; fold
+smaller areas into their parent rather than adding nodes. When the seed
+carries `meta.repository`, pass `--repo-root .` to both `validate` and
+`deliver` so the source paths and line numbers are verified against the
+working tree; without it, run both commands without `--repo-root`.
+
+## Delivery and verification
+
+`validate` during repair, `deliver` once for acceptance. Delivery freezes the
+exact spec bytes into a same-directory snapshot, renders and checks it,
+atomically commits the HTML, and reports SHA-256 plus byte counts for both
+spec and artifact. That is deterministic artifact evidence; it does not
+exercise the viewer in a browser.
+
+After `deliver` exits 0, run the Clio-side check on the committed file:
+
+```
+verify(check="frontend", path="<output.html>")
+```
+
+That validates structure, local references, and syntax, and loads the page
+in a headless browser when one is on PATH. Archify's own
+`node <skill>/bin/archify.mjs visual-check <output.html> --json` is optional:
+it needs a system Chrome and fails with `viewer/chrome-unavailable` on
+headless nodes. Report that outcome as what it is, never as a pass.
+
+Keep the three claims separate: `deliver` proves deterministic artifact
+checks, a browser load proves bounded behavior in a real browser, and
+perceptual visual review requires a human or an image-capable reviewer.
+
+## Output
+
+Return the HTML path, the diagram type, the validation summary, the
+spec and artifact receipt, the `verify` result, and the visual-review
+status. Do not claim success for a non-zero command or claim inspection you
+did not perform.

package/skills/planning/archify/evals.md

@@ -0,0 +1,65 @@
+# Evals — archify
+
+RED-GREEN scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
+bullet. Status: scenarios recorded, not yet executed against a model
+(`eval-status: scenarios-recorded`).
+
+Both scenarios assume the skill is installed at project scope
+(`.clio-coder/skills/archify/`) and run from the project root.
+
+## S1 — describe a system
+
+Setup: empty git repository. Prompt: "Draw the architecture: a browser
+talks to an API, the API uses Redis as a cache and PostgreSQL as its
+store."
+
+Expected:
+- Chooses `architecture` and reads exactly one schema plus one example
+  before writing.
+- The very next tool action writes
+  `.clio-coder/artifacts/maps/<name>.architecture.json` with four
+  components (`frontend`, `backend`, `database`, `database`), three
+  connections, and `meta.quality_profile: "showcase"`.
+- Runs `validate architecture ... --quality showcase --json`; the receipt
+  reports 0 errors and 0 warnings.
+- Runs `deliver` once; exit 0; `.clio-coder/artifacts/maps/<name>.html`
+  exists and the receipt carries a SHA-256 for both spec and artifact.
+- Runs `verify(check="frontend", path=<html>)` and reports its result.
+- Never invokes `scripts/check-update.mjs` and never runs `visual-check`
+  unless asked; if it does run it on a node without Chrome, reports
+  `viewer/chrome-unavailable` as a skipped check, not a pass.
+
+RED (baseline without the skill): draws Mermaid or ASCII in the reply,
+never writes a JSON spec, never validates, and claims a diagram that does
+not exist on disk.
+
+## S2 — map this repository
+
+Setup: a small fixture repository (about 15 TypeScript files across
+`src/cli`, `src/domains/store`, and `src/domains/api`) with a GitHub
+`origin` remote, a committed `HEAD`, and a codewiki index already built by
+`clio-coder context index`. Prompt: "Map this repository."
+
+Expected:
+- Runs `clio-coder context map --json` before authoring anything.
+- Keeps `meta.repository` (when present) and every seeded `sources` entry;
+  adds line ranges only from `code_nav mode=outline`.
+- Component count stays at or below 12; the `store` area carries
+  `type: "database"`.
+- Runs `validate architecture <seed> --repo-root . --quality standard
+  --json`; 0 errors.
+- Runs `deliver ... --repo-root .`; exit 0; the HTML exists under
+  `.clio-coder/artifacts/maps/`.
+- If the index is missing, tells the user to run `clio-coder context
+  index` instead of inventing components.
+
+RED (baseline without the skill): lists directories from `ls` as
+components with invented edges, no line evidence, no `--repo-root`
+verification, and no delivered HTML.
+
+## Baseline failure modes to watch for
+
+- Authoring coordinates in prose before the first candidate.
+- Reading renderer source before the first candidate.
+- Editing the spec after the final passing validation.
+- Reporting a non-zero `deliver` or a missing Chrome as success.