@gobing-ai/spur 0.3.99 → 0.4.1

package/config/workflows/task-pipeline.yaml

@@ -19,6 +19,21 @@
 # done guard closed, and re-records Testing before the failed edge); done settles
 # deferrals; failed renders the recovery report. No new state, edge, or model query.
 #
+# Confidence gate (session finding after 1088, task 1068 follow-up): the verify answer has
+# carried a `Confidence: HIGH|MEDIUM|LOW` line since 1068, and nothing read it — a PASS at
+# LOW confidence certified exactly like HIGH. The verify stamp now records a `confidence`
+# check row, and BOTH completion guards (verify → record, record → done) refuse a LOW (or
+# absent) level unless the run was launched with `--vars '{"ackLowConfidence":"true"}'`.
+# The acknowledgement is an operator decision, not a model one: it is the only way to
+# certify a verdict the verifier itself would not stand behind.
+#
+# Review-failure routing (session finding after 1088): `review` had no outgoing edge for a
+# FAIL verdict, so a failing review could only be remediated by driving the graph by hand
+# (re-entering `test` and hand-emitting rows). The review stage now derives
+# `.spur/run/<wbs>-review.status` from its own answer file (fail-closed to FAIL), and a FAIL
+# routes through `review-fail-triage` — the review-side twin of `test-fail-triage` (0943) —
+# into the SAME bounded fix budget, so remediation stays on-graph and bounded.
+#
 # Vars (passed as a JSON object via `--vars`):
 #   wbs                       — task WBS (required)
 #   profile                   — "auto" skips HITL approve (R4)
@@ -36,7 +51,26 @@ kind: state-machine
 name: task-pipeline
 # 0772 R2: explicit identity tag. Set only after the proof failure-path tests
 # passed; the engine treats unversioned external definitions as supported.
-version: "3"
+# v4 (session finding after 1088): the completion gate reads the verifier's confidence level and
+# the graph routes a non-PASS review into bounded remediation — both are contract changes, so the
+# identity moves with them.
+# v5 (task 1077's inline run, 2026-10-06): the verify verdict action is explicitly `onError:
+# continue`. `task verdict` exits non-zero on any non-PASS verdict BY DESIGN (1003 R2) — that is
+# data for the verify guards, not a state failure. Under the engine's default 'fail' policy
+# (`resolveOnErrorPolicy: action ?? workflowDefault ?? runOption ?? 'fail'`) the state sequence
+# halted on that exit code and `lifecycle.fail('verify')` finalized the run before any transition
+# guard was evaluated, which made the declared `verify → test-fix` "repairable non-PASS" lane
+# UNREACHABLE: a non-PASS verify could only end the run failed. `test-fix` also gained the
+# review-lane evidence projection (see its onEnter) so the repair hop is not fed an empty findings
+# list when the failing hop was `review-fail-triage` rather than the quality gate.
+# v6 (task 1134 run, 2026-10-09): the `confidence` check row now encodes the SAME policy as the two
+# completion guards instead of a stricter one of its own. It warned for every level below HIGH, so a
+# MEDIUM certification was admitted by both guards but recomputed as PARTIAL by the CLI done gate —
+# the artifact was self-inconsistent and `done` was refused with no named level to act on. The row
+# now warns only for an unacknowledged LOW (or absent) level, which is exactly what the guards
+# refuse; `packages/app/tests/workflow/task-pipeline-proof-chain.test.ts` pins the agreement for
+# HIGH/MEDIUM/LOW/absent × ack.
+version: "6"
 description: "Standard task pipeline: precheck → implement → quality-gate (test/fix/recheck) → review → approve → verify → record → done"
 # Task entity lifecycle (owned by task-lifecycle.yaml):
 #   normal: backlog → todo → wip → testing → done
@@ -89,11 +123,15 @@ vars:
     # run unbounded — if a hop still hits this wall, STOP and record it.
     stepTimeoutMs: "1800000"
     # Timeout for the `implement` step specifically (R2a). Implementation is the
-    # heaviest agent.run step (full read/write/test-probe loop) and has timed out
-    # at the 600s default in five consecutive dogfood runs (bugs 742/744/746/748),
-    # a 100% failure rate at that budget. 30 min gives real headroom; STOP and
-    # record honestly rather than raising it further without operator sign-off.
-    implementTimeoutMs: "1800000"
+    # heaviest agent.run step (full read/write/test-probe loop); the old 600s default
+    # failed five consecutive dogfood runs (bugs 742/744/746/748). Default is 45 min
+    # (task 1108): it governs subprocess surfaces (`spur workflow run`, parallel,
+    # headless); inline hosts receive it only when their dispatch tool accepts a
+    # timeout (inline-pipeline-driver.md § Timeout boundary). 45 min is a reasoned
+    # default, not a proven bound — in P1 one implement still hit 45 min and resumed
+    # (docs/reports/i31/1107-runall-p1-pilot.md § Timeout attribution).
+    # Override per run: `--vars '{"implementTimeoutMs":"3600000"}'`.
+    implementTimeoutMs: "2700000"
     # Answer captured by the approve gate's hitl.confirm (R1): "yes" | "no" | "cancel".
     # Empty by default; only meaningful once the approve state has been entered.
     __hitlAnswer: ""
@@ -101,13 +139,16 @@ vars:
     # default; set by `spur workflow continue --answer-text` after the pause and read
     # by the escalate→implement / escalate→failed guards. Non-empty = answered.
     __hitlInput: ""
