@gobing-ai/spur 0.4.14 → 0.4.16

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

@@ -147,7 +147,7 @@ must not be changed without updating the backing skill.
 - **Purpose:** Batch verification of a set of tasks (or all tasks under a feature) against their requirements and AC. Produces per-task verdicts + a summary report with aggregate statistics (counts, table, overall batch verdict). With `--fix all`, also evaluates **feature shippable readiness** once for the set.
 - **Inputs:** `--tasks <selector>` (required unless `--feature`). `--feature <id>` (convenience for `--tasks feature:<id>`). Shared verify flags from `dev-verify` (`--agent <inline|auto|name>`, `--fix`, `--focus`, `--bdd`, `--auto`, `--force`, **`--skip-shippable`**). `--next` (per-task lifecycle chaining: on a PASS verdict transition `testing → done` through the FSM with the target-aware `--as done` guard honored; PARTIAL/FAIL does not transition; transitions run **before** the shippable gate so `spur feature check` sees final statuses). `--json` for machine-readable summary report.
 - **Backing:** `sp:spur-dev` skill, `verifyall` operation (resolves the set using the shared selector grammar, dispatches per-task verify via `sp:code-verification` verify mode, writes per-task artifacts, aggregates and emits the batch summary report, then optional shippable gate).
-- **Behavior:** Resolve + freeze the set (supports `--feature` sugar). For each task: apply status guard, requirements traceability + AC + SECUA review, emit the verdict artifact (per-task fix pass under `--fix`). `## Testing` is written by the deterministic `record` step from the artifact (F92 0593 R1). After the batch: **shippable gate once** when active (see below). Emit a structured summary report (markdown or `--json`). Per-task behavior matches single `dev-verify` (except shippable is batch-once). **Batch verdict rollup is deterministic** — computed by `spur task verifyall-aggregate --from-file <batch-input.json> --json` (a tested service module, not agent discretion). **Per-task outcome grammar:** `PASS` / `PARTIAL` / `FAIL` for implemented tasks; `NOT-STARTED` for tasks that have not entered implementation (status `backlog`/`todo`/`blocked` — reachable only via `--force`). **Rollup rule:** all-NOT-STARTED → `UNKNOWN`; any `FAIL` → `FAIL`; any `PARTIAL` or `UNKNOWN` → `PARTIAL`; all `PASS` → `PASS`. NOT-STARTED rows are _excluded_ from the FAIL/PARTIAL rollup (they cannot manufacture a batch failure) but are _reported explicitly_ in the summary ("N NOT-STARTED, excluded from rollup"). This closes the 0341 dogfood gap where a healthy feature with 5 PASS + 2 unstarted tasks read as FAIL. **Shippable FAIL:** treat the batch as not clean — force rollup to at least **PARTIAL** and set `"shippable": false` under `--json` even if every task outcome is PASS.
+- **Behavior:** Resolve + freeze the set (supports `--feature` sugar). For each task: apply status guard, requirements traceability + AC + SECUA review, emit the verdict artifact (per-task fix pass under `--fix`). `## Testing` is written by the deterministic `spur task record` close from the artifact (F92 0593 R1). After the batch: **shippable gate once** when active (see below). Emit a structured summary report (markdown or `--json`). Per-task behavior matches single `dev-verify` (except shippable is batch-once). **Batch verdict rollup is deterministic** — computed by `spur task verifyall-aggregate --from-file <batch-input.json> --json` (a tested service module, not agent discretion). **Per-task outcome grammar:** `PASS` / `PARTIAL` / `FAIL` for implemented tasks; `NOT-STARTED` for tasks that have not entered implementation (status `backlog`/`todo`/`blocked` — reachable only via `--force`). **Rollup rule:** all-NOT-STARTED → `UNKNOWN`; any `FAIL` → `FAIL`; any `PARTIAL` or `UNKNOWN` → `PARTIAL`; all `PASS` → `PASS`. NOT-STARTED rows are _excluded_ from the FAIL/PARTIAL rollup (they cannot manufacture a batch failure) but are _reported explicitly_ in the summary ("N NOT-STARTED, excluded from rollup"). This closes the 0341 dogfood gap where a healthy feature with 5 PASS + 2 unstarted tasks read as FAIL. **Shippable FAIL:** treat the batch as not clean — force rollup to at least **PARTIAL** and set `"shippable": false` under `--json` even if every task outcome is PASS.
 - **Shippable readiness (default on with `--fix all`):** Active when `--fix all` and feature context exists (`--feature` or unique shared `feature_id`) and not `--skip-shippable`. Procedure: `sp:code-verification` Step 13 once after all per-task legs. Without `--fix all`, do not run the hard gate (optional note: use `--fix all` for ship evaluation).
 - **Cache discipline (batch):** freeze the `spur task list --feature <id> --json` (or selector) capture once at resolve; reuse that snapshot for every per-task verify leg. Do not re-list the set mid-batch. Re-read a task body only when that task's sections changed (e.g. after a `--fix` write). Prefer re-reading only cited `file:line` anchors over re-tokenizing full Solution sections when prior Testing is already present.
 - **Dogfood / mutation composition:** prefer step-split when dogfooding verifyall with `--fix all` and/or `--next` — first observe-only verifyall, then a separate fix pass, then `--next` only if status transitions are still needed. See `sp:dogfood-testing` §step-splitting.
