@gobing-ai/spur 0.3.40 → 0.3.42

package/plugins/sp/skills/spur-cli/references/rules/authoring-rules.md

@@ -0,0 +1,212 @@
+---
+name: authoring-rules
+description: Author new spur constraint rules — evaluator selection, real config shapes, JSON finding schema, smoke-testing.
+see_also:
+  - spur-cli
+---
+
+# Authoring Rules
+
+A rule codifies one constraint as machine-checkable policy. When a new standard or anti-pattern
+emerges, turn it into a rule so the gate catches it forever instead of relying on review.
+
+## Rule anatomy
+
+A rule file is YAML (or JSON) with an optional quoted `$schema` and a `rules:` array. Each rule:
+
+```yaml
+rules:
+  - id: no-console-log          # stable identifier — NEVER rename (CI/reports/suppressions reference it)
+    description: >              # the WHY, not the WHAT. A consuming agent fixes from this line alone.
+      console.log leaks to stdout and breaks --json output. Use the project logger. (ADR-xxx)
+    severity: error             # error | warning | info — see fine-tuning.md
+    evaluator:
+      type: regex               # which check to run
+      config: { mode: forbid, pattern: "console\\.log\\(" }
+    include: ["apps/**/src/**/*.ts"]   # rule-level globs (optional)
+    exclude: ["**/*.test.ts"]
+```
+
+Norms (verified against Spur's own catalog):
+
+- **`description` is a contract.** Encode the reason + a decision reference (`ADR-011`). Spur rules
+  do this in YAML block scalars (`>`). An agent reading a finding fixes from the description.
+- **Group by concern, not by mechanism.** `boundary/dao-boundary.yaml` holds all DAO rules; do not
+  make an `all-regex-rules.yaml`.
+- **Co-locate rationale.** A top-of-file comment explains why the file exists and any re-scoping
+  ("absorbed from ts-libs, re-scoped to Spur's monorepo layout").
+- **Rule IDs are stable.** Renaming an ID silently breaks every downstream reference. Pick a good
+  name once.
+
+## Evaluator selection
+
+Pick the narrowest evaluator that expresses the constraint. Decision order:
+
+```
+Is it a structural code pattern (throw a string, await in loop, specific call shape)?
+  → sg (ast-grep). AST-aware, won't match comments/strings. Requires the `sg` CLI.
+Is it a text pattern (forbidden/required substring or regex)?
+  → rg if the pattern is ripgrep-dialect-safe (fast, ReDoS-immune, parallel)
+  → regex if it needs lookbehind (?<=) or backreferences (\1)  [rg can't compile these]
+Is it about imports / package boundaries?
+  → forbidden-import (block specifiers) or import-boundary (scoped architectural seams)
+Is it about files existing / not existing?
+  → path / file-exist
+Is it about test presence for sources?
+  → test-location (with a ts/python/go/rust resolver)
+Is it about coverage thresholds?
+  → coverage-gate (reads lcov.info)
+Is it about doc comments on exports?
+  → tsdoc-export
+Is it a hardcoded-secret scan?
+  → secrets-scanner
+Is it a JSON schema artifact's structure?
+  → schema-artifact
+Can none of the built-ins express it?
+  → exit-code: run any command, gate on its exit status (escape hatch)
+```
+
+## Real config shapes
+
+These match Spur's live catalog and differ from the README's simplified examples — copy from here.
+
+### regex / rg — forbidden or required text
+
+```yaml
+- id: no-debugger
+  description: Do not commit debugger statements
+  severity: error
+  evaluator:
+    type: regex                 # use `rg` instead if pattern is dialect-safe
+    config: { mode: forbid, pattern: "\\bdebugger\\b" }
+  include: ["apps/**/src/**/*.ts"]
+```
+
+`mode: require` flips the meaning — the finding fires when the pattern is *absent*. `rg` rules run
+the real ripgrep CLI: no lookbehind, no backreferences. Use `isRipgrepCompatiblePattern(pattern)`
+(exported by `@gobing-ai/ts-rule-engine`) or the `rg-migration` preset to check before promoting a
+`regex` rule to `rg`.
+
+### forbidden-import — block specifiers in a scope
+
+The real shape uses `forbidden: [{ specifier }]` + a `scope` block (NOT a flat `forbidden: [string]`):
+
+```yaml
+- id: ts-db-only-in-domain
+  description: "@gobing-ai/ts-db may only be imported inside packages/domain. (ADR-011)"
+  severity: error
+  evaluator:
+    type: forbidden-import
+    config:
+      forbidden:
+        - specifier: "@gobing-ai/ts-db"
+        - specifier: "@gobing-ai/ts-db/schema"
+      scope:
+        include: ["apps/**/src/**/*.ts", "packages/config/src/**/*.ts"]
+        exclude: ["**/node_modules/**", "**/tests/**"]
+```
+
+This is an **architecture fitness function** — an architectural decision (ADR-011) made into an
+assertion that runs on every gate. Keep the seam honest without spending review bandwidth.
+
+### coverage-gate — per-file line coverage
+
+The real Spur rule uses `include`/`exclude` globs (not the README's `exemptions` array):
+
+```yaml
+- id: coverage-gate
+  description: "Per-file line coverage meets 90% threshold (read from lcov)"
+  severity: error
+  evaluator:
+    type: coverage-gate
+    config:
+      lcovPath: .coverage/lcov.info     # Spur writes here via bun test --coverage-dir=.coverage
+      threshold: 90
+      include: ["apps/**", "packages/**"]
+      exclude: ["**/node_modules/**"]
+```
+
+Because it reads `lcov.info`, this rule belongs in a **post-test** preset (`recommended-post-check`),
+never the pre-check — there is no coverage file before tests run.
+
+### exit-code — the escape hatch
+
+When no built-in fits, shell out and gate on exit status. Spur's `rg-dialect` meta-rule uses this to
+scan the rule catalog itself with `rg` + `yq`:
+
+```yaml
+- id: rg-evaluator-patterns-are-ripgrep-dialect
+  description: "rg-typed rules must use ripgrep dialect (no lookbehind/backreferences)."
+  severity: error
+  evaluator:
+    type: exit-code
+    config:
+      command: sh
+      args: ["-c", "…script that exits non-zero on violation…"]
+```
+
+This is also how you build **meta-rules** — rules that validate the rule catalog. Any required CLI
+(`rg`, `sg`, `yq`) must be present in every environment that runs the gate, including CI.
+
+## The JSON finding schema (verified against live CLI)
+
+`spur rule run --json` emits:
+
+```json
+{
+  "preset": "recommended-pre-check",
+  "ruleCount": 17,
+  "findings": [
+    {
+      "ruleId": "probe-forbid-shape",
+      "severity": "error",
+      "message": "forbidden pattern found: registerRuleCommand",
+      "filePath": "apps/cli/src/commands/rule.ts",
+      "line": 12,
+      "code": "regex:found"
+    }
+  ],
+  "fixes": []
+}
+```
+
+Field notes (ground truth, not assumptions):
+
+- `line` is **optional** — present on a forbid-match (`code: regex:found`), absent on a require-miss
+  (`code: regex:missing`). Do not assume every finding has a location.
+- `column` is generally **not** present. Locate by `filePath` + `line` (when present) + `message`.
+- `code` is `"<evaluator>:<result>"`, e.g. `regex:found`, `regex:missing`.
+- `fixes` is populated only when a rule declares `fix:` and the engine is invoked with fix authority.
+  **The `spur rule run` CLI never applies fixes** — it surfaces findings. The agent reads the
+  finding and makes the edit itself, then re-runs. (Library `applyFixes()` exists for programmatic
+  consumers only.)
+
+### Evaluator error vs. policy violation (first-class distinction)
+
+A finding with `kind: "error"` and `code: "evaluator:<type>"` and `filePath: null` is **not** a code
+violation — the rule itself crashed (missing `rg`/`sg`/`lcov.info`, or a misconfigured pattern). The
+fix is the rule or the environment, never the source code. Filter them apart:
+
+```ts
+const evaluatorErrors = findings.filter((f) => f.kind === "error");
+const violations = findings.filter((f) => f.kind !== "error");
+```
+
+## Smoke-test a new rule before trusting it
+
+A rule you have not watched fire is a rule you do not trust. Before adding it to a gate preset, run
+the shared **validate-and-smoke-test** core ([operations.md](operations.md#sub-procedure-validate-and-smoke-test)):
+schema/Zod validate → run against a **should-fire** fixture (expect a finding) → run against a
+**should-pass** fixture (expect none). Fixtures follow the
+[convention](operations.md#fixture-convention) `.spur/rules/fixtures/<rule-id>/should-{fire,pass}.<ext>`.
+
+```bash
+spur rule validate --file path/to/new-rule.yaml --json   # 1. schema/Zod
+# 2 & 3: run a FIXTURE-SCOPED copy (include → the fixture path) so the fixture is in scope:
+spur rule run --file /tmp/<id>-fixture-scoped.yaml --rule <id> --fail-on info --json
+```
+
+The smoke-test copy points `include` at the in-repo fixture (the shipped `apps/`/`packages/` scope
+won't match a fixture under `.spur/rules/fixtures/`); never change the shipped rule's scope to match.
+Only after schema-valid AND both directions pass do you fold the rule into a preset (see
+fine-tuning.md → Preset composition).

package/plugins/sp/skills/spur-cli/references/rules/fine-tuning.md

@@ -0,0 +1,148 @@
+---
+name: fine-tuning
+description: Dial in delivery quality — severity, glob scoping, exemptions, preset composition, layering, governance.
+see_also:
+  - spur-cli
+---
+
+# Fine-Tuning Rules and Presets
+
+Authoring a rule is half the work; dialing it in so it catches real problems without crying wolf is
+the other half. A gate with a high false-positive rate gets ignored, and an ignored gate is worthless.
+
+## Severity calibration
+
+Severity drives the `--fail-on` gate. Choose by blast radius:
+
+| Severity | Use when | Gate behavior |
+| -------- | -------- | ------------- |
+| `error` | Breaks delivery: security, architecture seam, broken build | Blocks at `--fail-on error` (default) |
+| `warning` | Should fix, won't break prod: style, missing docs | Blocks only at `--fail-on warning` |
+| `info` | Advisory / informational | Blocks only at `--fail-on info` |
+
+Default `--fail-on error` means warnings and info never fail the gate unless you ask. Reserve `error`
+for things you are willing to block a commit on; over-using `error` trains people to bypass the gate.
+
+## Glob scoping: the FP/FN dial
+
+The single biggest source of false positives is a loose include glob; the biggest source of false
+negatives is a missing nesting level.
+
+- **Tighten `include`** to exactly the files the rule should police. A boundary rule for app source
+  is `apps/**/src/**/*.ts`, not `apps/**`.
+- **`exclude` the legitimate exceptions**: tests, generated code, the one package allowed to break
+  the rule. Spur's `ts-db-only-in-domain` excludes `**/tests/**` and the domain schema dir.
+- **Loose-match footgun (`regex`/`rg`/`forbidden-import`/`secrets-scanner`).** These evaluators match
+  files in *loose* mode: the engine strips every `*`/`**` from your glob and matches the remainder by
+  **substring / suffix**, not by true glob. So `apps/**/src/**/*.ts` effectively becomes the fragment
+  `apps/src/.ts` and matches any path containing it. Practical consequences: write `include` as a
+  **distinctive path fragment** (`apps/cli/src`, `/src/`, `.ts`) and lean on `exclude` for carve-outs;
+  don't assume a precise multi-level glob narrows the way it reads. `coverage-gate`, `test-location`,
+  and `path` use stricter glob matching — the loose behavior is specific to the content-scanning
+  evaluators above. (Verified against `ts-rule-engine` `matchesAny`.)
+
+Rule-level `include`/`exclude` scopes one rule; some evaluators (`forbidden-import`,
+`coverage-gate`) take their own `scope`/`include` inside `config` — use the evaluator's own scoping
+when present (see authoring-rules.md for the real shapes).
+
+## Exemptions for known-legitimate cases
+
+When one file legitimately violates a rule, prefer a scoped `exclude` with a rationale comment over
+disabling the whole rule:
+
+```yaml
+evaluator:
+  type: forbidden-import
+  config:
+    scope:
+      include: ["packages/**/src/**/*.ts"]
+      exclude:
+        - "packages/domain/src/schema/**"   # the ONE place drizzle is allowed (ADR-011)
+```
+
+Never widen `exclude` just to make the gate green — that is gate-gaming (see SKILL.md gotchas).
+
+### Exclusions are exceptions, not a whitelist
+
+The chronic failure mode of refining is **exclusion creep**: each carve-out looks justified on its own,
+but they accumulate until the rule's `exclude` hollows out its `include` and the rule enforces almost
+nothing — a blocklist degraded into a de-facto allowlist. The per-change overlap check does not catch
+this (it guards rule-vs-rule collision, not erosion of a rule's own coverage), so guard it explicitly
+when adding any exclusion:
+
+- **Every exclusion earns its place.** It needs a specific, documented reason — the legitimate case
+  *and* why it is legitimate (`# the ONE place X is allowed (ADR-n)`), not a bare path. An exclusion
+  you cannot justify in one line does not belong.
+- **Narrowest possible.** Exclude a single file or the one directory that genuinely must be exempt —
+  never a broad glob that silences a whole tree to dodge one finding.
+- **Accumulation is a smell, not a solution.** When a rule keeps needing more exclusions, the rule's
+  scope is wrong: re-scope its `include`, split it into concern-specific rules, or reconsider whether
+  the policy holds — do not keep carving. A rule whose exclusions cover most of its scope should be
+  re-scoped or retired, not extended.
+- **Test the net.** After adding an exclusion, confirm the rule still fires on the cases it must catch
+  (the should-fire fixture still fires); an exclusion that also suppresses a real violation is a
+  false negative, not an exemption.
+
+## Preset composition
+
+A preset bundles rules for a lifecycle stage. The shape (verified against Spur's presets):
+
+```yaml
+$schema: "@gobing-ai/ts-rule-engine/schemas/preset.schema.json"
+name: recommended-post-check
+extends:                # category DIRECTORIES or other presets, resolved across roots
+  - quality
+  - surface
+disable:                # suppress an inherited rule that doesn't fit this project
+  - legacy-rule
+overrides:              # re-tune an inherited rule without forking it
+  no-console-log:
+    severity: warning
+    fix: { mode: suggest }
+```
+
+- **`extends`** pulls in whole category folders (`quality/`, `surface/`) or named presets.
+- **`disable`** turns off an inherited rule by ID.
+- **`overrides`** changes severity or fix mode of an inherited rule in place — the lever for
+  project-specific tuning without copying the rule.
+
+## Lifecycle-stage presets (Spur's actual layout)
+
+| Preset | Stage | Why it exists |
+| ------ | ----- | ------------- |
+| `recommended-pre-check` | inner loop, before tests | Fast: style, boundaries, structure. No coverage (no lcov yet). |
+| `recommended-post-check` | after tests | Adds `coverage-gate` (needs `.coverage/lcov.info`) + export docs + CLI surface. |
+| `strict-check` | optional deep audit | Hardened runtime/http/rule-file structural boundaries. |
+| `rg-migration` | on-demand, transitional | Meta-rule guarding `rg` patterns against ripgrep-incompatible constructs. |
+
+**Gate ordering rationale (not arbitrary):** cheap, always-available checks run first (pre-check);
+checks that need produced artifacts run after the step that produces them (coverage-gate after
+tests). This minimizes feedback latency — you fail on a style violation in seconds, not after a full
+test run.
+
+## Layering — project shadows bundled
+
+Rule roots resolve highest-priority-first: project `.spur/rules/` → user-global
+(`~/.config/spur/rules`) → bundled (shipped with the package). If two roots contain the same relative
+rule path, the **first wins** and lower roots fill gaps. This is why a project can shadow a single
+bundled rule file while inheriting the rest of the catalog.
+
+Confirm what is actually resolved before assuming:
+
+```bash
+spur rule list --json                          # discovered files + their source layer
+spur rule list --preset recommended-pre-check --json   # the resolved rule set for one preset
+```
+
+## Governance & evolution
+
+- **Where does a rule live?** Project-specific policy → `.spur/rules/`. A rule useful to every
+  consumer of `ts-rule-engine` → propose it upstream in the shared library (per the project's
+  shared-library evolution principle), don't fork it locally.
+- **Track false positives.** There is no built-in FP tracking (a tool gap). Convention: log FP
+  incidents in a YAML comment on the rule; if a rule cannot be tuned below an acceptable FP rate,
+  retire it — a noisy rule erodes trust in the whole gate.
+- **Link intent to decisions.** `description` carries the one-line why; reference the governing ADR
+  so a future maintainer (human or agent) understands the rule before changing it.
+- **Meta-rules keep the catalog honest.** `rg-migration` and the `strict/rule-files-structural`
+  rules validate the rule files themselves — rule governance as code.

package/plugins/sp/skills/spur-cli/references/rules/operations.md

@@ -0,0 +1,228 @@
+---
+name: operations
+description: Named operation procedures (run/scan/add/refine/validate/list), the shared find-existing-coverage and validate-and-smoke-test cores that back the spur rule slash commands.
+see_also:
+  - spur-cli
+---
+
+# Operations
+
+The skill's operations as discrete procedures. The deterministic ones (`run`, `validate`, `list`,
+`trace`) are direct CLI verbs — documented briefly here for completeness, but you run them straight
+(no slash command). The agent-driven ones (`scan`, `add`, `refine`) convert fuzzy intent into a reliable
+sequence and are what the slash commands delegate to; their full steps live below.
+
+A rule you have not watched fire is a rule you do not trust. So both `add` and `refine` end in the
+same verification core ([validate-and-smoke-test](#sub-procedure-validate-and-smoke-test)) — that
+shared core is why a tightened rule is re-checked exactly like a freshly authored one. Behavioral
+rule-testing ("does this rule fire correctly?") is that core, not a separate operation. `scan`, `add`,
+and `refine` also share the [find-existing-coverage](#sub-procedure-find-existing-coverage) core so the
+catalog never diverges no matter which operation touches it.
+
+## Fixture convention
+
+Smoke-testing needs a file the rule **should fire on** and a file it **should stay quiet on**. Without
+a convention, fixtures are invented ad-hoc and verification is not reproducible. Convention:
+
+```
+.spur/rules/fixtures/<rule-id>/should-fire.<ext>   # MUST produce a finding
+.spur/rules/fixtures/<rule-id>/should-pass.<ext>   # MUST produce no finding
+```
+
+`<ext>` matches the rule's target (`.ts` for a TS rule, `.yaml` for a meta-rule, etc.). Keep fixtures
+minimal — the smallest snippet that exercises the constraint. If a caller supplies `--fixture-fire` /
+`--fixture-pass`, use those paths instead; otherwise default to the convention. When neither exists,
+synthesize a fire fixture from the rule's own pattern/intent and a pass fixture by negating it, write
+them to the convention path, then run the core.
+
+**Fixtures must live inside the repo** (`.spur/rules/fixtures/...`) — the engine scans relative to the
+working tree, so an out-of-repo fixture (e.g. under `/tmp`) silently never fires. **Smoke-test runs
+use a copy of the rule with `include` pointed at the fixture fragment** (e.g. `fixtures/<rule-id>`),
+not the shipped rule's `apps/`/`packages/` scope — otherwise the fixture is out of scope and the
+fire-test produces a false negative. The shipped rule's scope is never changed to accommodate a
+fixture. (Verified: an in-repo fixture matched by any distinctive path fragment fires correctly; an
+out-of-repo fixture does not.)
+
+## Sub-procedure: find-existing-coverage
+
+Reconciliation core — run this **before authoring anything**. Authoring without checking the catalog
+breeds redundant, diverged, and contradictory rules (two `no-console` variants, one rule for `apps/**`
+and a twin for `packages/**`, the same concern at conflicting severities). In a layered preset system
+that is silent conflict, not just noise. Inputs: the clarified constraint (one checkable sentence).
+Steps:
+
+1. **Enumerate the catalog** — `spur rule list --json` for every rule ID + source layer, plus grep the
+   rule files for evaluator `type`, `pattern`/`specifier`, and `scope`/`include` so matches are found
+   by *substance*, not just by ID text.
+2. **Classify the strongest match** against the new constraint:
+
+   | Match | Meaning | Action |
+   | ----- | ------- | ------ |
+   | Exact / near-duplicate | A rule already enforces this concern on this scope | **STOP — do not add.** It is covered; if behavior is off, hand to [refine](#refine). |
+   | Same concern, different scope | A twin exists for other paths/specifiers | **EXTEND** — widen the existing rule's globs / add the specifier. One rule, not two. |
+   | Adjacent, same category/file | A sibling rule lives in the file this concern belongs to | **ADD into the existing file** (group by concern); reuse the category's preset wiring. |
+   | No real match | Genuinely new concern | **ADD new** — the only branch that authors from scratch. |
+
+3. **extend vs. refine boundary** (they are close): **extend** = the rule should now *also* cover this
+   case (same intent, wider net → broaden scope / add specifier). **refine** = the rule's *behavior*
+   is wrong (same net, better tuned → severity/scope/FP-FN). If the match means "already covered, you
+   want it tuned," that is refine, not add.
+4. **Recommend + confirm** — report the strongest match, the classification, and the recommended
+   action (extend / refine / add-into-file / add-new). **Require user confirmation before acting** —
+   surface the conflict; the human decides. Never silently duplicate, and never silently edit a rule
+   the user did not name.
+
+Output contract: `{ match: rule-id|none, classification, recommendation, evidence }` + the confirmed
+action to take.
+
+## Sub-procedure: validate-and-smoke-test
+
+The shared verification core. Inputs: a rule file path + a rule ID. Steps:
+
+1. **Schema/Zod validate** — `spur rule validate --file <rule-file> --json`. On error, surface
+   root-cause + fix (see [validate](#validate)); stop until clean. The most common error is an
+   unquoted `$schema` (`@` is YAML-reserved).
+2. **Smoke-test FIRE** — write a copy of the rule whose `include` points at the fire fixture
+   (the shipped scope won't match an in-repo fixture — see [fixture convention](#fixture-convention)),
+   then `spur rule run --file <fixture-scoped-rule> --rule <id> --fail-on info --json`. **Expect a
+   finding.** Zero findings means the rule does not catch what it claims — a false negative; fix the
+   pattern. (Verify the *pattern*, not the shipped scope.)
+3. **Smoke-test PASS** — same fixture-scoped rule against the pass fixture; **expect zero findings**.
+   A finding here is a false positive — fix the pattern (the shipped `include`/`exclude` is tested
+   separately by scoping precision, not by the fixture).
+4. **Report** — `{ schemaValid, firedAsExpected, falsePositiveFree }`. The rule is verified only when
+   all three are true.
+
+> The fixture must be in the rule's scope, or it cannot fire. A rule scoped to `apps/...` won't match
+> a fixture under `.spur/rules/fixtures/<id>/` — and for content-scanning evaluators (`regex`/`rg`/
+> `forbidden-import`/`secrets-scanner`) `include` is matched as a **substring/suffix fragment**, not a
+> true glob (see [fine-tuning.md → loose-match footgun](fine-tuning.md#glob-scoping-the-fpfn-dial)),
+> so the fixture path must contain the rule's scope fragment. Two safe options: (a) keep fixtures
+> under a path the rule's scope already covers, or (b) for the smoke-test run only, point `include` at
+> the fixture path — **never widen the shipped rule's scope to make a fixture match.**
+
+## run (direct CLI — the harness loop)
+
+`spur rule run` is a direct CLI verb; there is no slash command for it. The skill drives the loop when
+asked in natural language. Detailed in SKILL.md → "The harness loop". Procedure:
+
+1. `spur rule run [--preset <name>] [--rule <id>] [--file <path>] [--fail-on <sev>] [--stop-on-first [<sev>]] [--fix-mode <none|suggest|auto>] [--dry-run] --json`
+2. Read the exit code (binary gate) AND `findings[]` (actionable detail).
+3. Split findings: policy violations (fix the code) vs. evaluator errors
+   (`kind: "error"`, `code: "evaluator:<type>"`, `filePath: null` — fix the rule/environment).
+4. Apply the **specific** fix per violation — no drive-by refactors. By default the CLI surfaces
+   findings only; use `--fix-mode auto` to apply mechanically fixable violations, then re-run to
+   confirm green.
+5. Re-run the same command. Loop until exit 0.
+
+Output contract: exit code + parsed findings + violation/evaluator-error split + per-finding fix + optional `fixes[]`/`applied` (when `--fix-mode` ≠ `none`).
+
+## add
+
+Turn a natural-language constraint into a validated, smoke-tested rule. Procedure:
+
+1. **Clarify intent** — restate the constraint as one checkable sentence. If the description is
+   ambiguous (which paths? forbid or require? which severity?), state the interpretation taken.
+2. **Reconcile against the catalog** — run [find-existing-coverage](#sub-procedure-find-existing-coverage).
+   This is mandatory and gating: if it finds the concern already covered, **stop and hand to refine
+   (or extend the existing rule) on confirmation** — do not author a redundant rule. Only the
+   "no real match" branch proceeds to author from scratch below.
+3. **Select evaluator** — apply the decision tree in
+   [authoring-rules.md → Evaluator selection](authoring-rules.md#evaluator-selection)
+   (`sg` for structural, `rg`/`regex` for text, `forbidden-import`/`import-boundary` for imports,
+   `path` for files, `coverage-gate`/`test-location`/`tsdoc-export`/`secrets-scanner`/`schema-artifact`
+   for their specific concerns, `exit-code` as the escape hatch).
+4. **Write config** — use the **real config shapes** from
+   [authoring-rules.md → Real config shapes](authoring-rules.md#real-config-shapes)
+   (not the README's simplified ones). Set `id` (stable, kebab), `description` (the WHY + decision
+   ref), `severity` (see [fine-tuning.md → Severity](fine-tuning.md#severity-calibration)), and tight
+   `include`/`exclude`. Quote `$schema`.
+5. **Place the file** — default `.spur/rules/<category>/<rule-id>.yaml`, grouped by concern (a
+   `--file` arg overrides). One file per concern, not per mechanism.
+6. **Verify** — run the [validate-and-smoke-test core](#sub-procedure-validate-and-smoke-test). Not
+   done until all three checks pass.
+7. **Wire into preset (optional)** — if `--preset <target>` was given, add the rule's category to the
+   preset's `extends` (if not already present), or add the rule file under an extended category. Then
+   `spur rule validate --preset <target> --json` to confirm the preset still resolves. Re-tuning an
+   inherited rule uses `overrides`, not duplication.
+
+Output contract: YAML rule content + destination path + smoke-test result (both directions) + validate
+result. Done only when validate passes AND both smoke-test directions pass.
+
+## refine
+
+Tighten or adjust an existing rule/preset with the smallest change that meets the intent. Procedure:
+
+1. **Locate the target** — if a rule file/preset is named, load it. If the user describes a *concern*
+   instead ("the import-boundary rule is too noisy"), run
+   [find-existing-coverage](#sub-procedure-find-existing-coverage) to resolve which rule they mean
+   before editing. Read its current shape.
+2. **Identify the dimension** from `--intent` and flags:
+   - false positive → tighten `include` or add `exclude` (`--scope`, `--exempt`)
+   - false negative → broaden `include` or fix the pattern
+   - wrong blocking behavior → `--severity`
+   - inherited rule wrong for this project → preset `--disable <id>` or `--override <id>`
+   See [fine-tuning.md](fine-tuning.md) for each mechanism's real shape.
+3. **Apply the smallest change.** Add a rationale comment for any exemption (`# <path> is the one
+   place X is allowed (ADR-n)`). Never widen scope merely to pass a gate — that is gate-gaming.
+   **For any `exclude`/`--exempt` change, apply exclusion discipline**
+   ([fine-tuning.md → Exclusions are exceptions, not a whitelist](fine-tuning.md#exclusions-are-exceptions-not-a-whitelist)):
+   each exclusion must be the narrowest possible, carry a one-line justification, and leave the rule
+   still firing on the cases it must catch. If a rule needs ever more exclusions, re-scope or split it
+   rather than carving further — accumulating carve-outs turns a blocklist into a de-facto allowlist.
+4. **Preview if `--dry-run`** — emit a unified diff of the YAML change and stop (no write). This is a
+   skill-level output; the CLI has no dry-run for edits.
+5. **Verify** — run the [validate-and-smoke-test core](#sub-procedure-validate-and-smoke-test). A
+   refine that improves FP/FN must prove it: the fixture that previously misbehaved now behaves.
+6. **Overlap check (only when the change LOOSENS or WIDENS)** — broadening scope, relaxing a pattern,
+   or lowering severity can make this rule collide with or subsume a sibling — the inverse of add's
+   duplicate problem. Run [find-existing-coverage](#sub-procedure-find-existing-coverage) on the
+   *widened* rule; if it now overlaps another rule's concern/scope, **stop and report the collision**,
+   recommending which rule should own the overlap (merge, or keep the boundary). Require confirmation
+   before persisting a widening that overlaps. Tightening/narrowing changes skip this step.
+7. **Confirm preset (if target was a preset)** — `spur rule validate --preset <name> --json`.
+
+Output contract: diff of the change + validate result + smoke-test result (both directions) + overlap
+verdict on widening changes. With `--dry-run`, the diff only.
+
+## scan
+
+Proactive pattern discovery — survey the codebase for **recurring anti-patterns that should become
+rules**, so the catalog gets ahead of defects instead of only reacting to them. **Propose-only:**
+`scan` discovers and recommends candidates; it does **not** author. Each accepted candidate flows to
+[add](#add) (which reconciles against the catalog) on confirmation. This keeps broad/fuzzy discovery
+cleanly separated from precise/gated authoring. Procedure:
+
+1. **Scope the survey** — default to changed/working-tree code; accept a path/glob to bound it. Heavy
+   scans should run in a forked sub-context so raw output stays out of the main window.
+2. **Hunt recurring patterns** — look for smells that *repeat* (a one-off is not a rule):
+   - the same forbidden construct in multiple files (`console.log`, `debugger`, `as any`, raw `throw "string"`)
+   - ad-hoc boundary violations (a package importing something it shouldn't, repeated)
+   - modules with no corresponding test (systematic, not a single gap)
+   - inconsistent conventions applied unevenly (naming, error handling, logging)
+   Use `rg`/`sg` to count occurrences — evidence is the number of hits across files.
+3. **Cluster into candidate concerns** — group hits by the single concern they imply, and for each
+   pick the evaluator that would catch it ([authoring-rules.md → Evaluator selection](authoring-rules.md#evaluator-selection)).
+4. **Filter against the catalog** — run [find-existing-coverage](#sub-procedure-find-existing-coverage)
+   per candidate. Drop concerns already enforced; mark ones that an existing rule should *extend*
+   (→ refine/extend) vs. genuinely new (→ add).
+5. **Rank and report** — order candidates by occurrence count × severity-of-concern. For each:
+   the concern, evidence (hit count + sample files), proposed evaluator, and the recommended route
+   (`add` new / `refine`-extend existing / skip-already-covered). **Author nothing.**
+
+Output contract: a ranked list of rule candidates, each with `{ concern, evidence, evaluator,
+route: add|extend|covered }`. The user picks which to act on; accepted ones hand off to `add`/`refine`.
+
+## validate / list (direct CLI — no command, no procedure)
+
+Deterministic single-verb CLI calls. Run them straight; the skill interprets results when asked.
+
+- `spur rule validate [--file <path>|--preset <name>|<path>] [--no-schema] --json` — schema + Zod
+  check. Classify any error as **schema** (violates `rule-file.schema.json`/`preset.schema.json` —
+  often an unquoted `$schema`, `@` reserved) vs. **Zod** (regex `config` missing `pattern`, invalid
+  severity, a preset `override`/`disable`/`extends` targeting something that doesn't exist). The
+  `validate-and-smoke-test` core calls this as step 1.
+- `spur rule list --json` — discovered rule files + source layer (project/user/bundled).
+- `spur rule list --preset <name> --json` — the resolved rule set for one preset (after layering).
+
+Use `list` before `refine` to see which rules (and which shadowing layer) are actually in effect.