@gobing-ai/spur 0.4.15 → 0.4.17

package/plugins/sp/skills/spur-dev/references/execution-workflow.md

@@ -10,15 +10,17 @@ see_also:
 
 ```
 pick task (spur task list --json)
-  → interactive omit/inline: host driver reads task-pipeline.yaml and walks it in-session
+  → interactive omit/inline: spur workflow run task-pipeline.yaml with executor=host
   → explicit/headless executor: spur workflow run task-pipeline.yaml
   → on HITL pause: surface to operator → resume the selected driver
 ```
 
-The execution half runs a single task through the `task-pipeline.yaml` FSM. In an interactive
-omit/inline invocation, the skill's host driver interprets that YAML directly. Explicit executors
-and headless invocations use the workflow engine. Both surfaces preserve the same actions, guards,
-artifacts, HITL gates, and terminal states.
+The execution half runs a single task through the `task-pipeline.yaml` FSM, always on the workflow
+engine. In an interactive omit/inline invocation the engine runs with `executor=host`: it executes
+every deterministic action (shell, `command.gate`, `decide`) and every guard itself, and hands each
+model stage back to this session as a work item. Explicit executors and headless invocations run the
+model stages as subprocesses. Both surfaces share the same actions, guards, artifacts, decision
+rows, HITL gates and terminal states.
 
 > **Single-task vs batch.** This file covers the **single-task** execution half — one task through
 > `task-pipeline.yaml`. For **batch** execution (a set of tasks in dependency-correct order), see
@@ -32,11 +34,11 @@ This file owns **how operations sequence** in the pipeline. What each operation
 
 > **`/sp:dev-run` drives the pipeline — it is NEVER a pipeline step.** The command
 > `/sp:dev-run <wbs>` means "run this whole pipeline" (default `--mode full`). The pipeline's
-> internal stages call `/sp:dev-run --mode implement`, shell quality gate + optional
-> `/sp:dev-fixall`, `/sp:dev-review`, `/sp:dev-verify` — never `/sp:dev-run` in full mode.
+> internal stages call `/sp:dev-run --mode implement`, the typed quality gate + optional
+> `/sp:dev-fixall`, and `/sp:dev-review` — never `/sp:dev-run` in full mode.
 > Calling `/sp:dev-run --mode full` from inside the `implement` step would recurse into another
 > full pipeline run. The `implement` step is the **implement operation** (dev-operations.md §4);
-> the verify step is `sp:code-verification`.
+> requirement/AC certification happens inside `review` (D65 merged the former `verify` stage).
 
 ## The pipeline's internal stages
 
@@ -45,10 +47,11 @@ one thing and yields, so the **pipeline (not the agent) owns the loop**.
 
 | Stage | Operation | Defined in |
 | ------- | ----------- | ------------ |