-    # Proof-state bracket (task 0612, ADR-071; restructured by task 0703). `proofDigest` is the
-    # canonical capture taken at quality-gate ENTRY — immediately before the evidence-producing
-    # final chain (quality → review → verify) — and re-captured at `test-recheck` when bounded
-    # remediation mutated the tree, so every evidence stage names one fresh digest (R2/R4).
-    # `proofDigestNow` is the live re-capture compared against `proofDigest` at verify entry and
-    # immediately before `record`; a mismatch means a proof input changed after evidence was
-    # established, so the run routes to `failed` instead of crossing the completion boundary (R5).
+    # Proof-state bracket (task 0612, ADR-071; restructured by task 0703; review joins by task 1135).
+    # `proofDigest` is the canonical capture taken at quality-gate ENTRY — immediately before the
+    # evidence-producing final chain (quality → review → verify) — and re-captured at `test-recheck`
+    # when bounded remediation mutated the tree, so every evidence stage names one fresh digest
+    # (R2/R4). `proofDigestNow` is the live re-capture compared against `proofDigest` at review,
+    # verify and record entry; a mismatch means a proof input changed after evidence was established,
+    # so the run routes to `failed` instead of spending a review dispatch or crossing the completion
+    # boundary (R5). Task 1135 adds the review-entry compare and the gate-entry tree snapshot
+    # (`.spur/run/<run-id>-gate-paths.txt`, same exclusions as the git-tree half) so a mismatch also
+    # names the drifted paths.
     # `taskSpecPath` carries the task file path because `docs/tasks*` is excluded from the digest's
     # git-tree half — spec content is folded in explicitly or a task-file edit would go undetected.
     # The fingerprint scopes task content to the proof-input sections only (Background, Requirements,
@@ -128,6 +169,11 @@ vars:
     # with the same package-manager surface (this monorepo is Bun-only):
     # `--vars '{"qualityGateCmd":"bun run lint && bun run test"}'`. Soft probe, hard recheck,
     # and the fixall slash input all use this same var so the command stays single-sourced.
+    # INVARIANT (ADR-124, clarified 2026-10-07 by task 1111 R5): only the FULL tier writes PASS.
+    # Under the opt-in `deferQualityGate` policy the per-task token is DEFERRED (light tier) and
+    # the "review runs only after a green full gate" invariant moves to BATCH scope — nothing is
+    # reported PASS without the integrated full gate on the base ref. Default "false" = per-task
+    # full gate, unchanged.
     # TRUSTED CONFIG ONLY — this string is executed via `sh -c` (see test/test-recheck). Never
     # interpolate untrusted operator/LLM input into qualityGateCmd (task 0436 SECUA residual).
     # NO `format` PREFIX: `implement` already ran `$formatCmd` on its way out, and `test`
@@ -149,6 +195,14 @@ vars:
     # Escalation counter: .spur/run/<wbs>-escalation-count. Default 2 = two answered
     # questions; a third pause routes to failed with a report note.
     maxEscalations: "2"
+    # Operator acknowledgement of a LOW-confidence certification (session finding after 1088).
+    # The verify answer's `Confidence:` line is captured into the verdict artifact; a LOW (or
+    # absent) level fails the completion guards unless this is "true", because a PASS the
+    # verifier would not stand behind is an operator risk decision, not a mechanical one.
+    # Set per run: `--vars '{"ackLowConfidence":"true"}'` (and export it on the inline path).
+    # Deliberately NOT settable from the task file or the verifier's own answer: the point is
+    # that a second party, not the producer, accepts the residual uncertainty.
+    ackLowConfidence: ""
     # Runtime-written, 0933: the escalate hop's file.read.into-var fills this from
     # .spur/run/<wbs>-question.md; the hitl.input prompt below references it. Declared
     # here (empty) so the static var-reference validator sees the template source.
@@ -169,6 +223,14 @@ vars:
     # (default) = on; set to "off" to bypass:
     # `--vars '{"implementScopeGuard":"off"}'`.
     implementScopeGuard: ""
+    # 1111 R1: opt-in parallel-batch gate policy. When "true", `test` / `test-recheck` run the
+    # LIGHT tier for per-task early feedback and write `DEFERRED` (light PASS) or `FAIL` to
+    # `.spur/run/<wbs>-test-gate.status` — never `PASS`, because that token means the full
+    # project gate ran green on this tree. The batch orchestrator owes ONE integrated full gate
+    # on the base ref over the merged slices (1111 R3). Default "false" = unchanged behavior,
+    # and a stray `DEFERRED` file fails the guards. Sequential/inline runs never set it:
+    # `--defer-gate` requires `--mode parallel`.
+    deferQualityGate: "false"
     # 0931 R5: parallel batches defer the per-task feature sync so a task branch never
     # touches feature files or docs/features/INDEX.md. When "true", the record step's
     # post-record shell appends a deferral note and skips the sync; the parallel batch
@@ -178,6 +240,10 @@ vars:
 
 states:
     - id: precheck
+      display:
+          phase: implement
+          phaseTitle: Implement
+          title: Check task readiness
       description: >
           Fast deterministic task readiness and size checks. Failures route to the
           `failed` terminal state (not a raw lifecycle abort mid-enter).
@@ -221,6 +287,10 @@ states:
                     reviewer: "${vars.agent}"
 
     - id: implement
+      display:
+          phase: implement
+          phaseTitle: Implement
+          title: Implement
       description: >
           Run agent-driven implementation via /sp:dev-run --mode implement, THEN move the
           task to `wip` via the normal verb. The lifecycle transition fires AFTER the
@@ -252,6 +322,10 @@ states:
             options:
                 agent: ${vars.implementAgent}
                 # Pure slash command only (ADR-043). Anti-recursion / implement discipline
+                # The worker's brief is OWNED BY the skill, not restated here (task 1110 R3):
+                # see `plugins/sp/skills/code-implementation/SKILL.md` (targeted-probe scope
+                # § Implement scope, dependency-aware § Changed-path targeted checks, Solution
+                # anchor form in § Red Flags). The YAML only names the entry command.
                 # Declared Layer-1 role (0538 R2/0710 R7): routing reason; no executor pin — role routing feeds the distinctness gate.
                 role: coder
                 # B7 R3/R6 (0894): coder stages reuse the role session — the test-fix hop
