@iowarp/clio-coder 0.4.2 → 0.4.4

package/docs/process/release-cut-checklist.md

@@ -0,0 +1,207 @@
+# Release-Cut Checklist
+
+> **Visual blueprint:** The source checkout includes the complete
+> [Release-Cut Checklist visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/release_checklist_blueprint.html).
+
+This document provides the standard procedure for cutting a release of Clio Coder.
+Releases are cut from an annotated tag on canonical main. The GitHub release is
+produced by GitHub Actions, while package publication to npm is an authorized manual
+step performed by a maintainer. Everything before the authorization boundary is local,
+repeatable, and reversible. Every step following the authorization boundary affects
+canonical remote state or publishes immutable packages.
+
+## Part 1: Candidate Preparation on a Local Compact Branch
+
+Maintainers prepare release candidates on a local-only compact branch named after
+the version without punctuation, such as `v044` for version `0.4.4`. Dotted branch
+names like `v0.4.4` are forbidden because dotted names belong exclusively to immutable
+tags. The canonical repository hosts only `main`, and no release candidate branch is
+ever pushed to canonical origin.
+
+1. Ensure the working tree is clean and updated from canonical origin:
+
+   ```bash
+   git checkout -b v044 origin/main
+   ```
+
+2. Update `version` in `package.json` to the release version.
+
+3. Retitle the active changelog section in `CHANGELOG.md` from `## Unreleased` to
+   `## <version> - YYYY-MM-DD`. The release gate in `scripts/check-release.mjs` requires
+   the first version header to match the version in `package.json`.
+
+4. Commit the release candidate preparation locally:
+
+   ```bash
+   git commit -am "chore(release): prepare <version>"
+   ```
+
+## Part 2: Local Candidate Verification Gate
+
+Run deterministic local checks on the candidate commit before requesting authorization.
+
+1. Execute the release gate:
+
+   ```bash
+   npm run ci:release
+   ```
+
+   This gate runs `npm run ci` followed by `node scripts/check-release.mjs`. It verifies
+   type checking, Biome formatting, hygiene rules, architecture boundary invariants,
+   the build, the contract and smoke test suites, trace-viewer tests, and dist integrity.
+   The packaging audit checks executable entry shebangs, ensures forbidden files like
+   source maps and caches are omitted, verifies runtime resources from `scripts/release-manifest.json`,
+   and enforces size limits (10 MB packed, 50 MB unpacked).
+
+2. Optionally validate a live model turn against a configured target:
+
+   ```bash
+   node dist/cli/index.js run --target <id> --autonomy read-only "Reply with exactly: CLIO_LIVE_OK"
+   ```
+
+3. Run the real-home smoke test against the operator configuration:
+
+   ```bash
+   npm run smoke:real-home -- --target <id> --strict
+   ```
+
+   This runs `scripts/smoke-real-home.sh` using a copy of operator settings in a scratch
+   `CLIO_CODER_HOME`. The `--strict` flag ensures any failing rows from `clio-coder doctor`
+   fail the smoke run.
+
+4. Inspect the npm package contents with a dry run:
+
+   ```bash
+   npm pack --dry-run
+   ```
+
+5. Validate an installed tarball in a clean temporary directory:
+
+   Create a temporary directory, pack the tarball, install it via npm, and verify
+   installed binary lifecycle commands in an isolated environment with an empty `CLIO_CODER_HOME`:
+
+   ```bash
+   clio-coder --version
+   clio-coder --help
+   clio-coder doctor
+   clio-coder uninstall --dry-run
+   ```
+
+## Part 3: Candidate Review and Authorization Boundary
+
+Before touching any remote ref, summarize the candidate for maintainer review:
+- Candidate commit SHA
+- Results of `npm run ci:release`
+- Verification output from real-home smoke and installed package testing
+- Changelog contents and target npm version
+
+Every step below changes canonical remote refs, creates a release, or publishes
+an immutable package. Do not execute any of them without explicit maintainer authorization.
+
+## Part 4: Fast-forward Canonical Main
+
+1. Fetch the latest remote status from origin:
+
+   ```bash
+   git fetch origin
+   ```
+
+2. Confirm `origin/main` is an ancestor of the local candidate branch.
+
+3. Fast-forward local `main` to the candidate commit:
+
+   ```bash
+   git checkout main
+   git merge --ff-only v044
+   ```
+
+4. Verify that local `main` matches the reviewed candidate SHA exactly.
+
+5. Push `main` to canonical origin:
+
+   ```bash
+   git push origin refs/heads/main:refs/heads/main
+   ```
+
+   No release branch is ever pushed to origin.
+
+## Part 5: Tagging and GitHub Release
+
+1. Wait for GitHub Actions CI on canonical `main` to finish green for the pushed SHA.
+
+2. Create an annotated git tag matching the version:
+
+   ```bash
+   git tag -a v<version> -m "Clio Coder <version>"
+   ```
+
+3. Push only the release tag to canonical origin:
+
+   ```bash
+   git push origin refs/tags/v<version>
+   ```
+
+4. Pushing the tag triggers `.github/workflows/release.yml`. The workflow:
+   - Verifies the tag matches `package.json`.
+   - Runs `npm run ci:release` on the tagged commit.
+   - Packs the release tarball with `npm pack`.
+   - Extracts the version changelog section from `CHANGELOG.md`.
+   - Creates the GitHub Release with the tarball attached using `gh release create`.
+
+5. Inspect the GitHub Actions workflow run and confirm the GitHub release is published.
+
+## Part 6: Package Publication to npm
+
+Publishing to npm is a manual maintainer step performed from the tagged commit.
+
+1. Confirm authentication and registry status:
+
+   ```bash
+   npm whoami
+   ```
+
+2. Confirm the version does not already exist on npm:
+
+   ```bash
+   npm view @iowarp/clio-coder@<version>
+   ```
+
+3. Publish the package from the tagged checkout:
+
+   ```bash
+   npm publish
+   ```
+
+   The `prepublishOnly` lifecycle script sets `CLIO_CODER_RELEASE_CONTEXT=publish` and
+   re-executes `npm run ci:release` as a mandatory release-mode verification gate before
+   files are uploaded. When publishing a pre-release channel, append `--tag <channel>`.
+
+## Part 7: Post-Publish Verification and Branch Closeout
+
+1. Verify package availability on npm:
+
+   ```bash
+   npm view @iowarp/clio-coder version
+   ```
+
+2. On a clean machine, install the package globally and run basic lifecycle checks:
+
+   ```bash
+   npm install -g @iowarp/clio-coder@<version>
+   clio-coder --version
+   clio-coder doctor
+   ```
+
+3. Remove the local compact candidate branch:
+
+   ```bash
+   git branch -d v044
+   ```
+
+   The canonical repository remains in its steady state containing only `main` and immutable tags.
+
+## Part 8: Rollback and Error Recovery
+
+npm package publication is irreversible. A published version cannot be removed or overwritten.
+Any issue discovered after publication must be resolved through a subsequent release. Prior
+to pushing git tags or publishing to npm, local candidate commits can be amended or reset freely.

