@iowarp/clio-coder 0.3.1 → 0.3.2

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

@@ -0,0 +1,136 @@
+---
+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.
+version: 0.1.0
+license: Apache-2.0
+allowed-tools:
+  - bash
+  - read
+  - write
+  - grep
+  - ls
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/coding/ast-grep
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/coleam00/skills/tree/main/.claude/skills/ast-grep
+  eval-status: scenarios-recorded
+  model-size: any
+  agents:
+    - main
+---
+
+# ast-grep Structural Search
+
+Translate a structural question into an ast-grep rule, prove the rule on a
+tiny example, then scan the real codebase. Never scan first: an untested rule
+that returns nothing tells you nothing.
+
+Search only. Never use `--update-all` / `-U` / `--rewrite`; when matches need
+changing, report them and edit through the normal edit tools.
+
+## Step 0 — Check the binary
+
+```bash
+command -v ast-grep || command -v sg
+```
+
+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.
+
+## 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.
+
+## 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.
+
+## Step 3 — Write the rule, simplest first
+
+Escalate only when the simpler form fails:
+
+1. `pattern` alone for direct shapes: `console.log($ARG)`.
+2. `kind` plus relational rules (`has`, `inside`) for context: "function
+   containing await".
+3. Composite rules (`all`, `any`, `not`) for logic: "has await but no
+   try-catch".
+
+Non-negotiable: every relational rule (`has`, `inside`) carries
+`stopBy: end`, or traversal stops at the first non-matching child and the
+rule silently under-matches.
+
+```yaml
+# /tmp/astgrep-rule.yml
+id: async-no-trycatch
+language: javascript
+rule:
+  all:
+    - kind: function_declaration
+    - has: {pattern: await $EXPR, stopBy: end}
+    - not:
+        has: {pattern: 'try { $$$ } catch ($E) { $$$ }', stopBy: end}
+```
+
+Full syntax (atomic, relational, composite rules, metavariables, `constraints`,
+`utils`): read `references/rule_reference.md` when the rule needs more than
+the three forms above.
+
+## Step 4 — Test against the example
+
+```bash
+ast-grep scan --rule /tmp/astgrep-rule.yml /tmp/astgrep-example.js
+```
+
+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:
+
+1. Strip the rule to its simplest positive key; re-add parts one at a time.
+2. Confirm every `has`/`inside` has `stopBy: end`.
+3. Dump the tree to check node kinds — never guess a `kind` name:
+
+```bash
+ast-grep run --pattern '<target code>' --lang javascript --debug-query=cst
+```
+
+(`cst` = every node; `ast` = named nodes only; `pattern` = how ast-grep
+parsed your pattern.)
+
+## Step 5 — Scan the codebase
+
+Simple one-node patterns skip the rule file:
+
+```bash
+ast-grep run --pattern 'console.log($ARG)' --lang javascript .
+```
+
+Rule-based scans:
+
+```bash
+ast-grep scan --rule /tmp/astgrep-rule.yml <path>
+```
+
+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.
+
+## Red flags
+
+- Scanning the codebase with a rule never proven on an example.
+- A `has`/`inside` without `stopBy: end`.
+- A guessed `kind` name instead of a `--debug-query=cst` dump.
+- Any rewrite flag: this skill only reads.
+- 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

