@gobing-ai/spur 0.3.99 → 0.4.1

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

@@ -0,0 +1,98 @@
+---
+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."
+see_also:
+  - spur-cli
+---
+
+# spur decision - decision catalog surface
+
+`spur decision` exposes the **decision catalog** (ADR-117 trace discipline, task 1092) to agents
+and scripts: discover which decisions exist, inspect one's contract, serve one outcome, and audit
+catalog health. It is a thin transport over `DecisionService` (`packages/app`); the decision hub
+lives in `@gobing-ai/ts-ai-decision`.
+
+**Frozen at exactly four verbs** (`list`, `show`, `run`, `status`) by task 1093's design
+(`docs/design/decision-catalog.md` §3.4) — do not invent additional subcommands.
+
+## Catalog layers
+
+Decisions resolve first-wins across three layers:
+
+| Layer | Root | Notes |
+| ----- | ---- | ----- |
+| `project` | `<cwd>/.spur/decisions/*.yaml` | Highest precedence |
+| `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 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).
+
+## Verb map
+
+| Verb | Purpose | Key flags |
+| ---- | ------- | --------- |
+| `list` | Every visible decision: id, type, layer, catalog file, description | `--layer <layer>`, `--json` |
+| `show <id>` | One served contract: type, parameters, criteria, fallback, minConfidence, effective maker + source | `--json` |
+| `run <id>` | Serve one outcome (closed vocabulary; **never writes a resultFile**) | `--param <pairs...>`, `--evidence <files...>`, `--maker <name>`, `--json` |
+| `status` | Layer counts, registered makers, per-decision maker resolution, load errors | `--json` |
+
+All verbs support `--json` (bare payload) and `--json-envelope` (`{ok, data|error}` envelope,
+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 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
+`source`/`confidence` so callers can see why). Exit 1 is reserved for caller mistakes caught
+**before** the backend: unknown id, unknown parameter, missing required parameter, type-invalid
+parameter, unregistered `--maker`, unreadable evidence file.
+
+## Parameters and evidence
+
+`--param k=v` is repeatable and validated against the decision's declared parameters: values for
+`number`/`boolean`/`json` params are parsed accordingly (`json` accepts inline JSON objects);
+string/enum params pass through verbatim. A parameter with no `default` is **required** (hub
+loader derives `required: !hasDefault`). Undeclared keys exit 1.
+
+`--evidence <file>` is repeatable; each file is read, **redacted and bounded to
+`DECIDE_EVIDENCE_MAX_CHARS` (2000 chars)** via the same `redactAndBound` used by workflow
+agent execution. Evidence rides the hub's implicit `instructions` input parameter — it reaches the
+maker through the rendered question, never as a raw input key (the hub rejects undeclared input
+keys). An unreadable evidence file exits 1 before any backend call.
+
+## Effective maker resolution
+
+Makers resolve `flag → config-decision → config-default → catalog-decision → catalog-default`;
+`decision show` reports the effective maker as `{name, source}` with that source precedence
+(operator config outranks the shipped catalog because only the machine owner knows which backends
+exist there). The final `catalog-default` maker is the hub built-in `typesafe` — decisions served
+without a configured backend still produce deterministic closed-vocabulary outcomes, which is why
+`run` is usable in tests and scripts with no model access.
+
+## Examples
+
+```bash
+spur decision list --json | jq -r '.[].id'
+spur decision show task-triage                      # inspect contract before serving
+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 '.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)
+- 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/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]
@@ -448,3 +464,25 @@ spur task path     <wbs> [--folder] [--json]
 spur task run-link <wbs> [--source <src>] [--run-id <id>] [--json]
 spur task scaffold-tests <wbs> [--file <path>] [--folder] [--json]
 ```
+
+**No `delete` verb — and that is the surface's shape, not an oversight.** The corpus is
+append-only history: a task that is no longer wanted is a *decision*, and the lifecycle already owns
+it. Use
+
+```
+spur task update <wbs> cancelled [--json]      # the in-band terminal; the file stays as the record
+```
+
+Removing the file entirely is reserved for a task that should never have existed (a duplicate WBS, a
+mis-scaffolded capture) — a **corpus repair**, not a lifecycle move. Do it as a tracked deletion so
+the removal itself is auditable:
+
+```
+git rm docs/tasks<N>/<wbs>_<slug>.md
+git commit -m "chore(corpus): drop <wbs> — <why it never existed>"
+```
+
+Check for inbound references before deleting (`grep -rn "<wbs>" docs/ config/ plugins/`, plus any
+`dependencies[]` edge via `spur task list --json`). The `deps remove` verb clears an edge. A deleted
+WBS must not stay referenced: a dangling `dependencies[]` entry is a broken traceability edge, not a
+harmless leftover.

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

@@ -1,6 +1,6 @@
 ---
 name: spur-composer
-description: "Select, compose and tune spur artifacts — tasks, features, rules, workflows and agent specs. Owns workflow catalog selection, the ephemeral→project→shared ladder, the ADR-115 budgets, trace-driven rule tuning, and applying accepted sp:spur-doctor proposals. Triggers: compose a workflow, tune a rule, apply doctor proposals."
+description: "Select, compose and tune spur artifacts — tasks, features, rules, workflows, agent specs and project Board modules. Owns workflow catalog selection, the ephemeral→project→shared ladder, ADR-115 budgets, trace-driven rule tuning and applying accepted sp:spur-doctor proposals. Triggers: compose a workflow, tune a rule, add a Board module."
 license: Apache-2.0
 version: 1.0.0
 metadata:
@@ -49,7 +49,8 @@ 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`.
 
