@gobing-ai/spur 0.4.15 → 0.4.17

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

@@ -359,6 +359,19 @@ spur task path 0040 --json
   basename-WBS fallback. Exit `1` when no task owns the path.
 - `path <wbs>` is the inverse — absolute task file path for a WBS.
 
+## Lifecycle playbook
+
+| Stage | How | Gate / evidence |
+| --- | --- | --- |
+| **Create** | `spur task create <title> --feature <id>` ([Creating tasks](#creating-tasks)), then fill sections ([tasks/section-editing.md](tasks/section-editing.md)) | `spur task check <wbs> --json` exits 0 |
+| **Evaluate** | Readiness matrix ([check --json](#the-readiness-matrix--check---json)); `--precheck` before a pipeline run | `sp:spur-doctor` report cites the check rows |
+| **Triage** | Structural finding → `check --fix`; L3 refusal → [tasks/l3-guard-cheatsheet.md](tasks/l3-guard-cheatsheet.md); batch admission → `spur task preflight <wbs> --json` | Re-run `check` until clean |
+| **Enhance** | Replace one section from a temp file; batch refinement through `/sp:dev-refineall --feature <id> --auto` | Same `check` passes; AC still traces to the feature |
+
+- One deliverable per task; split rather than stack ACs from two features.
+- Every AC is observable and verifiable by a named command or file, never by self-report.
+- Status moves only through `update`/`record`; never hand-edit frontmatter.
+
 ## What this skill is NOT
 
 - **Not the pipeline.** Driving a task through `task-pipeline.yaml`, HITL surfacing, and

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

@@ -138,7 +138,7 @@ Spur's host additionally registers (`registerSpurBuiltins`, `packages/app/src/wo
 
 | Kind | Capability |
 | ---- | ---------- |
-| Action | `agent.run` (model call via `spur agent run`; `executor: 'fleet'` dispatches into the agent fleet), `decide` (inline `id`/`method`/`question`/`choices`/`default`/`evidence` → outcome written to `resultFile`; catalog-id references are pending task 1094 — use `spur decision run` for catalog decisions), `command.gate`, `rule.check`, `doctor.probe`, `proof.fingerprint`, `run.artifact`, `file.exists`, `file.read`, `file.read.into-var`, `http.request`, `hitl.confirm`, `hitl.select`, `hitl.input`, `shell` (streaming) |
+| Action | `agent.run` (model call via `spur agent run`; `executor: 'fleet'` dispatches into the agent fleet), `decide` (catalog reference `{id, decision, params?, evidence? \| instructions?, resultFile}` → a schemaVersion-1 row; gated by `workflows.decideDecisionMaker`, fallback row when off; the inline `question`/`method`/`default` form is deprecated, and a shell `spur decision run` bypasses the switch — see [decision lifecycle](../decision/lifecycle.md)), `command.gate`, `rule.check`, `doctor.probe`, `proof.fingerprint`, `run.artifact`, `file.exists`, `file.read`, `file.read.into-var`, `http.request`, `hitl.confirm`, `hitl.select`, `hitl.input`, `shell` (streaming) |
 | Guard | `shell` (env-aware), `contract-violation` |
 
 Order matters for both guards and conditions: **the first that passes wins.** Put the discriminating

package/plugins/sp/skills/spur-cli/references/workflows/workflow-fit-and-tuning.md

@@ -53,8 +53,9 @@ when the run count justifies it. One or zero → **descriptive procedure**; say
 | "Retry until the gate passes", "loop until clean" | workflow — bounded loop is the engine's job |
 | "Pause for approval, continue later / in another session" | workflow — HITL resume needs a run record |
 | "Every night", "for each task in the batch", unattended | workflow — replay + record |
-| "Then check whether it looks right and decide" | prose — the predicate is judgment, not an exit code |
-| "It depends what the diff says" | prose — the branch has no machine-checkable condition |
+| "Then check whether it looks right and decide" | prose — unless the answer is a closed set with a safe default; then a catalog `decide` step |
+| "It depends what the diff says" | prose — unless a deterministic floor routes first and a catalog decision refines it (task-triage pattern) |
+| "Classify the failure, then fix or stop" | workflow — a `decide` row the guard reads ([decision points](../../../spur-dev/references/decision-points.md)) |
 | Runs once, then the situation has changed | prose — a checklist, not a definition |
 | One operator, in-session, watching each step | prose — the trace has no second reader |
 

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

@@ -422,6 +422,15 @@ a **pipeline** (validate → dry-run → read trace → refine). It also covers
 extending the engine with custom actions/guards. It does not execute the orchestrated *work* itself —
 the workflow's actions (`shell`, custom runners) do that; this skill builds and operates the workflow.
 
+## Lifecycle playbook
+
+| Stage | How | Gate / evidence |
+| --- | --- | --- |
+| **Create** | [Fit gate](#decide-it-is-a-workflow-at-all--before-the-mode), then the composer ladder (ephemeral → `.spur/workflows/` → shared); author per [workflows/authoring-workflows.md](workflows/authoring-workflows.md) | `spur workflow validate <file> --json` clean |
+| **Evaluate** | Dry-run, then a real run; `spur workflow profile <workflow> --json` and `cost` for measured spend | [Composition measures](#composition-measures-and-the-advisory-0615) within budget |
+| **Triage** | `spur workflow trace <run-id> --json` → the failing node; [workflows/operations.md](workflows/operations.md) for HITL/continue/cancel | Re-run reaches the node and passes |
+| **Enhance** | Tune from measured evidence ([workflows/workflow-fit-and-tuning.md](workflows/workflow-fit-and-tuning.md)); judgement steps adopt a catalog `decide` ([decision/lifecycle.md](decision/lifecycle.md) §3) | Before/after `profile` pair |
+
 ## Gotchas
 
 1. **`kind` is required for transition-flow, optional for state-machine.** A missing `kind` silently

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

@@ -1,6 +1,6 @@
 ---
 name: spur-composer
-description: "Select, compose and tune spur artifacts — tasks, features, rules, workflows, agent specs and project Board modules. Owns workflow catalog selection, the ephemeral→project→shared ladder, ADR-115 budgets, trace-driven rule tuning and applying accepted sp:spur-doctor proposals. Triggers: compose a workflow, tune a rule, add a Board module."
+description: "Select, compose and tune spur artifacts — tasks, features, rules, workflows, decisions, agent specs and project Board modules. Owns workflow catalog selection, the ephemeral→project→shared ladder, ADR-115 budgets, trace-driven rule tuning and applying accepted sp:spur-doctor proposals. Triggers: compose a workflow, tune a rule, add a Board module."
 license: Apache-2.0
 version: 1.0.0
 metadata:
@@ -49,6 +49,7 @@ its own output and never runs a recurring loop — evaluation is the doctor's jo
 | feature | Apply accepted rows through `spur feature update --section --from-file`; keep acceptance criteria in Gherkin | [../spur-cli/references/features.md](../spur-cli/references/features.md) |
 | rule | The trace-driven tuning loop (§ Rule tuning loop) | [../spur-cli/references/rules.md](../spur-cli/references/rules.md) · [fine-tuning](../spur-cli/references/rules/fine-tuning.md) |
 | workflow | Catalog selection, the composition ladder, and the ADR-115 budgets (§ below) | [../spur-cli/references/workflows.md](../spur-cli/references/workflows.md) · [operations](../spur-cli/references/workflows/operations.md) |
+| decision | Select an existing id, place new entries up the layer ladder, tune maker/criteria from reliability evidence, adopt in workflows by class (§ Decision composition) | [../spur-cli/references/decision.md](../spur-cli/references/decision.md) · [lifecycle](../spur-cli/references/decision/lifecycle.md) |
 | agent spec | Read through `spur agent list --specs`; fleet member specs are derived in memory from `agent.fleet` (never written to `.spur/agents/`) | [../spur-cli/references/agent.md](../spur-cli/references/agent.md) |
 | board module | Declare under `bootstrap.modules`, gated by the serve preflight (§ Board module composition) | [../spur-cli/references/serve.md](../spur-cli/references/serve.md) |
 
@@ -144,6 +145,24 @@ Start from trace evidence, never from a guess:
 5. `spur rule run` on the affected inputs (constitution T11 — affected inputs, not a corpus sweep).
 6. Trace again and compare. A tuning with no trace pair behind it is a preference.
 
+## Decision composition
+
+Same select → compose → tune shape, applied to the decision catalog
+([lifecycle](../spur-cli/references/decision/lifecycle.md)):
+
+1. **Classify first.** keep-deterministic, rescue-only, adopt or keep-human (lifecycle §1). Only
+   adopt and rescue-only become a catalog entry.
+2. **Select.** `spur decision list --json`; reuse an id whose criteria fit.
+3. **Compose up the ladder.** `.spur/decisions/<file>.yaml` (project) → `config/decisions/` (shared,
+   recorded operator consent + `build:bundle`). A project file shadows the shipped file of the same
+   basename whole.
+4. **Tune from evidence.** Labelled `spur decision run --maker <name>` fixtures, then
+   `spur decision status --reliability --json`; one lever per pass (lifecycle §6). The maker
+   override goes in operator config, never the shipped catalog.
+5. **Adopt in a workflow.** One catalog-reference `decide` step per change, validated with
+   `spur workflow validate` and `spur workflow run --dry-run`; the fallback must stay safe with
+   `workflows.decideDecisionMaker` off.
+
 ## Applying doctor proposals
 
 `sp:spur-doctor` ([../spur-doctor/SKILL.md](../spur-doctor/SKILL.md)) returns a proposal table;

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

@@ -1,10 +1,10 @@
 ---
 name: spur-dev
-description: 'The thin orchestration spine for the planning→execution lifecycle: intake, feature-check/batch-create gates, the execution pipeline (precheck→implement→test→review→verify→record→done), HITL gating. Dispatches competency skills; never inlines them. Triggers: "run the pipeline", "drive this task", "plan a feature end to end", "continue the pipeline run", or operating the full lifecycle.'
+description: 'The thin orchestration spine for the planning→execution lifecycle: intake, feature-check/batch-create gates, the execution pipeline (precheck→implement→gate⇄remediate→review→done), catalog decision points, HITL gating. Dispatches competency skills; never inlines them. Triggers: "run the pipeline", "drive this task", "plan a feature end to end", "continue the pipeline run", or operating the full lifecycle.'
 license: Apache-2.0
 metadata:
   author: spur
-  version: "1.1"
+  version: "1.2"
   platforms: "claude-code,codex,openclaw,opencode,antigravity"
   interactions:
     - pipeline
@@ -23,11 +23,9 @@ metadata:
   execution_steps:
     - precheck
     - implement
-    - test
+    - gate
+    - remediate
     - review
-    - approve
-    - verify
-    - record
     - done
   openclaw:
     emoji: "🔄"
@@ -80,7 +78,7 @@ Full procedure: **[references/planning-workflow.md](references/planning-workflow
 
 ```
 pick task (spur task list --json)
-  → interactive omit/inline: read task-pipeline.yaml → drive actions + guards in host session
+  → interactive omit/inline: spur workflow run … executor=host → perform each returned work item
   → explicit/headless executor: spur workflow run task-pipeline.yaml --vars '{"wbs":"<wbs>"}'
   → on HITL pause: surface to operator; resume the selected driver from the paused state
 ```
@@ -88,7 +86,7 @@ pick task (spur task list --json)
 The pipeline (`kind: state-machine`) runs the work loop:
 
 ```
-precheck → implement[→escalate(HITL)] → test → review → approve(HITL) → verify → record → done
+precheck → implement[⇄escalate(HITL)] → gate[⇄remediate] → review → done | failed
 ```
 
 **Escalation contract (0933).** The implement agent may pause on an operator question: it writes
@@ -97,6 +95,10 @@ run. Resume with `spur workflow continue --answer-text <answer>` — the guard a
 `.spur/run/<wbs>-escalation.md` and re-enters implement (transcript via `--escalation-file`).
 `maxEscalations` (default 2) bounds the loop; exhausted or empty answer → `failed`. Implement only.
 
+**Decision points.** Lane, failure class, review failure class and approval are recorded
+`spur decision` answers with deterministic fallbacks, read by the next guard. Report the row; never
+re-judge it: **[references/decision-points.md](references/decision-points.md)**.
+
 Full procedure: **[references/execution-workflow.md](references/execution-workflow.md)**.
 Host executor: `spur workflow run` with `executor=host` → work item → `spur workflow continue`.
 
@@ -112,9 +114,6 @@ Read this `SKILL.md` plus your mode's files below before the first dispatch; eve
 
 `--mode auto` reads as sequential-inline until § 2.4a resolves it.
 
-Byte budgets for these sums live in `plugins/sp/tests/bootstrap-budget.test.ts`
-(`BOOTSTRAP_BUDGETS_BYTES`, task 1128); the test fails the build when a mode's bootstrap grows.
-
 ## Step routing
 
 Each step delegates to a CLI verb and is documented in exactly one reference file. Read the
@@ -133,8 +132,9 @@ reference for the half you're operating; do not duplicate its content here.
 | Task selection             | execution | `spur task list`                                                                          | [execution-workflow.md](references/execution-workflow.md)                                                                               |
 | Pipeline run               | execution | `spur workflow run` / `spur workflow continue`                                            | [execution-workflow.md](references/execution-workflow.md)                                                                               |
 | Implement (dispatch)       | execution | `sp:code-implementation`                                                                  | competency skill — the spine dispatches, does not inline                                                                                |
-| Test (dispatch)            | execution | `sp:code-testing`                                                                         | competency skill — the spine dispatches, does not inline                                                                                |
-| Review / verify (dispatch) | execution | `sp:dev-review` → `sp:code-verification` + `sp:functional-review` + `sp:code-improvement` | competency skills — the spine dispatches, does not inline                                                                               |
+| Gate / remediate | execution | `spur task gate` + `sp:dev-fixall` | [execution-workflow.md](references/execution-workflow.md) |
+| Review (dispatch) | execution | `sp:dev-review` → `sp:code-verification` + `sp:functional-review` + `sp:code-improvement` | competency skills — the spine dispatches, does not inline |
+| Decision points | execution | `spur decision status` (+ `show`, `run`) | [decision-points.md](references/decision-points.md) |
 | Operation catalog          | execution | `sp:dev-*` operations                                                                     | [dev-operations.md](references/dev-operations.md) (spine dispatch table)                                                                |
 | Continue                   | execution | `spur feature update` / `refresh`                                                         | [execution-workflow.md](references/execution-workflow.md)                                                                               |
 | Batch run                  | execution | `sp:super-planner` + `spur workflow run`                                                  | [execution-batch.md](references/execution-batch.md)                                                                                     |
@@ -193,8 +193,8 @@ CLI does.
    you ship corrupted corpus.
 2. **One writer per evidence section (F92 0593 R1).** `## Solution` is authored by the
    implement step; `## Review` by the review coordinator (`/sp:dev-review`); `## Testing` by the
-   deterministic `record` step from the verdict artifact (`record` backfills `## Review` only when
-   bare — fallback-only, never an overwrite). During execution, do not hand-edit another stage's
+   deterministic `spur task record` close in `done` from the verdict artifact (it backfills
+   `## Review` only when bare — fallback-only, never an overwrite). During execution, do not hand-edit another stage's
    section.
 3. **Resolve task IDs through the CLI.** Read a known WBS with `spur task show <wbs> --json`; it
    returns metadata, full content, and `filePath` across configured task folders. Use `spur task
@@ -226,7 +226,7 @@ section adds per-file content summaries and items with no single step (glossary,
   five gates (feature-check, batch-create, precheck, review, verify).
 - [references/section-batching.md](references/section-batching.md) — the evidence-section
   **one-writer protocol** (F92 0593 R1/R2): implement owns `Solution`, the review coordinator owns
-  `Review`, deterministic `record` owns `Testing`; skills query `spur task sections` /
+  `Review`, the deterministic `spur task record` close owns `Testing`; skills query `spur task sections` /
   `spur task check` instead of static section tables.
 - [references/ac-style-guide.md](references/ac-style-guide.md) — BDD scenario authoring:
   R-numbering, the two AC tiers, scenario-title stability, Gherkin template usage.

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

@@ -131,8 +131,9 @@ surface instead of spawning a subprocess; a subprocess fallback happens only whe
 
 **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
-workflow run` and never redirect silently to `agent.default`. Interactive **omit** is
+inline` run the existing `task-pipeline.yaml` on the host executor — the engine loop above
+(`spur workflow run … executor=host` → work item → `spur workflow continue`), with no subprocess —
+and never redirect silently to `agent.default`. Interactive **omit** is
 **host-controlled and non-subprocess**, but no longer guarantees host-context execution for every
 model stage (task 0508): an eligible `agent.run` stage — pure-slash input, non-interactive state,
 native subagent with shared-worktree read/write/shell capability, and a task above the
@@ -181,14 +182,14 @@ spawned step resolves to `agent.default` (step 2) or the YAML literal (step 3).
 
 `task-pipeline.yaml` declares a separate `implementAgent` var. The `implement` state's `agent.run`
 step reads `${vars.implementAgent}` instead of `${vars.agent}`, so an operator can pin the
-implement hop to one executor while review/verify/test-fix hops keep the default agent:
+implement hop to one executor while the remediate and review hops keep the default agent:
 
 ```bash
 # Pin implement to a specific executor; other hops keep agent.default / YAML literal
 --vars '{"implementAgent":"omp-zai"}'
 ```
 
-All other `agent.run` steps (test-fix, review, verify) read `${vars.agent}`. `implementAgent`
+All other `agent.run` steps (remediate, review) read `${vars.agent}`. `implementAgent`
 applies **only** to the implement hop. **The `--agent` flag forwards into BOTH `agent` and
 `implementAgent`** at the execution-batch boundary (§3.2), so a pinned `--agent X` reaches every
 hop including implement. To pin ONLY implement to a different executor while other hops keep the

package/plugins/sp/skills/spur-dev/references/decision-points.md

@@ -0,0 +1,97 @@
+---
+name: decision-points
+description: "The lifecycle's catalog decision points: which workflow state asks which `spur decision` id, its fallback, the row it writes and the guard that reads it — plus the rules for consuming, diagnosing and adding one."
+see_also:
+  - spur-dev
+  - execution-workflow
+  - spur-cli
+  - spur-composer
+---
+
+# Decision points
+
+A **decision point** is a closed-vocabulary judgment the workflow asks through `spur decision`
+instead of through an agent's prose. It names a catalog id, carries a deterministic fallback, and
+writes a schemaVersion-1 row (`value`, `source: model|default`, `degraded`, `confidence`,
+`confidenceLevel`, `reason`) that the next guard or projection reads. The verb catalog, maker
+resolution and the authoring lifecycle live in `sp:spur-cli`
+([decision.md](../../spur-cli/references/decision.md),
+[decision/lifecycle.md](../../spur-cli/references/decision/lifecycle.md)); this file is the
+lifecycle's map of where each one sits.
+
+## Inventory
+
+| Workflow · state | Decision id | Values (fallback) | Row | Consumer |
+| --- | --- | --- | --- | --- |
+| task-pipeline · `gate` | `task-triage` | low · standard · high (`standard`) | `.spur/run/<wbs>-triage.decision` | lane projection → `<wbs>-mode.txt` → review focus. Runs only after the deterministic floor (caller `mode`, sensitive path, > 400 lines) has not already pinned the lane |
+| task-pipeline · `gate` | `failure-class` | fix · stop (`fix`) | `.spur/run/<wbs>-failure-class.decision` | red gate: `stop` → `failed`, `fix` → `remediate` (under the attempt cap) |
+| task-pipeline · `review` | `review-failure-class` | fix · stop (`fix`) | `.spur/run/<wbs>-review-failure-class.decision` | non-PASS review: `stop` → `failed`, `fix` → `remediate` (same cap) |
+| task-pipeline · `review` | `gate-evidence` (approval `hitl.confirm`) | yes · no · defer (`defer`) | `.spur/run/<wbs>-approval.status` (APPROVED · DENIED) | `done` requires APPROVED; DENIED → `failed` (`cancelled`) |
+| idea-pipeline · discovery | `idea-recommendation` | proceed · reshape · drop · unknown (`unknown`) | `.spur/run/<runId>-idea-recommendation.decision` | rescue only: consulted when the awk parse says `unknown`; only a `source: model` answer is projected |
+| idea-pipeline · discovery | `needs-design` | design · skip (`design`) | `.spur/run/<runId>-idea-needs-design.decision` | rescue only: used when the report's boolean is missing; anything but a model `skip` keeps `design` |
+| idea-pipeline · `idea-eval`, `design-approval` | `gate-evidence` | yes · no · defer (`defer`) | `__hitlAnswer` → `<runId>-idea-eval-answer.txt` etc. | a deferred answer is a denial there |
+| wrapup-pipeline · `branch-cleanup` | `gate-evidence` | yes · no · defer (`defer`) | `branchCleanupStatus` | consent record only; wrap-up performs no git operation |
+| history-anatomy · validate | `anatomy-validation-verdict` | PASS · FAIL (`FAIL`) | shell `spur decision run` (not a `decide` row) | rescue for an unparseable validation verdict; a deterministic FAIL is never overturned |
+
+`maker-liveness` is served only by `spur decision status --probe`. `spur decision list --json` is
+the live inventory; when it and this table disagree, the CLI wins and this table is stale.
+
+## Switches
+
+- **`workflows.decideDecisionMaker`** (default off) gates every `decide` action. Off, the action
+  makes no model call and writes the fallback row (`source: default`). The pipeline still routes:
+  a red gate is `fix` and goes to the bounded repair, the lane is `standard`.
+- **`workflows.hitlDecisionMaker`** (default off) gates the evidence-mode HITL gates. Off,
+  interactive gates ask the operator; under `profile=auto` the gate's answer is deferred, which
+  task-pipeline treats as no objection and idea-pipeline treats as a denial.
+- **`spur decision run` ignores both switches.** A workflow that shells out to it calls a model
+  even with the switches off. That is why the typed `decide` action is the preferred form.
+
+## Rules for the lifecycle
+
+1. **Read the row; never re-judge it.** When a run reports `failed`, `remediate` or a lane, the
+   reason is the recorded `.decision` row or the approval token. Quote its `value`, `source` and
+   `reason`. Do not overrule a `stop` by hand-driving `remediate`, and do not treat a `source:
+   default` row as a model verdict.
+2. **A fallback row is a real outcome.** `source: default` (switch off, `no-backend`, low
+   confidence, invalid answer) is what the run acted on. Report it as degraded, not as an error.
+3. **Outside a pipeline, ask the catalog.** For a question a catalog id already owns (is this
+   red gate fixable? which lane does this diff need?), run `spur decision show <id>` and then
+   `spur decision run <id> --param … --evidence … --json` instead of improvising an answer. Never
+   let a `spur decision run` answer substitute for a gate the workflow owns.
+4. **Recurring judgment → a decision point, not prose.** A judgment that has a closed set of
+   answers and a safe default, recurs across runs, and currently lives in an agent prompt or a
+   `case` over free text belongs in a catalog entry plus a `decide` step. Author it through the
+   decision lifecycle (decision/lifecycle.md) and `sp:spur-composer`. A new shared catalog id
+   needs recorded operator consent (composition ladder §7) and `build:bundle`.
+5. **Keep deterministic floors first.** A decision point rescues or refines a deterministic
+   check; it never replaces one. task-triage runs after the sensitive-path/size floor, and the
+   idea-pipeline decides run after the parse they rescue.
+
+## Reporting a run
+
+After a task-pipeline run settles, `/sp:dev-run`, `/sp:dev-runall` and `sp:super-planner` report
+its decision points under the execution summary, one line per row, plus the approval token:
+
+```bash
+for f in .spur/run/<wbs>-{triage,failure-class,review-failure-class}.decision; do
+  [ -f "$f" ] && jq -r --arg f "${f##*/}" '"\($f): \(.value) — \(.source // (if .degraded then "default" else "model" end)) \(.backend // "-") \(.reason)"' "$f"
+done
+printf 'approval: %s\n' "$(cat .spur/run/<wbs>-approval.status 2>/dev/null || echo none)"
+```
+
+Rows outlive their run: a row's presence does not prove this run reached that state (the run's
+trace does). Rows written before `source` existed carry only `degraded`; the fallback above reads it.
+
+## Diagnosis
+
+| Question | Evidence |
+| --- | --- |
+| Why did this run take that route? | The row file in the table above; `spur workflow trace <run-id> --json` |
+| Is a maker serving at all? | `spur decision status --probe` |
+| How reliable is a decision in practice? | `spur decision status --reliability [--since <date>] --json` — per decision × maker: samples, acceptedRate, fallbacks by reason, median confidence, p50/p95 latency |
+| Which runs asked it? | Board → Decisions tab (`decision_logs`) |
+| Is the catalog healthy? | `spur decision status --json` → `loadErrors`, `makers[]` |
+
+A decision whose rows are almost all `source: default` while its switch is on has a maker
+problem, not a workflow problem. Hand it to `sp:spur-doctor`, which owns the proposal.

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.
@@ -156,10 +156,10 @@ must not be changed without updating the backing skill.
 ### 4. run
 
 - **Purpose:** Run a task through the execution pipeline (full) or execute a single pipeline step (implement).
-- **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.
+- **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 runs `task-pipeline.yaml` on the host executor (`spur workflow run … executor=host` → work item → `spur workflow continue`) — 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.
 
@@ -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

@@ -462,11 +462,11 @@ 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 invokes feature status sync. When a feature is
+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.
 
-`task-pipeline.yaml`'s `record` step invokes `spur feature sync <feature-id> --json` directly —
+`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`
@@ -482,7 +482,7 @@ retry suppression lives inside the `FeatureService.syncFeature` implementation:
    never reads or writes the state.
 
 **Batch driver contract:** the orchestrator does **nothing extra** — the suppression lives inside
-the pipeline's `record` 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.
@@ -530,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:

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: