@iowarp/clio-coder 0.4.2 → 0.4.3

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

@@ -7,12 +7,13 @@ triggers:
   - find calls with this argument shape
   - find code inside a function
   - grep returns too much noise
-version: 0.2.0
+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

@@ -7,18 +7,15 @@ triggers:
   - parse don't validate
   - illegal states unrepresentable
   - functional core imperative shell
-version: 0.2.0
+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.

package/skills/coding/prototype/SKILL.md

@@ -7,7 +7,7 @@ triggers:
   - prototype this state model
   - sanity-check this logic
   - what should this UI look like
-version: 0.3.0
+version: 0.4.0
 license: Apache-2.0
 allowed-tools:
   - read
@@ -17,15 +17,14 @@ allowed-tools:
   - git
   - bash
   - write
-  - ask_user
-  - artifact
+  - edit
 clio-coder:
   registry-id: iowarp/clio-coder
   source-url: https://github.com/iowarp/clio-coder/tree/main/skills/coding/prototype
   audit: pass
   provenance: adapted
   origin: https://github.com/mattpocock/skills/tree/main/skills/engineering/prototype
-  eval-status: smoke-checked
+  eval-status: scenarios-recorded
   model-size: any
   agents:
     - main
@@ -36,57 +35,117 @@ clio-coder:
 A prototype is throwaway code that answers a question. Name the question
 first; the question decides the shape.
 
+## Arguments
+
+```text
+/skill prototype [--branch logic|ui] [--subject <path>] <question>
+```
+
+- `--branch`: force the branch from Step 1. Omit to infer it.
+- `--subject`: the file or module the prototype is about. Omit to find it
+  from the question text.
+- Everything else is the question the prototype must answer. If no
+  question is stated, write the one you infer as the first line of your
+  reply and proceed; do not stop to ask when running headlessly.
+
+Examples:
+
+- `/skill prototype sanity-check whether the retry state machine in retry.js feels right`
+- `/skill prototype --branch ui what should the dashboard header look like`
+
+The three steps below are the plan; do not open a task list for them.
+
 ## Step 1 — Pick the branch
 
-From the user's prompt, the surrounding code, or by asking:
+From the question, the surrounding code, or the `--branch` flag:
 
 - **"Does this logic / state model feel right?"** → read
-  `references/LOGIC.md`. Build a single shareable HTML file — free-play
-  controls plus guided walkthroughs — that pushes the state machine through
-  the cases that are hard to reason about on paper, drivable by a
+  `references/LOGIC.md`. Build a single self-contained HTML file: free-play
+  controls plus guided walkthroughs that push the state model through the
+  cases that are hard to reason about on paper, drivable by a
   non-developer.
 - **"What should this look like?"** → read `references/UI.md`. Generate
   several radically different UI variations on one route, switchable via a
   URL parameter.
 
 The branches produce very different artifacts; getting this wrong wastes
-the prototype. Ambiguous and the user unreachable → default by neighborhood
-(backend module → logic; page or component → UI) and state the assumption
-at the top of the prototype.
+the prototype. Ambiguous → default by neighborhood (backend module →
+logic; page or component → UI) and state the assumption at the top of the
+prototype and in your reply.
+
+Read the subject code once, then write down in your reply, before any
+code: the question, the branch, and the three to five cases the prototype
+must exercise. That list is the acceptance bar for Step 2.
 
 ## Step 2 — Build under the prototype rules
 
-1. **Throwaway from day one, marked as such.** Place it near the code it
-   prototypes for, named so a casual reader sees it is not production.
-   Follow the project's existing routing/layout conventions; invent no new
-   top-level structure.
-2. **Trivial to run.** One command in the project's own task runner, or one
-   double-clickable HTML file. No setup thinking required.
+1. **Throwaway from day one, marked as such.** Place it next to the code
+   it prototypes for, named so a casual reader sees it is not production
+   (`<subject>-prototype.html`, `prototype-<slug>/`). Follow the project's
+   existing routing/layout conventions; invent no new top-level structure.
+2. **Trivial to run.** One command in the project's own task runner, or
+   one double-clickable HTML file. No setup thinking required.
 3. **No persistence.** State lives in memory. If the question is itself
    about a database, use a scratch DB or file named "PROTOTYPE — wipe me".
 4. **Skip the polish.** No tests, no error handling beyond runnable, no
    abstractions. Speed of learning is the only quality bar.
 5. **Surface the state.** After every action (logic) or variant switch
    (UI), print or render the full relevant state so the change is visible.
