@gobing-ai/spur 0.3.40 → 0.3.42

package/plugins/sp/skills/spur-cli/references/rules/validation-and-extension.md

@@ -0,0 +1,129 @@
+---
+name: validation-and-extension
+description: Validate rule files and presets, extend the engine with custom evaluators/resolvers/formatters, and the CLI-vs-library capability gaps.
+see_also:
+  - spur-cli
+---
+
+# Validation & Extension
+
+## Validating before you trust
+
+`spur rule validate` checks a rule file or preset (schema + Zod) without evaluating it. Always
+validate a rule you authored or edited before wiring it into a gate.
+
+```bash
+spur rule validate .spur/rules/typescript/no-debugger.yaml --json   # validate a file
+spur rule validate --preset strict-check --json                     # validate a preset
+spur rule validate <path> --no-schema --json                        # skip $schema ref, Zod only
+```
+
+What it catches:
+
+- **Schema errors** — the file violates `rule-file.schema.json` / `preset.schema.json` (e.g. unknown
+  key, wrong type). The quoted `$schema` ref is resolved from the bundled package — no network.
+- **Zod errors** — internal validation (e.g. a regex `config` missing `pattern`, an invalid
+  severity, a preset `override` targeting a non-existent rule ID).
+
+A preset validation also surfaces broken `extends` references (a category folder that doesn't exist)
+and invalid `overrides`/`disable` targets.
+
+**`$schema` quoting gotcha:** the value starts with `@`, which YAML treats as reserved. It must be
+quoted: `$schema: "@gobing-ai/ts-rule-engine/schemas/rule-file.schema.json"`. An unquoted value is a
+parse error.
+
+### Meta-rules: validating the catalog itself
+
+Beyond per-file validation, rules can validate the *rule catalog*. Spur ships two:
+
+- `rg-evaluator-patterns-are-ripgrep-dialect` (`rg-migration` preset) — fails if any `type: rg` rule
+  uses lookbehind/backreferences ripgrep can't compile.
+- `strict/rule-files-structural` — structural integrity of the rule YAML files.
+
+Run them as a second-order gate after editing rules:
+
+```bash
+spur rule run --preset rg-migration --fail-on error --json
+```
+
+## Extending the engine
+
+The built-in evaluators cover most needs. When they don't, the library (`@gobing-ai/ts-rule-engine`)
+supports four extension kinds: **resolvers**, **evaluators**, **fixers** (since 0.3.4), and **formatters**.
+Fixer extensions may be loaded from a preset or rule file via the `extensions.fixers` block (gated by
+`allowExtensions`). The other kinds are library-level APIs consumed by code that drives `RuleEngine`
+directly, or by `ts-rule-engine` gaining capabilities upstream.
+
+### Custom evaluator (direct API)
+
+For a check no built-in expresses, register a `RuleEvaluator`:
+
+```ts
+import { RuleEngine, createFinding, type RuleEvaluator } from "@gobing-ai/ts-rule-engine";
+
+const evaluator: RuleEvaluator = {
+  async evaluate(rule, context) {
+    if (!context.workdir.includes("service")) {
+      return { findings: [createFinding(rule, 'workdir must include "service"', null, { code: "custom:not-service" })], fixes: [] };
+    }
+    return { findings: [], fixes: [] };
+  },
+};
+
+const engine = new RuleEngine();
+engine.registerEvaluator("workspace-name", evaluator);
+```
+
+Then a rule references it by `evaluator.type: workspace-name`.
+
+### Preset extensions (declared modules)
+
+A preset can declare extension modules. They are **trust-gated**: disabled unless the caller passes
+`allowExtensions: true` to `loadExtensionsIntoHost()`. Without the flag, loading throws — untrusted
+presets cannot silently register code.
+
+```yaml
+# preset.yaml
+extensions:
+  resolvers:  ["./extensions/custom-resolver.ts"]   # source→test path mapping
+  evaluators: ["./extensions/custom-evaluator.ts"]  # new rule type
+  formatters: ["./extensions/compact-formatter.ts"] # output rendering
+```
+
+```ts
+const loaded = await loadPreset("local", { roots: [".spur/rules"] });
+const engine = new RuleEngine();
+await loadExtensionsIntoHost(engine.host, loaded.extensions, { allowExtensions: true });
+const result = await engine.evaluate(loaded.rules, process.cwd());
+```
+
+Each registered capability is origin-tracked (`builtin`/`extension`/`caller`) so an extension cannot
+silently override a built-in — conflicts are surfaced, not swallowed.
+
+### Custom resolvers and formatters
+
+- **Resolver** — maps a source path to its expected test path for `test-location`. Built-ins:
+  `typescript`, `python`, `go`, `rust`. Author one for non-standard monorepo conventions
+  (`{ name, resolveTestPath(srcRelPath) }`).
+- **Formatter** — renders a `RuleEngineResult` (`{ name, format(result) }`). For team-specific or
+  compact output beyond the built-in `TextFormatter`/`JsonFormatter`.
+
+## Capability gaps (be honest about these)
+
+The library can do more than the CLI currently exposes. When you hit a wall, the gap type tells you
+the fix path:
+
+| Capability | In library? | On `spur rule` CLI? | Fix path |
+| ---------- | ----------- | ------------------- | -------- |
+| Apply fixes (`applyFixes`) | Yes | **Yes** — `--fix-mode auto` applies fixes; `--fix-mode auto --dry-run` previews the diff | Task 0027. Surfaces `evaluateWithFixes` + `applyFixes` from `ts-rule-engine`. |
+| Fix authority `none`/`suggest`/`auto` | Yes (`min(rule, caller)`) | **Yes** — `--fix-mode none\|suggest\|auto` | Task 0027. Maps 1:1 to library `maxFixMode`. |
+| Custom evaluators/resolvers/formatters | Yes (`allowExtensions`) | **No** loading flag | Drive `RuleEngine` from code, or add upstream CLI support. |
+| `EventBus` observability (`rule.*` events, `durationMs`) | Yes | **No** | Library-only; for progress bars/dashboards. |
+| Custom **fixer** providers | **Yes** (`extensions` includes `fixers` since `ts-rule-engine@0.3.4`) | **Yes** (loads via preset or rule-file `extensions.fixers` with `allowExtensions`) | Task 0027 (catalog bump to 0.3.4). Upstream: ts-libs 0023 moved fixers onto the host registry. |
+| FP/FN rate tracking | **No** | No | Tool gap. Convention: track in YAML comments. |
+| Rule-ID rename migration | **No** | No | Tool gap. Don't rename IDs. |
+
+**Per project policy:** when `ts-rule-engine` can't support a Spur need cleanly, prefer enhancing the
+shared package upstream over leaking a workaround into Spur. The remaining gaps above (custom
+evaluator loading via CLI flag, `EventBus` observability, FP/FN tracking, rule-ID migration) are
+`ts-rule-engine` evolution candidates or future CLI surface growth.

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

@@ -0,0 +1,209 @@
+---
+name: spur-cli-rules
+description: "spur-cli noun reference: operate `spur rule` as the project's constraint quality gate across its full lifecycle — run presets, author rules, fine-tune for delivery quality, validate rule files and preset schemas, and extend the engine. The deterministic verifier in the LLM code-delivery loop."
+see_also:
+  - spur-cli
+---
+
+# spur rule — the constraint quality gate
+
+`spur rule` runs declarative YAML constraint rules (powered by `@gobing-ai/ts-rule-engine`) over the
+working tree and reports policy violations. It is the **deterministic verifier** in an LLM delivery
+loop: a coding agent is overconfident, the rule engine is not. Putting the deterministic check inside
+the agent's loop catches forbidden patterns, missing tests, leaked secrets, broken import boundaries,
+and coverage regressions that the agent would otherwise confidently ship.
+
+Operating the gate well is a full lifecycle — not just running it. This skill covers all of it.
+
+## Lifecycle map
+
+| Phase | Activity | Where |
+| ----- | -------- | ----- |
+| **Run & fix** | Gate the diff, interpret findings, self-correct, re-run until green | this file |
+| **Author** | Add a constraint by writing a new rule when a standard/anti-pattern emerges | [rules/authoring-rules.md](rules/authoring-rules.md) |
+| **Fine-tune** | Dial in quality: severity, glob scoping, exemptions, preset `disable`/`overrides`, layering | [rules/fine-tuning.md](rules/fine-tuning.md) |
+| **Validate & extend** | Validate files/presets, smoke-test, add custom evaluators/resolvers/formatters | [rules/validation-and-extension.md](rules/validation-and-extension.md) |
+
+## When to use
+
+Use this skill to:
+
+- **Gate generated code** — run a preset over changes before declaring a task done or committing.
+- **Add a constraint** — codify a new rule (forbidden pattern, import boundary, required test,
+  coverage floor) so the gate enforces it forever. → authoring-rules.md
+- **Fine-tune delivery quality** — adjust severity, scope a rule to kill false positives, exempt a
+  legitimate case, or re-tune an inherited rule via preset `overrides`. → fine-tuning.md
+- **Validate before trusting** — schema/Zod-check a rule file or preset; smoke-test a new rule
+  against known-good/known-bad files. → validation-and-extension.md
+- **Extend the engine** — write a custom evaluator/resolver/formatter when built-ins fall short.
+  → validation-and-extension.md
+- **Interpret a failing gate** — turn `ERROR <rule-id> <file>:<line>` into the exact fix, re-run.
+
+## Operations
+
+The skill's logic divides by **whether the LLM adds value**:
+
+- **Direct CLI** (`run`, `validate`, `list`) — deterministic, single-verb commands. Run them
+  straight: `spur rule run`, `spur rule validate`, `spur rule list`. A slash-command wrapper here
+  would only forward flags and add drift; **there is no command for these — use the CLI**. The skill
+  still drives them when asked in natural language (e.g. interpreting findings, the fix loop below).
+- **Agent-driven** (`scan`, `add`, `refine`) — convert fuzzy human intent into a reliable sequence the
+  CLI cannot express as one verb. `scan` discovers candidate rules; `add`/`refine` author and tune
+  them. These are the operations worth a slash command, and the skill owns all their logic. Full
+  procedures: [rules/operations.md](rules/operations.md).
+
+| Operation | Backed by | Input | Output (done-when) |
+| --------- | --------- | ----- | ------------------ |
+| `run` | `spur rule run` (CLI) | `[--preset <name>] [--rule <id>] [--file <path>] [--fail-on <sev>] [--stop-on-first [<sev>]] [--fix-mode none\|suggest\|auto] [--dry-run] [--verbose]` | Gate to exit 0; findings interpreted, code fixed, re-run clean (the harness loop below) |
+| `validate` | `spur rule validate` (CLI) | `[file-or-preset] [--file <path>] [--preset <name>] [--kind file\|preset] [--no-schema]` | Schema + Zod verdict |
+| `list` | `spur rule list` (CLI) | `[--preset <name>]` | Discovered files + source layer, or resolved rules for a preset |
+| `trace` | `spur rule trace` (CLI) | `[run-id] [--preset <name>] [--status done\|failed] [--since <iso>] [--last <n>]` | Persisted rule-run history / per-run detail |
+| `scan` | agent procedure | `[<path-or-glob>]` | **Propose-only** discovery: surveys code for recurring anti-patterns, clusters them, filters against the catalog, and reports ranked rule candidates (`add` new / `refine`-extend / already-covered). Authors nothing → [scan](rules/operations.md#scan) |
+| `add` | agent procedure | `"<nl-description>" [--file <path>] [--preset <target>]` | **First reconciles against the existing catalog** (extend/refine an existing rule rather than duplicate, on confirmation); only a genuinely new concern is authored, then **validated AND smoke-tested both directions** (fires on bad, quiet on good); optionally wired into a preset → [add](rules/operations.md#add) |
+| `refine` | agent procedure | `<rule-file-or-preset> [--intent "<goal>"] [--severity <sev>] [--scope <glob>] [--exempt <path>] [--disable <id>] [--override <id>] [--dry-run]` | Smallest change meeting the intent, re-validated and re-smoke-tested; `--dry-run` emits a diff only → [refine](rules/operations.md#refine) |
+
+`scan`, `add`, and `refine` are not CLI verbs. `add`/`refine` compose `validate` + `run` around a
+generated/edited YAML rule and both end in the same **validate-and-smoke-test** core
+([operations.md](rules/operations.md#sub-procedure-validate-and-smoke-test)) so a tightened rule
+is verified exactly like an authored one. They also share the **find-existing-coverage** core
+([operations.md](rules/operations.md#sub-procedure-find-existing-coverage)): `add` runs it up
+front (don't duplicate), `refine` runs it to locate a target and to catch overlap after a widening,
+and `scan` runs it to filter candidates against the catalog. Behavioral rule-testing (does a rule fire
+correctly?) is not a standalone operation — it **is** the verify core, invoked by `add` and `refine`.
+
+## The harness loop (run → interpret → fix → re-run)
+
+```
+generate / edit code
+        │
+        ▼
+spur rule run --preset recommended-pre-check --json   ← deterministic gate
+        │
+   exit 0? ──yes──▶ proceed to tests / commit
+        │ no
+        ▼
+parse findings[] → apply the SPECIFIC fix per finding → re-run
+        │
+        └──────────── loop until exit 0 ◀──────────────
+```
+
+Two signals, two purposes: the **exit code** is the binary pass/fail (the gate); the **`findings[]`**
+carry the actionable detail (what to fix). Always use `--json` when an agent consumes the result.
+
+### Step 1: Run
+
+```bash
+spur rule run --json                                              # fast inner-loop (default preset)
+spur rule run --preset recommended-pre-check --fail-on error --json
+spur rule run --preset recommended-post-check --fail-on error --json   # final gate (after tests)
+```
+
+`spur rule run` exits non-zero when a finding meets `--fail-on` (default `error`). A non-zero exit
+means **not done**. `--stop-on-first error` fails fast while iterating; drop it for the final pass to
+surface every violation.
+
+### Step 2: Interpret
+
+Each finding has `ruleId`, `severity`, `message`, `filePath`, optional `line`, and `code`. Two kinds:
+
+- **Policy violation** — code broke a rule. Fix the code.
+- **Evaluator error** (`kind: "error"`, `code: "evaluator:<type>"`, `filePath: null`) — the rule
+  crashed (missing `rg`/`sg`/`lcov.info`, or a bad pattern). Fix the rule or the environment, **not**
+  the code. This distinction is first-class — never edit source to silence a broken rule.
+
+Full JSON schema and field nuances (e.g. `line` is present on forbid-matches, absent on
+require-misses): [rules/authoring-rules.md](rules/authoring-rules.md).
+
+### Step 3: Fix and re-run
+
+Fix the *specific* violation the finding names — no drive-by refactors — then re-run the same
+command. By default, `spur rule run` surfaces findings only; the agent makes the edit and re-runs.
+Loop until exit 0.
+
+**`--fix-mode` shortcut:** when the violation is mechanically fixable (e.g. a regex replacement),
+`spur rule run --fix-mode auto` applies the fix and reports the result. The exit code still reflects
+the *findings* (not whether fixes were applied), so re-run to confirm green. `--fix-mode suggest`
+surfaces candidate fixes in `--json` output without writing.
+
+## Command surface
+
+```
+spur rule run      [--preset <name>] [--file <path>] [--rule <id>] [--fail-on <sev>] [--stop-on-first [<sev>]] [--fix-mode <none|suggest|auto>] [--dry-run] [--verbose] [--json]
+spur rule validate [file-or-preset] [--file <path>] [--preset <name>] [--kind file|preset] [--no-schema] [--json]
+spur rule list     [--preset <name>] [--json]
+spur rule trace    [run-id] [--preset <name>] [--status done|failed] [--since <iso-date>] [--last <n>] [--json]
+```
+
+Default preset is `recommended-pre-check`. `--fail-on`/`--stop-on-first` take `error|warning|info`.
+List what is actually enforced before assuming — presets are layered (project shadows bundled):
+
+```bash
+spur rule list --json                                    # discovered files + source layer
+spur rule list --preset recommended-pre-check --json     # resolved rules for one preset
+spur rule trace --last 10 --json                         # recent rule runs
+spur rule trace <run-id> --json                          # per-run detail
+```
+
+Repo presets: `recommended-pre-check` (inner loop), `recommended-post-check` (final, adds coverage),
+`strict-check` (hardened boundaries), `rg-migration` (ripgrep-dialect guard). Rationale for the
+ordering and how to compose a new preset: [rules/fine-tuning.md](rules/fine-tuning.md).
+
+## Behavior
+
+This skill behaves as a **reviewer** (apply a deterministic rule set, return ranked findings) feeding
+a **pipeline** (gate → interpret → fix → re-run until green). It also covers authoring/tuning the
+rules the reviewer applies. It does not generate feature code; it constrains code another agent wrote.
+
+## Gotchas
+
+1. **Exit code is the source of truth, not the printed text.** A clean-looking run still exits
+   non-zero if a finding meets `--fail-on`. Check the exit code / `--json` summary before claiming
+   the gate passed.
+2. **Evaluator errors are not policy violations.** `code: "evaluator:<type>"` + `filePath: null`
+   means a tool is missing or the rule is misconfigured — fix the rule/environment, not the source.
+3. **Don't game the gate.** An LLM will try the cheapest path to "passed": adding `biome-ignore`,
+   deleting a test, lowering `--fail-on`, or excluding the offending file. Each defeats the harness.
+   The `no-biome-suppressions` meta-rule exists specifically to catch suppression-to-pass. Fix root
+   causes.
+4. **`rg` uses ripgrep dialect — no lookbehind/backreferences.** A `type: rg` rule with `(?<=...)`
+   or `\1` won't compile. Keep it on `type: regex`, or run the `rg-migration` preset to catch it.
+   `isRipgrepCompatiblePattern()` (library export) checks a pattern before promotion.
+5. **`line` is optional on findings.** Present on forbid-matches, absent on require-misses. Don't
+   assume every finding has a location; locate by `filePath` + `message`.
+6. **Real config shapes differ from the README's simplified examples.** `forbidden-import` uses
+   `forbidden: [{specifier}]` + `scope`; `coverage-gate` uses `include`/`exclude` globs. Copy from
+   `.spur/rules/` or authoring-rules.md, not from a half-remembered snippet.
+7. **`$schema` must be quoted** — it starts with `@`, which YAML reserves. Unquoted is a parse error.
+8. **Presets are layered.** A surprising finding may come from a shadowing project rule. Run
+   `spur rule list --preset <name>` to see the resolved set and its source layer.
+
+## Additional Resources
+
+- [rules/operations.md](rules/operations.md) — the operation procedures
+  (run/scan/add/refine/validate/list), the shared find-existing-coverage and validate-and-smoke-test
+  cores, and the fixture convention. The entry point for slash-command delegation.
+- [rules/authoring-rules.md](rules/authoring-rules.md) — add constraints: evaluator
+  selection, real config shapes, the JSON finding schema, smoke-testing a new rule.
+- [rules/fine-tuning.md](rules/fine-tuning.md) — dial in quality: severity, glob scoping,
+  exemptions, preset `extends`/`disable`/`overrides`, layering, governance.
+- [rules/validation-and-extension.md](rules/validation-and-extension.md) — validate files
+  and presets, custom evaluators/resolvers/formatters, and the CLI-vs-library capability gaps.
+- `@gobing-ai/ts-rule-engine` README — authoritative library reference (every evaluator, fixer,
+  preset mechanism, observability event).
+- `.spur/rules/` — this repo's live rule catalog; copy real config shapes from here.
+
+## Platform Notes
+
+### Claude Code
+Run `spur rule` via the Bash tool. During development the CLI entry is a `.ts` file that runs only
+under Bun: `bun run apps/cli/src/index.ts rule run --json`. The installed `spur` binary works once
+built.
+
+### Codex / OpenClaw / OpenCode / Antigravity
+Run `spur rule ...` via the Bash tool; parse `--json` output programmatically. Arguments are passed
+directly on the command line.
+
+---
+
+**Template type**: technique
+**Purpose**: Operate `spur rule` across its full lifecycle as the deterministic constraint gate in LLM code delivery

package/plugins/sp/skills/spur-cli/references/serve.md

@@ -0,0 +1,58 @@
+---
+name: spur-cli-serve
+description: "spur-cli noun reference: operate `spur serve` as the local web-server fallback - start the Hono/Cloudflare-Worker server that backs the web Task Kanban and the team supervisor API. Single verb, five flags."
+see_also:
+  - spur-cli
+---
+
+# spur serve - local web server
+
+`spur serve` starts the **Spur web server** - a local Hono / Cloudflare-Worker server that serves
+the web Task Kanban and exposes the team supervisor API (`/api/team/*`). It is the local fallback
+when no remote server is configured.
+
+## Verb map
+
+| Verb | Purpose | Key flags |
+| ---- | ------- | --------- |
+| `serve` | Start the Spur web server (local fallback) | `--port <n>` `--host <addr>` `--no-open` `--cwd <path>` `--json` |
+
+**Exit codes:** `0` success, `1` error.
+
+## `serve` - start the web server
+
+```bash
+spur serve                          # default: localhost:3000, opens browser
+spur serve --port 8080 --host 0.0.0.0
+spur serve --no-open                # skip browser
+spur serve --json                   # dry probe: print { port, url, pid, running } and exit
+```
+
+Starts the server with the Hono app backed by the local SQLite database. The web Task Kanban and
+the team supervisor API become available at `http://<host>:<port>`.
+
+### Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--port <n>` | Server port (env: `PORT`, default: `3000`). |
+| `--host <addr>` | Bind address (env: `HOST`, default: `localhost`). |
+| `--no-open` | Skip opening the browser (default: opens). |
+| `--cwd <path>` | Working directory (default: current directory). |
+| `--json` | Dry machine-readable probe: print `{ port, url, pid, running }` and exit. No server is started. |
+
+`--json` is a **dry probe** - it reports the resolved port/url without starting the server
+(`running: false`, `pid: null`). Use it to check what *would* start, not to launch.
+
+## What this skill is NOT
+
+- **Not the team supervisor.** `spur serve` hosts the supervisor API; `spur team start` / `stop` /
+  `status` are the verbs that drive it. See **[team.md](team.md)**.
+- **Not a production server.** This is the local fallback. Production deployment uses the Cloudflare
+  Worker build (`apps/server/`), not `spur serve`.
+
+## See also
+
+- **`spur team` (see [team.md](team.md))** - `start`/`stop`/`status` require `spur serve` for the
+  supervisor API.
+- **`sp:spur-cli`** SKILL.md - the facade that routes to this reference.

package/plugins/sp/skills/spur-cli/references/tasks/l3-guard-cheatsheet.md

@@ -0,0 +1,98 @@
+---
+name: task-l3-guard-cheatsheet
+description: First-write formats for task lifecycle transitions, Solution citations, Review findings, verdict artifacts, and canonical sections.
+see_also:
+  - spur-cli
+  - task-section-editing
+---
+
+# Task L3 guard cheat sheet
+
+Read this before writing `Solution`, `Testing`, or `Review`. The owning implementations are
+`.spur/workflows/task-lifecycle.yaml`, `hasPopulatedPriorityTable()` in
+`packages/app/src/services/task-check.ts`, the verdict normalizers in
+`packages/app/src/services/task-record.ts`, and `TASK_CANONICAL_SECTIONS` in
+`packages/domain/src/planning/markdown-document.ts`.
+
+## Lifecycle graph
+
+```text
+backlog → todo → wip → testing → done
+            ↕       ↕
+          blocked ←→
+
+done → wip
+backlog|todo|wip|testing|blocked → cancelled
+```
+
+- `wip → testing` runs `spur task check <wbs>`.
+- `testing → done` runs `spur task check <wbs> --strict-core`, followed by the PASS-verdict gate.
+- Invalid: `todo → testing`, `todo → done`, and `wip → done`.
+- Normal path: `backlog → todo → wip → testing → done`.
+
+## Solution: `file:line`
+
+The body needs at least one real citation with a filename or repository-relative path:
+
+```markdown
+| Change | Evidence |
+| --- | --- |
+| Preserve activity during roster failure | `apps/web/src/modules/teams/SupervisorTab.tsx:218` |
+```
+
+- Correct: `SupervisorTab.tsx:218`, `apps/web/src/modules/teams/SupervisorTab.tsx:218`.
+- Wrong: `:218`, `line 218`, or a filename with no line.
+- Re-read after formatting so the anchor is current.
+
+## Review: populated P1–P4 table
+
+`hasPopulatedPriorityTable()` requires a markdown row containing an exact `P1`, `P2`, `P3`, or
+`P4` cell plus non-placeholder content:
+
+```markdown
+| Priority | Finding | File:Line | Disposition |
+| --- | --- | --- | --- |
+| P2 | Missing null guard | `src/foo.ts:42` | Fixed |
+```
+
+Prose-only reviews and rows containing only empty/placeholder cells do not pass.
+
+## Verdict artifact
+
+`.spur/run/<wbs>-verdict.json` uses arrays of normalized records:
+
+```json
+{
+  "wbs": "0379",
+  "verdict": "PASS",
+  "requirements": [
+    { "id": "R1", "status": "MET", "evidence": "plugins/sp/skills/code-testing/SKILL.md:55" }
+  ],
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1",
+      "status": "MET",
+      "evidenceType": "test",
+      "evidence": "bun test plugins/sp/tests: exit 0"
+    }
+  ],
+  "checks": [
+    { "name": "lint-clean", "status": "pass", "evidence": "bun run lint: exit 0" }
+  ],
+  "source": "spur-task-verdict"
+}
+```
+
+- `requirements[]`: `{ id, status, evidence }`.
+- `acceptanceCriteria[]`: `{ id, status, evidenceType, evidence }`.
+- `checks[]`: `{ name, status, evidence }`.
+- `verdict`: `PASS`, `PARTIAL`, `FAIL`, or `UNKNOWN`.
+- Use `spur task verdict`/`spur task record` when a verify answer exists.
+
+## Canonical section names
+
+`Background`, `Requirements`, `Acceptance Criteria`, `Q&A`, `Design`, `Plan`, `Solution`,
+`Root Cause`, `Testing`, `Review`, `References`, `History`, `Notes`.
+
+`Verdict` is not a section. `Root Cause` is valid only for variants/statuses whose section matrix
+allows it. Use `spur task sections <wbs> list --json` before adding an optional section.

package/plugins/sp/skills/spur-cli/references/tasks/section-editing.md

@@ -0,0 +1,95 @@
+---
+name: task-section-editing
+description: The temp-file → --section/--from-file recipe for editing task sections, when to use record instead, and which sections to fill when.
+see_also:
+  - spur-cli
+---
+
+# Editing task sections
+
+Task bodies are edited section-by-section through `spur task update --section <name> --from-file
+<path>`. The write is **file-wins and crash-safe** (atomic write): the named section's body is
+replaced wholesale from the file you point at. There is no inline-body flag — always stage the new
+body in a file first.
+
+For **pipeline output** (`Testing` / `Review` / safety-net `Solution`), prefer `spur task record`
+over hand-assembling files — it renders the matrix-compliant tables from a verify verdict for you.
+Use the manual recipe below for `Plan`, `Acceptance Criteria`, hand-authored `Solution`, and any
+narrative section.
+
+## The recipe
+
+1. **Assemble the full section body** in a temp file. The body is everything *under* the `###`
+   heading — do not include the heading line itself; the CLI owns the heading.
+
+   ```bash
+   cat > /tmp/review.md <<'EOF'
+   **Verdict: PASS**
+
+   | # | Finding | Dim | Location | P | Disposition |
+   |---|---------|-----|----------|---|-------------|
+   | 1 | … | Correctness | src/foo.ts:42 | P2 | FIXED |
+   EOF
+   ```
+
+2. **Replace the section:**
+
+   ```bash
+   spur task update 0040 --section Review --from-file /tmp/review.md
+   ```
+
+3. The whole `### Review` body is now that file's contents. To amend rather than overwrite, read
+   the current body (`spur task show 0040`), edit the temp file to the full desired state, and
+   replace again — there is no append mode.
+
+`--section` **requires** `--from-file` (exit `2` otherwise). Section names match the DD-08 headings
+exactly: `Background`, `Requirements`, `Acceptance Criteria`, `Q&A`, `Design`, `Plan`, `Solution`, `Root Cause`, `Testing`, `Review`, `References`, `History`, `Notes` (universal sections are `History`, `References`, `Notes`; `Root Cause` is carried by the `issue` template variant).
+
+## `record` vs. hand-editing
+
+`spur task record 0040 --transition testing` reads `.spur/run/0040-verdict.json` and writes both
+`Testing` (per-requirement table) and `Review` (P1–P4 findings table) in the matrix-required shape,
+optionally backfilling a bare `Solution` from `git diff -U0`. It never transitions to `done`.
+
+- **Use `record`** when a verify step produced a verdict artifact — it is the pipeline's record step.
+- **Use `update --section`** when you are authoring a section by hand (planning, design, narrative
+  solution) or amending one `record` already wrote.
+
+The two are interchangeable on the same section: `record` writes `Review`, a later
+`update --section Review` overwrites it. Both go through the same file-wins atomic write.
+
+## Which section, when
+
+During a pipeline run the sections fill in roughly this order — but *what* goes in each is the
+LLM's job (orchestrated by `sp:spur-dev`); this skill only owns the *mechanism*:
+
+| Section | Filled | Holds |
+| ------- | ------ | ----- |
+| `Background` | at create (derived from feature `Goal` if `--feature`) | why this task exists |
+| `Acceptance Criteria` | planning (present at `todo` for spec'd tasks) | the scenarios this task satisfies (matched to feature AC by title) |
+| `Plan` | before `wip` | the step list |
+| `Solution` | during impl (first appears at `wip`) | the approach actually taken; L3 `file:line` rule fires once it has real content |
+| `Testing` | testing phase (via `record`) | what was verified and how — gated at `wip→testing` by `check` |
+| `Review` | review phase (via `record`) | SECU findings + verdict — gated at `testing→done` by `check --strict-core` |
+
+A spec'd task (`--feature` link or batch item with `background`/`requirements`) is created at `todo`
+with Acceptance Criteria + Plan scaffolding present; a bare capture is created at `backlog` with
+Background only.
+
+## Status vs. section — don't conflate
+
+`update 0040 wip` is a lifecycle transition. `update 0040 --section …` is a body edit. They are
+separate invocations and mutually exclusive in one call. A typical step does the section edit first,
+then the transition:
+
+```bash
+spur task update 0040 --section Plan --from-file /tmp/plan.md
+spur task update 0040 wip
+```
+
+The `wip→testing` and `testing→done` transitions run a `check` guard (§7.5) — fill the gated
+sections (`Testing`, `Review`, `Solution`) before attempting the transition, or it will be blocked.
+
+Before authoring pipeline output for the first time, read the
+**[L3 guard format cheat sheet](l3-guard-cheatsheet.md)**. It centralizes the lifecycle graph,
+Solution citation rule, Review table shape, verdict artifact schema, and canonical section names.