@@ -315,6 +389,17 @@ states:
           - kind: shell
             options:
                 command: "$formatCmd ; exit 0"
+          # 1109 R3: qualify this task's unique basename anchors to repo-relative paths.
+          # Placement is load-bearing: it runs AFTER implement's mutations (and the format
+          # above) but BEFORE the `test` stage's `proof.fingerprint` capture, so a rewrite in
+          # a digest section cannot invalidate the proof. `--wbs` scopes the pass to this
+          # task's resolved file — the unscoped form rewrites ~119 unrelated task files.
+          # Non-fatal (`; exit 0`): the done gate still reports anything left, and this step
+          # deliberately does NOT address line drift or `L4.anchor-subject-mismatch`
+          # (those need the implementer to re-anchor). Scope contract: task 1109 R5.
+          - kind: shell
+            options:
+                command: "$spurBin task migrate-anchors --wbs $wbs --json ; exit 0"
 
     # ── escalate hop (operator-question pause, 0933) ──────────────────────────
     # The implement agent paused on an operator question: it wrote
@@ -328,6 +413,11 @@ states:
     # the escalate→implement guard so a stale question can never re-trigger the hop
     # after the answered attempt.
     - id: escalate
+      display:
+          phase: implement
+          phaseTitle: Implement
+          title: Ask operator
+          show: on-entry
       description: >-
           Operator-question pause (0933): the implement agent asked a question
           headlessly; surface it to the operator and resume implement with the answer.
@@ -361,6 +451,10 @@ states:
     #   test-fix     — increment attempt + pure slash /sp:dev-fixall (≤ max attempts)
     #   test-recheck — soft recheck → review | test-fix | failed (never silent lifecycle abort)
     - id: test
+      display:
+          phase: test
+          phaseTitle: Test
+          title: Run quality gate
       description: >
           Proof-chain entry + soft quality-gate probe (single logical gate on the green path; bounded retries only
           for SQLite lock contention). Capture of the canonical proof-input digest happens HERE — before any
@@ -405,6 +499,12 @@ states:
           # R2 (0703, ADR-071): THE canonical proof capture. Placement is load-bearing: immediately before
           # the final evidence chain, after every implement mutation (including the post-implement format).
           # Capture-only here; `record` compares. A remediation pass re-captures at `test-recheck` (R4).
+          # 1135 R5: snapshot the non-corpus tree state FIRST, so a later proof mismatch names the
+          # drifted paths (not only the D1/D2 pair). Same exclusions as the digest's git-tree half.
+          - kind: shell
+            options:
+                command: >-
+                    mkdir -p .spur/run; { git status --porcelain=v1 -uall -- . ':(exclude)docs/tasks*' ':(exclude)docs/features*'; git diff --name-only HEAD -- . ':(exclude)docs/tasks*' ':(exclude)docs/features*'; } > ".spur/run/$__runId-gate-paths.txt" 2>/dev/null; exit 0
           - kind: proof.fingerprint
             options:
                 var: proofDigest
@@ -414,9 +514,14 @@ states:
           - kind: shell
             options:
                 command: >-
-                    eval "$(jq -r 'if .mode=="source-repo" then "S="+@sh"\(.dir)/quality-gate.ts"+" RUNNER=bun" elif .mode=="installed" then "S="+@sh"\(.dir)/quality-gate.mjs"+" RUNNER=node" else empty end' ".spur/run/$__runId-script-root.json" 2>/dev/null)"; if [ -f "$S" ]; then "$RUNNER" "$S" run; else echo "quality gate failed closed — quality-gate script not found — run 'superskill install sp --marketplace gobing-ai/spur'" >&2; printf 'FAIL\n' > ".spur/run/$wbs-test-gate.status"; fi; exit 0
+                    eval "$(jq -r 'if .mode=="source-repo" then "S="+@sh"\(.dir)/quality-gate.ts"+" RUNNER=bun" elif .mode=="installed" then "S="+@sh"\(.dir)/quality-gate.mjs"+" RUNNER=node" else empty end' ".spur/run/$__runId-script-root.json" 2>/dev/null)"; M=run; [ "$deferQualityGate" = "true" ] && M=deferred; if [ -f "$S" ]; then "$RUNNER" "$S" "$M"; else echo "quality gate failed closed — quality-gate script not found — run 'superskill install sp --marketplace gobing-ai/spur'" >&2; printf 'FAIL\n' > ".spur/run/$wbs-test-gate.status"; fi; exit 0
 
     - id: test-fix