+6. **Write once, then edit.** Write the file once. Subsequent changes go
+   through `edit`; never rewrite the whole file to change a few lines.
+7. **Exercise it headlessly.** For a logic prototype, drive the real
+   module through the Step 1 cases with one `node -e` (or the project's
+   runtime) call and read the output. That transcript is the evidence
+   for the verdict; a verdict from reading code alone is a guess.
+
+Shell rules: run one command per `bash` call, plain and direct. Never use
+`$(...)` or backticks; they trigger an approval gate that ends a headless
+run.
 
 ## Step 3 — Capture and discard
 
-When the question is answered:
+Do these in order. Do not stop after building; a prototype without a
+recorded verdict answered nothing.
+
+1. **Decide.** Write the verdict in one sentence, then the evidence: which
+   Step 1 cases behaved as expected, which did not, and what the model is
+   missing.
+2. **Park the code on a throwaway branch.** Run these as separate `bash`
+   calls, substituting a short slug:
+
+   ```bash
+   git checkout -b prototype/<slug>
+   ```
+   ```bash
+   git add <prototype files>
+   ```
+   ```bash
+   git commit -m "prototype: <question> (throwaway, verdict in message)"
+   ```
+   ```bash
+   git checkout -
+   ```
 
-1. Fold the validated decision into the real code or the relevant plan.
-2. Commit the prototype to a throwaway branch off the main line, and leave
-   a pointer to that branch wherever the work is tracked (issue, plan,
-   handoff).
-3. Record the verdict and the question it settled in the same place.
-4. The main branch keeps only the validated decision — never the prototype.
+   Returning to the original branch removes the committed prototype from
+   the working tree, which is the point: the main line keeps only the
+   validated decision, never the prototype. If the directory is not a git
+   repository, leave the file in place and say so.
+3. **Report.** Your final reply is the record. It names, in this order:
+   the question, the verdict, the evidence, the recommended change to the
+   real code (or "none"), and the branch pointer `prototype/<slug>`. When
+   the work is tracked elsewhere (issue, plan, handoff), the user copies
+   this block there; you do not need a separate report file, and you must
+   not end the run with the `artifact` tool.
 
-Done when the verdict is recorded, the pointer exists, and no prototype
-code remains on the working branch.
+Done when the verdict is in the reply, the pointer exists, and
+`git status` on the working branch shows no prototype files.
 
 ## Red flags
 
-- A prototype quietly growing tests, error handling, or abstractions — it
+- A prototype quietly growing tests, error handling, or abstractions: it
   is becoming production without a decision.
 - Persistence added "just to make it work".
-- The prototype merged to the main line.
+- The prototype merged to the main line, or left untracked on it.
 - Code built before the question was stated.
+- A verdict written without running the cases.
+- Ending the run by writing a report artifact instead of finishing Step 3.

package/skills/coding/prototype/evals.md

@@ -40,3 +40,22 @@ Expected:
 
 One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
 (30B local, llamacpp on mini), full-auto sandbox. PASS. Verdict captured via terminal artifact; code discarded.
+
+## Battletest record (2026-09-03)
+
+S1 fixture, `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) | 207s | 17 | 6.1k / 11.6k | HTML built, verdict written via terminal `artifact`; 7 `tasks` calls; prototype left untracked on main |
+| v0.3.0 | 220s | 10 | 12.3k / 15.8k | logic branch chosen, LOGIC.md read; `edit` blocked by allowed-tools so the 12.5k-char file was rewritten whole; `artifact` ended the run before Step 3; nothing committed |
+| v0.4.0 | 178s | 13 | 6.7k / 10.8k | cases enumerated first; module driven headlessly via `node -e`; branch `prototype/retry-state-machine` created, prototype committed there, `main` clean; reply carries question, verdict, evidence, recommended change, pointer |
+
+Changes in v0.4.0 that closed the gaps: dropped `artifact` (terminal tool,
+`terminate: true`, ends the run before capture-and-discard), added `edit`,
+added an `## Arguments` contract with a headless fallback, made Step 3 an
+explicit sequence of single-command `bash` calls, banned `$(...)` (net ask
+rail even under full-auto), and made the final reply the verdict record.
+Remaining blocked calls in v0.4.0: one `tasks` plan and one read-only
+`git` status; `git` restored to allowed-tools and a one-line "the steps are
+the plan" note added afterwards.