@gobing-ai/spur 0.4.15 → 0.4.17

package/plugins/sp/skills/conflict-finding/references/finding-contract.md

@@ -218,7 +218,7 @@ inventory, findings, unresolved, coverage, cost, remediation, errors
 {
   "schema_version": 1,
   "command": "dev-find-conflict",
-  "scope": "docs/00_ADR.md",
+  "scope": "scope:docs/00_ADR.md",
   "mode": "adaptive",
   "pillars": ["authority"],
   "authority_map": {},
@@ -236,7 +236,7 @@ inventory, findings, unresolved, coverage, cost, remediation, errors
 | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `schema_version` | integer, `1`. The envelope contract version — not a semantic-reasoning version.                                                                                             |
 | `command`        | string, `dev-find-conflict`.                                                                                                                                                |
-| `scope`          | string. The resolved audit scope (path, WBS, feature ID, symbol, command, or `"<project>"`).                                                                                |
+| `scope`          | string. The frozen target as `<kind>:<id>[,<id>]` — `tasks:0486,0487`, `feature:H11,H12`, `scope:apps,docs` — or `"<project>"` when no selector was given.               |
 | `mode`           | string, `adaptive` \| `full`.                                                                                                                                               |
 | `pillars`        | string[]. The pillars actually audited (subset of `source`, `tasks`, `features`, `authority`).                                                                              |
 | `authority_map`  | object. Claim-type → authoritative artifact/rule, with each precedence edge citing its project rule or fallback (see [./authority-resolution.md](authority-resolution.md)). |

package/plugins/sp/skills/conflict-finding/references/remediation-routing.md

@@ -13,7 +13,8 @@ opt-in, gated workflow. This file is the SSOT for *when a write is allowed*, *wh
 
 The governing rule, carried through everything below: **no mutation in audit mode, and no automatic
 mutation merely because `--resolve` is present.** Every write requires (a) a presented repair set,
-(b) explicit operator confirmation, (c) a freshness revalidation of the supporting evidence, and
+(b) explicit operator confirmation (interactive, or the explicit `--auto` pre-approval of eligible
+items — §2.2a), (c) a freshness revalidation of the supporting evidence, and
 (d) dispatch through the artifact owner's verified harness surface. Ambiguity or partial failure is
 reported, never silently continued.
 
@@ -23,7 +24,7 @@ reported, never silently continued.
 |-----------|-----------|
 | Audit mode is read-only | Without `--resolve`, no source, corpus (task/feature), or numbered-document mutation of any kind. |
 | `--resolve` is not a write | It only *opens* the proposal → confirmation → owner-routed workflow. It never authorizes automatic repair. |
-| Confirmation precedes every write | No repair executes until the operator explicitly approves the specific proposed repair set. |
+| Confirmation precedes every write | No repair executes until the operator explicitly approves the specific proposed repair set — interactively, or by `--auto` pre-approval of its eligible subset (§2.2a). |
 | Freshness precedes mutation | The supporting evidence anchors are re-read and compared against the finding's fingerprint before any write. |
 | Owner surface, not raw edits | Each approved repair routes through the artifact's owner (Spur CLI, `sp:doc-evolve`, Spur dev lifecycle, Superskill lifecycle) — never a direct file write where an owner surface exists. |
 | Idempotent and partial-failure aware | Already-matching artifacts resolve without a write; one repair's failure neither marks others successful nor silently rolls forward. |
@@ -93,6 +94,23 @@ is:
 A declined or deferred repair is left **untouched** and reported as such; it is not re-attempted
 implicitly in the same run.
 
+### 2.2a `--auto` pre-approval
+
+`--auto` (only valid with `--resolve`) is the operator's explicit, up-front confirmation of the
+**eligible** subset of the repair set — it replaces the interactive pause for that subset only. The
+repair set is still presented (§2.1) before anything is applied. An item is eligible only when all
+hold:
+
+- `status` is `open` — never `needs-authority-decision` (authority is resolved, not ambiguous/missing);
+- `confidence` is `high`;
+- `repair_owner` resolves to a verified owner surface in §3 (no manual/unknown owner).
+
+Ineligible items are the HITL that remains: authority decisions and medium/low-confidence repairs
+**still pause** for the operator, exactly as without `--auto`. In a non-interactive run (no operator
+to answer), they are recorded `deferred` and left untouched. The remediation report marks each
+approved item `approved_by: auto` or `approved_by: operator`, so the audit trail distinguishes the two.
+`--auto` never skips freshness revalidation (§2.3), owner routing (§3), or partial-failure handling (§5).
+
 ### 2.3 Revalidate evidence freshness
 
 Between the audit and any write, the world may have changed. Immediately before dispatching each
@@ -245,6 +263,7 @@ These are the explicit boundaries for remediation. Each is a hard violation, not
 | Anti-pattern | Why it is prohibited |
 |--------------|----------------------|
 | **Automatic mutation merely because `--resolve` is present** | `--resolve` only opens the workflow; it never authorizes automatic repair. Confirmation + freshness + owner surface are all required. |
+| **`--auto` beyond its eligible subset** | `--auto` pre-approves only §2.2a-eligible items; applying an authority decision or a medium/low-confidence repair under it is a violation. |
 | **Changing correct authority for projection drift** | A stale projection is repaired against its governing contract. Correct authority only when defective and authorized; then update affected projections. |
 | **Broad cleanup outside confirmed findings** | Only the artifacts named by confirmed, freshness-checked findings are touched. No opportunistic refactors or doc "improvements" while repairing. |
 | **Ambiguity silently resolved** | Ambiguous/missing authority stops for an operator decision; it is never forced through a global ranking or a guessed owner. |
@@ -260,7 +279,7 @@ Before dispatching any write, confirm each of the following:
 
 - [ ] Audit mode performed **no** governed mutation; the report is a pure envelope.
 - [ ] `--resolve` was present, and the **repair set was presented** (keyed by finding ID + fingerprint).
-- [ ] The operator **explicitly confirmed** the specific selected repair set.
+- [ ] The operator **explicitly confirmed** the specific selected repair set, or `--auto` pre-approved only §2.2a-eligible items.
 - [ ] Evidence **freshness revalidated** per finding at dispatch; `stale-evidence` items returned to audit.
 - [ ] Each approved repair routed through its **owner surface** (§3), never a raw write where an owner exists.
 - [ ] **Idempotent** already-matching items marked `resolved` without a write.

package/plugins/sp/skills/fleet-join/SKILL.md

@@ -5,6 +5,8 @@ description: >-
   "join the fleet", "become a fleet guest", "pull fleet inbox work in this session", or when a
   session should receive fleet messages without being supervised. Runs `spur agent join`, then
   loops `spur agent wait --inbox`, and releases the lease with `spur agent leave`.
+metadata:
+  version: "1.0"
 ---
 # fleet-join — a live session as a fleet guest (G73, task 1081)
 

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.

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

@@ -285,6 +285,18 @@ spur feature sync H2 --folder docs/custom-tasks --json   # non-default tasks fol
   `{ 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