-| `implement` | `/sp:dev-run --mode implement <wbs>` — write the code that satisfies the task; author `## Solution`. | [dev-operations.md §4 run](dev-operations.md) → `sp:code-implementation` |
-| `test` → (`test-fix` ↔ `test-recheck`) → `review` \| `failed` | **Project quality gate** (not `/sp:dev-unit`). Soft shell probe of `${vars.qualityGateCmd}` (default `spur self exec check`) — green path pays **one** full gate run. On FAIL: bounded `/sp:dev-fixall` loop (`qualityGateMaxFixAttempts`, default 2) with soft recheck; exhausted attempts route to pipeline `failed`. `/sp:dev-unit` remains **coverage gap-fill** (router C3/C5 / standalone). | [dev-operations.md §10 fixall](dev-operations.md); unit op still §1 |
-| `review` | `/sp:dev-review --tasks <wbs>` — SECUA-framework review of the diff. | [dev-operations.md §2 review](dev-operations.md) |
-| `verify` | `sp:code-verification` — requirements traceability + verdict. | [dev-operations.md §3 verify](dev-operations.md) |
+| `implement` | `/sp:dev-run --mode implement <wbs>` — write the code that satisfies the task; author `## Solution`. May pause through `escalate` (operator question). | [dev-operations.md §4 run](dev-operations.md) → `sp:code-implementation` |
+| `gate` | **Typed quality gate** (not `/sp:dev-unit`): `spur task gate <wbs> run\|recheck` over `${vars.qualityGateCmd}` (default `spur self exec check`) under the host-wide lock, with tree-hash receipt reuse. The first visit runs `run`; every visit after a remediation runs `recheck`. Also resolves the review lane (`task-triage`) and classifies a red gate (`failure-class`). | `spur task gate` ([tasks reference](../../spur-cli/references/tasks/verbs.md)) |
+| `remediate` | `/sp:dev-fixall "${vars.qualityGateCmd}" --gate-log … --findings …` — the bounded repair hop for a red gate **or** a fixable non-PASS review; re-enters `gate`. One shared counter (`qualityGateMaxFixAttempts`, default 2) bounds both lanes. `/sp:dev-unit` stays coverage gap-fill (router C3/C5 / standalone). | [dev-operations.md §10 fixall](dev-operations.md) |
+| `review` | `/sp:dev-review --tasks <wbs> --auto --focus <functional\|all>` — SECUA + requirement/AC traceability; `spur task verdict --from-answer` certifies the answer, `review-failure-class` classifies a non-PASS, then the approval decision point answers. | [dev-operations.md §2 review](dev-operations.md) |
+| `done` | Deterministic close: `spur task record` writes `## Testing` from the verdict, then `spur task update <wbs> done --no-lifecycle` runs the completion check. | [dev-operations.md §3 verify](dev-operations.md) (standalone re-certification) |
 
 Interactive omit/`inline` executes these model stages in the host session through the engine loop:
 the engine owns every guard and transition, the host performs each returned work item and records
@@ -144,7 +147,7 @@ Synchronous invocation (`--json` without `--async`) is acceptable **only** for s
 On the subprocess path, when `--agent <value>` is set (passed through from the thin wrapper), merge it into the vars as
 **both** `agent` and `implementAgent` (task 0483 R2):
 `--vars '{"wbs":"<wbs>","agent":"<value>","implementAgent":"<value>"}'`. The pipeline YAML reads