package/docs/process/scientific-validation.md

@@ -5,19 +5,19 @@
 
 Scientific software development cannot treat simple file presence as proof of correctness. A simulation script that crashes on rank 48, or writes out NetCDF arrays filled with `NaN`s, may still successfully write a file to the disk. 
 
-Clio Coder recognizes **scientific validation contract files** as an opt-in signal for a higher evidence bar. Currently, the session rigor resolver does not parse or enforce a scientific contract schema. The presence of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md` at the workspace root raises the default rigor level to `high`; the file contents are advisory material for developers, project agents, and external validators.
+Clio Coder recognizes a **scientific validation contract** as an opt-in signal for a higher evidence bar. One strict loader in `src/domains/safety/validation-contract.ts` reads the first of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, or `validation.yml` at the workspace root and parses it under the version-1 schema below. A contract that parses raises the default rigor level to `high`. A contract that does not parse (empty, malformed YAML, unknown field, unsupported version, over the 256 KiB cap) leaves rigor at `normal` and is diagnosed with the exact fault: `clio-coder doctor` reports it in the `validation contract` row, the interactive session prints it once at startup, and `clio-coder verifiers author` repeats it. A Markdown `VALIDATION.md` is recognized as present but is never parsed and never raises rigor on its own; it is advisory prose for developers, project agents, and external validators.
 
-This advisory convention is separate from the executable project verifier catalog at `.clio-coder/verifiers.yaml`. The verifier catalog has a strict version-1 schema and admits exact argv vectors to the `verify` tool. Scientific validation contracts and handbook expectations do not grant command authority: prose such as `validators: ["python tools/check_grid.py"]` remains guidance until the project owner confirms the equivalent argv, cwd, timeout, and tags in `verifiers.yaml`. The executable catalog does not interpret numerical tolerances or artifact expectations; it only runs the explicitly declared process vector through safe-exec.
+This advisory convention is separate from the executable project verifier catalog at `.clio-coder/verifiers.yaml`. The verifier catalog has a strict schema (version 2, with version 1 still loading) and admits exact argv vectors to the `verify` tool. Scientific validation contracts and handbook expectations do not grant command authority: prose such as `validators: ["python tools/check_grid.py"]` remains guidance until the project owner confirms the equivalent argv, cwd, timeout, and tags in `verifiers.yaml`. The executable catalog runs only the explicitly declared process vector through safe-exec; a `numeric-compare` or `perf-budget` entry adds a judgement of that command's output or wall time, never an interpretation of the contract's artifact expectations.
 
-`clio-coder verifiers author` can inspect top-level `validators` entries in the YAML contract filenames above and propose catalog checks. It labels those vectors as project-declared and shows their source index, exact argv, cwd, timeout, tags, catalog path, and resulting execution authority. This inspection is read-only. A command string with sound quoting and no shell operator can be represented as argv for review; shell expansion, pipes, redirection, environment assignments, incomplete quoting, and Markdown prose receive a manual JSON-argv diagnostic. Nothing becomes executable and nothing is dry-run until the operator confirms the catalog write with `--yes`.
+`clio-coder verifiers author` reads the parsed contract's `validators` entries through the same loader and proposes catalog checks. It labels those vectors as project-declared and shows their source index, exact argv, cwd, timeout, tags, catalog path, and resulting execution authority. This inspection is read-only. A command string with sound quoting and no shell operator can be represented as argv for review; shell expansion, pipes, redirection, environment assignments, incomplete quoting, and Markdown prose receive a manual JSON-argv diagnostic. Nothing becomes executable and nothing is dry-run until the operator confirms the catalog write with `--yes`.
 
-The convention below is a recommended shape for scientific projects that need to document expected dimensions, attributes, numerical tolerances, scheduler context, and verification commands for scientific artifacts. Developed at the [Gnosis Research Center (GRC)](https://grc.iit.edu) at Illinois Tech as part of the NSF-funded scientific-software context (NSF Award [#2411318](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2411318)), this convention links execution metadata with physical output checks without claiming that the current harness executes those checks automatically.
+The convention below is a recommended shape for scientific projects that need to document expected dimensions, attributes, numerical tolerances, scheduler context, and verification commands for scientific artifacts. Developed at the [Gnosis Research Center (GRC)](https://grc.iit.edu) at Illinois Tech as part of the NSF-funded scientific-software context (NSF Award [#2411318](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2411318)), this convention links execution metadata with physical output checks; the harness executes a check only through a matching `verifiers.yaml` entry.
 
 ---
 
 ## Validation Contract Convention
 
-A validation contract can be stored as YAML or Markdown. A custom or project-level agent (such as a local `scientific-validator` agent example under `.clio-coder/agents/`) or the developer can draft these files and commit them next to the research code. Clio core currently checks only for the documented filenames at the workspace root.
+A validation contract is a YAML file under the version-1 schema; `VALIDATION.md` is the Markdown companion for prose that the schema cannot hold. A custom or project-level agent (such as a local `scientific-validator` agent example under `.clio-coder/agents/`) or the developer can draft these files and commit them next to the research code. The loader rejects unknown fields at every level and names the field it rejected, so a typo is a diagnostic rather than a silently ignored key.
 
 ### Example netCDF / Slurm validation contract:
 ```yaml
