@gobing-ai/spur 0.4.14 → 0.4.16

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

@@ -1,6 +1,6 @@
 ---
 name: spur-cli-decision
-description: "spur-cli noun reference: operate `spur decision` as the read/serve surface over the decision catalog - list registered decisions, show one served contract (parameters, criteria vocabulary, effective maker), run a decision to a served outcome (never writes a workflow resultFile), and status the catalog layers with per-maker readiness marks (registered, configured, recorded, probed). Backed by @gobing-ai/ts-ai-decision 0.5.22 hub; offline by default via the built-in `typesafe` maker. Introduced by task 1093; readiness marks and `--probe` by feature P11."
+description: "spur-cli noun reference: operate `spur decision` as the read/serve surface over the decision catalog - list registered decisions, show one served contract (parameters, criteria vocabulary, effective maker), run a decision to a served outcome (never writes a workflow resultFile), and status the catalog layers with per-maker readiness marks (registered, configured, recorded, probed). Backed by the @gobing-ai/ts-ai-decision hub; with no reachable backend every decision serves its declared fallback. Lifecycle (author, evaluate, triage, tune) lives in decision/lifecycle.md."
 see_also:
   - spur-cli
 ---
@@ -25,14 +25,16 @@ Decisions resolve first-wins across three layers:
 | `registered` | folders listed in config `decisions.paths` | Operator-added catalogs |
 | `shared` | `decisions/` under the bundled config root | Shipped catalogs (`config/decisions/` in-repo) |
 
-The bundled shared catalog ships `task-triage`, `failure-class`, `review-failure-class`,
+The bundled shared catalog ships `task-semantic-risk`, `failure-class`,
 `gate-evidence`, `idea-recommendation`, `needs-design`, `anatomy-validation-verdict` and
 `maker-liveness` (the last served only by `spur decision status --probe`; no workflow references
-it). Duplicate ids across layers keep the higher layer; duplicates inside one file are a load error.
+it). Layers win **per file basename** (a project `gates.yaml` replaces the shipped `gates.yaml`
+whole); the same id in two winning files of different basenames is a `duplicateIds` catalog error.
 
 **Config keys** (under `decisions:` in the global `~/.config/spur/config.yaml` or project `.spur/config.yaml`):
 `paths` (extra catalog folders forming the `registered` layer), `maker` (default DecisionMaker
-for every decision point), `makers` (per-decision-id overrides). An unregistered maker name is a
+for every decision point), `makers` (per-decision-id overrides), `log` (`full` | `metadata` | `off`,
+how much of each served decision the ledger keeps). An unregistered maker name is a
 config error, never a silent fallback (design §3.6).
 
 ## Verb map
@@ -43,6 +45,7 @@ config error, never a silent fallback (design §3.6).
 | `show <id>` | One served contract: type, parameters, criteria, fallback, minConfidence, effective maker + source | `--json` |
 | `run <id>` | Serve one outcome (closed vocabulary; **never writes a resultFile**) | `--param <pairs...>`, `--evidence <files...>`, `--maker <name>`, `--json` |
 | `status` | Sectioned readiness report: one status line, errors, aligned `Makers` and `Decisions` tables (registration, configuration source, recorded evidence), `Catalog` block | `--probe`, `--reliability [--since <iso>]`, `--json` |
+| `outcome <invocation-id>` | Record what actually happened after a served decision — acceptance is not accuracy (task 1263). First write wins | `<outcome>`, `--review-severity <wbs>`, `--gate-status <run-id>`, `--source <text>`, `--json` |
 
 All verbs support `--json` (bare payload) and `--json-envelope` (`{ok, data|error}` envelope,
 ADR-091). Failure output for `--json` commands uses the canonical error envelope only under
@@ -51,6 +54,62 @@ ADR-091). Failure output for `--json` commands uses the canonical error envelope
 **Exit codes:** `status` exits 1 on any catalog load error or maker-config error; `show` exits 1 on unknown id; `list` exits 0
 (design §3.4 — load errors surface via `status`) except for an invalid `--layer` value (exit 1).
 Error envelopes use `NOT_FOUND` for an unknown id and `VALIDATION_FAILED` for every other caller mistake.
