@gobing-ai/spur 0.4.0 → 0.4.2

package/.claude-plugin/marketplace.json

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

package/config/config.global.yaml

@@ -157,8 +157,10 @@ workflows:
 # project-relative); the first layer wins per file basename (ADR-113 style).
 # `maker` selects the default DecisionMaker for every decision point, and
 # `makers` overrides it per decision id. Built-in makers: typesafe, fm-local,
-# laya-local (laya-local needs Apple Silicon). An unregistered name is a config
-# error, never a silent fallback. Inspect the effective choice with
+# laya-local (laya-local needs Apple Silicon) and clef (hosted Cloudflare
+# Workers AI, registered only when CLOUDFLARE_ACCOUNT_ID and
+# CLOUDFLARE_AUTH_TOKEN are both set). An unregistered name is a config error,
+# never a silent fallback. Inspect the effective choice with
 # `spur decision status`. `init` never overwrites this file — until you add the
 # keys, the shipped catalog's maker applies (see `status`).
 decisions:

package/config/decisions/gates.yaml

@@ -0,0 +1,36 @@
+$schema: "@gobing-ai/spur/schemas/decision-catalog.schema.json"
+# Decision catalog for evidence-mode operator gates (feature P1 / task 1099,
+# decision-observability-and-adoption.md §4, class keep-human).
+#
+# `gate-evidence` serves `hitl.confirm` actions overridden to
+# `decision.mode: evidence`: the workflow gate responder decides through it
+# instead of the legacy inline maker, so operator gates get catalog maker
+# resolution, the catalog min-confidence floor and `decision.*` lifecycle
+# events with caller `gate` (task 1099 R2). Bundled workflows keep
+# `mode: never` and always pause for the operator (task 1099 R4); no shipped
+# workflow YAML references this id.
+#
+# Resolution: this file ships in the shared layer (the installed package's
+# config/decisions/). A project can override it per basename through
+# .spur/decisions/ or decisions.paths (first layer wins, ADR-113 style).
+version: 1
+
+decisions:
+    gate-evidence:
+        type: choice
+        description: Should an evidence-mode operator gate proceed, stop, or defer to the operator?
+        parameters:
+            prompt:
+                type: string
+                description: The gate question that would have been asked to the operator.
+            evidence:
+                type: json
+                description: Bounded, redacted producer-node evidence recorded for this run.
+            node:
+                type: string
+                description: The workflow node that raised the gate.
+        criteria:
+            yes: The recorded evidence establishes that the gate should proceed.
+            no: The recorded evidence establishes that the gate should not proceed.
+            defer: The evidence is insufficient or conflicting; defer to the operator.
+        fallback: defer

package/config/decisions/history-anatomy.yaml

@@ -0,0 +1,35 @@
+$schema: "@gobing-ai/spur/schemas/decision-catalog.schema.json"
+# Decision catalog for the history-anatomy workflow (feature P1 / task 1098).
+#
+# `anatomy-validation-verdict` backs the rescue-only classification of an
+# ambiguous validation artifact in config/workflows/history-anatomy.yaml
+# (validate state, verdict-normalization step): the deterministic parse stays
+# first, and the catalog decision runs only when the artifact's final line is
+# not exactly `Verdict: PASS` and the file holds zero exact `Verdict: FAIL`
+# lines. Any exact `Verdict: FAIL` line short-circuits to FAIL without calling
+# a maker, so a deterministic FAIL can never be overturned (AC1). The fallback
+# is FAIL — an ambiguous verdict with no model answer fails the 0771 guard,
+# the same routing as before the rescue existed.
+#
+# Resolution: this file ships in the shared layer (the installed package's
+# config/decisions/). A project can override it per basename through
+# .spur/decisions/ or decisions.paths (first layer wins, ADR-113 style).
+version: 1
+
+defaults:
+    # ADR-125 value, kept over the upstream 0.7 default.
+    minConfidence: 0.8
+
+decisions:
+    anatomy-validation-verdict:
+        type: choice
+        description: >
+            Does the history-anatomy validation artifact certify the candidate
+            report? The evidence file is the full validation artifact; the
+            answer decides which verdict line the 0771 guard reads.
+        criteria:
+            PASS: The artifact substantively certifies the candidate report —
+                its only plausible reading is a PASS verdict.
+            FAIL: The artifact does not certify the candidate report, or its
+                verdict cannot be determined from the text.
+        fallback: FAIL