@@ -69,12 +69,14 @@ checks:
     tags: [scientific, netcdf]
 ```
 
-### Suggested Fields:
-1. **`version`:** Set to `1` for project-local compatibility.
-2. **`runtime.kind`:** Document execution mode (`local`, `slurm`, `mpi`, or `other`).
-3. **`artifacts`:** List output files or directories the validation plan should inspect.
-4. **`preserve`:** Project convention for artifacts that should not be deleted by cleanup workflows. Clio's built-in protected-artifact guard is separate and is driven by live `protect_path` effects, not by this YAML field.
-5. **`validators`:** List shell commands or scripts a verifier should run to validate the generated files.
+### Schema (version 1):
+Every field except `version` is optional. Strings are capped at 4096 bytes (`notes` at 16 KiB), `artifacts` at 256 entries, `validators` at 128, `runtime.modules` at 64, and each map at 256 keys; a diagnostic cites the cap it crossed.
+1. **`version`:** Required, exactly `1`.
+2. **`task`:** One string describing the work the contract covers.
+3. **`runtime`:** `kind` is required and one of `local`, `slurm`, `mpi`, or `other`; `nodes` and `ranks` are positive integers, `walltime` is a string, and `modules` is a list of strings.
+4. **`artifacts`:** Each entry needs `path`; `format` is a string, `expected_dimensions` maps names to non-negative integers, `expected_attributes` maps names to strings, `numerical_tolerances` holds `relative`, `absolute` (finite non-negative numbers), and `ulp` (non-negative integer), and `preserve` is a boolean. `preserve` is a project convention for cleanup workflows; Clio's built-in protected-artifact guard is separate and is driven by live `protect_path` effects, not by this field.
+5. **`validators`:** A list of command strings a verifier should satisfy. They remain prose until the project declares matching `verifiers.yaml` entries.
+6. **`notes`:** Free text.
 
 ---
 
@@ -88,8 +90,7 @@ Comparing floating-point values in scientific computations must accommodate roun
 | **`absolute`** | $|val - ref| \le absolute$ | Additive difference check. Used when reference value is close to `0`. |
 | **`ulp`** | $StepsBetween(val, ref) \le ulp$ | Unit in the Last Place. Measures floating-point representation steps. |
 
-> [!NOTE]
-> Clio core does not currently execute tolerance comparisons and does not apply a default numerical tolerance. Put defaults directly in project validators or contract text.
+Tolerances become executable through a `kind: numeric-compare` entry in `.clio-coder/verifiers.yaml` (catalog version 2). The entry's `command` prints a JSON object of `string -> number | number[]` on stdout, `reference` names a repository-relative JSON file of the same shape, and `tolerance` names at least one of `relative`, `absolute`, or `ulp`. A value passes only when it satisfies every tolerance given; a key missing on either side fails with the key named, arrays compare elementwise and fail on length mismatch, and any `NaN` or infinity fails. The report lists each key's worst deviation and which tolerance it failed, and it is recorded on the `verify` result and on the host-verification check of a dispatch receipt. Clio applies no default tolerance: the catalog entry states it. `clio-coder verifiers author` proposes one such entry for every contract artifact that declares `numerical_tolerances`, with the command left for the operator to fill, so nothing runs until the operator confirms an exact argv. A `kind: perf-budget` entry judges the command's wall time the same way against a `budget` or a recorded baseline; see [Tool usage](../guide/tool-usage.md#project-verifier-catalog).
 
 ---
 
@@ -112,12 +113,12 @@ Scheduler-driven runs require distinct validation handling compared to local uni
 - **Queue status is not validation**: Checking if a Slurm command like `sbatch` exits successfully only proves that the Slurm scheduler accepted the job script. A good contract tells the verifier how to check actual simulation artifacts inside `out/` or `ckpt/` after job completion.
 - **Environment module loading**: The `runtime.modules` array can document the exact software stack dependencies (such as `intel/2024`, `openmpi/5.0`) that must be loaded before running the validators.
 - **HPC and Data Integration**: For large-scale allocations such as those at the Argonne Leadership Computing Facility (ALCF), projects can archive verification logs through their own storage or data-transfer workflow. Clio core does not manage Globus transfers.
-- **Validator execution**: In the current alpha version, contract validation is advisory. Quality/verification agents (such as the base `verifier` agent or custom project-level agents) read the contract to guide developers and write out verification receipts. Automated in-harness contract execution is not implemented yet.
+- **Validator execution**: A parsed contract's `artifacts` and `validators` are requirements the `verifier` agent and custom project-level agents must satisfy, and they are executable only through `verifiers.yaml` entries. Automated in-harness execution of the contract itself is not implemented.
 
 ### How a Validation Contract Raises Session Rigor
 
 Clio Coder integrates scientific validation contracts directly into its safety model to raise the evidence standard automatically:
-- **Automatic Escalation**: At startup, Clio scans the workspace root. The presence of any validation contract (e.g. `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md`) automatically escalates the session's rigor level from `normal` to `high`.
-- **High-Rigor Gate Requirements**: Once the rigor is raised to `high`, the finish gate is active. It engages on a settled `turn_end` only when the recent window contains successful workspace mutation evidence and no validation evidence or explicit limitation. The window is entries since the last user message, capped at 80 entries:
+- **Parsed contract escalates**: At startup and at every finish-gate decision, `rigorResolution()` in `src/domains/safety/rigor.ts` loads the contract. A contract that parses raises the session's rigor level from `normal` to `high` with source `validation-contract`. An unparseable contract yields `normal` with source `invalid-contract` and the fault as the diagnostic; a Markdown-only workspace yields `normal` with source `markdown-advisory`. `CLIO_CODER_RIGOR` still overrides both directions.
+- **High-Rigor Gate Requirements**: Once the rigor is `high`, the finish gate is active. It engages on a settled `turn_end` only when the recent window contains successful workspace mutation evidence and no validation evidence or `limitation` receipt. The window is entries since the last user message, capped at 80 entries:
   - Clio issues a `request_continuation` middleware effect to keep the session running.
-  - Clio injects a dynamic warning reminder (`HIGH_RIGOR_REVALIDATION_MESSAGE`) instructing the agent to run a verification command or to declare a limitation before it can conclude the turn.
+  - Clio injects a dynamic warning reminder (`HIGH_RIGOR_REVALIDATION_MESSAGE`) instructing the agent to run a verification command or to call `limitation` before it can conclude the turn.

package/evals/behavioral-machinery-support.ts

@@ -133,6 +133,7 @@ export function dispatchStubContext(): DomainContext {
 		health: { status: "healthy", lastCheckAt: null, lastError: null, latencyMs: null },
 		capabilities: { ...runtime.defaultCapabilities },
 		discoveredModels: [],
+		discoveredModelsSource: "none",
 	}));
 	const fallbackStatus = statuses[0];
 	if (fallbackStatus === undefined) throw new Error("behavioral machinery requires one target");

package/evals/behavioral-machinery.yaml

@@ -12,7 +12,7 @@ suite:
 matrix:
   dimensions: []
   targets:
-    - id: local
+    - id: default
   repeats: 1
 tasks:
   - id: architect-positive

package/evals/behavioral-model.yaml

@@ -67,6 +67,7 @@ tasks:
     metrics:
       collect: &metrics
         [task.solved, claims.unsupported, completion.reported, tools.calls.read, tools.calls.dispatch,
+        tools.succeeded.dispatch,
         tools.blocked.bash, tools.read.distinctPaths, tools.read.outsideAllowed, tools.read.decoyHits]
       readObservation:
         allowedPaths: [evals/fixtures/behavioral-main.ts]
@@ -137,10 +138,10 @@ tasks:
       expectedBehavior:
         - id: delegation-chooses-dispatch
           category: tool_choice
-          fact: {source: tool, key: tools.calls.dispatch, op: gte, value: 1}
+          fact: {source: tool, key: tools.succeeded.dispatch, op: gte, value: 1}
         - id: delegation-occurs
           category: delegation
-          fact: {source: tool, key: tools.calls.dispatch, op: gte, value: 1}
+          fact: {source: tool, key: tools.succeeded.dispatch, op: gte, value: 1}
         - id: delegation-grounded
           category: claim_grounding
           fact: {source: grader, key: claims.unsupported, op: eq, value: 0}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@iowarp/clio-coder",
-	"version": "0.4.2",
+	"version": "0.4.4",
 	"description": "The terminal coding agent for people who maintain the code that science runs on, with user-chosen models and inspectable evidence.",
 	"keywords": [
 		"ai",
@@ -80,7 +80,7 @@
 		"test": "node --import tsx --import ./tests/harness/tmp-root.ts --test tests/contracts/*.test.ts tests/smoke/*.test.ts",
 		"test:trace-viewer": "npm --prefix apps/trace-viewer test",
 		"trace:ui": "node apps/trace-viewer/server.mjs",
-		"ci": "npm run typecheck && npm run lint && npm run skills:check && npm run build && npm run test && npm run test:trace-viewer",
+		"ci": "npm run typecheck && npm run lint && npm run build && npm run test && npm run test:trace-viewer",
 		"ci:release": "npm run ci && node scripts/check-release.mjs",
 		"install:local": "bash scripts/install-local.sh",
 		"smoke:real-home": "bash scripts/smoke-real-home.sh",

package/skills/README.md

@@ -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,12 @@ 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. See [Skill tool surface narrowing](../docs/architecture/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)

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.