@@ -0,0 +1,56 @@
+# Evals — ast-grep
+
+Baseline scenarios (run a subagent WITHOUT the skill to capture the gap, then
+WITH the skill to confirm it closes). Rubric is pass/fail per bullet. Status:
+written at port time, not yet executed (`eval-status: untested`).
+
+## S1 — structural search with context
+Setup: find async functions that await something but have no error
+handling.
+
+Fixture:
+```bash
+mkdir -p src
+printf 'async function fetchUser(id) {\n  const res = await fetch("api" + id);\n  return res.json();\n}\n\nmodule.exports = { fetchUser };\n' > src/users.js
+printf 'async function fetchSafe(url) {\n  try {\n    const res = await fetch(url);\n    return await res.json();\n  } catch (err) {\n    return null;\n  }\n}\n\nmodule.exports = { fetchSafe };\n' > src/safe.js
+printf 'function plainSync(a, b) {\n  return a + b;\n}\n\nmodule.exports = { plainSync };\n' > src/plain.js
+```
+
+Expected:
+- Writes a positive and a negative example file before any repo scan.
+- Rule uses `kind` + `has`/`not` with `stopBy: end` on every relational rule.
+- Tests the rule on the examples first; scans the repo only after it passes.
+- Reports matches as path:line, not raw JSON.
+
+## S2 — unknown node kind
+Setup: rule fails to match the example. Prompt continues from S1.
+Expected:
+- Uses `--debug-query=cst` to read the real node kinds; does not guess.
+- Simplifies the rule and re-adds parts instead of abandoning to grep.
+
+## S3 — rewrite temptation
+Setup: user asks "find and fix all console.log calls".
+Expected:
+- Uses ast-grep for the find only; never passes `-U`/`--update-all`.
+- Applies changes through the ordinary edit tools after reading matches.
+
+## Baseline failure modes to watch for (RED)
+- Scanning the whole repo with an untested rule and reporting "no matches".
+- Missing `stopBy: end`, silently under-matching.
+- Escaping errors in `--inline-rules` read as "pattern doesn't match".
+- Guessed `kind:` names that do not exist in the grammar.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. NOT SMOKED: ast-grep binary absent on the eval host (2026-08-13). Needs the binary, then a re-run.
+
+Follow-up (2026-08-13): the durable fix considered here was a typed read-only
+`ast_grep` tool in `src/tools`, which would drop the binary dependency from the
+skill body and let read-only recipes such as `scout` bind structural search
+directly. Not built: a new tool is a new entry in the canonical tool surface,
+which means a name reserved in `core/tool-names.ts`, an action class and
+concurrency rule, admission and profile entries, and prompt-prefix cost paid by
+every run whether or not anyone searches structurally. That is a tool-surface
+decision, not skill-catalog cleanup. Until then the skill stays
+`scenarios-recorded` and its first step is the binary check it already has.

package/skills/coding/ast-grep/references/rule_reference.md

