@gobing-ai/spur 0.4.14 → 0.4.16

package/config/workflows/idea-pipeline.yaml

@@ -1,67 +1,48 @@
-# Idea-to-feature pipeline — unified entry from a vague idea to a feature, AC, and task batch
-# (design §idea-pipeline).
+# Idea-to-feature pipeline — unified entry from a vague idea to a feature, AC, and a task batch
+# (design docs/design/workflow-consolidation.md §3.4). YAML over the dual-workflow engine; zero new
+# engine code. The pipeline STOPS at handoff — tasks are created but NOT executed; use
+# task-pipeline.yaml for execution. No state inlines another pipeline's state graph.
 #
-# Orchestration is configuration (ADR-022 / §3.2): this is YAML over the existing
-# dual-workflow engine — zero new engine code. The pipeline STOPS at handoff — tasks are
-# created but NOT executed. Use task-pipeline.yaml or feature-dev.yaml for execution.
-# No state in this pipeline inlines another pipeline's state graph (no-nesting principle,
-# design §System Principles 4).
+# Shape: start -> discovery -> idea-eval -> feature-create -> ac-generate
+#        -> system-design (conditional: needs_design signal) -> design-approval (taste)
+#        -> decompose -> batch-create-run -> ready-prepare -> handoff-finalize -> handoff.
+#        idea-eval rejection (or auto + `drop`) -> cancelled; ac-generate check failure and
+#        batch-create failure -> their own capped retry loops -> failed.
 #
-# Shape: start -> discovery -> idea-eval -> feature-create -> ac-generate -> feature-check
-#          -> system-design (conditional: needs_design signal)
-#          -> design-approval (taste HITL gate; bypassed only when design_approved=true + design check PASS)
-#          -> decompose -> batch-create -> handoff-finalize -> handoff
-#        (idea-eval rejection, or auto + `drop` recommendation -> cancelled)
-#        (feature-check failure routes back to ac-generate; batch-create failure to decompose).
+# D66 1250 (design §3.4): the objective checks carry no operator pause. `feature-check` and
+# `batch-create` are DELETED — their recorded results are deterministic PASS/FAIL, which every
+# profile now routes on directly, so the former `profile=auto` predicates and the always fallbacks
+# into those states are gone. The two discovery rescues are typed `decide` actions over the catalog
+# ids in config/decisions/idea-pipeline.yaml (rescue-only, design §4): the deterministic parse runs
+# first and the decide is consulted only for output the parse cannot classify. `idea-eval` and
+# `design-approval` stay operator gates (taste). The start-state entry check is EXECUTOR-TYPED: a
+# host run's executor is the session itself (no subprocess doctor), and a fleet run is ready exactly
+# when this host wired fleet dispatch (ADR-126).
 #
-# Evidence instead of ceremony (task 0769): the feature check is MEASURED exactly once at
-# each author/revise boundary — `idea-ac-check` at the end of ac-generate, `idea-design-check`
-# at the end of system-design — by a deterministic `command.gate` writing a run-scoped
-# PASS/FAIL result file. Transition guards only CONSUME the recorded result (run-scoped path,
-# no CLI re-run per guard); a gate re-runs only after a relevant write (revision pass) or on
-# the next boundary.
+# Evidence instead of ceremony (task 0769): the feature check is MEASURED once at each author/revise
+# boundary — `idea-ac-check` at the end of ac-generate, `idea-design-check` at the end of
+# system-design — by a deterministic `command.gate` writing a run-scoped PASS/FAIL result file.
+# Guards only CONSUME the recorded result; no guard re-runs the CLI.
 #
-# Vars (passed as a JSON object via `--vars`):
-#   idea     — the idea text (required), e.g. --vars '{"idea":"add a --dry-run flag to dev-wrap"}'
-#   profile  — set --vars '{"profile":"auto"}' to skip objective HITL gates (feature-check, batch-create)
-#   design   — "auto" (default, signal-driven) or "skip" (--skip-design). No force path.
-#              Unified: skip also means omit per-task Design in batch-create (scaffold only;
-#              refine fills later). Default: decompose must author batch item `design`.
-#   design_approved — "true" lets profile=auto route around the design-approval taste gate when
-#              the recorded design check PASSes (default "false")
-#   idea_approved — "true" lets profile=auto accept the idea-eval report's recommendation
-#              (proceed/reshape → continue, drop → cancelled; missing → pause) (default "false")
-#   CLI --auto on dev-idea / dev-plan sets profile=auto AND both pre-clear vars to true.
-#   spurBin  — PATH-independent spur invocation (overridden by CLI at run start)
-#   agent    — agent for agent.run steps (default: auto → `agent.default` in config)
-#
-# Reliability (aligned with task-pipeline / ADR-043):
-#   - Soft agent doctor at start → failed via transitions (not raw lifecycle abort)
-#   - expectFile on feature-create / ac-generate / decompose artifacts (no silent no-ops)
-#   - Caped AC and batch-create retry loops with fail-closed escalation
-#   - HITL taste gates (idea-eval, design-approval) exhaustive yes/no/cancel
-#   - Free-form skill pointers remain only where no pure slash surface exists yet
-#     (discovery/sys-architecture/decompose internals — residual until dedicated commands)
-#
-# Seeded by `spur init`; adapt the agent.run inputs to your project's command set.
+# Vars (`--vars '{"idea":"…"}'`): idea (required); profile ("auto" skips the taste gates' questions —
+# they answer from recorded evidence — while the objective stages route identically under every
+# profile); design ("auto" default signal-driven | "skip", which also omits per-task Design);
+# design_approved / idea_approved ("true" lets profile=auto route around that taste gate, default
+# "false"); spurBin; agent (agent.run steps; default auto → `agent.default`); executor ("host" |
+# "fleet" | "" for the tier ladder — read by the entry check and every agent.run stage).
+# CLI --auto on dev-idea / dev-plan sets profile=auto AND both pre-clear vars to true.
 
 "$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
-version: "2"
 kind: state-machine
 name: idea-pipeline
-description: "Idea to feature + AC + task batch: discovery, idea-eval, feature-create, ac-generate, feature-check, system-design, decompose, batch-create, handoff"
-# Worst legal auto path with advertised caps: start/discovery/idea-eval/feature/ac plus 2 AC
-# retries, design, one design rejection, decompose plus 2 batch retries, handoff ≈24 transitions.
-# Keep a small cushion so the explicit retry caps fail first, not the engine bound.
+version: "3"
+description: "Idea to feature + AC + task batch: discovery, idea-eval, feature-create, ac-generate, system-design, decompose, ready-prepare, handoff"
+# Worst legal path with advertised caps ≈20 transitions; the cushion keeps the explicit retry caps
+# failing first, not the engine bound.
 iterationBound: 25
 initialState: start
-terminalStates:
-  - handoff
-  - cancelled
-  - failed
-failureStates:
-  - failed
-  - cancelled
+terminalStates: [handoff, cancelled, failed]
+failureStates: [failed, cancelled]
 vars:
   idea: ""
   profile: "standard"
@@ -76,26 +57,16 @@ vars:
   agent: "auto"
   planningAgent: ""
   stepTimeoutMs: "1800000"
-  # Executor for every agent.run stage (D65 R1): "host" pauses the run with a work item
-  # (`spur workflow run|continue --json`), "fleet" dispatches through ADR-126, and empty
-  # resolves the subprocess surface through the existing tier ladder.
+  # Executor for every agent.run stage (D65 R1): "host" pauses the run with a work item, "fleet"
+  # dispatches through ADR-126, empty resolves the subprocess surface through the tier ladder.
   executor: ""
   # Accepted/deferred status each operator gate's decision binding writes (1236 R2).
   ideaEvalStatus: ""
-  featureCheckStatus: ""
   designApprovalStatus: ""
-  batchCreateStatus: ""
 
 states:
   - id: start
-    display:
-      phase: discover
-      phaseTitle: Discover
-      title: Check inputs
-    description: >
-      Pipeline start. The idea text arrives as vars.idea. The pipeline stops at
-      handoff — no task execution. Soft agent doctor (status file) so doctor red
-      routes to `failed` via transitions instead of a raw lifecycle abort.
+    description: "One executor-typed entry check (D66 1250 R1): the executor-aware doctor.probe writes the executor verdict and the idea-text check writes its own named reason to the SAME status file, so a single token routes."
     onEnter:
       - kind: note
         options:
@@ -107,8 +78,8 @@ states:
           agent: "${vars.agent}"
           role: planner
           resolvedAgentVar: planningAgent
-          # B7 R1 (0894): also pin the role once — __executor.planner feeds stage
-          # dispatch so no later idea stage re-walks the doctor ladder.
+          # B7 R1 (0894): also pin the role once — __executor.planner feeds stage dispatch so no
+          # later idea stage re-walks the doctor ladder.
           roles:
             planner: "${vars.agent}"
       - kind: shell
@@ -117,101 +88,81 @@ states:
             mkdir -p .spur/run &&
             printf '%s\n' "$idea" > ".spur/run/$__runId-idea-input.md" &&
             awk 'NF' ".spur/run/$__runId-idea-input.md" | grep -q . ||
-            printf 'FAIL\n' > ".spur/run/$__runId-idea-precheck-doctor.status"
+            printf 'FAIL: idea text is empty\n' > ".spur/run/$__runId-idea-precheck-doctor.status"
 
   - id: discovery
-    display:
-      phase: discover
-      phaseTitle: Discover
-      title: Discovery interview
-    description: >
-      Dispatch sp:brainstorm to explore the idea, generate approaches with trade-offs,
-      and record a design summary. The brainstorm ALWAYS records a design summary
-      ("nothing is too simple" pattern). The brainstorm also emits a needs_design
-      boolean signal written to .spur/run/${vars.__runId}-idea-needs-design.json — this determines
-      whether the system-design state runs. As its terminal artifact for the idea path,
-      brainstorm also emits the idea-evaluation report to .spur/run/${vars.__runId}-idea-eval-report.md
-      (template: the `sp:spur-dev` skill's `idea-evaluation` reference — named by skill, not by
-      repo path, because `spur init` never scaffolds `plugins/sp/` into a seeded project).
-      The operator's verbatim idea argument is persisted at .spur/run/${vars.__runId}-idea-input.md
-      (written by start; the authoritative ask every model-bearing stage reads).
-      expectFile fails a silent no-op discovery (no eval report).
+    description: "Dispatch sp:brainstorm: approaches with trade-offs, a design summary, the needs_design signal, and the idea-evaluation report (.spur/run/${vars.__runId}-idea-eval-report.md, per the `sp:spur-dev` `idea-evaluation` reference — named by skill, not repo path). The operator's verbatim idea is persisted at .spur/run/${vars.__runId}-idea-input.md by start. expectFile fails a silent no-op discovery. D66 1250 R3: the two rescues are typed `decide` actions whose projections keep the pre-1250 fallback semantics."
     onEnter:
       - kind: agent.run
         options:
           agent: ${vars.planningAgent}
           input: "The operator's ask of record is .spur/run/${vars.__runId}-idea-input.md — idea persisted verbatim at start; authoritative, read it first (${vars.idea} is a convenience echo). Run sp:brainstorm. The skill owns the approach-generation, design summary, and `needs_design` signal criteria; emit .spur/run/${vars.__runId}-idea-needs-design.json ({\"needs_design\": true|false}) plus the design summary per its `Design Approval Gate` / `The needs_design signal` sections. Also emit the idea-evaluation report to .spur/run/${vars.__runId}-idea-eval-report.md per the `sp:spur-dev` skill's `idea-evaluation` reference (urgency/necessity 0–5, premises, pros/cons, alternatives, enhanced idea, recommendation, plus mandatory `## Requirement inventory`: numbered I<n> items quoting/paraphrasing idea-input lines; `[unclear: ...]` marks ambiguity, `[deferred: <reason>]` marks out-of-scope). End with this exact footer: `---\\nrun_id: ${vars.__runId}\\ngenerated_at: <RFC3339>\\n---` (omit if run_id is empty)."
-          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          # Declared Layer-1 role (0538 R2) + declared fresh policy (B7 R6 / 0894).
           role: planner
-          # B7 R6 (0894): planner stages declare fresh — the role default is stated
-          # explicitly so the definition is self-documenting.
           session: fresh
           expectFile: .spur/run/${vars.__runId}-idea-eval-report.md
-          # The signal is this stage's own output; the plural form declares it to the
-          # work item (host/fleet) while the singular expectFile stays the subprocess
-          # post-exit guard, so a missing signal still falls back to the catalog decision.
+          # The signal is this stage's own output; the plural form declares it to the work item
+          # (host/fleet) while the singular expectFile stays the subprocess post-exit guard.
           expectFiles:
             - .spur/run/${vars.__runId}-idea-needs-design.json
           timeoutMs: ${vars.stepTimeoutMs}
       # Derive the eval recommendation ONCE (0769 pattern): the first non-blank line under
-      # `## Recommendation` → proceed | reshape | drop | unknown. The --auto guards out of
-      # discovery / idea-eval read this file; `unknown` routes to the idea-eval pause.
+      # `## Recommendation` → proceed | reshape | drop | unknown. `unknown` routes to idea-eval.
       - kind: shell
         options:
           command: >-
             awk '/^## Recommendation/{f=1;next} f&&NF{r=tolower($0);exit}
             END{print (match(r,/^[*_ ]*(proceed|reshape|drop)/) ? substr(r,RSTART,RLENGTH) : "unknown")}'
             ".spur/run/$__runId-idea-eval-report.md" | tr -d '*_ ' > ".spur/run/$__runId-idea-recommendation.txt"
-      # 1097 R2 (design §4 rescue-only): the awk parse stays first; this rescue runs ONLY when
-      # the derived file is `unknown`. A model answer is written only when `source == "model"`
-      # and it lands in the closed vocabulary (proceed|reshape|drop) — every other outcome
-      # (spur missing/non-zero, unparseable output, model `unknown`) leaves `unknown` in place,
-      # which is today's idea-eval pause route. Exits 0 on every path (default onError: fail).
+      # D66 1250 R3 (design §4 rescue-only): the awk parse above stays FIRST; this typed decide
+      # replaces the former `spur decision run` shell and is consulted only for unclassifiable
+      # output. It writes the frozen schemaVersion-1 row.
+      - kind: decide
+        options:
+          id: idea-recommendation
+          decision: idea-recommendation
+          evidence:
+            - .spur/run/${vars.__runId}-idea-eval-report.md
+          resultFile: .spur/run/${vars.__runId}-idea-recommendation.decision
+      # Projection (1250 R3): a non-model source (switch off, backend failure, low confidence) reads
+      # `unknown`, so no default can auto-create a feature — it routes to the idea-eval pause.
       - kind: shell
         options:
           command: >-
             f=".spur/run/$__runId-idea-recommendation.txt";
             [ "$(cat "$f" 2>/dev/null)" = unknown ] || exit 0;
-            v="$($spurBin decision run idea-recommendation --evidence ".spur/run/$__runId-idea-eval-report.md" --json 2>/dev/null | jq -r 'if .source=="model" then .value else "unknown" end' 2>/dev/null)";
+            v="$(jq -r 'if .source=="model" then .value else "unknown" end' ".spur/run/$__runId-idea-recommendation.decision" 2>/dev/null)";
             case "$v" in proceed|reshape|drop) printf '%s\n' "$v" > "$f" ;; esac
-      # 1097 R3 (same rescue-only pattern): a valid needs_design boolean short-circuits — no
-      # decision is called. On a missing/corrupt/non-boolean file the catalog decision decides:
-      # `{"needs_design": false}` only when `source == "model"` AND `value == "skip"`; otherwise
-      # `{"needs_design": true}` — today's behavior for a missing or corrupt file. The
-      # ac-generate route writer (:274) consumes this file unchanged. Exits 0 on every path.
+      # D66 1250 R3: the same shape for the design signal — a valid boolean short-circuits in the
+      # projection; otherwise it falls back to `design` unless the model said `skip`.
+      - kind: decide
+        options:
+          id: needs-design
+          decision: needs-design
+          evidence:
+            - .spur/run/${vars.__runId}-idea-eval-report.md
+          resultFile: .spur/run/${vars.__runId}-idea-needs-design.decision
       - kind: shell
         options:
           command: >-
             f=".spur/run/$__runId-idea-needs-design.json";
             jq -e '.needs_design|type=="boolean"' "$f" >/dev/null 2>&1 && exit 0;
-            $spurBin decision run needs-design --evidence ".spur/run/$__runId-idea-eval-report.md" --json 2>/dev/null | jq -e '.source=="model" and .value=="skip"' >/dev/null 2>&1 && printf '{"needs_design": false}\n' > "$f" || printf '{"needs_design": true}\n' > "$f"
+            jq -e '.source=="model" and .value=="skip"' ".spur/run/$__runId-idea-needs-design.decision" >/dev/null 2>&1 &&
+            printf '{"needs_design": false}\n' > "$f" || printf '{"needs_design": true}\n' > "$f"
 
   - id: idea-eval
-    display:
-      phase: discover
-      phaseTitle: Discover
-      title: Evaluate idea
-    description: >
-      HITL taste gate. Discovery has produced the idea-evaluation report
-      (.spur/run/${vars.__runId}-idea-eval-report.md) with urgency/necessity scores, premises,
-      pros/cons, and a recommendation. The operator reviews and approves or
-      rejects. Routed around only when profile=auto AND vars.idea_approved=true
-      (CLI --auto) AND the report's recommendation is proceed/reshape; a drop
-      recommendation cancels, a missing one asks the gate, whose evidence binding then
-      answers under profile=auto (1236/1241).
+    description: "HITL taste gate over the idea-evaluation report. Routed around only when profile=auto AND vars.idea_approved=true AND the recommendation is proceed/reshape; a drop recommendation cancels and a missing one asks the gate, whose evidence binding then answers under profile=auto (1236/1241)."
     onEnter:
       - kind: hitl.confirm
         options:
           prompt: "Review the idea evaluation report (.spur/run/${vars.__runId}-idea-eval-report.md). Approve to create a feature, or reject to cancel? (Reject creates no feature.)"
-          # Interactive always prompts the operator; profile=auto answers from the discovery
-          # stage's recorded evidence, deferring when it cannot decide (1236 R1/R2).
           decision:
             mode: evidence
             statusVar: ideaEvalStatus
             evidenceNodes:
               - discovery
-      # A deferred/absent answer is the denial today's headless responder gave, so the
-      # guards keep routing on yes | no | cancel with no new edge.
+      # A deferred/absent answer is the denial today's headless responder gave, so the guards keep
+      # routing on yes | no | cancel with no new edge.
       - kind: shell
         options:
           command: >-
@@ -223,33 +174,17 @@ states:
           var: __hitlAnswer
 
   - id: feature-create
-    display:
-      phase: define
-      phaseTitle: "Define feature"
-      title: Create feature
-    description: >
-      Create a feature via spur feature create, or select an existing feature id.
-      The agent writes the feature id to .spur/run/${vars.__runId}-idea-feature-id.txt and body-only
-      intent artifacts .spur/run/${vars.__runId}-idea-goal.md / -idea-scope.md. Goal carries
-      concise intent only; Scope carries explicit in/out boundaries — task breakdowns and
-      checklists never enter Goal. Shell actions then persist both sections through
-      `spur feature update --section Goal|Scope --from-file ...`; a missing/empty artifact
-      stops the state. Prefer the enhanced idea from .spur/run/${vars.__runId}-idea-eval-report.md as
-      context; do not overwrite vars.idea. The operator's verbatim ask of record is
-      .spur/run/${vars.__runId}-idea-input.md (persisted at start; authoritative over any
-      paraphrase).
+    description: "Create a feature via `spur feature create` (or select an existing id). The agent writes the feature id plus body-only Goal/Scope intent artifacts; the shell persists both sections through `spur feature update --from-file` and fails closed on an empty artifact. Goal carries intent only — task breakdowns and checklists never enter it. The operator's verbatim ask of record stays .spur/run/${vars.__runId}-idea-input.md."
     onEnter:
       - kind: agent.run
         options:
           agent: ${vars.planningAgent}
           input: 'Create a feature for the idea. The operator''s ask of record is .spur/run/${vars.__runId}-idea-input.md — the idea argument persisted verbatim at start; treat it as the authoritative ask. Read .spur/run/${vars.__runId}-idea-eval-report.md if present for the enhanced idea and scores. Use ''spur feature create "<name>" --json'' to create it; with --json the feature id is returned under the .ref.id envelope (n), not a top-level .id — read it from there. Write the feature id to .spur/run/${vars.__runId}-idea-feature-id.txt. If an existing feature is appropriate, use its id instead. Also write two body-only intent artifacts: .spur/run/${vars.__runId}-idea-goal.md with concise Goal intent only (a short statement of what the feature achieves; never task breakdowns, checklists, or how-to steps), and .spur/run/${vars.__runId}-idea-scope.md with explicit in-scope and out-of-scope boundary bullets.'
-          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
           role: planner
-          # B7 R6 (0894): declared fresh policy (planner default).
           session: fresh
           expectFile: .spur/run/${vars.__runId}-idea-feature-id.txt
-          # Intent artifacts this stage writes; the shell below fails closed when either is
-          # missing, so declaring them adds the work-item contract, not a new precondition.
+          # Intent artifacts this stage writes; the shell below fails closed when either is missing,
+          # so declaring them adds the work-item contract, not a new precondition.
           expectFiles:
             - .spur/run/${vars.__runId}-idea-goal.md
             - .spur/run/${vars.__runId}-idea-scope.md
@@ -258,9 +193,8 @@ states:
         options:
           path: .spur/run/${vars.__runId}-idea-feature-id.txt
           var: featureId
-      # 1007 R2: one shell persists both sections — the Goal and Scope updates share the
-      # artifact precondition, so the two update shells merged (original commands in order,
-      # same && fail-fast semantics).
+      # 1007 R2: one shell persists both sections — they share the artifact precondition, so the two
+      # update shells merged (original commands in order, same && fail-fast semantics).
       - kind: shell
         options:
           command: >-
@@ -271,25 +205,7 @@ states:
             $spurBin feature update "$featureId" --section Scope --from-file .spur/run/$__runId-idea-scope.md
 
   - id: ac-generate
-    display:
-      phase: define
-      phaseTitle: "Define feature"
-      title: Generate AC
-    description: >
-      Generate acceptance criteria per ac-style-guide.md. Write AC scenarios to the
-      feature file via `spur feature update --section "Acceptance Criteria"
-      --from-file`. The agent authors R-numbered Gherkin scenarios tied to the
-      design summary into a captured file; the shell step verifies the file is
-      non-empty, writes it through the CLI, and writes a completion sentinel
-      (.spur/run/${vars.__runId}-idea-ac-done.txt). AC quality is MEASURED once at this
-      boundary by the deterministic `idea-ac-check` command.gate below (task 0769): a failing
-      check records FAIL and routes through the capped retry loop via guards that consume the
-      recorded result — it never fails the run (the engine's default onError policy is `fail`,
-      so an in-action check failure would kill the run before the retry edges are evaluated).
-      Requirement coverage is MEASURED by the same gate (1004 R2): the `idea-ac-check` args
-      carry `--inventory .spur/run/${vars.__runId}-idea-eval-report.md`, so uncovered
-      inventory items record FAIL on `idea-ac-check.status` and route through the same capped
-      retry loop via the guards below.
+    description: "Author R-numbered BDD scenarios tied to the requirement inventory and persist them through `spur feature update --section \"Acceptance Criteria\" --from-file`. AC quality and requirement coverage are MEASURED once at this boundary by the `idea-ac-check` command.gate (0769; 1004 R2 folds coverage in via --inventory): a FAIL is recorded, never a run abort, so the capped retry edges can route it."
     onEnter:
       - kind: shell
         options:
@@ -298,20 +214,14 @@ states:
         options:
           agent: ${vars.planningAgent}
           input: "Generate acceptance criteria for feature ${vars.featureId}. The operator's ask of record is .spur/run/${vars.__runId}-idea-input.md — idea persisted verbatim at start; authoritative. Read the feature file and author R-numbered BDD Gherkin scenarios per ac-style-guide.md. Tie every scenario to the `## Requirement inventory` of .spur/run/${vars.__runId}-idea-eval-report.md: under each `Scenario:` heading add a comment `# covers: I1, I3` listing covered ids — every non-`[deferred: ...]` item needs at least one covering scenario. Two `spur task check` rules bind AC text: (1) AC bullets copy scenario titles verbatim — the title is the byte-identical identity key of its bullet; (2) gate-language words (HITL, approval/approved, merged/merge event, content-gate, GATED, capstone standalone) are forbidden in titles, bodies, and enum values (L4.gate-language) — rephrase around them. Output only the Acceptance Criteria section body (gherkin fence included), no commentary, no heading."
-          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
           role: planner
-          # B7 R6 (0894): declared fresh policy (planner default).
           session: fresh
           answerFile: .spur/run/${vars.__runId}-idea-ac-content.md
           expectFile: .spur/run/${vars.__runId}-idea-ac-content.md
           timeoutMs: ${vars.stepTimeoutMs}
-      # Empty capture is a RETRYABLE outcome, not a run abort. `answerFile` always
-      # creates the file (so `expectFile` above cannot catch an empty answer), and the
-      # old `test -s … && …` chain exited 1 on empty content — killing the run under
-      # the default `fail` policy before the capped retry edges were ever evaluated,
-      # contradicting this state's own contract. Empty now falls through with exit 0
-      # so the recorded FAIL routes it back here (cap: 3). A failing CLI *write* still
-      # exits non-zero and aborts — that one is not retryable.
+      # Empty capture is a RETRYABLE outcome, not a run abort: `answerFile` always creates the file,
+      # so an empty answer falls through with exit 0 and the recorded FAIL routes it back here (cap
+      # 3). A failing CLI *write* still exits non-zero and aborts — that one is not retryable.
       - kind: shell
         options:
           command: >-
@@ -320,9 +230,8 @@ states:
             else
               exit 0;
             fi
-      # 0769: ONE measured check at the AC author/revise boundary. `softFail: true` keeps a
-      # FAIL routable (retry loop / failed) instead of aborting; sibling guards consume the
-      # recorded result from the run-scoped status file and never re-run the CLI.
+      # 0769: ONE measured check at the AC author/revise boundary. `softFail: true` keeps a FAIL
+      # routable (retry loop / failed) instead of aborting.
       - kind: command.gate
         options:
           id: idea-ac-check
@@ -331,14 +240,11 @@ states:
           resultFile: .spur/run/${vars.__runId}-idea-ac-check.status
           softFail: true
           timeoutMs: 120000
-      # 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 the recorded check is PASS (1004 R2:
-      # coverage folds into idea-ac-check via --inventory).
-      # (warn) 7 commands: two three-way `test && printf || printf` derivations over captured
-      # signal files (ADR-115); no model hop, no CLI re-run.
+      # 0945 R2: derive the route facts ONCE at this boundary (0769 pattern) so guards read these
+      # named files instead of re-deriving design×needs_design inline. Missing/corrupt needs-design
+      # JSON fails safe to `design`; readiness is PASS only when the recorded check is PASS (1004 R2:
+      # coverage folds into idea-ac-check via --inventory). (warn) 7 commands: two three-way
+      # `test && printf || printf` derivations over captured signal files (ADR-115); no model hop.
       - kind: shell
         options:
           command: >-
@@ -350,70 +256,8 @@ states:
             printf 'PASS\n' > .spur/run/$__runId-idea-ac-ready.status ||
             printf 'FAIL\n' > .spur/run/$__runId-idea-ac-ready.status; }
 
-  - id: feature-check
-    display:
-      phase: define
-      phaseTitle: "Define feature"
-      title: Check feature
-    description: >
-      HITL gate over the recorded `idea-ac-check` result (measured at the ac-generate
-      boundary — this gate never re-runs the CLI). Deliberately NOT --strict: before
-      decompose/batch-create a feature has scenarios but zero linked tasks, which
-      emits L4.orphan-scenarios at severity `warning`; --strict would elevate that
-      to a failure, making the success edges unreachable and looping ac-generate
-      into `failed`. Malformed AC still blocks via the error-severity L3 BDD
-      checks. Strict coverage belongs at the shippable gate, not here. The recorded
-      result is objective (schema/AC validation) and auto-routable — under profile=auto
-      the transition guards route directly from ac-generate to the appropriate next
-      state, so this state is only entered in interactive mode. On failure, the retry
-      cap routes back to ac-generate (≤3 retries) or escalates to failed.
-      Requirement coverage (1004 R2) folds into the recorded `idea-ac-check` result via the
-      gate's `--inventory` flag: a FAIL there can mean some inventory items have no covering
-      scenario — answer no to route back to ac-generate for revision if needed.
-    onEnter:
-      - kind: hitl.confirm
-        options:
-          prompt: "Feature check for ${vars.featureId}. Review the AC and confirm to proceed? Recorded check status: $(cat .spur/run/${vars.__runId}-idea-ac-check.status 2>/dev/null || echo unknown) (.spur/run/${vars.__runId}-idea-ac-check.status — includes inventory-coverage findings, 1004 R2). (Failures route back to ac-generate for revision, capped at 3 retries.)"
-          # Interactive always prompts the operator; profile=auto answers from the AC
-          # authoring stage's recorded evidence (1236 R1/R2). No `pause: true` — an
-          # evidence binding cannot live in a paused state (0911 D2), and the responder
-          # is what asks the operator now.
-          decision:
-            mode: evidence
-            statusVar: featureCheckStatus
-            evidenceNodes:
-              - ac-generate
-      # A deferred/absent answer is the denial today's headless responder gave.
-      - kind: shell
-        options:
-          command: >-
-            mkdir -p .spur/run; a="$__hitlAnswer"; [ -n "$a" ] || a=no;
-            printf '%s\n' "$a" > ".spur/run/$__runId-idea-feature-check-answer.txt"
-      - kind: file.read.into-var
-        options:
-          path: .spur/run/${vars.__runId}-idea-feature-check-answer.txt
-          var: __hitlAnswer
-      # 1007 R2: the former post-confirm route-writer duplicate is deleted — ac-generate's
-      # writer is the single writer (0945 R2 pin updated); its inputs (design var, needs-design
-      # JSON, recorded ac-check status) cannot change across hitl.confirm.
-
   - id: system-design
-    display:
-      phase: design
-      phaseTitle: Design
-      title: System design
-    description: >
-      Dispatch sp:sys-architecture to produce the system design. This state runs
-      only when needs_design=true (design=auto signal path). The agent creates ADR
-      entries, architecture updates, and design satellites through constitution rules.
-      A run-scoped design-review artifact (.spur/run/${vars.__runId}-idea-design-review.md)
-      with fixed headings `## Proposed design`, `## Operator feedback`, and `## Reconciliation`
-      carries operator rejection feedback back into this state: on the first pass the agent
-      fills `## Proposed design`; on retry (operator feedback present) it revises the design,
-      records the reconciliation, and updates invalidated Acceptance Criteria through
-      `spur feature update` before design can exit. Design quality is then MEASURED once at
-      this boundary by the deterministic `idea-design-check` command.gate (task 0769). The
-      design-approval state follows (taste gate).
+    description: "Dispatch sp:sys-architecture (runs only on the needs_design signal) to produce ADR entries, architecture updates and design satellites. The run-scoped design-review artifact (.spur/run/${vars.__runId}-idea-design-review.md) with fixed headings `## Proposed design`, `## Operator feedback`, `## Reconciliation` carries operator rejection feedback into a revision pass, which reconciles invalidated AC through `spur feature update`. Design quality is MEASURED once at this boundary by the `idea-design-check` command.gate (0769)."
     onEnter:
       - kind: shell
         options:
@@ -425,23 +269,18 @@ states:
         options:
           agent: ${vars.planningAgent}
           input: 'The operator''s ask of record is .spur/run/${vars.__runId}-idea-input.md (idea persisted verbatim at start; authoritative). Run sp:sys-architecture for feature ${vars.featureId}. Read the brainstorm artifact, feature AC, and .spur/run/${vars.__runId}-idea-design-review.md. Produce ADR entries, architecture updates, and design satellites (docs/design/<slug>.md) per the constitution edit rules; never write task or feature corpus files directly. Design-review contract (fixed headings `## Proposed design`, `## Operator feedback`, `## Reconciliation`): first pass — write the proposed summary under `## Proposed design`, leave `## Operator feedback` empty; retry after operator feedback — revise the design/ADR artifacts, document changes under `## Reconciliation`, and when feedback invalidates an Acceptance Criteria scenario write the revised AC section body to a file, persist via `$spurBin feature update "$featureId" --section "Acceptance Criteria" --from-file <file>`.'
