@gobing-ai/spur 0.3.92 → 0.3.94

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
     "plugins": [
         {
             "name": "sp",
-            "version": "0.3.92",
+            "version": "0.3.94",
             "source": "./plugins/sp"
         }
     ]

package/config/pipeline-budgets.json

@@ -48,13 +48,6 @@
             "tokenCostUsd": null,
             "source": "Coverage entry (0826 R2): the live definition's model-query count (extractResolvedWorkflowFacts, 2026-09-11). No real-run measurement yet: wall-clock and cost are unenforced until measured, never 0.",
             "decision": null
-        },
-        "decision-routing-example": {
-            "modelQueries": 0,
-            "wallClockMs": null,
-            "tokenCostUsd": null,
-            "source": "Coverage entry (0911): authoring example (config/workflows/decision-routing-example.yaml) enumerating `decision:` modes. Measured 0 model queries — the producer is a shell action, so the example runs with no provider (live count via loadQueryCounts, 2026-09-20). Not a pipeline humans run; wall-clock and cost unenforced, never 0.",
-            "decision": null
         }
     }
 }

package/config/plugin-scripts.json

@@ -36,6 +36,11 @@
             "contract": "standard",
             "twin": "idea-handoff.mjs"
         },
+        {
+            "rel": "wrapup-drift-probe.ts",
+            "contract": "standard",
+            "twin": "wrapup-drift-probe.mjs"
+        },
         {
             "rel": "wrapup-steps.ts",
             "contract": "standard",
@@ -96,6 +101,11 @@
             "rel": "surface-drift-inventory.ts",
             "contract": "repo-only"
         },