-`${vars.agent}` for review/verify/test-fix and `${vars.implementAgent}` for implement — setting
+`${vars.agent}` for remediate/review and `${vars.implementAgent}` for implement — setting
 both keys ensures the pinned executor reaches every hop. The full value-semantics contract (one
 rule, value table, objective triggers, and headless `inline` substitution (tier resolution + one warning) per ADR-087)
 lives in [cross-cutting.md](cross-cutting.md#inline-default-execution-surface) — the SSOT.
@@ -161,34 +164,39 @@ pipeline (bug-742).
 The pipeline (`kind: state-machine`) runs the work loop:
 
 ```
-precheck → implement → test [→ test-fix → test-recheck] → review → approve(HITL) → verify → record → done
+precheck → implement[⇄ escalate] → gate[⇄ remediate] → review → done | failed
 ```
 
-Two branches reach the bounded repair hop, not one (session finding after 1088):
+Two branches reach the bounded `remediate` hop, and each is routed by a recorded decision row, not
+by this session's judgment:
 
-- `test`/`test-recheck` FAIL → `test-fail-triage` (0943's failure-class router) → `test-fix`;
-- `review` without a `Verdict: PASS` in its answer → `review-fail-triage` (the review-side twin) →
-  `test-fix`, bounded by the SAME `qualityGateMaxFixAttempts` counter. A FAIL review therefore has
-  an on-graph, bounded path to remediation instead of dead-ending the run, and the fix re-enters
-  quality → review → verify on a freshly captured proof digest.
+- a red `gate` → `failure-class` (`fix` → `remediate`, `stop` → `failed`);
+- a review that did not certify PASS → `review-failure-class` (`fix` → `remediate`, `stop` →
+  `failed`), bounded by the SAME `qualityGateMaxFixAttempts` counter. The repair re-enters
+  `gate` (recheck) → `review` on the remediated tree.
+
+Every decision point, its fallback and its consumer are listed in
+[decision-points.md](decision-points.md); read the rows it names instead of re-judging them.
 
 The completion gate reads deterministic evidence only: the review stage's **verdict artifact** (`.spur/run/<wbs>-verdict.json`, derived by `spur task verdict --from-answer`) and the **tree-hash gate receipt** (`.spur/run/<wbs>-check-receipt.json`, reused while the tree is unchanged). The ADR-071 proof chain this paragraph used to describe — proof digests, `verify → record`, review-inside-the-bracket — was deleted by the D65 pipeline rewrite; `record` now runs inside `done`'s onEnter and `verify` merged into `review`. Two grades are read, and only as cross-checks against the answer's own rows: the review answer states one `Confidence: HIGH|MEDIUM|LOW` line (ADR-141) and the review gate recomputes it from the finding dispositions, rejecting a disagreement. Nothing grades the *verifier's* opinion: an open P1–P3 finding blocks `done` on its own, and what protects a hand-driven `task update <wbs> done` is unchanged — the gate must show a PASS receipt for this tree and a recorded review artifact.
 
 Agentic steps use the pure slash inputs declared by each YAML `agent.run` action (ADR-043). The
 workflow engine dispatches them; the interactive driver invokes their backing skills in-session.
-The `test` hop is primarily
-**deterministic shell** (quality gate); only the optional `test-fix` hop is agentic
+The `gate` state is
+**deterministic** (quality gate plus decision points); only the optional `remediate` hop is agentic
 (`/sp:dev-fixall`). The skill monitors the run:
 
-- **On HITL pause** (`approve` state): surface the review output to the operator. On the subprocess
-  path use `spur workflow continue <run-id> --yes`; on the inline path retain the current state and
-  resume the host driver with the operator's answer.
+- **On HITL pause** (`escalate`, or the approval decision point inside `review`): surface the
+  question, or the review answer and verdict, to the operator. Resume with `spur workflow continue
+  <run-id> --answer-text <answer>` (or `--yes` for the approval). The approval answer lands in
+  `.spur/run/<wbs>-approval.status`; a `no`/`cancel` ends the run `failed` with terminal reason
+  `cancelled`, a recorded denial rather than a check failure.
 - **On guard failure** (`precheck`): the task's check findings block progress — fix the
   task first.
-- **On completion** (`done`): the pipeline's `record` step has already written the verdict
+- **On completion** (`done`): the `done` state's onEnter has already written the verdict
   transcript into the task's `## Testing` via `spur task record <wbs>` (matrix-compliant tables;
   `## Review` was authored by the review step and is only backfilled bare, never overwritten —
-  F92 0593 R1; never transitions to `done` — the gate stays in the workflow).
+  F92 0593 R1) and moved the task to `done` through the verb's own completion check.
 
 ## `--next` chain — advance to the next step
 
@@ -400,6 +408,10 @@ After a completed task, decide next action:
 
 ## Skipping HITL
 
-Passing `--vars '{"profile":"auto"}'` to `spur workflow run` (a var choice, not a YAML fork) skips
-the `approve` HITL gate — use for low-risk, well-understood tasks where operator review adds no value.
+Passing `--vars '{"profile":"auto"}'` to `spur workflow run` (a var choice, not a YAML fork) makes the
+approval decision point answer itself instead of prompting: its evidence binding answers from the
+recorded review evidence, through the `gate-evidence` decision when `workflows.hitlDecisionMaker`
+is on. It is not a bypass — an auto run still ends `failed`/`cancelled` when the maker answers
+`no`; a deferred answer (switch off, no reachable maker, or insufficient evidence) is not a denial. Use it for low-risk,
+well-understood tasks where operator review adds no value.
 (Combine with `wbs` in one object: `--vars '{"wbs":"0042","profile":"auto"}'`.)

package/plugins/sp/skills/spur-dev/references/execution-worktree-landing.md

@@ -118,6 +118,39 @@ WT_PATH="$(cd "../<worktree-dir>" && pwd)"   # hoisted: needed by WT-4a AND WT-4
 # task's creation), so a manual DB edit is never required:
 spur workflow persist-out --from "$WT_PATH" "${TASK_FILE_ARGS[@]}" \
   || { echo "halt: worktree run-record persist-out failed - worktree retained (WT-5)" >&2; write_marker retained; exit 1; }
