@gobing-ai/spur 0.3.91 → 0.3.93

package/config/workflows/task-pipeline.yaml

@@ -6,13 +6,18 @@
 # through the normal `spur task update <wbs> <status>` verb so the lifecycle guards
 # (0055) apply identically. Run linkage is written to `task_run_links` (kind=pipeline).
 #
-# Shape: precheck → implement → test[→test-fix↔test-recheck] → review → approve(HITL)
+# Shape: precheck → implement[→escalate] → test[→test-fix↔test-recheck] → review → approve(HITL)
 #        → verify → record → done
 #        (precheck failure short-circuits to `failed`; approve routes to `failed` on
 #        operator rejection or `cancelled` on operator cancel — R1, bug-750).
 #        `test` is the project quality gate (shell + bounded /sp:dev-fixall), not
 #        /sp:dev-unit (coverage gap-fill; router C3/C5).
 #
+# F96 residual sweep (0950): precheck captures the resume-safe base commit; verify
+# scans and folds residuals between the verdict and the proof bind (blocking leftovers
+# downgrade PASS → PARTIAL and take the existing remediation edge); done settles
+# deferrals; failed renders the recovery report. No new state, edge, or model query.
+#
 # Vars (passed as a JSON object via `--vars`):
 #   wbs                       — task WBS (required)
 #   profile                   — "auto" skips HITL approve (R4)
@@ -21,6 +26,7 @@
 #   implementTimeoutMs        — implement agent.run budget (ms)
 #   qualityGateCmd            — project gate (default: bun run spur-check)
 #   qualityGateMaxFixAttempts — max /sp:dev-fixall hops after a red gate (default: 2)
+#   maxEscalations            — max operator-question pauses per implement chain (default: 2)
 #
 # Seeded by `spur init`. agent.run inputs are pure slash commands (ADR-043).
 
@@ -90,6 +96,10 @@ vars:
     # 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: ""
+    # Operator answer captured by the escalate hop's hitl.input (0933). Empty by
+    # 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
@@ -134,6 +144,14 @@ vars:
     # Max /sp:dev-fixall attempts after a red quality-gate probe/recheck (bounded; no thrash).
     # Attempt counter: .spur/run/<wbs>-test-fix-attempt. Default 2 = two fixall hops before failed.
     qualityGateMaxFixAttempts: "2"
+    # Max operator-question pauses (0933) before the implement chain routes to failed.
+    # Escalation counter: .spur/run/<wbs>-escalation-count. Default 2 = two answered
+    # questions; a third pause routes to failed with a report note.
+    maxEscalations: "2"
+    # 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.
+    escalationQuestion: ""
     # Post-implement auto-format. Overridable like qualityGateCmd so a non-Bun seeded
     # project can point it at its own formatter; invoked best-effort (a missing or
     # failing formatter must never abort a run — the quality gate is the real gate).
@@ -156,6 +174,12 @@ vars:
     # (default) = on; set to "off" to bypass:
     # `--vars '{"implementScopeGuard":"off"}'`.
     implementScopeGuard: ""
+    # 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
+    # orchestrator runs the sync + `spur feature refresh` once per touched feature on the
+    # base ref after integration. Sequential/inline keep the default "false" (unchanged).
+    deferFeatureSync: "false"
 
 states:
     - id: precheck
@@ -189,6 +213,12 @@ states:
             options:
                 command: >-
                     mkdir -p .spur/run; S=plugins/sp/scripts/task-evidence-precheck.ts; [ -f "$S" ] || S="$(superskill script path sp task-evidence-precheck.ts 2>/dev/null)"; if [ -f "$S" ]; then bun "$S" "$wbs" --spur-bin "$spurBin"; else echo "task-evidence-precheck failed closed — checker not found in plugins/sp/scripts/ nor staged — run 'superskill install sp'." >&2; echo "FAIL" > ".spur/run/$wbs-precheck-evidence.status"; fi; exit 0
+          # (e) F96 R1 (0950): capture the run's base commit once — a resumed or re-entered run
+          # keeps its original base so residual scans stay anchored to the same diff.
+          - kind: shell
+            options:
+                command: >-
+                    mkdir -p .spur/run; [ -f ".spur/run/$wbs-base.sha" ] || git rev-parse HEAD > ".spur/run/$wbs-base.sha"; exit 0
           # (e) route-reason lookup and routes log; proportional-routing tests locate it
           # (0759 R1/R5 run-scoped artifact; 0804 R8 run-id safety — one line, no in-scalar `#`).
           - kind: shell
