@gobing-ai/spur 0.4.0 → 0.4.2

package/plugins/sp/skills/spur-cli/references/agent.md

@@ -22,19 +22,19 @@ that before using `run` for fan-out dispatch.
 | Verb | Purpose | Key flags |
 | ---- | ------- | --------- |
 | `run <prompt>` | Execute a prompt or slash command via a coding agent | `--agent <name>` `--spec <id>` `--model <name>` `--mode <mode>` `--continue` `--cwd <path>` `--drain` `--json` |
-| `wait [<specId>]` | Identity-pinned wait for an occupant run to reach a lifecycle state (G4 wave 2; `--role` selector per 0685) | `--role <name>` `--run <runId>` `--until <state>...` `--timeout <ms>` `--json` |
+| `wait [<specId>]` | Identity-pinned wait for an occupant run to reach a lifecycle state (G4 wave 2; `--role` selector per 0685) | `--role <name>` `--run <runId>` `--until <state>...` `--timeout <ms>` `--inbox <id>` `--json` |
 | `trace <runId>` | Print one execution record's lineage — the run, its dispatch parents, agent session ids and streams (1076 R4, ADR-132) | `--follow` `--timeout <ms>` `--json` |
 | `list` | List detected coding agents, or agent specs with `--specs` (live run status + member session merged from `spur self serve`) | `--specs` `--server <url>` `--json` |
 | `report` | Report a fleet member lifecycle state (`working`/`idle`/`blocked`) from a host hook (G73 R1/R2, task 1080) | `--state <state>` `--seq <ns>` `--spec <id>` `--json` |
 | `join` | Join the fleet as a guest occupant — a live session that pulls its own work (G73 R2, task 1081) | `--role <name>` `--id <id>` `--session-id <sid>` `--pid <n>` `--executor <name>` `--json` |
-| `leave` | Leave the fleet: release the guest lease, retire the occupant, return claimed messages to pending | `[id]` `--session-id <sid>` `--json` |
+| `leave` | Leave the fleet: release the guest lease, retire the occupant, return claimed messages to `queued` | `[id]` `--session-id <sid>` `--json` |
 | `status` | Agent specs with live process status and member session (requires `spur self serve`) | `--server <url>` `--json` |
 | `doctor [agent]` | Check agent readiness | `--json` `--probe-health` `--force-refresh` |
 | `usage` | Run-once provider usage capture (codexbar) → quota-owned availability refresh; scheduled externally | `--dry-run` `--source <name>` `--json` |
 | `start <spec-id>` | Start a supervised agent process (requires `spur self serve`) | `--server <url>` `--json` |
 | `stop <spec-id>` | Stop a supervised agent process (requires `spur self serve`) | `--server <url>` `--json` |
 
-`list`, `status`, `doctor`, `run`, `wait`, `trace`, `start`, and `stop` accept `--json` plus `--json-envelope`. The hidden
+Every verb except `trace` accepts `--json` plus `--json-envelope`; `trace` is `--json` only. The hidden
 `loop` is a supervisor-internal process surface. **Exit codes:** `0` success, `1` failure, and `2`
 invalid usage; `run` can also propagate the invoked agent's non-zero result.
 
@@ -142,24 +142,27 @@ exits 2 naming the accepted vocabulary. Resolution collapses onto the same ident
 
 ```bash
 spur agent list              # detected coding agents on this machine
-spur agent list --specs      # agent specs under .spur/agents/
+spur agent list --specs      # agent specs: .spur/agents/*.yaml + agent.fleet members
 spur agent list --json       # machine-readable
 ```
 
 Without `--specs`, lists coding agents detected on the host (by binary on `PATH`). With `--specs`,
-lists agent specs (`.spur/agents/*.yaml`) **with live run status merged from the server's
+lists agent specs — hand-authored `.spur/agents/*.yaml` merged with the members declared under
+`agent.fleet.members` (derived in memory, never written to disk; the fleet declaration wins on an
+id clash; stale `fleet:generated` files are ignored) — **with live run status merged from the server's
 supervisor**: each row carries a trailing status column
 (`running` / `stopped` / `errored` / `unknown`), `pid=<n>` where a process exists, and the member
 session (0897): the session mode plus a shortened resume id (`resume id=3f9c2a1d`), or `-` when the
-member has no recorded session. When `spur self serve` is unreachable, the listing falls back to all
+member has no recorded session. `--json` rows carry `source: file` (plus `path`) or `source: fleet`
+(no backing file, so no `path`). When `spur self serve` is unreachable, the listing falls back to all
 `stopped` with a stderr warning. `--server <url>` targets the supervisor API; without it the URL is
 this project's serve — the port in the cwd's project-registry entry (`http://localhost:<port>/api`),
 falling back to `http://localhost:3000/api` only when the project has no live entry (1088 R1).
 
 ```bash
 spur agent list --specs
-# planner	claude	reviewer	claude	plans the work	running pid=4132	resume id=3f9c2a1d
-# worker-1	pi	worker	pi	implements	stopped	one-shot
+# myapp-planner-1	claude	planner	claude	orchestrator	running pid=4132	resume id=3f9c2a1d
+# myapp-coder-1	pi	coder	pi	implements	stopped	one-shot
 ```
 
 ## `status` - live status + member session per spec
@@ -180,7 +183,7 @@ unreachable server reports every spec `stopped` with no session. `--server <url>
 
 ```bash
 spur agent report --state working --seq 1759665600000000000
-spur agent report --state blocked --seq 1759665600000000000 --spec proj-worker-1 --json
+spur agent report --state blocked --seq 1759665600000000000 --spec myapp-coder-1 --json
 ```
 
 | Flag | Description |
@@ -215,7 +218,7 @@ concrete id only (role/executor selectors count declared members, so a guest is
 claim table (same TTL/heartbeat semantics as the write slot — R5) and writes
 `.spur/run/guests/<id>.json` so a host Stop hook can recognize its own session without a CLI call.
 `leave`, or lease expiry in the reconciler pass, releases the lease, marks the occupant exited,
-returns its claimed messages to `pending` and removes the record.
+returns its claimed messages to `queued` and removes the record.
 
 | Flag | Description |
 | --- | --- |
@@ -296,8 +299,8 @@ buffer is only a live view.
 ## `start` - start a supervised process
 
 ```bash