+
+**Two refusals this step raises, and how to clear each without touching foreign evidence.**
+
+1. **`durable evidence conflicts: <name>`** — the worktree owns a receipt (`*-feature-verification.json`)
+   whose canonical target already holds *different* bytes. The conflict policy is fail-closed on
+   purpose: overwriting would destroy the invoking tree's copy. When the worktree receipt is the
+   newer, authoritative one (e.g. the feature transition this batch performed), archive the
+   superseded copy out of the canonical path and re-run — never delete it, and never copy the
+   worktree file in with `cp`:
+
+   ```bash
+   mkdir -p .spur/memory/evidence/superseded
+   mv ".spur/memory/evidence/<name>" ".spur/memory/evidence/superseded/<name>.<iso-timestamp>.json"
+   # then re-run the persist-out command above; the newer receipt lands at the canonical path
+   ```
+
+   When the *invoking* copy is the newer one, do nothing: `persist-check` reports it as foreign and
+   divergent, which is not a blocker.
+2. **`persist-check … BLOCKED n unforwarded durable verdict/receipt`** — the worktree holds
+   `*-verdict.json` files for tasks this batch did not run, because **WT-2 stages the invoking tree's
+   evidence into the worktree before the first task**. Forwarding them back (`--task-file`) is wrong
+   when the invoking tree's copies are newer: persist-out then refuses with `cited run evidence …
+   diverges`, and it would write stale bytes over fresh ones. Compare mtimes and delete the staged
+   worktree copies, then re-run `persist-check` with only this batch's `--task-file` arguments:
+
+   ```bash
+   for w in <staged-wbs>; do
+     [ .spur/run/$w-verdict.json -nt "$WT_PATH/.spur/run/$w-verdict.json" ] \
+       && rm -f "$WT_PATH/.spur/run/$w-verdict.json"
+   done
+   ```
+
+   Both steps are reads plus a delete of a *copy* whose source still holds it — no evidence is lost.
 #
 # WT-4b — bounded CWD-holder cleanup (task 0720 R1). $WT_PATH above is the EXACT
 # absolute worktree path; a relative path or a stale entry matches the wrong processes.

package/plugins/sp/skills/spur-dev/references/flag-glossary.md

@@ -151,7 +151,7 @@ halt-on-first-failure. Never silently retried; the failure is still reported.
 **Applies to:** `/sp-dev-runall --mode parallel`, and `--mode auto` when it resolves to parallel.
 **Default:** off — every task pipeline runs its own FULL project gate inside its worktree.
 
-With `--defer-gate`, each task's `test` / `test-recheck` hop runs the **light tier** (changed-scope
+With `--defer-gate`, each task's `gate` state (every visit) runs the **light tier** (changed-scope
 format, per-workspace typecheck, related tests) and writes `DEFERRED` — never `PASS` — to
 `.spur/run/<wbs>-test-gate.status`. The orchestrator then owes **one integrated full gate** on the
 base ref over the merged slices, **before** the deferred feature sync; on FAIL the batch verdict is
@@ -164,8 +164,8 @@ Two properties are load-bearing and are asserted structurally:
   fails inside its own worktree instead of at the end of the batch (the reason ADR-124 rejected an
   unconditional single end-of-run gate).
 - **The full tier is still the only `PASS` writer.** Only the integrated run can claim a green
-  project gate; the per-task token is `DEFERRED`, and the `test → triage` /
-  `test-recheck → triage` guards accept it only while `deferQualityGate = "true"`.
+  project gate; the per-task token is `DEFERRED`, and the deferred `gate → review`
+  guard accepts it only while `deferQualityGate = "true"`.
 
 `--defer-gate` with `--mode sequential` (or omitted `--mode`) is rejected — the flag exists to move
 one full gate from N worktrees to the one place the integrated tree exists. Under `--mode auto` it
@@ -219,8 +219,8 @@ or irreversible HITL gates.
 
 Scope the operation to all tasks under a feature id (`^[A-Z][1-9]*$`). On feature-advancing
 commands (`dev-wrapall`) it also advances the feature through legal lifecycle edges with guards
-honored. On `dev-review` it takes a comma list (`--feature <id>[,<id>]`) — sugar for the union of
-the `feature:<id>` sets, resolved once and frozen.
+honored. On `dev-review` and `dev-find-conflict` it takes a comma list (`--feature <id>[,<id>]`) —
+sugar for the union of the `feature:<id>` sets, resolved once and frozen.
 
 ### `--check <cmd>` — validation command for iterate-and-check loops
 
@@ -250,9 +250,10 @@ all dimensions.
 **Anchor:** `#flag-scope`.
 
 Limit the operation to a file or directory path (`dev-arch`, `dev-debug`, `dev-fixall`,
-`dev-gitmsg`, `dev-gtd`, `dev-refactor`, `dev-review`, `dev-simplify`) to bound the working set.
-On `dev-review` it takes a comma list of paths — normalized, nested and duplicate paths merged,
-one advisory sub-review per surviving path.
+`dev-find-conflict`, `dev-gitmsg`, `dev-gtd`, `dev-refactor`, `dev-review`, `dev-simplify`) to
+bound the working set. On `dev-review` and `dev-find-conflict` it takes a comma list of paths —
+normalized, nested and duplicate paths merged; `dev-review` runs one advisory sub-review per
+surviving path, `dev-find-conflict` seeds one audit with all of them.
 
 ### `--all` — widen the operation to everything in its domain
 