@@ -222,6 +252,20 @@ states:
           that command DRIVES this pipeline, so calling it here recurses.
           --mode implement is the single-step implement entry.
       onEnter:
+          # 0933 R27 (guard-lines compression): the transcript append lives HERE, on
+          # (re-)entry, not in the escalate→implement guard. On first entry there is no
+          # pending question (no-op); on a resume entry the guard already confirmed a
+          # non-empty $__hitlInput and a fresh question file, so this shell records the
+          # Q/A pair (## Q<n>/## A<n>, R3) and consumes the question file before the
+          # agent.run re-dispatches — which also disarms the implement→escalate edge.
+          - kind: shell
+            options:
+                command: >-
+                    test -n "$__hitlInput" -a -s .spur/run/$wbs-question.md || exit 0;
+                    qn="$(cat .spur/run/$wbs-escalation-count 2>/dev/null || echo 0)";
+                    printf '## Q%s\n%s\n\n## A%s\n%s\n' "$qn" "$(cat .spur/run/$wbs-question.md 2>/dev/null)" "$qn" "$__hitlInput" >> .spur/run/$wbs-escalation.md;
+                    rm -f .spur/run/$wbs-question.md;
+                    exit 0
           - kind: agent.run
             options:
                 agent: ${vars.implementAgent}
@@ -232,13 +276,23 @@ states:
                 # resumes the implement session instead of re-reading the task cold.
                 session: reuse
                 # lives in /sp:dev-run --mode implement → sp:code-implementation, not YAML prose.
-                input: /sp:dev-run --mode implement ${vars.wbs} --auto
+                # 0933 R28: --escalation-file names the Q/A transcript the implement
+                # agent appends to when pausing and reads back on re-dispatch; absent
+                # on a first attempt means "no prior escalations".
+                input: /sp:dev-run --mode implement ${vars.wbs} --auto --escalation-file .spur/run/${vars.wbs}-escalation.md
                 timeoutMs: ${vars.implementTimeoutMs}
                 # R3 (task 0424): empty-implement no-op guard — the agent.run action
                 # fails the step when exit 0 produced zero non-corpus file changes, so
                 # a silent no-op routes the run to `failed` here instead of drifting
                 # into test/review and being caught a full pass later.
                 requireDiff: true
+                # 0933 R26: escalation contract — the agent.run option names the QUESTION
+                # file (the pause signal, deleted pre-dispatch for freshness); a paused
+                # attempt (agent wrote its question there and exited 0) succeeds with
+                # data.escalated=true and skips requireDiff for THAT attempt only. The
+                # Q/A transcript (.spur/run/<wbs>-escalation.md) is separate: it reaches
+                # the agent via --escalation-file in the input below.
+                escalationFile: .spur/run/${vars.wbs}-question.md
                 # 0706 R6: this stage mutates the working tree unattended under the
                 # auto profile, so it declares minimum execution-capability
                 # requirements. Dispatch fails closed (before spawn) when the
@@ -273,6 +327,39 @@ states:
             options:
                 command: "$formatCmd ; exit 0"
 
+    # ── escalate hop (operator-question pause, 0933) ──────────────────────────
+    # The implement agent paused on an operator question: it wrote
+    # .spur/run/<wbs>-question.md and exited 0 (agent.run reported
+    # data.escalated=true, skipping requireDiff for that attempt). This hop bounds
+    # the asks (counter), surfaces the question verbatim through the HITL responder
+    # (the run pauses here), and — after `spur workflow continue --answer-text <a>`
+    # delivers __hitlInput — resumes implement with the Q/A transcript
+    # (.spur/run/<wbs>-escalation.md) named in the implement input via
+    # --escalation-file. The transcript append + question-file consumption happen in
+    # the escalate→implement guard so a stale question can never re-trigger the hop
+    # after the answered attempt.
+    - id: escalate
+      description: >-
+          Operator-question pause (0933): the implement agent asked a question
+          headlessly; surface it to the operator and resume implement with the answer.
+      onEnter:
+          # Bounded asks: increment the per-task escalation counter before pausing.
+          - kind: shell
+            options:
+                command: >-
+                    mkdir -p .spur/run; n="$(cat .spur/run/$wbs-escalation-count 2>/dev/null || echo 0)"; echo $((n + 1)) > .spur/run/$wbs-escalation-count; exit 0
+          # The agent's question, verbatim, becomes the pause prompt.
+          - kind: file.read.into-var
+            options:
+                file: .spur/run/${vars.wbs}-question.md
+                var: escalationQuestion
+          # Pause for the operator (responder pause:true stops the run after this
+          # onEnter; `spur workflow continue --answer-text <answer>` writes
+          # __hitlInput and re-evaluates the escalate guards).
+          - kind: hitl.input
+            options:
+                prompt: "${vars.escalationQuestion}"
+
     # ── test hop (quality gate + bounded auto-fix) ─────────────────────────────
     # NOT /sp:dev-unit. That command (sp:code-testing) *extends/generates* tests toward
     # a coverage target; it is not the project quality gate. Coverage gap-fill remains