+        {
+            "rel": "task-diffstat.ts",
+            "contract": "standard",
+            "twin": "task-diffstat.mjs"
+        },
         {
             "rel": "task-evidence-precheck.ts",
             "contract": "repo-only"

package/config/rules/boundary/test-subpath-boundary.yaml

@@ -0,0 +1,48 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
+# Test-only subpath boundary — @gobing-ai/spur-app/testing and the app's testing/
+# module are for tests and the mock itself, never production sources (task 0975 R3).
+#
+# WHY: `@gobing-ai/spur-app/testing` (packages/app/src/testing/history-board-mock.ts)
+# is a test-only mock subpath (E82). A production import couples shipped code to a
+# fake, and it crept toward the server transport before 0961 severed the seam. The
+# evaluator's glob matcher is segment-aware with `*`/`**` only (no brace groups), so
+# the ts/tsx globs would need separate entries — the repo carries .ts sources only,
+# matching the dao-boundary precedent.
+#
+# Scope covers src trees only: `<workspace>/tests/**` directories stay outside, and
+# `packages/app/src/testing/**` (the mock's own home) is exempted explicitly.
+rules:
+  - id: no-testing-subpath-import
+    description: >
+      Production sources must not import the @gobing-ai/spur-app/testing subpath
+      (history-board mock, E82/0961). Tests under <workspace>/tests/** and the
+      packages/app/src/testing/** module itself are exempt.
+    severity: error
+    evaluator:
+      type: forbidden-import
+      config:
+        forbidden:
+          - specifier: "@gobing-ai/spur-app/testing"
+        scope:
+          include:
+            - "apps/**/src/**/*.ts"
+            - "packages/**/src/**/*.ts"
+          exclude:
+            - "packages/app/src/testing/**"
+
+  - id: no-relative-testing-module-import
+    description: >
+      packages/app production sources must not reach the testing/ module through
+      relative imports (from './testing/…' or '../…/testing…'). The testing/**
+      module itself and workspace tests/ directories are exempt.
+    severity: error
+    evaluator:
+      type: forbidden-import
+      config:
+        forbidden:
+          - pattern: "(?:from\\s+|import\\(\\s*)['\"](\\.\\.?/)+(?:[^'\"]*/)?testing(?:/|['\"])"
+        scope:
+          include:
+            - "packages/app/src/**/*.ts"
+          exclude:
+            - "packages/app/src/testing/**"

package/config/rules/strict/runtime-boundaries.yaml

@@ -73,6 +73,7 @@ rules:
 
             # Synchronous template & workflow resolvers:
             - "apps/cli/src/commands/task.ts" # sync loadTemplateContent/Bodies callbacks
-            - "packages/app/src/services/workflow-service.ts" # composition advisory source (0775: facts extracted from the live definition inside the synchronous validate path; the baseline snapshot sync read was retired)
+            - "packages/app/src/services/workflow-service.ts" # run-log/checkpoint reclamation realpath confinement (:988, :1014)
+            - "packages/app/src/workflow/run-record.ts" # confined sync run-record reads: realpath + fstat byte-window (moved from workflow-service.ts, 0962)
             - "apps/cli/src/release-ops.ts" # sync manifest/workspace reads + Bun.write rewrites inside the git release flow (task 0617); mirrors task.ts sync-template exemption
             - "apps/cli/src/version-carriers.ts" # sync manifest reads + Bun.write rewrites for registered release carriers (task 0854); mirrors release-ops.ts sync exemption

package/config/rules/structure/protected-files.yaml

@@ -37,6 +37,10 @@ rules:
             # this rule's include scope — scanning generated copies only adds noise
             # (e.g. `id: task-implement-transition` trips the sk- token shape).
             - "apps/cli/config/"
+            # `apps/cli/plugins/` is the same kind of gitignored build:bundle output — a staged
+            # npm copy of `plugins/`, itself outside the include scope. Minified generated libs
+            # there trip the api-key shape (0976: HEAD's inline-run.generated.mjs fires too).
+            - "apps/cli/plugins/"
 
   - id: no-unsafe-git-commands
     description: "Unsafe git commands (force-push, hard reset) can overwrite history or cause data loss (AGENTS.md CRITICAL safety)."

package/config/templates/AGENTS.md

@@ -95,6 +95,10 @@ It owns document responsibilities and maintenance; `00` owns architectural choic
 `01` product scope, and root `DESIGN.md` UI/UX. Use **`sp:doc-evolve`** for drift,
 sync and contract checks. Follow host/operator precedence.
 
+For new `docs/plans/` working records and `docs/design/` non-UI satellites, use the
+`sp:spur-dev` plan/design templates and document-authoring reference. Preserve legacy files' history
+and headings when revising them; `sp:spur-doctor` can propose safe upgrades.
+
 ### Doc map
 
 | File | Owns | Update when |

package/config/templates/docs/02_ROADMAP.md

@@ -16,6 +16,8 @@ sync: [T5, T6]
 
 Phase goals, order, dependencies and exits only. Detailed feature state belongs in the
 feature tool's index; task progress belongs in task records (constitution §6.3).
+Detailed proposals and investigations may live in dated `docs/plans/` working records;
+link accepted phase changes here without copying the plan.
 
 ## Phase 0 — Foundation
 

package/config/templates/docs/03_ARCHITECTURE.md

@@ -31,4 +31,6 @@ _(Describe the primary data path: input → processing → output. Name the seam
 <!--
 Describes the CURRENT architecture only. Future/accepted designs go in sections explicitly
 titled "(accepted design — ADR-NNN; not yet built)". Keep command/schema detail in 04 satellites and task delivery receipts in task records.
--->
+Use the `sp:spur-dev` design template for a new non-UI satellite; link it instead of copying its
+contract here.
+-->

package/config/templates/docs/04_DESIGN.md

@@ -16,6 +16,8 @@ sync: [T3, T9]
 
 Non-UI contract index (constitution §6.5). Keep signatures, schemas, defaults, errors
 and boundary behavior in the owning `docs/design/<slug>.md` satellite.
+Start a new satellite from the `sp:spur-dev` design template; distinguish proposed from current
+behavior and preserve existing headings when revising one.
 
 ## UI/UX boundary & DESIGN.md
 

package/config/templates/docs/99_PROJECT_CONSTITUTION.md

@@ -3,7 +3,7 @@ name: Project Constitution
 doc: 99_PROJECT_CONSTITUTION
 owns: PROCESS — how the key files are maintained
 authority: authoritative-on-process
-version: 1.7.0
+version: 1.8.0
 created_at: {{init-date}}
 updated_at: {{init-date}}
 edit_rules: 99 §6.8
@@ -70,11 +70,15 @@ size, approval, task count, or completion alone does not qualify it for an ADR (
 ### 4.2 Working layers (outside the authority chain)
 
 - Dated `docs/plans/` and `docs/reports/` files hold proposals, investigations, audits and evidence.
-  They record work; accepted conclusions take effect only in their proper owner.
+  They record work; accepted conclusions take effect only in their proper owner. New plan files use
+  ordinary Markdown with concise frontmatter and purpose, evidence, recommendation, and follow-up
+  as applicable; the `sp:spur-dev` plan template is a starting point, not a rigid schema.
 - Configured task folders hold requirements, implementation plans, results and verification,
   maintained through the task tool. Resolve their paths through that tool.
 - Existing project context or learning storage holds reusable lessons (§8).
 - `docs/design/` and `docs/features/` are governed detail layers (§4.5), not scratch storage.
+  New non-UI design satellites use the `sp:spur-dev` design template; revisions preserve existing
+  meaning and references.
 
 Preserve historical evidence and its dates. It may be linked for provenance, but current
 contracts must be understandable without treating an old plan or report as governing policy.
@@ -90,6 +94,8 @@ Use `authoritative` for `00`, `authoritative-on-scope` for `01`,
 `owns` must match §4.1 in meaning. Bump the minor version for substantive edits and refresh
 `updated_at` when content changes. Do not touch unrelated documents just to update a date.
 Keep one metadata block. Root entry/UI files may use their established native format.
+Plans and design satellites use lighter frontmatter for identity, truthful status and dates;
+legacy files without it remain valid and readable. Do not infer historical status from a template.
 
 ### 4.4 AGENTS.md synchronization
 
@@ -194,6 +200,8 @@ Keep the index short. Satellites own non-UI signatures, schemas, defaults, error
 and boundary behavior. Verify against registrations/contracts; prefer generated artifacts to
 manual copies. UI rules belong in root `DESIGN.md`; architectural rationale belongs in `00`/`03`.
 Separate proposed from current behavior. A completed task adds no delivery receipt here.
+Use the design template to structure new satellites around boundaries, contracts, invariants and
+compatibility. Preserve stable headings and historical claims when revising old ones.
 
 ### 6.6 `docs/05_FEATURES.md` + `docs/features/<feature-id>_<slug>.md`
 

package/config/workflow-candidates.json

@@ -1,7 +1,72 @@
 {
     "schemaVersion": 1,
     "note": "Workflow graph-change promotion candidates (task 0873, feature D62; ADR-076 amendment). A candidate is shadow-run against recorded real-run inputs and is promoted into the canonical definition or deleted by its named deadline — never left as a standing parallel <name>2.yaml. `verdict` is null while pending and is filled by `bun scripts/spur-dev.ts promotion evaluate <id>`; `promotion check` (spur-check-feature) fails any candidate still present past its deadline, any unreferenced parallel definition in config/workflows/, and (0877 R8) any retired definition with real (non-dry) terminal runs lacking a recorded decision in `retirements[]`.",
-    "candidates": [],
+    "candidates": [
+        {
+            "id": "task-pipeline-triage-lanes",
+            "canonical": "task-pipeline",
+            "deadline": "2026-11-24",
+            "createdAt": "2026-09-25",
+            "rationale": "0943 (feature D64): task-pipeline work routes by triage lane and failure class instead of static graphs. Between a green gate and the review/verify fork a deterministic `triage` state writes the diffstat (plugins/sp/scripts/task-diffstat.ts, numstat + untracked scan against the precheck-anchored run base), honors a caller-set mode verbatim (never overridden), pins the safety lane on sensitive paths (drizzle/, packages/config/, server auth basenames, *secret*, .github/, plugins/sp/hooks/, *.sql) or >400 changed lines with NO model call, otherwise consults `decide task-triage` (low → fast lane skips review; standard/high → review), and appends the route reason to .spur/memory/task-pipeline-routes.log (R5). On a red gate, `decide failure-class` routes retryable → test-recheck (attempt counted, qualityGateMaxFixAttempts still bounds), fix → test-fix, stop → failed(failed-check); missing/corrupt decision fails closed. Projected basis: the 0938 baseline (docs/reports/2026-09-workflow-cost-baseline.md) measured task-pipeline wall median 7983s over 1 real terminal run with agent.run median 0; the fast lane saves the review agent.run + wall on triage-low diffs, and retryable classification saves fixall hops (and their gate re-runs) on transient failures. Measurement gap honestly named: with workflow.decideDecisionMaker off (R4) triage degrades to standard lanes (diffstat-guard-sensitive/large still forced safety — pure shell, no model), so benefit only materializes with the flag on; per-lane route counts are observable post-merge in .spur/memory/task-pipeline-routes.log. Measured-benefit status: projected from 0938, NOT shadow-run-confirmed — plan step 5 (recorded-input shadow runs) is DEFERRED out of the 0943 session and tracked by this candidate's deadline; `promotion evaluate` runs post-merge. If it does not beat the baseline, it is reverted (ADR-076).",
+            "measurement": {
+                "workflow": "task-pipeline"
+            },
+            "delta": {
+                "agentRunCount": 0,
+                "baselineAgentRunCount": 0,
+                "note": "Structural graph agent.run count unchanged (no new model state); fast-lane runs save the existing review agent.run (1 fewer on triage-low diffs), retryable classification can save fixall fix hops. baselineAgentRunCount = 0938 task-pipeline agentRunCountMedian."
+            },
+            "verdict": null
+        },
+        {
+            "id": "check-dedup-task-pipeline",
+            "canonical": "task-pipeline",
+            "deadline": "2026-11-24",
+            "createdAt": "2026-09-25",
+            "rationale": "0940 (feature D64): the comprehensive check runs once at the quality boundary — no-progress rechecks skip the full gate to the probe path (check.skipped-no-progress) and review confirms the check receipt (check.reused) instead of re-running tests/lint. Projected basis: the 0938 baseline (docs/reports/2026-09-workflow-cost-baseline.md) measured task-pipeline wall median 7983s over 1 real terminal run with agent.run median 0; per-state rows cover only `record` (visits=0) — no test-recheck/review state-level wall deltas exist yet, so the benefit is projected as wall time (full-gate vs probe cost on no-progress loops, plus removed review-stage re-runs), not agent.run count. Measured-benefit status: projected from 0938, NOT shadow-run-confirmed; `promotion evaluate` runs post-merge against recorded runs. If it does not beat the baseline, it is reverted (ADR-076).",
+            "measurement": {
+                "workflow": "task-pipeline"
+            },
+            "delta": {
+                "agentRunCount": 0,
+                "baselineAgentRunCount": 0,
+                "note": "No agent.run delta by design: check dedup removes full-gate wall time on no-progress rechecks and model-stage re-runs, not model hops. baselineAgentRunCount = 0938 task-pipeline agentRunCountMedian."
+            },
+            "verdict": null
+        },
+        {
+            "id": "wrapup-drift-probe",
+            "canonical": "wrapup-pipeline",
+            "deadline": "2026-11-24",
+            "createdAt": "2026-09-25",
+            "rationale": "0944 (feature D64): a deterministic probe (plugins/sp/scripts/wrapup-drift-probe.ts) runs only when the caller leaves wrapup mode empty and projects mode=fast when no changed path matches a doc-owned surface (AGENTS.md doc map + docs/99_PROJECT_CONSTITUTION.md ownership table) and every task's Solution change map parsed — clean wraps then skip doc-sync via the existing fast edge (fast:drift-probe-clean), any doubt stays on the safety path. Projected basis: doc-sync costs exactly 1 agent.run per wrapup (wrapup-pipeline declares one model query; 0938 baseline docs/reports/2026-09-workflow-cost-baseline.json has 0 recorded wrapup runs — agentRunCountMedian null — so the 1 is structural, never a measured median). Measurement gap honestly named: skipping doc-sync also skips learnings capture (0607 R2 merge), so clean wraps lose per-task learnings rows; measured post-promotion by comparing .spur/memory/wrapup-routes.log fast:drift-probe-clean counts against captured <runId>-wrapup-learnings.md files. For 0946 (measurement-only confirmation): the 0938 snapshot carries per-state rows in states[] but history-anatomy has zero of them (0 recorded runs — only task-pipeline/record exists), and cache hit/miss disposition lives in the history-anatomy provenance stamp (0659/0660, history-anatomy-cache.ts), not in real-run-cost.ts; terminalReasonMix exists per workflow but history-anatomy's is empty. Measured-benefit status: projected from structure + 0938, NOT shadow-run-confirmed; `promotion evaluate` runs post-merge. If it does not beat the baseline, it is reverted (ADR-076).",
+            "measurement": {
+                "workflow": "wrapup-pipeline"
+            },
+            "delta": {
+                "agentRunCount": 0,
+                "baselineAgentRunCount": 1,
+                "note": "Clean wrap skips the single doc-sync agent.run (1 -> 0 for those wraps). baselineAgentRunCount = 1 structural doc-sync agent.run per wrapup run (wrapup-pipeline declares one model query — config/pipeline-budgets.json); the 0938 snapshot records 0 wrapup runs (agentRunCountMedian null), so no measured median exists yet."
+            },
+            "verdict": null
+        },
+        {
+            "id": "idea-pipeline-guard-legibility",
+            "canonical": "idea-pipeline",
+            "deadline": "2026-11-24",
+            "createdAt": "2026-09-25",
+            "rationale": "0945 (feature D64): the four idea-pipeline route guards (ac-generate/feature-check → system-design|decompose) read derived fact files (.spur/run/<runId>-idea-design-route.txt, <runId>-idea-ac-ready.status) written by one deterministic shell action at the end of both ac-generate and feature-check onEnter, instead of re-deriving design×needs_design and dual status reads inline — guards drop from 4-5 logical commands with (warn) markers to 3 predicates with no warn (ADR-115), and routing is proven identical by the executed truth-table test (idea-pipeline-routing.test.ts: the frozen pre-refactor guards are the oracle across profile × __hitlAnswer × design × needs_design × ac × coverage, 3456 cells, plus the guard-parity fixture refreshed per the 0874→0887 protocol). Projected basis: 0938 terminal-reason coverage for idea-pipeline is 100% classified for new runs (all nine failure-state edges declare terminalReason under 0937), so route outcomes stay measurable per terminalReason; this is projected from structure, NOT shadow-run-confirmed — promotion evaluate fills the verdict post-merge, and a losing candidate reverts (ADR-076).",
+            "measurement": {
+                "workflow": "idea-pipeline"
+            },
+            "verdict": null,
+            "delta": {
+                "agentRunCount": 6,
+                "baselineAgentRunCount": 6,
+                "note": "No agent.run delta by design: legibility derives the route facts in shell, model hops are unchanged (composition baseline modelQueries=6 in config/pipeline-budgets.json holds). baselineAgentRunCount = 0938 idea-pipeline agentRunCountMedian."
+            }
+        }
+    ],
     "retirements": [
         {
             "name": "planning-pipeline",
@@ -14,6 +79,12 @@
             "recordedBy": "ADR-076 (commit 017ac7a30)",
             "date": "2026-08-20",
             "rationale": "Standing parallel definition deleted with the D5-N fixture promotion bar; 5 real terminal runs retained in history."
+        },
+        {
+            "name": "decision-routing-example",
+            "recordedBy": "0946 (D64)",
+            "date": "2026-09-25",
+            "rationale": "Example-only authoring sample (0911 D7, retained-as-example 0921) retired per the mechanical catalogue rule (D64 design §10): zero real runs in the 0938 window (2026-06-01, run-record plane) and no live caller — only the plugin README catalogue row, a 0-query budget coverage entry and design/help doc mentions. YAML deleted; README row, budget entry and doc mentions removed; the decision-policy regression fixture moved to packages/app/tests/services/fixtures/decision-routing-example.yaml (workflow-service.test.ts decision-policy block). Its exit also dropped `hitl.select` from the live action union, so the inline-pipeline-parity-check DOCUMENTED set and driver mirror dropped it (parity contract). No run history deleted; 0 real terminal runs retained in history."
         }
     ]
 }

package/config/workflows/feature-verification.yaml

@@ -74,6 +74,7 @@ transitions:
         command: 'test "$(cat .spur/run/$__runId-feature-verification.status 2>/dev/null)" = PASS'
   - from: verify
     to: failed
+    terminalReason: failed-check
     description: Repo-wide checks failed (or the evidence is missing/corrupt) — stop at failed.
     guard:
       kind: always

package/config/workflows/history-anatomy.yaml

@@ -391,6 +391,7 @@ transitions:
         command: 'grep -q "^PASS$" .spur/run/$__runId-structure-gate.txt 2>/dev/null'
   - from: structure-gate
     to: failed
+    terminalReason: retry-exhausted
     description: Structure gate FAIL with the correction cap exhausted — never publish a malformed candidate.
     guard:
       kind: shell
@@ -418,6 +419,7 @@ transitions:
         command: '! tail -n 1 .spur/run/$__runId-validation.txt 2>/dev/null | grep -qx "Verdict: PASS" && test "$(cat .spur/run/$__runId-correction-count 2>/dev/null || echo 0)" -lt 2'
   - from: validate
     to: failed
+    terminalReason: retry-exhausted
     description: Validation FAIL with the correction cap exhausted — terminate without publishing.
     guard:
       kind: always

package/config/workflows/idea-pipeline.yaml

@@ -262,6 +262,23 @@ states:
               printf 'FAIL run=%s checker not found — run superskill install sp\n' "$__runId" | tee ".spur/run/$__runId-idea-coverage.reason" >&2;
               printf 'FAIL\n' > ".spur/run/$__runId-idea-coverage.status";
             fi
+      # 0945 R2: derive the route facts ONCE at this boundary (0769 pattern) — guards read these
+      # named files instead of re-deriving design×needs_design inline. The same command is
+      # duplicated in feature-check's onEnter (YAML has no include); byte-equality is
+      # test-pinned (idea-pipeline-routing.test.ts). Missing/corrupt needs-design JSON fails
+      # safe to `design`; readiness is PASS only when both recorded checks are PASS.
+      # (warn) 7 commands: two three-way `test && printf || printf` derivations over captured
+      # signal files (ADR-115); no model hop, no CLI re-run.
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run &&
+            { test "$design" = skip -o "$design" = auto -a "$(jq -r .needs_design .spur/run/$__runId-idea-needs-design.json 2>/dev/null)" = false &&
+            printf 'skip\n' > .spur/run/$__runId-idea-design-route.txt ||
+            printf 'design\n' > .spur/run/$__runId-idea-design-route.txt; } &&
+            { test "$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" = PASS -a "$(cat .spur/run/$__runId-idea-coverage.status 2>/dev/null)" = PASS &&
+            printf 'PASS\n' > .spur/run/$__runId-idea-ac-ready.status ||
+            printf 'FAIL\n' > .spur/run/$__runId-idea-ac-ready.status; }
 
   - id: feature-check
     description: >
@@ -286,6 +303,19 @@ states:
           prompt: "Feature check for ${vars.featureId}. Review the AC and confirm to proceed? Requirement coverage status: $(cat .spur/run/${vars.__runId}-idea-coverage.status 2>/dev/null || echo unknown) — reason: $(cat .spur/run/${vars.__runId}-idea-coverage.reason 2>/dev/null || echo n/a) (.spur/run/${vars.__runId}-idea-coverage.status[.reason]). (Failures route back to ac-generate for revision, capped at 3 retries.)"
           decision:
             mode: never
+      # 0945 R2: same writer as ac-generate's onEnter (byte-equal, test-pinned) — refreshes the
+      # derived route facts after the interactive gate so both entries into this boundary read
+      # consistent files; hitl.confirm only sets $__hitlAnswer.
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run &&
+            { test "$design" = skip -o "$design" = auto -a "$(jq -r .needs_design .spur/run/$__runId-idea-needs-design.json 2>/dev/null)" = false &&
+            printf 'skip\n' > .spur/run/$__runId-idea-design-route.txt ||
+            printf 'design\n' > .spur/run/$__runId-idea-design-route.txt; } &&
+            { test "$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" = PASS -a "$(cat .spur/run/$__runId-idea-coverage.status 2>/dev/null)" = PASS &&
+            printf 'PASS\n' > .spur/run/$__runId-idea-ac-ready.status ||
+            printf 'FAIL\n' > .spur/run/$__runId-idea-ac-ready.status; }
 
   - id: system-design
     description: >
@@ -567,6 +597,7 @@ transitions:
         command: 'test "$(cat .spur/run/$__runId-idea-precheck-doctor.status 2>/dev/null)" = PASS'
   - from: start
     to: failed
+    terminalReason: failed-check
     description: Agent doctor FAIL — stop before discovery.
     guard:
       kind: always
@@ -606,6 +637,7 @@ transitions:
         command: 'test "$__hitlAnswer" = yes'
   - from: idea-eval
     to: cancelled
+    terminalReason: cancelled
     description: Idea evaluation rejected or cancelled — no feature created.
     guard:
       kind: shell
@@ -621,9 +653,11 @@ transitions:
 
   # ── ac-generate: auto-skip (profile=auto) OR enter feature-check HITL gate (interactive) ──
   # Declaration order: auto-skip guards tried FIRST (same pattern as task-pipeline review→verify
-  # and design-gen→handoff). Under profile=auto, the recorded `idea-ac-check` result and the
-  # recorded requirement-coverage status (0887 R4) route directly to the appropriate next
-  # state — guards never re-run the CLI or the checker (task 0769). Under interactive, the
+  # and design-gen→handoff). Under profile=auto, the derived route facts — the ready file (both
+  # recorded checks PASS, 0887 R4) and the design route file (0945 R2 writer at the end of both
+  # ac-generate and feature-check onEnter) — route directly to the appropriate next state:
+  # guards never re-run the CLI or the checker and never re-derive the signals (task 0769).
+  # Under interactive, the
   # always fallback enters the feature-check state whose onEnter hitl.confirm pauses for
   # operator confirmation (coverage is surfaced in that prompt; the operator's answer governs).
   #
@@ -631,25 +665,29 @@ transitions:
   - from: ac-generate
     to: system-design
     description: "profile=auto, check passed, requirements covered, design route — run system design."
-    # (warn) 4 commands: one persistent multi-assignment line captures both statuses; `test -a` folds the
-    # profile/ac and design/needs pairs (same operand semantics); guards never re-run the CLI (0769).
+    # 0945 R3: three predicates over derived facts — the ready file folds both recorded check
+    # statuses (PASS only when ac-check AND coverage are PASS), the route file folds
+    # design×needs_design (fail-safe design); nothing re-runs, nothing re-derives (0769).
     guard:
       kind: shell
       options:
         command: >-
-          ac_status="$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" cov_status="$(cat .spur/run/$__runId-idea-coverage.status 2>/dev/null)";
-          test "$profile" = auto -a "$ac_status" = PASS && test "$cov_status" = PASS && test "$design" = auto -a "$(jq -r .needs_design .spur/run/$__runId-idea-needs-design.json 2>/dev/null)" != false
+          test "$profile" = auto &&
+          test "$(cat .spur/run/$__runId-idea-ac-ready.status 2>/dev/null)" = PASS &&
+          test "$(cat .spur/run/$__runId-idea-design-route.txt 2>/dev/null)" = design
   # Auto-skip 2: pass + coverage + skip-design route → decompose
   - from: ac-generate
     to: decompose
     description: "profile=auto, check passed, requirements covered, skip-design route — go directly to decompose."
-    # (warn) 4 test segments: profile + inlined ac/coverage reads + the OR'd design=skip/(design=auto AND
-    # needs_design=false) pair folded into one `test` (`-a` binds tighter than `-o`), keeping one captured
-    # signal file authoritative for both routes (0769).
+    # 0945 R3: mirror of the design-route guard over the same derived facts with route=skip;
+    # one captured signal file per fact keeps both routes symmetric (0769).
     guard:
       kind: shell
       options:
-        command: 'test "$profile" = auto && test "$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" = PASS && test "$(cat .spur/run/$__runId-idea-coverage.status 2>/dev/null)" = PASS && test "$design" = skip -o "$design" = auto -a "$(jq -r .needs_design .spur/run/$__runId-idea-needs-design.json 2>/dev/null)" = false'
+        command: >-
+          test "$profile" = auto &&
+          test "$(cat .spur/run/$__runId-idea-ac-ready.status 2>/dev/null)" = PASS &&
+          test "$(cat .spur/run/$__runId-idea-design-route.txt 2>/dev/null)" = skip
   # Auto-skip 3: check or coverage failed, retry < 3 → loop back to ac-generate (self-loop)
   - from: ac-generate
     to: ac-generate
@@ -666,6 +704,7 @@ transitions:
   # Auto-skip 4: check or coverage failed, retry cap reached → escalate to failed
   - from: ac-generate
     to: failed
+    terminalReason: retry-exhausted
     description: "profile=auto, check or coverage failed after 3 retries — escalate to failed."
     # (warn) 5 commands: mirror of the retry guard with cap>=3; keeping escalation and retry as one
     # test-chain pair makes the cap boundary auditable in the diff (0769).
@@ -687,23 +726,27 @@ transitions:
   - from: feature-check
     to: system-design
     description: Feature check passed, design route — run system design.
-    # (warn) 5 commands (named status capture + 4 conditions): HITL answer + captured status + design route; same shape as the
-    # ac-generate auto-skips, reading the same captured signal files (0769).
+    # 0945 R3: three predicates over derived facts — the recorded ac-check status stays the
+    # conjunct here (parity: the operator's answer governs the interactive gate, 0887), the
+    # route file folds design×needs_design (fail-safe design); nothing re-runs (0769).
     guard:
       kind: shell
       options:
         command: >-
-          ac_status="$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)";
-          test "$__hitlAnswer" = yes && test "$ac_status" = PASS && test "$design" = auto && test "$(jq -r .needs_design .spur/run/$__runId-idea-needs-design.json 2>/dev/null)" != false
+          test "$__hitlAnswer" = yes &&
+          test "$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" = PASS &&
+          test "$(cat .spur/run/$__runId-idea-design-route.txt 2>/dev/null)" = design
   - from: feature-check
     to: decompose
     description: Feature check passed, skip-design route — go directly to decompose.
-    # (warn) 5 test segments: same as the feature-check design route plus the OR'd
-    # design=auto/needs_design=false pair (0769).
+    # 0945 R3: mirror of the design-route guard over the same derived facts with route=skip.
     guard:
       kind: shell
       options:
-        command: 'test "$__hitlAnswer" = yes && test "$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" = PASS && (test "$design" = skip || (test "$design" = auto && test "$(jq -r .needs_design .spur/run/$__runId-idea-needs-design.json 2>/dev/null)" = false))'
+        command: >-
+          test "$__hitlAnswer" = yes &&
+          test "$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" = PASS &&
+          test "$(cat .spur/run/$__runId-idea-design-route.txt 2>/dev/null)" = skip
   - from: feature-check
     to: ac-generate
     description: "Feature check failed — revise AC (retry cap: 3)."
@@ -717,6 +760,7 @@ transitions:
           (test "$__hitlAnswer" = no || test "$ac_status" != PASS) && test "$(cat .spur/run/$__runId-idea-ac-retry-count 2>/dev/null || echo 0)" -lt 3
   - from: feature-check
     to: failed
+    terminalReason: retry-exhausted
     description: Feature check failed after 3 retries — escalate to failed.
     # (warn) 5 commands (named status capture + 4 conditions): mirror of the revise guard with cap>=3 (0769).
     guard:
@@ -727,6 +771,7 @@ transitions:
           (test "$__hitlAnswer" = no || test "$ac_status" != PASS) && test "$(cat .spur/run/$__runId-idea-ac-retry-count 2>/dev/null || echo 0)" -ge 3
   - from: feature-check
     to: cancelled
+    terminalReason: cancelled
     description: Operator cancelled the feature-check gate.
     guard:
       kind: shell
@@ -772,6 +817,7 @@ transitions:
         command: 'test "$__hitlAnswer" = no && test "$(cat .spur/run/$__runId-idea-design-reject-count 2>/dev/null || echo 0)" -le 1'
   - from: design-approval
     to: failed
+    terminalReason: retry-exhausted
     description: "Design rejected after 1 revise - design-approval gate exhausted (R7 0433)."
     guard:
       kind: shell
@@ -779,6 +825,7 @@ transitions:
         command: 'test "$__hitlAnswer" = no && test "$(cat .spur/run/$__runId-idea-design-reject-count 2>/dev/null || echo 0)" -gt 1'
   - from: design-approval
     to: cancelled
+    terminalReason: cancelled
     description: Operator cancelled design approval.
     guard:
       kind: shell
@@ -816,6 +863,7 @@ transitions:
         command: 'test "$__hitlAnswer" = no'
   - from: batch-create
     to: cancelled
+    terminalReason: cancelled
     description: Operator cancelled batch creation.
     guard:
       kind: shell
@@ -845,6 +893,7 @@ transitions:
         command: 'test -f .spur/run/$__runId-idea-batch-create.failed && test "$(cat .spur/run/$__runId-idea-decompose-retry-count 2>/dev/null || echo 0)" -lt 3'
   - from: batch-create-run
     to: failed
+    terminalReason: retry-exhausted
     description: Batch-create failed after 3 retries — escalate to failed.
     guard:
       kind: shell

package/config/workflows/pr-review.yaml

@@ -223,6 +223,7 @@ transitions:
         command: 'test "$(cat .spur/run/$__runId-pr-preflight.status 2>/dev/null)" = PASS'
   - from: preflight
     to: failed
+    terminalReason: failed-check
     description: Preflight red (detached HEAD, dirty tree, gh auth, no GitHub remote, or the current branch being the base branch) — stop before any publishing
     guard:
       kind: always
@@ -236,6 +237,7 @@ transitions:
         command: 'grep -qE "^(PASS|WARN)$" .spur/run/$__runId-pr-hygiene.status 2>/dev/null'
   - from: hygiene
     to: failed
+    terminalReason: failed-check
     description: BLOCK (secrets/.env/conflict markers) or probe failure — never submit a tainted diff
     guard:
       kind: always
@@ -249,6 +251,7 @@ transitions:
         command: 'grep -qE "^(PASS|SKIP)$" .spur/run/$__runId-pr-precheck.status 2>/dev/null'
   - from: precheck
     to: failed
+    terminalReason: failed-check
     description: Project checks red — do not spend a review request on code that fails its own gate
     guard:
       kind: always
@@ -262,6 +265,7 @@ transitions:
         command: 'grep -qE "^(PUSHED|UP_TO_DATE)$" .spur/run/$__runId-pr-push.status 2>/dev/null'
   - from: push
     to: failed
+    terminalReason: failed-check
     description: Push rejected (e.g. non-fast-forward) — report; never force-push as a workaround
     guard:
       kind: always
@@ -275,6 +279,7 @@ transitions:
         command: 'grep -qE "^(FOUND|CREATED)$" .spur/run/$__runId-pr-ensure.status 2>/dev/null'
   - from: ensure-pr
     to: failed
+    terminalReason: failed-check
     description: No reviewable delta or PR creation failed — report the actual git/GitHub state
     guard:
       kind: always
@@ -306,6 +311,7 @@ transitions:
         command: 'test "$(cat .spur/run/$__runId-pr-request.status 2>/dev/null)" = REQUESTED'
   - from: request
     to: failed
+    terminalReason: failed-check
     description: Request failed (no PR, gh error) — report the preserved error
     guard:
       kind: always
@@ -326,6 +332,7 @@ transitions:
         command: 'test "$(cat .spur/run/$__runId-pr-wait.status 2>/dev/null)" = TIMEOUT'
   - from: wait
     to: failed
+    terminalReason: failed-check
     description: Poll probe itself failed
     guard:
       kind: always
@@ -346,6 +353,7 @@ transitions:
         command: 'test "$(cat .spur/run/$__runId-pr-collect.status 2>/dev/null)" = PENDING'
   - from: collect
     to: failed
+    terminalReason: failed-check
     description: Collect probe failed
     guard:
       kind: always