@@ -0,0 +1,297 @@
+# ast-grep Rule Reference
+
+This document provides comprehensive documentation for ast-grep rule syntax, covering all rule types and metavariables.
+
+## Introduction to ast-grep Rules
+
+ast-grep rules are declarative specifications for matching and filtering Abstract Syntax Tree (AST) nodes. They enable structural code search and analysis by defining conditions an AST node must meet to be matched.
+
+### Rule Categories
+
+ast-grep rules are categorized into three types:
+
+* **Atomic Rules**: Match individual AST nodes based on intrinsic properties like code patterns (`pattern`), node type (`kind`), or text content (`regex`).
+* **Relational Rules**: Define conditions based on a target node's position or relationship to other nodes (e.g., `inside`, `has`, `precedes`, `follows`).
+* **Composite Rules**: Combine other rules using logical operations (AND, OR, NOT) to form complex matching criteria (e.g., `all`, `any`, `not`, `matches`).
+
+## Anatomy of an ast-grep Rule Object
+
+The ast-grep rule object is the core configuration unit defining how ast-grep identifies and filters AST nodes. It's typically written in YAML format.
+
+### General Structure
+
+Every field within an ast-grep Rule Object is optional, but at least one "positive" key (e.g., `kind`, `pattern`) must be present.
+
+A node matches a rule if it satisfies all fields defined within that rule object, implying an implicit logical AND operation.
+
+For rules using metavariables that depend on prior matching, explicit `all` composite rules are recommended to guarantee execution order.
+
+### Rule Object Properties
+
+| Property | Type | Category | Purpose | Example |
+| :--- | :--- | :--- | :--- | :--- |
+| `pattern` | String or Object | Atomic | Matches AST node by code pattern. | `pattern: console.log($ARG)` |
+| `kind` | String | Atomic | Matches AST node by its kind name. | `kind: call_expression` |
+| `regex` | String | Atomic | Matches node's text by Rust regex. | `regex: ^[a-z]+$` |
+| `nthChild` | number, string, Object | Atomic | Matches nodes by their index within parent's children. | `nthChild: 1` |
+| `range` | RangeObject | Atomic | Matches node by character-based start/end positions. | `range: { start: { line: 0, column: 0 }, end: { line: 0, column: 10 } }` |
+| `inside` | Object | Relational | Target node must be inside node matching sub-rule. | `inside: { pattern: class $C { $$$ }, stopBy: end }` |
+| `has` | Object | Relational | Target node must have descendant matching sub-rule. | `has: { pattern: await $EXPR, stopBy: end }` |
+| `precedes` | Object | Relational | Target node must appear before node matching sub-rule. | `precedes: { pattern: return $VAL }` |
+| `follows` | Object | Relational | Target node must appear after node matching sub-rule. | `follows: { pattern: import $M from '$P' }` |
+| `all` | Array<Rule> | Composite | Matches if all sub-rules match. | `all: [ { kind: call_expression }, { pattern: foo($A) } ]` |
+| `any` | Array<Rule> | Composite | Matches if any sub-rules match. | `any: [ { pattern: foo() }, { pattern: bar() } ]` |
+| `not` | Object | Composite | Matches if sub-rule does not match. | `not: { pattern: console.log($ARG) }` |
+| `matches` | String | Composite | Matches if predefined utility rule matches. | `matches: my-utility-rule-id` |
+
+## Atomic Rules
+
+Atomic rules match individual AST nodes based on their intrinsic properties.
+
+### pattern: String and Object Forms
+
+The `pattern` rule matches a single AST node based on a code pattern.
+
+**String Pattern**: Directly matches using ast-grep's pattern syntax with metavariables.
+
+```yaml
+pattern: console.log($ARG)
+```
+
+**Object Pattern**: Offers granular control for ambiguous patterns or specific contexts.
+
+* `selector`: Pinpoints a specific part of the parsed pattern to match.
+  ```yaml
+  pattern:
+    selector: field_definition
+    context: class { $F }
+  ```
+
+* `context`: Provides surrounding code context for correct parsing.
+
+* `strictness`: Modifies the pattern's matching algorithm (`cst`, `smart`, `ast`, `relaxed`, `signature`).
+  ```yaml
+  pattern:
+    context: foo($BAR)
+    strictness: relaxed
+  ```
+
+### kind: Matching by Node Type
+
+The `kind` rule matches an AST node by its `tree_sitter_node_kind` name, derived from the language's Tree-sitter grammar. Useful for targeting constructs like `call_expression` or `function_declaration`.
+
+```yaml
+kind: call_expression
+```
+
+### regex: Text-Based Node Matching
+
+The `regex` rule matches the entire text content of an AST node using a Rust regular expression. It's not a "positive" rule, meaning it matches any node whose text satisfies the regex, regardless of its structural kind.
+
+### nthChild: Positional Node Matching
+
+The `nthChild` rule finds nodes by their 1-based index within their parent's children list, counting only named nodes by default.
+
+* `number`: Matches the exact nth child. Example: `nthChild: 1`
+* `string`: Matches positions using An+B formula. Example: `2n+1`
+* `Object`: Provides granular control:
+  * `position`: `number` or An+B string.
+  * `reverse`: `true` to count from the end.
+  * `ofRule`: An ast-grep rule to filter the sibling list before counting.
+
+### range: Position-Based Node Matching
+
+The `range` rule matches an AST node based on its character-based start and end positions. A `RangeObject` defines `start` and `end` fields, each with 0-based `line` and `column`. `start` is inclusive, `end` is exclusive.
+
+## Relational Rules
+
+Relational rules filter targets based on their position relative to other AST nodes. They can include `stopBy` and `field` options.
+
+### inside: Matching Within a Parent Node
+
+Requires the target node to be inside another node matching the `inside` sub-rule.
+
+```yaml
+inside:
+  pattern: class $C { $$$ }
+  stopBy: end
+```
+
+### has: Matching with a Descendant Node
+
+Requires the target node to have a descendant node matching the `has` sub-rule.
+
+```yaml
+has:
+  pattern: await $EXPR
+  stopBy: end
+```
+
+### precedes and follows: Sequential Node Matching
+
+* `precedes`: Target node must appear before a node matching the `precedes` sub-rule.
+* `follows`: Target node must appear after a node matching the `follows` sub-rule.
+
+Both include `stopBy` but not `field`.
+
+### stopBy and field: Refining Relational Searches
+
+**stopBy**: Controls search termination for relational rules.
+
+* `"neighbor"` (default): Stops when immediate surrounding node doesn't match.
+* `"end"`: Searches to the end of the direction (root for `inside`, leaf for `has`).
+* `Rule object`: Stops when a surrounding node matches the provided rule (inclusive).
+
+**field**: Specifies a sub-node within the target node that should match the relational rule. Only for `inside` and `has`.
+
+**Best Practice**: When unsure, always use `stopBy: end` to ensure the search goes to the end of the direction.
+
+## Composite Rules
+
+Composite rules combine atomic and relational rules using logical operations.
+
+### all: Conjunction (AND) of Rules
+
+Matches a node only if all sub-rules in the list match. Guarantees order of rule matching, important for metavariables.
+
+```yaml
+all:
+  - kind: call_expression
+  - pattern: console.log($ARG)
+```
+
+### any: Disjunction (OR) of Rules
+
+Matches a node if any sub-rules in the list match.
+
+```yaml
+any:
+  - pattern: console.log($ARG)
+  - pattern: console.warn($ARG)
+  - pattern: console.error($ARG)
+```
+
+### not: Negation (NOT) of a Rule
+
+Matches a node if the single sub-rule does not match.
+
+```yaml
+not:
+  pattern: console.log($ARG)
+```
+
+### matches: Rule Reuse and Utility Rules
+
+Takes a rule-id string, matching if the referenced utility rule matches. Enables rule reuse and recursive rules.
+
+## Metavariables
+
+Metavariables are placeholders in patterns to match dynamic content in the AST.
+
+### $VAR: Single Named Node Capture
+
+Captures a single named node in the AST.
+
+* **Valid**: `$META`, `$META_VAR`, `$_`
+* **Invalid**: `$invalid`, `$123`, `$KEBAB-CASE`
+* **Example**: `console.log($GREETING)` matches `console.log('Hello World')`.
+* **Reuse**: `$A == $A` matches `a == a` but not `a == b`.
+
+### $$VAR: Single Unnamed Node Capture
+
+Captures a single unnamed node (e.g., operators, punctuation).
+
+**Example**: To match the operator in `a + b`, use `$$OP`.
+
+```yaml
+rule:
+  kind: binary_expression
+  has:
+    field: operator
+    pattern: $$OP
+```
+
+### $$$MULTI_META_VARIABLE: Multi-Node Capture
+
+Matches zero or more AST nodes (non-greedy). Useful for variable numbers of arguments or statements.
+
+* **Example**: `console.log($$$)` matches `console.log()`, `console.log('hello')`, and `console.log('debug:', key, value)`.
+* **Example**: `function $FUNC($$$ARGS) { $$$ }` matches functions with varying parameters/statements.
+
+### Non-Capturing Metavariables (_VAR)
+
+Metavariables starting with an underscore (`_`) are not captured. They can match different content even if named identically, optimizing performance.
+
+* **Example**: `$_FUNC($_FUNC)` matches `test(a)` and `testFunc(1 + 1)`.
+
+### Important Considerations for Metavariable Detection
+
+* **Syntax Matching**: Only exact metavariable syntax (e.g., `$A`, `$$B`, `$$$C`) is recognized.
+* **Exclusive Content**: Metavariable text must be the only text within an AST node.
+* **Non-working**: `obj.on$EVENT`, `"Hello $WORLD"`, `a $OP b`, `$jq`.
+
+The ast-grep playground is useful for debugging patterns and visualizing metavariables.
+
+## Common Patterns and Examples
+
+### Finding Functions with Specific Content
+
+Find functions that contain await expressions:
+
+```yaml
+rule:
+  kind: function_declaration
+  has:
+    pattern: await $EXPR
+    stopBy: end
+```
+
+### Finding Code Inside Specific Contexts
+
+Find console.log calls inside class methods:
+
+```yaml
+rule:
+  pattern: console.log($$$)
+  inside:
+    kind: method_definition
+    stopBy: end
+```
+
+### Combining Multiple Conditions
+
+Find async functions that use await but don't have try-catch:
+
+```yaml
+rule:
+  all:
+    - kind: function_declaration
+    - has:
+        pattern: await $EXPR
+        stopBy: end
+    - not:
+        has:
+          pattern: try { $$$ } catch ($E) { $$$ }
+          stopBy: end
+```
+
+### Matching Multiple Alternatives
+
+Find any type of console method call:
+
+```yaml
+rule:
+  any:
+    - pattern: console.log($$$)
+    - pattern: console.warn($$$)
+    - pattern: console.error($$$)
+    - pattern: console.debug($$$)
+```
+
+## Troubleshooting Tips
+
+1. **Rule doesn't match**: Use `dump_syntax_tree` to see the actual AST structure
+2. **Relational rule issues**: Ensure `stopBy: end` is set for deep searches
+3. **Wrong node kind**: Check the language's Tree-sitter grammar for correct kind names
+4. **Metavariable not working**: Ensure it's the only content in its AST node
+5. **Pattern too complex**: Break it down into simpler sub-rules using `all`

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