@@ -358,6 +445,14 @@ states:
             options:
                 command: >-
                     mkdir -p .spur/run; A=".spur/run/$wbs-test-fix-attempt"; n=$(cat "$A" 2>/dev/null || echo 0); printf '%s\n' "$((n + 1))" > "$A"; [ ! -f ".spur/run/$wbs-verdict.json" ] || { echo '--- verify verdict (remediation input, task 0703 R4) ---'; cat ".spur/run/$wbs-verdict.json"; } >> ".spur/run/$wbs-test-gate.log"; exit 0
+          # (d) F96 R3 (0950): hand the residual list to the remediation loop — dev-fixall
+          # treats residual items as fix targets and may defer P3/markers to
+          # residual-deferrals.json (see dev-fixall.md). Fold already merged the anchors
+          # into <wbs>-test-gate.findings; this carries the structured artifact too.
+          - kind: shell
+            options:
+                command: >-
+                    [ ! -f ".spur/run/$wbs-residuals.json" ] || { echo '--- residual artifact (F96 fix targets; deferrals go to residual-deferrals.json, P3/markers only) ---'; cat ".spur/run/$wbs-residuals.json"; } >> ".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.
@@ -391,8 +486,8 @@ states:
     - id: test-recheck
       description: >
           Soft recheck after fixall with bounded SQLite-lock retry. Writes PASS|FAIL (always exit 0). Transitions
-          branch to review (PASS), another test-fix (FAIL and under max attempts),
-          or the pipeline `failed` state (FAIL and attempts exhausted) — never a
+          branch to `triage` (PASS — the 0943 lane router), `test-fail-triage` (FAIL — the 0943
+          failure-class router), or the pipeline `failed` state (corrupt status) — never a
           raw lifecycle abort that skips the terminal `failed` state.
       onEnter:
           # R4 (0703, ADR-071): bounded remediation mutated the tree by design, so the fresh evidence
@@ -415,6 +510,99 @@ states:
                 command: >-
                     mkdir -p .spur/run; if [ -f plugins/sp/scripts/quality-gate.ts ]; then bun plugins/sp/scripts/quality-gate.ts recheck; elif Q="$(superskill script path sp quality-gate.mjs 2>/dev/null)" && [ -f "$Q" ]; then node "$Q" recheck; else echo "quality gate failed closed — quality-gate script not found — run 'superskill install sp'" >&2; printf 'FAIL\n' > ".spur/run/$wbs-test-gate.status"; fi; exit 0
 
