@gobing-ai/spur 0.3.41 → 0.3.43

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

@@ -0,0 +1,361 @@
+---
+name: task-verbs
+description: Per-verb flag detail, template variants, verdict + check JSON shapes, and exit codes for spur task.
+see_also:
+  - spur-cli
+---
+
+# `spur task` — verb detail
+
+Ground truth for every `spur task` verb. The CLI is the source of behavior; this reference mirrors
+it so you don't have to read the command source. If a flag isn't listed here, it doesn't exist —
+don't assume one. Authority for surface + semantics: `docs/04_DESIGN.md §7.1`.
+
+**Exit codes (all verbs):** `0` success, `1` error, `2` invalid usage. `--json` follows the
+`api-response` envelope (`{ ok, data? }`).
+
+## `create <title>`
+
+Allocate one task with a race-safe WBS (a create-lock serializes ID allocation; fail-loud, no
+blocking retry).
+
+| Flag | Effect |
+| ---- | ------ |
+| `--feature <id>` | Records `feature_id` in frontmatter; derives `Background` from the feature's `Goal` (L4 edge). |
+| `--parent <wbs>` | Groups under a parent WBS for sub-task decomposition. |
+| `--template <variant>` | Selects the section-matrix variant for the new file. |
+| `--folder <path>` | Target a non-default tasks folder. |
+| `--json` | Emit `{ ref: { id, filePath } }`. |
+
+(See also the full verb map in [tasks.md](../tasks.md).)
+
+**Template variants** (`TASK_VARIANTS`): `standard`, `feature-impl`, `issue`, `review`, `meta`,
+`brainstorm`. The variant chooses which sections the new file carries (via the Section-Status-Matrix)
+and its scaffold body. **Default:** `feature-impl` when `--feature` is given, else `standard`. An
+unknown variant is exit `2`.
+
+**Creation status** follows the matrix: a spec'd task (a `--feature` link, or a batch item with
+`background`/`requirements`) is created at **`todo`** ("ready to execute"); a bare capture is created
+at **`backlog`** ("still preparing"). `Solution` first appears at `wip`.
+
+## `show <wbs>` / `list`
+
+- `show <wbs>` prints one task's frontmatter + body. With `--json`, frontmatter is a top-level field.
+- `list` filters: `--status <s>` (or legacy `--phase <p>`), `--parent <wbs>`, `--feature <id>`
+  (linked `feature_id` edge). `--json` emits an array.
+
+## `update <wbs> [status] | --section <name> --from-file <path> | --feature/--priority`
+
+Multi-mode. Status and `--section` are **mutually exclusive**; `--feature`/`--priority` set a
+frontmatter scalar.
+
+- **Status** (positional): legal transition over `backlog → todo → wip → testing → blocked → done →
+  cancelled`. Two transitions run a `check` guard (§7.5): `wip→testing` → `spur task check <wbs>`;
+  `testing→done` → `spur task check <wbs> --strict-core`. A failing gate blocks the transition.
+- **`--no-lifecycle`**: suppress lifecycle workflow *run record* creation (use inside pipeline runs
+  to avoid orphaned nested lifecycle runs). **It is not a guard bypass** — the `wip→testing` and
+  `testing→done` `check` gates above still run; the CLI evaluates them inline when the FSM guard
+  does not. `--force-done` waives the verify **verdict** only, never the section matrix.
+- **Section** (`--section` **requires** `--from-file`): replaces the entire named section body from
+  the file. No inline-body flag. Section names: `Background`, `Requirements`, `Acceptance Criteria`, `Q&A`, `Design`, `Plan`, `Solution`, `Testing`, `Review`, `References`, `History`, `Notes`.
+- **Frontmatter** (`--feature <id>`, `--priority <p>`): sets the scalar frontmatter field on an
+  existing task — the only post-create path, allow-listed to `feature_id` / `parent_wbs` / `priority`.
+
+Exit code `2` when neither mode's required args are supplied (e.g. `--section` without `--from-file`,
+or no status and no `--section`/frontmatter flag).
+
+## `deps <wbs> <op> [values...]`
+
+Mutate the `dependencies[]` frontmatter array on an existing task. Operations run validation (WBS format, existence, self-edge, duplicates, cycle detection) before any write.
+
+| Op | Usage | Description |
+| --- | --- | --- |
+| `set` | `spur task deps <wbs> set <dep-wbs...>` | Replace `dependencies[]` with given WBS values |
+| `add` | `spur task deps <wbs> add <dep-wbs...>` | Append given WBS values (deduped) |
+| `remove` | `spur task deps <wbs> remove <dep-wbs...>` | Drop given WBS values |
+| `clear` | `spur task deps <wbs> clear` | Empty `dependencies[]` array |
+
+Flags: `--folder <path>`, `--json`. Exit codes: `0` success, `1` error, `2` usage error, `3` validation error.
+`--json` shape: `{ "ref": { "id": "0316", "filePath": "..." }, "dependencies": ["0315"] }`.
+
+## `sections <wbs> <op> [name]`
+
+CLI-safe, matrix-enforced task section mutation. Section names are validated against canonical sections (`Background`, `Requirements`, `Acceptance Criteria`, `Q&A`, `Design`, `Plan`, `Solution`, `Root Cause`, `Testing`, `Review`, `References`, `History`, `Notes`). Universal sections (`History`, `References`, `Notes`) are always allowed; `Root Cause` is carried by the `issue` template variant.
+
+| Op | Usage | Description |
+| --- | --- | --- |
+| `init` | `spur task sections <wbs> init` | Add every required section for task's status not already present (idempotent) |
+| `add` | `spur task sections <wbs> add <name>` | Add a single canonical section |
+| `list` | `spur task sections <wbs> list` | Read-only: return matrix required/optional/forbidden, present, and missing sections |
+
+Flags: `--folder <path>`, `--json`. Exit codes: `0` success, `1` error, `2` usage error, `3` validation error.
+
+## `run-link <wbs>`
+
+Record a pipeline run provenance link for a task WBS (used by `--next` auto chains).
+
+Flags: `--source <source>` (default `chain`), `--run-id <id>`, `--json`.
+`--json` shape: `{ "id": "trl_...", "wbs": "0316", "runId": "...", "kind": "pipeline", "existed"?: true }`.
+Idempotent: skips if a pipeline link already exists for the task. Exit codes: `0` success, `1` error.
+
+## `batch-create --file <path>`
+
+Create many tasks from a JSON file passed via **`--file <path>`** (not a positional). The file is a
+**bare top-level array** (not wrapped in an object). Each item is `.strict()` — unknown keys are
+rejected, and creation is **all-or-nothing**:
+
+```json
+[
+  {
+    "name": "Add email validation",
+    "feature_id": "H2",
+    "parent_wbs": "0040",
+    "priority": "P1",
+    "tags": ["validation"],
+    "template": "feature-impl",
+    "background": "…",
+    "requirements": "…"
+  }
+]
+```
+
+Valid `template` values match `TASK_VARIANTS`: `standard`, `feature-impl`, `issue`, `review`, `meta`,
+`brainstorm`. `priority`: `P0`–`P3`. Only `name` is required. An item with `background`/`requirements`
+is created at `todo`; a bare item at `backlog`. The schema lives at
+`apps/cli/schemas/task-batch.schema.json`; the decomposition heuristics that produce this array live
+in `sp:spur-dev`.
+
+## `record <wbs>`
+
+Write `Testing` + `Review` from a verify verdict, with optional `Solution` backfill and a lifecycle
+transition. Collapses the pipeline's record step to one call.
+
+| Flag | Effect |
+| ---- | ------ |
+| `--verdict-file <path>` | Verdict JSON (default `.spur/run/<wbs>-verdict.json`). |
+| `--solution-from-diff` | Backfill `Solution` from `git diff -U0` **only when Solution is bare**. |
+| `--transition <status>` | Optional lifecycle transition after writing. **Never `done`.** |
+
+**Verdict shape** (`.spur/run/<wbs>-verdict.json`):
+
+```json
+{
+  "wbs": "0040",
+  "verdict": "PASS",
+  "requirements": [{ "id": "AC-1", "status": "MET", "evidence": "…" }],
+  "checks": [{ "name": "SECU", "status": "P3", "evidence": "…" }]
+}
+```
+
+- `verdict`: `PASS` | `PARTIAL` | `FAIL` | `UNKNOWN`. A missing/malformed/empty file degrades to
+  `UNKNOWN` (empty arrays) — `record` never throws.
+- `requirements[]` → the `Testing` per-requirement table. `checks[]` → the `Review` P1–P4 findings
+  table. With no requirements/checks, each renders exactly one "none recorded" row (a clean verify is
+  a valid outcome; the matrix requires a table, not an empty section).
+- `--solution-from-diff` parses `+++ b/<path>` + `@@ +new @@` hunk headers into sorted, unique
+  `` `file:line` `` rows; falls back to `--name-only` at `:1` when there are no hunk lines.
+
+## `check [wbs]`
+
+The four-layer validator (design §3): L1 frontmatter, L2 section-matrix, L3 structure/format, L4
+traceability. Bare = whole corpus; with a WBS = one task. The matrix is loaded from
+`.spur/tasks/section-matrix.yaml`.
+
+- **`--strict`** elevates *all* warnings to failures.
+- **`--strict-core`** is the `testing→done` gate variant: fails only on **hard-core errors** —
+  Solution `file:line`, Review P1–P4, and `gate:true` required-section misses — *without* the blanket
+  warning elevation.
+
+**L4 traceability** resolves `feature_id` / `parent_wbs` / `dependencies` edges and checks **AC
+coverage** (DD-09): a task's scenarios must be a subset of its linked feature's AC by normalized
+title — orphans warn by default.
+
+`--json` emits an array of per-task results:
+
+```json
+[
+  {
+    "wbs": "0040",
+    "status": "wip",
+    "pass": false,
+    "findings": [
+      { "severity": "error", "layer": "L4", "section": "Acceptance Criteria", "message": "…" }
+    ],
+    "missingSections": ["Testing"]
+  }
+]
+```
+
+- `severity`: `error` | `warning` (under `--strict`, warnings count as failures).
+- `layer`: which check layer raised it (`L1` frontmatter / `L2` sections / `L3` structure / `L4`
+  traceability).
+- `pass`: per-task verdict. Process exit code is `1` if **any** task fails.
+
+Parse this matrix to answer readiness questions — don't re-implement the checks in prose.
+
+## `refresh`
+
+Re-scan the task corpus and report counts (`{ folders, tasks }` with `--json`). Human output:
+`Corpus scanned — N tasks across M folder(s)`. **`kanban.md` generation is retired** (A17 cutover) —
+the web Task Kanban board is the daily driver. Does not write task files.
+
+## `migrate`
+
+One-time A17 task corpus normalization pass (`CorpusMigrator`). Normalizes live corpus files under
+the active tasks folder (or `--folder`).
+
+| Flag | Effect |
+| ---- | ------ |
+| `--dry-run` | Full report without writing files. |
+| `--folder <path>` | Custom tasks folder. |
+| `--json` | Machine-readable report envelope. |
+
+## `resolve <file-path>`
+
+Map a file path to its **owning task** — returns the WBS + task file. Strategies, in order: direct
+task-file match, filename WBS parse, then walk-up the directory tree (A10). Use `--strict` to match
+only the exact corpus path, with no basename-WBS fallback. Returns exit `1` if no task owns the path.
+`--json` for structured output.
+
+## `verdict <wbs>`
+
+Derive a PASS / PARTIAL / FAIL / UNKNOWN verdict from a verify-step answer text file (the agent's
+structured evidence write-up). Replaces the pipeline's verify→record transition's previous grep/shell
+ladder (0108; ADR-022). On a readable answer, emits `.spur/run/<wbs>-verdict.json` (mkdir-p the
+directory first).
+
+| Flag | Effect |
+| ---- | ------ |
+| `--from-answer <path>` | Path to the verify answer text file (default `.spur/run/<wbs>-verify-answer.txt`). |
+| `--folder <path>` | Custom tasks folder. |
+| `--json` | Emit the verdict JSON envelope to stdout. |
+
+Verdict shape (always written to `.spur/run/<wbs>-verdict.json` regardless of `--json`):
+
+```json
+{
+  "wbs": "0040",
+  "verdict": "PASS",
+  "requirements": [{ "id": "R1", "status": "MET", "evidence": "…" }],
+  "acceptanceCriteria": [{ "id": "AC-1", "status": "MET", "evidence": "…" }],
+  "checks": [{ "name": "design-conformance", "status": "PASS", "evidence": "…" }],
+  "source": "spur-task-verdict"
+}
+```
+
+- `verdict`: `PASS` | `PARTIAL` | `FAIL` | `UNKNOWN`. A missing/unreadable answer file is a CLI
+  input error and exits non-zero before writing a verdict artifact.
+- Behavior-bearing requirements and AC need `test` or `command` evidence; static-reference-only rows
+  cap the verdict at `PARTIAL`.
+- Exit code: `0` on `PASS`, `1` on `PARTIAL` / `FAIL` / `UNKNOWN` (so the pipeline's verify→record
+  guard can gate on exit code AND read the JSON).
+
+### Answer-file shape (what `--from-answer` parses)
+
+The answer file is **markdown** — exactly what a chained `/sp:dev-verify` leg naturally writes.
+The parser (`task-verdict.ts` `extractRequirements` / `extractAcceptanceCriteria`) reads rows from
+two table shapes; free-form prose with no tables parses to **zero rows**, which yields
+`verdict: "UNKNOWN"` (the honest answer for unparseable input — the fix is to write tables, not to
+loosen the parser).
+
+**Requirement rows** — markdown table with `Req` (or `Requirement`) and `Status` (or `Verdict`)
+columns; optional `Evidence` third column. Header detection is case-insensitive on the first two
+cells:
+
+```markdown
+| Req | Status | Evidence |
+|-----|--------|----------|
+| R1  | MET    | `src/foo.ts:42` |
+| R2  | PARTIAL| needs test |
+| R3  | UNMET  | not started |
+```
+
+`Status` values: `MET` | `PARTIAL` | `UNMET` (matched by word-boundary regex, case-insensitive).
+
+**Acceptance Criteria rows** — markdown table with `AC` (or `Acceptance`) / `Status` / `Evidence
+Type` / `Evidence` columns (four cells minimum). Header detection requires the `evidence type`
+column to distinguish AC rows from requirement rows:
+
+```markdown
+| AC | Status | Evidence Type | Evidence |
+|----|--------|---------------|----------|
+| AC-1 | MET | test    | `tests/foo.test.ts:12` |
+| AC-2 | MET | command | `bun run lint` exit 0 |
+| AC-3 | N/A | n/a     | non-behavioral — doc-only |
+```
+
+`Status`: `MET` | `PARTIAL` | `UNMET` | `N/A`. `Evidence Type`: `test` | `command` | `static-ref`
+(or `static`) | `manual-review` (or `manual`) | `llm-judge` (or `judge`) | `n/a` (or `na`).
+
+**Evidence rule (behavior-bearing AC):** an AC row with `status: MET` on a behavior-bearing id
+(no `[advisory]`/`[non-core]`/`[non-behavior]`/`[docs-only]` marker) MUST carry `test` or
+`command` evidence; any other evidence type downgrades the row to `PARTIAL` and caps the verdict.
+
+**Worked example** — a minimal PASS-producing answer file:
+
+```markdown
+## Verify Verdict — 0042
+
+| Req | Status | Evidence |
+|-----|--------|----------|
+| R1  | MET    | `src/foo.ts:42` implements the guard |
+| R2  | MET    | `tests/foo.test.ts` covers the branch |
+
+| AC | Status | Evidence Type | Evidence |
+|----|--------|---------------|----------|
+| AC-1 | MET | test | `tests/foo.test.ts:12` exit 0 |
+```
+
+A free-form prose answer (no tables, or tables missing the required headers) yields
+`verdict: "UNKNOWN"`. The resulting `.spur/run/<wbs>-verdict.json` (with `source:
+"spur-task-verdict"`) will then deny the `testing → done` transition — the denial message names
+the artifact source and directs the operator to `/sp:dev-verify <wbs>`. Re-run verify with the
+table format above.
+
+## `refresh-roster <wbs>`
+
+Regenerate a parent task's sub-task roster block in `## Plan` — the marker-delimited table that the
+L4 roll-up gate (`runL4Rollup`, task 0121) reads. Idempotent: same children → same block. Invoked
+automatically by `spur task batch-create` for each distinct `parent_wbs` after the atomic create
+lands (task 0178, F1); invoke manually after a child status change outside `batch-create`.
+
+| Flag | Effect |
+| ---- | ------ |
+| `--folder <path>` | Custom tasks folder. |
+| `--json` | Emit `{ written, childCount, wbs }` machine-readable. |
+
+Human output: `Roster refreshed for <wbs> (N sub-task(s)).` on a successful write, or
+`Task <wbs> has no sub-tasks — nothing to roster.` when the parent has no children.
+
+## `path <wbs>`
+
+Resolve a WBS to its absolute task file path. Inverse of `resolve <file-path>`.
+
+| Flag | Effect |
+| ---- | ------ |
+| `--folder <path>` | Custom tasks folder. |
+| `--json` | Emit `{ wbs, filePath }` machine-readable. |
+
+Human output: the absolute path on stdout. Exit `1` with `Task <wbs> not found` when the WBS is
+unallocated.
+
+## Command surface (quick)
+
+```
+spur task create   <title> [--feature <id>] [--parent <wbs>] [--template <v>] [--dedupe-within <seconds>] [--allow-duplicate-name] [--folder] [--json]
+spur task show     <wbs> [--folder] [--json]
+spur task update   <wbs> [status] [--section <n> --from-file <p>] [--feature <id>] [--priority <p>] [--no-lifecycle] [--folder] [--json]
+spur task deps     <wbs> <set|add|remove|clear> [values...] [--folder] [--json]
+spur task sections <wbs> <init|add|list> [name] [--folder] [--json]
+spur task list     [--status <s>] [--phase <p>] [--parent <wbs>] [--feature <id>] [--folder] [--json]
+spur task refresh  [--folder] [--json]
+spur task migrate  [--dry-run] [--folder] [--json]
+spur task refresh-roster <wbs> [--folder] [--json]
+spur task batch-create --file <path> [--folder] [--json]
+spur task record   <wbs> [--verdict-file <p>] [--solution-from-diff] [--transition <s>] [--folder] [--json]
+spur task verdict  <wbs> [--from-answer <p>] [--folder] [--json]
+spur task check    [wbs] [--strict] [--strict-core] [--folder] [--json]
+spur task resolve  <file-path> [--strict] [--folder] [--json]
+spur task path     <wbs> [--folder] [--json]
+spur task run-link <wbs> [--source <src>] [--run-id <id>] [--json]
+```

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

