@iowarp/clio-coder 0.4.6 → 0.4.8

package/library/skills/README.md

@@ -0,0 +1,120 @@
+# Clio skill packages
+
+This tree contains reviewed skill instructions and authoring evidence. Complete
+packages participate in the same [library](../../docs/guide/resource-library.md) as
+plugins, agents, prompts and fleets. Nothing in this source tree loads merely
+because it ships with Clio.
+
+`library/skills/` is the canonical source for Clio Coder's curated skills. The npm
+package includes this tree, `library/plugins/`, and the `library/registry.yaml` index.
+The index points to these bundled directories relative to its own location,
+so discovery and installation work from a source checkout or an installed
+package without fetching the library from GitHub. Skill provenance URLs point
+back to this repository; they do not replace the bundled package source.
+
+## Install and use
+
+```bash
+clio-coder library search research --kind skill
+clio-coder library install skill:grill-me --project --dry-run
+clio-coder library install skill:grill-me --project
+clio-coder library skills --all --json
+clio-coder library update skill:grill-me --project
+clio-coder library disable skill:grill-me --project
+clio-coder library remove skill:grill-me --project
+```
+
+In a session, `/library skill` browses skill packages and `/skill <name> [task]`
+activates one. Installed skill packages live beneath the selected scope's
+`plugins/<name>/`, with one complete-tree digest and the common package state.
+Unmanaged local `SKILL.md` files still load from established Clio and foreign
+resource roots. Foreign project imports and interop-adopted resources retain
+their trust requirements. Plugin resource roots are the packaged resource tier;
+harness extensions do not contribute skills.
+
+Installations, updates and active resource trees belong to the operator. Models
+may draft outside active roots and inspect or validate the result, but recognized
+model shell mutations of library packages are refused at every autonomy level.
+Interactive offers commit only after the bound operator answer. Skill tool
+restrictions last for the session until replaced or cleared with `/skill off`;
+worker activations remain scoped to their run. A skill can narrow tools but never
+grant authority the host disallows.
+
+## Source organization
+
+| Directory | Subject |
+| --- | --- |
+| `coding/` | Implementation, structural search, prototyping and tests |
+| `context/` | Repository orientation and task handoff |
+| `git/` | Tickets, patches, worktrees and review closeout |
+| `meta/` | Skill authoring, Clio development, credentials and external tools |
+| `planning/` | Product intent, architecture, requirements and backlog |
+| `research/` | Literature, experiments, scientific debugging and modernization |
+| `workflow/` | Interviews, sprint planning, design review and workflow capture |
+
+Each complete package contains `plugin.json`, `SKILL.md`, authored `evals.md`
+scenarios, and any supporting files. Standalone skill manifests set
+`extensions["ai.iowarp.clio"].kind` to `skill`, declare `resources.skills: "."`,
+and declare exactly one skill component at `SKILL.md`. The package name and
+explicit Semantic Version identify the distributable.
+
+Archify's package is an instruction wrapper for an independently installed
+upstream renderer. It does not claim to ship that renderer's executable,
+schemas or examples. Follow the skill's prerequisite check before using it.
+The raw-source overlay helpers and `remote.yaml` remain authoring/preparation
+utilities; the library installs complete, manifest-bearing trees through the
+common package engine.
+
+## Authoring contract
+
+House skills require `name`, `description`, `version`, and `license` frontmatter,
+and a nested `clio-coder:` map with `registry-id`, `source-url`, `provenance`, and
+`eval-status`. Set `audit: pass` after review. Provenance is `designed`, `adapted`,
+or `imported`. Declare optional whole-phrase `triggers` to improve lexical
+matching. `allowed-tools` and `disallowed-tools` must name canonical Clio tools.
+The description should say when to load the skill; detailed procedure belongs
+in the body or supporting references.
+
+Create an `evals.md` beside every house skill with realistic baseline/treatment
+scenarios and explicit expected evidence. Metadata saying scenarios are recorded
+is not a claim that a model evaluation passed. Authors can start by copying the
+standalone skill template from `library/_authoring/templates/skill/` (with `eval-status: scenarios-recorded`
+prior to maintainer review). The existing `skill-craft` skill provides the authoring and review procedure.
+
+```bash
+clio-coder library validate library/skills/workflow/grill-me/SKILL.md
+clio-coder library validate library/skills/workflow/grill-me --json
+pnpm run skills:pin
+pnpm run skills:check
+pnpm run library:pin
+pnpm run library:check
+```
+
+`skills:pin` and `skills:check` retain the authoring audit records in
+`library/skills/registry.yaml` and `library/skills/skill-marketplace.json`. Those normalized
+skill-body hashes describe reviewed instruction content and are advisory
+provenance evidence; they are not library installation pins. `library:pin`
+generates the canonical `library/registry.yaml` from complete package trees.
+`library:check` verifies every distributed byte and runs in release hygiene.
+Changes to scripts, references, manifests or evals require repinning the library
+just as changes to instructions do.
+
+For local publication, run `clio-coder library register <package-root> --user`
+or `--project`, then install its typed reference. Remote index entries require
+an explicit GitHub tree URL, the manifest version and a complete-tree SHA-256.
+Read the [package authoring guide](../../docs/guide/authoring-plugins.md) for the
+portable manifest and component contract.
+
+## Evaluation
+
+Named suite evals belong in the package manifest's `evals` map and run through
+`clio-coder eval validate/run --package skill:<name> --eval <suite>`. The same
+suite contract works for all five package kinds.
+
+The experimental `clio-coder eval skill <name|path>` lane executes authored
+`evals.md` RED/GREEN scenarios. It runs a baseline without the skill, a treatment
+with it, and a judge over the expected evidence. `--scenario` selects a scenario;
+`--target`, `--workspace`, and `--timeout` configure the run. Fixture shell needs
+`--trust-fixtures`; network tools need `--allow-network`. Unmeasured judge output
+is reported separately from a failed treatment. These model-based measurements
+are independent of deterministic package and script validation.

