@gobing-ai/spur 0.3.91 → 0.3.93

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

@@ -92,9 +92,15 @@ pick task (spur task list --json)
 The pipeline (`kind: state-machine`) runs the work loop:
 
 ```
-precheck → implement → test → review → approve(HITL) → verify → record → done
+precheck → implement[→escalate(HITL)] → test → review → approve(HITL) → verify → record → done
 ```
 
+**Escalation contract (0933).** The implement agent may pause on an operator question: it writes
+`.spur/run/<wbs>-question.md` and exits 0; the `escalate` hop surfaces it via HITL and pauses the
+run. Resume with `spur workflow continue --answer-text <answer>` — the guard appends the Q/A to
+`.spur/run/<wbs>-escalation.md` and re-enters implement (transcript via `--escalation-file`).
+`maxEscalations` (default 2) bounds the loop; exhausted or empty answer → `failed`. Implement only.
+
 Full procedure: **[references/execution-workflow.md](references/execution-workflow.md)**.
 Host-session procedure: **[references/inline-pipeline-driver.md](references/inline-pipeline-driver.md)**.
 
@@ -110,7 +116,7 @@ reference for the half you're operating; do not duplicate its content here.
 | Feature check gate         | planning  | `spur feature check`                                                                      | [planning-workflow.md](references/planning-workflow.md)                                                                                 |
 | Decomposition (dispatch)   | planning  | `task-batch.schema.json`                                                                  | `sp:spec-decomposition` competency — the spine dispatches, does not inline                                                              |
 | Batch-create gate          | planning  | `spur task batch-create`                                                                  | [planning-workflow.md](references/planning-workflow.md)                                                                                 |
-| Design doc                 | planning  | — (prompt work; §4.5/T9)                                                                  | [planning-workflow.md](references/planning-workflow.md)                                                                                 |
+| Design doc | planning | — (§4.5/T9) | [document-authoring.md](references/document-authoring.md) |
 | Refine                     | planning  | `spur task update --section`                                                              | [planning-workflow.md](references/planning-workflow.md)                                                                                 |
 | Batch refine               | planning  | `sp:dev-refineall` → per-task `refine`                                                    | [dev-operations.md](references/dev-operations.md) § refineall · [planning-workflow.md](references/planning-workflow.md)                 |
 | Task selection             | execution | `spur task list`                                                                          | [execution-workflow.md](references/execution-workflow.md)                                                                               |
@@ -162,9 +168,10 @@ CLI does.
 - Before accepting a child/watcher result, compare its run ID with the dispatched run ID and check
   current trace state through Spur. If using a run log as evidence, require its mtime to be at least
   the dispatch time. A mismatch or stale timestamp is not completion evidence. Do not scrape terminals.
-  Bound each watch invocation to 10 minutes or 20 polls, whichever comes first; persist the last
-  confirmed identity/state and report a checkpoint before continuing. A watcher timeout does not
-  cancel the owned run or authorize launching a replacement.
+  Bound each watch invocation to `spur workflow trace <run-id> --follow --timeout 600000` — one
+  bounded call, no hand-rolled poll loop; a timeout prints one checkpoint line and exits 1 while the
+  run continues, so persist the last confirmed identity/state and report the checkpoint before
+  continuing. A watcher timeout does not cancel the owned run or authorize launching a replacement.
 - Mark superseded scratch with `SUPERSEDED` and a pointer to the authoritative task Design. Never
   let a scratch instruction override the live task, even when its old run is still readable.
 - Checker-policy changes require one explicit unsuppressed audit (T10); ordinary corpus commit
@@ -239,6 +246,7 @@ for "what's actually in file Y" or for resources that sit outside the step seque
 - `idea-pipeline.yaml` — the front-half state machine (absorbed the retired
   planning-pipeline in D5-K; `/sp:dev-plan` routes here, ADR-072).
 - `templates/bdd/gherkin.md` — the BDD scenario template.
+- `templates/plan.md` and `templates/design.md` — plan and design starting points.
 
 ## Platform Notes
 

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
@@ -512,7 +520,10 @@ iterating one task).
 
 **The rule.** When a test fails and you are iterating to green:
 
-1. Run the narrow target first: `bun test <file> --test-name-pattern <test>`.
+1. Run the narrow target first: `bun test <file> --test-name-pattern <test>`. Workspace tests need
+   the workspace `bunfig.toml` preload — invoke them as a subshell `(cd <workspace> && bun test …)`
+   or with absolute paths, because the shell's cwd persists between calls and a bare `cd` breaks
+   later relative-path commands (verifyall session friction, 2026-09-23).
 2. Loop on that narrow target until green.
 3. **Then** run the single full `spur-check` (or `bun run check`) as the final gate.
 
@@ -782,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/dev-operations.md

@@ -352,8 +352,8 @@ must not be changed without updating the backing skill.
 ### 13. runall
 
 - **Purpose:** Run a batch of tasks through their pipelines in dependency-correct order — resolve a set, topo-sort, run each via `task-pipeline.yaml`, inspect verdicts, apply the failure policy, emit a batch report.