@@ -0,0 +1,280 @@
+---
+name: spur-cli-tasks
+description: "spur-cli noun reference: operate `spur task` as the project's task-file CLI — create tasks (with template variants), edit sections, drive the status lifecycle, record pipeline verdicts, derive verdicts, query the four-layer readiness matrix via `check --json`, and re-scan the corpus. The committed-corpus side of the planning layer that the spine orchestrates against."
+see_also:
+  - spur-cli
+---
+
+# spur task — the task-file CLI
+
+`spur task` is the CLI for the **task corpus** — the markdown task files under `docs/tasks/` (DD-08).
+Each verb is deterministic and machine-gated: WBS allocation is race-safe, section edits are
+file-wins, `record` writes pipeline verdicts mechanically, and `check` is the four-layer readiness
+matrix the rest of the planning layer reads.
+
+This is a **companion reference**, not an orchestrator. It documents *what each verb is and how to
+use it well*. The end-to-end planning + execution loop (intake → feature → decomposition →
+pipeline run) lives in **`sp:spur-dev`** — do not reimplement that loop here. When you need to
+*drive* a task through its lifecycle, reach for `sp:spur-dev`; when you need to know *which verb
+does what*, this skill.
+
+## Verb map
+
+| Verb | Purpose | Key flags |
+| ---- | ------- | --------- |
+| `create <title>` | Allocate a new task (race-safe WBS) | `--feature <id>` `--parent <wbs>` `--template <variant>` `--dedupe-within <s>` `--allow-duplicate-name` `--folder` `--json` |
+| `show <wbs>` | Print one task's frontmatter + body | `--folder` `--json` |
+| `update <wbs> [status]` | Lifecycle transition, section replace, **or** frontmatter set | `--section <name> --from-file <path>` `--feature <id>` `--priority <p>` `--no-lifecycle` `--force-done` `--reason <text>` `--verdict-dir <path>` `--folder` `--json` |
+| `deps <wbs> <op> [values...]` | Mutate `dependencies[]` frontmatter array (ops: `set`, `add`, `remove`, `clear`) | `--folder` `--json` |
+| `sections <wbs> <op> [name]` | Initialize, add, or list canonical task sections (ops: `init`, `add`, `list`) | `--folder` `--json` |
+| `list` | List tasks, filtered | `--status <s>` `--phase <p>` `--parent <wbs>` `--feature <id>` `--folder` `--json` |
+| `refresh` | Re-scan the corpus and report counts (**`kanban.md` retired** — web Task Kanban is SSOT) | `--folder` `--json` |
+| `migrate` | One-time A17 corpus normalization pass | `--dry-run` `--folder` `--json` |
+| `refresh-roster <wbs>` | Regenerate a parent task's sub-task roster block in `## Plan` | `--folder` `--json` |
+| `batch-create` | Create many tasks from a validated JSON array | `--file <path>` `--folder` `--json` |
+| `record <wbs>` | Write Testing/Review from a verify verdict; optional Solution + transition | `--verdict-file <path>` `--solution-from-diff` `--transition <status>` `--folder` `--json` |
+| `verdict <wbs>` | Derive PASS/PARTIAL/FAIL/UNKNOWN from verify answer text → verdict JSON; see [answer-file shape](tasks/verbs.md#answer-file-shape-what---from-answer-parses) | `--from-answer <path>` `--folder` `--json` |
+| `check [wbs]` | Four-layer validation; the readiness matrix | `--strict` `--strict-core` `--folder` `--json` |
+| `resolve <file-path>` | Map a file path to its owning task WBS | `--strict` `--folder` `--json` |
+| `path <wbs>` | Map a WBS to its absolute task file path (inverse of `resolve`) | `--folder` `--json` |
+| `run-link <wbs>` | Record pipeline run provenance link for task | `--source <src>` `--run-id <id>` `--json` |
+| `verifyall-aggregate` | Aggregate per-task verify outcomes into a batch verdict (NOT-STARTED excluded) | `--from-file <path>` `--json` |
+| `scaffold-tests <wbs>` | Generate BDD test stubs from task Acceptance Criteria | `--file <path>` `--folder` `--json` |
+
+All verbs accept `--json` for machine consumption and `--folder <path>` to target a non-default
+tasks folder. **Exit codes:** `0` success, `1` error, `2` invalid usage.
+
+## Creating tasks
+
+```bash
+spur task create "Add email validation" --feature H2 --parent 0040
+```
+
+- **`--feature <id>`** wires traceability: it derives the task's `Background` from the feature's
+  `Goal` and records `feature_id` in frontmatter (L4 traceability reads this edge).
+- **`--parent <wbs>`** groups the new task under a parent WBS for sub-task decomposition.
+- **`--template <variant>`** selects the section-matrix variant that shapes the new file's sections:
+  `standard·feature-impl·issue·review·meta·brainstorm`. The default is **`feature-impl` when
+  `--feature` is given, else `standard`**. An unknown variant is exit `2`.
+
+The same `--template` axis drives both *which sections the new file carries* (per the
+Section-Status-Matrix) and *its creation status*: a spec'd task (a `--feature` link, or a batch item
+with `background`/`requirements`) is created at **`todo`**; a bare capture is created at **`backlog`**.
+See [tasks/verbs.md](tasks/verbs.md) for the variant detail.
+- **Dedup guard (default-on)** — when `--feature <id>` is set, the CLI refuses creation if an
+  existing task under the same feature has an identical (case-insensitive) title created within the
+  last **300 seconds** (5 min). This prevents the orphan-skeleton + re-create pattern: an agent
+  creates a task, loses context, then creates it again. The guard emits `duplicate-follow-up` with
+  exit code `3` and names the existing WBS — reuse it.
+  - **`--dedupe-within <seconds>`** overrides the default window (e.g. `--dedupe-within 60`).
+  - **`--allow-duplicate-name`** disables the guard entirely (explicit override).
+  - The guard applies to every create: feature-scoped tasks collide within the same
+  feature; unscoped tasks (no `--feature`) collide with other unscoped tasks of the
+  same title (their own collision scope).
+  - With `--json`, a duplicate emits `{ ok: false, error: { code, message, existingWbs,
+    existingName, attemptedName } }` for deterministic reuse.
+
+```bash
+# Default guard is on — second call within 5 min exits 3:
+spur task create "Add email validation" --feature H2
+spur task create "Add email validation" --feature H2  # → duplicate-follow-up, exit 3
+# Narrow the window:
+spur task create "Add email validation" --feature H2 --dedupe-within 60
+# Override (creates anyway):
+spur task create "Add email validation" --feature H2 --allow-duplicate-name
+```
+
+Many tasks at once (the decomposition output) go through `batch-create` with a JSON **array** file.
+After child creation succeeds, the CLI refreshes each referenced parent roster and advances a parent
+still at `todo` to `wip`; the JSON result includes `parentsWired[]` for these best-effort side
+effects. Shape and gating live in `sp:spur-dev`'s decomposition reference.
+
+## Editing a task: status vs. section vs. frontmatter
+
+`update` is multi-mode. **The first positional after the WBS is a status; `--section` switches to
+section-edit mode; `--feature`/`--priority` set a frontmatter scalar.** Status and `--section` are
+mutually exclusive.
+
+**Lifecycle transition** (positional status):
+
+```bash
+spur task update 0040 wip
+```
+
+Valid statuses: `backlog · todo · wip · testing · blocked · done · cancelled` (the lifecycle engine
+enforces legal transitions). Two transitions are **guarded by `check`**: `wip→testing` runs
+`spur task check <wbs>`, and `testing→done` runs `spur task check <wbs> --strict-core` — a failing
+gate blocks the transition (§7.5).
+
+**`--no-lifecycle`** suppresses lifecycle workflow *run record* creation (use during pipeline-driven
+transitions so nested lifecycle runs are not orphaned). **It is not a guard bypass** — the
+`wip→testing` / `testing→done` `check` gates still run, evaluated inline when the FSM guard does not.
+**Forced-done override** (`--force-done`, paired with `--reason`):
+
+```bash
+spur task update 0040 done --force-done --reason "verify PASS deferred; manual review confirmed"
+spur task update 0040 done --force-done --reason "verify PASS deferred" --verdict-dir .spur/run/ci
+```
+
+- **`--force-done`** allows a `testing->done` transition even when the verify verdict is not PASS
+  (0292); it records an override rather than silently bypassing the gate.
+- **`--reason <text>`** is the rationale for the override, persisted as `done_reason` in frontmatter.
+- **`--verdict-dir <path>`** sets the directory the lifecycle guard reads `<wbs>-verdict.json`
+  artifacts from (default `.spur/run`) - useful when a pipeline writes verdicts to a non-default
+  location.
+
+**Section replace** (file-wins, crash-safe):
+
+```bash
+spur task update 0040 --section Review --from-file /tmp/review.md
+```
+
+- `--section` **requires** `--from-file` — there is no inline-body flag; the new body is always
+  read from a file (this is what makes edits crash-safe and reviewable). Exit `2` otherwise.
+- Section names match the DD-08 task headings: `Background`, `Acceptance Criteria`, `Plan`,
+  `Solution`, `Testing`, `Review`, `References`, `History`.
+- The write replaces the **whole** named section body; assemble the full section in the temp file
+  first, then point `--from-file` at it.
+
+**Frontmatter set** (the only post-create path to scalar fields, allow-listed to
+`feature_id`/`parent_wbs`/`priority`):
+
+```bash
+spur task update 0040 --feature H2
+spur task update 0040 --priority P1
+```
+
+The section-write-then-replace pattern is the workflow agents use to fill in `Plan` / `Solution` /
+`Testing` / `Review` during a run. See
+[tasks/section-editing.md](tasks/section-editing.md) for the full recipe. For pipeline
+output specifically, prefer **`record`** (below) over hand-assembling Testing/Review files.
+
+## Recording pipeline results — `record`
+
+`spur task record <wbs>` writes the `Testing` and `Review` sections **from a verify verdict**, so the
+pipeline's record step is one CLI call instead of awk/sed/jq plumbing:
+
+```bash
+spur task record 0040 --transition testing
+spur task record 0040 --verdict-file .spur/run/0040-verdict.json --solution-from-diff --transition testing
+```
+
+- Reads the verdict JSON (default `.spur/run/<wbs>-verdict.json`); renders `Testing` as a
+  per-requirement table and `Review` as a P1–P4 findings table. A missing/malformed verdict degrades
+  to an `UNKNOWN` verdict — it never throws.
+- **`--solution-from-diff`** backfills `Solution` from `git diff -U0` hunk headers **only when the
+  Solution section is still bare** — a safety net, not an overwrite.
+- **`--transition <status>`** optionally advances the lifecycle after writing (e.g. `testing`).
+  `record` **never transitions to `done`** — the `testing→done` gate stays in the workflow (0108).
+
+The verdict shape (`wbs`, `verdict`, `requirements[]`, `checks[]`) and the rendered tables are
+documented in [tasks/verbs.md](tasks/verbs.md).
+
+## Batch verdict aggregation - `verifyall-aggregate`
+
+`spur task verifyall-aggregate` replaces agent-discretion rollup prose with deterministic code: it
+reads a JSON array of per-task outcomes and emits a single batch verdict, excluding NOT-STARTED
+tasks from the rollup.
+
+```bash
+spur task verifyall-aggregate --from-file .spur/run/verifyall-batch-input.json --json
+```
+
+- **`--from-file <path>`** points at a JSON array of `{ wbs, outcome, reason? }` rows (default
+  `.spur/run/verifyall-batch-input.json`). `outcome` is one of
+  `PASS · PARTIAL · FAIL · NOT-STARTED · UNKNOWN`.
+- The aggregation rolls up every task **except** NOT-STARTED (those are reported separately in
+  `notStarted[]`). The batch verdict is `FAIL` if any rolled-up task is FAIL; `PARTIAL` if any is
+  PARTIAL; else `PASS`.
+- **`--json`** emits `{ verdict, rolledUp[], notStarted[], summary }` where each entry is
+  `{ wbs, outcome, verdict?, reason? }`.
+- **Exit codes:** `0` on PASS/PARTIAL, `1` on FAIL (and on missing/invalid input), `2` invalid usage.
+
+## Test scaffolding - `scaffold-tests`
+
+`spur task scaffold-tests <wbs>` generates BDD test stubs from a task's `## Acceptance Criteria` -
+one stub per scenario - so a spec'd task lands with a runnable test file from the start.
+
+```bash
+spur task scaffold-tests 0040 --json
+spur task scaffold-tests 0040 --file tests/0040.test.ts
+```
+
+- **`--file <path>`** overrides the default target test file path.
+- **`--json`** emits `{ wbs, targetFile, created, skipped, drifted, driftedScenarios[], warnings[] }`.
+  `drifted`/`driftedScenarios[]` flag scenarios whose AC titles no longer match the existing test
+  names; `warnings[]` carries non-fatal notices.
+- **Exit codes:** `0` success, `1` error (e.g. task WBS not found), `2` invalid usage.
+
+## The readiness matrix — `check --json`
+
+`spur task check` is the **deterministic four-layer gate** over the corpus (design §3): L1
+frontmatter, L2 section-matrix, L3 structure/format, L4 traceability. Run it bare for the whole
+corpus, or with a WBS for one task:
+
+```bash
+spur task check --json              # whole corpus
+spur task check 0040 --json         # one task
+spur task check --strict --json     # elevate ALL warnings to failures
+spur task check 0040 --strict-core  # the testing→done gate variant
+```
+
+`--json` emits the structured matrix — per-task findings (missing sections, broken feature edges,
+AC-coverage orphans via L4 traceability) keyed by WBS, plus a per-task `pass` verdict. **Query this,
+do not re-derive it**: parse the JSON to answer "which tasks are ready?", "what's blocking 0040?",
+or "are there orphaned scenarios?" rather than reading task files and re-implementing the checks.
+
+The two flags are distinct gate profiles:
+
+- **`--strict`** elevates *all* warnings to failures (the strictest reading).
+- **`--strict-core`** fails only on hard-core errors — Solution `file:line`, Review P1–P4, and
+  `gate:true` required-section misses — *without* the blanket elevation. This is the variant wired
+  as the `testing→done` lifecycle guard.
+
+See [tasks/verbs.md](tasks/verbs.md) for the JSON shape per finding.
+
+## Corpus scan — `refresh` (kanban.md retired)
+
+```bash
+spur task refresh
+```
+
+Re-scans the task corpus and reports counts (`Corpus scanned — N tasks across M folder(s)`). With
+`--json`, emits `{ folders, tasks }`. **`kanban.md` generation is retired** (A17 cutover) — the web
+Task Kanban board is the daily driver. `refresh` does not write task files.
+
+## Path resolution — `resolve` / `path`
+
+```bash
+spur task resolve docs/tasks/0040_add-email-validation.md
+spur task resolve src/lib/validation.ts --json
+spur task path 0040 --json
+```
+
+- `resolve <file-path>` maps a file path to its **owning task** (returns WBS + file). Strategies, in
+  order: direct task-file match, filename WBS parse, then walk-up the tree (A10). `--strict` disables
+  basename-WBS fallback. Exit `1` when no task owns the path.
+- `path <wbs>` is the inverse — absolute task file path for a WBS.
+
+## What this skill is NOT
+
+- **Not the pipeline.** Driving a task through `task-pipeline.yaml`, HITL surfacing, and
+  `workflow continue` is `sp:spur-dev`'s execution half — not here (R3).
+- **Not validation logic.** This skill tells you *to run* `check`; the rules it enforces live in
+  the CLI (`task check` / `feature check`), never restated as prose checks here.
+- **Not features.** Feature authoring, hierarchical IDs, and AC conventions live in the companion
+  **`spur feature` (see [features.md](features.md))**.
+
+## References
+
+| Reference | Covers |
+| --------- | ------ |
+| [tasks/verbs.md](tasks/verbs.md) | Per-verb flag detail, template variants, verdict + check JSON shapes, exit codes |
+| [tasks/section-editing.md](tasks/section-editing.md) | The temp-file → `--section`/`--from-file` recipe; which sections to fill when; `record` vs. hand-editing |
+
+## See also
+
+- **`sp:spur-dev`** — the umbrella skill that orchestrates these verbs into the planning +
+  execution loop. Use it to *drive* work; use this skill to *look up a verb*.
+- **`spur feature` (see [features.md](features.md))** — the companion for `spur feature` (hierarchical IDs, AC conventions,
+  traceability).