package/library/skills/coding/ast-grep/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: ast-grep
+description: "Structural code search with ast-grep rules: finds code by shape when grep on text is too noisy, and never rewrites it. Not for plain string or filename lookups; use grep or find."
+triggers:
+  - structural code search
+  - ast-grep rule
+  - find calls with this argument shape
+  - find code inside a function
+  - grep returns too much noise
+version: 0.3.0
+license: Apache-2.0
+allowed-tools:
+  - bash
+  - read
+  - write
+  - edit
+  - grep
+  - ls
+clio-coder:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/library/skills/coding/ast-grep
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/coleam00/skills/tree/main/.claude/skills/ast-grep
+  eval-status: scenarios-recorded
+  model-size: any
+  agents:
+    - main
+---
+
+# ast-grep Structural Search
+
+Translate a structural question into an ast-grep rule, prove the rule on a
+tiny example, then scan the real codebase. Never scan first: an untested rule
+that returns nothing tells you nothing.
+
+Search only. Never use `--update-all` / `-U` / `--rewrite`; when matches need
+changing, report them and edit through the normal edit tools.
+
+## Arguments
+
+```text
+/skill ast-grep [--lang <language>] [--path <dir>] <structural question>
+```
+
+- `--lang`: tree-sitter language name (`javascript`, `typescript`, `python`,
+  `rust`, `go`, ...). Omit to infer from the files under `--path`.
+- `--path`: directory or file to scan. Omit to scan the project source
+  directory (`src/` when it exists, otherwise `.`).
+- Everything else is the question: what shape to find, what to exclude.
+
+The five steps below are the plan; do not open a task list for them.
+
+Examples:
+
+- `/skill ast-grep find async functions that await but have no try/catch`
+- `/skill ast-grep --lang python --path app/ find calls to open() outside a with block`
+
+Shell rules for every `bash` call in this workflow: one command per call,
+plain and direct. Never use `$(...)` or backticks; they trigger an approval
+gate that ends a headless run. Always pass rules through a file, never
+through `--inline-rules`, because `$VAR` metavariables inside shell quotes
+produce quoting errors that look exactly like non-matches.
+
+## Step 0 — Check the binary
+
+```bash
+ast-grep --version
+```
+
+If that fails, try the short alias, but verify it is really ast-grep:
+
+```bash
+sg --version
+```
+
+Only an output that starts with `ast-grep` counts. On many Linux systems
+`sg` is the unrelated shadow-utils "switch group" command and prints a
+usage error; that is NOT ast-grep. If neither binary is ast-grep, say so
+(`npm i -g @ast-grep/cli` or `cargo install ast-grep`) and stop. Do not
+fall back to text grep and present it as a structural result.
+
+Use the resolved binary name in every later command.
+
+## Step 1 — Pin down the question
+
+Before writing any rule, write in your reply: the target language; the
+structure to match; what must be included and excluded. If the request is
+ambiguous on any of these, ask one clarifying question. When running
+headlessly, state your reading of the ambiguity and proceed.
+
+## Step 2 — Write a minimal example
+
+Create a scratch directory inside the workspace and write the smallest
+code snippet that MUST match and, when exclusions matter, one that must
+NOT match:
+
+```bash
+mkdir -p .clio-coder/scratch/ast-grep
+```
+
+Then write `.clio-coder/scratch/ast-grep/positive.<ext>` and
+`.clio-coder/scratch/ast-grep/negative.<ext>` with the `write` tool. These
+are the rule's test fixture: one file that must match, one that must not,
+nothing more. Never write under `/tmp`, not even by shell redirection; a
+write outside the workspace needs an approval a headless run cannot give,
+and the call is refused.
+
+## Step 3 — Write the rule, simplest first
+
+Write `.clio-coder/scratch/ast-grep/rule.yml` with the `write` tool.
+Escalate only when the simpler form fails:
+
+1. `pattern` alone for direct shapes: `console.log($ARG)`.
+2. `kind` plus relational rules (`has`, `inside`) for context: "function
+   containing await".
+3. Composite rules (`all`, `any`, `not`) for logic: "has await but no
+   try-catch".
+
+Non-negotiable: every relational rule (`has`, `inside`) carries
+`stopBy: end`, or traversal stops at the first non-matching child and the
+rule silently under-matches.
+
+```yaml
+id: async-no-trycatch
+language: javascript
+rule:
+  all:
+    - kind: function_declaration
+    - has: {pattern: await $EXPR, stopBy: end}
+    - not:
+        has: {pattern: 'try { $$$ } catch ($E) { $$$ }', stopBy: end}
+```
+
+This example is verified against ast-grep 0.45 on JavaScript. When the
+question is this one, use it verbatim. Two facts it encodes that models
+guess wrong: tree-sitter JavaScript and TypeScript have no
+`async_function_declaration` kind (the `async` keyword is a token inside
+`function_declaration`; assert it with `pattern: 'async function $F($$$) { $$$ }'`
+when async matters), and an unknown `kind` fails the whole rule with
+`Kind ... is invalid` (exit 8); answer that error with the tree dump in
+Step 4, never with another guessed name.
+
+Full syntax (atomic, relational, composite rules, metavariables, `constraints`,
+`utils`): read `references/rule_reference.md` when the rule needs more than
+the three forms above.
+
+## Step 4 — Test against the example
+
+```bash
+ast-grep scan --rule .clio-coder/scratch/ast-grep/rule.yml .clio-coder/scratch/ast-grep
+```
+
+The rule must match the positive example and miss the negative one before
+you scan anything real. When it passes, go to Step 5. When it does not,
+debug in this order, changing the rule file with `edit`:
+
+1. Strip the rule to its simplest positive key; re-add parts one at a time.
+2. Confirm every `has`/`inside` has `stopBy: end`.
+3. Dump the tree to check node kinds; never guess a `kind` name:
+
+```bash
+ast-grep run --pattern 'async function f() { await g(); }' --lang javascript --debug-query=cst
+```
+
+(`cst` = every node; `ast` = named nodes only; `pattern` = how ast-grep
+parsed your pattern.) Pipe long dumps through `head -80`. Dump the tree
+only after a test has failed; a dump before the first test is a wasted
+turn.
+
+## Step 5 — Scan the codebase
+
+Simple one-node patterns skip the rule file:
+
+```bash
+ast-grep run --pattern 'console.log($ARG)' --lang javascript src
+```
+
+Rule-based scans:
+
+```bash
+ast-grep scan --rule .clio-coder/scratch/ast-grep/rule.yml src
+```
+
+Scan the requested path, not `.`, so your own fixture under
+`.clio-coder/scratch` does not show up as a match; if it does, drop those
+lines from the report. Add `--json` only when the output feeds further
+processing.
+
+Report matches as `path:line` with a one-line reading of each; do not paste
+raw JSON at the user. Done when the reported matches answer the Step 1
+question and false positives you noticed are either excluded by the rule or
+called out. Delete the scratch files last, naming each file. `rm -r` and
+`rm -f` are hard-blocked by the safety net, so:
+
+```bash
+rm .clio-coder/scratch/ast-grep/positive.js .clio-coder/scratch/ast-grep/negative.js .clio-coder/scratch/ast-grep/rule.yml
+```
+```bash
+rmdir .clio-coder/scratch/ast-grep
+```
+
+## Red flags
+
+- Scanning the codebase with a rule never proven on an example.
+- A `has`/`inside` without `stopBy: end`.
+- A guessed `kind` name instead of a `--debug-query=cst` dump.
+- Any rewrite flag: this skill only reads.
+- Treating shadow-utils `sg` as ast-grep because `command -v sg` succeeded.
+- Cleaning up with `rm -rf`, or writing fixtures under `/tmp`; both are
+  refused in a headless run.
+- Falling back to grep halfway because rule debugging felt slow; fix the
+  rule with Step 4, that is the job.

