@gobing-ai/spur 0.4.15 → 0.4.16

package/plugins/sp/commands/dev-fixall.md

@@ -27,12 +27,17 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 
 ## Implementation
 
-Follow the inline procedure in [dev-operations.md](../skills/spur-dev/references/dev-operations.md#10-fixall) (fixall). Pipeline signal: when `--gate-log` is set (the `test-fix` hop), run no full gate — the `test-recheck` state immediately after is the deciding run (R4, task 0483).
+Follow the inline procedure in [dev-operations.md](../skills/spur-dev/references/dev-operations.md#10-fixall) (fixall). Pipeline signal: when `--gate-log` is set (the `remediate` hop), run no full gate — the `gate` state's recheck immediately after is the deciding run (R4, task 0483).
 
-When dispatched from the pipeline's test-fix stage (F96, task 0950), the gate log carries a
+When dispatched from the pipeline's `remediate` hop (F96, task 0950), the gate log carries a
 `residual artifact` block (`<wbs>-residuals.json`) and the findings file already
 contains the merged residual anchors: treat those items as fix targets, in order,
 alongside gate anchors. The fixer may write `.spur/run/<wbs>-residual-deferrals.json`
 — one `{id, reason}` entry per item — but only for P3 findings or diff markers it
 cannot fix inside the task; the done stage settles deferrals into follow-up tasks.
 
+The `remediate` hop is entered only after a `fix` decision (`failure-class` on a red gate,
+`review-failure-class` on a non-PASS review). A `stop` decision ends the run before this command
+runs, so do not invoke it by hand to overrule a `stop`
+([decision points](../skills/spur-dev/references/decision-points.md)).
+

package/plugins/sp/commands/dev-idea.md

@@ -44,7 +44,7 @@ trace records the answering source. `--auto` takes the recommended option at eac
 
 | Gate | Pauses when | Recommendation comes from | `--auto` takes |
 | --- | --- | --- | --- |
-| idea-eval | after discovery | eval report `## Recommendation` (`proceed` / `reshape` / `drop`) | `proceed`/`reshape` → continue; `drop` → cancel; missing → still asks |
+| idea-eval | after discovery | eval report `## Recommendation` (`proceed` / `reshape` / `drop`); when unparseable, a model answer from the `idea-recommendation` decision | `proceed`/`reshape` → continue; `drop` → cancel; neither → the gate asks, and under `--auto` its `gate-evidence` decision answers (a deferred answer denies) |
 | design-approval | after system-design (skipped by `--skip-design`) | recorded design check | PASS → approve; FAIL → still asks |
 
 The AC check and the batch create are deterministic pipeline steps, not gates: `ac-generate`
@@ -52,6 +52,11 @@ runs `spur feature check` and routes on the recorded result (a FAIL retries the
 and `batch-create-run` runs `spur task batch-create` and routes on its own recorded result.
 Neither ever pauses, under any profile.
 
+The rescue decisions and the gate answers are catalog decision points; their rows and switches
+are in [decision points](../skills/spur-dev/references/decision-points.md). With both switches off
+(the default) no model is called and a `--auto` run with no parseable recommendation stops at
+idea-eval as a denial rather than creating a feature.
+
 Flag → vars: `--auto` sets `profile=auto`, `idea_approved=true`, `design_approved=true`;
 `--skip-design` sets `design=skip`.
 

package/plugins/sp/commands/dev-run.md

@@ -50,6 +50,9 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 - Implement step only (`--mode implement`): `Skill(skill="sp:code-implementation", args="$ARGUMENTS")`
 - After a full-mode run settles (done, failed or paused), print the
   [execution summary](../skills/spur-dev/references/dev-operations.md#execution-summary) unless `--no-summary`.
+- Then report the run's decision points (triage lane, failure classes, approval) from their rows
+  ([reporting a run](../skills/spur-dev/references/decision-points.md#reporting-a-run)). A `failed` or `remediate` route is explained by the row
+  that chose it; quote its value, source and reason, never a fresh judgment.
 
 **Flags:**
 

package/plugins/sp/commands/dev-runall.md

@@ -26,7 +26,7 @@ Wraps the **sp:spur-dev** skill.
 | `--worktree` `[<name>]` | Run the batch in an isolated git worktree; FF-merge on success, retain on failure. Bare `--worktree` creates a fresh tree; `--worktree <name>` adopts an existing worktree by name/path/branch. | off |
 | `--no-summary` | Skip the measured execution summary (one row per task run: time, wait, tool calls, total / non-cached tokens) printed after the batch report. | off (summary printed) |
 | `--concurrency` `<n>` | Parallel-mode worker bound: at most `<n>` task pipelines run at once (task 0931); a dependent starts only after its in-set dependencies are integrated onto the base ref. No-op in sequential mode (ignored). | 2 |
-| `--defer-gate` | Opt-in parallel-batch gate policy (task 1111): each task's `test` hop runs the light tier and writes `DEFERRED`; the batch runs one integrated full gate on the base ref before the feature sync. Requires `--mode parallel`, or `--mode auto` resolved to parallel (dropped with a note otherwise); default off. | off |
+| `--defer-gate` | Opt-in parallel-batch gate policy (task 1111): each task's `gate` state runs the light tier and writes `DEFERRED`; the batch runs one integrated full gate on the base ref before the feature sync. Requires `--mode parallel`, or `--mode auto` resolved to parallel (dropped with a note otherwise); default off. | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 
@@ -82,8 +82,8 @@ FF-merge on success. This is expected, not a bug.
 
 **`--next` (batch-once wrap).** `--next`
 is chain-to-completion with propagation. On `dev-runall`, each task in the batch runs its
-`task-pipeline.yaml` to terminal status (the pipeline already drives precheck → implement → test →
-review → approve → verify → record → done); when the batch is complete, the wrap hop runs **once
+`task-pipeline.yaml` to terminal status (the pipeline already drives precheck → implement → gate ⇄ remediate →
+review → done); when the batch is complete, the wrap hop runs **once
 for the batch** — mirroring the batch-once shippable gate `dev-verifyall` uses — rather than once
 per task. Without `--next`, `--wrap` is wrap-without-chaining (the single batch wraps without
 advancing the feature lifecycle). **was: `--next` deliberately omitted; the old no-`--next` rationale argued against the old per-task-transition meaning and does not carry.**
@@ -111,3 +111,6 @@ full distinction.
 - Explicit executor (any mode, including `auto`) or parallel mode: `Skill(skill="sp:spur-dev", args="runall $ARGUMENTS")` → `sp:super-planner` agent.
 - After the batch report, print the [execution summary](../skills/spur-dev/references/dev-operations.md#execution-summary) over every attempted run unless
   `--no-summary`.
+- A failed task's report row names the decision row that ended it (`failure-class` or
+  `review-failure-class` = `stop`, or approval `DENIED`) per
+  [reporting a run](../skills/spur-dev/references/decision-points.md#reporting-a-run); the batch failure policy then applies unchanged.

package/plugins/sp/commands/dev-verify.md

@@ -45,7 +45,7 @@ See `sp:code-verification` § Shippable readiness gate.
   run `spur task residual <wbs> scan` + `fold` (observe-only; folds the verdict's `residual-sweep` check,
   PASS → PARTIAL when a blocking residual exists) — under every `--fix` mode — then, only on a
   downgrade, re-run `spur task record <wbs> --verdict-file .spur/run/<wbs>-verdict.json` so Testing
-  carries the final verdict. Same order as the pipeline `record` state (0983): scanning before
+  carries the final verdict. Same order as the pipeline `done` state's record close (0983): scanning before
   record reads unticked-but-proven boxes and folds a clean PASS to PARTIAL. When the task reaches
   `done` through `--next`, run `spur task residual <wbs> settle` (best-effort). On a folded PARTIAL: the bounded remediation loop has
   already run — a residual-failed task is routed to router C6 (HITL STOP), never another

package/plugins/sp/plugin.json

@@ -1,5 +1,5 @@
 {
     "name": "sp",
-    "version": "0.4.15",
+    "version": "0.4.16",
     "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics."
 }

package/plugins/sp/skills/code-implementation/SKILL.md

@@ -103,7 +103,7 @@ surfaces is what keeps that gate quiet.
 
 ## Implement scope: do not run the project quality gate
 
-During implement, the pipeline's `test` hop runs `${vars.qualityGateCmd}` (the full project gate:
+During implement, the pipeline's `gate` state runs `${vars.qualityGateCmd}` (the full project gate:
 `spur self exec check`) immediately after this step and is the gate that actually
 decides pass/fail. Running it inside implement is pure redundancy — it cannot change the outcome and
 only burns wall clock and context budget.
@@ -118,9 +118,9 @@ only burns wall clock and context budget.
   re-select the execution tree inside the call (`cd -- "$TREE"` plus the identity check) instead of
   relying on a `cd` a previous call left behind.
 - **NEVER run** `spur self exec test`, `spur self exec check`, `bun run check`, or any other full-suite /
-  project-gate command from inside implement. These belong to the pipeline's `test` hop.
+  project-gate command from inside implement. These belong to the pipeline's `gate` state.
 - **Full-suite budget: at most 2 per task** (task 0436 R2) — counted across the whole task run
-  (implement probes + the pipeline `test` hop + verify/recheck), not per step. When a check fails,
+  (implement probes + the pipeline `gate` state and its rechecks), not per step. When a check fails,
   run the narrow target (`bun test <file> --test-name-pattern <test>`) to green before any full
   suite; reach for the second full run only when the narrow target cannot reproduce the failure.
 - **Consolidate dogfood runs**: one combined real-data execution that exercises all scenarios,
@@ -128,7 +128,7 @@ only burns wall clock and context budget.
   rerunning the same dogfood command with one flag changed, stop and fold the variants into a
   single run — repeated identical commands are loop-detector findings and pure cost.
 - If a targeted probe reveals a failure you cannot fix within implement scope, note it in
-  `## Solution` and let the `test` hop's fixall handle it — do not pre-empt the gate.
+  `## Solution` and let the `gate` state's `remediate` hop handle it — do not pre-empt the gate.
 
 ### Public-surface probe (task 1135 R1/R6/R8)
 
@@ -155,7 +155,7 @@ changed no public surface, report the single line
 - the paired-script parity test when `package.json` changed (a half-updated `spur-check` /
   `spur-check:full` chain).
 
-The single full project check stays the pipeline `test` hop's job (see the section above); these are
+The single full project check stays the pipeline `gate` state's job (see the section above); these are
 changed-path checks, not that gate.
 
 ## Changed-path targeted checks (dependency-aware verification, task 0510 R3 / task 1142 R3)
@@ -164,14 +164,14 @@ changed-path checks, not that gate.
 surface can break a downstream consumer. The matrix below is dependency-aware — domain → app →
 CLI — so a shared change verifies its consumers without recreating the full project check inside
 implement. **It augments narrow behavior tests; it never authorizes `spur self exec check`,
-`spur self exec test`, or another full project check inside implement** — the pipeline's `test` hop owns
+`spur self exec test`, or another full project check inside implement** — the pipeline's `gate` state owns
 that single full gate.
 
 **Worker iteration check order (task 1142 R3):**
 1. The **changed-path matrix** below (narrow behavior tests + affected consumers);
 2. `spur task gate <wbs> light` (biome on changed files, per-workspace typecheck, rule presets `rules:pre`/`rules:post`, related tests).
 
-Neither step takes the full project gate. The full gate is named only for the pipeline's `test` and `test-recheck` hops.
+Neither step takes the full project gate. The full gate is named only for the pipeline's `gate` state (first visit and rechecks).
 
 | Changed surface | Required targeted tests | Required typechecks |
 | --- | --- | --- |
@@ -189,7 +189,7 @@ Neither step takes the full project gate. The full gate is named only for the pi
   (a flag the plugin layer consumes) actually changes, so an unconditional parity suite does not
   creep into every plugin edit.
 - Run the applicable rows, then stop: the single full project check belongs to the pipeline's
-  `test` hop (`task-pipeline.yaml` `${vars.qualityGateCmd}`).
+  `gate` state (`task-pipeline.yaml` `${vars.qualityGateCmd}`).
 - **Mirrored surfaces: an edit lands on all of them.** When the change is one instance of a repeated
   pattern — the same wiring rule on two runbooks, a signature in both a generator and its generated
   `.d.mts`, a command chain in both `spur-check` and `spur-check:full` — grep for the siblings and

package/plugins/sp/skills/code-improvement/SKILL.md

@@ -89,8 +89,8 @@ and the deepening direction. Full definitions and examples in
 | **minor** | advisory | Local friction: a module slightly too shallow, coupling that's awkward but not coordinated. |
 | **advisory** | advisory | Deepening opportunity: the code works and is testable, but would be cleaner with a deeper module. Always non-blocking. |
 
-**Under the pipeline** (`/sp:dev-review` in a task run), `blocker` and `major` block the
-`approve(HITL)` gate. `minor` and `advisory` are recorded but do not block. **Standalone** reviews
+**Under the pipeline** (`/sp:dev-review` in a task run), `blocker` and `major` block review
+certification (a non-PASS review goes to the `review-failure-class` decision). `minor` and `advisory` are recorded but do not block. **Standalone** reviews
 are advisory-only — the operator decides what to act on.
 
 ---
@@ -185,7 +185,7 @@ Each candidate is a structured finding:
 When invoked as the `--focus architecture` dimension of `/sp:dev-review`:
 
 - The scope is the task's diff (pipeline) or the `path` arg (standalone).
-- `blocker`/`major` candidates block the `approve(HITL)` gate alongside any SECUA blockers from
+- `blocker`/`major` candidates block review certification alongside any SECUA blockers from
   `sp:code-verification`.
 - The candidate list is returned as a **review fragment**; the review coordinator
   (`sp:super-reviewer` — the invoking session under `/sp:dev-review`) merges it into the combined

package/plugins/sp/skills/code-review/references/verification-before-completion.md

@@ -42,10 +42,11 @@ Before reporting a task as complete, a test as passing, a bug as fixed, or a fea
 
 ## Under the pipeline
 
-`task-pipeline.yaml`'s `verify` step (Phase 8) and `record` step enforce this gate. The `verify`
-step runs `sp:code-verification` verify mode, which produces a `VerifyVerdict` artifact; the
-`record` step transcribes it to the task's `## Testing` section. A `done` transition requires a
-PASS verdict.
+`task-pipeline.yaml` enforces this gate deterministically. The `gate` state runs `spur task gate`
+and a red result goes through the `failure-class` decision to `remediate`; the `review` state
+certifies the review answer with `spur task verdict`, which writes the `VerifyVerdict` artifact.
+`review → done` requires that PASS plus the approval decision point, and `done`'s `spur task record`
+close transcribes the verdict to the task's `## Testing` section.
 
 Under manual execution (no pipeline), the agent must still run the gates and paste the evidence.
 "Manual" is not an exemption — it just means the agent, not the pipeline, runs the commands.

package/plugins/sp/skills/code-verification/SKILL.md

@@ -29,7 +29,7 @@ The **verifier** in the Spur execution loop. A coding agent reports "done" with
 this skill is the deterministic counterweight that proves — or disproves — the claim against the
 task's own requirements and Acceptance Criteria, then emits the canonical verdict artifact
 through CLI verbs (section writes are owned by the review coordinator and the deterministic
-`record` step — F92 0593 R1).
+`spur task record` close in `done` — F92 0593 R1).
 
 It backs two commands:
 
@@ -321,7 +321,7 @@ spur task residual <wbs> fold
 > **Do not write `## Review` directly, ever.** The `## Review` section is owned by the
 > `review` coordinator (`/sp:dev-review` → `sp:super-reviewer`), which merges
 > `functional-review` + `code-verification` review mode + `code-improvement` fragments. The
-> `record` step backfills `## Review` from the verdict artifact **only** if the section is bare
+> `spur task record` close backfills `## Review` from the verdict artifact **only** if the section is bare
 > (`sectionIsBare` guard, `task-section-bodies.ts`) — a standalone compatibility fallback, never an
 > overwrite of authored Review. Writing `## Review` here destroys the review step's
 > three-dimensional findings.
@@ -546,7 +546,7 @@ Flags: `--agent <inline|auto|name>` (execution surface — inline default, with
 
 ## When to use
 
-- **Verify a task before `done`** — the pipeline's `verify` step, or a manual `/sp:dev-verify`.
+- **Verify a task before `done`** — the pipeline's `review` state certifies it (`spur task verdict`), or a manual `/sp:dev-verify`.
 - **Audit completed work** — `--force` re-verifies a `done` task (compliance, post-merge).
 - **Focused code review** — `/sp:dev-review` for SECUA findings on a diff.
 
@@ -581,7 +581,7 @@ Do **not** use this skill for:
   rubric.
 - `plugins/sp/references/roles.md` — the Layer-1 role→tier table; this skill's verify/review modes
   run under the `reviewer` role (0538 R4: this file points at roles.md, it does not restate tiers).
-- `task-pipeline.yaml` — the `verify → record` gate that consumes the verdict.
+- `task-pipeline.yaml` — the `review → done` gate that consumes the verdict.
 - **`sp:spur-dev`** — the execution-half umbrella that drives the pipeline this skill gates.
 - [references/code-improvement.md](references/code-improvement.md) — architecture-improvement lens
   for module depth, seam placement, locality, coupling, and testability.

package/plugins/sp/skills/code-verification/references/verdict-schema.md

@@ -64,6 +64,14 @@ no level (ADR-131, 1196), no operator `ackLowConfidence`-style var exists, and h
 findings carry no per-finding grade. A verifier that can write a PASS can still write a wrong
 `HIGH` — which is exactly why the gate derives the level instead of trusting it.
 
+**A review run carries two answer artifacts, one `Confidence:` line each (1254).** The `## Review`
+section states the disposition-derived level (`deriveReviewConfidence`); the captured answer handed
+to `spur task verdict --from-answer` states the evidence-derived level (`deriveVerifyConfidence`)
+under the table above and carries exactly one `Confidence:` line. The two legitimately disagree — a
+PASS with executable AC and one carried P4 is section `MEDIUM`, answer `HIGH` — so the captured
+answer must not repeat the section's line (`confidence-duplicate` rejects the whole answer). The
+review stage's prompt owns that instruction; this schema owns the shape it must produce.
+
 ## Compatibility alias: `scenario` row key
 
 Task 0410 hardened the verdict reader. Producers SHOULD use the canonical `id` field for every
@@ -241,25 +249,33 @@ Wave C verification can emit the following additive `checks[]` rows:
 
 ## How the gate reads it
 
-`task-pipeline.yaml`, transition `verify → record`:
+In `task-pipeline.yaml` the `review` state writes this artifact: `spur task verdict <wbs>
+--from-answer` lints the review answer and derives `.spur/run/<wbs>-verdict.json`. A fold step then
+writes `.spur/run/<wbs>-review.status` = PASS only when the typed verdict is PASS, the artifact's own
+`verdict` is PASS (`jq -r '.verdict // empty'`) and `spur task residual <wbs> review-gate` is clean.
+The `review → done` guard reads that status **and** the approval decision point's token:
 
 ```yaml
 guard:
   kind: shell
   options:
-    command: 'test "$(jq -r .verdict .spur/run/${vars.wbs}-verdict.json)" = PASS'
+    command: >-
+      test "$(cat ".spur/run/$wbs-review.status" 2>/dev/null)" = PASS &&
+      test "$(cat ".spur/run/$wbs-approval.status" 2>/dev/null)" = APPROVED
 ```
 
-with a sibling `verify → failed` guarded on the negation. So a missing file, malformed JSON, or any
-non-`PASS` verdict routes the run to `failed` rather than `done` — the pipeline cannot certify
-completion without an explicit PASS artifact.
+A missing file, malformed JSON or any non-`PASS` verdict leaves the status FAIL, which the
+`review-failure-class` decision routes to `remediate` (`fix`) or `failed` (`stop`). The pipeline
+cannot certify completion without an explicit PASS artifact.
 
 ## Lifecycle
 
-- **Written:** Step 9 of verify mode, *after* the verdict is final (never partially).
-- **Read:** by the workflow gate on the `verify → record` transition.
-- **Location:** `.spur/run/` (the run-scratch dir the pipeline's `record` step also uses).
-- **Lifetime:** per execution attempt; overwritten on the next verify of the same WBS.
+- **Written:** by `spur task verdict` in the pipeline's `review` state, or by Step 9 of standalone
+  verify mode, *after* the verdict is final (never partially).
+- **Read:** by the review fold and the `review → done` guard, then by `done`'s `spur task record`
+  close, which transcribes it.
+- **Location:** `.spur/run/`.
+- **Lifetime:** per execution attempt; overwritten on the next certification of the same WBS.
 
 ## Optional check severity (task 0592, feature F92)
 
@@ -304,6 +320,6 @@ The prose shape above is executed by a single runtime-validated contract:
   failure can never yield PASS.
 - A row-less artifact aggregates to UNKNOWN — a stored PASS that does not recompute to PASS
   (including a row-less PASS) is treated as non-PASS at the done gate. The done-transition choke
-  point (`done-transition-guard.ts` `evaluateDoneTransition`) is the final authority; workflow JSON
-  routing may select `verify → record/failed` but cannot weaken the final transition.
+  point (`done-transition-guard.ts` `evaluateDoneTransition`) is the final authority; workflow
+  routing may select `review → done/failed` but cannot weaken the final transition.
 - `--force-done --reason` on `spur task update <wbs> done` remains the sole auditable override.

package/plugins/sp/skills/functional-review/SKILL.md

@@ -295,7 +295,7 @@ Include the per-requirement traceability table in the report:
 **Under the pipeline**, `sp:functional-review` is a component of `/sp:dev-review`: it returns its
 fragment to the coordinator (`sp:super-reviewer` — the invoking session under `/sp:dev-review`),
 which writes the combined `## Review`. The
-`record` step transcribes only `## Testing` from the verdict artifact and backfills `## Review`
+`done` state's `spur task record` close transcribes only `## Testing` from the verdict artifact and backfills `## Review`
 only when the section is bare (`sectionIsBare` guard, `task-section-bodies.ts`); it never overwrites the
 coordinator's authored Review. Keep the priority-table lead stable in the fragment so the L3 gate
 stays satisfied through `record` → `done`.

package/plugins/sp/skills/functional-review/references/verdict-schema.md

@@ -130,4 +130,4 @@ all core requirements MET                                    → PASS
 | `VerifyVerdict` | `sp:code-verification` | Is the code SECUA-correct and AC-complete? | any core req/AC UNMET → FAIL; any blocker correctness/security → FAIL; any PARTIAL → PARTIAL; else PASS |
 
 A complete `/sp:dev-review --focus all` pipeline may produce both artifacts; they are consumed by
-the pipeline's `record` step and written to the task's `## Testing` section.
+the `done` state's `spur task record` close and written to the task's `## Testing` section.

package/plugins/sp/skills/next-router/references/routing-table.md

@@ -125,7 +125,7 @@ token, deterministic).
 means the workspace holds unfinished task residue, so fixall/unit reruns would either clean it
 unintentionally or re-certify a folded verdict. C6 fires before any fix/unit dispatch; recovery is
 the operator re-running the pipeline (`/sp:dev-run <wbs>`), which re-enters the normal
-verify → test-fix remediation budget.
+gate ⇄ remediate budget.
 
 **Explicit non-probes in v1:** no freeform chat history; no always-on full `bun run test` for every
 call; no git dirtiness as a route (optional advisory print only).

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

@@ -92,7 +92,7 @@ preserved by construction. `recheck` stays the no-progress probe path for fix lo
 
 ## Composition
 
-- **Pipeline:** `sp:spur-dev` runs `run` at `test` and `recheck` at `test-recheck`; light mode
+- **Pipeline:** `sp:spur-dev` runs `run` on the `gate` state's first visit and `recheck` on later visits (after `remediate`); light mode
   belongs to implement/fix edits, not to the gate state.
 - **Fix loops:** `/sp:dev-fixall --gate-log` consumes `<wbs>-test-gate.log` (and the bounded
   `<wbs>-test-gate.findings` anchors) after a red gate; it never writes receipts. A green fixall

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

@@ -50,7 +50,7 @@ Pick the noun, read its reference. Each Tier A and Tier B reference owns that no
 | **Tier B** | **self** | Self-management verbs: scaffold (`init`), project SDLC actions (`exec`), database maintenance (`maintain`), schema migrations (`migrate`), local web server (`serve`), status overview (`status`); `self init` runs post-scaffold validation probes & layout classification | [references/self.md](references/self.md) |
 | **Tier B** | **history** | Import agent histories, aggregate forensic artifacts, render reports, and run the checkpoint-resumed daily pipeline | [references/history.md](references/history.md) |
 | **Tier B** | **projects** | Manage the local multi-project registry and start/stop project servers | [references/projects.md](references/projects.md) |
-| **Tier B** | **decision** | Decision-catalog transport: list visible decisions, show a served contract, run a decision to a served outcome, audit catalog health | [references/decision.md](references/decision.md) |
+| **Tier B** | **decision** | Decision catalog: list visible decisions, show a served contract, run a decision to a served outcome, audit catalog health and maker reliability; author and tune catalog entries | [references/decision.md](references/decision.md) |
 | **Tier C** | **help** | Commander-generated help command; not a Spur noun | Generated `--help` |
 
 **Execute-First Contract:** Load the noun reference first and execute Tier A or Tier B commands
@@ -69,6 +69,26 @@ Each noun's per-topic detail lives one level deeper under `references/<noun>/` (
 `references/tasks/verbs.md`, `references/tasks/section-editing.md`, `references/features/acceptance-criteria.md`,
 `references/rules/operations.md`, `references/workflows/authoring-workflows.md`).
 
+## Lifecycle playbooks
+
+Authorable nouns carry a `## Lifecycle playbook` (rules: `## Lifecycle map`) in one shared stage
+vocabulary — **Create → Evaluate → Triage → Enhance** — each row naming the command and the gate
+that proves the stage, plus best practices. The playbook links the noun's subfiles; it never
+restates them.
+
+| Noun | Playbook |
+| --- | --- |
+| task | [references/tasks.md](references/tasks.md#lifecycle-playbook) |
+| feature | [references/features.md](references/features.md#lifecycle-playbook) |
+| rule | [references/rules.md](references/rules.md#lifecycle-map) |
+| workflow | [references/workflows.md](references/workflows.md#lifecycle-playbook) |
+| agent spec | [references/agent.md](references/agent.md#lifecycle-playbook-agent-specs) |
+| decision | [references/decision/lifecycle.md](references/decision/lifecycle.md) |
+
+Operational nouns (builder, message, self, history, projects) run verbs rather than author
+artifacts, so they have no playbook. Cross-noun selection and composition live in
+`sp:spur-composer`; read-only evaluation reports in `sp:spur-doctor`.
+
 ## When to use
 
 Use this skill to:
@@ -144,7 +164,8 @@ and spreading it; full contract in `docs/04_DESIGN.md` §1.0.1.
 - **[references/message.md](references/message.md)** - durable inter-agent messaging (`send`,
   `inbox`, `reply`, `watch`).
 - **[references/decision.md](references/decision.md)** - decision catalog (`list`, `show`, `run`,
-  `status`); offline by default via the built-in `typesafe` maker.
+  `status`); with no reachable backend each decision serves its declared fallback. Authoring and
+  tuning: [references/decision/lifecycle.md](references/decision/lifecycle.md).
 - **[references/self.md](references/self.md)** - `spur self init|exec|maintain|migrate|serve|status` CLI verbs
   (the five legacy top-level nouns remain hidden aliases). `self init` runs post-scaffold init
   validation (Phase 1.5/1.6 probes).

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

@@ -400,6 +400,18 @@ failed drains marked the session poisoned. The next drain opens a fresh session.
 only. A settled (delivered) inbox message is never redelivered — resuming a session or resetting
 one never re-sends settled work; only never-started deliveries release and redeliver (0831/0834).
 
+## Lifecycle playbook (agent specs)
+
+| Stage | How | Gate / evidence |
+| --- | --- | --- |
+| **Create** | Prefer an `agent.fleet.members` entry; hand-author `.spur/agents/<id>.yaml` only for a spec the fleet cannot express | `spur agent list --specs --json` shows the row with the intended `source` |
+| **Evaluate** | `spur agent doctor [agent] --json` for the executor; `spur agent status --json` for the live process and member session | Executor ready; spec resolves |
+| **Triage** | Run failed → `spur agent trace <runId> --json`; stuck occupant → `spur agent wait <specId> --until <state> --timeout <ms>`; supervisor unreachable → `spur self serve` | Lineage names the failing dispatch |
+| **Enhance** | Change one field (executor, model, role) and re-run the same prompt | Compare the two `trace` records |
+
+- The fleet declaration wins on an id clash; do not keep a same-id file "as a backup".
+- Coordinate through `spur message` / `spur agent wait`, never terminal scraping.
+
 ## What this skill is NOT
 
 - **Not the dispatch decision.** *When* to use `spur agent run` vs a native subagent is the

package/plugins/sp/skills/spur-cli/references/decision/lifecycle.md

@@ -0,0 +1,166 @@
+---
+name: spur-cli-decision-lifecycle
+description: "spur decision lifecycle: author a catalog entry, wire it into a workflow, evaluate a maker with recorded evidence, triage fallbacks and catalog errors, and tune criteria, floors and makers."
+see_also:
+  - spur-cli
+  - spur-composer
+---
+
+# Decision lifecycle — create, evaluate, triage, enhance
+
+The verb catalog is [../decision.md](../decision.md). This file is the per-noun procedure: how a
+decision point is born, proven, diagnosed and improved. Contracts it links rather than restates:
+[decision catalog design](../../../../../../docs/design/decision-catalog.md) (§3.1 SSOT, §3.2 layers,
+§3.6 maker precedence) and
+[decision observability](../../../../../../docs/design/decision-observability-and-adoption.md) (§3.4
+reliability, §4 workflow audit, §5 staged adoption). The upstream format authority is the
+`@gobing-ai/ts-ai-decision` README and its `schemas/decision-catalog.schema.json`.
+
+## 1. Decide it is a decision at all
+
+A catalog decision is a **total classification**: a closed vocabulary, a declared fallback, and a
+recorded outcome. Use the §4 audit classes before authoring anything:
+
+| Class | Use when | Shape |
+| --- | --- | --- |
+| **keep-deterministic** | An exact check answers it (status file, exit code, count, regex) | No decision; a shell guard or rule |
+| **rescue-only** | A deterministic parse answers most inputs; free-form output sometimes defeats it | Parse first, call the decision only on what the parse cannot classify |
+| **adopt** | The input is judgement over prose/diff evidence and a safe default exists | Catalog-reference `decide` step |
+| **keep-human** | It is an operator taste gate | `hitl.confirm`/`hitl.select`; opt-in `decision.mode: evidence` routes through `gate-evidence` |
+
+A model is a regression wherever an exact check exists. A decision with no safe fallback is a gate,
+not a decision.
+
+## 2. Create
+
+1. **Select first.** `spur decision list --json` across every layer; `spur decision show <id> --json`
+   on near matches. An existing id whose criteria fit is reused, never cloned under a new id.
+2. **Pick the layer** (the composer ladder, [spur-composer](../../../spur-composer/SKILL.md)):
+   scratch → `.spur/decisions/<file>.yaml` (project) → shared `config/decisions/<file>.yaml` (spur
+   repository only, recorded operator consent + `build:bundle`). Winners are chosen **per file
+   basename** before the hub loads, so a project file named like a shipped one replaces that whole
+   shipped file — copy every id you still need, or use a new basename.
+3. **Author the entry** (format version 1; unknown keys are rejected at every level):
+
+```yaml
+version: 1
+defaults:
+    minConfidence: 0.8            # repo convention for pipeline decisions; upstream default is 0.7
+decisions:
+    review-scope:                 # ^[a-z][a-z0-9_-]*$ — stable id, it keys the ledger
+        type: choice              # choice | score | noul
+        description: Which review depth does this diff need?   # documentation only, never sent
+        parameters:
+            wbs:
+                type: string      # string | number | boolean | enum | json
+                description: Task WBS the diff belongs to.
+        criteria:                 # choice: >= 2 labels, each label's meaning in one sentence
+            light: Docs-only or test-only diff with no runtime surface.
+            full: Any runtime, contract, schema or security-relevant change.
+        fallback: full            # must be a declared label; the safe answer on any backend failure
+```
+
+   - A parameter with no `default` is **required**. `instructions` is reserved: it is the implicit
+     channel `--evidence` and workflow `evidence:` feed. Never declare it.
+   - `fallback` is the outcome on `no-backend`, `timeout`, `error` and `low-confidence`. Choose the
+     answer that is **safe when wrong** (`full`, `fix`, `defer`, `standard`), not the most common one.
+   - Leave `maker` out of shipped catalogs. Operator config outranks the catalog
+     (`flag → decisions.makers.<id> → decisions.maker → catalog`) because only the machine owner
+     knows which backends exist there.
+   - Spur's `DecisionService` resolves the effective maker as one name. Upstream maker chains
+     (`maker: [a, b]`) and `shadow` exist in the schema but are not surfaced by `decision show`
+     or `status` today; prove them with `run` before relying on them.
+4. **Gate it:** `spur decision status --json` must show no `loadErrors` / `duplicateIds` and exit 0;
+   `spur decision show <id> --json` must render the parameters, criteria and fallback you meant.
+
+## 3. Wire into a workflow (optional)
+
+Use the catalog-reference `decide` form; the inline `question`/`method`/`default` form is
+deprecated (composition lint and the runner warn once per site):
+
+```yaml
+- kind: decide
+  options:
+      id: review-scope                       # step id; one resultFile per step
+      decision: review-scope                 # catalog id
+      params: { wbs: '${vars.wbs}' }
+      evidence:                              # redacted + bounded to 2000 chars, joined into instructions
+          - .spur/run/${vars.wbs}-diffstat.json
+      resultFile: .spur/run/${vars.wbs}-review-scope.decision
+```
+
+- Guards read the schemaVersion-1 `resultFile` row (`value`, `source`, `degraded`, `confidence`).
+  Route on `source == "model"` only where a degraded fallback must be distinguishable.
+- `workflows.decideDecisionMaker` gates the workflow action. Off (the default) → every `decide`
+  serves its fallback with no model call. `spur decision run` ignores the switch.
+- `evidence` and `instructions` are mutually exclusive; `params.instructions` fails the action.
+- Validate with `spur workflow validate <file> --json` and `spur workflow run <file> --dry-run`.
+
+## 4. Evaluate
+
+Evidence before adoption — the S4a–c slices each landed only with recorded `run` evidence for the
+effective maker (observability §5).
+
+| Question | Evidence (read-only unless noted) |
+| --- | --- |
+| Does the contract say what I meant? | `spur decision show <id> --json` |
+| Does the catalog load cleanly? | `spur decision status --json` → `ok`, `loadErrors`, `duplicateIds`, `errors` |
+| Is the maker registered / configured / ever used? | `spur decision status` readiness marks (`ST`, `CONFIGURED BY`, `RECORDED`, `ACCEPTED`) |
+| Does the maker answer right now? | `spur decision status --probe` (calls each effective maker once; writes nothing) |
+| How well has it served? | `spur decision status --reliability [--since <iso>] --json` → per `decisionId × maker`: `samples`, `acceptedRate`, `fallbacks{reason}`, `medianConfidence`, p50/p95 duration |
+| Does it classify known cases correctly? | `spur decision run <id> --param … --evidence <fixture> --json` per labelled fixture (records a ledger row) |
+
+Build a small labelled fixture set — at least one clear case per label plus one ambiguous case — and
+run it against each candidate maker with `--maker <name>`. Compare `value` to the label, not just
+`source: model`: an accepted wrong answer is worse than a fallback.
+
+**Read confidence per maker type.** Probability-native makers (`typesafe`, `laya-local`, `clef`)
+return a model distribution. Sampled makers (`fm-local`) return agreement over k samples, so
+`accepted` means "all samples agreed" and 1.0 is unanimity, not calibration. Choose a
+probability-native maker where the floor must discriminate.
+
+## 5. Triage
+
+| Symptom | Likely cause | Next step |
+| --- | --- | --- |
+| `status` exits 1, `loadErrors` names a file | Schema violation (unknown key, fallback not a declared label, bad `${params.*}` ref) | Fix the file; the whole catalog file is skipped until it loads |
+| `duplicateIds` non-empty | Same id in two winning files of different basenames | Rename or delete one; any `run`/`decide` of that id fails meanwhile |
+| `run` exits 1 | Caller mistake: unknown id, undeclared/missing/invalid param, unregistered `--maker`, unreadable evidence | Read the message; nothing reached a backend |
+| `source: default`, `reason: no-backend` | Maker cannot be constructed (missing credentials, wrong host) | `status --probe`; set credentials or override `decisions.makers.<id>` |
+| `reason: timeout` | Cold local model or unreachable host | Re-probe; prefer a warm or hosted maker for pipeline-critical ids |
+| `reason: error` | Backend rejected the call or returned an invalid answer | Check `decision_logs.error`; on `typesafe`, parameterless decisions hit the known `state: null` 422 until the ts-libs bump (design §5) |
+| `reason: low-confidence`, repeated | Criteria labels overlap, evidence is too thin, or a sampled maker disagrees with itself | Sharpen criteria (§6), add evidence, or switch to a probability-native maker |
+| `RECORDED > 0`, `ACCEPTED 0` | Maker is wired but has never once succeeded | Treat as broken, not healthy; triage by `fallbacks` reason |
+| Config names a maker `status` calls unregistered | Typo, or `clef` without `CLOUDFLARE_ACCOUNT_ID`/`CLOUDFLARE_AUTH_TOKEN` | Loud by design — fix the name or the environment |
+| A `decide` step always degrades | `workflows.decideDecisionMaker` is off | Intended default; enable only after §4 evidence |
+
+## 6. Enhance
+
+Tune one lever at a time and re-run the same fixture set; a change with no before/after evidence
+pair is a preference.
+
+| Lever | When | Where |
+| --- | --- | --- |
+| **Criteria wording** | Low confidence or wrong labels on clear cases | Make labels mutually exclusive and observable ("touches runtime code"), not evaluative ("risky") |
+| **Evidence** | The model cannot see what decides the answer | Add or trim workflow `evidence` files; keep each well under the 2000-char bound |
+| **Parameters** | The answer depends on a structured fact | Declare a typed parameter instead of burying it in evidence |
+| **`minConfidence`** | Fallback rate is too high with correct answers, or too low with wrong ones | Per-decision field; lower only with fixture evidence that low-confidence answers were right |
+| **Maker** | Reliability differs by backend | Operator config `decisions.makers.<id>` (not the shipped catalog) |
+| **Fallback** | The safe-when-wrong answer changed | Change only with the owning workflow's guard reviewed in the same change |
+| **Adoption class** | A deterministic parse now covers the input | Demote to rescue-only or keep-deterministic |
+
+Never rename a shipped id: the ledger, Board Decisions tab and workflow `decision:` references all
+key on it. Add a new id and retire the old one through the workflow change.
+
+## 7. Best practices
+
+- **Determinism first, model second.** Every adopted decision keeps a deterministic route or a safe
+  fallback so the pipeline behaves identically with the switch off.
+- **One question per id.** A decision that needs "and" in its description is two decisions.
+- **Labels are a contract.** Guards and downstream shell read the label strings; treat a label
+  rename as a breaking change.
+- **Probe is not evidence.** `--probe` proves liveness; only `--reliability` and labelled `run`
+  results prove quality, and the probe never writes the rows it would inflate.
+- **Never route pipeline correctness on `maker-liveness`.** It serves only `status --probe`.
+- **Measure before you migrate.** Land the catalog entry, gather `run` evidence, then adopt in a
+  workflow — one decision point per change.