@@ -275,9 +276,9 @@ is the contract; divergence between `--dry-run` and the real run is a bug.
 
 **Anchor:** `#flag-tasks`.
 
-Batch operation (`dev-refineall`, `dev-review`, `dev-runall`, `dev-verifyall`). An
+Batch operation (`dev-find-conflict`, `dev-refineall`, `dev-review`, `dev-runall`, `dev-verifyall`). An
 explicit selector — WBS list, status pseudo-list (`todo`, `wip`), `feature:<id>`, or `ready` —
-resolving to the set the batch runs over. On `dev-review` the selector is restricted to the
+resolving to the set the batch runs over. On `dev-review` and `dev-find-conflict` the selector is restricted to the
 review-safe forms: comma WBS list and `feature:<id>` — status pseudo-lists and `ready` are
 rejected (they select work to do, not work to review). Required on `dev-runall` and
 `dev-verifyall`, where `--feature` is an optional restrictor. On `dev-refineall` it is instead

package/plugins/sp/skills/spur-dev/references/gate-checklists.md

@@ -98,9 +98,10 @@ Entered before `task-pipeline.yaml` `review` state dispatches `sp:code-verificat
 
 ## verify gate
 
-Entered before `task-pipeline.yaml` `verify` state produces a task verdict.
+Entered before the `task-pipeline.yaml` `review` state certifies a task verdict (D65 merged the
+former `verify` state into `review`; standalone `/sp:dev-verify` applies the same list).
 
-- [ ] The verify answer file (`.spur/run/<wbs>-verify-answer.txt`) is lint-clean before
+- [ ] The answer file (`.spur/run/<runId>-review-answer.txt` in the pipeline) is lint-clean before
       verdict derivation: `spur task verdict <wbs> --from-answer …` (0726 R3) lints the
       file first and rejects missing/duplicate/unknown R IDs, AC identities that are not an
       exact task checklist label or linked-feature scenario title, invalid status/evidence-type

package/plugins/sp/skills/spur-dev/references/glossary.md

@@ -80,9 +80,18 @@ Avoid: *prompt* (reserved for LLM input text), *interrupt* (implies an exception
 pause point).
 
 **DecisionMaker** — optional provider-backed responder for executed `hitl.confirm`/`hitl.select`
-actions (ADR-123), enabled via `workflows.hitlDecisionMaker: true` and `TYPESAFE_API_KEY`.
-Evidence answers clear the answer variable and record `statusVar: accepted/deferred`; unresolved
-cases defer or delegate to the human. Offline readiness: `spur self status`.
+actions (ADR-123), enabled via `workflows.hitlDecisionMaker: true`. Evidence-mode confirm gates
+answer through the catalog decision `gate-evidence`, so the effective maker (and its credentials)
+comes from `decisions.*` config. Evidence answers clear the answer variable and record
+`statusVar: accepted/deferred`; unresolved cases defer or delegate to the human. Readiness:
+`spur decision status --probe`.
+
+**decision point** — a recorded, closed-vocabulary judgment inside a workflow: a `decide` action
+(or an evidence-mode HITL gate) that names a catalog decision id and writes a schemaVersion-1
+`.decision` row whose `value` the next guard reads. It always has a deterministic fallback, so it
+works with no model. Inventory: [decision-points.md](decision-points.md).
+Avoid: *decision brief* (the operator-facing HITL summary format in
+[decision-brief.md](decision-brief.md) — prose for a human, not a catalog answer).
 
 **WBS** (work-breakdown-structure ID) — the four-digit task identifier (e.g. `0187`) that
 names a task file and its position in the corpus. WBS IDs are assigned once and never reused.

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

@@ -58,6 +58,7 @@ record saves the returned table under `docs/reports/`; the doctor creates no art
 | rule | `spur rule trace --json`, `spur rule validate` |
 | workflow | `spur workflow validate --json` (findings by `level`), `spur workflow profile <workflow> --json` |
 | agent spec | `spur agent list --specs --json` |
+| decision | `spur decision status --json`, `spur decision status --reliability --json`, `spur decision show <id> --json` |
 | history | A `sp:history-anatomy` report ([../history-anatomy/SKILL.md](../history-anatomy/SKILL.md)), never raw history records |
 | plan/design Markdown | The file itself, the project constitution, the relevant spur-dev template, and inbound index/links; no new CLI needed |
 
@@ -135,6 +136,28 @@ optimization**, and the change comes from the §10 table:
 - A proposal that changes a shared workflow goes through §7 of the composition ladder
   ([spur-composer](../spur-composer/SKILL.md)), including its recorded operator consent.
 
+## Decision flags
+
+Decision evidence is `spur decision status --json` (catalog and per-maker readiness) and
+`spur decision status --reliability [--since <iso>] --json` (per decision × maker). Each flag is a
+predicate over those fields, so compute it with `jq` and never estimate from prose. Each flag becomes
+one row with action class **workflow optimization**. A catalog or config change routes through
+`sp:spur-composer` and the decision lifecycle
+([decision/lifecycle.md](../spur-cli/references/decision/lifecycle.md)).
+
+| Evidence | Flag | Proposed change |
+| --- | --- | --- |
+| `status`: `loadErrors[]` or `duplicateIds[]` non-empty | `catalog-error` | Fix the named catalog file; a layer collision is renamed, not suppressed |
+| `status` `makers[]`: `evidence.recorded > 0` and `evidence.accepted == 0` | `maker-never-accepted` | Re-point `decisions.makers.<id>` for the decisions in `serves`, after `--probe` confirms the maker answers |
+| `status` `makers[]`: `configuredBy` non-empty and `evidence.recorded == 0` | `maker-unrecorded` | Run `spur decision status --probe`; propose only when the probe fails |
+| `--reliability` `groups[]`: `samples >= 10` and `acceptedRate < 0.5` | `low-accept-rate` | Read the dominant `fallbacks` reason: `low-confidence` → tune criteria or `minConfidence`, or change the maker; `no-backend` / errors → maker config; invalid answers → the criteria vocabulary |
+| A workflow step's shell command (not a YAML comment) runs `spur decision run` — read it from `spur workflow show <workflow> --json` | `shell-decision-run` | Convert to a typed `decide` step plus a projection. The shell call ignores both workflow switches |
+
+- `samples < 10` is not evidence: the row says so instead of raising `low-accept-rate`.
+- A run's rows under `.spur/run/*.decision` explain one route; the reliability report is the only
+  rate evidence. Never compute a rate from row files.
+- A decision whose `source: default` rows are expected (switch off, `reason: disabled`) is a no-op.
+
 ## Reflection map over history findings
 
 For each history-anatomy finding (`key`, `category`, `trend`, `ownerSurface`), assign **exactly