@gobing-ai/spur 0.4.14 → 0.4.16

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/pr-reviewing/SKILL.md

@@ -39,19 +39,19 @@ invoking coding agent is the local orchestrator and implementer.
       ▼
 sp:pr-reviewing (this skill — mode routing, local-review dispatch, triage, fix)
       │  local route:  pr-check --scan-only → git diff --name-only → /sp:dev-review
-      │  Codex route:  pr-review.yaml  (check → precheck → open → review)
+      │  Codex route:  pr-check → pr-open → pr-review → pr-status
       ▼
 `spur builder pr-<verb>` + `spur builder show-branches`  ← tested git/gh core
 ```
 
-- **State order and guards** for the Codex route are defined once, in `pr-review.yaml`. Do not
-  re-derive them in prose; when the YAML and this file disagree, the YAML wins and this file gets
-  fixed.
 - **Deterministic work** (every git/gh call) goes through the four flat `spur builder pr-<verb>`
   commands and `spur builder show-branches` — never hand-rolled `gh` invocations that drift from
   the tested core.
+- **Sequencing inside a verb** (preflight→hygiene, push→ensure, request→wait→collect) lives in
+  `runPrVerb`, not in this file. This skill orders the *verbs*; each verb owns its own ops, its
+  one-word verdict and its exit code.
 - **Model-bearing work** (the local review dispatch, finding triage, `fix` edits) is this skill's
-  job and never enters the workflow machine.
+  job and never enters a deterministic verb.
 
 ## Modes and routing
 
@@ -61,7 +61,7 @@ Parse the first positional argument as the mode; default `status`.
 | --- | --- | --- |
 | `status` | direct CLI | `spur builder show-branches --base <b> --pr --format markdown`, with the report filtered to the current branch and its base, plus `spur builder pr-status --json` (PR number, CI, local changes, latest current-head review in `.review`). Read-only. |
 | `review` | local stack | `spur builder pr-check --base <b> --scan-only --json`; `BLOCK` stops, `WARN` is reported. Then `git diff --name-only <b>...HEAD` → `/sp:dev-review --scope <comma-joined paths> --focus <focus>`. An empty diff ends with "nothing to review". Posts nothing to GitHub. |
-| `review --codex` | `pr-review.yaml` | Run the spine with `mode=full`; `--force` → `mode=rerun`; `--no-wait` → `mode=submit`; `focus`/`baseBranch` passed as vars. States: check → precheck → open → review. `pending` is reported as pending, never failure. |
+| `review --codex` | direct verb sequence | `spur builder pr-check --base <b> --json` → `pr-open --base <b> --json` → `pr-review --focus <focus> [--force] [--no-wait] --json` → `pr-status --json`. Each verb's verdict gates the next; `PENDING` is reported as pending, never failure. |
 | `fix` | direct verb + model work | Findings from the latest local review verdict, or from `spur builder pr-status --json` `.review` when the last review was Codex. Validate each finding against the code before editing; rejected findings are listed with a reason. Fix the legitimate ones, run the project gate, make one focused commit and push without force (`spur builder pr-open` handles a first push). |
 
 Retired modes print one notice line and run their replacement: `full` → `review --codex`;
@@ -125,17 +125,37 @@ Codex:         clean | findings | pending | not requested | unavailable
 
 ## Review mode (--codex)
 
-Run `pr-review.yaml` as the single source of truth for the Codex spine — check → precheck → open →
-review. Never call `spur builder pr-review` in a way that bypasses the workflow's state order and
-guards.
+Four verbs in order. Each one's `--status-file` verdict gates the next — stop at the first red
+verdict and report it with the stage's JSON record; never run a later verb to "retry" an earlier
+one, and never force-push around a rejected push.
 
 ```sh
