@iowarp/clio-coder 0.4.1 → 0.4.3

package/skills/README.md

@@ -12,7 +12,7 @@ Clio's engine discovers *runtime* skills from these roots (see
 - extension roots
 - `~/.agents`, `~/.claude`, `~/.codex`, `~/.config/opencode`, `~/.copilot` → their `skills/` subdir
 - `<clio-config>/skills` (per-user)
-- project `.agents` / `.claude` / `.codex` / `.opencode` / `.github` → their `skills/` subdir (model-visible only with `CLIO_CODER_TRUST_PROJECT_SKILLS=1`; untrusted by default)
+- project `.agents` / `.claude` / `.codex` / `.opencode` / `.github` → their `skills/` subdir (model-visible only when `integrations.projectResources.trustProjectImports` is true; untrusted by default)
 - `.clio-coder/skills` (per-project)
 
 This repo's `skills/` directory is **not** one of those roots, so nothing here
@@ -22,10 +22,10 @@ auto-loads. That gap is deliberate.
 |---|---|---|
 | Location | a discovery root above | `skills/<category>/<name>/` in this repo |
 | Author | any user or harness | Clio authors, reviewed |
-| Provenance | none required | `clio:` block with `registry-id` + `source-url` + `audit: pass` |
+| Provenance | none required | `clio-coder:` block with `registry-id` + `source-url` + `audit: pass` |
 | Auto-loaded | yes | no, as it must be installed |
 
-"Approved" is visible in the frontmatter: a maintainer set `clio.audit: pass`
+"Approved" is visible in the frontmatter: a maintainer set `clio-coder.audit: pass`
 and a `version`. A skill a user wrote themselves carries none of those fields.
 
 ## Catalog
@@ -63,6 +63,7 @@ folder is presentation and provenance, not a namespace.
 | [`worktree-create`](git/worktree-create/) | workflow | Stand up isolated worktrees for parallel branches: detected install/config/health-check, per-worktree verification. |
 | [`worktree-merge`](git/worktree-merge/) | workflow | Integrate finished worktree branches through a throwaway integration branch with per-merge tests and a full final gate. |
 | [`resolve-merge-conflicts`](git/resolve-merge-conflicts/) | workflow | A merge/rebase is stopped on conflicts. Resolves from both sides' reconstructed intent, validates, completes the operation. |
+| [`branch-closeout`](git/branch-closeout/) | workflow | Proves merged work on the canonical base, inspects and removes associated worktrees through Git, deletes local branches safely, and audits surviving repository refs. |
 
 ### `research/` — scientific and literature work
 
@@ -101,11 +102,13 @@ folder is presentation and provenance, not a namespace.
 | [`herdr`](meta/herdr/) | integration | The user asks to launch, drive, or inspect another agent or command in a Herdr pane — including a second Clio Coder instance. Requires `HERDR_ENV=1`. |
 
 Each SKILL.md may declare `allowed-tools` / `disallowed-tools`. After a skill