package/config/decisions/idea-pipeline.yaml

@@ -0,0 +1,38 @@
+$schema: "@gobing-ai/spur/schemas/decision-catalog.schema.json"
+# Decision catalogs for the idea pipeline (feature P1 / task 1097, design §5 S5).
+#
+# Rescue-only adoption (design §4): the deterministic parses in
+# config/workflows/idea-pipeline.yaml stay FIRST — the awk derivation over
+# `## Recommendation` and the needs_design JSON read. These entries serve only
+# the output those parses cannot classify: recommendation `unknown`, or a
+# missing/corrupt needs_design JSON. Fallbacks reproduce today's routing
+# (`unknown` keeps the idea-eval pause; `design` keeps the system-design pass),
+# so no default can auto-create a feature.
+#
+# Resolution: this file ships in the shared layer (the installed package's
+# config/decisions/). A project can override it per basename through
+# .spur/decisions/ or decisions.paths (first layer wins, ADR-113 style).
+version: 1
+
+defaults:
+    # ADR-125 value, kept over the upstream 0.7 default.
+    minConfidence: 0.8
+
+decisions:
+    idea-recommendation:
+        type: choice
+        description: Which route does the idea evaluation report recommend?
+        criteria:
+            proceed: Build as evaluated — create the feature.
+            reshape: Build with the evaluation's reshaping — create the feature and fold it in.
+            drop: Do not build — cancel without creating a feature.
+            unknown: The report states no clear recommendation.
+        fallback: unknown
+
+    needs-design:
+        type: choice
+        description: Does this idea need a system-design pass before decomposition?
+        criteria:
+            design: Run the system-design stage before decomposition.
+            skip: Decompose directly — no system-design pass needed.
+        fallback: design

package/config/plugin-scripts.json

@@ -7,6 +7,16 @@
             "contract": "standard",
             "twin": "batch-preflight.mjs"
         },
+        {
+            "rel": "batch-plan.ts",
+            "contract": "standard",
+            "twin": "batch-plan.mjs"
+        },
+        {
+            "rel": "commit-guard.ts",
+            "contract": "standard",
+            "twin": "commit-guard.mjs"
+        },
         {
             "rel": "daily-summary/daily-summary.ts",
             "contract": "standard",
@@ -51,6 +61,11 @@
             "contract": "standard",
             "twin": "inline-run-setup.mjs"
         },