+`outcome` exits 1 for an unknown invocation id (there is no decision to score) and 2 for a malformed
+outcome (it must match `^[a-z0-9-]{1,32}$`) or for naming zero/several outcome sources.
+
+## Acceptance versus accuracy (`outcome` + `--reliability`)
+
+`decision.end` says **what was answered**; it never says whether the answer was right. A maker can
+be accepted on every call and still add no information: `review-failure-class` answered its own
+fallback 15/15 times at confidence 1.0 before task 1262 retired it. Tuning `minConfidence`, choosing
+a maker, or judging a shadow maker therefore needs (value, outcome) pairs.
+
+**Recording one.** A decide step now writes the invocation's ledger key into its result row
+(`invocationId`, task 1263 R1) — the same id the `decision.*` events and the `decision_logs` row
+carry. Once the outcome is known, record it:
+
+```bash
+# an explicit label (lowercase slug): what a human or a later check observed
+spur decision outcome <invocation-id> fixed --source "quality gate recheck"
+# derived from a task's Review findings: the worst finding, resolved rows included (p1-p4, or none)
+spur decision outcome <invocation-id> --review-severity 1263
+# derived from a gate visit: PASS -> fixed, anything else (or a missing token) -> not-fixed
+spur decision outcome <invocation-id> --gate-status <run-id>
+```
+
+First write wins: a replay exits 0 with `recorded: false` and the outcome that already stands. The
+row lands in `system_events` beside `decision.end`, on the same `run_id`, so the report joins it by
+`invocationId`.
+
+**Scoring one.** `decisions.outcomeMap` in config (project or global layer) holds Spur's reading of
+Spur's own artifacts — per decision id, which recorded outcomes count as correct for each served
+value (`String(value)` keys, so a yes/no decision uses `"true"`/`"false"`). The shipped defaults
+score `failure-class` (`fix` → `fixed`, `stop` → `not-fixed`) and `task-semantic-risk`
+(`"false"` → `none`/`p4`/`p3`, `"true"` → `p1`/`p2`).
+
+`spur decision status --reliability` then reports, per (decision × maker) group:
+
+| Field | Meaning |
+| --- | --- |
+| `samples`, `accepted`, `acceptedRate` | `decision.end` rows; acceptance only |
+| `outcomes` | recorded outcomes by label over those samples |
+| `accuracy` | correct accepted answers ÷ accepted answers **with an outcome**; null when the decision has no map entry or no accepted sample recorded one |
+| `fallbackAccuracy` | the same ratio over fallback (`source: default`) samples |
+
+`accuracy: null` is deliberate: an unmapped decision or an unobserved one is unknown, never zero.
+Acceptance and accuracy answer different questions — a high `acceptedRate` with `accuracy: null`
+means "the maker answered and we have not looked at whether it was right yet".
+
+**Reading a sampled maker.** Sampled makers report unanimity, not calibration: with two options,
+2-of-3 agreement is ~0.08 confidence and the 0.8 floor only accepts when every sample agreed
+(ts-libs `docs/design/llm-agent-decision-backend.md` § Confidence granularity). A 1.0 confidence on
+that kind of maker therefore means "the samples agreed", not "the answer is calibrated".
+
+**Retuning `minConfidence` from the report.** Read a group's `accuracy` and `fallbackAccuracy`
+together with `fallbacks` by reason. Accepted-but-wrong answers point at raising the floor (or
+changing the maker); fallbacks that were right point at lowering it. Change the floor in the
+catalog entry (or `defaults.minConfidence`), record the new samples, and compare the same two
+numbers — never one of them alone.
 
 ## Readiness marks (`status`, feature P11)
 
