@gobing-ai/spur 0.3.92 → 0.3.94

package/plugins/sp/skills/spur-check/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: spur-check
+description: 'Two-tier check primitive for the sp pipeline: light (changed-scope biome, per-workspace typecheck, related tests) during development; full (bun run spur-check) once at the quality boundary. Reads/writes fingerprint-bound check receipts (.spur/run/<wbs>-check-receipt.json) and reuses a PASS full receipt only at the same proof digest.'
+license: Apache-2.0
+version: 1.0.0
+metadata:
+  author: spur
+  platforms: "claude-code,codex,openclaw,opencode,antigravity,pi"
+  category: check-execution
+  interactions:
+    - pipeline
+  operations:
+    - check
+    - accumulate
+    - reuse
+  openclaw:
+    emoji: "🧾"
+see_also:
+  - sp:spur-dev
+  - sp:spur-cli
+  - sp:code-verification
+---
+
+# sp:spur-check — the two-tier check primitive (ADR-124)
+
+One check primitive with two tiers behind the shipped `quality-gate` script
+([task 0939](../../../../docs/tasks5/0939_add-the-two-tier-spur-check-primitive-with-fingerprint-bound.md),
+[workflow catalogue refactor §4](../../../../docs/design/workflow-catalogue-refactor.md)): light
+checks accumulate during development, the full chain runs once at the quality boundary, and every
+gate writes a fingerprint-bound receipt that downstream stages read instead of re-running checks.
+
+## Tiers
+
+| Tier | Mode | When | Scope |
+| --- | --- | --- | --- |
+| `light` | `quality-gate.ts light` | after each implement/fix edit | `bunx biome check` on the changed files (`git diff --name-only HEAD` + untracked), `bun run typecheck` per touched workspace, and related tests (`<ws>/src/**/x.ts` → `<ws>/tests/**/x.test.ts` filename mapping) run via `cd <ws> && bun test …` — never from the repo root, whose bunfig preload does not apply inside the workspace |
+| `full` | `quality-gate.ts run` | once at the task quality boundary (`test`) | today's chain: `bun run lint` + `bun run test-pre-check` + `bun run test` + `bun run test-post-check` (=`bun run spur-check`), with bounded findings, SQLite-busy retry, and the `recheck` probe |
+
+Soft-fail contract: both tiers always exit 0; the verdict lives in files (`*-test-gate.status`,
+receipt `status`), never in the exit code.
+
+## Receipt
+
+`.spur/run/<wbs>-check-receipt.json`, schema `check-receipt/v1`:
+
+```json
+{
+  "schemaVersion": "check-receipt/v1",
+  "wbs": "0939",
+  "runId": "pipeline-0939",
+  "tier": "full",
+  "inputDigest": "<proof-input digest>",
+  "checks": [{ "id": "test", "cmd": "…", "status": "PASS", "durationMs": 0, "logPath": "…" }],
+  "status": "PASS",
+  "completedAt": "2026-09-25T00:00:00.000Z"
+}
+```
+
+- `inputDigest` is the shared `ProofInputFingerprint` (task markdown + git tree of tracked
+  sources). The plugin never computes it — the pipeline captures it with the `proof.fingerprint`
+  action into `env.proofDigest` (ADR-124: no second fingerprint, no `@gobing-ai/*` import);
+  standalone callers use `inline-run-setup.ts --fingerprint`.
+- Only `run`/`full` writes a reusable receipt. Without a digest, `run` writes no receipt and says
+  so in the gate log. The gate executes `qualityGateCmd` as one unit, so the full receipt carries a
+  single `test` row for the whole chain; `lint`, `typecheck`, `test-pre-check`,
+  `test-post-check` name the chain steps the full tier covers.
+- `light` merges its rows under `tier: light` and skips any sub-check already `PASS` in a light
+  receipt at the same `{id, inputDigest}` (accumulation). Light rows never make a receipt
+  reusable for review.
+
+## Reuse rule
+
+Check `status` mode before re-running a gate. Resolve the shipped script through the superskill
+runtime (shipped surfaces never hard-code repo paths):
+
+```bash
+QG="$(superskill script path sp quality-gate.mjs)"
+bun "$QG" status   # env: wbs, proofDigest → prints {"reuse":…,"reason":…}
+```
+
+`reuse: true` only when the receipt is `status: PASS`, `tier: full`, and `inputDigest` equals the
+current digest. Otherwise the reason is one of `missing | failed | stale | light-only`:
+
+- `missing` — no readable receipt (or foreign schema version)
+- `failed` — last full run failed
+- `stale` — digest mismatch (or no current digest supplied)
+- `light-only` — a valid PASS receipt that came from the light tier
+
+Only `full` may satisfy a review/verify/record boundary: "review only after a green full gate" is
+preserved by construction. `recheck` stays the no-progress probe path for fix loops.
+
+## Composition
+
+- **Pipeline:** `sp:spur-dev` runs `run` at `test` and `recheck` at `test-recheck`; light mode
+  belongs to implement/fix edits, not to the gate state.
+- **Fix loops:** `/sp:dev-fixall --gate-log` consumes `<wbs>-test-gate.log` (and the bounded
+  `<wbs>-test-gate.findings` anchors) after a red gate; it never writes receipts. A green fixall
+  output still requires a fresh `run` receipt before review.
+- **Verification:** `sp:code-verification` and the review checklists read the receipt (status
+  mode) instead of re-running `bun run test`.
+- **Feature scope:** `spur-check-feature` remains the ADR-119 repo-wide pass; this primitive is
+  task-local. A public `spur check` verb is out of scope without separate consent.
+
+## Gotchas
+
+1. **Never value-import `@gobing-ai/*` into the script** — the plugin standalone contract fails
+   the install; the digest arrives via `env.proofDigest`.
+2. **Never run light tests from the repo root** — the workspace `bunfig.toml` preload (coverage,
+   thresholds) only applies inside the workspace; `cd <ws> && bun test …` is the contract.
+3. **Light is a filter, not a boundary** — unmapped files (root-level scripts, non-src layouts)
+   are simply not covered by light; the full tier is the safety net. Do not widen the mapping
+   without an ADR.