@@ -106,6 +107,31 @@ budgets:
 A new model step in a shared workflow raises its `pipeline-budgets` `modelQueries`; that needs a
 recorded decision before the shared step.
 
+## Board module composition
+
+A project adds its own Spur Board modules (ADR-128) by declaration, never by editing the installed
+package. The contract — the `react`/`iframe` union, the `@gobing-ai/spur/board` type, the Vite
+externals and the frame/trust limits — is owned by
+[downstream Board modules §6](../../../../docs/design/downstream-board-modules.md#6-authoring-guide);
+the user walkthrough is
+[docs/help/how_to_customize_project_modules.md](../../../../docs/help/how_to_customize_project_modules.md).
+Link them, never restate them.
+
+| Step | Action |
+| --- | --- |
+| select | A built-in module or an existing declaration already covers the need → no new module. An app that already runs and permits framing → `type: iframe`. Otherwise → `type: react`. |
+| compose | Add one declaration to the project `.spur/config.yaml` `bootstrap.modules` list. Stage it with `enabled: false` first: it is fully validated (id shape, duplicates, host/retired collisions) but loads no assets. |
+| build | `react` only: the downstream project builds its own ESM entry plus CSS into the declared `directory`, externalizing exactly the `imports` keys of the installed `web/board-runtime.json`. Building the module is the project's code work, not composer's. |
+| gate | Restart `spur self serve`; the preflight fails startup on any declaration, asset or runtime-version error. Confirm the module in `GET /api/board/modules` and open `/board/modules/<id>`. `spur self serve --json` is a dry port probe and does **not** run this preflight. |
+| enable | Flip to `enabled: true`, restart and reload. There is no hot reload. |
+
+- The module is project-owned: it never climbs a shared layer, and it needs no `build:bundle`.
+- Declare only trusted code — importing a `react` entry evaluates it. Spur never starts or proxies an
+  `iframe` app, and a frame the child refuses stays blank by design.
+- Changing a built-in module is internal Board work in the spur repository
+  ([docs/help/how_to_add_a_new_ui_module.md](../../../../docs/help/how_to_add_a_new_ui_module.md)),
+  not a downstream declaration.
+
 ## Rule tuning loop
 
 Start from trace evidence, never from a guess:

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,19 @@ 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`
+
+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 +210,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 +219,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

@@ -100,9 +100,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