-          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
           role: planner
-          # B7 R6 (0894): declared fresh policy (planner default).
           session: fresh
           expectFile: .spur/run/${vars.__runId}-idea-design-review.md
           timeoutMs: ${vars.stepTimeoutMs}
-      # expectFile proves existence only, and the onEnter skeleton pre-creates the file — so an
-      # agent no-op would still pass it (0515 P3-2). Fail closed: the `## Proposed design` section
-      # must carry non-whitespace content before design can exit to approval/decompose.
+      # expectFile proves existence only and the skeleton above pre-creates the file, so an agent
+      # no-op would pass it (0515 P3-2). Fail closed on the section's content.
       - kind: shell
         options:
           command: >-
             REVIEW=".spur/run/$__runId-idea-design-review.md" &&
             awk '/^## Proposed design/{f=1; next} /^## Operator feedback/{f=0} f' "$REVIEW" | grep -q '[^[:space:]]'
-      # 0769: ONE measured check at the design author/revise boundary — after this pass's
-      # design writes (including AC reconciliation). softFail keeps FAIL routable; sibling
-      # guards consume the recorded result and never re-run the CLI.
+      # 0769: ONE measured check at the design author/revise boundary — after this pass's writes.
       - kind: command.gate
         options:
           id: idea-design-check
@@ -452,25 +291,7 @@ states:
           timeoutMs: 120000
 
   - id: design-approval
-    display:
-      phase: design
-      phaseTitle: Design
-      title: Approve design
-    description: >
-      HITL taste gate. The operator reviews the system design and approves or
-      rejects it. Routed around only when profile=auto AND vars.design_approved=true
-      (CLI --auto) AND the recorded design check PASSes; a FAIL still pauses here.
-
-      R7 (0433): a headless `no` persisted by DefaultHitlResponder would loop
-      design-approval -> system-design -> design-approval, burning unbounded
-      agent passes. The onEnter shell increments a reject counter; the `no`
-      edge to system-design is capped at 1 revise, after which the run
-      terminates as `failed` naming this gate.
-
-      Rejection must carry operator feedback: before answering `no`, the operator
-      records the concrete issue(s) in the run-scoped design-review artifact
-      (.spur/run/${vars.__runId}-idea-design-review.md) under `## Operator feedback` —
-      the revision pass reads it to reconcile invalidated AC before re-approval.
+    description: "HITL taste gate. Routed around only when profile=auto AND vars.design_approved=true AND the recorded design check PASSes; a FAIL still pauses here. R7 (0433): the `no` edge back to system-design is capped at 1 revise (the onEnter counter), after which the run ends failed naming this gate. Rejection must carry operator feedback in the review artifact under `## Operator feedback`. D66 1250 R2: an approved design whose recorded check FAILS routes to ac-generate (the AC revision state) — the former feature-check hop is deleted."
     onEnter:
       - kind: shell
         options:
@@ -478,8 +299,6 @@ states:
       - kind: hitl.confirm
         options:
           prompt: "Review the system design for feature ${vars.featureId}. Approve to proceed to decomposition? To reject, first record your feedback in .spur/run/${vars.__runId}-idea-design-review.md under the `## Operator feedback` heading, then answer no."
-          # Interactive always prompts the operator; profile=auto answers from the
-          # system-design stage's recorded evidence (1236 R1/R2).
           decision:
             mode: evidence
             statusVar: designApprovalStatus
@@ -497,18 +316,7 @@ states:
           var: __hitlAnswer
 
   - id: decompose
-    display:
-      phase: decompose
-      phaseTitle: Decompose
-      title: Decompose into tasks
-    description: >
-      Dispatch sp:spec-decomposition with the brainstorm artifact, feature AC, and
-      design doc as input. The agent produces a task-batch JSON file at
-      .spur/run/${vars.__runId}-idea-task-batch.json, validated against task-batch.schema.json,
-      plus the private task-order sidecar .spur/run/${vars.__runId}-idea-task-order.json
-      (a JSON array of { name, depends_on_names[] }; `[]` when no ordering exists).
-      A post-agent shell action validates the sidecar shape before decomposition
-      can exit — missing or ambiguous title-to-WBS resolution fails before handoff.
+    description: "Dispatch sp:spec-decomposition with the brainstorm artifact, feature AC and design doc. The agent produces the task-batch JSON (.spur/run/${vars.__runId}-idea-task-batch.json, validated against task-batch.schema.json) plus the private task-order sidecar (.spur/run/${vars.__runId}-idea-task-order.json — an array of { name, depends_on_names[] }; `[]` when no ordering exists). The post-agent shell validates the sidecar shape fail-closed."
     onEnter:
       - kind: shell
         options:
@@ -517,19 +325,14 @@ states:
         options:
           agent: ${vars.planningAgent}
           input: "The operator's ask of record is .spur/run/${vars.__runId}-idea-input.md (the idea argument persisted verbatim at start; authoritative). Run sp:spec-decomposition for feature ${vars.featureId} per skill references/decomposition.md § Idea-pipeline emission: sizing first, then the batch JSON at .spur/run/${vars.__runId}-idea-task-batch.json and the private task-order sidecar at .spur/run/${vars.__runId}-idea-task-order.json."
-          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
           role: planner
-          # B7 R6 (0894): declared fresh policy (planner default).
           session: fresh
           expectFile: .spur/run/${vars.__runId}-idea-task-batch.json
           timeoutMs: ${vars.stepTimeoutMs}
-      # R1 (0518): the task-order sidecar is the ordering contract for handoff-finalize.
-      # Validate it fails closed: sidecar must be an array, batch names unique, sidecar names
-      # unique, every sidecar name/dependency must refer to exactly one batch name, and — the
-      # converse (F2, 0518 verify) — every batch name must appear in the sidecar, so a partial
-      # sidecar can never silently skip `task deps` for an unlisted item (`[]` is valid).
-      # (warn) stays inline by design: one jq predicate over two run-scoped files; splitting
-      # it into a script would hide the exact fail-closed contract this guard pins (0824).
+      # R1 (0518): the sidecar is the ordering contract for handoff-finalize. Fail closed on the
+      # array shape, unique names on both sides, and BIDIRECTIONAL coverage (F2, 0518 verify) — a
+      # partial sidecar must never silently skip `task deps` for an unlisted item (`[]` is valid).
+      # (warn) stays inline by design: one jq predicate over two run-scoped files (0824).
       - kind: shell
         options:
           command: >-