+        {
+            "rel": "inline-run-dispatch.ts",
+            "contract": "standard",
+            "twin": "inline-run-dispatch.mjs"
+        },
         {
             "rel": "feature-verification-steps.ts",
             "contract": "standard",

package/config/rules/docs/sourced-api-claims.yaml

@@ -0,0 +1,60 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
+# Sourced-claims rules (docs corpus) — API/library claims in markdown must be
+# verifiable. A bare version string or a time-anchored API claim ("deprecated
+# since", "added in 0.5.x") on a line with no citation anchor (http(s) URL or a
+# repo path:line reference) is an unverifyable claim: readers cannot tell
+# measured fact from model memory. The deterministic scan is line-level and
+# heuristic — code fences and command examples can legitimately carry bare
+# versions, so severity is info (advisory visibility; the recommended-pre-check
+# gate runs --fail-on warning, so this rule surfaces findings for review without
+# reddening gates — changed-file enforcement happens in SECUA review).
+#
+# The semantic contract — every external API/library claim carries a source
+# citation (URL or path:line) AND a confidence level (HIGH/MEDIUM/LOW) — is
+# owned by the sp-source-driven-development skill and verified in SECUA review
+# (code-verification secu-review checklist). Generic "supports/requires" prose
+# is deliberately out of scope here: in this corpus it is structural writing,
+# not external API assertion, and would drown the signal.
+include:
+  - "docs/**/*.md"
+  - "plugins/sp/skills/**/references/**/*.md"
+exclude:
+  # Legacy task archives are historical records — retro-citing ~900 closed
+  # lines is make-work; the tripwire targets active authoring surfaces.
+  - "docs/tasks/"
+  - "docs/tasks2/"
+  - "docs/tasks3/"
+  - "docs/tasks4/"
+  - "drizzle/**"
+  - "**/node_modules/**"
+rules:
+  - id: cited-version-strings
+    description: >
+      A markdown line asserting a version string (x.y.z) without a citation
+      anchor on the same line — http(s) URL or repo path reference like
+      packages/app/src/foo.ts:123 — is unverifyable. Add the anchor, or drop
+      the version if it is not load-bearing. Confidence level (HIGH/MEDIUM/LOW)
+      is part of the claim contract; see sp-source-driven-development.
+    severity: info
+    evaluator:
+      type: regex
+      config:
+        mode: forbid
+        # Fire when the line has NO citation anchor (no URL, no path:line) AND
+        # contains a semver-ish token. Lookarounds exclude IPs (127.0.0.1) and
+        # longer dotted numerics; fenced-code lines are out of regex reach —
+        # that residual noise is why this is warning, not error.
+        pattern: "^(?!.*(?:https?://|(?:[\\w.-]+/)+[\\w.-]+:\\d+)).*(?<![\\d.])\\d+\\.\\d+\\.\\d+(?!\\.\\d)"
+  - id: cited-api-claims
+    description: >
+      A markdown line making a time- or version-anchored external API claim
+      ("deprecated since 1.2", "introduced in v3", "available since 0.9") must
+      carry a citation anchor on the same line — URL or repo path:line. Add the
+      source (URL or path:line) and the confidence level (HIGH/MEDIUM/LOW);
+      contract in sp-source-driven-development.
+    severity: info
+    evaluator:
+      type: regex
+      config:
+        mode: forbid
+        pattern: "^(?!.*(?:https?://|(?:[\\w.-]+/)+[\\w.-]+:\\d+)).*\\b(?:deprecated (?:since|in|as of)|introduced in|added in|available since|stable since)\\b"

package/config/rules/recommended-pre-check.yaml

@@ -2,9 +2,14 @@ $schema: "@gobing-ai/spur/schemas/preset.schema.json"
 # Recommended pre-check preset — portable rule categories bundled with the catalog.
 # Use with: spur rule run --preset recommended-pre-check
 #
-# Runs BEFORE tests (test-pre-check). Extends six categories: typescript,
-# structure, boundary, surface, ui, and strict (ui since bc267cc8, strict since
-# 79186391). TSDoc exports run in post-check alongside coverage-gate.
+# Runs BEFORE tests (test-pre-check). Extends categories: typescript,
+# structure, boundary, surface, ui, strict (ui since bc267cc8, strict since
+# 79186391), and docs (sourced-api-claims, 2026-10-07). TSDoc exports run in
+# post-check alongside coverage-gate.
+#
+# TEMPORARY (2026-10-08): `docs` removed from extends to unblock the gate —
+# restore it (add `- docs` back) once sourced-api-claims finding noise is
+# triaged. Recapture the raw-json-baseline fixtures in the same change.
 name: recommended-pre-check
 extends:
   - typescript

package/config/rules/structure/scratch-evidence-pointer.yaml

@@ -0,0 +1,35 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
+# ADR-131 consumer invariant: `.spur/run/` may be absent in any later run, so a
+# durable record must not cite it as evidence. `done_reason` is the one
+# machine-consumed pointer with a fixed shape, so this rule anchors there: a task's
+# close rationale must name `.spur/memory/evidence/<wbs>-verdict.json` (or the
+# tracked `## Testing` section), never the scratch copy.
+#
+# Scope — the pointer field, not the directory string. 600+ tracked documents
+# legitimately mention `.spur/run/` while documenting what the pipeline writes
+# there (that is the mechanism the ADR governs); only a `done_reason:` value that
+# points at a scratch verdict is a citation of record. Prose mentions in any
+# section, design doc or source file never match, so no allowlist is needed.
+#
+# Out of scope, and this rule makes no claim to cover it: executable source under
+# the gitignored `.spur/run/` (a hook or script loader registered from scratch).
+# No loader registers from there — verified 2026-10-09, and the runtime-guard task
+# that would have covered the class (1145) was cancelled. The rule engine reads
+# tracked files only, so that class is invisible here by construction.
+#
+# Repair: `spur task migrate-anchors --wbs <wbs>` retargets the pointer (1140).
+include:
+  - "docs/tasks*/**/*.md"
+rules:
+  - id: no-scratch-verdict-pointer
+    description: >
+      done_reason cites a .spur/run verdict, which ADR-131 makes disposable: the
+      directory may be absent in any later run, so a consumer resolving this pointer
+      reads a broken reference. Cite .spur/memory/evidence/<wbs>-verdict.json, or the
+      tracked Testing section when no durable copy was retained; repair with
+      `spur task migrate-anchors --wbs <wbs>`.
+    severity: error
+    evaluator:
+      type: rg
+      config:
+        pattern: "^done_reason:.*\\.spur/run/[0-9]{4}(-|/)verdict\\.json"

package/config/script-placement-baseline.json

@@ -7,8 +7,8 @@
             "reason": "Keep, sp-owned git/gh loop; cited exemption (plan \u00a72)"
         },
         "plugins/sp/scripts/wrapup-steps.ts": {
-            "kinds": ["budget"],
-            "reason": "Keep (budget exemption), W2 (plan \u00a72)",
+            "kinds": ["budget", "corpus-parse"],
+            "reason": "Keep (budget exemption), W2 (plan \u00a72). corpus-parse: the 1147 R1 doc-sync write-scope guard excludes the task/feature corpus by path prefix -- a scope exclusion, not corpus parsing (same class as wrapup-drift-probe.ts).",
             "exempt": true
         },
         "plugins/sp/scripts/batch-preflight.ts": {

package/config/templates/AGENTS.md

@@ -36,7 +36,7 @@ All product development work goes through the harness by default.
 | ------ | ---------- | -------- |
 | Plan a feature (intake → AC → tasks) | `/sp:dev-plan`, `/sp:dev-idea` | Freeform feature files without gates |
 | Drive one task end-to-end | `/sp:dev-run <wbs>` or **`sp:super-planner`** | Implement with no task / no pipeline |
-| Batch or parallel task runs | `/sp:dev-runall` (host sequential; **`sp:super-planner`** explicit/parallel), `/sp:dev-parallel` | Unordered multi-task thrash |
+| Batch or parallel task runs | `/sp:dev-runall` (host sequential; `--mode parallel\|auto` → **`sp:super-planner`**) | Unordered multi-task thrash |
 | Batch-refine tasks under a feature | `/sp:dev-refineall --feature <id> --auto` | Hand-looping `/sp:dev-refine` per WBS |
 | Multi-step corpus CLI (tasks/features/rules/workflows) | **`sp:expert-spur`** | Raw Write/Edit on corpus files |
 | Look up `spur` verbs / flags / `--json` | Skill **`sp:spur-cli`** | Inventing flags from memory |

package/config/workflows/feature-lifecycle.yaml

@@ -9,7 +9,7 @@
 "$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
 kind: state-machine
 name: feature-lifecycle
-version: "1"
+version: "2"
 description: >
   Feature lifecycle FSM (design §2.3, §5.1, DD-13). States are the canonical
   FeatureStatus vocabulary; transitions encode the §2.3 graph including the
@@ -50,7 +50,14 @@ states:
           # applied as a replacement, so the inner run lost spurBin and loadModule
           # fell into source mode (0948 R1). The nested JSON is shell-expanded:
           # $spurBin inside the double quotes keeps a multi-word invocation intact.
-          command: '$spurBin workflow run feature-verification.yaml --vars "{\"featureId\":\"$featureId\",\"spurBin\":\"$spurBin\"}"'
+          # 1147 R4: clear the inherited nested-run marker for this ONE child. The
+          # bounded, definition-pinned feature-verification pass (no agent.run, no
+          # further nested run) is a legitimate child, but the outer run's
+          # SPUR_WORKFLOW_RUN_ACTIVE marker rides every child env — so the CLI's
+          # nested-run refusal (0610 R4) rejected it and the same pass that passes
+          # standalone failed here with a bare exit 1. The recursion guard stays
+          # binding for every other nested invocation.
+          command: 'env -u SPUR_WORKFLOW_RUN_ACTIVE $spurBin workflow run feature-verification.yaml --vars "{\"featureId\":\"$featureId\",\"spurBin\":\"$spurBin\"}"'
   - id: blocked
     description: Impediment; work suspended.
   - id: done

package/config/workflows/history-anatomy.yaml

@@ -250,6 +250,28 @@ states:
                 grep -vx 'Verdict: PASS' "$f" > "$f.tmp" && printf 'Verdict: PASS\n' >> "$f.tmp" && mv "$f.tmp" "$f";
               fi;
             fi
+      - kind: shell
+        options:
+          # 1098 ambiguous-verdict rescue (design §5 S6, rescue-only): runs AFTER the
+          # normalization step and only when the artifact is still undecidable — final
+          # line not `Verdict: PASS` and ZERO exact `Verdict: FAIL` lines (zero PASS
+          # lines or several). The catalog decision `anatomy-validation-verdict`
+          # classifies the artifact. `Verdict: PASS` is appended ONLY from a model
+          # answer (source == "model" and value == "PASS"; the jq `// .data.*` arms
+          # also accept the ADR-091 envelope shape); a fallback, a non-model source,
+          # a jq failure or any maker failure appends `Verdict: FAIL`. The zero-FAIL
+          # guard short-circuits BEFORE the maker call, so a deterministic FAIL is
+          # never overturned (AC1) and the 0771 guard/assert-clean stay the
+          # authorities. Separate action from normalization to stay inside the
+          # ADR-115 composition budget (§1.2 shell tier).
+          command: >-
+            f=.spur/run/$__runId-validation.txt;
+            if [ -f "$f" ] && [ "$(grep -cx 'Verdict: FAIL' "$f")" = 0 ] && ! tail -n 1 "$f" | grep -qx 'Verdict: PASS'; then
+              d=$("$spurBin" decision run anatomy-validation-verdict --evidence "$f" --json || true);
+              v=$(printf '%s' "$d" | jq -r 'if (.source // .data.source) == "model" and (.value // .data.value) == "PASS" then "PASS" else "FAIL" end' 2>/dev/null);
+              [ "$v" = "PASS" ] || v="FAIL";
+              printf 'Verdict: %s\n' "$v" >> "$f";
+            fi
       - kind: shell
         options:
           command: >-

package/config/workflows/idea-pipeline.yaml

@@ -79,6 +79,10 @@ vars:
 
 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
@@ -113,6 +117,10 @@ states:
             printf 'FAIL\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
@@ -146,8 +154,35 @@ states:
             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).
+      - 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)";
+            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.
+      - 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"
 
   - 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,
@@ -164,6 +199,10 @@ states:
             mode: never
 
   - 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
@@ -203,6 +242,10 @@ 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"
@@ -279,6 +322,10 @@ states:
             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
@@ -306,6 +353,10 @@ states:
       # 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
@@ -356,6 +407,10 @@ 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
@@ -383,6 +438,10 @@ states:
             mode: never
 
   - 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
@@ -427,6 +486,10 @@ states:
             ' "$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
@@ -443,6 +506,10 @@ states:
             mode: never
 
   - 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
@@ -472,6 +539,10 @@ 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,
@@ -521,6 +592,10 @@ 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