@@ -159,7 +159,7 @@ must not be changed without updating the backing skill.
 - **Inputs:** `<wbs>` (required). `--mode <full|implement>` selects the execution mode. `implement` invokes `sp:code-implementation` inline by default. Interactive `full` resolves the selector uniformly (task 0687): omit ≡ explicit `--agent inline`; full mode reads `task-pipeline.yaml` and drives its actions/guards in the host session — host-controlled and non-subprocess, with 0508 eligibility applying to the resolved-inline selector (eligible `agent.run` stages dispatch once to a native subagent, host fallback)). `--agent auto`, a name, or headless invocation launches the workflow subprocess. `--agent <inline|auto|name>` selects the execution surface (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips the HITL approve gate / confirmations and propagates down the `--next` chain. `--next` controls chaining only and never changes the mode; a pipeline implement stage must invoke `/sp:dev-run <wbs> --mode implement`. On implement success with `--next`, transition `todo → wip → testing` through the FSM (guards honored — no `--no-lifecycle`) + chain to `/sp:dev-verify <wbs> --auto --next`. On a guard failure, stop as review-pending. **Partial-deliverable rule:** if the task ships only part of its requirements (e.g. an R1/R2 split with the rest in a follow-up task), the `## Solution` section must state that explicitly and the verify verdict will record the scope. `--worktree [<name>]` runs the full pipeline inside an isolated git worktree (create or reuse; FF-merge on success, retain on failure) — the batch lifecycle in [execution-batch.md § Worktree isolation](execution-batch.md#worktree-isolation---worktree-name) applied to a batch of one; rejected with `--mode implement`. `--no-summary` skips the [execution summary](#execution-summary) printed after a full-mode run. `--wrap` hands off to `/sp:dev-wrap <wbs>` after the main step; the `--agent` selector is preserved into that handoff when supplied (omission remains omission), and the wrap hop reports its own trigger-3 subprocess override per the wrap contract.
 - **Backing:** `sp:spur-dev` skill — `run` operation for the full pipeline (the spine drives it); `sp:code-implementation` competency skill for the implement step (the spine dispatches to it).
 - **Modes:**
-  - **`full`** (default): Drive the full pipeline — precheck → implement → test → review → approve(HITL) → verify → record → done. Interactive omit/inline runs `spur workflow run task-pipeline.yaml --vars '{"wbs":"<wbs>","executor":"host"}'` and performs each returned work item (eligible stages may use a native subagent); explicit/headless executor selection runs the same definition without the `executor` var (with `profile: auto` when `--auto`). Both monitor/surface HITL and preserve the YAML gates. `--next` never changes this mode.
+  - **`full`** (default): Drive the full pipeline — precheck → implement → gate ⇄ remediate → review → done, with the repair, stop and approval routes taken from decision rows ([decision-points.md](decision-points.md)). Interactive omit/inline runs `spur workflow run task-pipeline.yaml --vars '{"wbs":"<wbs>","executor":"host"}'` and performs each returned work item (eligible stages may use a native subagent); explicit/headless executor selection runs the same definition without the `executor` var (with `profile: auto` when `--auto`). Both monitor/surface HITL and preserve the YAML gates. `--next` never changes this mode.
   - **`implement`** (explicit `--mode implement` only): Execute only the implement step. Read the task's `## Requirements` / `## Design` / `## Plan`, write the code that satisfies them, author the `## Solution` change-map section (file:line + what/why per changed file) via `spur task update <wbs> --section Solution --from-file`. This is the implement step the pipeline calls — it is NOT the pipeline driver. With `--next`: on success, transition `todo → wip → testing` through the FSM (guards honored — no `--no-lifecycle`) + chain to `/sp:dev-verify <wbs> --auto --next`; on a guard failure, stop as review-pending. **Partial-deliverable rule:** if the task ships only part of its requirements (e.g. an R1/R2 split with the rest in a follow-up task), the `## Solution` and `## Review` sections MUST carry a `⚠️ PARTIAL` marker naming the deferred part and the follow-up WBS — see `plugins/sp/commands/dev-run.md` → "Section ownership".
 - **Delegation:** `Skill(skill="sp:spur-dev", args="run $ARGUMENTS")` for both full-mode paths (the `executor` var picks host session vs child process); `Skill(skill="sp:code-implementation", args="$ARGUMENTS")` for implement mode.
 
@@ -366,13 +366,13 @@ check receipt (`receipt.runId === runId`), otherwise `n/a (<reason>)`. Any value
 
 ### 6. plan
 
-- **Purpose:** Plan a feature from a description — intake → feature create → AC generation → feature check gate → decomposition → batch-create (with **Design by default**).
+- **Purpose:** Plan a feature from a description — intake → feature create → AC generation → decomposition → batch-create (with **Design by default**).
 - **Inputs:** `"<description>"` (required). `--feature <id>` links to an existing feature. `--parent <feature-id>` nests under a parent. Omitted/`inline` drives `idea-pipeline.yaml` in the host session; `auto` or a name launches the async workflow worker. **Design package flags (unified with `/sp:dev-idea`):**
   - **Default:** author task `design` on every batch item + feature satellite when the seam heuristic fires (**ties lean design**). There is **no** `--design` force flag.
   - `--skip-design` — skip feature satellite **and** omit task `design` fields (scaffold only; refine fills later). Sole design opt-out.
   - `--auto` — accept the recommendation at every operator gate, taste gates included (same contract as § 16 idea).
 - **Backing:** `sp:spur-dev` skill, `plan` operation. Stage floor: the `planner` role per [`roles.md`](../../../references/roles.md) — this file names roles, never tiers (0538 R4).
-- **Behavior:** Clarify scope → `spur feature create` → author BDD AC → `spur feature check` gate → decompose into task-batch JSON **including `design` (unless `--skip-design`)** → `spur task batch-create` gate. Design package details: [planning-workflow.md](planning-workflow.md) Step 5.5.
+- **Behavior:** Clarify scope → `spur feature create` → author BDD AC → decompose into task-batch JSON **including `design` (unless `--skip-design`)**. The pipeline then runs `spur feature check` on the recorded AC (`ac-generate`) and `spur task batch-create` (`batch-create-run`) as deterministic steps that route on their recorded result — neither is an operator gate. Design package details: [planning-workflow.md](planning-workflow.md) Step 5.5.
 - **Delegation:** `Skill(skill="sp:spur-dev", args="plan $ARGUMENTS")`
 
 ### 7. docs
@@ -489,10 +489,10 @@ gate commands, pending questions and approval requirements.>
 
 ### 14. wrap
 
-- **Purpose:** Wrap up a single completed task — capture learnings, record metrics, sync docs, and optionally advance the feature / clean up the branch.
+- **Purpose:** Wrap up a single completed task — capture learnings, record metrics, sync docs, and optionally clean up the branch.
 - **Inputs:** `<wbs>` (required, positional). `--agent <inline|auto|name>` names the wrap's model-bearing executor (default: `inline`, resolving identically when omitted; task 0687); wrap is workflow-backed (headless), so omit ≡ explicit `inline` (task 0687): tier substitution under objective trigger 3 (durable auditable run record required) plus one warning naming the substituted executor. `auto` tier-resolves an executor, and a name pins that executor into `vars.agent` (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips objective confirmations (the branch-cleanup HITL gate still pauses — irreversible). `--merge` triggers branch cleanup (irreversible HITL gate).
 - **Backing:** `spur workflow run wrapup-pipeline.yaml` — direct workflow invocation (no backing skill; the pipeline IS the procedure).
-- **Behavior:** Resolves the executor (`agent.default` for omit/`inline`, tier-resolved for `auto`, unchanged for a name), emits a pre-dispatch notice naming the subprocess override — `execution surface: subprocess`, `reason: trigger 3 — durable auditable run record required`, `requested agent: <selector>`, `executor: <resolved>` — then builds `--vars '{"tasks":"[\"<wbs>\"]","agent":"<resolved>","profile":"interactive|auto","merge":"true|false"}'` and invokes the wrapup pipeline. The pipeline runs: task-resolve → doc-sync → learnings-validate → learnings-append → doc-tripwire → metrics-record → (feature-transition) → (branch-cleanup) → done. `doc-tripwire` (1037) runs the TRUSTED CONFIG ONLY `docTripwireCmd` over the still-uncommitted wrap diff after the doc-sync exits converge — the default runs `bun run test-repo-wide` only when `package.json` declares the script (a no-op in other projects); override it via `--vars`, and an empty string disables the check while still recording PASS; a FAIL fails the wrap with already-written learnings/docs preserved. Task statuses are NOT mutated. Branch cleanup is an irreversible HITL gate that always pauses, even under `--auto`.
+- **Behavior:** Resolves the executor (`agent.default` for omit/`inline`, tier-resolved for `auto`, unchanged for a name), emits a pre-dispatch notice naming the subprocess override — `execution surface: subprocess`, `reason: trigger 3 — durable auditable run record required`, `requested agent: <selector>`, `executor: <resolved>` — then builds `--vars '{"tasks":"[\"<wbs>\"]","agent":"<resolved>","profile":"interactive|auto","merge":"true|false"}'` and invokes the wrapup pipeline. The pipeline runs: task-resolve → doc-sync → learnings-validate → learnings-append → doc-tripwire → metrics-record → (branch-cleanup) → done. `doc-tripwire` (1037) runs the TRUSTED CONFIG ONLY `docTripwireCmd` over the still-uncommitted wrap diff after the doc-sync exits converge — the default runs `bun run test-repo-wide` only when `package.json` declares the script (a no-op in other projects); override it via `--vars`, and an empty string disables the check while still recording PASS; a FAIL fails the wrap with already-written learnings/docs preserved. Task and feature statuses are NOT mutated. Branch cleanup is an irreversible HITL gate that always pauses, even under `--auto`.
 - **Vars string typing:** `tasks` is a JSON-encoded **string**, not a JSON array — `spur workflow run --vars` accepts only string values (`--vars values must be strings`); the pipeline's guards parse the string with `jq length`. `jq -nc` guarantees the shape:
 
   ```bash
@@ -505,15 +505,15 @@ gate commands, pending questions and approval requirements.>
 
 ### 15. wrapall
 
-- **Purpose:** Wrap up a batch of completed tasks — capture learnings, record metrics, sync docs, advance a feature through legal lifecycle edges, and optionally clean up branches.
-- **Inputs:** `--since <iso-date>` filters done tasks by frontmatter `updated_at >= date` (v1 approximation). `--feature <id>` selects all tasks under a feature AND advances the feature through legal lifecycle edges (`backlog → active → verifying → done`, guards honored). `--status <s>` (default: `done`) filters by task status. `--agent <inline|auto|name>` names the wrap's model-bearing executor (default: `inline`, resolving identically when omitted; task 0687); wrap is workflow-backed (headless), so omit ≡ explicit `inline` (task 0687): tier substitution under objective trigger 3 (durable auditable run record required) plus one warning naming the substituted executor. `auto` tier-resolves an executor, and a name pins that executor into `vars.agent` (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips objective confirmations. `--merge` triggers branch cleanup (irreversible HITL gate).
+- **Purpose:** Wrap up a batch of completed tasks — capture learnings, record metrics, sync docs, and optionally clean up branches.
+- **Inputs:** `--since <iso-date>` filters done tasks by frontmatter `updated_at >= date` (v1 approximation). `--feature <id>` selects all tasks under a feature; it no longer advances the feature — wrap-up owns post-task knowledge work only (1249 R1/R5), so follow the batch with `spur feature sync <id>` if a transition is wanted. `--status <s>` (default: `done`) filters by task status. `--agent <inline|auto|name>` names the wrap's model-bearing executor (default: `inline`, resolving identically when omitted; task 0687); wrap is workflow-backed (headless), so omit ≡ explicit `inline` (task 0687): tier substitution under objective trigger 3 (durable auditable run record required) plus one warning naming the substituted executor. `auto` tier-resolves an executor, and a name pins that executor into `vars.agent` (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips objective confirmations. `--merge` triggers branch cleanup (irreversible HITL gate).
 - **Backing:** `spur workflow run wrapup-pipeline.yaml` — direct workflow invocation.
-- **Behavior:** Resolves the task list via `spur task list --json` (filtered by `--feature`, `--since`, `--status`), resolves the executor (omission and explicit `--agent inline` tier-substitute identically with a warning per task 0687, `auto` tier-resolves, a name pins), emits a pre-dispatch notice naming the subprocess override — `execution surface: subprocess`, `reason: trigger 3 — durable auditable run record required`, `requested agent: <selector>`, `executor: <resolved>` — then builds `--vars '{"tasks":"[...]","feature":"<id>","agent":"<resolved>","profile":"interactive|auto","merge":"true|false"}'` and invokes the wrapup pipeline. The pipeline runs the same states as `wrap` — including the `doc-tripwire` hop (1037), whose TRUSTED CONFIG ONLY `docTripwireCmd` runs the repo-wide tripwires over the still-uncommitted wrap diff and can be overridden or disabled (empty string) via `--vars` — but with the full task list and optional feature transition. Task statuses are NOT mutated. Feature transitions go through `spur feature update` so lifecycle guards apply. Branch cleanup is an irreversible HITL gate.
+- **Behavior:** Resolves the task list via `spur task list --json` (filtered by `--feature`, `--since`, `--status`), resolves the executor (omission and explicit `--agent inline` tier-substitute identically with a warning per task 0687, `auto` tier-resolves, a name pins), emits a pre-dispatch notice naming the subprocess override — `execution surface: subprocess`, `reason: trigger 3 — durable auditable run record required`, `requested agent: <selector>`, `executor: <resolved>` — then builds `--vars '{"tasks":"[...]","agent":"<resolved>","profile":"interactive|auto","merge":"true|false"}'` and invokes the wrapup pipeline. The pipeline runs the same states as `wrap` — including the `doc-tripwire` hop (1037), whose TRUSTED CONFIG ONLY `docTripwireCmd` runs the repo-wide tripwires over the still-uncommitted wrap diff and can be overridden or disabled (empty string) via `--vars` — but with the full task list. Task and feature statuses are NOT mutated. Branch cleanup is an irreversible HITL gate.
 - **Vars string typing:** `tasks` is a JSON-encoded **string**, not a JSON array — `--vars` values must be strings (the CLI rejects raw arrays); `jq -nc` passes the array text through as a string value:
 
   ```bash
-  VARS=$(jq -nc --arg tasks "$TASKS" --arg feature "$FEATURE" --arg agent "$AGENT" --arg profile "$PROFILE" --arg merge "$MERGE" \
-    '{tasks:$tasks, feature:$feature, agent:$agent, profile:$profile, merge:$merge}')
+  VARS=$(jq -nc --arg tasks "$TASKS" --arg agent "$AGENT" --arg profile "$PROFILE" --arg merge "$MERGE" \
+    '{tasks:$tasks, agent:$agent, profile:$profile, merge:$merge}')
   spur workflow run wrapup-pipeline.yaml --vars "$VARS"
   ```
 
@@ -538,7 +538,7 @@ gate commands, pending questions and approval requirements.>
   fails the run when that file is empty or missing, and every model-bearing stage prompt treats
   it as the authoritative ask (R2).
 - **Backing:** `idea-pipeline.yaml` on the host executor (`vars.executor: host`, advanced by `spur workflow continue`) for omitted/`inline`, or `spur workflow run idea-pipeline.yaml --async` for `auto`/name.
-- **Behavior:** Builds vars from the table above and drives the idea pipeline. Flow: discovery → **idea-eval** (taste; reject → cancelled) → feature-create → ac-generate → feature-check → system-design (conditional) → design-approval (taste) → decompose → batch-create (`--skip-ready`) → ready-prepare (ready checklist per created task + ready-evidence sidecar, 0788) → handoff. STOPS at handoff — no task execution, no pipeline nesting. Headless runs use one `trace --follow`; cancellation is reported stopped only when `workflow cancel --json` returns `killed: true`.
+- **Behavior:** Builds vars from the table above and drives the idea pipeline. Flow: discovery → **idea-eval** (taste; reject → cancelled) → feature-create → ac-generate → system-design (conditional) → design-approval (taste) → decompose → batch-create-run (`--skip-ready`) → ready-prepare (ready checklist per created task + ready-evidence sidecar, 0788) → handoff-finalize → handoff. STOPS at handoff — no task execution, no pipeline nesting. Headless runs use one `trace --follow`; cancellation is reported stopped only when `workflow cancel --json` returns `killed: true`.
 - **Delegation:** Host executor (this session answers each work item) by default; explicit executor selection uses the async workflow worker.
 - **Idea-evaluation gate:** After discovery, operator reviews `.spur/run/idea-eval-report.md` ([idea-evaluation.md](idea-evaluation.md)). Approve continues; reject/cancel → no feature. Under `--auto`, follows the report's recommendation (`drop` → cancelled; missing recommendation → pauses). Enhanced idea is a sidecar — `vars.idea` is not overwritten.
 - **Design package (`--skip-design` only):**
@@ -569,7 +569,7 @@ These define their procedure directly in the command file. No `Skill()` delegati
 is the procedure. The backing is a combination of git CLI, `spur` CLI, and agent reasoning.
 
 **Gate ownership.** A project quality gate (`spur self exec autofix|check|lint`, typecheck, tests,
-rule runs) runs only where an operation's own contract names it: the pipeline `test` hop
+rule runs) runs only where an operation's own contract names it: the pipeline `gate` state
 (`run`/`runall`), `fixall`, `gtd`, `fixgha`, `unit`, and the `--check <cmd>` loops. The scribe
 operations — `changelog`, `gitmsg`, `handover`, `job-dump` — produce text or a commit, not code, so
 they run **no gate by default**, and a generic "verify before you finish" rule from `AGENTS.md` or
@@ -683,7 +683,7 @@ host instructions does not add one. An opt-in gate is explicit: `gitmsg --check
 ### 10. fixall
 
 - **Purpose:** Fix all lint, type, and test errors systematically across the working tree.
-- **Inputs:** `--scope <path>` (default: entire working tree) — limits fixes to a file or directory. `--gate-log <path>` (R3, task 0482) — before fixing, read this captured validation-run log and start at the `file:line` anchors its findings name, rather than re-deriving the failure from a fresh gate run. `--findings <anchors>` (R3, task 0482) — space-separated `file:line` anchors already extracted from that log by the `test` hop; when present these ARE the failing set, so fix them in order and do not run the gate to discover what broke.
+- **Inputs:** `--scope <path>` (default: entire working tree) — limits fixes to a file or directory. `--gate-log <path>` (R3, task 0482) — before fixing, read this captured validation-run log and start at the `file:line` anchors its findings name, rather than re-deriving the failure from a fresh gate run. `--findings <anchors>` (R3, task 0482) — space-separated `file:line` anchors already extracted from that log by the `gate` state; when present these ARE the failing set, so fix them in order and do not run the gate to discover what broke.
 - **Backing:** `inline` — lint + test fix loop.
 - **Behavior:** 0. **Start at the anchors, never at a discovery run.** If `--findings <anchors>` is given, that space-separated `file:line` list IS the failing set — open those locations first, in order, and fix them; do not run the gate to find out what broke. If only `--gate-log <path>` is given, read that log first and identify the failing findings (lint/test errors with their `file:line` anchors) before running the loop — the captured log is the authoritative source. Either way the first action of this hop is a read, not a gate run (R3, task 0482).
   1. Inspect the project's formatter command, then settle formatter-only diffs. Without `--scope`, use the project formatter (here `spur self exec format`). With `--scope`, use a formatter invocation whose only path operands are inside the selected scope — for Biome, `bunx biome check --write "$SCOPE"`. Never append a path to a script already containing `.`: `biome check . --write <path>` still writes across the repository. Preserve quoted paths and apply the same scope to every later formatting pass. If no scoped formatter is available, report that limitation and leave out-of-scope files untouched. Here `spur self exec lint` checks formatting without rewriting it and also runs typecheck; formatting errors fail that check.
@@ -695,9 +695,9 @@ host instructions does not add one. An opt-in gate is explicit: `gitmsg --check
   7. If tests are green, proceed to the applicable standalone confirmation or pipeline handoff below.
   8. **Test fix loop:** for each in-scope failure, diagnose (test bug vs implementation bug), apply the fix, re-run the **failing test only** (`bun test <file> --test-name-pattern "<test>"`). Report outside-scope blockers without editing them. Do NOT re-run the full suite per fix — it is the dominant loop cost (task 0436 R2).
   9. **Confirming run — standalone invocation only (at most once).** After all fixes, repeat the scope-safe formatting invocation from step 1, then run the selected validation command **at most once** to confirm (here the default project gate is `spur self exec check`). If it passes, the hop is done. **Skip this step entirely when `--gate-log` is set** (see step 10) — under the pipeline nothing consumes its verdict.
-  10. **Pipeline-awareness (R4, task 0483; confirming run dropped 2026-08-31).** `--gate-log` is set only by the pipeline's `test-fix` hop, so treat it as the pipeline signal. There, `test-recheck` runs the full `${vars.qualityGateCmd}` gate immediately after this hop returns — that is the **deciding** run, the only one that writes PASS to `.spur/run/<wbs>-test-gate.status`. A confirming run inside this hop decides nothing and costs a second full gate (~105 s here) to answer a question `test-recheck` is about to answer anyway. So under `--gate-log`: **run no full gate at all.** Your self-check is what step 8 already gives you — the failing tests you re-ran individually — plus **one `spur self exec lint`** (~7 s: Biome + typecheck) to catch type or lint breakage your fixes introduced. Then return and let `test-recheck` judge. `test-recheck` opens with the same cheap `${vars.gateProbeCmd}` probe, so a still-red tree is caught in seconds rather than by a full suite. Historical anti-pattern this replaces: 0482 ran the gate 3× plus a standalone `bun run test`, and `test-recheck` then ran it a 5th time.
+  10. **Pipeline-awareness (R4, task 0483; confirming run dropped 2026-08-31).** `--gate-log` is set only by the pipeline's `remediate` hop, so treat it as the pipeline signal. There, the `gate` state's recheck visit runs the full `${vars.qualityGateCmd}` gate immediately after this hop returns — that is the **deciding** run, the only one that writes PASS to `.spur/run/<wbs>-test-gate.status`. A confirming run inside this hop decides nothing and costs a second full gate (~105 s here) to answer a question the gate recheck is about to answer anyway. So under `--gate-log`: **run no full gate at all.** Your self-check is what step 8 already gives you — the failing tests you re-ran individually — plus **one `spur self exec lint`** (~7 s: Biome + typecheck) to catch type or lint breakage your fixes introduced. Then return and let the gate recheck judge. It opens with the same cheap `${vars.gateProbeCmd}` probe, so a still-red tree is caught in seconds rather than by a full suite. Historical anti-pattern this replaces: 0482 ran the gate 3× plus a standalone `bun run test`, and the recheck then ran it a 5th time.
   11. Report: list what was fixed (file + one-line summary per fix). If any error could not be resolved, report it explicitly — do not suppress.
-- **Invariants:** Never bypass with `--no-verify`, `--force`, or new `biome-ignore`/`eslint-disable` suppressions. Never skip or `.skip` a test to make the suite green. Fix the root cause, not the symptom. Here lint checks formatting and types; it does not prove that the full test gate passed. Keep every write inside `--scope`. **Never re-run the full gate more than once per confirming pass** (R4) — use targeted probes during the fix loops and let the pipeline's `test-recheck` state be the deciding run.
+- **Invariants:** Never bypass with `--no-verify`, `--force`, or new `biome-ignore`/`eslint-disable` suppressions. Never skip or `.skip` a test to make the suite green. Fix the root cause, not the symptom. Here lint checks formatting and types; it does not prove that the full test gate passed. Keep every write inside `--scope`. **Never re-run the full gate more than once per confirming pass** (R4) — use targeted probes during the fix loops and let the pipeline's `gate` recheck be the deciding run.
 - **MANDATORY Exit Condition — standalone only.** At step 9, execute the following once; do not add another confirming run:
   1. Run validation command: `eval "$VALIDATION_CMD"`
   2. Capture exit code: `EXIT_CODE=$?`
@@ -706,7 +706,7 @@ host instructions does not add one. An opt-in gate is explicit: `gitmsg --check
 
   If EXIT_CODE != 0: NOT completed. Continue the bounded fix loop for in-scope failures; report outside-scope blockers.
 
-  **Pipeline exit condition (`--gate-log` set):** return the fixes and the targeted-test/lint evidence from step 10 to `test-recheck`. Do not run the standalone validation command or claim a full-gate PASS; `test-recheck` owns that verdict.
+  **Pipeline exit condition (`--gate-log` set):** return the fixes and the targeted-test/lint evidence from step 10 to the `gate` recheck. Do not run the standalone validation command or claim a full-gate PASS; the recheck owns that verdict.
 
   **Hallucination Red Flags — STOP if you think:**
   - "The errors look fixed" — check exit code, not appearance
@@ -735,7 +735,7 @@ host instructions does not add one. An opt-in gate is explicit: `gitmsg --check
   └─────────────────────────────────────────────────┘
   ```
 
-  The 7 phases describe standalone execution: Phases 1–2 capture the gate, Phase 3 settles auto-fixable formatting within scope, Phases 4–6 are the per-group root-cause fix loops, Phase 7 is the final verification run. With `--gate-log`, use the supplied evidence instead of capturing the gate again, and hand off to `test-recheck` instead of running Phase 7's full validation.
+  The 7 phases describe standalone execution: Phases 1–2 capture the gate, Phase 3 settles auto-fixable formatting within scope, Phases 4–6 are the per-group root-cause fix loops, Phase 7 is the final verification run. With `--gate-log`, use the supplied evidence instead of capturing the gate again, and hand off to the `gate` recheck instead of running Phase 7's full validation.
 
 - **Fix Priority:**
 

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

@@ -15,7 +15,7 @@ Read at Step 5 and once at batch end (task 1128 R1).
 When the batch finishes — clean (all `done`), halted (default failure policy), parked (`paused`:
 one or more tasks sit on an operator question (escalate, 0933) or an approval gate), or aborted
 (cycle / unknown selector) — emit a structured report. The report is the orchestrator's sole
-output; it does not mutate the corpus (the pipeline's `record` step already wrote per-task
+output; it does not mutate the corpus (the pipeline's `done` state already recorded per-task
 results). A `paused` task is non-terminal — the report marks it `paused` (never `done`) and names
 the resume command. Unless `--no-summary`, follow it with the measured
 [execution summary](dev-operations.md#execution-summary), one `--progress <wbs>=<file>` per attempted run.

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

@@ -112,7 +112,8 @@ bun run apps/cli/src/index.ts feature check <id> --strict --json
   live tasks (a warning in `FeatureCheckService` until `done`); `--strict` elevates both to error,
   so they are reported verbatim but do **not** abort the batch; every other error finding (L1–L3
   structural, `L4.malformed-verdict-artifact`, `L4.uncovered-feature-scenario`) still aborts. The
-  terminal feature-transition gate enforces scenario verification after the batch runs, so pre-run
+  feature-lifecycle done-boundary gate (reached via `spur feature sync <id>`, the forward hop from
+  task-pipeline's done close) enforces scenario verification after the batch runs, so pre-run
   unverified scenarios and incomplete tasks are transient, not defects (dogfood 2026-08-11,
   feature I2; 2026-10-08, feature H1). Extend the set by editing that constant, never this prose.
 - **Auto-repairs are reported.** Structural repairs applied by `--fix` are listed under
@@ -461,14 +462,12 @@ in next-router; this only maps status → primary TABLE A hop for recovery.
 
 ### 3.3c Feature-sync retry suppression (task 0411; 1004 R3)
 
-During a batch, the per-task `record` step and the wrap-up `feature-transition` step each invoke
-feature status sync. When a feature is L4-gate-blocked (e.g. not all linked tasks are `done`), the
-identical blocked proposal repeats on every call with no intervening input change. The service fixes
-this, not the engine.
+During a batch, the per-task `done` state invokes feature status sync. When a feature is
+L4-gate-blocked (e.g. not all linked tasks are `done`), the identical blocked proposal repeats on
+every call with no intervening input change. The service fixes this, not the engine.
 
-Both `task-pipeline.yaml` (`record` step) and `wrapup-pipeline.yaml` (`feature-transition` step)
-invoke `spur feature sync <feature-id> --json` directly — retry suppression lives inside the
-`FeatureService.syncFeature` implementation:
+`task-pipeline.yaml`'s `done` state invokes `spur feature sync <feature-id> --json` directly —
+retry suppression lives inside the `FeatureService.syncFeature` implementation:
 
 1. On a **blocked** result (`gateBlocked` checked first — a partial hop can have `applied: true`
    while still gate-blocked — then an unapplied from≠to deferral), the service persists
@@ -483,7 +482,7 @@ invoke `spur feature sync <feature-id> --json` directly — retry suppression li
    never reads or writes the state.
 
 **Batch driver contract:** the orchestrator does **nothing extra** — the suppression lives inside
-the pipeline's `record` step and the wrap-up's `feature-transition` step. The driver still
+the pipeline's `done` state. The driver still
 launches `task-pipeline.yaml` verbatim (R4.1). Suppression is transparent: the sync emits the same
 `FeatureSyncResult` JSON shape (`suppressed: true` added on replay), so downstream report logic is
 unchanged. The only observable difference is fewer redundant `feature sync` derivations.
@@ -531,6 +530,16 @@ belongs to a subagent or the operator, not to the batch controller's report loop
 By default, the **first** pipeline failure halts the batch. Remaining tasks in the plan are reported
 as `not-attempted`. The report lists succeeded, failed, and not-attempted tasks.
 
+**Run-failed / task-done (observed 2026-10-19, feature P1).** A run can fail *after* the task is
+already finished: the `done` state's close commands run last, and a lint or anchor rule can refuse
+the transition on an otherwise green task. Resolve it the honest way — fix the finding through the
+owning surface, re-run the same close command, and confirm the task reads `done` with a PASS verdict
+— then record the task as `done (run-failed-recovered)` with the failing command in the report.
+That is **not** a `failed` outcome: the failure policy applies to a task that did not reach its
+contract, not to a run whose last recorded state was superseded. Surface it in the report either
+way (never silently continue), and never re-run the pipeline just to flip a run row from `failed` to
+`done` — a second run re-executes model stages for a task that is already closed.
+
 ### 4.2 `--keep-going` (R3.2)
 
 With `--keep-going`, a failed task does **not** halt the batch. Instead:
@@ -650,7 +659,7 @@ Before launching a full `spur-check:full`:
 | R4.3 (`--agent` merged into per-task vars) | Step 3.2 |
 | R5.1 (orchestrator boundary) | "Zero engine code" preamble + Step 3 |
 | R5.2 (structured batch report) | Step 5 |
-| 0411 (bounded feature-sync retry suppression) | Step 3.3c — wrapper lives in pipeline `record` + wrap-up `feature-transition`; driver unchanged |
+| 0411 (bounded feature-sync retry suppression) | Step 3.3c — wrapper lives in pipeline `record`; driver unchanged |
 | 0510 R2 (feature-derived strict preflight) | Step 1 — "Feature-derived strict preflight (R2, task 0510)" |
 | 0510 R5 (metadata-only host controller) | Step 3.4 + projected `task show` / trace snippets in Step 1, 2.3, 3.1 |
 

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

@@ -29,7 +29,7 @@ while ready or running:
         RUN[t] = (cd "$WT" && spur workflow run task-pipeline.yaml \
                   --vars '{"wbs":"<wbs>","deferFeatureSync":"true"[,"deferQualityGate":"true"],...}' --async --json)
                      # deferQualityGate is added ONLY under the opt-in --defer-gate flag (1111 R3):
-                     # the task's `test` hop then runs the light tier and writes DEFERRED.
+                     # the task's `gate` state then runs the light tier and writes DEFERRED.
     wait for any RUN terminal        # trace poll --follow --timeout 600000; stale-evidence rule applies
     on done:    WT-3b commit on $BRANCH → integrate(t)
     on failed:  WT-5 retain (marker retained); failure policy — stop-the-batch default / --keep-going subtree skip
@@ -92,9 +92,9 @@ per-task with `/sp:dev-run <wbs> --worktree <branch>`.
 
 ### Generated regions — defer the sync, regenerate once (R5)
 
-The only per-task writer of feature files is the `record` step's post-record feature sync
+The only per-task writer of feature files is the `done` state's post-record feature sync
 (`task-pipeline.yaml`). Parallel launches set
-the pipeline var `deferFeatureSync: "true"` (default `"false"`): the record step appends
+the pipeline var `deferFeatureSync: "true"` (default `"false"`): the done state appends
 `feature sync deferred to batch integration` to the task report and skips the sync, so task
 branches never touch feature files or `docs/features/INDEX.md`. After the last integration, on the
 base ref, the orchestrator runs `spur feature sync <f> --json` (service-level suppression) plus `spur feature refresh --feature <f>`
@@ -103,7 +103,7 @@ inline runs keep the default `"false"` and are unchanged. Any rebase conflict
 path or any other — is an R4 `integration-conflict`; there is no path-based exception.
 
 **Deferred gate (`--defer-gate`, task 1111 R3/R4).** The opt-in flag adds
-`deferQualityGate: "true"` to the same per-task `--vars`, so each task's `test` hop runs the light
+`deferQualityGate: "true"` to the same per-task `--vars`, so each task's `gate` state runs the light
 tier and writes `DEFERRED` instead of a full-gate `PASS` (see
 [flag-glossary](flag-glossary.md#flag-defer-gate)). The orchestrator then runs the project
 `qualityGateCmd` **once** on the integrated `BASE_REF` **before** the deferred feature sync:

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

@@ -10,15 +10,17 @@ see_also:
 
 ```
 pick task (spur task list --json)
-  → interactive omit/inline: host driver reads task-pipeline.yaml and walks it in-session
+  → interactive omit/inline: spur workflow run task-pipeline.yaml with executor=host
   → explicit/headless executor: spur workflow run task-pipeline.yaml
   → on HITL pause: surface to operator → resume the selected driver
 ```
 
-The execution half runs a single task through the `task-pipeline.yaml` FSM. In an interactive
-omit/inline invocation, the skill's host driver interprets that YAML directly. Explicit executors
-and headless invocations use the workflow engine. Both surfaces preserve the same actions, guards,
-artifacts, HITL gates, and terminal states.
+The execution half runs a single task through the `task-pipeline.yaml` FSM, always on the workflow
+engine. In an interactive omit/inline invocation the engine runs with `executor=host`: it executes
+every deterministic action (shell, `command.gate`, `decide`) and every guard itself, and hands each
+model stage back to this session as a work item. Explicit executors and headless invocations run the
+model stages as subprocesses. Both surfaces share the same actions, guards, artifacts, decision
+rows, HITL gates and terminal states.
 
 > **Single-task vs batch.** This file covers the **single-task** execution half — one task through
 > `task-pipeline.yaml`. For **batch** execution (a set of tasks in dependency-correct order), see
@@ -32,11 +34,11 @@ This file owns **how operations sequence** in the pipeline. What each operation
 
 > **`/sp:dev-run` drives the pipeline — it is NEVER a pipeline step.** The command
 > `/sp:dev-run <wbs>` means "run this whole pipeline" (default `--mode full`). The pipeline's
-> internal stages call `/sp:dev-run --mode implement`, shell quality gate + optional
-> `/sp:dev-fixall`, `/sp:dev-review`, `/sp:dev-verify` — never `/sp:dev-run` in full mode.
+> internal stages call `/sp:dev-run --mode implement`, the typed quality gate + optional
+> `/sp:dev-fixall`, and `/sp:dev-review` — never `/sp:dev-run` in full mode.
 > Calling `/sp:dev-run --mode full` from inside the `implement` step would recurse into another
 > full pipeline run. The `implement` step is the **implement operation** (dev-operations.md §4);
-> the verify step is `sp:code-verification`.
+> requirement/AC certification happens inside `review` (D65 merged the former `verify` stage).
 
 ## The pipeline's internal stages
 
@@ -45,10 +47,11 @@ one thing and yields, so the **pipeline (not the agent) owns the loop**.
 
 | Stage | Operation | Defined in |
 | ------- | ----------- | ------------ |
-| `implement` | `/sp:dev-run --mode implement <wbs>` — write the code that satisfies the task; author `## Solution`. | [dev-operations.md §4 run](dev-operations.md) → `sp:code-implementation` |
-| `test` → (`test-fix` ↔ `test-recheck`) → `review` \| `failed` | **Project quality gate** (not `/sp:dev-unit`). Soft shell probe of `${vars.qualityGateCmd}` (default `spur self exec check`) — green path pays **one** full gate run. On FAIL: bounded `/sp:dev-fixall` loop (`qualityGateMaxFixAttempts`, default 2) with soft recheck; exhausted attempts route to pipeline `failed`. `/sp:dev-unit` remains **coverage gap-fill** (router C3/C5 / standalone). | [dev-operations.md §10 fixall](dev-operations.md); unit op still §1 |
-| `review` | `/sp:dev-review --tasks <wbs>` — SECUA-framework review of the diff. | [dev-operations.md §2 review](dev-operations.md) |
-| `verify` | `sp:code-verification` — requirements traceability + verdict. | [dev-operations.md §3 verify](dev-operations.md) |
+| `implement` | `/sp:dev-run --mode implement <wbs>` — write the code that satisfies the task; author `## Solution`. May pause through `escalate` (operator question). | [dev-operations.md §4 run](dev-operations.md) → `sp:code-implementation` |
+| `gate` | **Typed quality gate** (not `/sp:dev-unit`): `spur task gate <wbs> run\|recheck` over `${vars.qualityGateCmd}` (default `spur self exec check`) under the host-wide lock, with tree-hash receipt reuse. The first visit runs `run`; every visit after a remediation runs `recheck`. Also resolves the review lane (`task-triage`) and classifies a red gate (`failure-class`). | `spur task gate` ([tasks reference](../../spur-cli/references/tasks/verbs.md)) |
+| `remediate` | `/sp:dev-fixall "${vars.qualityGateCmd}" --gate-log … --findings …` — the bounded repair hop for a red gate **or** a fixable non-PASS review; re-enters `gate`. One shared counter (`qualityGateMaxFixAttempts`, default 2) bounds both lanes. `/sp:dev-unit` stays coverage gap-fill (router C3/C5 / standalone). | [dev-operations.md §10 fixall](dev-operations.md) |
+| `review` | `/sp:dev-review --tasks <wbs> --auto --focus <functional\|all>` — SECUA + requirement/AC traceability; `spur task verdict --from-answer` certifies the answer, `review-failure-class` classifies a non-PASS, then the approval decision point answers. | [dev-operations.md §2 review](dev-operations.md) |
+| `done` | Deterministic close: `spur task record` writes `## Testing` from the verdict, then `spur task update <wbs> done --no-lifecycle` runs the completion check. | [dev-operations.md §3 verify](dev-operations.md) (standalone re-certification) |
 
 Interactive omit/`inline` executes these model stages in the host session through the engine loop:
 the engine owns every guard and transition, the host performs each returned work item and records
@@ -144,7 +147,7 @@ Synchronous invocation (`--json` without `--async`) is acceptable **only** for s
 On the subprocess path, when `--agent <value>` is set (passed through from the thin wrapper), merge it into the vars as
 **both** `agent` and `implementAgent` (task 0483 R2):
 `--vars '{"wbs":"<wbs>","agent":"<value>","implementAgent":"<value>"}'`. The pipeline YAML reads
-`${vars.agent}` for review/verify/test-fix and `${vars.implementAgent}` for implement — setting
+`${vars.agent}` for remediate/review and `${vars.implementAgent}` for implement — setting
 both keys ensures the pinned executor reaches every hop. The full value-semantics contract (one
 rule, value table, objective triggers, and headless `inline` substitution (tier resolution + one warning) per ADR-087)
 lives in [cross-cutting.md](cross-cutting.md#inline-default-execution-surface) — the SSOT.
@@ -161,34 +164,39 @@ pipeline (bug-742).
 The pipeline (`kind: state-machine`) runs the work loop:
 
 ```
-precheck → implement → test [→ test-fix → test-recheck] → review → approve(HITL) → verify → record → done
+precheck → implement[⇄ escalate] → gate[⇄ remediate] → review → done | failed
 ```
 
-Two branches reach the bounded repair hop, not one (session finding after 1088):
+Two branches reach the bounded `remediate` hop, and each is routed by a recorded decision row, not
+by this session's judgment:
 
-- `test`/`test-recheck` FAIL → `test-fail-triage` (0943's failure-class router) → `test-fix`;
-- `review` without a `Verdict: PASS` in its answer → `review-fail-triage` (the review-side twin) →
-  `test-fix`, bounded by the SAME `qualityGateMaxFixAttempts` counter. A FAIL review therefore has
-  an on-graph, bounded path to remediation instead of dead-ending the run, and the fix re-enters
-  quality → review → verify on a freshly captured proof digest.
+- a red `gate` → `failure-class` (`fix` → `remediate`, `stop` → `failed`);
+- a review that did not certify PASS → `review-failure-class` (`fix` → `remediate`, `stop` →
+  `failed`), bounded by the SAME `qualityGateMaxFixAttempts` counter. The repair re-enters
+  `gate` (recheck) → `review` on the remediated tree.
+
+Every decision point, its fallback and its consumer are listed in
+[decision-points.md](decision-points.md); read the rows it names instead of re-judging them.
 
 The completion gate reads deterministic evidence only: the review stage's **verdict artifact** (`.spur/run/<wbs>-verdict.json`, derived by `spur task verdict --from-answer`) and the **tree-hash gate receipt** (`.spur/run/<wbs>-check-receipt.json`, reused while the tree is unchanged). The ADR-071 proof chain this paragraph used to describe — proof digests, `verify → record`, review-inside-the-bracket — was deleted by the D65 pipeline rewrite; `record` now runs inside `done`'s onEnter and `verify` merged into `review`. Two grades are read, and only as cross-checks against the answer's own rows: the review answer states one `Confidence: HIGH|MEDIUM|LOW` line (ADR-141) and the review gate recomputes it from the finding dispositions, rejecting a disagreement. Nothing grades the *verifier's* opinion: an open P1–P3 finding blocks `done` on its own, and what protects a hand-driven `task update <wbs> done` is unchanged — the gate must show a PASS receipt for this tree and a recorded review artifact.
 
 Agentic steps use the pure slash inputs declared by each YAML `agent.run` action (ADR-043). The
 workflow engine dispatches them; the interactive driver invokes their backing skills in-session.
-The `test` hop is primarily
-**deterministic shell** (quality gate); only the optional `test-fix` hop is agentic
+The `gate` state is
+**deterministic** (quality gate plus decision points); only the optional `remediate` hop is agentic
 (`/sp:dev-fixall`). The skill monitors the run:
 
-- **On HITL pause** (`approve` state): surface the review output to the operator. On the subprocess
-  path use `spur workflow continue <run-id> --yes`; on the inline path retain the current state and
-  resume the host driver with the operator's answer.
+- **On HITL pause** (`escalate`, or the approval decision point inside `review`): surface the
+  question, or the review answer and verdict, to the operator. Resume with `spur workflow continue
+  <run-id> --answer-text <answer>` (or `--yes` for the approval). The approval answer lands in
+  `.spur/run/<wbs>-approval.status`; a `no`/`cancel` ends the run `failed` with terminal reason
+  `cancelled`, a recorded denial rather than a check failure.
 - **On guard failure** (`precheck`): the task's check findings block progress — fix the
   task first.
-- **On completion** (`done`): the pipeline's `record` step has already written the verdict
+- **On completion** (`done`): the `done` state's onEnter has already written the verdict
   transcript into the task's `## Testing` via `spur task record <wbs>` (matrix-compliant tables;
   `## Review` was authored by the review step and is only backfilled bare, never overwritten —
-  F92 0593 R1; never transitions to `done` — the gate stays in the workflow).
+  F92 0593 R1) and moved the task to `done` through the verb's own completion check.
 
 ## `--next` chain — advance to the next step
 
@@ -400,6 +408,10 @@ After a completed task, decide next action:
 
 ## Skipping HITL
 
-Passing `--vars '{"profile":"auto"}'` to `spur workflow run` (a var choice, not a YAML fork) skips
-the `approve` HITL gate — use for low-risk, well-understood tasks where operator review adds no value.
+Passing `--vars '{"profile":"auto"}'` to `spur workflow run` (a var choice, not a YAML fork) makes the
+approval decision point answer itself instead of prompting: its evidence binding answers from the
+recorded review evidence, through the `gate-evidence` decision when `workflows.hitlDecisionMaker`
+is on. It is not a bypass — an auto run still ends `failed`/`cancelled` when the maker answers
+`no`; a deferred answer (switch off, no reachable maker, or insufficient evidence) is not a denial. Use it for low-risk,
+well-understood tasks where operator review adds no value.
 (Combine with `wbs` in one object: `--vars '{"wbs":"0042","profile":"auto"}'`.)

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

@@ -118,6 +118,39 @@ WT_PATH="$(cd "../<worktree-dir>" && pwd)"   # hoisted: needed by WT-4a AND WT-4
 # task's creation), so a manual DB edit is never required:
 spur workflow persist-out --from "$WT_PATH" "${TASK_FILE_ARGS[@]}" \
   || { echo "halt: worktree run-record persist-out failed - worktree retained (WT-5)" >&2; write_marker retained; exit 1; }
+
+**Two refusals this step raises, and how to clear each without touching foreign evidence.**
+
+1. **`durable evidence conflicts: <name>`** — the worktree owns a receipt (`*-feature-verification.json`)
+   whose canonical target already holds *different* bytes. The conflict policy is fail-closed on
+   purpose: overwriting would destroy the invoking tree's copy. When the worktree receipt is the
+   newer, authoritative one (e.g. the feature transition this batch performed), archive the
+   superseded copy out of the canonical path and re-run — never delete it, and never copy the
+   worktree file in with `cp`:
+
+   ```bash
+   mkdir -p .spur/memory/evidence/superseded
+   mv ".spur/memory/evidence/<name>" ".spur/memory/evidence/superseded/<name>.<iso-timestamp>.json"
+   # then re-run the persist-out command above; the newer receipt lands at the canonical path
+   ```
+
+   When the *invoking* copy is the newer one, do nothing: `persist-check` reports it as foreign and
+   divergent, which is not a blocker.
+2. **`persist-check … BLOCKED n unforwarded durable verdict/receipt`** — the worktree holds
+   `*-verdict.json` files for tasks this batch did not run, because **WT-2 stages the invoking tree's
+   evidence into the worktree before the first task**. Forwarding them back (`--task-file`) is wrong
+   when the invoking tree's copies are newer: persist-out then refuses with `cited run evidence …
+   diverges`, and it would write stale bytes over fresh ones. Compare mtimes and delete the staged
+   worktree copies, then re-run `persist-check` with only this batch's `--task-file` arguments:
+
+   ```bash
+   for w in <staged-wbs>; do
+     [ .spur/run/$w-verdict.json -nt "$WT_PATH/.spur/run/$w-verdict.json" ] \
+       && rm -f "$WT_PATH/.spur/run/$w-verdict.json"
+   done
+   ```
+
+   Both steps are reads plus a delete of a *copy* whose source still holds it — no evidence is lost.
 #
 # 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.
@@ -361,8 +394,7 @@ skipped persist-out (or the pre-removal assertion fired too late), verdicts rema
 from the task records — `spur task show <wbs> --json` carries the recorded verdict and its
 proof block, so a lost `<wbs>-verdict.json` is regenerated by re-recording or copying from
 the task store. Feature run/latest receipts are re-runnable, not recovered: rerun the
-feature-verification workflow in the invoking tree —
-`spur workflow run feature-verification.yaml --vars '{"featureId":"<id>"}'` — which rewrites
+feature-verification pass in the invoking tree — `spur feature verify <id>` — which rewrites
 the receipt files it owns. Divergent files are never auto-overwritten; reconcile by hand.
 
 ```

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

@@ -208,10 +208,10 @@ the worktree directory before launching the loop.
 #### Evidence staging before the first task (create and reuse mode)
 
 `.spur/memory/evidence/` and `.spur/run/` are **untracked per-tree** planes, so a fresh worktree
-starts with neither while the invoking tree holds every earlier task's verdict. Both
-`preflightFeature` (`spur task wrapup resolve` → `spur feature check --strict --as done`
-with cwd = the worktree) and `runMetrics` resolve verdict artifacts relative to the tree they run
-in, so without this step an already-`done` linked task reads as missing evidence
+starts with neither while the invoking tree holds every earlier task's verdict. Feature completion
+checks (`spur feature check --strict --as done`) and wrap-up metrics resolve verdict artifacts relative
+to the tree they run in; wrap-up task resolution itself checks task identity and terminal status only.
+Without this step an already-`done` linked task reads as missing evidence
 (`L4.evidence-not-recoverable`, `L4.scenario-unverified`) and its metrics row degrades to
 `UNKNOWN`.
 

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

@@ -151,7 +151,7 @@ halt-on-first-failure. Never silently retried; the failure is still reported.
 **Applies to:** `/sp-dev-runall --mode parallel`, and `--mode auto` when it resolves to parallel.
 **Default:** off — every task pipeline runs its own FULL project gate inside its worktree.
 
-With `--defer-gate`, each task's `test` / `test-recheck` hop runs the **light tier** (changed-scope
+With `--defer-gate`, each task's `gate` state (every visit) runs the **light tier** (changed-scope
 format, per-workspace typecheck, related tests) and writes `DEFERRED` — never `PASS` — to
 `.spur/run/<wbs>-test-gate.status`. The orchestrator then owes **one integrated full gate** on the
 base ref over the merged slices, **before** the deferred feature sync; on FAIL the batch verdict is
@@ -164,8 +164,8 @@ Two properties are load-bearing and are asserted structurally:
   fails inside its own worktree instead of at the end of the batch (the reason ADR-124 rejected an
   unconditional single end-of-run gate).
 - **The full tier is still the only `PASS` writer.** Only the integrated run can claim a green
-  project gate; the per-task token is `DEFERRED`, and the `test → triage` /
-  `test-recheck → triage` guards accept it only while `deferQualityGate = "true"`.
+  project gate; the per-task token is `DEFERRED`, and the deferred `gate → review`
+  guard accepts it only while `deferQualityGate = "true"`.
 
 `--defer-gate` with `--mode sequential` (or omitted `--mode`) is rejected — the flag exists to move
 one full gate from N worktrees to the one place the integrated tree exists. Under `--mode auto` it

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

@@ -98,9 +98,10 @@ Entered before `task-pipeline.yaml` `review` state dispatches `sp:code-verificat
 
 ## verify gate
 
-Entered before `task-pipeline.yaml` `verify` state produces a task verdict.
+Entered before the `task-pipeline.yaml` `review` state certifies a task verdict (D65 merged the
+former `verify` state into `review`; standalone `/sp:dev-verify` applies the same list).
 
-- [ ] The verify answer file (`.spur/run/<wbs>-verify-answer.txt`) is lint-clean before
+- [ ] The answer file (`.spur/run/<runId>-review-answer.txt` in the pipeline) is lint-clean before
       verdict derivation: `spur task verdict <wbs> --from-answer …` (0726 R3) lints the
       file first and rejects missing/duplicate/unknown R IDs, AC identities that are not an
       exact task checklist label or linked-feature scenario title, invalid status/evidence-type

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

@@ -80,9 +80,18 @@ Avoid: *prompt* (reserved for LLM input text), *interrupt* (implies an exception
 pause point).
 
 **DecisionMaker** — optional provider-backed responder for executed `hitl.confirm`/`hitl.select`
-actions (ADR-123), enabled via `workflows.hitlDecisionMaker: true` and `TYPESAFE_API_KEY`.
-Evidence answers clear the answer variable and record `statusVar: accepted/deferred`; unresolved
-cases defer or delegate to the human. Offline readiness: `spur self status`.
+actions (ADR-123), enabled via `workflows.hitlDecisionMaker: true`. Evidence-mode confirm gates
+answer through the catalog decision `gate-evidence`, so the effective maker (and its credentials)
+comes from `decisions.*` config. Evidence answers clear the answer variable and record
+`statusVar: accepted/deferred`; unresolved cases defer or delegate to the human. Readiness:
+`spur decision status --probe`.
+
+**decision point** — a recorded, closed-vocabulary judgment inside a workflow: a `decide` action
+(or an evidence-mode HITL gate) that names a catalog decision id and writes a schemaVersion-1
+`.decision` row whose `value` the next guard reads. It always has a deterministic fallback, so it
+works with no model. Inventory: [decision-points.md](decision-points.md).
+Avoid: *decision brief* (the operator-facing HITL summary format in
+[decision-brief.md](decision-brief.md) — prose for a human, not a catalog answer).
 
 **WBS** (work-breakdown-structure ID) — the four-digit task identifier (e.g. `0187`) that
 names a task file and its position in the corpus. WBS IDs are assigned once and never reused.

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

@@ -1,6 +1,6 @@
 ---
 name: planning-workflow
-description: "Extracted section: the planning half — intake → feature create → AC generation → feature check gate → decomposition → batch-create gate → refine. The full step-by-step procedure for turning a vague description into a validated, decomposed feature."
+description: "Extracted section: the planning half — intake → feature create → AC generation → decomposition → batch-create → refine. The full step-by-step procedure for turning a vague description into a validated, decomposed feature."
 see_also:
   - spur-dev
   - decomposition
@@ -13,18 +13,19 @@ see_also:
 vague description
   → intake (clarify scope, constraints — prompt work)
   → spur feature create … ; AC authored/generated (spur agent run, bdd templates)
-  → GATE: spur feature check   (BDD validator; loop until clean)
+  → ac-generate runs `spur feature check`   (BDD validator; loop until clean)
   → decomposition (prompt work) → task-batch JSON
-  → GATE: task-batch.schema.json + spur task batch-create (atomic: all-or-nothing)
+  → batch-create-run runs `task-batch.schema.json` + `spur task batch-create` (atomic: all-or-nothing)
   → design doc (conditional: seam heuristic under default; skip with --skip-design) → docs/design/<slug>.md + 04 index
 ```
 
 
 The planning half transforms a description into a validated feature file with acceptance
-criteria, then decomposes it into a batch of tasks. Two CLI gates make LLM regressions
-unable to corrupt the corpus: `spur feature check` validates the AC, and
+criteria, then decomposes it into a batch of tasks. Two deterministic validation steps make LLM
+regressions unable to corrupt the corpus: `spur feature check` validates the AC, and
 `task-batch.schema.json` validates the decomposition shape before `spur task batch-create`
-writes anything.
+writes anything. Both run inside the pipeline (`ac-generate`, `batch-create-run`) and route on
+their recorded result — neither is an operator gate.
 
 ## Step 1: Intake