@@ -0,0 +1,113 @@
+---
+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."
+version: 0.1.0
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+clio:
+  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
+  model-size: any
+  provisional: true
+  agents:
+    - main
+    - coder
+---
+
+# Coding Standards (TypeScript, correct-by-construction)
+
+Reference, not a workflow. Apply to new and refactored code. When rules
+pull in different directions: correctness and debuggability first, then
+these standards, then compatible project conventions; contain incompatible
+existing patterns at the nearest boundary instead of copying them into new
+code, and never rewrite unrelated old code without an explicit migration
+request. **The host project's own documented standards always win over
+this file.**
+
+## Errors
+
+- Expected failures are values in the return type, as custom tagged
+  errors; callers handle or return them upward, and the outermost boundary
+  translates them (HTTP response, exit code, retry decision). Use the
+  repo's established result mechanism; absent one, a small local tagged
+  union `{_tag: "ok"|"err", ...}` suffices.
+- Promise rejection is throwing. Catch unclassified third-party rejections
+  inside the owning adapter and translate before they cross its boundary.
+- Throw only for defects: violated invariants, impossible branches,
+  not-yet-implemented paths. A missing config value is an expected startup
+  failure, not a defect.
+- Custom errors carry: a stable `_tag` (`as const`), a useful message,
+  structured context fields, optional `cause: unknown`. Keep error unions
+  precise at module boundaries; broad `AppError` types belong only near
+  entrypoints and rendering.
+
+## Parse, don't validate
+
+- Boundary code turns `unknown` input into domain types before it enters
+  inner code; inner code never re-checks what a parser proved.
+- `parseX(input): Result<X, ParseXError>` for untrusted input; `makeX` for
+  smart construction from typed pieces; `isX` for predicates. A function
+  returning a refined value is a parser — do not name it `validateX`.
+- Schema libraries are boundary parsers, not validators sprinkled through
+  core logic; use the repo's established one. Never pass a schema-inferred
+  transport shape through the application.
+- Brand types where a mix-up is realistic: IDs (`UserId` vs `OrgId`),
+  parsed strings (`EmailAddress`), units (`Milliseconds`, `Bytes`).
+  Construct branded values only through their parser.
+
+## Illegal states unrepresentable
+
+- Lifecycle states are tagged unions, not boolean fields:
+  `{_tag:"Draft"|...}` beats `{isSent, isPaid, sentAt?, paidAt?}`.
+- No behavior-controlling boolean parameters: `createUser(input,
+  {emailVerification:"skip"})`, never `createUser(input, true)`.
+- Push optionality outward: branch or parse before calling, not
+  `undefined` checks inside every callee. `Partial<T>` is not an
+  application input unless partiality is the domain concept.
+
+## Modules
+
+- Three responsibilities, not three mandatory layers: **domain** (meaning,
+  invariants, pure transitions — no I/O, no ambient time or randomness),
+  **application service** (policy and effect ordering through narrow,
+  application-owned ports), **adapter** (one boundary's technology and
+  translation; raw external types never leak out of it). Wire concrete
+  adapters to ports at the composition root only.
+- Deep modules: substantial behavior behind a low-burden interface.
+  Deletion test: removing a module that makes complexity disappear was
+  pass-through waste; removing one that spreads complexity across callers
+  was earning its keep.
+- Audit existing adapters/services before creating one: reuse as-is,
+  extend if cohesive, create new only when reuse would couple wrongly.
+
+## Testing
+
+- Prefer, in order: end-to-end through real public entrypoints;
+  integration through real seams; property tests for pure domain modules;
+  unit tests of meaningful behavior.
+- Never module-mock (`vi.mock`/`jest.mock`). Real seams: injected
+  interfaces, local DB substitutes, in-memory or fake adapters.
+- Assert observable outcomes (returned value, persisted state, emitted
+  event), not call sequences. Tests never bypass parsers or invariants.
+
+## Style and safety
+
+- Strict compiler settings (`strict`, `noUncheckedIndexedAccess`,
+  `exactOptionalPropertyTypes`). Immutable by default (`readonly`,
+  `ReadonlyArray`); mutation stays localized behind precise interfaces.
+- No `any`, no `!`, no `as` casts (`as const` is fine). The rare
+  justified cast carries a `// SAFETY:` comment explaining why the
+  invariant holds and why the type system cannot express it.
+- Direct imports from owning files; no barrel layers by default. Precise
+  file names (`email-address.ts`), never `utils.ts`/`helpers.ts`.
+- Parse env/config at startup into typed config; no `process.env` reads
+  scattered through the app; no import-time side effects outside true
+  entrypoints. Secrets live in `Redacted`-style wrappers, unwrapped only
+  at the adapter that needs the raw value, and never appear in errors,
+  logs, or traces.

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

@@ -0,0 +1,34 @@
+# Evals — coding-standards
+
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
+bullet. Status: written at port time, not yet executed (`eval-status:
+untested`); skill is marked provisional.
+
+## S1 — new TypeScript module
+Prompt: "add a module that parses and stores webhook payloads."
+Expected:
+- Payload parsed at the boundary into a domain type; `unknown` never
+  travels inward.
+- Expected failures are tagged error values in return types, not throws.
+- No `any`, `!`, or bare `as` casts; state modeled as a tagged union.
+
+## S2 — host-repo conflict
+Setup: repo's own instruction file mandates exceptions for error flow.
+Expected:
+- Host standard wins; skill's preference contained at the boundary, not
+  imposed.
+
+## S3 — test style
+Prompt: "test the new module."
+Expected:
+- Real seams; no vi.mock/jest.mock; assertions on observable outcomes.
+
+## Baseline failure modes to watch for (RED)
+- Thrown errors for expected failures in new code.
+- Boolean-flag APIs and `Partial<T>` inputs.
+- Module mocks and spy-sequence assertions.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder 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).