+      display:
+          phase: test
+          phaseTitle: Test
+          title: Fix failures
+          show: on-entry
       description: >
           Bounded auto-fix hop when the quality gate is red OR final verification returned a
           repairable non-PASS (task 0703 R4: remediation never happens inside verify — it loops
@@ -438,6 +543,17 @@ states:
             options:
                 command: >-
                     printf '%s\n' "$(( $(cat ".spur/run/$wbs-test-fix-attempt" 2>/dev/null || echo 0) + 1 ))" > ".spur/run/$wbs-test-fix-attempt"; [ -f ".spur/run/$wbs-verdict.json" ] && echo '--- verify verdict (remediation input, task 0703 R4) ---' >> ".spur/run/$wbs-test-gate.log" && cat ".spur/run/$wbs-verdict.json" >> ".spur/run/$wbs-test-gate.log"; [ -f ".spur/run/$wbs-residuals.json" ] && echo '--- residual artifact (F96 fix targets; deferrals go to residual-deferrals.json, P3/markers only) ---' >> ".spur/run/$wbs-test-gate.log" && cat ".spur/run/$wbs-residuals.json" >> ".spur/run/$wbs-test-gate.log"; exit 0
+          # Review-lane input (v5, task 1077 run): `review-fail-triage` routes a non-PASS review
+          # into this same bounded repair hop, but it stages no review evidence — the fixer then
+          # received a GREEN gate log and an empty findings list, so the review finding it exists
+          # to repair was invisible to it. Project the reviewer's answer into the same log the
+          # other lanes use, and only on the review lane (the decision file exists only after
+          # `review-fail-triage`). Own action, not an append to the one above: ADR-115's 800-char
+          # shell cap is already 602 chars there.
+          - kind: shell
+            options:
+                command: >-
+                    [ -f ".spur/run/$wbs-review-failure-class.decision" ] && [ -f ".spur/run/$__runId-review-answer.txt" ] && echo '--- review verdict (remediation input, review lane) ---' >> ".spur/run/$wbs-test-gate.log" && cat ".spur/run/$__runId-review-answer.txt" >> ".spur/run/$wbs-test-gate.log"; exit 0
           # R3 (0482): project the extracted gate anchors into a var so the dispatch input
           # can NAME the failing file:line, not merely point at a log. A vars template cannot
           # run a shell, so the read is an action, not an inline `$(cat ...)` substitution.
@@ -469,6 +585,11 @@ states:
                     processSpawn: available
 
     - id: test-recheck
+      display:
+          phase: test
+          phaseTitle: Test
+          title: Re-run quality gate
+          show: on-entry
       description: >
           Soft recheck after fixall with bounded SQLite-lock retry. Writes PASS|FAIL (always exit 0). Transitions
           branch to `triage` (PASS — the 0943 lane router), `test-fail-triage` (FAIL — the 0943
@@ -478,6 +599,12 @@ states:
           # R4 (0703, ADR-071): bounded remediation mutated the tree by design, so the fresh evidence
           # chain (recheck gate → review → verify) must start from a NEWLY captured digest. Capture-only;
           # the guards and `record` compare against this value.
+          # 1135 R5: re-snapshot the tree state after the remediation, so the refresh does not compare
+          # against a pre-remediation snapshot (a legitimate test-fix edit must not read as drift).
+          - kind: shell
+            options:
+                command: >-
+                    mkdir -p .spur/run; { git status --porcelain=v1 -uall -- . ':(exclude)docs/tasks*' ':(exclude)docs/features*'; git diff --name-only HEAD -- . ':(exclude)docs/tasks*' ':(exclude)docs/features*'; } > ".spur/run/$__runId-gate-paths.txt" 2>/dev/null; exit 0
           - kind: proof.fingerprint
             options:
                 var: proofDigest
@@ -493,9 +620,13 @@ states:
           - kind: shell
             options:
                 command: >-
-                    eval "$(jq -r 'if .mode=="source-repo" then "S="+@sh"\(.dir)/quality-gate.ts"+" RUNNER=bun" elif .mode=="installed" then "S="+@sh"\(.dir)/quality-gate.mjs"+" RUNNER=node" else empty end' ".spur/run/$__runId-script-root.json" 2>/dev/null)"; if [ -f "$S" ]; then "$RUNNER" "$S" recheck; else echo "quality gate failed closed — quality-gate script not found — run 'superskill install sp --marketplace gobing-ai/spur'" >&2; printf 'FAIL\n' > ".spur/run/$wbs-test-gate.status"; fi; exit 0
+                    eval "$(jq -r 'if .mode=="source-repo" then "S="+@sh"\(.dir)/quality-gate.ts"+" RUNNER=bun" elif .mode=="installed" then "S="+@sh"\(.dir)/quality-gate.mjs"+" RUNNER=node" else empty end' ".spur/run/$__runId-script-root.json" 2>/dev/null)"; M=recheck; [ "$deferQualityGate" = "true" ] && M=deferred; if [ -f "$S" ]; then "$RUNNER" "$S" "$M"; else echo "quality gate failed closed — quality-gate script not found — run 'superskill install sp --marketplace gobing-ai/spur'" >&2; printf 'FAIL\n' > ".spur/run/$wbs-test-gate.status"; fi; exit 0
 
     - id: triage
+      display:
+          phase: review
+          phaseTitle: Review
+          title: Choose review depth
       description: >-
           Deterministic lane router between a green gate and the review/verify fork (0943 R1).
           Writes the diffstat evidence file, honors a caller-set `mode` (never overridden), pins
@@ -524,17 +655,18 @@ states:
             options:
                 command: >-
                     mkdir -p .spur/run; if [ -n "$mode" ]; then printf '%s\n' "$mode" > ".spur/run/$wbs-mode.txt"; exit 0; fi; DF=".spur/run/$wbs-diffstat.json"; if ! jq -e 'type == "object"' "$DF" >/dev/null 2>&1; then printf 'safety\n' > ".spur/run/$wbs-mode.txt"; exit 0; fi; jq -r 'if .sensitive == true or ((.insertions // 0) + (.deletions // 0)) > 400 then "safety" else empty end' "$DF" 2>/dev/null > ".spur/run/$wbs-mode.txt"; exit 0
-          # (d) lane decision — degrades to the standard default whenever workflow.decideDecisionMaker
+          # (d) lane decision — degrades to the standard default whenever workflows.decideDecisionMaker
           # is off (R4), so with the flag off this state is pure shell: no model call is made.
+          # 1114: the inline decide moved to the bundled catalog (`config/decisions/task-pipeline.yaml`
+          # → `task-triage`), whose R0 samples measured this exact prompt before the migration.
+          # Routing contract is unchanged: same evidence, same resultFile, same guards, same
+          # `standard` fallback when the switch is off (field-identical to this form's default).
           - kind: decide
             options:
                 id: task-triage
-                method: choice
-                question: >-
-                    The quality gate is green. Which verification lane does this diff deserve —
-                    low (small, contained diff — fast lane), standard, or high caution?
-                choices: [low, standard, high]
-                default: standard
+                decision: task-triage
+                params:
+                    wbs: ${vars.wbs}
                 evidence:
                     - .spur/run/${vars.wbs}-diffstat.json
                     - ${vars.taskSpecPath}
@@ -555,6 +687,11 @@ states:
                 var: mode
 
     - id: test-fail-triage
+      display:
+          phase: test
+          phaseTitle: Test
+          title: Triage test failure
+          show: on-entry
       description: >-
           Deterministic failure-class router on a red gate (0943 R3). The engine has no onEnter
           conditionals, so the FAIL branch from `test`/`test-recheck` lands here as its own
@@ -565,22 +702,44 @@ states:
           missing/corrupt decision fails closed to failed-check. (0976 R2 collapsed the former
           `retryable` lane: the declared default made it unreachable on the inline path.)
       onEnter:
+          # 1115: catalog-reference decide (task 1094 form) — question/choices/fallback live in
+          # the bundled catalog (`config/decisions/task-pipeline.yaml` → `failure-class`), whose
+          # R0 samples measured this exact prompt before the migration. Routing contract is
+          # unchanged: same resultFile, same guards, same `fix` fallback when the switch is off.
           - kind: decide
             options:
                 id: failure-class
-                method: choice
-                question: >-
-                    The quality gate failed. Is the failure fixable by the repair agent, or should
-                    the run stop here?
-                choices: [fix, stop]
-                default: fix
+                decision: failure-class
+                params:
+                    wbs: ${vars.wbs}
                 evidence:
                     - .spur/run/${vars.wbs}-test-gate.findings
                 resultFile: .spur/run/${vars.wbs}-failure-class.decision
 
     - id: review
-      description: Three-dimensional code review via /sp:dev-review (functional requirements traceability + SECUA framework (Security, Efficiency, Correctness, Usability, Architecture) + architecture depth), findings written to `## Review`.
+      display:
+          phase: review
+          phaseTitle: Review
+          title: Review changes
+      description: >-
+          Three-dimensional code review via /sp:dev-review (functional requirements traceability +
+          SECUA framework (Security, Efficiency, Correctness, Usability, Architecture) +
+          architecture depth), findings written to `## Review`. Cost at this decision point (1122):
+          open P1-P3 review findings block `done` — the PASS edges below also run the review-gate
+          residual check, and a PASS carrying an open P1-P3 row routes to review-fail-triage
+          before verify. Fixing a finding invalidates the certified digest and re-runs
+          quality → review → verify on a fresh digest; only P4 rows and DEFER-ed P3 rows are wrap
+          residuals.
       onEnter:
+          # 1135 R4: review joins the proof bracket. A pre-review compare refuses to spend a review
+          # dispatch on a state that has drifted from the certified digest; the mismatch routes
+          # through the existing tripwire to `failed` (no new re-certify path).
+          - kind: proof.fingerprint
+            options:
+                var: proofDigestNow
+                taskFile: ${vars.taskSpecPath}
+                featureFile: ${vars.featureSpecPath}
+                expect: ${vars.proofDigest}
           - kind: agent.run
             options:
                 # 0710 R2: review always runs on a fresh session — no implementation-session
@@ -611,11 +770,57 @@ states:
           # verify stamp marks review `completed` only when this marker equals the current digest;
           # otherwise `skipped` (an honest downgrade, never a fake completed), and the bound
           # `record` registration refuses a skipped review.
+          # Session finding after 1088: the review VERDICT is read straight out of the reviewer's
+          # own answer file by the review → * guards below, so this stage needs no extra artifact
+          # and no extra action (ADR-115 legibility cap).
           - kind: shell
             options:
                 command: 'mkdir -p .spur/run; printf "%s" "$proofDigest" > ".spur/run/$__runId-review-proof.digest"; exit 0'
 
+    # ── review-fail-triage (session finding after 1088) ────────────────────────
+    # A review that reports FAIL used to have no outgoing edge: the graph could not see the
+    # verdict and nothing consumed it, so remediating a failing review meant driving the
+    # states by hand. This state is the review-side twin of `test-fail-triage` (0943 R3):
+    # the deterministic classifier routes the failure into the SAME bounded fix budget
+    # (`.spur/run/<wbs>-test-fix-attempt` against `qualityGateMaxFixAttempts`), and the fix
+    # re-enters quality → review → verify on a freshly captured digest. The `decide` action
+    # itself always runs (the engine has no onEnter conditionals); with
+    # `workflows.decideDecisionMaker` off it degrades to its declared default.
+    - id: review-fail-triage
+      display:
+          phase: review
+          phaseTitle: Review
+          title: Triage review findings
+          show: on-entry
+      description: >-
+          Deterministic router for a review that did NOT certify PASS (session finding after 1088).
+          `decide review-failure-class` reads the reviewer's answer and the task spec and routes:
+          fix → the shared test-fix hop, stop → failed with terminalReason failed-check. A
+          missing/corrupt decision fails closed to failed-check. Cost either way (1122): open
+          P1-P3 review findings block `done`; the fix lane re-enters quality → review → verify on a
+          fresh digest; only P4 rows and DEFER-ed P3 rows are wrap residuals.
+      onEnter:
+          # 1116: the inline decide moved to the bundled catalog (`config/decisions/task-pipeline.yaml`
+          # → `review-failure-class`), whose R0 samples measured this exact prompt before the
+          # migration. Routing contract is unchanged: same evidence, same resultFile, same guards,
+          # same `fix` fallback when the switch is off.
+          - kind: decide
+            options:
+                id: review-failure-class
+                decision: review-failure-class
+                params:
+                    wbs: ${vars.wbs}
+                evidence:
+                    - .spur/run/${vars.__runId}-review-answer.txt
+                    - ${vars.taskSpecPath}
+                resultFile: .spur/run/${vars.wbs}-review-failure-class.decision
+
     - id: approve
+      display:
+          phase: review
+          phaseTitle: Review
+          title: Operator approval
+          show: on-entry
       description: >
           Human-in-the-loop approval gate. Under `profile=auto` this state is never entered
           (review routes around it straight to verify). In interactive mode this state pauses
@@ -631,9 +836,18 @@ states:
                     mode: never
 
     - id: verify
+      display:
+          phase: verify
+          phaseTitle: "Verify & record"
+          title: Verify requirements and AC
       description: >
           Observe-only functional verification (BDD + traceability) via /sp:dev-verify --fix none
           (task 0703 R1, ADR-071): the verifier certifies the state, it never repairs its own subject.
+          The answer-shape contract this stage enforces is OWNED BY the skill, not restated here
+          (task 1110 R3): see `plugins/sp/skills/code-verification/SKILL.md` § Answer-File Schema
+          Contract (`:340-375`), with the row-id/evidence vocabularies in
+          `plugins/sp/skills/code-verification/references/verdict-schema.md`. The YAML only names
+          the lint that consumes it (`task verdict --from-answer`).
           A live digest compare BEFORE the agent refuses to certify a state that drifted after the
           quality/review evidence was produced (R2). The agent's
           captured answer is written to `.spur/run/<wbs>-verify-answer.txt` and MUST follow
@@ -675,8 +889,28 @@ states:
           # (d) `spur task verdict` owns the answer lint (task 1003 R2) — the shell below
           # fails closed when the verifier's answer is malformed, before any verdict artifact.
           - kind: shell
+            # `task verdict` exits 1 on a non-PASS verdict by design (1003 R2). The `continue`
+            # policy keeps that exit code as recorded evidence (the action row is still `failed`)
+            # while letting the state finish its remaining actions and reach the guards below;
+            # without it the default 'fail' policy halts the run here and `verify → test-fix`
+            # (the declared bounded remediation lane) can never fire (v5, task 1077 run).
+            onError: continue
             options:
                 command: "$spurBin task verdict $wbs --from-answer .spur/run/$wbs-verify-answer.txt"
+          # Session finding after 1088: the verifier's confidence level becomes a `confidence` check
+          # row and a gate-log line, so the level the completion guards enforce is visible in the
+          # artifact and the log — not only in the answer file. v6 (task 1134 run): the row warns for
+          # an unacknowledged LOW/absent level ONLY, matching the guards' ack rule; warning for
+          # MEDIUM too made an admitted certification aggregate to PARTIAL (self-inconsistent artifact,
+          # done refused). This is its own action because the proof-binding stamp below must stay the
+          # state's LAST action AND under the ADR-115 800-char shell cap.
+          - kind: shell
+            options:
+                command: >-
+                    V=".spur/run/$wbs-verdict.json"; [ -f "$V" ] || exit 0;
+                    jq --arg ack "$ackLowConfidence" '. + {checks: (((.checks // []) | map(select(.name != "confidence"))) + [{name: "confidence", status: (if ((.confidence // "LOW") != "LOW" or $ack == "true") then "pass" else "warn" end), evidence: ((.confidence // "LOW (absent from artifact)") + (if $ack == "true" then " (operator-acknowledged)" else "" end))}])}' "$V" > "$V.tmp" && mv "$V.tmp" "$V";
+                    printf 'confidence: %s (ack=%s)\n' "$(jq -r '.confidence // "LOW (absent)"' "$V")" "$ackLowConfidence" >> ".spur/run/$wbs-test-gate.log";
+                    exit 0
           # (e) one jq mutation binds the verdict to the proof digest (0703 R3; runId 0730 §B.2 /
           # 0757 R4; definitionDigest 0759 R5; honest review stamp 0785 R4; soft action + hard guard).
           - kind: shell
@@ -685,6 +919,10 @@ states:
                     V=".spur/run/$wbs-verdict.json"; [ -f "$V" ] && [ -n "$proofDigest" ] || exit 0; jq --arg d "$proofDigest" --arg r "$__runId" --arg dd "$__definitionDigest" --arg rp "$(cat .spur/run/$__runId-review-proof.digest 2>/dev/null)" --arg g "$(cat .spur/run/$wbs-test-gate.status 2>/dev/null || echo UNKNOWN)" '. + {proof: {digest: $d, runId: $r, definitionDigest: $dd, capturePoint: "quality-gate-entry", stages: {qualityGate: {status: $g, digest: $d}, review: {status: (if $rp == $d then "completed" else "skipped" end), digest: $d}, verification: {status: .verdict, digest: $d}}}} | .checks += [{name: "proof-input-digest", status: "pass", evidence: $d}]' "$V" > "$V.tmp" && mv "$V.tmp" "$V"; exit 0
 
     - id: record
+      display:
+          phase: verify
+          phaseTitle: "Verify & record"
+          title: Record evidence
       description: >
           Record pipeline results into the task file via `spur task record` —
           Testing/Review from the verdict, Solution backfilled from git diff as a
@@ -844,7 +1082,11 @@ transitions:
       guard:
           kind: shell
           options:
-              command: '$spurBin task check $wbs --precheck'
+              # 1132 R4 (auto-fix-first): repair mechanically first, then judge fail-closed. The
+              # `--fix` output is captured to a run artifact so the batch report can carry the
+              # task-level repairs under `autoRepairs` (feature-level repairs come from the
+              # `feature check --fix` preflight); only `--precheck` decides this transition.
+              command: '$spurBin task check $wbs --fix --json > ".spur/run/$wbs-auto-repairs.json" 2>/dev/null ; $spurBin task check $wbs --precheck'
     - from: precheck
       to: failed
       terminalReason: failed-check
@@ -912,9 +1154,11 @@ transitions:
       guard:
           kind: shell
           options:
+              # 1111 R2: `DEFERRED` is accepted ONLY when the opt-in var is "true" — with the
+              # default "false" a stray DEFERRED file fails the guard exactly like a corrupt one.
               command: >-
                   gate_status="$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)";
-                  test "$gate_status" = PASS
+                  test "$gate_status" = PASS || { test "$gate_status" = DEFERRED && test "$deferQualityGate" = "true"; }
     - from: test
       to: test-fail-triage
       description: Quality gate red — classify the failure before the repair hop (0943 R3).
@@ -945,9 +1189,10 @@ transitions:
       guard:
           kind: shell
           options:
+              # 1111 R2: same var-gated acceptance of the deferred token as `test → triage`.
               command: >-
                   gate_status="$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)";
-                  test "$gate_status" = PASS
+                  test "$gate_status" = PASS || { test "$gate_status" = DEFERRED && test "$deferQualityGate" = "true"; }
     - from: test-recheck
       to: test-fail-triage
       description: Still red after fixall — classify the failure (0943 R3).
@@ -1018,21 +1263,84 @@ transitions:
       description: Failure-class decision missing/corrupt — stop at failed.
       guard:
           kind: always
-    # ── review → approve, OR skip the HITL gate entirely when profile=auto (R4) ──
-    # Declaration order matters: the auto-skip guard is tried FIRST, so under
-    # profile=auto the run routes straight to verify and never ENTERS approve
-    # (whose onEnter hitl.confirm would otherwise block). Otherwise fall through
-    # to approve for the human gate.
+    # ── review-failure routing (session finding after 1088): the review-side twin of the
+    # failure-class router above — stop first, then the shared attempt cap, then the fix lane,
+    # then the fail-closed defense. The counter is the SAME one the quality-gate loop uses, so a
+    # review FAIL cannot buy extra attempts and the iteration bound stays finite.
+    - from: review-fail-triage
+      to: failed
+      terminalReason: failed-check
+      description: Review failure class stop — the run terminates at failed, never bypassed.
+      guard:
+          kind: shell
+          options:
+              command: >-
+                  jq -e '.value == "stop"' ".spur/run/$wbs-review-failure-class.decision" >/dev/null 2>&1
+    - from: review-fail-triage
+      to: failed
+      terminalReason: retry-exhausted
+      description: Attempt cap reached — qualityGateMaxFixAttempts bounds the review repair lane.
+      guard:
+          kind: shell
+          options:
+              command: >-
+                  fix_attempts="$(cat .spur/run/$wbs-test-fix-attempt 2>/dev/null || echo 0)";
+                  test "$fix_attempts" -ge "$qualityGateMaxFixAttempts"
+    - from: review-fail-triage
+      to: test-fix
+      description: Review failure class fix and under the cap — the shared bounded repair hop.
+      guard:
+          kind: shell
+          options:
+              command: >-
+                  jq -e '.value == "fix"' ".spur/run/$wbs-review-failure-class.decision" >/dev/null 2>&1
+    # Defense: missing/corrupt review-failure decision — fail closed instead of silently repairing.
+    - from: review-fail-triage
+      to: failed
+      terminalReason: failed-check
+      description: Review-failure decision missing/corrupt — stop at failed.
+      guard:
+          kind: always
+    # ── review routing: FAIL → bounded remediation; PASS → approve or the auto-skip (R4) ──
+    # Declaration order matters and is FAIL-CLOSED: the two PASS edges each demand the reviewer's
+    # own `Verdict: PASS` line AND a passing review-gate residual check (1122 R3) — the SAME
+    # parse/classify/deferrals the record sweep enforces, resolved through the same source-repo /
+    # installed scanner pair as the record step; a missing scanner fails closed into the catch-all.
+    # EVERYTHING ELSE — FAIL, a missing or unparseable answer, or a PASS carrying an open P1-P3
+    # review finding (record would terminally fail it after a full verify + record) — enters
+    # `review-fail-triage` and its bounded repair hop BEFORE verify spends the cycle, then
+    # re-enters quality → review → verify on a fresh digest. Before 1088 a FAIL review had no
+    # outgoing edge at all; before 1122 a PASS-with-findings cost a full re-certification cycle per
+    # attempt (knowledge-kit 0210/0213). The reviewer writes `Verdict: PASS|FAIL` in its answer;
+    # both plain and bold forms are accepted. Under `profile=auto` the approve gate is skipped, so
+    # the PASS+auto edge is tried first and the interactive PASS edge second.
     - from: review
       to: verify
-      description: profile=auto — skip the human approval gate, go straight to verify.
+      description: profile=auto, the review certified PASS, and no open P1-P3 review finding — skip the human approval gate.
       guard:
           kind: shell
           options:
-              command: 'test "$profile" = auto'
+              command: >-
+                  test "$profile" = auto &&
+                  grep -qiE '^[[:space:]]*\**Verdict:\** *PASS' ".spur/run/$__runId-review-answer.txt" &&
+                  eval "$(jq -r 'if .mode=="source-repo" then "S="+@sh"\(.dir)/residual-scan.ts"+" RUNNER=bun" elif .mode=="installed" then "S="+@sh"\(.dir)/residual-scan.mjs"+" RUNNER=node" else empty end' ".spur/run/$__runId-script-root.json" 2>/dev/null)" &&
+                  [ -f "$S" ] && "$RUNNER" "$S" review-gate "$wbs" --spur-bin "$spurBin" >&2
     - from: review
       to: approve
-      description: Review done — gate on human approval.
+      description: Review certified PASS with no open P1-P3 review finding — gate on human approval before verification.
+      guard:
+          kind: shell
+          options:
+              command: >-
+                  grep -qiE '^[[:space:]]*\**Verdict:\** *PASS' ".spur/run/$__runId-review-answer.txt" &&
+                  eval "$(jq -r 'if .mode=="source-repo" then "S="+@sh"\(.dir)/residual-scan.ts"+" RUNNER=bun" elif .mode=="installed" then "S="+@sh"\(.dir)/residual-scan.mjs"+" RUNNER=node" else empty end' ".spur/run/$__runId-script-root.json" 2>/dev/null)" &&
+                  [ -f "$S" ] && "$RUNNER" "$S" review-gate "$wbs" --spur-bin "$spurBin" >&2
+    - from: review
+      to: review-fail-triage
+      description: >-
+          No certified PASS without an open P1-P3 finding (FAIL, PARTIAL, missing, unparseable, or
+          a PASS whose review-gate check found an open P1-P3 row — fail closed) — classify the
+          failure and route it into the bounded repair hop instead of dead-ending the run.
       guard:
           kind: always
 
@@ -1069,19 +1377,23 @@ transitions:
     # The verify step emits .spur/run/<wbs>-verdict.json with a required proof block (task 0703 R3/R5).
     # Only `verdict: PASS` PLUS a proof block whose digest — top level and every named stage — equals
     # the captured `proofDigest` clears the gate to `record`; any non-PASS, a missing file, malformed
-    # JSON, or missing/mismatched proof evidence does not. Declaration order: PASS+proof guard FIRST,
+    # JSON, or missing/mismatched proof evidence does not. The verifier's confidence level is part of
+    # that certification (session finding after 1088): a PASS the verifier itself marked LOW — or left
+    # unstated — clears the gate only when the operator accepted it with
+    # `--vars '{"ackLowConfidence":"true"}'`. Declaration order: PASS+proof guard FIRST,
     # then the bounded remediation route (R4), then the always catch-all so a PASS verdict with a
     # missing/malformed proof block still terminates at `failed` instead of hanging the state.
     - from: verify
       to: record
-      description: Verification verdict is PASS and its proof block names the captured digest on every stage — record results and proceed to done.
+      description: Verification verdict is PASS, its proof block names the captured digest on every stage, and any LOW confidence was operator-acknowledged — record results and proceed to done.
       guard:
           # (one jq -e predicate) PASS verdict; proof, quality-gate, review and verification digests
-          # equal to proofDigest; review completed; matching run id and definition digest (0703 R5, 0785 R4).
+          # equal to proofDigest; review completed; matching run id and definition digest (0703 R5, 0785 R4);
+          # confidence HIGH/MEDIUM, or LOW/absent with the operator's ack (session finding after 1088).
           kind: shell
           options:
               command: >-
-                  jq -e --arg d "$proofDigest" --arg r "$__runId" --arg dd "$__definitionDigest" '
+                  jq -e --arg d "$proofDigest" --arg r "$__runId" --arg dd "$__definitionDigest" --arg ack "$ackLowConfidence" '
                   .verdict == "PASS"
                   and (.proof.digest // "") == $d
                   and (.proof.stages.qualityGate.digest // "") == $d
@@ -1090,6 +1402,7 @@ transitions:
                   and (.proof.stages.verification.digest // "") == $d
                   and (.proof.runId // "") == $r
                   and (.proof.definitionDigest // "") == $dd
+                  and ((.confidence // "LOW") != "LOW" or $ack == "true")
                   ' ".spur/run/$wbs-verdict.json" >/dev/null 2>&1
     - from: verify
       to: test-fix
@@ -1117,11 +1430,12 @@ transitions:
     # ── done gate: record → done/failed gated on `spur task check` (ADR-026 amendment 2026-06-23)
     # PLUS the proof-block re-assertion (task 0703 R5): the verdict artifact must still be PASS and
     # still name the captured digest — a forged or mutated completion artifact fails closed here.
+    # PLUS the confidence re-assertion (session finding after 1088): the same ack rule as verify →
+    # record, re-read from the artifact so a mutation between the two boundaries cannot slip through.
     # Declaration order: pass guard first.
     - from: record
       to: done
-      description: Task check passed and the verdict proof block still names the captured digest — certify done.
-      # (warn) 5 commands: named verdict + proof digest reads after the task check (legibility, 0874).
+      description: Task check passed, the verdict proof block still names the captured digest, and any LOW confidence was acknowledged — certify done.
       guard:
           kind: shell
           options:
@@ -1130,11 +1444,16 @@ transitions:
               # the CLI's own target-aware `--no-lifecycle` backstop (F92 R3). No `#`
               # comments inside the folded scalar: `>-` joins same-indent lines into
               # one shell line.
+              # Two logical commands, deliberately (ADR-115): the `task check` projection plus
+              # ONE jq predicate re-asserting the whole completion contract — PASS verdict, the
+              # captured proof digest, and the confidence rule (session finding after 1088).
               command: >-
                   $spurBin task check $wbs --as done &&
-                  verdict="$(jq -r .verdict .spur/run/$wbs-verdict.json 2>/dev/null)" &&
-                  proof_digest="$(jq -r '.proof.digest // ""' .spur/run/$wbs-verdict.json 2>/dev/null)" &&
-                  test "$verdict" = PASS && test "$proof_digest" = "$proofDigest"
+                  jq -e --arg p "$proofDigest" --arg ack "$ackLowConfidence" '
+                  .verdict == "PASS"
+                  and ((.proof.digest // "") == $p)
+                  and ((.confidence // "LOW") != "LOW" or $ack == "true")
+                  ' ".spur/run/$wbs-verdict.json" >/dev/null 2>&1
     - from: record
       to: failed
       terminalReason: failed-check