@gobing-ai/spur 0.2.11 → 0.2.12

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.2.11",
+    "version": "0.2.12",
     "description": "Spur CLI — local-first harness for mainstream coding agents: constraint checking, workflow orchestration, agent health, and history analytics. Bun-native; exposes the `spur` command.",
     "keywords": [
         "spur",

package/spur-cli/config/workflows/feature-dev.yaml

@@ -86,6 +86,11 @@ states:
 
   - id: done
     description: Terminal — feature planned, all tasks executed, and the feature verified.
+    # Checkpoint write: record session state for resume (Phase 4, task 0171 R3)
+    onEnter:
+      - kind: shell
+        options:
+          command: 'mkdir -p .spur/memory/sessions && echo "checkpoint: feature-dev done featureId=${vars.featureId} ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)" > .spur/memory/sessions/${vars.featureId}-checkpoint.md'
 
   - id: failed
     description: Terminal — plan rejected, a task failed verification, or the feature check did not pass.

package/spur-cli/config/workflows/idea-pipeline.yaml

@@ -0,0 +1,285 @@
+# Idea-to-feature pipeline — unified entry from a vague idea to a feature, AC, and task batch
+# (design §idea-pipeline).
+#
+# 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 -> feature-create -> ac-generate -> feature-check
+#          -> system-design (conditional: needs_design signal or --design)
+#          -> design-approval (taste HITL gate; not auto-clicked by --auto)
+#          -> decompose -> batch-create -> handoff
+#        (feature-check failure routes back to ac-generate; batch-create failure to decompose).
+#
+# 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), "force" (--design), "skip" (--skip-design)
+#   spurBin  — PATH-independent spur invocation (overridden by CLI at run start)
+#   agent    — agent for agent.run steps (default: omp)
+#
+# Seeded by `spur init`; adapt the agent.run inputs to your project's command set.
+
+"$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+kind: state-machine
+name: idea-pipeline
+description: "Idea to feature + AC + task batch: discovery, feature-create, ac-generate, feature-check, system-design, decompose, batch-create, handoff"
+iterationBound: 15
+initialState: start
+terminalStates:
+  - handoff
+  - cancelled
+  - failed
+vars:
+  idea: ""
+  profile: "standard"
+  design: "auto"
+  spurBin: "spur"
+  agent: "omp"
+  stepTimeoutMs: "600000"
+
+states:
+  - id: start
+    description: >
+      Pipeline start. The idea text arrives as vars.idea. The pipeline stops at
+      handoff — no task execution.
+    onEnter:
+      - kind: note
+        options:
+          message: "Idea pipeline start for idea: ${vars.idea}"
+      - kind: shell
+        options:
+          command: 'rm -f .spur/run/idea-ac-retry-count .spur/run/idea-decompose-retry-count'
+
+  - id: discovery
+    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/idea-needs-design.json — this determines
+      whether the system-design state runs.
+    onEnter:
+      - kind: agent.run
+        options:
+          agent: ${vars.agent}
+          input: "Run sp:brainstorm for the idea: ${vars.idea}. Generate 2-3 approaches with trade-offs and a design summary. Perform the scope decomposition check and write the needs_design boolean to .spur/run/idea-needs-design.json as {\"needs_design\": true|false}. Criteria: true if multiple subsystems/schema/transport/dependency changes; false if single-module/bug-fix/pattern-following. Ties lean true. ALWAYS record a design summary — no idea is too simple."
+          timeoutMs: ${vars.stepTimeoutMs}
+
+  - id: feature-create
+    description: >
+      Create a feature via spur feature create, or select an existing feature id.
+      The agent writes the feature id to .spur/run/idea-feature-id.txt for subsequent
+      states to read.
+    onEnter:
+      - kind: agent.run
+        options:
+          agent: ${vars.agent}
+          input: "Create a feature for the idea: ${vars.idea}. Use 'spur feature create \"<name>\" --json' to create it. Write the feature id to .spur/run/idea-feature-id.txt. If an existing feature is appropriate, use its id instead."
+          timeoutMs: ${vars.stepTimeoutMs}
+
+  - id: ac-generate
+    description: >
+      Generate acceptance criteria per ac-style-guide.md. Write AC scenarios to the
+      feature file via spur feature update (direct body edit, not --section). The
+      agent authors R-numbered Gherkin scenarios tied to the design summary.
+    onEnter:
+      - kind: agent.run
+        options:
+          agent: ${vars.agent}
+          input: "Generate acceptance criteria for the feature whose id is in .spur/run/idea-feature-id.txt. Read the feature file, author R-numbered BDD Gherkin scenarios per ac-style-guide.md, and write them to the feature body via direct file edit (spur feature update does not support --section for features). Run 'spur feature check <id>' to validate."
+          timeoutMs: ${vars.stepTimeoutMs}
+
+  - id: feature-check
+    description: >
+      Objective gate: run spur feature check <id> --strict. Under --auto, routes
+      around the HITL gate when the check passes. On failure, routes back to
+      ac-generate for AC revision. The feature id is read from
+      .spur/run/idea-feature-id.txt.
+    onEnter:
+      - kind: note
+        options:
+          message: "Running feature check for feature $(cat .spur/run/idea-feature-id.txt)"
+
+  - id: system-design
+    description: >
+      Dispatch sp:sys-architecture to produce the system design. This state runs
+      only when needs_design=true (or --design forces it). The agent creates ADR
+      entries, architecture updates, and design satellites through constitution rules.
+      The design-approval state follows (taste gate).
+    onEnter:
+      - kind: agent.run
+        options:
+          agent: ${vars.agent}
+          input: "Run sp:sys-architecture for the feature whose id is in .spur/run/idea-feature-id.txt. Read the brainstorm artifact and feature AC. Produce ADR entries, architecture updates, and design satellites (docs/design/<slug>.md) following the constitution edit rules. Do not write task or feature corpus files directly."
+          timeoutMs: ${vars.stepTimeoutMs}
+
+  - id: design-approval
+    description: >
+      HITL taste gate. The operator reviews the system design and approves or
+      rejects it. This gate is NOT auto-clicked by --auto (Auto-Decision Principle
+      #5: taste-decision -> surface to human). Only routes around when
+      vars.design_approved=true (explicit prior approval).
+    pause: true
+    onEnter:
+      - kind: hitl.confirm
+        options:
+          prompt: "Review the system design for feature $(cat .spur/run/idea-feature-id.txt). Approve to proceed to decomposition?"
+
+  - id: decompose
+    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/idea-task-batch.json, validated against task-batch.schema.json.
+    onEnter:
+      - kind: agent.run
+        options:
+          agent: ${vars.agent}
+          input: "Run sp:spec-decomposition for the feature whose id is in .spur/run/idea-feature-id.txt. Read the brainstorm artifact, feature AC, and design doc. Produce a task-batch JSON array at .spur/run/idea-task-batch.json, validated against apps/cli/schemas/task-batch.schema.json. Each entry must have filled Requirements, AC, Design, and Plan sections."
+          timeoutMs: ${vars.stepTimeoutMs}
+
+  - id: batch-create
+    description: >
+      Objective gate: run spur task batch-create with the batch JSON from the
+      decompose state. Under --auto, routes around the HITL gate when the batch
+      validates. On failure, routes back to decompose.
+    onEnter:
+      - kind: note
+        options:
+          message: "Running batch-create for feature $(cat .spur/run/idea-feature-id.txt)"
+
+  - id: handoff
+    description: >
+      Terminal — idea pipeline complete. Output: feature id, task WBS list, and
+      the next command to run (/sp:dev-run <first-wbs> or /sp:dev-runall --tasks feature:<id>).
+      No task execution — the pipeline stops here.
+    onEnter:
+      - kind: note
+        options:
+          message: "Idea pipeline handoff. Feature: $(cat .spur/run/idea-feature-id.txt). Tasks created. Next: /sp:dev-runall --tasks feature:$(cat .spur/run/idea-feature-id.txt)"
+      # Checkpoint write: record session state for resume (Phase 4, task 0171 R3)
+      - kind: shell
+        options:
+          command: 'mkdir -p .spur/memory/sessions && echo "checkpoint: idea-pipeline handoff feature=$(cat .spur/run/idea-feature-id.txt) ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)" > .spur/memory/sessions/idea-checkpoint.md'
+
+  - id: cancelled
+    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.
+
+transitions:
+  # ── start -> discovery ──
+  - from: start
+    to: discovery
+    description: Begin discovery — brainstorm the idea.
+    guard:
+      kind: always
+
+  # ── discovery -> feature-create ──
+  - from: discovery
+    to: feature-create
+    description: Discovery complete — create or select a feature.
+    guard:
+      kind: always
+
+  # ── feature-create -> ac-generate ──
+  - from: feature-create
+    to: ac-generate
+    description: Feature created — generate acceptance criteria.
+    guard:
+      kind: always
+
+  # ── ac-generate -> feature-check ──
+  - from: ac-generate
+    to: feature-check
+    description: AC generated — run feature check.
+    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.
+    guard:
+      kind: shell
+      options:
+        command: '${vars.spurBin} feature check $(cat .spur/run/idea-feature-id.txt) --strict && (test "${vars.design}" = force || (test "${vars.design}" = auto && test "$(jq -r .needs_design .spur/run/idea-needs-design.json 2>/dev/null)" != false))'
+  - from: feature-check
+    to: decompose
+    description: Feature check passed, skip-design route — go directly to decompose.
+    guard:
+      kind: shell
+      options:
+        command: '${vars.spurBin} feature check $(cat .spur/run/idea-feature-id.txt) --strict && (test "${vars.design}" = skip || (test "${vars.design}" = auto && test "$(jq -r .needs_design .spur/run/idea-needs-design.json 2>/dev/null)" = false))'
+  - from: feature-check
+    to: ac-generate
+    description: "Feature check failed — revise AC (retry cap: 3)."
+    guard:
+      kind: shell
+      options:
+        command: '! ${vars.spurBin} feature check $(cat .spur/run/idea-feature-id.txt) --strict && test "$(cat .spur/run/idea-ac-retry-count 2>/dev/null || echo 0)" -lt 3 && echo $(( $(cat .spur/run/idea-ac-retry-count 2>/dev/null || echo 0) + 1 )) > .spur/run/idea-ac-retry-count'
+  - from: feature-check
+    to: failed
+    description: Feature check failed after 3 retries — escalate to failed.
+    guard:
+      kind: shell
+      options:
+        command: '! ${vars.spurBin} feature check $(cat .spur/run/idea-feature-id.txt) --strict && test "$(cat .spur/run/idea-ac-retry-count 2>/dev/null || echo 0)" -ge 3'
+
+  # ── 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 — skip design approval gate.
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.profile}" = auto && test "${vars.design_approved}" = true'
+  - from: system-design
+    to: design-approval
+    description: System design done — gate on design approval.
+    guard:
+      kind: always
+
+  # ── design-approval -> decompose (after operator approval) ──
+  - from: design-approval
+    to: decompose
+    description: Design approved — proceed to decomposition.
+    guard:
+      kind: always
+
+  # ── decompose -> batch-create ──
+  - from: decompose
+    to: batch-create
+    description: Decomposition complete — create task batch.
+    guard:
+      kind: always
+
+  # ── batch-create: success -> handoff, failure -> decompose (retry cap: 3), failure+cap -> failed ──
+  - from: batch-create
+    to: handoff
+    description: Batch created — handoff.
+    guard:
+      kind: shell
+      options:
+        command: '${vars.spurBin} task batch-create --file .spur/run/idea-task-batch.json'
+  - from: batch-create
+    to: decompose
+    description: "Batch-create failed — revise decomposition (retry cap: 3)."
+    guard:
+      kind: shell
+      options:
+        command: '! ${vars.spurBin} task batch-create --file .spur/run/idea-task-batch.json && test "$(cat .spur/run/idea-decompose-retry-count 2>/dev/null || echo 0)" -lt 3 && echo $(( $(cat .spur/run/idea-decompose-retry-count 2>/dev/null || echo 0) + 1 )) > .spur/run/idea-decompose-retry-count'
+  - from: batch-create
+    to: failed
+    description: Batch-create failed after 3 retries — escalate to failed.
+    guard:
+      kind: shell
+      options:
+        command: '! ${vars.spurBin} task batch-create --file .spur/run/idea-task-batch.json && test "$(cat .spur/run/idea-decompose-retry-count 2>/dev/null || echo 0)" -ge 3'

package/spur-cli/config/workflows/planning-pipeline.yaml

@@ -12,7 +12,9 @@
 # commit (Q3 — hybrid by risk).
 #
 # Shape: phasing(HITL) → feature-id → design-gen → design-approval(HITL) → handoff
-#        (phasing/design-approval skipped when profile=auto).
+#        (phasing skipped when profile=auto; design-approval skipped when profile=auto
+#         AND design_approved=true — taste gates pause even in auto unless prior approval
+#         is encoded, per design doc HITL taxonomy).
 #
 # Vars (passed as a JSON object via `--vars`):
 #   slug     — the design-doc slug, e.g. `--vars '{"slug":"auth-migration"}'`
@@ -78,8 +80,11 @@ states:
   - id: design-approval
     description: >
       HITL gate — the highest-leverage gate in the pipeline. Loop until the operator
-      approves the design doc. Under profile=auto this state is never entered (design-gen
-      routes around it straight to handoff).
+      approves the design doc. Under profile=auto this state is skipped ONLY when
+      vars.design_approved=true (explicit prior approval); otherwise the taste gate
+      pauses even in auto mode (design doc HITL taxonomy). Loop back to design-gen
+      for revisions.
+    pause: true
     onEnter:
       - kind: hitl.confirm
         options:
@@ -90,6 +95,11 @@ states:
       Terminal — design doc approved; the drafted feature list is ready. Hand off to
       sp:spur-dev (steps 7–12), which starts at `spur feature create`. The seam is the
       drafted-feature-list file at docs/plans/${vars.slug}-drafted.md.
+    # Checkpoint write: record session state for resume (Phase 4, task 0171 R3)
+    onEnter:
+      - kind: shell
+        options:
+          command: 'mkdir -p .spur/memory/sessions && echo "checkpoint: planning-pipeline handoff slug=${vars.slug} ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)" > .spur/memory/sessions/${vars.slug}-checkpoint.md'
 
   - id: cancelled
     description: Terminal — planning abandoned by the operator.
@@ -131,16 +141,17 @@ transitions:
     guard:
       kind: always
 
-  # ── design-gen → design-approval, OR skip the HITL gate when profile=auto ──
-  # Auto-skip guard tried FIRST: under profile=auto, route straight to handoff
-  # without entering design-approval (whose onEnter hitl.confirm would block).
+  # ── design-gen → design-approval, OR skip the HITL gate when profile=auto AND design_approved=true ──
+  # Auto-skip guard tried FIRST: under profile=auto with explicit prior approval,
+  # route straight to handoff without entering design-approval. Without prior
+  # approval, the taste gate pauses even in auto (design doc HITL taxonomy).
   - from: design-gen
     to: handoff
-    description: profile=auto — skip the design-approval HITL gate, hand off directly.
+    description: profile=auto AND design_approved=true — skip the design-approval HITL gate.
     guard:
       kind: shell
       options:
-        command: 'test "${vars.profile}" = auto'
+        command: 'test "${vars.profile}" = auto && test "${vars.design_approved}" = true'
   - from: design-gen
     to: design-approval
     description: Design doc drafted — gate on human approval.

package/spur-cli/config/workflows/task-pipeline.yaml

@@ -75,6 +75,15 @@ states:
       - kind: shell
         options:
           command: "${vars.spurBin} task update ${vars.wbs} wip --no-lifecycle"
+      # Post-implement cleanup: auto-format any unformatted output the agent produced.
+      # The agent may leave files that don't pass `biome check`, which then fails
+      # `bun run lint` downstream. Running format here is cheap (< 1 s) and prevents
+      # the test stage from tripping on a purely mechanical formatting defect (dogfood
+      # bug-733 — omp left agent-run.test.ts unformatted, causing a spurious lint gate
+      # failure that the ## Testing section mis-attributed to "pre-existing gaps").
+      - kind: shell
+        options:
+          command: "bun run format"
 
   - id: test
     description: Test execution + coverage via /sp:dev-unit.
@@ -84,6 +93,13 @@ states:
           agent: ${vars.agent}
           input: /sp:dev-unit ${vars.wbs} --auto
           timeoutMs: ${vars.stepTimeoutMs}
+      # Post-test gate: run the project's full lint gate (biome check + tsc). If the
+      # implement or test step left unformatted files or type errors, the run routes to
+      # `failed` rather than letting an agent-authored `## Testing` claim "all pass"
+      # against a red gate (dogfood bug-733).
+      - kind: shell
+        options:
+          command: "bun run lint"
 
   - id: review
     description: SECUA-framework code review via /sp:dev-review (Security, Efficiency, Correctness, Usability, Architecture).
@@ -147,6 +163,10 @@ states:
       - kind: note
         options:
           message: "Pipeline complete for task ${vars.wbs} (done gate cleared)."
+      # Checkpoint write: record session state for resume (Phase 4, task 0171 R3)
+      - kind: shell
+        options:
+          command: 'mkdir -p .spur/memory/sessions && echo "checkpoint: task-pipeline done wbs=${vars.wbs} ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)" > .spur/memory/sessions/${vars.wbs}-checkpoint.md'
 
   - id: failed
     description: Terminal — precheck (or a gated step) failed; reported, not advanced.

package/spur-cli/config/workflows/wrapup-pipeline.yaml

@@ -0,0 +1,225 @@
+# Wrap-up pipeline — post-execution wrap-up for one task or a batch (design §wrapup-pipeline).
+#
+# Orchestration is configuration (ADR-022 / §3.2): this is YAML over the existing
+# dual-workflow engine — zero new engine code. The pipeline NEVER mutates task status —
+# wrap-up consumes completed tasks and produces learning/metrics/doc artifacts only.
+# Feature transitions go through `spur feature update` so the feature-lifecycle guards
+# apply identically. Branch cleanup is an irreversible HITL gate — it always pauses,
+# even under --auto (Iron Law #6: irreversible action -> surface to human).
+#
+# Shape: start -> task-resolve -> doc-sync -> learning-capture -> metrics-record
+#          -> feature-transition (conditional: if vars.feature set)
+#          -> branch-cleanup (conditional: if vars.merge=true)
+#          -> done
+#        (task-resolve with empty list short-circuits to `skipped`).
+#
+# Vars (passed as a JSON object via `--vars`):
+#   tasks    — JSON array of WBS strings (required), e.g. --vars '{"tasks":["0167"]}'
+#   feature  — feature id to advance through legal lifecycle edges (optional)
+#   profile  — set --vars '{"profile":"auto"}' to skip objective confirmations
+#   merge    — set --vars '{"merge":"true"}' to run branch cleanup (irreversible HITL)
+#   spurBin  — PATH-independent spur invocation (overridden by CLI at run start)
+#   agent    — agent for agent.run steps (default: omp)
+#
+# Seeded by `spur init`; adapt the agent.run inputs to your project's command set.
+
+"$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+kind: state-machine
+name: wrapup-pipeline
+description: "Post-execution wrap-up: doc-sync, learning-capture, metrics, feature-transition, branch-cleanup"
+iterationBound: 10
+initialState: start
+terminalStates:
+  - done
+  - skipped
+vars:
+  tasks: "[]"
+  feature: ""
+  profile: "standard"
+  merge: "false"
+  spurBin: "spur"
+  agent: "omp"
+  stepTimeoutMs: "600000"
+
+states:
+  - id: start
+    description: >
+      Pipeline start. Task statuses are NOT mutated by wrap-up — wrap-up consumes
+      completed tasks and produces learning/metrics/doc artifacts only.
+    onEnter:
+      - kind: note
+        options:
+          message: "Wrap-up pipeline start for tasks: ${vars.tasks}. Task statuses are NOT mutated."
+
+  - id: task-resolve
+    description: >
+      Validate the task list passed by the wrapper is non-empty. The command wrapper
+      (dev-wrap/dev-wrapall) resolves the task list and passes it as vars.tasks;
+      this state validates it before proceeding. Empty list routes to `skipped`.
+    onEnter:
+      - kind: note
+        options:
+          message: "Resolving task list: ${vars.tasks}"
+
+  - id: doc-sync
+    description: >
+      Dispatch sp:doc-evolve once for the entire batch. Project-level doc drift repair
+      runs once, not per-task. The agent reads the batch's completed tasks, identifies
+      doc drift (04_DESIGN, 03_ARCHITECTURE, 00_ADR, docs/design/*), and repairs it
+      following the constitution's edit rules. Does NOT write task or feature corpus.
+    onEnter:
+      - kind: agent.run
+        options:
+          agent: ${vars.agent}
+          input: "Run sp:doc-evolve for completed tasks ${vars.tasks}. Repair doc drift in 04_DESIGN, 03_ARCHITECTURE, 00_ADR, docs/design/* following the constitution edit rules. Do not write task or feature corpus files."
+          timeoutMs: ${vars.stepTimeoutMs}
+
+  - id: learning-capture
+    description: >
+      Append working learnings to .spur/memory/learnings.md. The agent extracts insights
+      from the batch — conventions discovered, errors hit and resolved, patterns that
+      worked, gotchas for future tasks. Grouped by date and task WBS. Working scratchpad,
+      not a CLI-gated corpus artifact.
+    onEnter:
+      - kind: agent.run
+        options:
+          agent: ${vars.agent}
+          input: "Extract working learnings from tasks ${vars.tasks}. Append to .spur/memory/learnings.md grouped by date and task WBS. Include: conventions discovered, errors hit and resolved, patterns that worked, gotchas. This is a working scratchpad, not a validated corpus."
+          timeoutMs: ${vars.stepTimeoutMs}
+
+  - id: metrics-record
+    description: >
+      Append one JSONL row per task to .spur/memory/wrapup-metrics.jsonl. Each row
+      records: task WBS, feature id, status, verdict, timestamp. Append-only and
+      machine-readable.
+    onEnter:
+      - kind: agent.run
+        options:
+          agent: ${vars.agent}
+          input: "For each task in ${vars.tasks}, read the task file and append one JSONL row to .spur/memory/wrapup-metrics.jsonl with fields: wbs, feature_id, status, verdict (from .spur/run/<wbs>-verdict.json if available), timestamp. Append-only; do not overwrite existing rows."
+          timeoutMs: ${vars.stepTimeoutMs}
+
+  - id: feature-transition
+    description: >
+      If vars.feature is set, advance the feature through legal lifecycle edges only
+      via spur feature update. Never attempt backlog|active -> done directly. The
+      legal path: backlog -> active (always), active -> verifying (feature check
+      guard), verifying -> done (strict feature check guard). Task statuses are NOT
+      mutated. The agent checks current status and advances idempotently.
+    onEnter:
+      - kind: agent.run
+        options:
+          agent: ${vars.agent}
+          input: "Advance feature ${vars.feature} through legal lifecycle edges using spur feature update. Check current status with 'spur feature show ${vars.feature} --json'. If backlog, transition to active. If active, run 'spur feature check ${vars.feature}' then transition to verifying. If verifying, run 'spur feature check ${vars.feature} --strict' then transition to done. Never skip edges (no backlog->done directly). Report transitions made."
+          timeoutMs: ${vars.stepTimeoutMs}
+
+  - id: branch-cleanup
+    description: >
+      Irreversible HITL gate. If vars.merge=true, dispatch branch cleanup (merge or
+      delete). This gate ALWAYS pauses — even under --auto — because branch operations
+      are irreversible (Auto-Decision Principle #6). The operator must explicitly confirm.
+    pause: true
+    onEnter:
+      - kind: hitl.confirm
+        options:
+          prompt: "Branch cleanup for tasks ${vars.tasks}. This is IRREVERSIBLE (merge or delete). Confirm to proceed?"
+
+  - id: done
+    description: >
+      Terminal — wrap-up complete. Output summary: tasks wrapped, learnings captured,
+      metrics recorded, feature advanced (if applicable), branch cleaned (if applicable).
+    onEnter:
+      - kind: note
+        options:
+          message: "Wrap-up pipeline complete for tasks: ${vars.tasks}. Learnings at .spur/memory/learnings.md, metrics at .spur/memory/wrapup-metrics.jsonl."
+      # Checkpoint write: record session state for resume (Phase 4, task 0171 R3)
+      - kind: shell
+        options:
+          command: 'mkdir -p .spur/memory/sessions && echo "checkpoint: wrapup-pipeline done tasks=${vars.tasks} ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)" > .spur/memory/sessions/wrapup-checkpoint.md'
+
+  - id: skipped
+    description: Terminal — wrap-up skipped (empty task list or operator abort).
+
+transitions:
+  # ── start -> task-resolve ──
+  - from: start
+    to: task-resolve
+    description: Begin wrap-up.
+    guard:
+      kind: always
+
+  # ── task-resolve: non-empty -> doc-sync, empty -> skipped ──
+  - from: task-resolve
+    to: doc-sync
+    description: Task list resolved and non-empty — begin doc-sync.
+    guard:
+      kind: shell
+      options:
+        command: 'test "$(echo "${vars.tasks}" | jq length)" -gt 0'
+  - from: task-resolve
+    to: skipped
+    description: Task list is empty — skip wrap-up.
+    guard:
+      kind: shell
+      options:
+        command: 'test "$(echo "${vars.tasks}" | jq length)" -eq 0'
+
+  # ── linear body: doc-sync -> learning-capture -> metrics-record ──
+  - from: doc-sync
+    to: learning-capture
+    description: Doc sync complete — capture learnings.
+    guard:
+      kind: always
+  - from: learning-capture
+    to: metrics-record
+    description: Learnings captured — record metrics.
+    guard:
+      kind: always
+
+  # ── metrics-record: conditional routing based on feature and merge ──
+  # Declaration order matters: feature-transition is tried first (if feature is set),
+  # then branch-cleanup (if merge=true but no feature), then done (neither).
+  - from: metrics-record
+    to: feature-transition
+    description: Feature id is set — advance feature through legal lifecycle edges.
+    guard:
+      kind: shell
+      options:
+        command: 'test -n "${vars.feature}"'
+  - from: metrics-record
+    to: branch-cleanup
+    description: No feature id, but merge is requested — go to branch cleanup.
+    guard:
+      kind: shell
+      options:
+        command: 'test -z "${vars.feature}" && test "${vars.merge}" = true'
+  - from: metrics-record
+    to: done
+    description: No feature id and no merge — wrap-up is done.
+    guard:
+      kind: shell
+      options:
+        command: 'test -z "${vars.feature}" && test "${vars.merge}" != true'
+
+  # ── feature-transition: -> branch-cleanup (if merge) or done ──
+  - from: feature-transition
+    to: branch-cleanup
+    description: Feature advanced — merge is requested.
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.merge}" = true'
+  - from: feature-transition
+    to: done
+    description: Feature advanced — no merge requested.
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.merge}" != true'
+
+  # ── branch-cleanup: HITL confirmed -> done ──
+  - from: branch-cleanup
+    to: done
+    description: Branch cleanup confirmed — wrap-up complete.
+    guard:
+      kind: always

package/spur.js

@@ -58665,18 +58665,16 @@ var init_task_check = __esm(() => {
     runL3(doc2, entry, findings) {
       const reqBody = doc2.getSection("Requirements");
       if (reqBody !== null && !isPlaceholderBody(reqBody)) {
-        const rLines = reqBody.trim().split(`
-`);
+        const blocks = reqBody.trim().split(/\n\s*\n/).filter((b) => b.trim().length > 0);
         let numbered = 0;
-        let allLines = 0;
-        for (const l of rLines) {
-          if (l.trim().length > 0) {
-            allLines++;
-            if (/^\s*[-*]?\s*(?:\[[ xX]\]\s*)?R\d+\.?\s/.test(l))
-              numbered++;
+        for (const block of blocks) {
+          const firstLine = block.trimStart().split(`
+`)[0] ?? "";
+          if (/^\s*[-*]?\s*(?:\[[ xX]\]\s*)?R\d+\.?\s/.test(firstLine)) {
+            numbered++;
           }
         }
-        if (numbered === 0 || numbered < allLines * 0.5) {
+        if (numbered === 0 || numbered < blocks.length * 0.5) {
           findings.push({
             layer: "L3",
             severity: "warning",
@@ -59966,6 +59964,7 @@ var init_team_service = __esm(() => {
 });
 
 // ../../packages/app/src/workflow/actions/agent-run.ts
+import { existsSync as existsSync4 } from "fs";
 import { mkdir, writeFile } from "fs/promises";
 import { dirname as dirname9, isAbsolute as isAbsolute2, join as join10 } from "path";
 
@@ -60012,6 +60011,7 @@ class AgentRunActionRunner {
     if (continueFlag !== undefined)
       flags.continue = continueFlag;
     const answerFile = asOptionalString(options.answerFile);
+    const expectFile = asOptionalString(options.expectFile);
     const capture = asOptionalBoolean(options.capture) || answerFile !== undefined;
     const agentLabel = agent ?? "<default>";
     if (capture) {
@@ -60022,6 +60022,16 @@ class AgentRunActionRunner {
         await mkdir(dirname9(target), { recursive: true });
         await writeFile(target, answer, "utf8");
       }
+      if (ok2 && expectFile !== undefined) {
+        const target = isAbsolute2(expectFile) ? expectFile : join10(cwd, expectFile);
+        if (!existsSync4(target)) {
+          return {
+            ok: false,
+            data: { exitCode: exitCode2, agent: agentLabel, answer },
+            error: `agent.run (${agentLabel}) exited 0 but expected file is absent: ${expectFile}`
+          };
+        }
+      }
       return {
         ok: ok2,
         data: { exitCode: exitCode2, agent: agentLabel, answer },
@@ -60031,6 +60041,16 @@ class AgentRunActionRunner {
     }
     const exitCode = await this.agentService.run(input, flags);
     const ok = exitCode === 0;
+    if (ok && expectFile !== undefined) {
+      const target = isAbsolute2(expectFile) ? expectFile : join10(cwd, expectFile);
+      if (!existsSync4(target)) {
+        return {
+          ok: false,
+          data: { exitCode, agent: agentLabel },
+          error: `agent.run (${agentLabel}) exited 0 but expected file is absent: ${expectFile}`
+        };
+      }
+    }
     return {
       ok,
       data: { exitCode, agent: agentLabel },
@@ -68685,7 +68705,7 @@ init_src3();
 init_src3();
 init_loader();
 init_src2();
-import { existsSync as existsSync4 } from "fs";
+import { existsSync as existsSync5 } from "fs";
 import { join as join12 } from "path";
 
 // src/workflow/resolve-spur-bin.ts
@@ -68708,11 +68728,11 @@ function resolveWorkflowPath(context3, profile) {
   const bundledRoot = bundledConfigRoot();
   if (bundledRoot !== null) {
     const bundledPath = join12(bundledRoot, "workflows", `${profile.workflowName}.yaml`);
-    if (existsSync4(bundledPath))
+    if (existsSync5(bundledPath))
       return bundledPath;
   }
   const projectPath = join12(context3.cwd, ".spur", "workflows", `${profile.workflowName}.yaml`);
-  if (existsSync4(projectPath))
+  if (existsSync5(projectPath))
     return projectPath;
   return null;
 }
@@ -68967,7 +68987,7 @@ import { join as join13, resolve as resolve4 } from "path";
 var CLI_CONFIG = {
   binaryName: "spur",
   binaryLabel: "spur",
-  binaryVersion: "0.2.11",
+  binaryVersion: "0.2.12",
   configDir: ".spur",
   configFile: ".spur/config.yaml",
   databaseFile: ".spur/spur.db"
@@ -77672,7 +77692,7 @@ async function readTargetStatus(context3, targetPath) {
 init_src3();
 init_loader();
 init_src2();
-import { existsSync as existsSync5, readFileSync as readFileSync6 } from "fs";
+import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
 import { join as join18 } from "path";
 // schemas/section-matrix.schema.json
 var section_matrix_schema_default = {
@@ -78495,7 +78515,7 @@ function loadTemplateContent(projectRoot, variant) {
   if (templateMissSet.has(variant))
     return;
   const localPath = join18(projectRoot, ".spur", "tasks", "templates", `${variant}.md`);
-  if (existsSync5(localPath)) {
+  if (existsSync6(localPath)) {
     const content = readFileSync6(localPath, "utf8");
     templateContentCache.set(variant, content);
     return content;
@@ -78503,7 +78523,7 @@ function loadTemplateContent(projectRoot, variant) {
   const root = bundledConfigRoot();
   if (root !== null) {
     const templatePath = join18(root, "templates", "task", `${variant}.md`);
-    if (existsSync5(templatePath)) {
+    if (existsSync6(templatePath)) {
       const content = readFileSync6(templatePath, "utf8");
       templateContentCache.set(variant, content);
       return content;
@@ -78519,13 +78539,13 @@ function loadTemplateBodies(projectRoot, variant) {
     return cached2;
   let bodies = {};
   const localPath = join18(projectRoot, ".spur", "tasks", "templates", `${variant}.md`);
-  if (existsSync5(localPath)) {
+  if (existsSync6(localPath)) {
     bodies = extractTemplateBodies(readFileSync6(localPath, "utf8"));
   } else {
     const root = bundledConfigRoot();
     if (root !== null) {
       const templatePath = join18(root, "templates", "task", `${variant}.md`);
-      if (existsSync5(templatePath)) {
+      if (existsSync6(templatePath)) {
         bodies = extractTemplateBodies(readFileSync6(templatePath, "utf8"));
       }
     }
@@ -78560,7 +78580,7 @@ async function loadSectionMatrix(projectRoot) {
 }
 async function loadSectionMatrixUncached(projectRoot) {
   const localPath = join18(projectRoot, ".spur", "tasks", "section-matrix.yaml");
-  if (existsSync5(localPath)) {
+  if (existsSync6(localPath)) {
     const data = await loadStructuredSpurConfig(localPath, {
       validateJsonSchema: true,
       embeddedSchemas: EMBEDDED_SPUR_SCHEMAS
@@ -78570,7 +78590,7 @@ async function loadSectionMatrixUncached(projectRoot) {
   const root = bundledConfigRoot();
   if (root !== null) {
     const matrixPath = join18(root, "tasks", "section-matrix.yaml");
-    if (existsSync5(matrixPath)) {
+    if (existsSync6(matrixPath)) {
       const data = await loadStructuredSpurConfig(matrixPath, {
         validateJsonSchema: true,
         embeddedSchemas: EMBEDDED_SPUR_SCHEMAS