@@ -544,58 +347,10 @@ states:
               (((map(.depends_on_names // []) | flatten | unique) - ($b[0] | map(.name))) | length == 0)
             ' "$ORDER" >/dev/null
 
-  - id: batch-create
-    display:
-      phase: decompose
-      phaseTitle: Decompose
-      title: Approve task batch
-    description: >
-      HITL gate: runs spur task batch-create with the batch JSON from the
-      decompose state. The check is objective (schema validation) and
-      auto-routable — under profile=auto the transition guards route directly
-      from decompose to the appropriate next state, so this state is only
-      entered in interactive mode. On failure, the retry cap routes back to
-      decompose (≤3 retries) or escalates to failed.
-    onEnter:
-      - kind: hitl.confirm
-        options:
-          prompt: "Batch-create for feature ${vars.featureId}. Review the task batch and confirm to proceed? (Failures route back to decompose for revision, capped at 3 retries.)"
-          # Interactive always prompts the operator; profile=auto answers from the
-          # decompose stage's recorded evidence (1236 R1/R2).
-          decision:
-            mode: evidence
-            statusVar: batchCreateStatus
-            evidenceNodes:
-              - decompose
-      # A deferred/absent answer is the denial today's headless responder gave.
-      - kind: shell
-        options:
-          command: >-
-            mkdir -p .spur/run; a="$__hitlAnswer"; [ -n "$a" ] || a=no;
-            printf '%s\n' "$a" > ".spur/run/$__runId-idea-batch-create-answer.txt"
-      - kind: file.read.into-var
-        options:
-          path: .spur/run/${vars.__runId}-idea-batch-create-answer.txt
-          var: __hitlAnswer
-
   - id: batch-create-run
-    display:
-      phase: decompose
-      phaseTitle: Decompose
-      title: Create tasks
-    description: >
-      Executes task batch creation exactly once per decomposition attempt. The
-      side effect lives in onEnter and records a sentinel; transition guards only
-      inspect sentinel/retry state. The `--json` result is captured atomically in
-      .spur/run/${vars.__runId}-idea-batch-create-result.json (temp file + mv); the done
-      sentinel is written only after the JSON parses and `created == (.wbs | length)`,
-      so handoff-finalize can zip batch names to the returned WBS list. Any failure
-      (CLI error or malformed result) writes the failed sentinel, preserving the
-      existing retry behavior.
+    description: "Executes task batch creation exactly once per decomposition attempt. The side effect records a sentinel; guards only inspect sentinel/retry state. The `--json` result is captured atomically (.spur/run/${vars.__runId}-idea-batch-create-result.json, temp file + mv) and the done sentinel is written only after the JSON parses and `created == (.wbs | length)`, so handoff-finalize can zip batch names to the returned WBS list. Any failure writes the failed sentinel, preserving the retry behavior. D66 1250 R2: every profile reaches this state directly from decompose — the former `batch-create` approval state is deleted."
     onEnter:
-      # (e) idempotent batch creation: sentinel + temp/mv atomicity stay inline (0824);
-      # the jq verdict check keeps the done sentinel truthful so handoff-finalize can
-      # zip batch names to the returned WBS list.
+      # (e) idempotent batch creation: sentinel + temp/mv atomicity stay inline (0824).
       - kind: shell
         options:
           command: >-
@@ -612,34 +367,17 @@ states:
             fi
 
   - id: ready-prepare
-    display:
-      phase: handoff
-      phaseTitle: "Hand off"
-      title: Prepare ready set
-    description: >
-      Ready-by-default preparation (0788): the planning owner applies the
-      ready-refinement checklist to each created task (requirements, design,
-      plan, ac, decisions, dependencies, premises) so the deterministic task
-      check passes, then writes the run-scoped ready evidence sidecar
-      (.spur/run/${vars.__runId}-idea-ready.json) with one row per task: wbs,
-      status (ready|failed|skipped), planningDigest, and seven check rows,
-      with the premises row carrying tree-verified path:line citations
-      (0947). Handoff-finalize verifies presence, digest, feature binding and
-      checklist evidence before recommending auto runall; missing or failing
-      evidence never fails the run — it degrades the recommendation to
-      ready-depth refineall.
+    description: "Ready-by-default preparation (0788): the planning owner applies the ready-refinement checklist to each created task (requirements, design, plan, ac, decisions, dependencies, premises) so the deterministic task check passes, then writes the run-scoped ready evidence sidecar (.spur/run/${vars.__runId}-idea-ready.json) with one row per task: wbs, status (ready|failed|skipped), planningDigest, and seven check rows, the premises row carrying tree-verified path:line citations (0947). Missing or failing evidence never fails the run — it degrades the handoff recommendation to ready-depth refineall."
     onEnter:
       - kind: agent.run
         options:
           agent: ${vars.planningAgent}
-          # Declared Layer-1 role (0538 R2), same planner executor as decompose.
           role: planner
-          # B7 R6 (0894): declared fresh policy (planner default).
           session: fresh
           timeoutMs: ${vars.stepTimeoutMs}
-          # (warn) non-slash pointer: the 0788 checklist is per-checkout (digest via the
-          # project's own computePlanningDigest), so the bounded prompt pins the skill
-          # reference instead of a command; artifacts are gated by answerFile/expectFile.
+          # (warn) non-slash pointer: the 0788 checklist is per-checkout (digest via the project's
+          # own computePlanningDigest), so the prompt pins the skill reference; artifacts are gated
+          # by answerFile/expectFile.
           input: >-
             The operator's ask of record is .spur/run/${vars.__runId}-idea-input.md (the idea
             argument persisted verbatim at start; authoritative). Run the ready-prepare stage
@@ -651,12 +389,10 @@ states:
             cites at least one verified path:line (handoff-finalize lints it; task 0947).
           answerFile: .spur/run/${vars.__runId}-ready-prepare-answer.txt
           expectFile: .spur/run/${vars.__runId}-ready-prepare-answer.txt
-      # Fail-closed shape validation (mirrors the order-sidecar guard). Absence is
-      # normalized to an empty sidecar: finalize and the seeded fallback then degrade
-      # the recommendation to refineall instead of failing the run. A PRESENT but
-      # malformed sidecar fails the run here — it must not masquerade as evidence.
-      # (warn) stays inline by design: single jq shape predicate over the run-scoped
-      # sidecar; the failed/skipped rows are what degrade the recommendation (0824).
+      # Fail-closed shape validation (mirrors the order-sidecar guard). Absence is normalized to an
+      # empty sidecar so finalize degrades the recommendation to refineall instead of failing the
+      # run; a PRESENT but malformed sidecar fails here — it must not masquerade as evidence.
+      # (warn) stays inline by design: single jq shape predicate over the run-scoped sidecar (0824).
       - kind: shell
         options:
           command: >-
@@ -665,387 +401,69 @@ states:
             jq -e 'type == "object" and (.tasks | type == "array") and (all(.tasks[]; (.wbs | type == "string") and (.status == "ready" or .status == "failed" or .status == "skipped") and (.planningDigest | type == "string") and (.checks | type == "array") and (all(.checks[]; (.id | type == "string") and (.pass | type == "boolean") and (.evidence | type == "string")))))' "$READY" >/dev/null
 
   - id: handoff-finalize
-    display:
-      phase: handoff
-      phaseTitle: "Hand off"
-      title: Finalize handoff
-    description: >
-      Post-create finalization (0518): zip batch item names to the created WBS
-      values from the captured batch-create result (equal-length/unique-name
-      checks), apply every non-empty depends_on_names list through
-      `spur task deps`, refresh the feature roster, check every created task, and
-      write the run-scoped handoff report
-      (.spur/run/${vars.__runId}-idea-handoff.md) with exactly one next command.
-      A mapping or CLI error fails the run before terminal handoff; an unready
-      task is a successful planning outcome recorded as a refineall recommendation.
+    description: "Post-create finalization (0518): zip batch item names to the created WBS values (equal-length / unique-name checks), apply every non-empty depends_on_names list through `spur task deps`, refresh the feature roster, check every created task, and write the run-scoped handoff report (.spur/run/${vars.__runId}-idea-handoff.md) with exactly one next command. A mapping or CLI error fails the run before terminal handoff; an unready task is a successful planning outcome recorded as a refineall recommendation."
     onEnter:
-      # (d) `spur feature handoff` owns finalization (0824; script-absorption PR-5
-      # retired the idea-handoff plugin script and its bundle). A nonzero exit fails
-      # the run (fail closed) instead of silently skipping finalization. The
-      # zip/deps/refresh/check/report contract itself is pinned by
+      # (d) `spur feature handoff` owns finalization (0824; script-absorption PR-5 retired the
+      # idea-handoff plugin script). A nonzero exit fails the run (fail closed) instead of silently
+      # skipping finalization. The zip/deps/refresh/check/report contract is pinned by
       # finalizeIdeaHandoff unit tests, not by this file.
       - kind: shell
         options:
           command: '$spurBin feature handoff "$featureId" --run-id "$__runId" --no-logo'
+
   - id: handoff
-    description: >
-      Terminal — idea pipeline complete. Ordering applied, roster refreshed, and
-      the handoff report written at .spur/run/${vars.__runId}-idea-handoff.md:
-      feature id, task WBS list, per-task readiness, and exactly one recommended
-      next command (ready-depth refineall when any task is unready, else auto
-      runall). No task execution — the pipeline stops here.
+    description: "Terminal — idea pipeline complete. Ordering applied, roster refreshed, and the handoff report written at .spur/run/${vars.__runId}-idea-handoff.md: feature id, task WBS list, per-task readiness, and exactly one recommended next command (ready-depth refineall when any task is unready, else auto runall). No task execution — the pipeline stops here."
     onEnter:
-      # 1007 R2: the handoff note is deleted — the run.artifact below carries the handoff
-      # (same path, the recommended-next-command report).
+      # 1007 R2: the run.artifact carries the handoff (the recommended-next-command report).
       - kind: run.artifact
         options:
           path: .spur/run/${vars.__runId}-idea-handoff.md
           artifactKind: idea-handoff
 
   - id: cancelled
-    description: Terminal — pipeline cancelled by operator or error.
+    description: "Terminal — pipeline cancelled by operator or error."
 
   - id: failed
-    description: >
-      Terminal — pipeline failed after exhausting retry caps on cyclic edges
-      (feature-check → ac-generate or batch-create → decompose). The error
-      message in the run trace identifies which edge exceeded the cap.
+    description: "Terminal — the entry check failed, or a capped retry loop exhausted (ac-generate → ac-generate or batch-create-run → decompose). The recorded status file's first line names the reason; the terminal reason identifies the exhausted edge."
 
+# ── Routing table ──
+# Declaration order is load-bearing: the engine takes the first passing guard. start's PASS edge
+# precedes its reporting failure edge; discovery/idea-eval's auto-accept edges precede their gates
+# (0366 R4/R5) and every gate's discriminating edge precedes its always fallback. ac-generate routes
+# on the derived route facts under EVERY profile (1250 R2) — no guard re-runs the CLI (0769).
 transitions:
-  # ── start -> discovery ──
-  - from: start
-    to: discovery
-    description: Agent doctor PASS — begin discovery.
-    guard:
-      kind: shell
-      options:
-        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
-
-  # ── discovery: auto-accept the eval recommendation (profile=auto + idea_approved) OR enter idea-eval ──
-  # Declaration order: auto edges FIRST (same pattern as system-design → design-approval).
-  # Without them, discovery always enters the idea-eval gate, rendering the prompt and
-  # persisting an avoidable operator question before the gate's own auto answer can fire (0366 R4/R5).
-  # --auto accepts the recommendation derived at the end of discovery (-idea-recommendation.txt):
-  # drop → cancelled, proceed/reshape → feature-create; unknown/missing falls through to the
-  # idea-eval gate, whose evidence binding then answers (fail-safe: never auto-create a feature
-  # without an explicit proceed).
-  - from: discovery
-    to: cancelled
-    terminalReason: cancelled
-    description: profile=auto AND idea_approved=true AND eval recommends drop — accept it, no feature.
-    guard:
-      kind: shell
-      options:
-        command: >-
-          test "$profile" = auto && test "$idea_approved" = true &&
-          grep -qx drop .spur/run/$__runId-idea-recommendation.txt
-  - from: discovery
-    to: feature-create
-    description: profile=auto AND idea_approved=true AND eval recommends proceed/reshape — skip idea-eval taste gate.
-    guard:
-      kind: shell
-      options:
-        command: >-
-          test "$profile" = auto && test "$idea_approved" = true &&
-          grep -qxE 'proceed|reshape' .spur/run/$__runId-idea-recommendation.txt
-  - from: discovery
-    to: idea-eval
-    description: Discovery complete — gate on idea evaluation taste decision.
-    guard:
-      kind: always
-
-  # ── idea-eval: auto-skip (profile=auto + idea_approved) OR approve/reject HITL ──
-  # Declaration order: auto-skip FIRST (same pattern as system-design → design-approval).
-  - from: idea-eval
-    to: feature-create
-    description: profile=auto AND idea_approved=true AND eval recommends proceed/reshape — skip idea-eval taste gate.
-    guard:
-      kind: shell
-      options:
-        command: >-
-          test "$profile" = auto && test "$idea_approved" = true &&
-          grep -qxE 'proceed|reshape' .spur/run/$__runId-idea-recommendation.txt
-  - from: idea-eval
-    to: feature-create
-    description: Idea evaluation approved — create or select a feature.
-    guard:
-      kind: shell
-      options:
-        command: 'test "$__hitlAnswer" = yes'
-  - from: idea-eval
-    to: cancelled
-    terminalReason: cancelled
-    description: Idea evaluation rejected or cancelled — no feature created.
-    guard:
-      kind: shell
-      options:
-        command: 'test "$__hitlAnswer" = no || test "$__hitlAnswer" = cancel'
-
-  # ── feature-create -> ac-generate ──
-  - from: feature-create
-    to: ac-generate
-    description: Feature created — generate acceptance criteria.
-    guard:
-      kind: always
-
-  # ── 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 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).
-  #
-  # Auto-skip 1: pass + coverage + design route → system-design (design=auto + needs_design != false)
-  - from: ac-generate
-    to: system-design
-    description: "profile=auto, check passed, requirements covered, design route — run system design."
-    # 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: >-
-          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."
-    # 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-ready.status 2>/dev/null)" = PASS &&
-          test "$(cat .spur/run/$__runId-idea-design-route.txt 2>/dev/null)" = skip
-  # Auto-skip 3: check failed (incl. inventory coverage), retry < 3 → loop back to ac-generate (self-loop)
-  - from: ac-generate
-    to: ac-generate
-    description: "profile=auto, check failed (incl. inventory coverage), retry cap not reached — re-run ac-generate."
-    # (warn) 4 commands: one persistent multi-assignment line captures the check status and the retry
-    # count (with its 0 fallback); the profile gate folds into the retry test via `test -a`; the retry
-    # loop is the smallest honest formulation of cap<3 routing (0769).
-    guard:
-      kind: shell
-      options:
-        command: >-
-          ac_status="$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" retry="$(cat .spur/run/$__runId-idea-ac-retry-count 2>/dev/null || echo 0)";
-          test "$ac_status" != PASS && test "$profile" = auto -a "$retry" -lt 3
-  # Auto-skip 4: check failed (incl. inventory coverage), retry cap reached → escalate to failed
-  - from: ac-generate
-    to: failed
-    terminalReason: retry-exhausted
-    description: "profile=auto, check failed (incl. inventory coverage) after 3 retries — escalate to failed."
-    # (warn) 4 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).
-    guard:
-      kind: shell
-      options:
-        command: >-
-          ac_status="$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" retry="$(cat .spur/run/$__runId-idea-ac-retry-count 2>/dev/null || echo 0)";
-          test "$ac_status" != PASS && test "$profile" = auto -a "$retry" -ge 3
-  # Interactive fallback: enter feature-check HITL gate
-  - from: ac-generate
-    to: feature-check
-    description: Interactive — enter feature-check HITL gate for operator confirmation.
-    guard:
-      kind: always
-
-  # ── feature-check: pass + design route -> system-design, pass + skip route -> decompose, fail -> ac-generate ──
-  # Declaration order matters: system-design route tried first, then skip route, then fail.
-  - from: feature-check
-    to: system-design
-    description: Feature check passed, design route — run system design.
-    # 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: >-
-          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.
-    # 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 "$(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)."
-    # (warn) 5 commands (named status capture + 4 conditions): HITL reject/failed-status OR-pair + captured retry count; the
-    # interactive retry mirror of the ac-generate cap<3 guard (0769).
-    guard:
-      kind: shell
-      options:
-        command: >-
-          ac_status="$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)";
-          (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:
-      kind: shell
-      options:
-        command: >-
-          ac_status="$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)";
-          (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
-      options:
-        command: 'test "$__hitlAnswer" = cancel'
-
-  # ── system-design: -> design-approval (normal) OR -> decompose (auto + prior approval) ──
-  # Declaration order: auto-skip guard tried FIRST (like task-pipeline's review->verify pattern).
-  - from: system-design
-    to: decompose
-    description: profile=auto AND design_approved=true AND recorded design check passes — skip design approval gate.
-    guard:
-      kind: shell
-      options:
-        command: 'test "$profile" = auto && test "$design_approved" = true && test "$(cat .spur/run/$__runId-idea-design-check.status 2>/dev/null)" = PASS'
-  - from: system-design
-    to: design-approval
-    description: System design done — gate on design approval.
-    guard:
-      kind: always
-
-  # ── design-approval -> decompose (after operator approval), AC-failure -> feature-check ──
-  - from: design-approval
-    to: decompose
-    description: Design approved and recorded design check passes — proceed to decomposition.
-    guard:
-      kind: shell
-      options:
-        command: 'test "$__hitlAnswer" = yes && test "$(cat .spur/run/$__runId-idea-design-check.status 2>/dev/null)" = PASS'
-  - from: design-approval
-    to: feature-check
-    description: "Design approved but recorded design check fails — route back through the AC gate (revise AC, retry cap: 3)."
-    guard:
-      kind: shell
-      options:
-        command: 'test "$__hitlAnswer" = yes && test "$(cat .spur/run/$__runId-idea-design-check.status 2>/dev/null)" != PASS'
-  - from: design-approval
-    to: system-design
-    description: "Design rejected - revise system design (cap: 1 revise)."
-    guard:
-      kind: shell
-      options:
-        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
-      options:
-        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
-      options:
-        command: 'test "$__hitlAnswer" = cancel'
-
-  # ── decompose: auto-skip (profile=auto) OR enter batch-create HITL gate (interactive) ──
-  - from: decompose
-    to: batch-create-run
-    description: "profile=auto — execute batch-create side effect."
-    guard:
-      kind: shell
-      options:
-        command: 'test "$profile" = auto'
-  # Interactive fallback: enter batch-create HITL gate
-  - from: decompose
-    to: batch-create
-    description: Interactive — enter batch-create HITL gate for operator confirmation.
-    guard:
-      kind: always
-
-  - from: batch-create
-    to: batch-create-run
-    description: Operator approved batch creation — execute side effect.
-    guard:
-      kind: shell
-      options:
-        command: 'test "$__hitlAnswer" = yes'
-  - from: batch-create
-    to: decompose
-    description: Operator requested decomposition revisions.
-    guard:
-      kind: shell
-      options:
-        command: 'test "$__hitlAnswer" = no'
-  - from: batch-create
-    to: cancelled
-    terminalReason: cancelled
-    description: Operator cancelled batch creation.
-    guard:
-      kind: shell
-      options:
-        command: 'test "$__hitlAnswer" = cancel'
-
-  # ── batch-create-run: success -> ready-prepare, failure -> decompose (retry cap: 3), failure+cap -> failed ──
-  - from: batch-create-run
-    to: ready-prepare
-    description: Batch created and result captured — apply ready-by-default preparation, then finalize the handoff.
-    guard:
-      kind: shell
-      options:
-        command: "test -f .spur/run/$__runId-idea-batch-create.done"
-  # ── ready-prepare: -> handoff-finalize (always; evidence absence degrades to refineall, never fails the run) ──
-  - from: ready-prepare
-    to: handoff-finalize
-    description: Ready evidence sidecar written (or normalized empty) — finalize the handoff report.
-    guard:
-      kind: always
-  - from: batch-create-run
-    to: decompose
-    description: "Batch-create failed — revise decomposition (retry cap: 3)."
-    guard:
-      kind: shell
-      options:
-        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
-      options:
-        command: 'test -f .spur/run/$__runId-idea-batch-create.failed && test "$(cat .spur/run/$__runId-idea-decompose-retry-count 2>/dev/null || echo 0)" -ge 3'
-
-  # ── handoff-finalize: -> handoff (terminal) ──
-  - from: handoff-finalize
-    to: handoff
-    description: Ordering applied, roster refreshed, handoff report written — terminal handoff.
-    guard:
-      kind: always
+  - {from: start, to: discovery, guard: {kind: shell, options: {command: 'test "$(cat .spur/run/$__runId-idea-precheck-doctor.status 2>/dev/null)" = PASS'}}}
+  # The entry check's named reason (`FAIL: idea text is empty`, or the executor verdict) is the
+  # operator's one-place explanation for a run that never left start. `>&2` precedes the stderr
+  # suppression: redirections apply left to right, so the reverse order would send the line to
+  # /dev/null with it.
+  - {from: start, to: failed, terminalReason: failed-check, guard: {kind: shell, options: {command: 'head -1 .spur/run/$__runId-idea-precheck-doctor.status >&2 2>/dev/null; exit 0'}}}
+  - {from: discovery, to: cancelled, terminalReason: cancelled, guard: {kind: shell, options: {command: 'test "$profile" = auto && test "$idea_approved" = true && grep -qx drop .spur/run/$__runId-idea-recommendation.txt'}}}
+  - {from: discovery, to: feature-create, guard: {kind: shell, options: {command: 'test "$profile" = auto && test "$idea_approved" = true && grep -qxE "proceed|reshape" .spur/run/$__runId-idea-recommendation.txt'}}}
+  - {from: discovery, to: idea-eval, guard: {kind: always}}
+  - {from: idea-eval, to: feature-create, guard: {kind: shell, options: {command: 'test "$profile" = auto && test "$idea_approved" = true && grep -qxE "proceed|reshape" .spur/run/$__runId-idea-recommendation.txt'}}}
+  - {from: idea-eval, to: feature-create, guard: {kind: shell, options: {command: 'test "$__hitlAnswer" = yes'}}}
+  - {from: idea-eval, to: cancelled, terminalReason: cancelled, guard: {kind: shell, options: {command: 'test "$__hitlAnswer" = no || test "$__hitlAnswer" = cancel'}}}
+  - {from: feature-create, to: ac-generate, guard: {kind: always}}
+  - {from: ac-generate, to: system-design, guard: {kind: shell, options: {command: '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'}}}
+  - {from: ac-generate, to: decompose, guard: {kind: shell, options: {command: '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'}}}
+  # (warn) 4 commands each: one persistent multi-assignment line captures the check status and the
+  # retry count (with its 0 fallback); retry and escalation stay one test-chain pair so the cap
+  # boundary is auditable in the diff (0769). The former `test "$profile" = auto` conjunct is gone.
+  - {from: ac-generate, to: ac-generate, guard: {kind: shell, options: {command: 'ac_status="$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" retry="$(cat .spur/run/$__runId-idea-ac-retry-count 2>/dev/null || echo 0)"; test "$ac_status" != PASS && test "$retry" -lt 3'}}}
+  - {from: ac-generate, to: failed, terminalReason: retry-exhausted, guard: {kind: shell, options: {command: 'ac_status="$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" retry="$(cat .spur/run/$__runId-idea-ac-retry-count 2>/dev/null || echo 0)"; test "$ac_status" != PASS && test "$retry" -ge 3'}}}
+  - {from: system-design, to: decompose, guard: {kind: shell, options: {command: 'test "$profile" = auto && test "$design_approved" = true && test "$(cat .spur/run/$__runId-idea-design-check.status 2>/dev/null)" = PASS'}}}
+  - {from: system-design, to: design-approval, guard: {kind: always}}
+  - {from: design-approval, to: decompose, guard: {kind: shell, options: {command: 'test "$__hitlAnswer" = yes && test "$(cat .spur/run/$__runId-idea-design-check.status 2>/dev/null)" = PASS'}}}
+  - {from: design-approval, to: ac-generate, guard: {kind: shell, options: {command: 'test "$__hitlAnswer" = yes && test "$(cat .spur/run/$__runId-idea-design-check.status 2>/dev/null)" != PASS'}}}
+  - {from: design-approval, to: system-design, guard: {kind: shell, options: {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, guard: {kind: shell, options: {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, guard: {kind: shell, options: {command: 'test "$__hitlAnswer" = cancel'}}}
+  # D66 1250 R2: the sidecar guard above validates the batch deterministically, so the deleted
+  # `batch-create` approval state had no decision left to settle — every profile takes this edge.
+  - {from: decompose, to: batch-create-run, guard: {kind: always}}
+  - {from: batch-create-run, to: ready-prepare, guard: {kind: shell, options: {command: 'test -f .spur/run/$__runId-idea-batch-create.done'}}}
+  - {from: batch-create-run, to: decompose, guard: {kind: shell, options: {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, guard: {kind: shell, options: {command: 'test -f .spur/run/$__runId-idea-batch-create.failed && test "$(cat .spur/run/$__runId-idea-decompose-retry-count 2>/dev/null || echo 0)" -ge 3'}}}
+  - {from: ready-prepare, to: handoff-finalize, guard: {kind: always}}
+  - {from: handoff-finalize, to: handoff, guard: {kind: always}}