package/plugins/sp/skills/spur-dev/SKILL.md

@@ -116,7 +116,7 @@ reference for the half you're operating; do not duplicate its content here.
 | Feature check gate         | planning  | `spur feature check`                                                                      | [planning-workflow.md](references/planning-workflow.md)                                                                                 |
 | Decomposition (dispatch)   | planning  | `task-batch.schema.json`                                                                  | `sp:spec-decomposition` competency — the spine dispatches, does not inline                                                              |
 | Batch-create gate          | planning  | `spur task batch-create`                                                                  | [planning-workflow.md](references/planning-workflow.md)                                                                                 |
-| Design doc                 | planning  | — (prompt work; §4.5/T9)                                                                  | [planning-workflow.md](references/planning-workflow.md)                                                                                 |
+| Design doc | planning | — (§4.5/T9) | [document-authoring.md](references/document-authoring.md) |
 | Refine                     | planning  | `spur task update --section`                                                              | [planning-workflow.md](references/planning-workflow.md)                                                                                 |
 | Batch refine               | planning  | `sp:dev-refineall` → per-task `refine`                                                    | [dev-operations.md](references/dev-operations.md) § refineall · [planning-workflow.md](references/planning-workflow.md)                 |
 | Task selection             | execution | `spur task list`                                                                          | [execution-workflow.md](references/execution-workflow.md)                                                                               |
@@ -246,6 +246,7 @@ for "what's actually in file Y" or for resources that sit outside the step seque
 - `idea-pipeline.yaml` — the front-half state machine (absorbed the retired
   planning-pipeline in D5-K; `/sp:dev-plan` routes here, ADR-072).
 - `templates/bdd/gherkin.md` — the BDD scenario template.
+- `templates/plan.md` and `templates/design.md` — plan and design starting points.
 
 ## Platform Notes
 

package/plugins/sp/skills/spur-dev/references/cross-cutting.md

@@ -120,6 +120,14 @@ This is **the same rule, not an exception**: `--agent` names who does the thinki
 the thinking happens in the stages. Selecting an executor for a loop that runs no prompts would be
 meaningless.
 
+**Fleet executor (0942, ADR-126, opt-in).** A workflow run may opt its `agent.run` stages into the
+agent fleet control plane by mapping the pipeline selector to `executor: 'fleet'` (dev-run /
+dev-runall `--agent fleet`). The stage dispatches to a fleet member through the fleet coordination
+surface instead of spawning a subprocess; a subprocess fallback happens only when the run declares
+`executorFallback: 'traditional'`, and an unavailable fleet otherwise fails the stage explicitly
+(0937 `failed-agent`). This is an additional `agent.run` transport — it does not change the
+`--agent` selector semantics documented above, and the interactive driver never resolves to it.
+
 **Interactive task pipelines invert control into the host session (ADR-047 amendment).**
 `dev-run --mode full` and sequential `dev-runall` with omitted `--agent` or explicit `--agent
 inline` interpret the existing `task-pipeline.yaml` in the host session; they do not launch `spur
@@ -785,8 +793,12 @@ The Design Approval Gate is the taste gate between system design and decompositi
 **The `needs_design` signal routing:**
 
 The signal is emitted by the `discovery` state's brainstorm dispatch and written to
-`.spur/run/idea-needs-design.json`. The `feature-check` state's transition guards read it to
-determine routing:
+`.spur/run/idea-needs-design.json`. A deterministic shell action at the end of the `ac-generate`
+and `feature-check` onEnter lists (0945 R2) folds `design` × `needs_design` once into
+`.spur/run/<runId>-idea-design-route.txt` (`design` | `skip`; missing/corrupt JSON fails safe to
+`design`) and the two recorded check statuses into `.spur/run/<runId>-idea-ac-ready.status`
+(`PASS` only when both are PASS). The transition guards read those derived files to determine
+routing — they never re-derive the signal inline (0769):
 
 | `design` var | `needs_design` signal | Route |
 | --- | --- | --- |

package/plugins/sp/skills/spur-dev/references/dev-operations.md

@@ -68,7 +68,7 @@ each would be scope creep for one-liner procedures.
 | #   | Operation  | Command             | Backing           | Skill / Verb                                                                       | Arg-hint                                                                                                                                                                                               |
 | --- | ---------- | ------------------- | ----------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | 1   | unit       | `dev-unit`          | `Skill()`         | `sp:code-testing`                                                                  | `<target> [--coverage <pct>] [--agent <inline\|auto\|name>] [--auto]`                                                                                                                                  |
-| 2   | review     | `dev-review`        | `Skill()`         | `sp:code-verification` (`review`) + `sp:functional-review` + `sp:code-improvement` | `[<wbs\|path>] [--agent <inline\|auto\|name>] [--focus <dims>] [--fix (deprecated)]`                                                                                                                   |
+| 2   | review     | `dev-review`        | `Skill()`         | `sp:code-verification` (`review`) + `sp:functional-review` + `sp:code-improvement` | `[<wbs\|path>] [--agent <inline\|auto\|name>] [--focus <dims>] [--triage] [--worktree [<name>]]`                                                                                                       |
 | 3   | verify     | `dev-verify`        | `Skill()`         | `sp:code-verification` (`verify`)                                                  | `<wbs> [--agent <inline\|auto\|name>] [--fix <none\|blockers-first\|all>] [--focus <lens>] [--bdd] [--auto] [--force] [--next] [--skip-shippable]`                                                     |
 | 3a  | verifyall  | `dev-verifyall`     | `Skill()` → agent | `sp:spur-dev` (`verifyall`)                                                        | `--tasks <selector> [--feature <id>] [--agent <inline\|auto\|name>] [--fix <none\|blockers-first\|all>] [--focus <lens>] [--bdd] [--auto] [--force] [--next] [--json] [--skip-shippable] [--worktree [<name>]]` |
 | 4   | run        | `dev-run`           | `Skill()`         | `sp:spur-dev` (`run` / `implement`)                                                | `<wbs> [--mode <full\|implement>] [--agent <inline\|auto\|name>] [--auto] [--next] [--wrap] [--continue] [--worktree [<name>]]`                                                                                              |
@@ -116,7 +116,13 @@ must not be changed without updating the backing skill.
 - **Modes:**
   - **WBS mode (`<wbs>`)**: Runs functional requirements traceability (`sp:functional-review`), SECUA framework (`sp:code-verification`), and architectural depth (`sp:code-improvement`). The three skills return review fragments; the coordinator writes the combined `## Review` (F92 0593 R1).
   - **Path mode (`<path>`)**: Runs advisory SECUA framework (`sp:code-verification`) and architectural depth (`sp:code-improvement`). Performs no task mutation.
