@gobing-ai/spur 0.3.92 → 0.3.93

package/plugins/sp/skills/spur-dev/references/cross-cutting.md

@@ -120,6 +120,14 @@ This is **the same rule, not an exception**: `--agent` names who does the thinki
 the thinking happens in the stages. Selecting an executor for a loop that runs no prompts would be
 meaningless.
 
+**Fleet executor (0942, ADR-126, opt-in).** A workflow run may opt its `agent.run` stages into the
+agent fleet control plane by mapping the pipeline selector to `executor: 'fleet'` (dev-run /
+dev-runall `--agent fleet`). The stage dispatches to a fleet member through the fleet coordination
+surface instead of spawning a subprocess; a subprocess fallback happens only when the run declares
+`executorFallback: 'traditional'`, and an unavailable fleet otherwise fails the stage explicitly
+(0937 `failed-agent`). This is an additional `agent.run` transport — it does not change the
+`--agent` selector semantics documented above, and the interactive driver never resolves to it.
+
 **Interactive task pipelines invert control into the host session (ADR-047 amendment).**
 `dev-run --mode full` and sequential `dev-runall` with omitted `--agent` or explicit `--agent
 inline` interpret the existing `task-pipeline.yaml` in the host session; they do not launch `spur
@@ -785,8 +793,12 @@ The Design Approval Gate is the taste gate between system design and decompositi
 **The `needs_design` signal routing:**
 
 The signal is emitted by the `discovery` state's brainstorm dispatch and written to
-`.spur/run/idea-needs-design.json`. The `feature-check` state's transition guards read it to
-determine routing:
+`.spur/run/idea-needs-design.json`. A deterministic shell action at the end of the `ac-generate`
+and `feature-check` onEnter lists (0945 R2) folds `design` × `needs_design` once into
+`.spur/run/<runId>-idea-design-route.txt` (`design` | `skip`; missing/corrupt JSON fails safe to
+`design`) and the two recorded check statuses into `.spur/run/<runId>-idea-ac-ready.status`
+(`PASS` only when both are PASS). The transition guards read those derived files to determine
+routing — they never re-derive the signal inline (0769):
 
 | `design` var | `needs_design` signal | Route |
 | --- | --- | --- |

package/plugins/sp/skills/spur-dev/references/document-authoring.md

@@ -0,0 +1,85 @@
+---
+name: document-authoring
+description: Light Markdown contracts for plan records and non-UI design satellites.
+see_also:
+  - spur-dev
+  - planning-workflow
+  - doc-evolve
+---
+
+# Plan and design document authoring
+
+Use [plan.md](../templates/plan.md) for a new `docs/plans/*.md` working record and
+[design.md](../templates/design.md) for a new `docs/design/*.md` non-UI contract satellite.
+The project constitution owns their authority and maintenance; these templates are writing aids,
+not parser schemas. Keep Markdown readable even when frontmatter is absent in a legacy file.
+
+| Document | Job | Authority |
+| --- | --- | --- |
+| `docs/plans/` | Ordered work: intended outcome, premises, dependencies, execution sequence, verification, and follow-up. Older proposals and investigations remain working records. | Working record. Accepted conclusions take effect in their owner, such as an ADR, feature, roadmap, or design satellite. |
+| `docs/design/` | Issue, context, solution, and its observable non-UI contract | Governed satellite of `docs/04_DESIGN.md`; label proposals and current behavior separately. |
+
+## Compose a new file
+
+1. Choose the owner before writing. Reuse an existing satellite when it already owns the surface.
+   Keep root `DESIGN.md` for UI rules and `03_ARCHITECTURE.md` for current system topology.
+2. Copy the relevant template. Replace placeholders. Keep `kind`, a descriptive `title`, a
+   truthful `status`, `created_at`, `updated_at`, `related` links, and `tags` for categorization.
+   Use ISO dates; leave `related` or `tags` empty when none apply. Keep one H1 matching the title.
+3. Use headings for the reader's question. The template's prompts are a starting shape: remove
+   inapplicable sections and keep specialized sections required by the producing workflow, such as
+   a brainstorm's `## Design Summary`. Number new sections in reading order. Plans make the
+   execution sequence and its premises usable; designs explain the issue, context, solution, and
+   observable contract. Never fill empty boilerplate.
+4. For a design satellite, write detail first, then add its pointer to `04_DESIGN.md` if missing.
+   Update an existing index row only when its indexed facts change. Do not put task receipts there.
+
+## Frontmatter vocabulary
+
+Soft conventions for consistency and tag filtering, not a validator. Unknown values stay readable.
+
+| Field | Values |
+| --- | --- |
+| `kind` | `plan` for any `docs/plans/` record, `design` for any `docs/design/` satellite. Nothing else. |
+| `status` (plan) | `draft`, `proposed`, `approved`, `in-progress`, `done`, `superseded` |
+| `status` (design) | `proposed`, `accepted`, `implemented`, `superseded` |
+| `tags` | Ordered: one record-type tag, then owning feature ids (for example `H14`), then at most two area tags. |
+| `related` | Repo-relative paths or feature/task ids; no prose. |
+
+Record-type tags — plan: `brainstorm`, `proposal`, `investigation`, `audit`, `map`, `execution`,
+`evidence`; design: `contract` (observable surface) or `system` (internal mechanism). Area tags:
+`cli`, `server`, `web`, `workflow`, `planning`, `history`, `observability`, `agent`, `plugin`,
+`docs`, `config`. A project may extend the area list; reuse a tag already in the corpus
+(`rg -n '^tags:' docs/plans docs/design`) before adding one.
+
+A producing workflow may keep its own keys beside these, such as a brainstorm's `needs_design` and
+`run_id`, and its own section shape. The shared fields still apply.
+
+## Revise an existing file
+
+Read the whole file and its inbound links first. Preserve the filename, meaningful headings,
+anchors, dates, decisions, and historical status. Add missing metadata from evidence; label
+unknowns instead of guessing. Restructure only where clarity improves, and keep a forwarding
+heading when an anchor cannot be migrated safely. Update `updated_at` only for a substantive edit.
+Do not turn an old proposal into a claim about current behavior without checking the owning source.
+
+Legacy metadata upgrade:
+
+- **Map** `date` → `created_at` and `feature`/`feature_id`/`task_wbs`/`parent_task` → `related`.
+  `title` is the H1 text; `topic` maps to `title` only when the file has no H1, otherwise drop it.
+- **Owners:** when no owner key exists, a feature or task record that links the file
+  (`rg -l <filename> docs/features <task dir>`) is evidence for `related`. Ids found only in body
+  prose are not; requirement and priority labels look like feature ids.
+- **Keep** workflow and provenance keys unchanged (`needs_design`, `run_id`, `doc`, `authority`,
+  `owns`, `read_before`, `edit_rules`, `version`, `derived_from`).
+- **Dates:** `created_at` comes from a legacy `date`, else the filename date prefix, else the first commit
+  (`git log --follow --diff-filter=A --format=%as -- <file> | tail -1`), else leave it out and flag it.
+  `updated_at` is the existing value or the last commit date; do not bump it for a metadata-only edit.
+- **Status:** use the vocabulary value only when the legacy value or body states it unambiguously
+  (`shipped`/`implemented`/`built …` → `implemented`; `approved-with-feedback` → `approved`).
+  Otherwise keep the legacy value and flag it for the operator. No status is better than a guessed one.
+- **Headings:** never renumber or rename legacy headings; numbering applies to new files only.
+
+For a bounded, read-only review of legacy files, use `sp:spur-doctor`. Apply accepted document
+proposals in place using this guide, then use `sp:doc-evolve` to check affected key-document sync.
+No bulk conversion or strict format check is required to read or maintain existing documents.

package/plugins/sp/skills/spur-dev/references/execution-batch.md

@@ -270,7 +270,7 @@ Only two flags cross the orchestrator→pipeline boundary; both are merged into
 | Flag | Effect on per-task `--vars` |
 | --- | --- |
 | `--auto` | sets `"profile":"auto"` (skips the HITL approve gate). Omitting it forwards nothing, so the pipeline uses its default profile (standard — HITL pause surfaces to the operator). (R4.2) |
-| `--agent <value>` | omit/`inline` in interactive sequential mode selects the host driver and is not forwarded. `auto` or a name sets **both** `"agent":"<value>"` and `"implementAgent":"<value>"` so every workflow `agent.run` step — including implement — spawns that executor. Headless omit/inline falls through the executor precedence chain. To pin ONLY implement, pass `--vars '{"implementAgent":"..."}'` separately; that explicit var selects the subprocess path. (R4.3, tasks 0483/0503) |
+| `--agent <value>` | omit/`inline` in interactive sequential mode selects the host driver and is not forwarded. `auto` or a name sets **both** `"agent":"<value>"` and `"implementAgent":"<value>"` so every workflow `agent.run` step — including implement — spawns that executor. Headless omit/inline falls through the executor precedence chain. To pin ONLY implement, pass `--vars '{"implementAgent":"..."}'` separately; that explicit var selects the subprocess path. (R4.3, tasks 0483/0503) The opt-in `fleet` value instead maps the run to `"executor":"fleet"`: every `agent.run` stage dispatches through the agent fleet control plane (0942/ADR-126) and neither `agent` nor `implementAgent` is pinned. |
 
 The host session remains the orchestrator for interactive sequential omit/inline. `sp:super-planner`
 owns explicit-executor and parallel paths; there the flag pins the per-task step executor, not the

package/plugins/sp/skills/spur-dev/references/flag-glossary.md

@@ -69,6 +69,14 @@ inline is the default selector and omitted/explicit `inline` resolve identically
 the concrete coding-agent tool; `executor` remains the domain-layer role and is not a command flag.
 `inline` and `auto` are reserved values — config validation rejects an executor claiming either.
 
+**Fleet executor (0942, ADR-126, opt-in).** On the pipeline selectors (`dev-run`, `dev-runall`),
+`--agent fleet` maps the workflow run to the executor var `executor: 'fleet'`: every `agent.run`
+stage dispatches through the agent fleet control plane instead of spawning a subprocess, with a
+subprocess fallback only when the run declares `executorFallback: 'traditional'`; otherwise an
+unavailable fleet fails the stage loudly (0937 `failed-agent`). `fleet` is deliberately not part of
+the `<inline|auto|name>` selector grammar above — the value table and the executor precedence chain
+are unchanged. Contract: [fleet-config-declaration.md](../../../../../docs/design/fleet-config-declaration.md).
+
 #### `--inline` (removed — collapsed into `--agent`)
 
 **Anchor:** `#flag-inline` (stub retained to avoid dangling external links).

package/plugins/sp/skills/spur-dev/references/gate-checklists.md

@@ -89,8 +89,9 @@ Entered before `task-pipeline.yaml` `review` state dispatches `sp:code-verificat
 
 - [ ] The implementation matches the task's `## Plan` checklist (every checked item maps to a code/test/doc change).
 - [ ] `git status` shows only changes traceable to this task's Plan (no drive-by edits).
-- [ ] Lint and typecheck pass (`bun run lint`).
-- [ ] Tests pass (`bun run test`) — no `.skip`, `xfail`, or commented-out tests.
+- [ ] Check receipt current: `quality-gate.ts status` reports `reuse: true` for
+      `.spur/run/<wbs>-check-receipt.json` at the current digest; run `bun run spur-check` only
+      when it reports stale or missing (0940 — never re-run the full chain on a reusable receipt).
 - [ ] New `biome-ignore` / `eslint-disable` suppressions: none, or each is justified inline.
 - [ ] No new `console.*` in scripts (use a project logger if one exists).
 - [ ] The `## Solution` section records the file:line change map and rationale.

package/plugins/sp/skills/spur-dev/references/inline-pipeline-driver.md

@@ -23,7 +23,7 @@ the resolved actions and guards of every `.spur/workflows/*.yaml`; any element p
 in one and absent in the other fails the check. Add a new kind here when the driver
 implements it; remove the entry when the corresponding kind is dropped from the YAML.
 
-**Actions:** `shell` · `note` · `doctor.probe` · `file.read.into-var` · `hitl.confirm` · `hitl.input` · `hitl.select` · `agent.run` · `proof.fingerprint` · `run.artifact` · `command.gate`
+**Actions:** `shell` · `note` · `doctor.probe` · `file.read.into-var` · `hitl.confirm` · `hitl.input` · `agent.run` · `proof.fingerprint` · `run.artifact` · `command.gate` · `decide`
 
 **Guards (transitions):** `always` · `shell` · `action-ok` · `contract-violation`
 
@@ -497,6 +497,24 @@ The driver reaches it through the existing run delegate (`$SETUP_SCRIPT`,
   (0887 R8), so `completed_at − started_at == duration_ms` exactly; a back-date failure is
   recorded (`action.backdate`) and never affects the run.
 
+- **A `decide` action (0941)** — the driver never executes the DecisionMaker itself; it delegates
+  to the same app runner the engine registers, which writes the resultFile row (schemaVersion 1)
+  and returns the decision, then the delegate records the `action_runs` row (`kind=decide`)
+  through the same writer as every other action:
+
+  ```bash
+  bun "$SETUP_SCRIPT" --decide --run-id "$RUN_ID" --node <state-id> --options-json <options-file>
+  ```
+
+  The options JSON mirrors the YAML `decide` options (`id`, `method: choice|noul`, `question`,
+  `choices`/`default`, optional `evidence`, optional `minConfidence`, `resultFile`); paths resolve
+  against the project workdir. The decision never pauses and never fails the run for model
+  problems: a degraded outcome (feature switch off, no backend, error, timeout, low confidence)
+  prints `ok:true` with `degraded:true`, the declared `reason`, and `value = default`, and exits
+  `0` — route on the resultFile's `.value` with the declared file guards. Only an invalid options
+  schema exits `1` (fail closed), and usage errors exit `2`. The `action_runs` trace row is
+  best-effort exactly like `--action`.
+
 - **At the run's declared terminal state** — before the driver reports the run complete, close the
   row so a successful inline run is never left non-terminal for `spur workflow clean` to reap as
   stale:

package/plugins/sp/skills/spur-dev/references/planning-workflow.md

@@ -198,11 +198,11 @@ task Design.
 order (§4.5 rule 5 / sync trigger **T9**):
 
 1. **Satellite first.** Write/update `docs/design/<slug>.md`. `<slug>` is the stable grep anchor —
-   derive it from the feature name (kebab-case), and **reuse the existing slug** on re-runs. Capture
-   the chosen approach + one-line reason, rejected alternatives, key interface/type **signatures**
-   (not bodies), invariants, and the surface it touches. Do **not** restate the satellite file format
-   here — follow the shape of existing satellites (`docs/design/server-side-adjustment-design.md`,
-   `workflow-observability.md`).
+   derive it from the feature name (kebab-case), and **reuse the existing slug** on re-runs. For a
+   new file use [document-authoring.md](document-authoring.md) and its design template; for an
+   existing file preserve its headings and anchors. Capture the chosen approach + one-line reason,
+   rejected alternatives, key interface/type **signatures** (not bodies), invariants, and the
+   surface it touches.
 2. **Index second.** Add or update the satellite's row in `docs/04_DESIGN.md §0` (the `| Satellite |
    Area | Status |` table) — pointer + one-line area + status only, never a restatement of the body.
 

package/plugins/sp/skills/spur-dev/templates/design.md

@@ -0,0 +1,31 @@
+---
+kind: design
+title: <specific non-UI contract or system design>
+status: proposed
+created_at: YYYY-MM-DD
+updated_at: YYYY-MM-DD
+related: []
+tags: []
+---
+
+# <Specific non-UI contract or system design>
+
+## 1. Issue and scope
+
+<Specific issue or tasks this design addresses, observed impact, boundaries, and whether the solution is proposed or current. Link the owning records.>
+
+## 2. Context and constraints
+
+<Relevant current behavior, evidence for the issue, and constraints the solution must respect. Link to 03 for wider architecture.>
+
+## 3. Solution
+
+<Chosen approach and how it resolves the issue. Show ownership, boundaries, and flow; distinguish proposed behavior from implemented behavior.>
+
+## 4. Contract and compatibility
+
+<Observable inputs, outputs, defaults, errors, invariants, edge cases, and migration behavior needed to implement or use the solution. Omit inapplicable parts.>
+
+## 5. Tradeoffs and open questions
+
+<Why this solution was chosen, material costs or alternatives, and unresolved questions or follow-up. Link ADR decisions instead of restating them.>

package/plugins/sp/skills/spur-dev/templates/plan.md

@@ -0,0 +1,32 @@
+---
+kind: plan
+title: <specific title>
+status: draft
+created_at: YYYY-MM-DD
+updated_at: YYYY-MM-DD
+related: []
+tags: []
+---
+
+# <Specific title>
+
+## 1. Objective and outcome
+
+<Issue or tasks this plan addresses, intended result, scope, and how completion will be recognized. Link the owning feature or tasks.>
+
+## 2. Premises and dependencies
+
+<Facts, assumptions, prerequisites, decisions, and blockers that affect the sequence. Link evidence; mark unverified premises.>
+
+## 3. Execution sequence
+
+1. <Action, prerequisite, and tangible output or checkpoint. Name an owner when coordination matters.>
+2. <Next action. Show dependencies and safe parallel work explicitly.>
+
+## 4. Risks and verification
+
+<What could change the sequence, the fallback or decision point, and how the intended result will be verified.>
+
+## 5. Follow-up
+
+<Handoff, remaining actions, and deferred work with owners or links when known. Omit if none.>

package/plugins/sp/skills/spur-doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spur-doctor
-description: "Evaluate spur artifacts from read-only CLI evidence — tasks, features, rules, workflows, agent specs — reflect over sp:history-anatomy findings, and return a proposal table. Diagnoses spur artifacts, not runtime environments (that is spur agent doctor). Triggers: check artifact health, propose evolution, reflect over history findings."
+description: "Evaluate spur artifacts and plan/design Markdown from read-only evidence, reflect over sp:history-anatomy findings, and return a proposal table. Diagnoses artifacts, not runtime environments (that is spur agent doctor). Triggers: check artifact health, propose evolution, review legacy documents."
 license: Apache-2.0
 version: 1.0.0
 metadata:
@@ -26,16 +26,19 @@ see_also:
 # sp:spur-doctor — evaluate spur artifacts and propose changes
 
 One cross-noun method (ADR-114, [spur artifact evolution](../../../../docs/design/spur-artifact-evolution.md)
-§2): gather **read-only CLI evidence** about tasks, features, rules, workflows and agent specs,
-**reflect** over `sp:history-anatomy` findings, and return a **proposal table**. It diagnoses spur
-**artifacts** — definitions, rules, corpus records — not runtime environments: whether an agent
+§2): gather **read-only evidence** about tasks, features, rules, workflows, agent specs, and
+plan/design Markdown; **reflect** over `sp:history-anatomy` findings; and return a
+**proposal table**. It diagnoses spur artifacts — definitions, rules, corpus records and documents —
+not runtime environments: whether an agent
 binary, host session or tool install is healthy is `spur agent doctor`'s job, not this skill's.
 
 ## Read-only invariant
 
-The doctor **writes nothing and names no mutating verb**. It performs no task, feature, rule or
-workflow write — the operator accepts rows and `sp:spur-composer`
-([../spur-composer/SKILL.md](../spur-composer/SKILL.md)) applies them. A caller that wants a
+The doctor **writes nothing and names no mutating verb**. It performs no task, feature, rule,
+workflow or document write. The operator accepts rows; `sp:spur-composer`
+([../spur-composer/SKILL.md](../spur-composer/SKILL.md)) applies corpus rows, while a document
+author applies plan/design rows using the
+[spur-dev authoring guide](../spur-dev/references/document-authoring.md). A caller that wants a
 record saves the returned table under `docs/reports/`; the doctor creates no artifact store.
 
 - **History enters only through `sp:history-anatomy` findings.** Raw history records stay out
@@ -55,9 +58,51 @@ record saves the returned table under `docs/reports/`; the doctor creates no art
 | workflow | `spur workflow validate --json` (findings by `level`), `node "$(superskill script path sp workflow-step-profile.mjs)" <workflow> --json` |
 | agent spec | `spur agent list --specs --json` |
 | history | A `sp:history-anatomy` report ([../history-anatomy/SKILL.md](../history-anatomy/SKILL.md)), never raw history records |
+| plan/design Markdown | The file itself, the project constitution, the relevant spur-dev template, and inbound index/links; no new CLI needed |
 
 Every row of a proposal cites the evidence it rests on. No anchor, no proposal.
 
+## Legacy plan and design review
+
+Enumerate `docs/plans/*.md` and `docs/design/*.md` with `rg --files` and sort the paths. Include
+every Markdown path in the review; JSON and other files are outside this contract. For a large set,
+freeze the list and split it into named path groups by record type (for example
+`docs/plans/*-brainstorm.md`, other plans, designs), at most ~40 files each, and combine their
+coverage lists. Read each file and the project constitution before judging it. Report scanned paths
+and counts of proposals and no-ops, so an omitted file is visible.
+
+Compare each plan with the [plan template](../spur-dev/templates/plan.md) and each design with the
+[design template](../spur-dev/templates/design.md), using the
+[authoring guide](../spur-dev/references/document-authoring.md) for meaning. Look for missing or
+unsupported `kind`, title, status, dates, material related links or useful tags; unclear objective,
+premises, execution sequence or follow-up in a plan; unclear issue, context, solution, contract or
+compatibility in a design; and a missing `04_DESIGN.md` pointer for a design satellite.
+These are **review prompts**, not format errors. Keep specialized sections required by a producing workflow.
+
+Judge metadata against the authoring guide's **frontmatter vocabulary** and **legacy metadata
+upgrade** rules, so every row in a batch makes the same choice: the same key mapping, `title` from
+the H1, `related` from owner keys or linking feature/task records, `created_at` source order
+(legacy `date`, filename prefix, first commit, else flag), status mapping only when unambiguous,
+and tags in record-type → feature → area order from the shared list. A row whose status or tag needs
+judgment says so in `change` instead of picking a value. Never propose renumbering or renaming a
+legacy heading.
+
+Propose only evidence-backed, useful edits. A proposal names the exact file and heading or
+frontmatter field, cites a line and the governing rule, and says what can be inferred and what
+needs an operator answer. Preserve filenames, anchors, original dates, decisions and historical
+status. Do not silently promote a proposal to current behavior, invent metadata, or rewrite a
+whole file to fit a template. A conforming or intentionally specialized file is a no-op.
+
+The `apply` cell for a document row points to the spur-dev authoring guide; the author edits an
+accepted row in place, then runs `sp:doc-evolve` sync-check for affected key documents and verifies
+links, headings, frontmatter and the `04` index when applicable. No bulk conversion or strict
+validator is required for old files.
+
+For a batch, the caller saves each group's table as
+`docs/reports/YYYY-MM-DD-<group>-doc-upgrade-review.md`. After the operator accepts rows, the author
+applies one group's metadata-only rows together and commits them as one change; body restructuring
+rows stay per file. Flagged rows wait for the operator's answer.
+
 ## Workflow step profile and cache-window flags
 
 The step profile (`plugins/sp/scripts/workflow-step-profile`, ADR-065 plugin entrypoint) reads
@@ -114,25 +159,26 @@ Return one row per actionable finding, with exactly these columns:
 | Column | Content |
 | --- | --- |
 | `key` | The finding key, or `<noun>:<id>:<check>` for an artifact finding |
-| `evidence` | The CLI output or report section the row rests on |
+| `evidence` | CLI output, report section, or document path and line the row rests on |
 | `action` | One action class from the reflection map (or the per-noun evaluation) |
 | `change` | The proposed change, in one line |
-| `apply` | The `spur` verb or composer procedure that lands it |
+| `apply` | The `spur`/composer route for corpus rows or the spur-dev authoring guide for document rows |
 | `verify` | The evidence to re-run after applying |
 
 Rules:
 
-- The `apply` route is always a `spur` verb or a gated composer step — never a raw file edit this
-  skill performs. Shared-workflow rows route through the composition ladder's shared step.
+- Corpus `apply` routes use a `spur` verb or gated composer step; document rows use the spur-dev
+  authoring guide. The doctor itself never edits either surface. Shared-workflow rows route
+  through the composition ladder's shared step.
 - A `task` row carries the finding `key` in the task body (the history-anatomy handoff route).
 - Rows are proposals only. No applied change, diff, or command output claimed as run.
 
 ## What this skill is not
 
-- **Not the applier.** `sp:spur-composer` applies accepted rows; this skill performs no
-  task/feature/rule/workflow write.
+- **Not the applier.** `sp:spur-composer` applies accepted corpus rows and document authors apply
+  accepted document rows; this skill performs no write.
 - **Not a runtime doctor.** Environment, binary and session readiness belong to
-  `spur agent doctor`; this skill diagnoses spur artifacts from CLI evidence.
+  `spur agent doctor`; this skill diagnoses artifacts from read-only evidence.
 - **Not a history interpreter.** Findings come from `sp:history-anatomy` reports, never from raw
   history records.
 - **Not a loop.** Recurring evolution passes belong to `sp:super-planner` or a workflow.

package/schemas/state-machine-workflow.schema.json

@@ -135,6 +135,10 @@
                         "type": "string",
                         "minLength": 1
                     },
+                    "terminalReason": {
+                        "type": "string",
+                        "description": "Closed terminal-reason enum declared when this edge finalizes the run (0937 R3; required for edges into failureStates)."
+                    },
                     "description": {
                         "type": "string"
                     },