-- **Inputs:** `--tasks <selector>` (required — explicit WBS list, status pseudo-list, `feature:<id>`, or `ready`). `--mode <sequential|parallel>` (default `sequential`; `parallel` fans out a proven-independent subset per `execution-batch.md` § Parallel Execution). `--keep-going` skips a failed task's in-batch dependents and continues independents (default halts on first failure). `--auto` sets `profile=auto` on each per-task run (skips the HITL approve gate). `--feature <id>` is sugar for `--tasks feature:<id>`; when the effective selector is feature-derived, the batch runs `spur feature check <id> --strict --json` **once** before task resolution — a non-zero strict check aborts with verdict `aborted`, zero attempted tasks, and the structured findings (task 0510 R2); scoped: `L4.scenario-unverified` (expected pre-run state of any not-yet-run feature) is reported verbatim but does not abort — any other strict error aborts. Explicit WBS/status/`ready` selectors add no feature check. The orchestrator loop itself continues in this session; interactive sequential omit/`inline` uses the host driver — host-controlled with eligible `agent.run` stages dispatching once to a native subagent and host fallback (task 0508) — while `--agent auto`/a name, parallel mode, and headless invocation keep the isolated per-task workflow subprocess boundary. `--agent <inline|auto|name>` pins the executor for the per-task stages (see [SSOT](cross-cutting.md#inline-default-execution-surface)); the value crosses into per-task `vars.agent`, not the orchestrator. `--json` emits the report as JSON. `--wrap` triggers `wrapup-pipeline.yaml` after the batch completes, `--next` chains each task to terminal status then runs the wrap hop **once for the batch**, `--continue` resumes from checkpoint.
-- **Three orthogonal axes (do not confuse):** `--keep-going` = batch failure policy (halt vs skip dependents); `--continue` = resume from checkpoint (pick up an interrupted batch); `--next` = per-task lifecycle chaining (advance status on a verdict — `dev-verify`/`dev-verifyall` only). `routing-table.md` offers `--continue` and `--next` as competing options for the same situation only when the batch was interrupted mid-run; otherwise they address different problems.
+- **Inputs:** `--tasks <selector>` (required — explicit WBS list, status pseudo-list, `feature:<id>`, or `ready`). `--mode <sequential|parallel>` (default `sequential`; `parallel` fans out a proven-independent subset per `execution-batch.md` § Parallel Execution). `--keep-going` skips a failed task's in-batch dependents and continues independents (default halts on first failure). `--auto` sets `profile=auto` on each per-task run (skips the HITL approve gate). `--feature <id>` is sugar for `--tasks feature:<id>`; when the effective selector is feature-derived, the batch runs `spur feature check <id> --strict --json` **once** before task resolution — a non-zero strict check aborts with verdict `aborted`, zero attempted tasks, and the structured findings (task 0510 R2); scoped: `L4.scenario-unverified` (expected pre-run state of any not-yet-run feature) is reported verbatim but does not abort — any other strict error aborts. Explicit WBS/status/`ready` selectors add no feature check. The orchestrator loop itself continues in this session; interactive sequential omit/`inline` uses the host driver — host-controlled with eligible `agent.run` stages dispatching once to a native subagent and host fallback (task 0508) — while `--agent auto`/a name, parallel mode, and headless invocation keep the isolated per-task workflow subprocess boundary. `--agent <inline|auto|name>` pins the executor for the per-task stages (see [SSOT](cross-cutting.md#inline-default-execution-surface)); the value crosses into per-task `vars.agent`, not the orchestrator. `--json` emits the report as JSON. `--wrap` triggers `wrapup-pipeline.yaml` **once for the batch** over the `done` subset only (execution-batch.md Step 6: `vars.feature` only when every frozen task is `done`/`cancelled`; empty done subset skips with a reason), `--next` chains each task to terminal status then runs the same batch-once wrap, `--continue` resumes from checkpoint.
+- **Three orthogonal axes (do not confuse):** `--keep-going` = batch failure policy (halt vs skip dependents); `--continue` = resume from checkpoint against the batch's original frozen identity (execution-batch.md § Batch continuation, task 0919); `--next` = per-task lifecycle chaining (advance status on a verdict — `dev-verify`/`dev-verifyall` only). `routing-table.md` offers `--continue` and `--next` as competing options for the same situation only when the batch was interrupted mid-run; otherwise they address different problems.
 - **Backing:** `sp:spur-dev` skill, `runall` operation → delegates the driver loop to the **`sp:super-planner`** agent (the batch orchestrator).
 - **Behavior:** The orchestrator reads [execution-batch.md](execution-batch.md) and drives: resolve selector → freeze set → topo-sort by `dependencies[]` (Kahn, WBS-ascending tie-break; cycle aborts) → resolve out-of-set deps by status (done → allow, else → block subtree) → run each task via `spur workflow run task-pipeline.yaml --async` + `spur workflow trace` polling → inspect terminal state + `.spur/run/<wbs>-verdict.json` → stop-the-batch default or `--keep-going` subtree skip → emit batch report. Per-task pipeline is invoked **verbatim** — no new FSM, no step edits. `--auto`/`--agent` are the only flags that cross the orchestrator→pipeline boundary (both into per-task `--vars`).
 - **Delegation:** `Skill(skill="sp:spur-dev", args="runall $ARGUMENTS")` → `sp:super-planner` agent.

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.