-spur agent start worker-1
-spur agent start worker-1 --json
+spur agent start myapp-coder-1
+spur agent start myapp-coder-1 --json
 ```
 
 Posts to the `spur self serve` supervisor API
@@ -310,8 +313,8 @@ when the server is unreachable or the start fails.
 ## `stop` - stop a supervised process
 
 ```bash
-spur agent stop worker-1
-spur agent stop worker-1 --json
+spur agent stop myapp-coder-1
+spur agent stop myapp-coder-1 --json
 ```
 
 Posts to the supervisor API
@@ -388,7 +391,9 @@ one never re-sends settled work; only never-started deliveries release and redel
   **[dispatch-surface rule](../../parallel-execution/references/dispatch-surface.md)**, not this
   reference. This reference documents the verbs; that rule decides which surface carries a dispatch.
 - **Not the fleet orchestrator.** The `spur self serve` supervisor drives the lifecycle: `spur agent
-  start` / `stop` manage supervised processes and `agent list --specs` reports live state.
+  start` / `stop` manage supervised processes and `agent list --specs` reports live state. Dispatch
+  policy (`agent.fleet.strategy` `rest|gtd`, the `orchestrator` member, `--agent fleet` routing)
+  lives in project config and the workflow executor, not in these verbs.
 
 ## See also
 

package/plugins/sp/skills/spur-cli/references/decision.md

@@ -1,6 +1,6 @@
 ---
 name: spur-cli-decision
-description: "spur-cli noun reference: operate `spur decision` as the read/serve surface over the decision catalog - list registered decisions, show one served contract (parameters, criteria vocabulary, effective maker), run a decision to a served outcome (never writes a workflow resultFile), and status the catalog layers. Backed by @gobing-ai/ts-ai-decision 0.5.16 hub; offline by default via the built-in `typesafe` maker. Introduced by task 1093."
+description: "spur-cli noun reference: operate `spur decision` as the read/serve surface over the decision catalog - list registered decisions, show one served contract (parameters, criteria vocabulary, effective maker), run a decision to a served outcome (never writes a workflow resultFile), and status the catalog layers. Backed by @gobing-ai/ts-ai-decision 0.5.22 hub; offline by default via the built-in `typesafe` maker. Introduced by task 1093."
 see_also:
   - spur-cli
 ---
@@ -22,15 +22,15 @@ Decisions resolve first-wins across three layers:
 | Layer | Root | Notes |
 | ----- | ---- | ----- |
 | `project` | `<cwd>/.spur/decisions/*.yaml` | Highest precedence |
-| `registered` | programmatic catalog registrations | Agents register in-process |
+| `registered` | folders listed in config `decisions.paths` | Operator-added catalogs |
 | `shared` | `decisions/` under the bundled config root | Shipped catalogs (`config/decisions/` in-repo) |
 
 The bundled shared catalog ships `task-triage`, `failure-class`, and `review-failure-class` (all
 `choice` type, param `wbs`). Duplicate ids across layers keep the higher layer; duplicates inside
 one file are a load error.
 