@@ -77,6 +136,57 @@ error surfaced as fallback, declined — is still a **successful serve** (exit 0
 **before** the backend: unknown id, unknown parameter, missing required parameter, type-invalid
 parameter, unregistered `--maker`, unreadable evidence file.
 
+## Executor failure rescue (`executor-failure-class`)
+
+The agent executor escalates on `FAILURE_RULES` matches only (`packages/app/src/services/failure-classification.ts`).
+A failure no rule matches — a reworded rate limit, "credits depleted", a proxy error body — ends
+the run as a task defect until somebody adds a regex. `executor-failure-class` covers that residue:
+`resource-exhaustion` / `auth` / `task-defect`, fallback `task-defect`, `minConfidence: 0.85`
+(a false `resource-exhaustion` costs a failover attempt; a false `task-defect` equals today's
+behaviour, so uncertainty must resolve downward).
+
+**It ships off.** `workflows.executorFailureDecisionMaker: true` is the opt-in; without it the executor
+makes no model call and the context carries no rescue seam at all. Turning it on is an operator
+call backed by replay evidence (`spur decision run executor-failure-class --evidence <tail>` over
+real unmatched tails), not a default.
+
+The rescue runs only when every deterministic check declined: non-zero exit without a timeout
+signal, `undefined` from `classifyDispatch`, no permission-denial evidence (a denial stays terminal),
+no confirmed quota event, and non-blank output. It sees the failure text **redacted first, then
+tailed** to 4096 characters — tailing first could cut a secret at the boundary and send the
+fragment off-box, so never reorder that.
+
+**Evidence leaves the machine with a hosted maker.** The tail is failure output from whatever the
+agent printed, so a hosted maker (`clef`) sees it. Two consequences:
+
+- Prefer a **probability-native** maker for this id (`decisions.makers.executor-failure-class`):
+  sampled makers accept only on unanimity (ts-libs `docs/design/llm-agent-decision-backend.md`
+  § Confidence granularity), so the 0.85 floor does not grade them.
+- `laya-local` keeps the evidence on-box (it needs Apple Silicon, and since task 1262 R1 the bundled
+  CLI ships its worker, so `workerScript` resolves without a source checkout).
+
+Every rescue is attributed `caller: executor` with the failing run's id, so it shows up in
+`decision.*` events, `decision_logs` and `spur decision status --reliability` with no extra work.
+To promote recurring text into a deterministic rule, list the accepted rescues:
+
+```bash
+sqlite3 .spur/spur.db "
+  SELECT o.decision_id, json_extract(o.payload_json, '$.data.outcome') AS answer,
+         json_extract(s.payload_json, '$.data.workflowName') AS workflow, o.run_id
+  FROM system_events o
+  JOIN system_events s
+    ON s.event_name = 'decision.start'
+   AND json_extract(s.payload_json, '$.data.invocationId')
+       = json_extract(o.payload_json, '$.data.invocationId')
+  WHERE o.event_name = 'decision.end'
+    AND json_extract(o.payload_json, '$.data.caller') = 'executor'
+    AND json_extract(o.payload_json, '$.data.source') = 'model'
+  ORDER BY o.occurred_at DESC;"
+```
+
+Add the `FAILURE_RULES` entry by hand, with a test — the rescue stays the safety net for what the
+table still misses.
+
 ## Parameters and evidence
 
 `--param k=v` is repeatable and validated against the decision's declared parameters: values for
@@ -95,23 +205,41 @@ keys). An unreadable evidence file exits 1 before any backend call.
 Makers resolve `flag → config-decision → config-default → catalog-decision → catalog-default`;
 `decision show` reports the effective maker as `{name, source}` with that source precedence
 (operator config outranks the shipped catalog because only the machine owner knows which backends
-exist there). The final `catalog-default` maker is the hub built-in `typesafe` — decisions served
-without a configured backend still produce deterministic closed-vocabulary outcomes, which is why
-`run` is usable in tests and scripts with no model access.
+exist there). The final `catalog-default` maker is the hub built-in `typesafe`, a **hosted** maker
+that needs `TYPESAFE_API_KEY`. Without a reachable backend `run` still exits 0 with the declared
+fallback (`source: default`, reason `no-backend`), which is why it is usable in tests and scripts
+with no model access — the outcome is deterministic, not model-judged.
+
+**Available makers:** the four upstream built-ins (`typesafe`, `fm-local`, `laya-local`,
+`llm-agent`) plus Spur's hosted `clef` (Cloudflare Workers AI via `@gobing-ai/ts-decision-clef`).
+
+- `llm-agent` samples an installed coding agent: by default the first installed tier-1 agent, 3
+  one-shot samples, accepted only when every sample agrees. Spur passes it no driver options, so
+  each ask costs several agent runs; name it per decision (`decisions.makers.<id>`) rather than as
+  the project-wide `decisions.maker`.
+- `clef` registers only when both `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_AUTH_TOKEN` are set in
+  the environment; without them it is absent from `registeredMakers`, so naming it in config or
+  `--maker` is a config error, never a silent fallback. Its model defaults to `clef-flash` (a
+  catalog `model` selects `clef`).
+
+## Workflow consumption
 