package/library/skills/coding/ast-grep/evals.md

@@ -0,0 +1,82 @@
+# Evals — ast-grep
+
+Baseline scenarios (run a subagent WITHOUT the skill to capture the gap, then
+WITH the skill to confirm it closes). Rubric is pass/fail per bullet. Status:
+written at port time, not yet executed (`eval-status: untested`).
+
+## S1 — structural search with context
+Setup: find async functions that await something but have no error
+handling.
+
+Fixture:
+```bash
+mkdir -p src
+printf 'async function fetchUser(id) {\n  const res = await fetch("api" + id);\n  return res.json();\n}\n\nmodule.exports = { fetchUser };\n' > src/users.js
+printf 'async function fetchSafe(url) {\n  try {\n    const res = await fetch(url);\n    return await res.json();\n  } catch (err) {\n    return null;\n  }\n}\n\nmodule.exports = { fetchSafe };\n' > src/safe.js
+printf 'function plainSync(a, b) {\n  return a + b;\n}\n\nmodule.exports = { plainSync };\n' > src/plain.js
+```
+
+Expected:
+- Writes a positive and a negative example file before any repo scan.
+- Rule uses `kind` + `has`/`not` with `stopBy: end` on every relational rule.
+- Tests the rule on the examples first; scans the repo only after it passes.
+- Reports matches as path:line, not raw JSON.
+
+## S2 — unknown node kind
+Setup: rule fails to match the example. Prompt continues from S1.
+Expected:
+- Uses `--debug-query=cst` to read the real node kinds; does not guess.
+- Simplifies the rule and re-adds parts instead of abandoning to grep.
+
+## S3 — rewrite temptation
+Setup: user asks "find and fix all console.log calls".
+Expected:
+- Uses ast-grep for the find only; never passes `-U`/`--update-all`.
+- Applies changes through the ordinary edit tools after reading matches.
+
+## Baseline failure modes to watch for (RED)
+- Scanning the whole repo with an untested rule and reporting "no matches".
+- Missing `stopBy: end`, silently under-matching.
+- Escaping errors in `--inline-rules` read as "pattern doesn't match".
+- Guessed `kind:` names that do not exist in the grammar.
+
+## 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 SMOKED: ast-grep binary absent on the eval host (2026-08-13). Needs the binary, then a re-run.
+
+Follow-up (2026-08-13): the durable fix considered here was a typed read-only
+`ast_grep` tool in `src/tools`, which would drop the binary dependency from the
+skill body and let read-only recipes such as `scout` bind structural search
+directly. Not built: a new tool is a new entry in the canonical tool surface,
+which means a name reserved in `core/tool-names.ts`, an action class and
+concurrency rule, admission and profile entries, and prompt-prefix cost paid by
+every run whether or not anyone searches structurally. That is a tool-surface
+decision, not skill-catalog cleanup. Until then the skill stays
+`scenarios-recorded` and its first step is the binary check it already has.
+
+## Battletest record (2026-09-03)
+
+S1 fixture plus `src/orders.js` (one matching `loadOrders`, one non-awaiting
+`noAwait`), `ornith1.5-35b-moe` on mini (llamacpp), `clio-coder run
+--autonomy full-auto --json`, headless, `@ast-grep/cli` 0.45.3 on PATH.
+Ground truth: `src/users.js:1` and `src/orders.js:1` match; `safe.js`,
+`plain.js`, `noAwait` do not.
+
+| run | wall | turns | in / out tokens | outcome |
+|---|---|---|---|---|
+| baseline (no skill) | 565s | 37 | 16.2k / 33.0k | never produced a valid rule (`$($params)` syntax, relational rules without `stopBy: end`, `--inline-rules` quoting); 3 `$(...)` calls; answered by reading the source; scratch left in `.astscratch/` |
+| v0.2.0 | 123s | 13 | 7.9k / 7.1k | correct 2/5 via a proven rule; wrote fixtures to `/tmp` first, then into the workspace; `rm -rf` and `find -delete` hard-blocked, scratch left behind |
+| v0.3.0 first cut | 176s | 13 | 9.8k / 10.5k | correct; dumped the tree before writing any rule; a `/tmp` write via shell redirection refused; `rm -rf` hard-blocked |
+| v0.3.0 | 190s | 24 | 9.5k / 10.9k | correct; zero safety blocks; scratch removed with per-file `rm` + `rmdir`; working tree clean. Spent 10 turns recovering from a guessed `async_function_declaration` kind |
+
+Changes in v0.3.0: `## Arguments` contract; Step 0 verifies `sg --version`
+prints `ast-grep` because `/usr/bin/sg` is shadow-utils on Linux; scratch
+lives in `.clio-coder/scratch/ast-grep/` (a `/tmp` write needs an approval
+a headless run cannot give); rules always go through a file; tree dumps
+only after a failed test; cleanup by named `rm` + `rmdir` because
+`rm -r`/`rm -f` match the `rm-recursive-or-force` damage-control block;
+`edit` added for rule iteration. The example rule was re-verified verbatim
+against 0.45.3 (matches exactly the two expected functions) and the skill
+now says so, plus that an unknown `kind` fails with exit 8 rather than
+matching nothing.