-**Config keys** (under `decisions:` in `config.global.yaml` or project config):
-`paths` (extra catalog folders joined to the registered layer), `maker` (default DecisionMaker
+**Config keys** (under `decisions:` in the global `~/.config/spur/config.yaml` or project `.spur/config.yaml`):
+`paths` (extra catalog folders forming the `registered` layer), `maker` (default DecisionMaker
 for every decision point), `makers` (per-decision-id overrides). An unregistered maker name is a
 config error, never a silent fallback (design §3.6).
 
@@ -47,8 +47,9 @@ All verbs support `--json` (bare payload) and `--json-envelope` (`{ok, data|erro
 ADR-091). Failure output for `--json` commands uses the canonical error envelope only under
 `--json-envelope`; plain `--json` keeps the human message on stderr.
 
-**Exit codes:** `status` exits 1 on catalog load errors; `show` exits 1 on unknown id; `list` always
-exits 0 (design §3.4 — load errors surface via `status`).
+**Exit codes:** `status` exits 1 on any catalog load error or maker-config error; `show` exits 1 on unknown id; `list` exits 0
+(design §3.4 — load errors surface via `status`) except for an invalid `--layer` value (exit 1).
+Error envelopes use `NOT_FOUND` for an unknown id and `VALIDATION_FAILED` for every other caller mistake.
 
 **Exit contract for `run` (design §3.4):** any backend-observed outcome — low confidence, model
 error surfaced as fallback, declined — is still a **successful serve** (exit 0, envelope carries
@@ -78,6 +79,13 @@ exist there). The final `catalog-default` maker is the hub built-in `typesafe`
 without a configured backend still produce deterministic closed-vocabulary outcomes, which is why
 `run` is usable in tests and scripts with no model access.
 
+**Available makers:** the three upstream built-ins (`typesafe`, `fm-local`, `laya-local`) plus
+Spur's hosted `clef` (Cloudflare Workers AI via `@gobing-ai/ts-decision-clef`). `clef` registers
+only when both `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_AUTH_TOKEN` are set in the environment;
+without them it is absent from `registeredMakers`, so naming it in config or `--maker` is a config
+error, never a silent fallback. Its model defaults to `clef-flash` (a catalog `model` selects
+`clef`).
+
 ## Examples
 
 ```bash
@@ -86,12 +94,12 @@ spur decision show task-triage                      # inspect contract before se
 spur decision run task-triage --param wbs=1093 --json
 spur decision run failure-class --param wbs=1093 \
     --evidence .spur/run/<runId>-test-output.txt    # redacted evidence -> instructions
-spur decision status --json | jq '.data.errors'     # audit catalog health
+spur decision status --json | jq '.loadErrors'      # audit catalog health
 ```
 
 ## References
 
 - Design: `docs/design/decision-catalog.md` (§2 catalog authoring, §3.4 CLI surface)
-- Hub: `@gobing-ai/ts-ai-decision` 0.5.16 (`DecisionService`, catalog schema, maker registry)
+- Hub: `@gobing-ai/ts-ai-decision` 0.5.22 (`DecisionService`, catalog schema, maker registry)
 - App service: `packages/app/src/decision/decision-service.ts`
 - Shipped catalogs: `config/decisions/*.yaml`

package/plugins/sp/skills/spur-cli/references/message.md

@@ -31,10 +31,10 @@ All verbs accept `--json` and `--json-envelope`. `watch` applies the envelope pe
 
 ```bash
 spur message send "Please review PR 42" --to reviewer
-spur message send "Task 0040 is blocked" --to worker-1 --from operator
+spur message send "Task 0040 is blocked" --to myapp-coder-1 --from operator
 spur message send "Done" --to planner --json
 spur message send "Review 0042" --to reviewer --wait --until invoke-exit --timeout 30000
-spur message send "Done" --to manager --request-key 0695-report-42      # retry-safe: same key replays the original receipt
+spur message send "Done" --to myapp-planner-1 --request-key 0695-report-42      # retry-safe: same key replays the original receipt
 spur message send "Start the pass" --role reviewer          # resolves to exactly one instance
 ```
 
@@ -66,9 +66,9 @@ wait; enqueue is **not** rolled back if the wait later fails.
 ## `inbox` - list addressed messages
 
 ```bash
-spur message inbox --agent worker-1
-spur message inbox --agent worker-1 --json
-spur message inbox --agent worker-1 --unresolved --json
+spur message inbox --agent myapp-coder-1
+spur message inbox --agent myapp-coder-1 --json
+spur message inbox --agent myapp-coder-1 --unresolved --json
 ```
 
 Lists messages addressed to `--agent <id>`, oldest first. The body is truncated in plain-text output;
@@ -107,8 +107,8 @@ Threads a reply to a specific message id. The reply is addressable to the origin
 ## `watch` - follow an inbox live
 
 ```bash
-spur message watch --agent worker-1
-spur message watch --agent worker-1 --interval 1000 --json
+spur message watch --agent myapp-coder-1
+spur message watch --agent myapp-coder-1 --interval 1000 --json
 ```
 
 Polls the inbox and surfaces each **new** message exactly once as it arrives. `Ctrl-C` to exit. With

package/plugins/sp/skills/spur-cli/references/projects.md

@@ -22,7 +22,7 @@ shapes live in `apps/cli/src/commands/projects.ts`.
 | `clean` | Purge missing project folders and terminate lingering processes (alias: `refresh`) | `--no-terminate-processes` `--json` |
 | `list` | List entries with live running status | `--json` `--fleet` |
 | `start <target>` | Start or reuse a detached project server | `--port <n>` `--json` |
-| `stop <target>` | Best-effort stop the listener and clear its recorded port | `--json` |
+| `stop <target>` | Ownership-verified stop of the listener and clear its recorded port | `--json` |
 
 Every verb also advertises `--json-envelope`; use the facade's machine-output contract. Success is
 exit `0`; validation, registry, spawn, health, or lookup failure is exit `1`.
@@ -36,8 +36,8 @@ exit `0`; validation, registry, spawn, health, or lookup failure is exit `1`.
 - `add` requires an existing path, resolves a relative path from the current working directory, and
   defaults the display name to its basename. It upserts; it does not start a server. The current
   source does not enforce a `.spur/` marker or directory type.
-- `list` automatically heals tilde paths, verifies project directories exist on disk (purging missing entries and terminating lingering processes), and heals stale entries to `port: 0` before reporting `running`.
-- `clean` (alias `refresh`) explicitly purges non-existent project directories from `projects.json`, probes live ports for removed entries, and cleanly terminates orphaned listening processes (SIGTERM with bounded wait and SIGKILL escalation). Supports `--no-terminate-processes` to skip process kills.
+- `list` automatically heals tilde paths, verifies project directories exist on disk (purging missing entries and terminating only ownership-verified lingering processes), and heals stale entries to `port: 0` before reporting `running`.
+- `clean` (alias `refresh`) explicitly purges non-existent project directories from `projects.json`, probes live ports for removed entries, and terminates orphaned listeners only after ownership verification (SIGTERM with bounded wait and SIGKILL escalation, each signal gated on `service:spur` identity plus exact project path and a stable PID; foreign or unverified listeners are never signaled). Supports `--no-terminate-processes` to skip process kills.
 - `list --fleet` (0835/0858) additionally resolves each project's `agent.fleet` section from that
   project's `.spur/config.yaml` under the existing verb (no new noun). Per project it prints one line
   per member: instance id (the spec id / mailbox identity), `role`, resolved `executor`,
@@ -76,8 +76,10 @@ port is returned idempotently; otherwise the service allocates a port (3000–39
 set), spawns `spur serve --host 127.0.0.1 --no-open` detached in the project root, waits for the port,
 then persists it.
 
-`stop` finds processes bound to the recorded port, sends `SIGTERM` best-effort while excluding the
-CLI and its parent, and clears the registry port. It is not a persistent supervisor contract.
+`stop` signals only a listener that proves `service:spur` identity plus the exact registered project
+path with a stable rediscovered PID; it refuses foreign or unverified listeners with exit 1 and
+preserves the port, treats an absent listener as idempotent success, and excludes the CLI and its
+parent. It is not a persistent supervisor contract.
 `remove` only removes the registry entry; stop a running project first when process cleanup matters.
 
 Raw JSON success payloads are verb-specific (`project`, `projects`, `removed`, `stopped`, or start

package/plugins/sp/skills/spur-cli/references/tasks/verbs.md

@@ -258,14 +258,28 @@ the active tasks folder (or `--folder`).
 
 ## `migrate-anchors`
 
-Qualify ambiguous in-repo evidence anchors to repo-relative paths across the task corpus. Run
+Qualify in-repo evidence anchors to repo-relative paths across the task corpus. Run
 `--dry-run` first: unambiguous matches are reported in `qualified`, multiple matches in `ambiguous`
 without rewriting, and schema-incompatible files in `skipped`. The write path uses the planning
 service rather than raw file edits.
 
+**`done_reason` scratch pointers are retargeted** (task 1140, ADR-131): a `.spur/run/<wbs>-verdict.json`
+or `.spur/run/<wbs>/verdict.json` substring becomes `.spur/memory/evidence/<wbs>-verdict.json` when
+that copy exists, else `tracked Testing section (scratch verdict not retained)` when Testing is
+non-empty; otherwise the value is left unchanged and reported in `doneReasonUnresolved`. Each
+`doneReasons` row carries `kind` (`absolute-path` | `durable-evidence` | `tracked-testing`). This is
+the repair for the `no-scratch-verdict-pointer` rule.
+
+**`--wbs <wbs>` scopes the pass to one task file** (task 1109 R1) — the wbs is resolved through the
+task locator and exactly that file is scanned, so the pipeline's implement stage can auto-repair a
+task's unique basename anchors without the corpus-wide pass rewriting unrelated files (the unscoped
+apply rewrote 119 on 2026-10-07). An unknown wbs exits `1` with an actionable message and writes
+nothing. Ambiguous basenames are still reported and left untouched in scoped mode.
+
 ```bash
 spur task migrate-anchors --dry-run --json
 spur task migrate-anchors --json
+spur task migrate-anchors --wbs 1109 --json     # one task file only
 ```
 
 ## `resolve <file-path>`
@@ -358,7 +372,9 @@ and `prefixId` normalizes `AC<n>` so the box flips. A bare `AC-<i>` also does bo
 resolves it through the feature's scenario order to the AC line aliasing scenario *i*
 (`AC<k> — [R<n> — ]<scenario title>`) and flips that box — never the same-numbered `AC<i>`; with no
 aliasing line it flips nothing. A bare `AC<n>` credits no scenario; a title carrying the scenario's
-`R<n>` label matches neither.
+`R<n>` label matches neither. When the task's AC section is a Gherkin fence (`Scenario: AC1 — …`
+rows), there is no checklist label: cite each row by its exact scenario title — a bare `AC<i>`
+matches nothing and the verdict is rejected.
 
 **Evidence rule (behavior-bearing AC):** an AC row with `status: MET` on a behavior-bearing id
 (no `[advisory]`/`[non-core]`/`[non-behavior]`/`[docs-only]` marker) MUST carry `test` or
@@ -436,7 +452,7 @@ spur task sections <wbs> <init|add|list> [name] [--folder] [--json]
 spur task list     [--status <s>] [--phase <p>] [--parent <wbs>] [--feature <id>] [--folder] [--json]
 spur task refresh  [--folder] [--json]
 spur task migrate  [--dry-run] [--folder] [--json]
-spur task migrate-anchors [--dry-run] [--json]
+spur task migrate-anchors [--wbs <wbs>] [--dry-run] [--json]
 spur task refresh-roster <wbs> [--folder] [--json]
 spur task batch-create --file <path> [--skip-ready | --agent <selector>] [--folder] [--json]
 spur task record   <wbs> [--verdict-file <p>] [--solution-from-diff] [--transition <s>] [--folder] [--json]

package/plugins/sp/skills/spur-cli/references/tasks.md

@@ -23,7 +23,7 @@ does what*, this skill.
 Start from the WBS, not the corpus layout:
 
 ```bash
-spur task show <wbs> --json  # metadata + full content + filePath
+spur task show <wbs> --json  # {wbs, name, status, frontmatter, content, filePath}; priority etc. under .frontmatter
 spur task get  <wbs> --json  # alias of `show` — same output, no separate code path
 spur task path <wbs> --json  # absolute path only
 ```
@@ -38,15 +38,15 @@ re-reading or re-tokenizing the task.
 
 | Verb | Purpose | Key flags |
 | ---- | ------- | --------- |
-| `create <title>` | Allocate a new task (race-safe WBS) | `--feature <id>` `--parent <wbs>` `--template <variant>` `--dedupe-within <s>` `--allow-duplicate-name` `--skip-ready` `--agent <selector>` `--folder` `--json` |
+| `create <title>` | Allocate a new task (race-safe WBS) | `--feature <id>` `--no-reopen` `--parent <wbs>` `--template <variant>` `--dedupe-within <s>` `--allow-duplicate-name` `--skip-ready` `--agent <selector>` `--folder` `--json` |
 | `show <wbs>` | Print one task's frontmatter + body | `--folder` `--json` |
-| `update <wbs> [status]` | Lifecycle transition, section replace, **or** frontmatter set | `--section <name> --from-file <path>` `--assignee <spec-id>` (exclusive with `--section`) `--feature <id>` `--priority <p>` `--ac-numbering task-local` `--ac-altitude <a>` `--estimate-hours <n>` `--no-lifecycle` `--force-done` `--reason <text>` `--provenance-bypass` `--verdict-dir <path>` `--folder` `--json` |
+| `update <wbs> [status]` | Lifecycle transition, section replace, **or** frontmatter set | `--section <name> --from-file <path>` `--assignee <spec-id>` (exclusive with `--section`) `--feature <id>` `--no-reopen` `--priority <p>` `--ac-numbering task-local` `--ac-altitude <a>` `--estimate-hours <n>` `--no-lifecycle` `--force-done` `--reason <text>` `--provenance-bypass` `--verdict-dir <path>` `--folder` `--json` |
 | `deps <wbs> <op> [values...]` | Mutate `dependencies[]` frontmatter array (ops: `set`, `add`, `remove`, `clear`) | `--folder` `--json` |
 | `sections <wbs> <op> [name]` | Initialize, add, or list canonical task sections (ops: `init`, `add`, `list`) | `--folder` `--json` |
 | `list` | List tasks, filtered | `--status <s>` `--phase <p>` `--parent <wbs>` `--feature <id>` `--folder` `--json` |
 | `refresh` | Re-scan the corpus and report counts (**`kanban.md` retired** — web Task Kanban is SSOT) | `--folder` `--json` |
 | `migrate` | One-time A17 corpus normalization pass | `--dry-run` `--folder` `--json` |
-| `migrate-anchors` | Qualify in-repo evidence anchors to repo-relative paths (0583 R1–R3) | `--dry-run` `--json` |
+| `migrate-anchors` | Qualify in-repo evidence anchors to repo-relative paths (0583 R1–R3); `--wbs` scopes to one task file (1109 R1); retargets scratch `done_reason` verdict pointers (1140) | `--wbs` `--dry-run` `--json` |
 | `refresh-roster <wbs>` | Regenerate a parent task's sub-task roster block in `## Plan` | `--folder` `--json` |
 | `batch-create` | Create many tasks from a validated JSON array | `--file <path>` `--skip-ready` `--agent <selector>` `--folder` `--json` |
 | `record <wbs>` | Write `Testing` from a verify verdict (deterministic); bare-`## Review` fallback only; optional Solution + transition | `--verdict-file <path>` `--solution-from-diff` `--transition <status>` `--folder` `--json` |
@@ -67,8 +67,11 @@ tasks folder. **Exit codes:** `0` success, `1` error, `2` invalid usage.
 spur task create "Add email validation" --feature H2 --parent 0040
 ```
 
-- **`--feature <id>`** wires traceability: it derives the task's `Background` from the feature's
-  `Goal` and records `feature_id` in frontmatter (L4 traceability reads this edge).
+- **`--feature <id>`** wires traceability: it derives the task's `Background` from the feature's `Goal`
+  and records `feature_id` in frontmatter (L4 traceability reads this edge). The parent feature's
+  status is checked before any write: `done`/`cancelled` is rejected with the status plus up to three
+  `active` sibling ids, and `verifying` is reopened to `active` through the guarded feature transition
+  (`featureReopened` in `--json`); `--no-reopen` suppresses only that reopen.
 - **`--parent <wbs>`** groups the new task under a parent WBS for sub-task decomposition.
 - **`--template <variant>`** selects the section-matrix variant that shapes the new file's sections:
   `standard·feature-impl·issue·review·meta·brainstorm`. The default is **`feature-impl` when
@@ -273,7 +276,7 @@ corpus, or with a WBS for one task:
 
 ```bash
 spur task check --json              # whole corpus
-spur task check 0040 --json         # one task
+spur task check 0040 --json         # one task; output is an array — read .[0].pass
 spur task check --strict --json     # elevate ALL warnings to failures
 spur task check 0040 --as done        # evaluate as the done row (lifecycle target, F92 R2)
 spur task check 0040 --strict-core    # compatibility alias; not the done gate (use --as done)

package/plugins/sp/skills/spur-cli/references/workflows/authoring-workflows.md

@@ -134,6 +134,13 @@ runner (see [validation-and-extension.md](validation-and-extension.md)).
 | Guard | `always` | Unconditional pass — the default edge condition / fallback transition |
 | Guard | `action-ok` | Pass iff the prior action on this state/node succeeded — useful for a single hard shell check |
 
+Spur's host additionally registers (`registerSpurBuiltins`, `packages/app/src/workflow/builtins.ts`):
+
+| Kind | Capability |
+| ---- | ---------- |
+| Action | `agent.run` (model call via `spur agent run`; `executor: 'fleet'` dispatches into the agent fleet), `decide` (inline `id`/`method`/`question`/`choices`/`default`/`evidence` → outcome written to `resultFile`; catalog-id references are pending task 1094 — use `spur decision run` for catalog decisions), `command.gate`, `rule.check`, `doctor.probe`, `response.validate`, `proof.fingerprint`, `run.artifact`, `file.exists`, `file.read`, `file.read.into-var`, `http.request`, `hitl.confirm`, `hitl.select`, `hitl.input`, `shell` (streaming) |
+| Guard | `shell` (env-aware), `contract-violation` |
+
 Order matters for both guards and conditions: **the first that passes wins.** Put the discriminating
 guard before the unconditional fallback (`always` / no-guard edge). For multi-condition gates (doctor
 + task check, quality gate + attempt cap), prefer a **soft probe** shell that writes PASS|FAIL and

package/plugins/sp/skills/spur-cli/references/workflows.md

@@ -112,7 +112,7 @@ The skill's logic divides by **whether the LLM adds value**:
 | `run` | `spur workflow run` (CLI) | `<file> [--run-id <id>] [--vars <json>] [--dry-run] [--async] [--no-plan] [--quiet/--silent/--verbose] [--detail <level>] [--trace-file] [--no-log] [--steer]` | Terminal state reached (sync) or run started (async); trace readable |
 | `continue` | `spur workflow continue` (CLI) | `[run-id] [--yes] [--answer <yes\|no\|cancel>] [--answer-text <text>] [--async] [--no-log]` | Resume a paused or interrupted run (omit id -> most recent resumable); `--answer` injects a confirm/select gate answer and `--answer-text` answers an input gate with free text (H1 R27), both before guard re-evaluation; one of them is required headless (0901 R3) and each is validated against the pending gate kind; `--async` detaches the resume (0901 R4) |
 | `cancel` | `spur workflow cancel` (CLI) | `<run-id>` | Single non-terminal run marked failed (SIGTERM async worker when live) |
-| `clean` | `spur workflow clean` (CLI) | `[--older-than <min>] [--force] [--logs] [--dry-run]` | Bulk-finalize stale `running`/`pending` runs as failed **and** reclaim retained run logs older than `workflow.logRetentionDays` (30d default) |
+| `clean` | `spur workflow clean` (CLI) | `[--older-than <min>] [--force] [--logs] [--dry-run]` | Bulk-finalize stale `running`/`pending` runs as failed **and** reclaim retained run logs older than `workflows.logRetentionDays` (30d default) |
 | `list` | `spur workflow list` (CLI) | — | Available workflow **YAML definition files** (not run records) |
 | `trace` | `spur workflow trace` (CLI) | `[run-id] [--workflow <n>] [--status <s>] [--since <iso>] [--last <n>] [--follow] [--poll <ms>] [--output] [--timeout <ms>]` | Run history list or per-run timeline |
 | `progress` | `spur workflow progress` (CLI) | `<run-id>` | The `projectWorkflowProgress` projection for that run — current state, per-action attempts, candidate next transitions, diagnostics. Read-only; the verb renders, `packages/app` derives. Unknown run id exits 1 with `Run <id> not found.` |
@@ -273,6 +273,11 @@ spur workflow progress <run-id> [--json]
 `spur workflow show <file>` renders the declared graph as Mermaid. `--format todo` instead emits a
 declared-step checklist; `--json` serializes the selected projection. This verb intentionally does
 not advertise `--json-envelope` because its JSON projection is a kept-raw document surface.
+Task 1104: for annotated definitions the todo `--json` payload also carries `plan` — the two-layer
+A-Z/1-9 phased plan derived from each state's `display` (`phase`/`phaseTitle`/`title`/`show`);
+`null` when no state declares `display`. `workflow validate` enforces the phase table on annotated
+definitions (every non-terminal state phased, terminals bare, ≤25 phases, ≤9 states per phase,
+consistent `phaseTitle`).
 
 | Flag (on `run`) | Effect |
 | --------------- | ------ |
@@ -361,7 +366,7 @@ redirecting `agent.run` stages (ADR-047).
 - **Stale-run finalization** (existing): bulk-finalizes orphaned `running`/`pending` runs as `failed`.
   `--older-than <minutes>` (default 30) and `--force` (all non-terminal regardless of age) apply here only.
 - **Run-log reclamation** (0429): removes expired `.log` files from `.spur/memory/runs/`
-  and legacy `.spur/run/`, using `workflow.logRetentionDays` (default 30 days). Non-terminal
+  and legacy `.spur/run/`, using `workflows.logRetentionDays` (default 30 days). Non-terminal
   runs, including paused/interrupted runs, are protected; ownership lookup failures preserve logs.
   The two-file record (`.md` + `.state.json`) and partial handoffs are retained.
 - **Checkpoint reclamation**: removes expired terminal checkpoints only when confinement,

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

@@ -49,7 +49,7 @@ its own output and never runs a recurring loop — evaluation is the doctor's jo
 | feature | Apply accepted rows through `spur feature update --section --from-file`; keep acceptance criteria in Gherkin | [../spur-cli/references/features.md](../spur-cli/references/features.md) |
 | rule | The trace-driven tuning loop (§ Rule tuning loop) | [../spur-cli/references/rules.md](../spur-cli/references/rules.md) · [fine-tuning](../spur-cli/references/rules/fine-tuning.md) |
 | workflow | Catalog selection, the composition ladder, and the ADR-115 budgets (§ below) | [../spur-cli/references/workflows.md](../spur-cli/references/workflows.md) · [operations](../spur-cli/references/workflows/operations.md) |
-| agent spec | Read through `spur agent list --specs`; specs are materialized from the fleet declaration at serve start | [../spur-cli/references/agent.md](../spur-cli/references/agent.md) |
+| agent spec | Read through `spur agent list --specs`; fleet member specs are derived in memory from `agent.fleet` (never written to `.spur/agents/`) | [../spur-cli/references/agent.md](../spur-cli/references/agent.md) |
 | board module | Declare under `bootstrap.modules`, gated by the serve preflight (§ Board module composition) | [../spur-cli/references/serve.md](../spur-cli/references/serve.md) |
 
 Do not drive the planning→execution lifecycle from here — that is `sp:spur-dev`.

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

@@ -39,11 +39,7 @@ metadata:
 It converts vague intent into shipped work by _orchestrating_, not by doing the work itself: it runs
 the gates (feature-check, batch-create) and the execution pipeline with human-in-the-loop control,
 and **dispatches deep competency skills** for each unit of work — it never inlines them. Every write
-to the corpus goes through a CLI verb that validates before writing — the spine knows _how to drive
-the lifecycle_; the competency skills know _how to do each job_; the CLI knows _what is valid_.
-
-The skill was decomposed **by function** (ADR-028): design, decomposition, implementation, testing,
-and verification each became a standalone competency skill, leaving this spine to orchestrate them.
+to the corpus goes through a CLI verb that validates before writing.
 
 **Ownership (ADR-054).** This spine owns multi-step lifecycle orchestration — intake, gates,
 decomposition, pipeline runs, HITL pauses. CLI noun/verb/flag semantics, including
@@ -104,6 +100,21 @@ run. Resume with `spur workflow continue --answer-text <answer>` — the guard a
 Full procedure: **[references/execution-workflow.md](references/execution-workflow.md)**.
 Host-session procedure: **[references/inline-pipeline-driver.md](references/inline-pipeline-driver.md)**.
 
+## Bootstrap reads
+
+Read this `SKILL.md` plus your mode's files below before the first dispatch; everything else under
+`references/` is on demand, and the per-task delegate `inline-pipeline-driver.md` is read at dispatch
+(budgets: `plugins/sp/tests/bootstrap-budget.test.ts`, task 1128).
+
+- sequential-inline: `references/execution-batch.md`
+- --worktree: `references/execution-batch.md`, `references/execution-worktree-setup.md`
+- --mode parallel: `references/execution-batch.md`, `references/execution-parallel-isolation.md`
+
+`--mode auto` reads as sequential-inline until § 2.4a resolves it.
+
+Byte budgets for these sums live in `plugins/sp/tests/bootstrap-budget.test.ts`
+(`BOOTSTRAP_BUDGETS_BYTES`, task 1128); the test fails the build when a mode's bootstrap grows.
+
 ## Step routing
 
 Each step delegates to a CLI verb and is documented in exactly one reference file. Read the
@@ -201,10 +212,8 @@ path <wbs> --json` only when another tool needs the absolute path. Never search
 
 ## Additional Resources
 
-**Every reference file and its step is listed once, in [Step routing](#step-routing) above — this
-section adds what that table has no room for: per-file content summaries and items with no single
-step (glossary, config companions).** Read Step routing to find "which file for step X"; read below
-for "what's actually in file Y" or for resources that sit outside the step sequence.
+**Every reference file and its step is listed once, in [Step routing](#step-routing) above.** This
+section adds per-file content summaries and items with no single step (glossary, config companions).
 
 - Job transfer: [dump/resume](references/dev-operations.md#11a-job-dump).
 
@@ -212,12 +221,9 @@ for "what's actually in file Y" or for resources that sit outside the step seque
   corpus, gate, verdict, noun/verb, half, HITL, WBS, section-write contract — canonical term +
   Avoid list. Owns term definitions only; `cross-cutting.md` owns the process rules that use them.
 - [references/flag-glossary.md](references/flag-glossary.md) — the shared-flag glossary (one
-  canonical entry per flag used by two or more `/sp:dev-*` commands) and the `--next` chain
-  contract. Moved verbatim from `dev-operations.md` (task 0408) so command files can deep-link
-  flag entries while this spine reads the operation catalog linearly.
+  canonical entry per flag used by two or more `/sp:dev-*` commands) and the `--next` chain contract.
 - [references/gate-checklists.md](references/gate-checklists.md) — checkbox checklists for the
-  five gates (feature-check, batch-create, precheck, review, verify). Each checklist is a
-  `- [ ]` list of prerequisites an agent verifies before entering the gate.
+  five gates (feature-check, batch-create, precheck, review, verify).
 - [references/section-batching.md](references/section-batching.md) — the evidence-section
   **one-writer protocol** (F92 0593 R1/R2): implement owns `Solution`, the review coordinator owns
   `Review`, deterministic `record` owns `Testing`; skills query `spur task sections` /

package/plugins/sp/skills/spur-dev/references/ac-style-guide.md

@@ -88,6 +88,33 @@ DD-06 permissive start: treat only the core tier as must-ship initially; promote
 prove important in a later iteration. (When tiered gating lands in `spur feature check`, these tags
 become the gate input — the CLI stays the validator; this guide stays the convention.)
 
+### Home-node tier (structural, exempt from the orphan sweep)
+
+A **home node** carries one structural or placement scenario that states *where the work lives*
+(e.g. "work on the kk workflow-run ledger has a home node"). No task can cover that statement — it
+describes planning placement, not behaviour — so tag it `@home-node` to remove it from the
+feature-side DD-09 orphan sweep (`L4.uncovered-feature-scenario`):
+
+```gherkin
+@home-node
+Scenario: R1 — Work on the kk workflow run ledger has a home node
+  Given a change that targets the kk workflow run ledger workflow
+  When the change is planned as a feature
+  Then it is feature G7 or a child feature of G7
+```
+
+Rules:
+
+- **Scenario-level tag only.** A `Feature:`-level `@home-node` exempts nothing; the tag is read per
+  scenario.
+- **Exempts the orphan sweep only.** Scenario satisfaction (0340), verdict-row matching, and the
+  known-issues ratchet are unchanged — a tagged scenario a task actually covers is classified
+  exactly as before.
+- **Never a hiding place.** Use it only for a scenario no task can own. A deliberately uncoverable
+  *capability* scenario belongs to `@core`/`@edge` and must stay in the sweep: tagging it
+  `@home-node` hides a real gap. Wording is never the signal.
+- A feature with **no linked task** is still flagged as `L4.orphan-scenarios`, tagged or not.
+
 ## Scenario-title stability
 
 The scenario title is the **identity key** for traceability. When a task references a
@@ -100,9 +127,12 @@ scenario, it matches by title. Rules:
 - **No synonyms in cross-references.** The title in the feature file and the title in the
   task's AC reference must be byte-identical.
 - **Avoid gate vocabulary in titles.** `spur task check` (L4.gate-language) rejects task sections
-  containing `HITL`, `approval`/`approved`, `merged`/`merge event`, `content-gate`, `GATED`, or
-  `capstone` as standalone words; task AC bullets copy scenario titles verbatim, so a title using
-  them fails every child task. Write "pause for an operator answer" instead of "HITL approval".
+  containing `HITL`, `merge event`, `content-gate`, `GATED`, or `capstone` as standalone words;
+  ambiguous words (`approval`, `approved`, `merged`) warn only when the same sentence also carries
+  a gating cue (`until`, `after`, `once`, `before`, `pending`, `blocked`, `wait for`, `requires`)
+  — plain composition prose like "the stages merged back into one step" stays silent. Task AC
+  bullets copy scenario titles verbatim, so a title using the unconditional tokens fails every
+  child task. Write "pause for an operator answer" instead of "HITL approval".
 
 ## Verdict AC ↔ feature scenario linkage
 

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

@@ -245,25 +245,36 @@ stage is required, select the subprocess path (`--agent auto` or `--agent <name>
 
 The workflow-backed dev commands (`dev-run`, `dev-runall`, `dev-refineall`, `dev-verifyall`) share one
 startup order. The order is load-bearing and applies on both the inline driver and the subprocess
-path; skill-only operations (refine/verify batches with no nested workflow) display their owned
+path. Runs that resolve a workflow definition publish the generated plan as their first action
+(1105 R1); skill-only operations (refine/verify batches with no nested workflow) display their owned
 procedure and do not fabricate a workflow YAML.
 
-1. **Publish a compact bootstrap checklist immediately** (host-preparation rows, never copied
-   workflow states): `A, Quick readiness` · `B, Prepare Git` · `C, Publish workflow plan` ·
-   `D, Comprehensive checking`.
-2. **Quick deterministic readiness (R2), before isolation.** Evaluate `quickReadiness`
+1. **Publish the generated plan first (1105 R1), before readiness and isolation.** Resolve the
+   selected workflow through the same resolver execution uses and run `spur workflow show
+   <resolved-file> --no-logo --format todo --json`; the projection reads the definition and executes
+   nothing, so publishing it first is safe. Publish every `.plan` row's `text` verbatim (`A Prepare`,
+   `B Implement`, `B1 … · precheck`) as the visible host list — never hand-write rows or copy state
+   tables into prose. `.plan` is `null` for unannotated workflows: those keep the flat `steps[]`
+   inventory with `columnLabel` labels; the skill-only refine/verify batches keep the bootstrap rows
+   below.
+2. **Quick deterministic readiness (R2) — plan row A1, before isolation.** Evaluate `quickReadiness`
    (`plugins/sp/scripts/batch-preflight.ts`) with the operation, status, filtered-set size, and the
    selected matrix required/present sections + content-policy findings. This is an admission decision
    (runnable / needs-refinement / blocked / skipped / invalid), never an implementation certificate.
-3. **Isolation (R3), only when `--worktree` is valid.** After quick readiness and the required Git
-   safety checks, create/adopt and switch to the execution tree; confirm absolute cwd, branch, base
-   SHA, and ownership. An invalid/empty target, unsupported mode, ambiguous ownership, or stale target
-   stops without creating a tree or discarding work. All subsequent tools, agents, corpus writes, and
-   run artifacts use the confirmed execution tree.
-4. **Publish the workflow inventory (R4), before reading the YAML.** `spur workflow show
-   <resolved-file> --no-logo --format todo --json`; validate with `parseWorkflowInventory` and bind to
-   the run's `__definitionDigest` with `assertInventoryIdentity`. Drift or projection failure stops the
-   run before any comprehensive/model work — never execute with a misleading plan.
+3. **Isolation (R3) — plan row A2, only when `--worktree` is valid.** After quick readiness and the
+   required Git safety checks, create/adopt and switch to the execution tree; confirm absolute cwd,
+   branch, base SHA, and ownership. An invalid/empty target, unsupported mode, ambiguous ownership, or
+   stale target stops without creating a tree or discarding work. All subsequent tools, agents, corpus
+   writes, and run artifacts use the confirmed execution tree.
+4. **Bind the published plan to the run digest (R4) — plan row A3.** Validate the step-1 projection
+   with `parseWorkflowInventory` and bind it to the run's `__definitionDigest` with
+   `assertInventoryIdentity`. Drift or projection failure stops the run before any
+   comprehensive/model work — never execute with a misleading plan.
+
+**Bootstrap rows without a generated plan (1105 R1).** `dev-refineall` and `dev-verifyall` have no
+workflow plan (their phases are map I13 fog), so until phases exist they keep publishing a compact
+host-preparation checklist immediately, never copied workflow states: A Quick readiness, B Prepare
+Git, C Publish workflow plan, D Comprehensive checking.
 5. **Load execution detail and run comprehensive checks (R7).** Only after the plan is visible (and
    after isolation when requested) load the full YAML for the active stage and run the owning
    comprehensive gates at their boundaries. Prefer deterministic checks; invoke semantic model work
@@ -300,6 +311,12 @@ keeps a malformed task out of `testing`/`done`.
 lifecycle-*run* creation because it is already a run and a nested one would orphan. The structural
 gate still runs — `→ testing` and `→ done` invoke `spur task check` regardless of the flag.
 
+**Worktree interaction (1149 R1/R3).** When an interactive `--next` chain runs inside an isolated
+git worktree (`--worktree`), the un-suppressed transitions create a `task-lifecycle` row in the
+worktree DB. When persist-out runs at landing, the terminal row is classified as non-fatal
+bookkeeping (`external-key-conflict-bookkeeping`) so it does not block teardown, and the receiving
+lifecycle row in the invoking tree is automatically reconciled to `done`.
+
 > **Behavior corrected 2026-08-07.** `--no-lifecycle` previously suppressed enforcement as a side
 > effect of suppressing the run record, because the FSM guards live inside the lifecycle workflow.
 > Combined with `--force-done` (which waives the verify **verdict** only) it left nothing: a task
@@ -542,6 +559,24 @@ Do not re-run the full suite per iteration, and do not `spur-check` before you h
 target. **Target:** full `spur-check` runs ≤2 per task (one during iteration, one final) instead of
 4 across a chain.
 
+**Isolation rerun for load-flakes (task 1112 review).** Under concurrent fleet load, subprocess-heavy
+tests can exceed bun's 5s default timeout. Five such timeouts were seen during 1112, and each one
+passed when run alone. A full gate that fails *only* on timeouts in tests outside the change scope
+does not earn another full-gate run:
+
+1. Rerun each timed-out test alone: `(cd <workspace> && bun test <file> --test-name-pattern <test>)`.
+2. **Green alone** → classify it as a load-flake. Cite the gate failure (test, elapsed ms) and the
+   isolated pass receipt in the verify evidence. The original full-gate run stands as the single
+   final gate.
+3. **Red alone**, or a failure that is not a timeout → it is a real failure. Fix it.
+4. Give the test an explicit per-test timeout and a WHY comment (see
+   `plugins/sp/tests/inline-run-close-reason.test.ts:100-102`) as soon as EITHER (a) the same test
+   load-flakes in two separate runs, OR (b) it times out once **outside the change scope** and then
+   passes green alone on three consecutive isolated reruns. Waiting for a second gate run to license
+   the fix cost 21 minutes on 2026-10-08 (task 1128, the 1058 two-tree canary: 5145 ms then 5967 ms
+   against bun's 5000 ms default, green 3/3 alone). Never raise the global timeout, skip the test,
+   or loop full-gate reruns.
+
 ## Auto-Decision Principles
 
 Seven principles governing `--auto` mode. `--auto` sets `profile=auto` in the workflow vars; the