-**Available makers:** the three upstream built-ins (`typesafe`, `fm-local`, `laya-local`) plus
-Spur's hosted `clef` (Cloudflare Workers AI via `@gobing-ai/ts-decision-clef`). `clef` registers
-only when both `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_AUTH_TOKEN` are set in the environment;
-without them it is absent from `registeredMakers`, so naming it in config or `--maker` is a config
-error, never a silent fallback. Its model defaults to `clef-flash` (a catalog `model` selects
-`clef`).
+Workflows consume a decision through the catalog-reference `decide` action
+(`{id, decision, params?, evidence? | instructions?, resultFile}`); the inline
+`question`/`method`/`default` form is deprecated. `workflows.decideDecisionMaker` (default off)
+gates model calls there — off, every `decide` serves its fallback. `hitl.confirm`/`hitl.select`
+with `decision: {mode: evidence, …}` route through `gate-evidence` under the separate
+`workflows.hitlDecisionMaker` switch (default off — the gate defers to the operator, or under
+`profile=auto` to its declared fallback). Neither switch affects `spur decision run`. Shape, adoption classes and
+guards: [decision/lifecycle.md](decision/lifecycle.md) §1, §3.
 
 ## Examples
 
 ```bash
 spur decision list --json | jq -r '.[].id'
-spur decision show task-triage                      # inspect contract before serving
-spur decision run task-triage --param wbs=1093 --json
+spur decision show task-semantic-risk               # inspect contract before serving
+spur decision run task-semantic-risk --param wbs=1093 \
+    --evidence .spur/run/1093-diffstat.json --evidence docs/tasks/1093_*.md --json
 spur decision run failure-class --param wbs=1093 \
     --evidence .spur/run/<runId>-test-output.txt    # redacted evidence -> instructions
 spur decision status --json | jq '.loadErrors'      # audit catalog health
@@ -124,7 +252,9 @@ spur decision status --json | jq '.makers[] | {name, registered, recorded: .evid
 
 - Design: `docs/design/decision-catalog.md` (§2 catalog authoring, §3.4 CLI surface),
   `docs/design/decision-observability-and-adoption.md` (§3.4 reliability report, §3.4.1 readiness view)
-- Hub: `@gobing-ai/ts-ai-decision` 0.5.22 (`DecisionService`, catalog schema, maker registry)
+- Lifecycle: [decision/lifecycle.md](decision/lifecycle.md) (create, wire, evaluate, triage, enhance)
+- Hub: `@gobing-ai/ts-ai-decision`, version pinned by the root `workspaces.catalog` (`DecisionService`,
+  catalog schema, maker registry)
 - App service: `packages/app/src/decision/decision-service.ts` (makers, `probeMaker`),
   `packages/app/src/decision/decision-status-readiness.ts` (readiness marks, probe loop)
 - Shipped catalogs: `config/decisions/*.yaml`

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

@@ -272,12 +272,31 @@ spur feature sync H2 --folder docs/custom-tasks --json   # non-default tasks fol
   task statuses, verdict mtimes); an identical next call replays the prior result
   (`suppressed: true`) instead of re-deriving. A changed input, `--force`, or a non-blocked
   outcome re-derives/clears. Dry-run never reads or writes the state.
+- **Single-call completion after the verifying entry (1247):** entering `verifying` runs the
+  feature-verification pass (1246), but the hop list was derived before that pass recorded its
+  receipt. Sync re-derives **once** after a `verifying` hop lands, so a PASS receipt applies
+  `verifying → done` in the same call (`appliedHops: ['verifying','done']`). A FAIL or still-missing
+  receipt leaves the feature in `verifying` and still exits `0`; `proposal.reason` then names the
+  receipt finding and the rework edge (`spur feature update <id> active`). The re-derive
+  never runs when the verifying hop was not applied (guard denied, goal conflict, `--dry-run`).
 - **`--json`** single-feature emits `{ proposal, applied, appliedHops[], suppressed? }`; `--all` emits
   `{ totalFeatures, evaluated, updatedCount, results[] }` where each result is the single-feature
   shape. `proposal` is
   `{ featureId, from, to, reason, requiresConfirm?, gateBlocked?, gateFindings?, hops? }`.
 - **Exit codes:** `0` success (including NOOP), `1` error, `2` invalid usage (no id and no `--all`).
 
+## Lifecycle playbook
+
+| Stage | How | Gate / evidence |
+| --- | --- | --- |
+| **Create** | `spur feature create <name> [--parent <id>]`; place it MECE in the tree ([features/hierarchy-mece.md](features/hierarchy-mece.md)) | `spur feature check <id> --json` exits 0 |
+| **Evaluate** | AC quality ([features/acceptance-criteria.md](features/acceptance-criteria.md)), [traceability](#traceability-habits), roadmap fit ([features/roadmap-priority.md](features/roadmap-priority.md)) | `sp:spur-doctor` report cites `check` rows |
+| **Triage** | Structural finding → `check --fix`; stale roster → `refresh`; status drift → `sync --dry-run` then `sync` | `check` clean; `sync --dry-run` empty |
+| **Enhance** | `update --section` for AC/scope; `move --dry-run` before re-parenting a subtree | Every task still links to a live AC |
+
+- A feature is a capability, not a work list; tasks own execution.
+- Re-parent with `move`, never by renaming IDs by hand.
+
 ## What this skill is NOT
 
 - **Not the planning loop.** Intake → create → AC generation → check-loop → decomposition →

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

@@ -22,6 +22,8 @@ Operating the gate well is a full lifecycle — not just running it. This skill
 | **Run & fix** | Gate the diff, interpret findings, self-correct, re-run until green | this file |
 | **Author** | Add a constraint by writing a new rule when a standard/anti-pattern emerges | [rules/authoring-rules.md](rules/authoring-rules.md) |
 | **Fine-tune** | Dial in quality: severity, glob scoping, exemptions, preset `disable`/`overrides`, layering | [rules/fine-tuning.md](rules/fine-tuning.md) |
+| **Evaluate** | `spur rule trace --last <n> --json` for hit rates and noise; `spur rule list --preset <name> --json` for what is enforced | this file, [rules/operations.md](rules/operations.md) |
+| **Triage** | Start from `spur rule trace <run-id> --json`: false positive → scope/exempt; true positive → fix the code, never the rule | [rules/fine-tuning.md](rules/fine-tuning.md) |
 | **Validate & extend** | Validate files/presets, smoke-test, add custom evaluators/resolvers/formatters | [rules/validation-and-extension.md](rules/validation-and-extension.md) |
 
 ## When to use

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

@@ -51,7 +51,7 @@ re-reading or re-tokenizing the task.
 | `batch-create` | Create many tasks from a validated JSON array | `--file <path>` `--skip-ready` `--agent <selector>` `--folder` `--json` |
 | `batch-plan <mode>` | Batch plan projection: `waves` / `order` / `task-children` (JSON on stdout; the batch driver's visible plan) | `--tasks <file>` `--concurrency <n>` `--letter <A-Z>` `--plan <file>` |
 | `preflight [wbs]` | Read-only batch admission: TABLE A STOP check, quick readiness (`--operation`), one-shot recovery hop; status/deps read from the corpus unless given | `--status <s>` `--deps <list>` `--dep-status <map>` `--operation <op>` `--filtered-count <n>` `--required-sections <list>` `--present-sections <list>` `--force` `--recovery` `--classify-feature <json>` `--folder` `--json` |
-| `wrapup <op>` | One deterministic `wrapup-pipeline` step (`resolve`, `route-reason`, `metrics`, `feature-transition`, `doc-sync-snapshot`, `doc-sync-scope`, `doc-supersession`, `drift-probe`) — workflow-internal | `--run-id <id>` `--tasks <json>` `--mode <m>` `--feature <id>` `--feature-gate-cmd <cmd>` `--spur-bin <cmd>` |
+| `wrapup <op>` | One deterministic `wrapup-pipeline` step (`resolve`, `route-reason`, `metrics`, `doc-sync-snapshot`, `doc-sync-scope`, `doc-supersession`, `drift-probe`) — workflow-internal | `--run-id <id>` `--tasks <json>` `--mode <m>` `--spur-bin <cmd>` |
 | `record <wbs>` | Write `Testing` from a verify verdict (deterministic); bare-`## Review` fallback only; optional Solution + transition | `--verdict-file <path>` `--solution-from-diff` `--transition <status>` `--folder` `--json` |
 | `verdict <wbs>` | Derive PASS/PARTIAL/FAIL/UNKNOWN from verify answer text → verdict JSON; see [answer-file shape](tasks/verbs.md#answer-file-shape-what---from-answer-parses) | `--from-answer <path>` `--folder` `--json` |
 | `check [wbs]` | Four-layer validation; `--fix` repairs structure; `--corpus` is the explicit unsuppressed audit; `--precheck` adds the pipeline precheck gate (size + evidence channel, WBS required) | `--strict` `--as <status>` `--strict-core` `--precheck` `--fix` `--folder` `--corpus` `--since <ref>` `--json` |
@@ -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/ac-style-guide.md

@@ -127,7 +127,8 @@ scenario, it matches by title. Rules:
 - **No synonyms in cross-references.** The title in the feature file and the title in the
   task's AC reference must be byte-identical.
 - **Avoid gate vocabulary in titles.** `spur task check` (L4.gate-language) rejects task sections
-  containing `HITL`, `merge event`, `content-gate`, `GATED`, or `capstone` as standalone words;
+  containing `HITL`, `merge event`, `content-gate`, `GATED`, or `capstone` as standalone words in any
+  case (dotted action kinds such as `hitl.confirm` are fine);
   ambiguous words (`approval`, `approved`, `merged`) warn only when the same sentence also carries
   a gating cue (`until`, `after`, `once`, `before`, `pending`, `blocked`, `wait for`, `requires`)
   — plain composition prose like "the stages merged back into one step" stays silent. Task AC

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

@@ -181,14 +181,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.