package/library/skills/coding/ast-grep/plugin.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "ast-grep",
+	"version": "0.3.0",
+	"description": "Structural code search with ast-grep rules: finds code by shape when grep on text is too noisy, and never rewrites it. Not for plain string or filename lookups; use grep or find.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"kind": "skill",
+			"resources": {
+				"skills": "."
+			},
+			"components": [
+				{
+					"kind": "skill",
+					"id": "ast-grep",
+					"path": "SKILL.md"
+				}
+			]
+		}
+	}
+}

package/library/skills/coding/coding-standards/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: coding-standards
+description: Correct-by-construction TypeScript rules (errors as values, parse don't validate, illegal states unrepresentable, deep modules) for writing or refactoring TypeScript when the project has not pinned its own standards.
+triggers:
+  - TypeScript coding standards
+  - errors as values
+  - parse don't validate
+  - illegal states unrepresentable
+  - functional core imperative shell
+version: 0.4.0
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - find
+  - ls
+  - code_nav
+  - bash
+  - write
+  - edit
+clio-coder:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/library/skills/coding/coding-standards
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/dmmulroy/skills/tree/main/coding-standards
+  eval-status: scenarios-recorded
+  model-size: any
+  provisional: true
+  agents:
+    - main
+    - coder
+---
+
+# Coding Standards (TypeScript, correct-by-construction)
+
+Reference, not a workflow. Apply to new and refactored code. When rules
+pull in different directions: correctness and debuggability first, then
+these standards, then compatible project conventions; contain incompatible
+existing patterns at the nearest boundary instead of copying them into new
+code, and never rewrite unrelated old code without an explicit migration
+request. **The host project's own documented standards always win over
+this file.**
+
+This skill's tool surface covers the whole write-code loop (read, grep,
+find, ls, code_nav, bash, write, edit) so a solo run can apply the rules
+it names. When it rides along with another skill, the surfaces merge as a
+union, so it never narrows the tools the task in flight needs.
+
+## Arguments
+
+```text
+/skill coding-standards [<task>]
+```
+
+- With a task: do the task, and hold every new or changed TypeScript line
+  to the rules below. Keep using the ordinary `write`, `edit`, and `bash`
+  tools; the standards change what you write, not how you write it.
+- Without a task: answer as a reference. Quote the relevant rule and show
+  a before/after snippet; do not touch the repository.
+
+## How to apply
+
+1. Read the host project's instruction file and one or two existing
+   modules near the change. If the project pins its own conventions on
+   errors, validation, or module layout, those win; note the conflict in
+   one line and follow the host.
+2. Before writing, state in your reply which rules the change touches (for
+   a parser: errors, parse-don't-validate, illegal states; for a service:
+   modules). This is the checklist for the code you are about to write.
+3. Write the code. Then run the project's typecheck (`npx tsc --noEmit` or
+   the repo script) with one plain `bash` call; never use `$(...)` or
+   backticks in the command.
+4. If you want runtime evidence beyond the typecheck, prefer a single
+   `node -e` (or the project's runtime) call. If you must write a smoke
+   script, put it under `.clio-coder/scratch/` and remove it with plain
+   `rm <file>`; `rm -f`, `rm -r`, `find -delete`, and moving files to
+   `/tmp` are all refused by the safety net in a headless run, and every
+   refused attempt is a wasted turn.
+5. Finish with a short audit of the diff against the checklist: each rule
+   either satisfied, or deliberately not, with the reason. `git status`
+   must show only the files the task asked for.
+
+## Errors
+
+- Expected failures are values in the return type, as custom tagged
+  errors; callers handle or return them upward, and the outermost boundary
+  translates them (HTTP response, exit code, retry decision). Use the
+  repo's established result mechanism; absent one, a small local tagged
+  union `{_tag: "ok"|"err", ...}` suffices.
+- Promise rejection is throwing. Catch unclassified third-party rejections
+  inside the owning adapter and translate before they cross its boundary.
+- Throw only for defects: violated invariants, impossible branches,
+  not-yet-implemented paths. A missing config value is an expected startup
+  failure, not a defect.
+- Custom errors carry: a stable `_tag` (`as const`), a useful message,
+  structured context fields, optional `cause: unknown`. Keep error unions
+  precise at module boundaries; broad `AppError` types belong only near
+  entrypoints and rendering.
+
+## Parse, don't validate
+
+- Boundary code turns `unknown` input into domain types before it enters
+  inner code; inner code never re-checks what a parser proved.
+- `parseX(input): Result<X, ParseXError>` for untrusted input; `makeX` for
+  smart construction from typed pieces; `isX` for predicates. A function
+  returning a refined value is a parser — do not name it `validateX`.
+- Schema libraries are boundary parsers, not validators sprinkled through
+  core logic; use the repo's established one. Never pass a schema-inferred
+  transport shape through the application.
+- Brand types where a mix-up is realistic: IDs (`UserId` vs `OrgId`),
+  parsed strings (`EmailAddress`), units (`Milliseconds`, `Bytes`).
+  Construct branded values only through their parser.
+
+## Illegal states unrepresentable
+
+- Lifecycle states are tagged unions, not boolean fields:
+  `{_tag:"Draft"|...}` beats `{isSent, isPaid, sentAt?, paidAt?}`.
+- No behavior-controlling boolean parameters: `createUser(input,
+  {emailVerification:"skip"})`, never `createUser(input, true)`.
+- Push optionality outward: branch or parse before calling, not
+  `undefined` checks inside every callee. `Partial<T>` is not an
+  application input unless partiality is the domain concept.
+
+## Modules
+
+- Three responsibilities, not three mandatory layers: **domain** (meaning,
+  invariants, pure transitions — no I/O, no ambient time or randomness),
+  **application service** (policy and effect ordering through narrow,
+  application-owned ports), **adapter** (one boundary's technology and
+  translation; raw external types never leak out of it). Wire concrete
+  adapters to ports at the composition root only.
+- Deep modules: substantial behavior behind a low-burden interface.
+  Deletion test: removing a module that makes complexity disappear was
+  pass-through waste; removing one that spreads complexity across callers
+  was earning its keep.
+- Audit existing adapters/services before creating one: reuse as-is,
+  extend if cohesive, create new only when reuse would couple wrongly.
+
+## Testing
+
+- Prefer, in order: end-to-end through real public entrypoints;
+  integration through real seams; property tests for pure domain modules;
+  unit tests of meaningful behavior.
+- Never module-mock (`vi.mock`/`jest.mock`). Real seams: injected
+  interfaces, local DB substitutes, in-memory or fake adapters.
+- Assert observable outcomes (returned value, persisted state, emitted
+  event), not call sequences. Tests never bypass parsers or invariants.
+
+## Style and safety
+
+- Strict compiler settings (`strict`, `noUncheckedIndexedAccess`,
+  `exactOptionalPropertyTypes`). Immutable by default (`readonly`,
+  `ReadonlyArray`); mutation stays localized behind precise interfaces.
+- No `any`, no `!`, no `as` casts (`as const` is fine). The rare
+  justified cast carries a `// SAFETY:` comment explaining why the
+  invariant holds and why the type system cannot express it.
+- Direct imports from owning files; no barrel layers by default. Precise
+  file names (`email-address.ts`), never `utils.ts`/`helpers.ts`.
+- Parse env/config at startup into typed config; no `process.env` reads
+  scattered through the app; no import-time side effects outside true
+  entrypoints. Secrets live in `Redacted`-style wrappers, unwrapped only
+  at the adapter that needs the raw value, and never appear in errors,
+  logs, or traces.

package/library/skills/coding/coding-standards/evals.md

@@ -0,0 +1,57 @@
+# Evals — coding-standards
+
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
+bullet. Status: written at port time, not yet executed (`eval-status:
+untested`); skill is marked provisional.
+
+## S1 — new TypeScript module
+Prompt: "add a module that parses and stores webhook payloads."
+Expected:
+- Payload parsed at the boundary into a domain type; `unknown` never
+  travels inward.
+- Expected failures are tagged error values in return types, not throws.
+- No `any`, `!`, or bare `as` casts; state modeled as a tagged union.
+
+## S2 — host-repo conflict
+Setup: repo's own instruction file mandates exceptions for error flow.
+Expected:
+- Host standard wins; skill's preference contained at the boundary, not
+  imposed.
+
+## S3 — test style
+Prompt: "test the new module."
+Expected:
+- Real seams; no vi.mock/jest.mock; assertions on observable outcomes.
+
+## Baseline failure modes to watch for (RED)
+- Thrown errors for expected failures in new code.
+- Boolean-flag APIs and `Partial<T>` inputs.
+- Module mocks and spy-sequence assertions.
+
+## 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. PASS (smoke). Skill loaded and produced its standards plan; judge emitted no parseable bullets (judge truncation, not a skill failure).
+
+## Battletest record (2026-09-03)
+
+S1 fixture: strict `tsconfig.json` (`strict`, `noUncheckedIndexedAccess`,
+`exactOptionalPropertyTypes`), empty `src/`, `typescript` on PATH. Task:
+add `src/webhook.ts` (parse unknown payload to a domain value, in-memory
+store, report invalid payloads to the caller), then run `npx tsc --noEmit`.
+`ornith1.5-35b-moe` on mini (llamacpp), `clio-coder run --autonomy
+full-auto --json`, headless.
+
+| run | wall | turns | in / out tokens | outcome |
+|---|---|---|---|---|
+| baseline (no skill) | 163s | 13 | 4.1k / 9.8k | typechecks; `{ok: boolean}` result with string errors; 5 `as` casts after manual checks |
+| v0.2.0 | 693s | 7 | 4.6k / 42.6k | **no file written.** `allowed-tools: [read, grep]` narrowed the surface so `write` and `dispatch` were blocked (`skill_surface`); the model ended with a design-only report |
+| v0.3.0 | 304s | 14 | 19.4k / 18.0k | typechecks; `_tag` discriminated `Result` and per-field tagged parse errors; 0 throws, 0 `any`, 0 `!`, 0 casts. Lost 5 turns cleaning a smoke script (`rm -f`, `find -delete`, `mv` to `/tmp` all refused) |
+
+Root cause of the v0.2.0 failure: `src/core/skill-activation.ts` enforces
+`allowed-tools` as a hard admission block, so a reference skill that names
+only read tools makes the coding task impossible whenever it is the only
+loaded skill. v0.3.0 declares no tool surface (same pattern as the meta
+reference skills), adds an `## Arguments` contract, a four-line apply
+checklist, and a scratch/cleanup rule (`.clio-coder/scratch/`, plain `rm`)
+so the safety net stops eating turns.