-loads, Clio enforces that declaration at tool admission until the turn (or
-worker run) ends: calls outside the merged surface are blocked with reason
-code `skill_surface`, with `context` and `ask_user` always admitted. A
-skill can narrow its tool surface but never grant tools the host would not
-allow. Full semantics: docs/safety-model.md, "Skill tool surface narrowing".
+loads, Clio enforces that declaration at tool admission for the rest of the
+session, across the operator's later turns, until another skill replaces it or
+the operator runs `/skill off` (a worker run keeps the run-scoped lifetime):
+calls outside the merged surface are blocked with reason code `skill_surface`,
+with `context` and `ask_user` always admitted. A skill can narrow its tool
+surface but never grant tools the host would not allow. See [Skill tool surface narrowing](../docs/architecture/safety-model.md#skill-tool-surface-narrowing)
+for the full semantics.
 
 ## Install (activate a marketplace skill)
 
@@ -140,8 +143,8 @@ teammate cloning it gets the same behavior.
 
 | Set | Scope | Why |
 |---|---|---|
-| `context-prime`, `context-handoff` | user | Session boundaries follow the operator across every repo; a handoff written in one project is read at the start of the next. |
-| `find-skills`, `skill-craft` | user | Discovery and authoring are things you do to your toolkit, not things a project does. Installing `find-skills` at user scope is also what makes the Clio copy outrank the compat-root one. |
+| `context-prime`, `context-handoff` | user | The workflow is useful in every repo, while each handoff remains scoped to the project where it was written. |
+| `find-skills`, `skill-craft` | user | Discovery and authoring are things you do to your toolkit, not things a project does. A user install outranks copies in shared user compatibility roots. |
 | `credentials` | user | Credential handling is a personal-machine discipline; a repo does not get to define it. |
 | `clio-coder-dev`, `clio-coder-test` | project, in this repo only | They describe Clio's own source tree. Elsewhere they are noise. |
 | `--category git` | project, where `git-master` is used | Branch, PR, and worktree conventions are the repository's, and the recipe binds them by name. |
@@ -150,8 +153,11 @@ teammate cloning it gets the same behavior.
 | `--category coding` | project | `tdd` and `coding-standards` follow the language and the test seams of the checkout. |
 | `--category workflow` | either | `grill-me` and `cut-it` travel with the operator; `design-council` is worth pinning per project when the project has recurring design forks. |
 
-When both scopes carry the same name, project wins: `.clio-coder/skills` outranks the
-user root, which outranks every compat root.
+Collision precedence from lowest to highest is extension, shared user
+compatibility roots, the Clio user root, project compatibility roots,
+`.clio-coder/skills`, then an explicit CLI skill path. Project compatibility
+roots are model-visible only after the project-import trust opt-in; their
+collision rank is still above the user root.
 
 After install, confirm Clio sees it:
 
@@ -176,21 +182,23 @@ both route through `clio-coder skills`. A community skill of the same name is
 commonly present in the compat roots (`~/.agents/skills`,
 `~/.claude/skills`) and drives the external `npx skills` installer, which
 bypasses Clio. Compat roots stay enabled, and the loader resolves name
-collisions by precedence: the Clio user root and `.clio-coder/skills` outrank the
-compat roots. Install the catalog copy so it wins:
+collisions by the precedence above. A user install beats the shared user
+compatibility copy. A project install beats both project and user
+compatibility copies. Install at the scope where the catalog copy must win:
 
 ```bash
-clio-coder skills install find-skills --user   # or --project for one repo
+clio-coder skills install find-skills --user
+clio-coder skills install find-skills --project  # strongest discovered project copy
 ```
 
 ## Publishing: the marketplace index
 
 `npm run skills:pin` writes two files. `registry.yaml` pins content hashes and
 is what drift is measured against. `skill-marketplace.json` is the published
-index: one entry per skill with `name`, `description`, `sourceUrl` (the
-skill's own `clio.source-url`), `version`, `audit`, and `category`. It carries
-no hashes, because duplicating them into a second published artifact only
-creates a way for the two to disagree.
+index: one entry per skill with `name`, `description`, optional `triggers`,
+`sourceUrl` (the skill's own `clio-coder.source-url`), `version`, `audit`, and
+`category`. It carries no hashes, because duplicating them into a second
+published artifact only creates a way for the two to disagree.
 
 A Clio install anywhere points at it and gets bare-name installs from this
 catalog:
@@ -216,12 +224,12 @@ The frontmatter contract has two layers, and the split is the point:
 - **Core keys stay community-standard.** `name`, `description`, `version`,
   `license`, and `allowed-tools` mean exactly what Claude Code and other agent
   loaders expect. No Clio-specific key ever lives at the top level.
-- **Everything Clio-specific nests under one reserved `clio:` mapping.**
+- **Everything Clio-specific nests under one reserved `clio-coder:` mapping.**
   Registry identity, provenance, audit and eval status, agent bindings, model
   guidance — all of it.
 
 The invariant this buys: a Clio skill dropped into any `.claude/skills`
-directory loads and works in Claude Code, which ignores the `clio:` block as
+directory loads and works in Claude Code, which ignores the `clio-coder:` block as
 an unknown key. Loaded by Clio Coder, the same file carries its full
 marketplace metadata. One file, no forks, no lossy export.
 
@@ -230,7 +238,9 @@ Required shape for every catalog skill:
 ```yaml
 ---
 name: <name>                  # lowercase, hyphens, matches the folder
-description: Use when ...     # triggers only, third person, <=1024 chars
+description: <one sentence>   # what it does, plus "Not for X; use Y" routing, <=1024 chars
+triggers:                     # the phrases a user types that should reach it
+  - <phrase>
 version: 0.1.0
 license: Apache-2.0
 allowed-tools:                # optional; community-standard tool narrowing
@@ -248,7 +258,7 @@ clio-coder:
 ---
 ```
 
-Field semantics inside `clio:`:
+Field semantics inside `clio-coder:`:
 
 - `registry-id` names the audited catalog a skill claims membership of; it is
   content, participates in the pinned hash, and survives installs.
@@ -280,16 +290,16 @@ Field semantics inside `clio:`:
 `requires: [skill:<name>, ...]` stays top-level: Clio's loader consumes it for
 dependency warnings, and other harnesses ignore it like any unknown key.
 
-Legacy flat keys (`registry-id`, `source-url`, `audit` at the top level) are
-still read by the loader as a fallback for copies installed before the nested
-form existed; the catalog itself must use the nested form, and `npm run
+The deprecated nested `clio:` mapping and legacy flat keys (`registry-id`,
+`source-url`, `audit` at the top level) are still read as fallbacks for older
+installed copies. The catalog itself must use `clio-coder:`, and `npm run
 skills:check` enforces that.
 
 ### Versioning policy
 
-`version` describes the skill as a working instrument, and the pinned hash
-already records every byte, so the version only moves when the thing an
-operator runs changes:
+`version` describes the skill as a working instrument. The registry separately
+hashes the normalized contents of `SKILL.md`; it does not hash sibling files.
+Move the version whenever the workflow an operator runs changes:
 
 | Change | Version |
 |---|---|
@@ -305,11 +315,11 @@ a broken link or a typo in a step. Nothing in this catalog is 1.0: a major bump
 is reserved for a skill whose triggers change enough that an operator relying on
 the old one would be surprised.
 
-Metadata changes do not bump because `registry.yaml` pins a
-provenance-stripped hash, so content edits are already caught byte-exactly, and
-raising a version for an `eval-status` line would make the number mean two
-different things at once. The trade is deliberate: the version is coarse, the
-hash is exact, and drift detection uses the hash.
+Lifecycle metadata changes do not bump the workflow version. The normalized
+`SKILL.md` hash catches non-stripped frontmatter and body edits; install fields
+such as `source-url` and `audit` are stripped. A sibling `references/`,
+`scripts/`, or `evals.md` change is represented by the required version change
+inside `SKILL.md`, because sibling bytes are not hashed directly.
 
 ## Claude Code interop
 
@@ -317,7 +327,7 @@ The invariant is that a catalog skill dropped unmodified into `.claude/skills`
 loads and runs in Claude Code. Verified against Claude Code 2.1.231:
 `skills/git/ship` copied into a scratch project's
 `.claude/skills/`, invoked headlessly, loaded through the `Skill` tool and
-answered a question about its own body. The `clio:` block is an unknown
+answered a question about its own body. The `clio-coder:` block is an unknown
 frontmatter key there and is ignored.
 
 **`allowed-tools` means the opposite thing in each harness, and that is the one
@@ -353,7 +363,7 @@ The rest of the surface, read from the same build:
 | `allowed-tools` | Grants, as above. Accepts a YAML list or one comma/space-separated string, same as Clio. |
 | `disallowed-tools` | Not read. A Clio denial is not enforced there. |
 | `requires:` | Not read; ignored as an unknown key, so a dependency warning is Clio-only. |
-| `clio:` | Not read; ignored as an unknown key. This is the invariant. |
+| `clio-coder:` | Not read; ignored as an unknown key. This is the invariant. |
 | Unparseable frontmatter | The per-skill load is wrapped in a bare catch: the skill is skipped silently, with no diagnostic. Clio warns instead. |
 | Size | No cap on SKILL.md. Clio rejects over 1 MiB and warns over 50 KiB, the activation delivery cap. |
 | `references/`, `scripts/` subfolders | Not enumerated at load time; they are files the body tells the model to read, which works in both. |
@@ -370,7 +380,7 @@ A skill is "approved for the marketplace" when a maintainer:
 1. Reviews `SKILL.md` against [`skill-craft`](meta/skill-craft/) (trigger-only
    description, checkable completion criteria, progressive disclosure, pruning
    pass, evals present).
-2. Confirms it carries the frontmatter spec above with `clio.audit: pass`.
+2. Confirms it carries the frontmatter spec above with `clio-coder.audit: pass`.
 3. Sets / bumps `version`.
 
 Each skill ships an `evals.md` recording the baseline scenarios it was tested
@@ -396,10 +406,11 @@ catalog where any skill is missing the required frontmatter, `audit: pass`, or
 its `evals.md`, declares a tool name Clio does not have, or carries a
 `source-url` that no longer ends with its catalog path. `npm run skills:check`
 (run in CI) fails on any drift between the catalog and either generated file,
-`registry.yaml` or `skill-marketplace.json`. Pinned hashes are provenance-stripped
-(install-lifecycle stamps like `installed-at` do not count as drift; content
-and registry-identity edits do), so a copy installed via `clio-coder skills install`
-still verifies against its audited source at activation.
+`registry.yaml` or `skill-marketplace.json`. Each pin covers the normalized
+`SKILL.md`, not the whole skill directory. Install-lifecycle stamps such as
+`installed-at` do not count as drift; body, version, and registry-identity
+edits do. A copy installed via `clio-coder skills install` therefore still
+verifies against its audited source at activation.
 
 A skill may declare typed dependencies with `requires: [skill:<name>, ...]`
 frontmatter; the loader warns at load time when a required skill is not

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

@@ -1,18 +1,19 @@
 ---
 name: ast-grep
-description: Use when a code search needs structure, not text — "find all async functions without error handling", "find calls with this argument shape", "find X inside Y" — or when grep returns too much noise to filter. Writes and tests ast-grep rules, then scans the codebase. Search only; never rewrites code. Not for plain string or filename lookups; use grep or find.
+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.1.1
+version: 0.3.0
 license: Apache-2.0
 allowed-tools:
   - bash
   - read
   - write
+  - edit
   - grep
   - ls
 clio-coder:
@@ -36,30 +37,78 @@ 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
-command -v ast-grep || command -v sg
+ast-grep --version
+```
+
+If that fails, try the short alias, but verify it is really ast-grep:
+
+```bash
+sg --version
 ```
 
-If neither exists, say ast-grep is not installed (`cargo install ast-grep` or
-the platform package) and stop. Some installs expose only `sg`; use whichever
-resolved.
+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, state: 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 instead of guessing.
+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
 
-Write the smallest code snippet that MUST match (and, when exclusions matter,
-one that must NOT match) to a scratch file, e.g. `/tmp/astgrep-example.js`.
-This is the rule's test fixture.
+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)`.
@@ -73,7 +122,6 @@ Non-negotiable: every relational rule (`has`, `inside`) carries
 rule silently under-matches.
 
 ```yaml
-# /tmp/astgrep-rule.yml
 id: async-no-trycatch
 language: javascript
 rule:
@@ -84,6 +132,15 @@ rule:
         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.
@@ -91,46 +148,57 @@ the three forms above.
 ## Step 4 — Test against the example
 
 ```bash
-ast-grep scan --rule /tmp/astgrep-rule.yml /tmp/astgrep-example.js
+ast-grep scan --rule .clio-coder/scratch/ast-grep/rule.yml .clio-coder/scratch/ast-grep
 ```
 
-Prefer a rule file over `--inline-rules`: inline YAML in shell needs `$VAR`
-escaped as `\$VAR` (or single quotes), and quoting errors look exactly like
-non-matches.
-
 The rule must match the positive example and miss the negative one before
-you scan anything real. When it does not, debug in this order:
+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:
+3. Dump the tree to check node kinds; never guess a `kind` name:
 
 ```bash
-ast-grep run --pattern '<target code>' --lang javascript --debug-query=cst
+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.)
+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 .
+ast-grep run --pattern 'console.log($ARG)' --lang javascript src
 ```
 
 Rule-based scans:
 
 ```bash
-ast-grep scan --rule /tmp/astgrep-rule.yml <path>
+ast-grep scan --rule .clio-coder/scratch/ast-grep/rule.yml src
 ```
 
-Add `--json` 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.
+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
 
@@ -138,5 +206,8 @@ the scratch files.
 - A `has`/`inside` without `stopBy: end`.
 - A guessed `kind` name instead of a `--debug-query=cst` dump.
 - Any rewrite flag: this skill only reads.
-- Falling back to grep halfway because rule debugging felt slow — fix the
-  rule with Step 4; that is the job.
+- 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/skills/coding/ast-grep/evals.md

@@ -54,3 +54,29 @@ 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/skills/coding/coding-standards/SKILL.md

@@ -1,24 +1,21 @@
 ---
 name: coding-standards
-description: "Use when writing or refactoring TypeScript and the project has not pinned its own conflicting standards — new modules, error-handling design, schema parsing, module boundaries — or when another skill needs a TypeScript standards reference. Correct-by-construction rules: errors as values, parse don't validate, illegal states unrepresentable, deep modules, functional core / imperative shell."
+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.1.1
+version: 0.3.0
 license: Apache-2.0
-allowed-tools:
-  - read
-  - grep
 clio-coder:
   registry-id: iowarp/clio-coder
   source-url: https://github.com/iowarp/clio-coder/tree/main/skills/coding/coding-standards
   audit: pass
   provenance: adapted
   origin: https://github.com/dmmulroy/skills/tree/main/coding-standards
-  eval-status: smoke-checked
+  eval-status: scenarios-recorded
   model-size: any
   provisional: true
   agents:
@@ -36,6 +33,44 @@ 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 declares no tool surface on purpose: it rides along with
+whatever task is in flight (writing, refactoring, reviewing), so it must
+not narrow the tools that task 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

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

@@ -32,3 +32,26 @@ Expected:
 
 One representative scenario via `clio-coder skills eval` 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.