-spur workflow run pr-review.yaml --vars '{"mode":"full","baseBranch":"<base>","focus":"<focus>"}'
+spur builder pr-check  --base "$base" --json --status-file .spur/run/pr-check.status
+# PASS|WARN → continue (a WARN rides into the report).  BLOCK|FAIL → stop.
+# BLOCK = secrets/.env/conflict markers/private keys. FAIL = preflight (detached HEAD, dirty
+# tree, gh unauthenticated, no GitHub remote, or the current branch *is* the base).
+
+# Optional project fast check before spending a review request. Run it only when the project
+# defines one; a red check stops here rather than reviewing code that fails its own gate.
+
+spur builder pr-open   --base "$base" --json --status-file .spur/run/pr-open.status
+# FOUND|CREATED → continue.  FAIL → stop (push rejected, no reviewable delta, PR create failed).
+
+spur builder pr-review --focus "$focus" [--force] [--no-wait] \
+    --timeout 600 --interval 30 --json --status-file .spur/run/pr-review.status
+# CLEAN|FINDINGS → collected.  PENDING → pending, not failed.  FAIL → stop.
+
+spur builder pr-status --json   # composite PR/CI/Codex report; read-only, never gates
 ```
 
-- `mode=full` by default; `--force` → `mode=rerun`; `--no-wait` → `mode=submit`.
-- The workflow's `pending` terminal state is **pending, not failed**: report the requested or
-  in-flight state and collect later with `status`.
+- **Flags from the invocation:** `--force` requests a fresh review of an already-reviewed HEAD;
+  `--no-wait` posts the request and returns `PENDING` without polling. Both are optional and
+  independent — pass each as its own argument. The default is request → wait → collect, with
+  per-HEAD dedupe.
+- **`PENDING` is pending, not failed** (a wait timeout included): report the requested or in-flight
+  state and collect later with `status`.
+- **`pr-review` owns request → wait → collect in one runtime** (`runPrVerb`), so there is no
+  separate request record to thread between steps.
 - When `--codex` is passed, the external review goes through the GitHub PR and an `@codex review`
   request only — never a local Codex CLI review. If GitHub Codex Code Review is unavailable, stop
   and report the setup/access problem; never silently fall back to a local review.
@@ -219,20 +239,18 @@ and nothing else.
 
 ## Platform notes
 
-- The skill, command and workflow YAML are platform-neutral; per-platform emission is owned by
-  superskill. On platforms without a Skill tool, read this file and follow the protocol manually.
+- The skill and command are platform-neutral; per-platform emission is owned by superskill. On
+  platforms without a Skill tool, read this file and follow the protocol manually.
 - Prerequisites: `git` for every path. `gh` authenticated with a GitHub remote wherever PR state is
   touched: `status` (its `pr-status` half — the `show-branches` topology runs on `git` alone, and
   its `--pr` enrichment only degrades with a warning), `review` (step 1's `pr-check --scan-only`),
-  `review --codex` (the workflow's check/open/review states), and `fix` when it reads a Codex
+  `review --codex` (its `pr-check`/`pr-open`/`pr-review` verbs), and `fix` when it reads a Codex
   verdict or pushes through `pr-open`. The `git diff --name-only` scope, `/sp:dev-review`, and
   `fix`'s local-verdict edit/commit path need only `git`. The `--codex` path additionally needs
   GitHub Codex Code Review enabled for the repository.
 
 ## Additional Resources
 
-- **Workflow SSOT (Codex path):** `pr-review.yaml` (seeded by `spur init`; tune per project — wait
-  budget, `preReviewCmd`, dedupe policy)
 - **Command source:** the four flat verbs `pr-status` / `pr-check` / `pr-open` / `pr-review` plus the
   read-only `show-branches` report — see `sp:spur-cli` `references/builder.md`
 - **Local review:** `/sp:dev-review` — its dimensions live in `sp:code-verification` and

package/plugins/sp/skills/spec-decomposition/references/decomposition.md

@@ -563,7 +563,8 @@ schema before emitting.
 **Pass the deterministic task check.** Each `acceptance_criteria` bullet must be an exact feature
 scenario title (L4.uncovered-task-scenario); add task-local checks as prose after the bullets, not
 as extra bullets. No section body may use `HITL`, `merge event`, `content-gate`, `GATED`, or
-`capstone` as standalone words (L4.gate-language); ambiguous words (`approval`, `approved`,
+`capstone` as standalone words in any case (L4.gate-language) — dotted action kinds such as
+`hitl.confirm` are fine, a bare `hitl` count is not; ambiguous words (`approval`, `approved`,
 `merged`) warn only with a gating cue (`until`, `after`, `once`, `before`, `pending`, `blocked`,
 `wait for`, `requires`) in the same sentence, so plain composition prose stays silent — say
 "operator answer" / "accepted" instead, and keep enum values out of that list too.

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/builder.md

@@ -80,7 +80,7 @@ spur builder pr-review --force --json                  # force a fresh review of
 ```
 
 Four flat verbs over the ops absorbed from `plugins/sp/scripts/pr-reviewing.ts` (script-absorption
-PR-7); driven by the `pr-review` workflow. Each composes existing ops and embeds their records in
+PR-7); sequenced directly by `sp:pr-reviewing`. Each composes existing ops and embeds their records in
 one JSON object per verb: `pr-status` → the status object plus `review` (collect, or `null` with no
 PR); `pr-check` → `{ ok, verdict, preflight, hygiene }`; `pr-open` → `{ ok, verdict, push, pr }`;
 `pr-review` → `{ ok, verdict, request, findings }`.
@@ -94,7 +94,7 @@ PR); `pr-check` → `{ ok, verdict, preflight, hygiene }`; `pr-open` → `{ ok,
   explicit pin that no longer matches the PR head fails loud instead of reporting a moved commit.
 - **Deduping:** `pr-review` collects without a new request when the exact HEAD is already reviewed,
   and returns `PENDING` when a marked request is still in flight; `--force` requests a fresh review
-  (`mode=rerun`). Never force-pushes.
+  of the current HEAD regardless. Never force-pushes.
 
 ```bash
 # deprecated alias, one release: maps the old op names to the verbs above

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.