-- **Inputs:** `<wbs|path>` (required). Review executes inline (in-session) by default. `--agent <inline|auto|name>` selector accepted (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--focus <lens>` narrows to one SECUA dimension. Note: `--fix` and `--next` are **deprecated** (no-op with warning; route remediation to `/sp:dev-verify --fix` and progression to `/sp:dev-next`).
+- **Inputs:** `<wbs|path>` (required). Review executes inline (in-session) by default. `--agent <inline|auto|name>` selector accepted (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--focus <lens>` narrows to one SECUA dimension. `--triage` opts into bounded remediation after the report (below). `--worktree [<name>]` isolates the triage writes (below; requires `--triage`). Note: `--fix` and `--next` are **deprecated** (no-op with warning; route remediation to `--triage` or `/sp:dev-verify --fix` and progression to `/sp:dev-next`). The task pipeline's review stage never passes `--triage` or `--worktree`.
+- **Triage (`--triage`):** runs inline in the invoking session after the merged report — never inside `sp:super-reviewer` or the review skills, which stay report-only. With `--agent <name>`, only the review is delegated; triage still runs inline on the returned findings. Never fix straight from the raw findings list:
+  1. **Bucket every finding exactly once.** **Direct fix** — local, low-risk, obvious root cause: no design choice, no public-surface / schema / dependency change, not a shared write path, verifiable by a targeted check (docs, a guard, a missing throw, a wrong path helper, a stale comment). **Task** — real and actionable but needs design, crosses modules, touches a public surface, or is not verifiable locally; skip it when an existing task already owns it (cite that WBS). **Note** — pre-existing, environmental, or ownerless; report only.
+  2. **Apply direct fixes** — smallest surgical diff in project style, then re-verify each with its targeted check (focused test, lint, or the exact command that exhibited the defect). A fix that grows beyond the bar or fails its check moves to the Task bucket with what was learned; do not leave it half-applied.
+  3. **File the Task bucket as one or more tasks**, one per cohesive unit of work that one agent can implement and verify in one run — split unrelated fixes, merge findings that share a root cause or file set. File under the existing feature that owns the affected surface; if none fits, create a child feature under the closest existing parent — never a new root feature. Write through the CLI-gated corpus surface only (`spur task create --feature <id> --skip-ready`, then `spur task update <wbs> --section <s> --from-file`). Each task must meet the implement-ready bar ([§ 5. refine](#5-refine), `--depth ready`) so it cannot drift: per finding the evidence (`file:line`), the defect, the chosen fix direction with rejected alternatives, file targets, AC, and out-of-scope; promote `backlog → todo` only when `spur task check <wbs> --json` is clean. Name what the direct fixes already resolved in each task's Background.
+  4. **Gate and report.** Run the project gate once after the direct fixes. Report a Triage section: each applied fix (path + one-line what + verification), each filed task (WBS + feature + scope), and the Notes. Never commit or create a branch outside `--worktree`.
+- **Worktree (`--worktree [<name>]`):** omitted → all writes land in the current working tree on the current branch; no branch creation, checkout, or commit (the operator commits). Given → the [execution-batch.md § Worktree isolation](execution-batch.md#worktree-isolation---worktree-name) lifecycle as a run of one: marker `command` = `dev-review`, `selector` = the review target, derived branch/directory slug = the WBS or the path's basename (`sp/review-<slug>-<short-id>`). Admission is "the target resolves" (a known WBS or an existing path) — no `quickReadiness` task-set check. Review and triage both run in the tree; WT-3b commits the fixes and filed tasks. The WT-4 success condition reads as "every direct fix passed its check and the project gate is green"; a failed check or gate takes the WT-5 retention path. Rejected without `--triage` (WT-7) — to review another worktree read-only, pass a path inside it.
 - **Backing:** `sp:functional-review`, `sp:code-verification` (review mode), `sp:code-improvement`.
 - **Behavior:** WBS mode runs functional traceability + SECUA + architecture depth, ranking findings P1–P4, and hands the merged report to the review coordinator, which writes `## Review`. Component skills never write `## Review` in coordinated mode. Path mode runs advisory SECUA + architecture depth with no task mutation.
 - **Delegation:** WBS mode: `sp:functional-review` + `sp:code-verification` (review) + `sp:code-improvement`; Path mode: `sp:code-verification` (review) + `sp:code-improvement`.

package/plugins/sp/skills/spur-dev/references/document-authoring.md

@@ -0,0 +1,85 @@
+---
+name: document-authoring
+description: Light Markdown contracts for plan records and non-UI design satellites.
+see_also:
+  - spur-dev
+  - planning-workflow
+  - doc-evolve
+---
+
+# Plan and design document authoring
+
+Use [plan.md](../templates/plan.md) for a new `docs/plans/*.md` working record and
+[design.md](../templates/design.md) for a new `docs/design/*.md` non-UI contract satellite.
+The project constitution owns their authority and maintenance; these templates are writing aids,
+not parser schemas. Keep Markdown readable even when frontmatter is absent in a legacy file.
+
+| Document | Job | Authority |
+| --- | --- | --- |
+| `docs/plans/` | Ordered work: intended outcome, premises, dependencies, execution sequence, verification, and follow-up. Older proposals and investigations remain working records. | Working record. Accepted conclusions take effect in their owner, such as an ADR, feature, roadmap, or design satellite. |
+| `docs/design/` | Issue, context, solution, and its observable non-UI contract | Governed satellite of `docs/04_DESIGN.md`; label proposals and current behavior separately. |
+
+## Compose a new file
+
+1. Choose the owner before writing. Reuse an existing satellite when it already owns the surface.
+   Keep root `DESIGN.md` for UI rules and `03_ARCHITECTURE.md` for current system topology.
+2. Copy the relevant template. Replace placeholders. Keep `kind`, a descriptive `title`, a
+   truthful `status`, `created_at`, `updated_at`, `related` links, and `tags` for categorization.
+   Use ISO dates; leave `related` or `tags` empty when none apply. Keep one H1 matching the title.
+3. Use headings for the reader's question. The template's prompts are a starting shape: remove
+   inapplicable sections and keep specialized sections required by the producing workflow, such as
+   a brainstorm's `## Design Summary`. Number new sections in reading order. Plans make the
+   execution sequence and its premises usable; designs explain the issue, context, solution, and
+   observable contract. Never fill empty boilerplate.
+4. For a design satellite, write detail first, then add its pointer to `04_DESIGN.md` if missing.
+   Update an existing index row only when its indexed facts change. Do not put task receipts there.
+
+## Frontmatter vocabulary
+
+Soft conventions for consistency and tag filtering, not a validator. Unknown values stay readable.
+
+| Field | Values |
+| --- | --- |
+| `kind` | `plan` for any `docs/plans/` record, `design` for any `docs/design/` satellite. Nothing else. |
+| `status` (plan) | `draft`, `proposed`, `approved`, `in-progress`, `done`, `superseded` |
+| `status` (design) | `proposed`, `accepted`, `implemented`, `superseded` |
+| `tags` | Ordered: one record-type tag, then owning feature ids (for example `H14`), then at most two area tags. |
+| `related` | Repo-relative paths or feature/task ids; no prose. |
+
+Record-type tags — plan: `brainstorm`, `proposal`, `investigation`, `audit`, `map`, `execution`,
+`evidence`; design: `contract` (observable surface) or `system` (internal mechanism). Area tags:
+`cli`, `server`, `web`, `workflow`, `planning`, `history`, `observability`, `agent`, `plugin`,
+`docs`, `config`. A project may extend the area list; reuse a tag already in the corpus
+(`rg -n '^tags:' docs/plans docs/design`) before adding one.
+
+A producing workflow may keep its own keys beside these, such as a brainstorm's `needs_design` and
+`run_id`, and its own section shape. The shared fields still apply.
+
+## Revise an existing file
+
+Read the whole file and its inbound links first. Preserve the filename, meaningful headings,
+anchors, dates, decisions, and historical status. Add missing metadata from evidence; label
+unknowns instead of guessing. Restructure only where clarity improves, and keep a forwarding
+heading when an anchor cannot be migrated safely. Update `updated_at` only for a substantive edit.
+Do not turn an old proposal into a claim about current behavior without checking the owning source.
+
+Legacy metadata upgrade:
+
+- **Map** `date` → `created_at` and `feature`/`feature_id`/`task_wbs`/`parent_task` → `related`.
+  `title` is the H1 text; `topic` maps to `title` only when the file has no H1, otherwise drop it.
+- **Owners:** when no owner key exists, a feature or task record that links the file
+  (`rg -l <filename> docs/features <task dir>`) is evidence for `related`. Ids found only in body
+  prose are not; requirement and priority labels look like feature ids.
+- **Keep** workflow and provenance keys unchanged (`needs_design`, `run_id`, `doc`, `authority`,
+  `owns`, `read_before`, `edit_rules`, `version`, `derived_from`).
+- **Dates:** `created_at` comes from a legacy `date`, else the filename date prefix, else the first commit
+  (`git log --follow --diff-filter=A --format=%as -- <file> | tail -1`), else leave it out and flag it.
+  `updated_at` is the existing value or the last commit date; do not bump it for a metadata-only edit.
+- **Status:** use the vocabulary value only when the legacy value or body states it unambiguously
+  (`shipped`/`implemented`/`built …` → `implemented`; `approved-with-feedback` → `approved`).
+  Otherwise keep the legacy value and flag it for the operator. No status is better than a guessed one.
+- **Headings:** never renumber or rename legacy headings; numbering applies to new files only.
+
+For a bounded, read-only review of legacy files, use `sp:spur-doctor`. Apply accepted document
+proposals in place using this guide, then use `sp:doc-evolve` to check affected key-document sync.
+No bulk conversion or strict format check is required to read or maintain existing documents.

package/plugins/sp/skills/spur-dev/references/execution-batch.md

@@ -270,7 +270,7 @@ Only two flags cross the orchestrator→pipeline boundary; both are merged into
 | Flag | Effect on per-task `--vars` |
 | --- | --- |
 | `--auto` | sets `"profile":"auto"` (skips the HITL approve gate). Omitting it forwards nothing, so the pipeline uses its default profile (standard — HITL pause surfaces to the operator). (R4.2) |
-| `--agent <value>` | omit/`inline` in interactive sequential mode selects the host driver and is not forwarded. `auto` or a name sets **both** `"agent":"<value>"` and `"implementAgent":"<value>"` so every workflow `agent.run` step — including implement — spawns that executor. Headless omit/inline falls through the executor precedence chain. To pin ONLY implement, pass `--vars '{"implementAgent":"..."}'` separately; that explicit var selects the subprocess path. (R4.3, tasks 0483/0503) |
+| `--agent <value>` | omit/`inline` in interactive sequential mode selects the host driver and is not forwarded. `auto` or a name sets **both** `"agent":"<value>"` and `"implementAgent":"<value>"` so every workflow `agent.run` step — including implement — spawns that executor. Headless omit/inline falls through the executor precedence chain. To pin ONLY implement, pass `--vars '{"implementAgent":"..."}'` separately; that explicit var selects the subprocess path. (R4.3, tasks 0483/0503) The opt-in `fleet` value instead maps the run to `"executor":"fleet"`: every `agent.run` stage dispatches through the agent fleet control plane (0942/ADR-126) and neither `agent` nor `implementAgent` is pinned. |
 
 The host session remains the orchestrator for interactive sequential omit/inline. `sp:super-planner`
 owns explicit-executor and parallel paths; there the flag pins the per-task step executor, not the
@@ -490,16 +490,25 @@ Evidence persistence precedes destructive cleanup: a persistence failure (unread
 disk-full, missing directory) routes to **WT-5** — the worktree and branch are retained so a green
 batch can never destroy its own evidence. Reuse mode retains its operator-owned tree but still
 persists the Step 5 report under the invoking tree; the reused tree's `.spur/run/` remains the live
-copy while that tree lives on.
-
-**Stage records are worktree-local too (0948 R9, E7 Finding 5).** The persisted report and verdict
-JSONs above are the batch's *summary* evidence. Each task's own per-stage run record
-(`.spur/run/<runId>.md` + `.state.json`, plus gate/answer artifacts) is written inside the
-worktree's `.spur/run/` and **is removed with the worktree** in create mode. A merged batch
-therefore leaves no per-stage run record in the invoking tree unless it is copied out. Anything
-auditing "what did this batch actually run?" must copy those records out **before** WT-4 removal —
-the E7 batch lost exactly this evidence this way. The rule is the same one above: copy out first,
-then remove; a copy failure retains the worktree.
+copy while that tree lives on. The per-run provenance — the worktree DB's run/action rows and the
+`.spur/run/<runId>.md` + `.state.json` records — is persisted mechanically by WT-4a's
+`inline-run-setup.ts --persist-out --from <worktree>` call, not by hand.
+
+**Stage records are worktree-local too (0948 R9, E7 Finding 5; persisted by 0975 R1).** Each task's
+own per-stage run record (`.spur/run/<runId>.md` + `.state.json`) and the worktree DB's run rows are
+written inside the worktree and **are removed with it** in create mode — the E7 batch lost exactly
+this evidence. Copying them out is no longer a manual audit-time duty: WT-4a (create-mode block
+below) runs `inline-run-setup.ts --persist-out --from "$WT_PATH"` **before** WT-4b holder cleanup,
+which copies the run/action/phase/transition/workflow-state rows and both record files into the
+invoking tree. The shapes are pinned (task 0975 R1): idempotent on re-persist; success exits 0
+printing `{"ok":true,"persisted":<n>,"skipped":[{"id":<run-id>,"reason":"id-exists"|"external-key-conflict"|"record-conflict:<file>"}]}`
+— an `id-exists` / `external-key-conflict` skip never modifies the pre-existing target rows, a
+`record-conflict:<file>` skip never overwrites a divergent invoking-tree record — and any failure
+exits 1 printing `{"ok":false,"error":<message>}` (a worktree DB run id that is not a single safe
+filename component is rejected before any target write). Any persist-out failure
+routes to **WT-5** — worktree and branch retained — the same copy-out-first contract as the
+verdict persistence above. After a green persist-out, `spur workflow progress --json` in the
+invoking tree shows the merged run `done` with its per-action rows.
 
 ## Step 6 — Batch wrap (`--wrap` / `--next`) (F96 task 0952 R1)
 
@@ -538,7 +547,7 @@ all subsequent tools, agents, task/feature writes, and run artifacts use the con
 tree's cwd. A stale or empty selector, an unsupported mode, or an invalid target creates no tree and
 no marker (WT-2/WT-7), and the required Git safety checks (WT-1) still precede creation.
 
-> **Command wiring (task 0814 R3).** The four worktree-capable commands (`dev-run`, `dev-runall`,
+> **Command wiring (task 0814 R3).** The four task-set worktree commands (`dev-run`, `dev-runall`,
 > `dev-refineall`, `dev-verifyall`) each call `quickReadiness` with their operation (`run`/`refine`/
 > `verify`), the resolved selector/status, and the filtered-set size **before** WT-1/WT-2. The
 > admission outcome gates the tree: an invalid/empty selector, unsupported mode, or a target that
@@ -557,6 +566,13 @@ non-PASS verify verdict, or a HITL pause that ends the run take the WT-5 retenti
 full pipeline is eligible — `--worktree --mode implement` is rejected (WT-7), because that mode is
 the pipeline's implement stage and already runs in the driver's tree.
 
+**Review triage `dev-review` (run of one).** `/sp:dev-review <target> --triage --worktree [<name>]`
+runs this lifecycle around one review-plus-triage pass: WT-1…WT-6 apply unchanged, the marker's
+`command` is `dev-review` and its `selector` is the review target, and the slug is the WBS or the
+path's basename (`sp/review-<slug>-<short-id>`). It skips `quickReadiness` (there is no task set;
+admission is "the target resolves"). WT-4 success reads as "every direct fix passed its check and the
+project gate is green"; anything else takes WT-5. Contract: [dev-operations.md § 2. review](dev-operations.md#2-review).
+
 One flag, two modes (see the glossary entry for the ownership rule). Bare `--worktree` is **create
 mode** (cut a fresh branch + sibling tree). `--worktree <name>` is **reuse mode** (attach to a tree
 that already exists); name resolution (§ WT-2 below) runs before WT-1. The deltas each mode applies
@@ -805,13 +821,23 @@ git checkout "$BASE_REF"
 [ "$(git rev-list --count "$BASE_SHA..$BRANCH")" -gt 0 ] \
   || { echo "halt: branch carries no commits - nothing to merge" >&2; false; }   # -> WT-5
 git merge --ff-only "$BRANCH"          # FF-only: never rebase, merge-commit, or resolve conflicts
-# if FF succeeded — WT-4a evidence persistence (Step 5, task 0720 R3) runs FIRST:
-# persist the batch report + verdict artifacts into the invoking tree's .spur/run/
-# before anything below touches the worktree. Persistence failure routes to WT-5.
+# if FF succeeded — WT-4a evidence persistence runs FIRST (Step 5, task 0720 R3):
+# persist the batch report + verdict artifacts AND the per-run provenance (task
+# 0975 R1) into the invoking tree before anything below touches the worktree.
+# Any persistence failure routes to WT-5 — the worktree and branch are retained.
+WT_PATH="$(cd "../<worktree-dir>" && pwd)"   # hoisted: needed by WT-4a AND WT-4b below
+# WT-4a provenance persist-out (task 0975 R1): copy the worktree DB's run rows plus
+# the .spur/run/<runId>.md + .state.json records into THIS tree. Run from the main
+# tree (cwd = the invoking tree). Idempotent; conflicts are reported, never
+# overwritten. A non-zero exit — including a half-readable worktree — must NOT
+# proceed to WT-4b removal:
+SETUP_SCRIPT="plugins/sp/scripts/inline-run-setup.ts"
+[ -f "$SETUP_SCRIPT" ] || SETUP_SCRIPT="$(superskill script path sp inline-run-setup.mjs 2>/dev/null)"
+bun "$SETUP_SCRIPT" --persist-out --from "$WT_PATH" \
+  || { echo "halt: worktree run-record persist-out failed - worktree retained (WT-5)" >&2; exit 1; }
 #
-# WT-4b — bounded CWD-holder cleanup (task 0720 R1). Resolve the EXACT absolute
-# worktree path; a relative path or a stale entry matches the wrong processes.
-WT_PATH="$(cd "../<worktree-dir>" && pwd)"
+# WT-4b — bounded CWD-holder cleanup (task 0720 R1). $WT_PATH above is the EXACT
+# absolute worktree path; a relative path or a stale entry matches the wrong processes.
 # Holders = processes with any open fd under the worktree tree (lsof +D walks the
 # tree; CWD holders are the common case but +D also catches open-file holders —
 # over-match errs toward removal success; a plain -t <dir> matches only the
@@ -976,6 +1002,8 @@ fallback, because `<name>` was explicit and unambiguous intent.
 - **`--mode implement`** is rejected when combined with `--worktree` on `dev-run` — that mode *is*
   the pipeline's implement stage (bug-742) and runs in whatever tree the driver set up; a second
   worktree would split one task's evidence across two trees.
+- **`dev-review` without `--triage`** is rejected when combined with `--worktree` — a read-only
+  review writes nothing worth isolating; review another worktree by passing a path inside it.
 - **No** create-with-name (`--worktree <name>` never creates; an unresolvable name is an error),
   no `--worktree-keep` variant, no auto-cleanup of stale worktrees or markers from prior runs.
 

package/plugins/sp/skills/spur-dev/references/flag-glossary.md

@@ -69,6 +69,14 @@ inline is the default selector and omitted/explicit `inline` resolve identically
 the concrete coding-agent tool; `executor` remains the domain-layer role and is not a command flag.
 `inline` and `auto` are reserved values — config validation rejects an executor claiming either.
 
+**Fleet executor (0942, ADR-126, opt-in).** On the pipeline selectors (`dev-run`, `dev-runall`),
+`--agent fleet` maps the workflow run to the executor var `executor: 'fleet'`: every `agent.run`
+stage dispatches through the agent fleet control plane instead of spawning a subprocess, with a
+subprocess fallback only when the run declares `executorFallback: 'traditional'`; otherwise an
+unavailable fleet fails the stage loudly (0937 `failed-agent`). `fleet` is deliberately not part of
+the `<inline|auto|name>` selector grammar above — the value table and the executor precedence chain
+are unchanged. Contract: [fleet-config-declaration.md](../../../../../docs/design/fleet-config-declaration.md).
+
 #### `--inline` (removed — collapsed into `--agent`)
 
 **Anchor:** `#flag-inline` (stub retained to avoid dangling external links).
@@ -402,6 +410,17 @@ Full checklist: [dev-operations.md](dev-operations.md) § refine (depth ready).
 Use the task's Gherkin scenarios as the verification lens on verify-family commands (`dev-verify`,
 `dev-verifyall`).
 
+### `--triage` — fix small findings, file the rest as tasks
+
+**Anchor:** `#flag-triage`.
+
+Review commands (`dev-review`, `dev-review-session`): after the report, bucket every finding once
+(direct fix / task / note), apply the direct fixes inline with a targeted check each, and file the
+remainder through `spur task` — never fix straight from the raw findings list. Off by default
+(report-only). Both file one or more implement-ready tasks sized per cohesive unit, under existing
+features ([dev-operations.md § 2. review](dev-operations.md#2-review)); `dev-review-session` keeps
+the stricter direct-fix bar (pure docs / one-to-two-line fixes).
+
 ### `--approve-taste` — pre-clear all taste gates this run
 
 **Anchor:** `#flag-approve-taste`.
@@ -414,9 +433,11 @@ flag sets both.
 
 **Anchor:** `#flag-worktree`.
 
-Batch commands plus single-task `dev-run` (`dev-refineall`, `dev-runall`, `dev-verifyall`,
-`dev-run`): run the entire driver loop inside an isolated git worktree instead of the operator's
-working directory. One flag, two modes:
+Batch commands plus single-task `dev-run` and review triage (`dev-refineall`, `dev-runall`,
+`dev-verifyall`, `dev-run`, `dev-review`): run the entire driver loop inside an isolated git
+worktree instead of the operator's working directory. On `dev-review` the flag requires `--triage`
+and wraps the review-plus-triage pass
+([dev-operations.md § 2. review](dev-operations.md#2-review)). One flag, two modes:
 
 - **Create mode** — bare `--worktree` (no value). Cut a fresh branch from the current HEAD's ref,
   create a sibling worktree with a derived name, run the batch there. On a fully successful batch

package/plugins/sp/skills/spur-dev/references/gate-checklists.md

@@ -89,8 +89,9 @@ Entered before `task-pipeline.yaml` `review` state dispatches `sp:code-verificat
 
 - [ ] The implementation matches the task's `## Plan` checklist (every checked item maps to a code/test/doc change).
 - [ ] `git status` shows only changes traceable to this task's Plan (no drive-by edits).
-- [ ] Lint and typecheck pass (`bun run lint`).
-- [ ] Tests pass (`bun run test`) — no `.skip`, `xfail`, or commented-out tests.
+- [ ] Check receipt current: `quality-gate.ts status` reports `reuse: true` for
+      `.spur/run/<wbs>-check-receipt.json` at the current digest; run `bun run spur-check` only
+      when it reports stale or missing (0940 — never re-run the full chain on a reusable receipt).
 - [ ] New `biome-ignore` / `eslint-disable` suppressions: none, or each is justified inline.
 - [ ] No new `console.*` in scripts (use a project logger if one exists).
 - [ ] The `## Solution` section records the file:line change map and rationale.

package/plugins/sp/skills/spur-dev/references/inline-pipeline-driver.md

@@ -23,7 +23,7 @@ the resolved actions and guards of every `.spur/workflows/*.yaml`; any element p
 in one and absent in the other fails the check. Add a new kind here when the driver
 implements it; remove the entry when the corresponding kind is dropped from the YAML.
 
-**Actions:** `shell` · `note` · `doctor.probe` · `file.read.into-var` · `hitl.confirm` · `hitl.input` · `hitl.select` · `agent.run` · `proof.fingerprint` · `run.artifact` · `command.gate`
+**Actions:** `shell` · `note` · `doctor.probe` · `file.read.into-var` · `hitl.confirm` · `hitl.input` · `agent.run` · `proof.fingerprint` · `run.artifact` · `command.gate` · `decide`
 
 **Guards (transitions):** `always` · `shell` · `action-ok` · `contract-violation`
 
@@ -497,6 +497,27 @@ The driver reaches it through the existing run delegate (`$SETUP_SCRIPT`,
   (0887 R8), so `completed_at − started_at == duration_ms` exactly; a back-date failure is
   recorded (`action.backdate`) and never affects the run.
 
+- **A `decide` action (0941)** — the driver never executes the DecisionMaker itself; it delegates
+  to the same app runner the engine registers, which writes the resultFile row (schemaVersion 1)
+  and returns the decision, then the delegate records the `action_runs` row (`kind=decide`)
+  through the same writer as every other action:
+
+  ```bash
+  bun "$SETUP_SCRIPT" --decide --run-id "$RUN_ID" --node <state-id> --options-json <options-file>
+  ```
+
+  The options JSON mirrors the YAML `decide` options (`id`, `method: choice|noul`, `question`,
+  `choices`/`default`, optional `evidence`, optional `minConfidence`, `resultFile`); paths resolve
+  against the project workdir. The decision never pauses and never fails the run for model
+  problems: a degraded outcome (feature switch off, no backend, error, timeout, low confidence)
+  prints `ok:true` with `degraded:true`, the declared `reason`, and `value = default`, and exits
+  `0` — route on the resultFile's `.value` with the declared file guards. Every row carries
+  `source: model|default` (0976 R2), and the delegate appends
+  `decide node=<id> value=<v> source=<s> reason=<r>` to the run log, so a declared-default
+  fallback is never read as a model decision. Only an invalid options
+  schema exits `1` (fail closed), and usage errors exit `2`. The `action_runs` trace row is
+  best-effort exactly like `--action`.
+
 - **At the run's declared terminal state** — before the driver reports the run complete, close the
   row so a successful inline run is never left non-terminal for `spur workflow clean` to reap as
   stale:
@@ -506,7 +527,18 @@ The driver reaches it through the existing run delegate (`$SETUP_SCRIPT`,
   ```
 
   `--status` is the declared terminal state's verdict, not a guess: a run that reached a terminal
-  state is `done`; a run halted by a failing action under its error policy is `failed`.
+  state is `done`; a run halted by a failing action under its error policy is `failed`. On success
+  the close reports the recorded evidence: `{"ok":true,"runId":…,"actionRows":<n>}`.
+
+  **Zero-row done closes are a named failure (task 0975 R2).** A run closed `done` with **zero**
+  `action_runs` rows (`actionRows:0`) finalizes the row but exits `1` with
+  `{"ok":false,"code":"NO_ACTION_ROWS","actionRows":0}` — a run that claims success without a
+  single recorded action is exactly the untraced-runs gap ADR-117 closes, so the driver must
+  surface the code in its final report instead of reporting a clean close. The failure must NOT
+  be repaired by backfilling rows: the run row is already terminal, and hand-written rows are
+  forbidden (ADR-117) — record the finding and let the task's evidence show the gap. A `failed`
+  close with zero rows stays a clean `0` (a halt before the first boundary legitimately records
+  nothing), and any `done` close with `actionRows ≥ 1` exits `0`.
 
 **Best-effort at the action boundary only (ADR-117).** An `--action` persistence failure is
 recorded — the delegate appends a `trace-emission-failed` line to `.spur/run/<run-id>.md` and

package/plugins/sp/skills/spur-dev/references/planning-workflow.md

@@ -198,11 +198,11 @@ task Design.
 order (§4.5 rule 5 / sync trigger **T9**):
 
 1. **Satellite first.** Write/update `docs/design/<slug>.md`. `<slug>` is the stable grep anchor —
-   derive it from the feature name (kebab-case), and **reuse the existing slug** on re-runs. Capture
-   the chosen approach + one-line reason, rejected alternatives, key interface/type **signatures**
-   (not bodies), invariants, and the surface it touches. Do **not** restate the satellite file format
-   here — follow the shape of existing satellites (`docs/design/server-side-adjustment-design.md`,
-   `workflow-observability.md`).
+   derive it from the feature name (kebab-case), and **reuse the existing slug** on re-runs. For a
+   new file use [document-authoring.md](document-authoring.md) and its design template; for an
+   existing file preserve its headings and anchors. Capture the chosen approach + one-line reason,
+   rejected alternatives, key interface/type **signatures** (not bodies), invariants, and the
+   surface it touches.
 2. **Index second.** Add or update the satellite's row in `docs/04_DESIGN.md §0` (the `| Satellite |
    Area | Status |` table) — pointer + one-line area + status only, never a restatement of the body.
 

package/plugins/sp/skills/spur-dev/templates/design.md

@@ -0,0 +1,31 @@
+---
+kind: design
+title: <specific non-UI contract or system design>
+status: proposed
+created_at: YYYY-MM-DD
+updated_at: YYYY-MM-DD
+related: []
+tags: []
+---
+
+# <Specific non-UI contract or system design>
+
+## 1. Issue and scope
+
+<Specific issue or tasks this design addresses, observed impact, boundaries, and whether the solution is proposed or current. Link the owning records.>
+
+## 2. Context and constraints
+
+<Relevant current behavior, evidence for the issue, and constraints the solution must respect. Link to 03 for wider architecture.>
+
+## 3. Solution
+
+<Chosen approach and how it resolves the issue. Show ownership, boundaries, and flow; distinguish proposed behavior from implemented behavior.>
+
+## 4. Contract and compatibility
+
+<Observable inputs, outputs, defaults, errors, invariants, edge cases, and migration behavior needed to implement or use the solution. Omit inapplicable parts.>
+
+## 5. Tradeoffs and open questions
+
+<Why this solution was chosen, material costs or alternatives, and unresolved questions or follow-up. Link ADR decisions instead of restating them.>

package/plugins/sp/skills/spur-dev/templates/plan.md

@@ -0,0 +1,32 @@
+---
+kind: plan
+title: <specific title>
+status: draft
+created_at: YYYY-MM-DD
+updated_at: YYYY-MM-DD
+related: []
+tags: []
+---
+
+# <Specific title>
+
+## 1. Objective and outcome
+
+<Issue or tasks this plan addresses, intended result, scope, and how completion will be recognized. Link the owning feature or tasks.>
+
+## 2. Premises and dependencies
+
+<Facts, assumptions, prerequisites, decisions, and blockers that affect the sequence. Link evidence; mark unverified premises.>
+
+## 3. Execution sequence
+
+1. <Action, prerequisite, and tangible output or checkpoint. Name an owner when coordination matters.>
+2. <Next action. Show dependencies and safe parallel work explicitly.>
+
+## 4. Risks and verification
+
+<What could change the sequence, the fallback or decision point, and how the intended result will be verified.>
+
+## 5. Follow-up
+
+<Handoff, remaining actions, and deferred work with owners or links when known. Omit if none.>