+    - id: triage
+      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
+          the safety lane on sensitive paths or >400 changed lines without a model call (R2c),
+          otherwise consults `decide task-triage` (low → fast lane; anything else stays empty →
+          standard review path), and appends the triage route reason to
+          .spur/memory/task-pipeline-routes.log (R5). The `decide` action itself runs
+          unconditionally (the engine has no onEnter conditionals); its result is consulted only
+          when neither a caller mode nor the deterministic guard resolved the lane. The resolved
+          lane lands in the `mode` var for the triage → verify/review guards.
+      onEnter:
+          # (a) diffstat producer: task-diffstat.ts owns git reading and sensitive-path
+          # classification; shell only resolves it and fails closed (writes sensitive:true,
+          # which the pre-guard below maps to the safety lane).
+          - kind: shell
+            options:
+                command: >-
+                    mkdir -p .spur/run; if [ -f plugins/sp/scripts/task-diffstat.ts ]; then bun plugins/sp/scripts/task-diffstat.ts --spur-bin "$spurBin"; elif D="$(superskill script path sp task-diffstat.mjs 2>/dev/null)" && [ -f "$D" ]; then node "$D"; else echo "task-diffstat failed closed — task-diffstat script not found — run 'superskill install sp'" >&2; printf '{"files":0,"insertions":0,"deletions":0,"paths":[],"sensitive":true}\n' > ".spur/run/$wbs-diffstat.json"; fi; exit 0
+          # (b)+(c) lane pre-guard BEFORE decide: a caller-set mode is projected verbatim (R2b);
+          # a sensitive path or >400 changed lines pins safety (R2c) and the decide result below
+          # is never consulted. A missing/malformed diffstat row (producer crashed or never ran,
+          # disk error) pins safety HERE: an empty mode file would let the low decide row project
+          # the fast lane downstream, so the "never to fast" fail-safe is enforced at the guard,
+          # not by the projection (the full-suite gate run exposed this fail-open path).
+          - kind: shell
+            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
+          # is off (R4), so with the flag off this state is pure shell: no model call is made.
+          - 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
+                evidence:
+                    - .spur/run/${vars.wbs}-diffstat.json
+                    - ${vars.taskSpecPath}
+                resultFile: .spur/run/${vars.wbs}-triage.decision
+          # (d) project the decision: low → fast lane; anything else (standard/high, degraded
+          # default, missing row) leaves the mode empty → standard review path. A non-empty mode
+          # file (caller-set or deterministic-high) is never overridden.
+          - kind: shell
+            options:
+                command: >-
+                    MF=".spur/run/$wbs-mode.txt"; [ -s "$MF" ] && exit 0; jq -r 'if .value == "low" then "fast" else empty end' ".spur/run/$wbs-triage.decision" 2>/dev/null > "$MF"; exit 0
+          # R5: append the triage route reason in the shared routes-log format.
+          - kind: shell
+            options:
+                command: >-
+                    m="$(cat ".spur/run/$wbs-mode.txt")"; RUN_ID="$__runId"; [ -n "$RUN_ID" ] || RUN_ID="pipeline-$wbs"; mkdir -p .spur/memory; printf '%s %s %s\n' "$RUN_ID" "$wbs" "$(jq -rn --arg m "$m" --arg c "$mode" 'if $c != "" then ($c + ":caller-set") else {"fast":"fast:triage low lane","safety":"safety:triage deterministic-high","":"safety:triage standard lane"}[$m] // "safety:triage unrecognized mode" end')" >> .spur/memory/task-pipeline-routes.log
+          # (d) the resolved lane becomes the `mode` var for the triage → verify/review guards.
+          - kind: file.read.into-var
+            options:
+                path: .spur/run/${vars.wbs}-mode.txt
+                var: mode
+
+    - id: test-fail-triage
+      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
+          deterministic state (the sanctioned alternative), while the green branch goes to
+          `triage`. `decide failure-class` reads the bounded gate findings and routes: retryable
+          → test-recheck (the attempt is counted on entry, so qualityGateMaxFixAttempts still
+          bounds the loop), fix → test-fix (the repair hop, as before), stop → failed with
+          terminalReason failed-check. A missing/corrupt decision fails closed to failed-check.
+      onEnter:
+          - kind: decide
+            options:
+                id: failure-class
+                method: choice
+                question: >-
+                    The quality gate failed. Is the failure retryable (transient or environmental
+                    — just re-run the gate), fixable by the repair agent, or should the run stop
+                    here?
+                choices: [retryable, fix, stop]
+                default: fix
+                evidence:
+                    - .spur/run/${vars.wbs}-test-gate.findings
+                resultFile: .spur/run/${vars.wbs}-failure-class.decision
+          # A retryable classification still counts an attempt so the existing
+          # qualityGateMaxFixAttempts cap bounds the recheck loop (0943 R3; the cap edge reads
+          # the same counter the fixall path uses).
+          - kind: shell
+            options:
+                command: >-
+                    A=".spur/run/$wbs-test-fix-attempt"; [ "$(jq -r '.value // ""' ".spur/run/$wbs-failure-class.decision" 2>/dev/null)" = retryable ] && { n="$(cat "$A" 2>/dev/null || echo 0)"; printf '%s\n' "$((n + 1))" > "$A"; }; exit 0
+
     - 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`.
       onEnter:
@@ -530,6 +718,16 @@ states:
           - kind: shell
             options:
                 command: "$spurBin task verdict $wbs --from-answer .spur/run/$wbs-verify-answer.txt"
+          # (d) F96 R2 (0950): residual-scan.ts owns the sweep; shell only resolves it.
+          # ONE hard action (scan+fold): a scanner crash fails verify closed — the
+          # verify→failed catch-all routes a missing/malformed verdict. Runs AFTER
+          # `task verdict` and BEFORE the jq bind so a blocking residual turns PASS
+          # into PARTIAL (fold rewrites the verdict artifact) and takes the existing
+          # verify→test-fix edge while attempts remain.
+          - kind: shell
+            options:
+                command: >-
+                    S=plugins/sp/scripts/residual-scan.ts; [ -f "$S" ] || S="$(superskill script path sp residual-scan.mjs 2>/dev/null)"; if [ ! -f "$S" ]; then echo "residual-scan failed closed — scanner not found in plugins/sp/scripts/ nor staged — run 'superskill install sp'" >&2; exit 1; fi; case "$S" in *.mjs) RUNNER=node ;; *) RUNNER=bun ;; esac; "$RUNNER" "$S" scan "$wbs" --spur-bin "$spurBin" && "$RUNNER" "$S" fold "$wbs" --spur-bin "$spurBin"
           # (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
@@ -584,10 +782,16 @@ states:
           # (d) feature-sync-bounded.ts owns the sync; shell adds the orphan note and fallbacks
           # (0411 retry-suppression; 0328 / ADR-0322). Best-effort `exit 0` — feature status sync is a
           # follow-up, not a completion gate; `record → done` runs `spur task check`.
+          # 0931 R5: with deferFeatureSync "true" (parallel mode) the deferral note lands in the
+          # task report and the sync is skipped entirely, so task branches never touch feature
+          # corpus files; the batch orchestrator performs the deferred sync on the base ref.
+          # The sync itself is owned by record-feature-sync.ts (ADR-115: the guard plus the old
+          # inline chain cannot share one shell); resolution follows the standard in-repo-first,
+          # superskill-staged fallback used by every pipeline checker.
           - kind: shell
             options:
                 command: >-
-                    FID=$($spurBin task show $wbs --json 2>/dev/null | jq -r '.feature_id // .frontmatter.feature_id // empty' 2>/dev/null); if [ -z "$FID" ]; then echo "Orphan task $wbs — no feature_id linked — proposal: consider linking to a parent feature." >> ".spur/run/$wbs-report.txt"; elif [ -f plugins/sp/scripts/feature-sync-bounded.ts ]; then bun plugins/sp/scripts/feature-sync-bounded.ts "$FID" --spur-bin "$spurBin" --json; elif M="$(superskill script path sp feature-sync-bounded.mjs 2>/dev/null)" && [ -f "$M" ]; then node "$M" "$FID" --spur-bin "$spurBin" --json; else $spurBin feature sync "$FID" --json; fi; exit 0
+                    S=plugins/sp/scripts/record-feature-sync.ts; [ -f "$S" ] || S="$(superskill script path sp record-feature-sync.mjs 2>/dev/null)"; [ "$deferFeatureSync" = "true" ] && echo "feature sync deferred to batch integration" >> ".spur/run/$wbs-report.txt" || if [ -f "$S" ]; then bun "$S" --spur-bin "$spurBin"; else echo "feature sync skipped — record-feature-sync not found in plugins/sp/scripts/ nor staged" >> ".spur/run/$wbs-report.txt"; fi; exit 0
 
     - id: done
       description: >
@@ -595,6 +799,13 @@ states:
           guard runs `spur task check` before certifying; a genuinely non-compliant
           task routes to `failed` instead of a silent bad `done`.
       onEnter:
+          # (d) F96 R4 (0950): residual-scan.ts owns the settle; shell only resolves it.
+          # Soft best-effort (exit 0) — runs after certification and must never change
+          # the outcome; failure prints the re-run command.
+          - kind: shell
+            options:
+                command: >-
+                    S=plugins/sp/scripts/residual-scan.ts; [ -f "$S" ] || S="$(superskill script path sp residual-scan.mjs 2>/dev/null)"; if [ -f "$S" ]; then case "$S" in *.mjs) RUNNER=node ;; *) RUNNER=bun ;; esac; "$RUNNER" "$S" settle "$wbs" --spur-bin "$spurBin" || echo "residual-settle failed — re-run: residual-scan settle $wbs" >&2; else echo "residual-scan not staged — settle skipped — re-run: residual-scan settle $wbs" >&2; fi; exit 0
           # (c) command.gate owns the done transition with classified transient retry.
           - kind: command.gate
             options:
@@ -620,7 +831,28 @@ states:
     - id: failed
       description: >
           Terminal — precheck, quality-gate exhaustion, verify non-PASS, record check
-          failure, or operator rejection; reported, not advanced.
+          failure, or operator rejection; reported, not advanced. Also receives an
+          escalation-bound pause or an operator give-up (0933).
+      onEnter:
+          # 0933 R30 (guard-lines compression): the escalation-bound report note lives
+          # here as a conditional — no-op unless the run reached failed with a pending
+          # question at (or above) the ask bound (bound pause or final give-up). The
+          # unanswered question itself is appended to the task report (report.txt, R2).
+          - kind: shell
+            options:
+                command: >-
+                    n="$(cat .spur/run/$wbs-escalation-count 2>/dev/null || echo 0)";
+                    test "$n" -ge "$maxEscalations" -a -s .spur/run/$wbs-question.md || exit 0;
+                    printf '\n## Escalation bound reached\n\nThe implement step asked an operator question %s times (bound %s) and ended without a resumable answer. Unanswered question:\n\n' "$n" "$maxEscalations" >> .spur/run/$wbs-report.txt;
+                    cat .spur/run/$wbs-question.md >> .spur/run/$wbs-report.txt;
+                    exit 0
+          # (d) F96 R5 (0950): residual-scan.ts owns the report; shell only resolves it.
+          # Soft (exit 0): a run that exhausts its fix budget on residuals leaves the
+          # report + recovery line while the task stays `wip`.
+          - kind: shell
+            options:
+                command: >-
+                    S=plugins/sp/scripts/residual-scan.ts; [ -f "$S" ] || S="$(superskill script path sp residual-scan.mjs 2>/dev/null)"; if [ -f "$S" ]; then case "$S" in *.mjs) RUNNER=node ;; *) RUNNER=bun ;; esac; "$RUNNER" "$S" report "$wbs" --spur-bin "$spurBin" || echo "residual-report failed — re-run: residual-scan report $wbs" >&2; else echo "residual-scan not staged — report skipped — re-run: residual-scan report $wbs" >&2; fi; exit 0
 
     - id: cancelled
       description: Terminal — pipeline cancelled by operator at the approval gate (R1).
@@ -640,43 +872,85 @@ transitions:
                   test "$size_status" = PASS && test "$evidence_status" = PASS && $spurBin task check $wbs
     - from: precheck
       to: failed
+      terminalReason: failed-check
       description: Size and/or task check failed — stop before implement.
       guard:
           kind: always
 
+    # ── implement routing: escalation first (0933 R26/R30), then the linear body ──
+    # Declaration order matters: the escalation bound is checked FIRST — a paused
+    # attempt that already exhausted its maxEscalations asks routes to failed (with a
+    # report note appended in the same guard) instead of asking forever; then the
+    # question-presence hop; then the normal always edge. The bound guard requires a
+    # fresh question file so a COMPLETED implement after max asks still routes to test.
+    - from: implement
+      to: failed
+      terminalReason: retry-exhausted
+      description: Escalation bound exhausted — the agent paused again after maxEscalations operator answers.
+      # 0933 R30 (guard-lines compression): thin predicate; the report note is written
+      # by the failed state's onEnter when it observes a bound-exhausted pause.
+      guard:
+          kind: shell
+          options:
+              command: >-
+                  n="$(cat .spur/run/$wbs-escalation-count 2>/dev/null || echo 0)";
+                  test "$n" -ge "$maxEscalations" -a -s .spur/run/$wbs-question.md
+    - from: implement
+      to: escalate
+      description: Implement agent paused on an operator question (non-empty question file) — pause for an answer.
+      guard:
+          kind: shell
+          options:
+              command: 'test -s .spur/run/$wbs-question.md'
     # ── linear body ──
     - from: implement
       to: test
       description: Implementation done — quality-gate probe.
       guard:
           kind: always
-    # Soft probe branching (declaration order: PASS first, then FAIL, then defense).
-    - from: test
-      to: verify
-      description: Quality gate already green and mode is fast — proportional fast path bypasses review.
+    # escalate branching (0933 R27): an answered pause resumes implement — the transcript
+    # append and question consumption happen in implement's onEnter (guards stay thin
+    # under ADR-115 guard-lines caps); an empty answer is an operator give-up → failed
+    # (question + transcript preserved as evidence).
+    - from: escalate
+      to: implement
+      description: Operator answered — re-enter implement, which records the Q/A transcript and consumes the question.
       guard:
           kind: shell
           options:
-              command: >-
-                  gate_status="$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)";
-                  test "$gate_status" = PASS && test "$mode" = fast
+              command: 'test -n "$__hitlInput"'
+    - from: escalate
+      to: failed
+      terminalReason: cancelled
+      description: Empty operator answer — give-up routes to failed (question + transcript preserved as evidence).
+      guard:
+          kind: shell
+          options:
+              command: 'test -z "$__hitlInput"'
+    # Soft probe branching (declaration order: PASS → triage, FAIL → test-fail-triage, defense).
+    # 0943 R1/R3: the four former gate-PASS edges (test/test-recheck → verify/review, split on
+    # `$mode`) are replaced by the deterministic `triage` lane producer; a red gate lands in
+    # `test-fail-triage` where `decide failure-class` routes the failure instead of a static fixall.
     - from: test
-      to: review
-      description: Quality gate already green and safety mode — proceed to review.
+      to: triage
+      description: Quality gate green — route the lane deterministically (triage, 0943 R1).
       guard:
           kind: shell
           options:
               command: >-
                   gate_status="$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)";
-                  test "$gate_status" = PASS && test "$mode" != fast
+                  test "$gate_status" = PASS
     - from: test
-      to: test-fix
-      description: Quality gate red — start bounded fixall loop.
+      to: test-fail-triage
+      description: Quality gate red — classify the failure before the repair hop (0943 R3).
       guard:
           kind: shell
           options:
               command: 'test "$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)" = FAIL'
-    # Defense: missing/corrupt status — treat as FAIL path, not silent PASS.
+    # 0943 review P3#2: the former `test → test-fix` FAIL edge is removed — it was dead (the
+    # identical guard on test → test-fail-triage fires first) and a silent spec-bypass trap:
+    # restoring it would skip failure-class on every red gate. The always-defense below keeps
+    # pre-0943 corrupt-status behavior (fixall then recheck).
     - from: test
       to: test-fix
       description: Probe status missing/corrupt — attempt fixall then recheck.
@@ -687,51 +961,95 @@ transitions:
       description: Fixall finished — soft recheck the same quality gate.
       guard:
           kind: always
-    # Recheck branching (PASS first; under-max FAIL → fixall again; exhausted → failed).
+    # Recheck branching (PASS → triage; red → test-fail-triage; defense). The two former
+    # static FAIL edges (under-max → test-fix, exhausted → failed retry-exhausted) moved into
+    # test-fail-triage's decision routing (0943 R3).
     - from: test-recheck
-      to: verify
-      description: Quality gate green after fixall and mode is fast — proportional fast path bypasses review.
+      to: triage
+      description: Quality gate green after fixall — route the lane deterministically (triage, 0943 R1).
       guard:
           kind: shell
           options:
               command: >-
                   gate_status="$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)";
-                  test "$gate_status" = PASS && test "$mode" = fast
+                  test "$gate_status" = PASS
     - from: test-recheck
-      to: review
-      description: Quality gate green after fixall and safety mode — proceed to review.
+      to: test-fail-triage
+      description: Still red after fixall — classify the failure (0943 R3).
       guard:
           kind: shell
           options:
               command: >-
                   gate_status="$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)";
-                  test "$gate_status" = PASS && test "$mode" != fast
+                  test "$gate_status" = FAIL
+    # Defense: corrupt recheck status — failed, not review.
     - from: test-recheck
-      to: test-fix
-      description: Still red and under qualityGateMaxFixAttempts — another fixall hop.
-      # (warn) 5 commands: named gate status + fix attempts (legibility, 0874).
+      to: failed
+      terminalReason: failed-check
+      description: Recheck status missing/corrupt — stop at failed.
+      guard:
+          kind: always
+    # ── triage routing (0943 R1/R2): the lane producer replaced the four gate-PASS edges.
+    # mode=fast → verify; anything else (standard/high, deterministic-high, degraded default,
+    # caller-set non-fast) → review. Together the two guards are exhaustive, so triage never hangs.
+    - from: triage
+      to: verify
+      description: Triage resolved the fast lane (caller-set fast or task-triage low) — skip review.
+      guard:
+          kind: shell
+          options:
+              command: 'test "$mode" = fast'
+    - from: triage
+      to: review
+      description: Triage resolved a review lane (standard/high, deterministic-high, or caller-set) — review.
+      guard:
+          kind: shell
+          options:
+              command: 'test "$mode" != fast'
+    # ── failure-class routing (0943 R3): stop first (never mislabeled by the cap), then the
+    # attempt cap (bounds BOTH lanes — retryable counted on entry, fix as before), then the
+    # decision lanes, then the fail-closed defense. Declaration order matters.
+    - from: test-fail-triage
+      to: failed
+      terminalReason: failed-check
+      description: Failure class stop — the run terminates at failed, never bypassed.
       guard:
           kind: shell
           options:
               command: >-
-                  gate_status="$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)";
-                  fix_attempts="$(cat .spur/run/$wbs-test-fix-attempt 2>/dev/null || echo 0)";
-                  test "$gate_status" = FAIL && test "$fix_attempts" -lt "$qualityGateMaxFixAttempts"
-    - from: test-recheck
+                  jq -e '.value == "stop"' ".spur/run/$wbs-failure-class.decision" >/dev/null 2>&1
+    - from: test-fail-triage
       to: failed
-      description: Still red after max fixall attempts — stop at failed (not silent abort).
-      # (warn) 5 commands: named gate status + fix attempts (legibility, 0874).
+      terminalReason: retry-exhausted
+      description: Attempt cap reached — qualityGateMaxFixAttempts bounds the retryable recheck and fix lanes alike.
+      # (warn) 5 commands: named fix attempts (legibility, 0874).
       guard:
           kind: shell
           options:
               command: >-
-                  gate_status="$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)";
                   fix_attempts="$(cat .spur/run/$wbs-test-fix-attempt 2>/dev/null || echo 0)";
-                  test "$gate_status" = FAIL && test "$fix_attempts" -ge "$qualityGateMaxFixAttempts"
-    # Defense: corrupt recheck status — failed, not review.
-    - from: test-recheck
+                  test "$fix_attempts" -ge "$qualityGateMaxFixAttempts"
+    - from: test-fail-triage
+      to: test-recheck
+      description: Failure class retryable and under the cap — re-run the gate without fixall; the attempt was counted on entry.
+      guard:
+          kind: shell
+          options:
+              command: >-
+                  jq -e '.value == "retryable"' ".spur/run/$wbs-failure-class.decision" >/dev/null 2>&1
+    - from: test-fail-triage
+      to: test-fix
+      description: Failure class fix and under the cap — the bounded repair hop, as before.
+      guard:
+          kind: shell
+          options:
+              command: >-
+                  jq -e '.value == "fix"' ".spur/run/$wbs-failure-class.decision" >/dev/null 2>&1
+    # Defense: missing/corrupt failure-class decision — fail closed instead of silently repairing.
+    - from: test-fail-triage
       to: failed
-      description: Recheck status missing/corrupt — stop at failed.
+      terminalReason: failed-check
+      description: Failure-class decision missing/corrupt — stop at failed.
       guard:
           kind: always
     # ── review → approve, OR skip the HITL gate entirely when profile=auto (R4) ──
@@ -766,6 +1084,7 @@ transitions:
               command: 'test "$__hitlAnswer" = yes'
     - from: approve
       to: failed
+      terminalReason: cancelled
       description: Operator rejected at the approval gate — report and stop.
       guard:
           kind: shell
@@ -773,6 +1092,7 @@ transitions:
               command: 'test "$__hitlAnswer" = no'
     - from: approve
       to: cancelled
+      terminalReason: cancelled
       description: Operator cancelled at the approval gate.
       guard:
           kind: shell
@@ -821,6 +1141,7 @@ transitions:
                   test "$(cat .spur/run/$wbs-test-fix-attempt 2>/dev/null || echo 0)" -lt "$qualityGateMaxFixAttempts"
     - from: verify
       to: failed
+      terminalReason: retry-exhausted
       description: >-
           Non-PASS with the fix budget exhausted, or a PASS/missing/malformed verdict whose proof
           block is absent or mismatched (task 0703 R5) — block before done; defense catch-all so the
@@ -850,6 +1171,7 @@ transitions:
                   test "$verdict" = PASS && test "$proof_digest" = "$proofDigest"
     - from: record
       to: failed
+      terminalReason: failed-check
       description: Task check failed or proof evidence missing/malformed/mismatched — block before done.
       guard:
           kind: always