@gobing-ai/spur 0.3.41 → 0.3.43

package/plugins/sp/skills/next-router/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: next-router
+description: "Status→command router backing /sp:dev-next — resolve a task WBS or feature frontier, load corpus signals, look up TABLE A/B/C, dispatch exactly one existing /sp:dev-* command or stop with an exact dev-next: message. Never a second pipeline FSM. Triggers: \"what's next\", \"advance this task\", \"which dev command\"."
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  protocol: "sp:next-router@1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  interactions:
+    - router
+  modes:
+    - dry-run
+    - dispatch
+  openclaw:
+    emoji: "🧭"
+---
+
+# Next Router — Status→Command Dispatcher
+
+`sp:next-router` is the backing skill for `/sp:dev-next`. It inspects corpus status (plus light
+gates when a row calls for them), selects the **single best existing** `/sp:dev-*` command (or
+documented `spur` verb) for a task WBS or feature frontier, optionally executes it, and on clean
+success lets that command's own `--next` chain continue — **without inventing a second pipeline
+FSM**.
+
+The routing tables (TABLE A task / TABLE B feature / TABLE C light gates), the frontier-selection
+algorithm, the HITL stop matrix, chain semantics, and the explicit non-routes are the SSOT in
+**[references/routing-table.md](references/routing-table.md)**. This file owns the driver protocol:
+parse → resolve → signals → lookup → shape argv → dispatch or stop.
+
+## When to use
+
+- Unsure which `/sp:dev-*` command to run for a task or feature.
+- Want to complete the current lifecycle step and advance when gates are clean.
+- Hygiene forks (unit gap, lint red, rule findings) need a deterministic first hop.
+
+Do **not** use this skill to: reimplement `task-pipeline.yaml`, bypass lifecycle guards, batch a
+feature (that is `/sp:dev-runall` — a deliberate aperture), or pick among multi-candidate forks
+silently (that is a HITL stop).
+
+## Inputs
+
+| Input | Semantics |
+|-------|-----------|
+| `target` | Task WBS (digits), task `.md` path, or feature id (`^[A-Z][1-9]*$`). Required for dispatch; omit → stop **U1** (usage). |
+| `--dry-run` | Print the resolved plan (**P1**) and do not dispatch. |
+| `--once` | Strip `--next` from the shaped child argv so only the current step runs; no router re-entry. |
+| `--auto` | Forward into dispatched children that support it. **Never** breaks multi-candidate HITL ties. |
+| `--agent <inline\|auto\|name>` | Execution-surface selector forwarded into the dispatched child when that child documents `--agent`. Router defaults inline; a named escalation trigger overrides `--agent inline`. Omit → forward nothing. |
+| `--full` | When the primary route is `dev-run … --next`, substitute `dev-run <wbs> --mode full` (no `--next`). No effect on non-run routes → warning **W-FULL**. |
+
+## Protocol (deterministic)
+
+1. **Parse** — split `$ARGUMENTS` into target + flags. Unknown flags are not silently dropped:
+   note them in the plan line (P1) or stop U1 if no valid target remains.
+2. **Resolve target** —
+   - digits / known WBS → task mode;
+   - task `.md` path → resolve WBS via `spur task resolve` / path handling;
+   - feature id → TABLE B: run the **frontier algorithm** (routing-table §2 B3) over
+     `spur task list --json` + per-dep `spur task show <dep> --json`; no frontier → feature-level
+     row (B4–B8), usually a stop.
+   - unresolvable → stop **U2**; omitted → stop **U1**.
+3. **Load signals (corpus first)** — `spur task show <wbs> --json` (status, `dependencies[]`),
+   dep statuses, `spur feature show <id> --json` when invoked by feature. Light gates only when
+   the matched row sets `probe=yes`.
+4. **Table lookup** — TABLE A (task) or TABLE B (feature-level). Apply TABLE C **sequential
+   short-circuit** probes in order C1→C5; first hit replaces the dispatch.
+5. **Cardinality** — 0 candidates → stop **U3**; 1 → continue; >1 → HITL stop **U-HITL**
+   (decision-brief; `--auto` does not pick a winner).
+6. **Shape child argv** — apply `--once` (strip `--next`), `--full` (run-chain rewrite only),
+   `--auto` / `--agent` / execution-surface forwarding per the Inputs table and
+   [cross-cutting.md](../spur-dev/references/cross-cutting.md#inline-default-execution-surface).
+7. **`--dry-run`** → print plan block **P1**; exit success without dispatching.
+8. **Dispatch** — print **P2**, invoke the child:
+   - **Claude Code:** `Skill(skill="sp:spur-dev", args="…")` (or the documented backing
+     skill/command protocol for refine/run/verify/unit/wrap/wrapall/handover/fixall) with the
+     shaped argv.
+   - On child guard failure / review-pending → stop **U-GUARD** (leave task status untouched).
+   - On success → print **P3**. The child's own `--next` chain (when left intact) continues on
+     its own; the router never double-chains.
+
+**Step budget:** one router invocation performs **at most one primary dispatch** (+ whatever that
+command's own `--next` chain does). Never self-loop `/sp:dev-next`.
+
+## Chain progression contract (`--next`)
+
+The router is the single owner of `--next` chain progression. The definition of [`--next`](../spur-dev/references/flag-glossary.md#flag-next)
+and the full chain contract (stop conditions, hop bound, reporting) live in the glossary; this
+section states the router's side: how a chain propagates, how it stops, and how it reports.
+
+**Single dispatch per invocation.** One router invocation performs **at most one primary dispatch**
+(already stated above as the step budget). Chain continuation is the child's `--next` re-entering
+the router, not the router self-looping. The router never double-chains.
+
+**Propagation.** When the dispatched child completes successfully and its argv carried `--next`
+(i.e. `--once` was not applied), the child re-invokes `/sp:dev-next` with the same target and
+`--next` still set. The router resolves the next dispatch from the **new** task status (which may
+have advanced) and dispatches again. This is the chain: router → child → router → child, until a
+stop condition.
+
+**Hop bound: 8 primary dispatches per `--next` chain.** A chain running under `--next` performs at
+most **8 primary dispatches**. Each router re-entry is one hop. When the bound is reached without a
+terminal task status, the router stops and emits message **W-CHAIN-BOUND** (below): "chain halted —
+hop bound (8) reached at `<step>` without terminal status; this indicates a routing cycle, not
+completion." The bound is sized for the longest legitimate chain (refine → run → verify → wrap is
+four hops; the remaining four absorb probe short-circuits like `dev-fixall`/`dev-unit`).
+
+**Stop conditions.** A chain halts cleanly when a gate fails, the verify verdict is non-PASS, a
+HITL pause fires (taste gate, irreversible gate, multi-candidate fork), dependencies are unmet, or
+the task reaches terminal status. The stop is a normal outcome, not an error: the report names
+which step halted and why ("chain halted at `<step>` — `<cause>`"), distinct from the completion
+report ("chain complete — task `<wbs>` is `<status>`"). The per-row `Stop / notes` column in
+[routing-table.md](references/routing-table.md) §5 names the stop condition for each route.
+
+**Flag vs command.** `/sp:dev-next` (the command) runs the next step **once** and stops; `--next`
+(the flag) makes any command it is passed to **keep going**. `/sp:dev-next <wbs> --next` is valid
+but redundant. See the glossary entry for the disambiguation in full.
+
+| Id | Fires when | Kind |
+|----|-----------|------|
+| W-CHAIN-BOUND | `--next` chain hit the 8-dispatch hop bound without terminal status | warning — stop (routing-cycle suspected) |
+
+## Operator messages
+
+**[references/messages.md](references/messages.md)** (exact templates, prefixed `dev-next:`). The router fires them by id:
+
+| Id | Fires when | Kind |
+|----|-----------|------|
+| U1 | no target | stop — usage |
+| U2 | target unresolvable | stop |
+| U3 | no route (table miss / cancelled) | stop |
+| U4 | todo with open dependencies (A2) | stop |
+| U-HITL | multi-candidate fork | HITL stop — decision-brief, then dispatch only after answer |
+| U-GUARD | child guard / review-pending failure | stop — recovery line |
+| P1 | `--dry-run` | plan block |
+| P2 | dispatch start | info |
+| P3 | success | info — re-run hint |
+| W-FULL | `--full` on a non-run route | warning — continue |
+
+## Non-routes (summary — full table in routing-table §6)
+
+Never: reimplement the pipeline inside the router; default `todo` to `--mode full`; infer targets
+from git/chat; auto-`--merge` on wrap; auto-author rules; use `dev-runall` as the feature default;
+bypass lifecycle guards (`--no-lifecycle`) to force progress.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "Two candidates are both fine — pick the higher-priority one." | Multi-candidate is a HITL stop (routing-table §4). A silent pick hides a real fork from the operator; print the decision-brief. |
+| "The task is todo, so run the full pipeline to be safe." | Full mode is not the v1 default (non-route). A3 dispatches the `--next` chain link; `--full` exists for the explicit override. |
+| "I can loop dev-next until the task is done." | Step budget is one dispatch per invocation. Self-looping makes token cost unbounded; the operator re-invokes after non-chain dispatches. |
+| "The guard failed but the fix is obvious — force it through." | Guards are the product (non-route: no lifecycle bypass). Stop U-GUARD, surface the finding, let the operator resolve. |
+
+## Red Flags
+
+- Dispatching more than one primary command in a single invocation.
+- `--auto` used to choose among HITL candidates.
+- A route that is not in TABLE A/B/C (invented dispatch targets).
+- `--once` honored by merely skipping the re-invoke while leaving `--next` in the child argv.
+- Omitting the `dev-next:` prefix on stop/plan messages.
+
+## Platform Notes
+
+- **Claude Code:** invoked via `/sp:dev-next` → `Skill(skill="sp:next-router", args="$ARGUMENTS")`;
+  dispatch children via `Skill()`; HITL via `AskUserQuestion` with the decision-brief options.
+- **Codex / OpenClaw / OpenCode / Antigravity:** no `Skill()` — read this file +
+  `references/routing-table.md` as the procedure SSOT; corpus signals via
+  `spur task show|list --json`, `spur feature show|list --json`, `spur task check --json`;
+  dispatch by invoking the target command protocol (or its backing skill) with forwarded flags;
+  message literals in `plugins/sp/commands/dev-next.md`; HITL via the platform's decision-brief
+  equivalent (`spur-dev/references/decision-brief.md`). Never reimplement refine/run/verify inside
+  the router.
+
+## See also
+
+- **[references/routing-table.md](references/routing-table.md)** — TABLE A/B/C SSOT + algorithm.
+- **`sp:spur-dev`** — the spine that owns the lifecycle the router dispatches into.
+- **`sp:dogfood-testing`** — peer meta-tool (also outside the numbered dev-operations map).
+- **`plugins/sp/skills/spur-dev/references/decision-brief.md`** — HITL brief format.

package/plugins/sp/skills/next-router/references/messages.md

@@ -0,0 +1,90 @@
+---
+name: messages
+description: "Exact dev-next: operator-message literals for sp:next-router — U1, U2, U3, U4, U-HITL, U-GUARD, P1, P2, P3, W-FULL templates, verbatim (R3)."
+see_also:
+  - next-router
+---
+
+# Operator Messages — Exact Templates (R3)
+
+Use these literals (substitute angle-bracket tokens). Prefix every stop with `dev-next:`.
+
+### U1 — no target
+```
+dev-next: no target
+  usage: /sp:dev-next <wbs|feature-id> [--dry-run] [--once] [--auto] [--agent <name|auto>] [--full]
+  hint: pass a task WBS (e.g. 0274) or feature id (e.g. N)
+```
+
+### U2 — unknown / unresolvable target
+```
+dev-next: cannot resolve target <raw>
+  spur task show / spur feature show failed
+  fix: check WBS/feature id, then re-run
+```
+
+### U3 — no route (table miss / cancelled)
+```
+dev-next: no route for <wbs|feature> (status=<status>)
+  reason: <one-line from table stop notes>
+```
+
+### U4 — deps not satisfied (A2)
+```
+dev-next: blocked by open dependencies for <wbs>
+  unmet: <dep1>(status), <dep2>(status), …
+  fix: finish deps or re-order work; re-run /sp:dev-next <wbs>
+```
+
+### U-HITL — multi-candidate
+```
+dev-next: multiple candidates — choose one
+  task/feature: <id>  status=<status>
+  recommended: <cmd-1>
+  alternatives:
+    - <cmd-2>
+    - <cmd-3>
+  stakes: <one line>
+  (re-run with an explicit /sp:dev-* if you prefer not to use the router)
+```
+Then invoke decision-brief / AskUserQuestion; do not dispatch until answered.
+
+### U-GUARD — child guard / review-pending
+```
+dev-next: dispatch stopped (review-pending)
+  child: <exact invocation>
+  reason: <guard or verify verdict summary>
+  task left at status=<status>
+  fix: resolve the finding, then /sp:dev-next <wbs>
+```
+
+### P1 — dry-run plan
+```
+dev-next: plan (dry-run)
+  target: <wbs> (from <raw>)  status=<status>  feature=<id|—>
+  row: <A#|B#|C#>  probe=<yes|no>
+  signals: <bullet or compact json keys>
+  dispatch: <exact child argv>
+  chain: <embedded --next|none>  once=<bool>  full=<bool>  auto=<bool>
+  (no commands executed)
+```
+
+### P2 — dispatch start
+```
+dev-next: dispatch
+  row: <A#|B#|C#>
+  → <exact child argv>
+```
+
+### P3 — success (no further router work)
+```
+dev-next: ok
+  child finished: <exact child argv>
+  task status now: <status>
+  next: re-run /sp:dev-next <wbs> if more steps remain (or rely on child --next chain if present)
+```
+
+### W-FULL — --full ignored
+```
+dev-next: warning — --full ignored (primary route is not dev-run --next); continuing with <dispatch>
+```

package/plugins/sp/skills/next-router/references/routing-table.md

@@ -0,0 +1,216 @@
+---
+name: routing-table
+description: "SSOT routing tables for sp:next-router — resolution algorithm, TABLE A (task status), TABLE B (feature frontier), TABLE C (light-gate short-circuit), HITL stop matrix, chain semantics, and explicit non-routes. Seeded from task 0270 Solution."
+see_also:
+  - next-router
+---
+
+# Routing Table — `/sp:dev-next` v1
+
+The v1 routing table is the SSOT for `/sp:dev-next`. The router is a pure status→command
+dispatcher: resolve target → load corpus → apply primary table → optional light-gate short-circuit
+→ single dispatch or HITL stop → optional chain.
+
+## Batch consumers (task 0279)
+
+`sp:super-planner` (via `/sp:dev-runall`) **reads** TABLE A STOP preconditions for:
+
+1. **Preflight** — skip pipeline launch when A2/A7/A8/A9 would stop `dev-next` (`batch-preflight.ts`).
+2. **One-shot recovery** — after a failed pipeline, map status → primary hop (A1/A3/A5/A6/A7) at most once.
+
+It does **not** reimplement TABLES or replace `task-pipeline.yaml` with a `dev-next` loop. Keep this
+file as the only SSOT for row semantics; batch helpers must stay aligned with A2/A7/A8/A9 codes.
+
+## 0. Algorithm (deterministic)
+
+```
+INPUT:  positional target (WBS | feature-id | omit), flags (--dry-run, --once, --auto?, --agent?, --full?)
+OUTPUT: printed plan; optionally invoke one /sp:dev-* or spur verb; optionally chain
+
+1. Resolve target
+   a. Digits-only or known WBS → task mode
+   b. Feature-id regex ^[A-Z][1-9]*$ → feature mode (pick frontier task, else feature-level row)
+   c. Omitted → NOT v1 (see Non-routes); stop with usage
+2. Load signals (corpus first)
+   - task:  spur task show <wbs> --json
+   - feature (if any): spur feature show <id> --json
+   - deps: for each dependencies[] entry, spur task show <dep> --json → status
+3. Primary route = TABLE A (task) or TABLE B (feature-level when no frontier task)
+4. Light gates — ONLY if the matched row sets probe=yes
+   - Run TABLE C probes in listed short-circuit order; first hit replaces dispatch
+5. Cardinality
+   - 0 candidates → stop (message: no route)
+   - 1 candidate → dispatch (or print if --dry-run)
+   - >1 candidates → HITL STOP (decision-brief; never silent pick)
+6. On dispatch success and not --once and row.chain is set → invoke chain command
+   On guard/HITL/fail → stop; leave status; print recovery line
+```
+
+**Default flags forwarded into dispatched lifecycle commands:** `--auto` when the operator passed
+it or when chaining (chain links already use `--auto` per existing refine→run→verify convention).
+`--agent` forwarded only when the child command documents it. `--full` only rewrites a
+`dev-run … --next` primary into `dev-run <wbs> --mode full` (without `--next`); ignored otherwise
+(warning W-FULL).
+
+## 1. TABLE A — Task primary routes (corpus status)
+
+Statuses from `TASK_STATUSES`: backlog | todo | wip | testing | blocked | done | cancelled.
+
+| # | Precondition | Primary signal | Dispatch | probe | Chain on success? | Stop / notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| A1 | `status == backlog` | `task.show.status` | `/sp:dev-refine <wbs> --auto --next` | yes (refine skip-gate sections) | **yes** — refine's own `--next` → run → verify | If refine fails guard → stop review-pending |
+| A2 | `status == todo` AND any open dep `status != done` | `dependencies[]` + dep statuses | *(none)* | no | no | **STOP** — blocked by deps; print unmet dep WBS list. Do not invent parallel work. |
+| A3 | `status == todo` AND deps satisfied | `task.show.status` + deps | `/sp:dev-run <wbs> --mode implement --auto --next` | yes | **yes** — implement → verify | Explicit mode prevents the pipeline step from recursively launching full mode (bug-742) |
+| A4 | `status == wip` AND checkpoint exists under `.spur/memory/sessions/*-<wbs>-*` | checkpoint `next_action` | `/sp:dev-run <wbs> --continue` | no | no (continue owns resume) | If continue cannot resume → fall through A5 |
+| A5 | `status == wip` (no usable checkpoint) | `task.show.status` | `/sp:dev-run <wbs> --mode implement --auto --next` | yes | **yes** → verify | Completes implement step then chain |
+| A6 | `status == testing` | `task.show.status` | `/sp:dev-verify <wbs> --auto --next` | yes | **yes** — verify `--next` → done (FSM + provenance guards) | On PARTIAL/FAIL → stop review-pending (do not force done) |
+| A7 | `status == blocked` | `task.show` + Notes/History for blocker text | `/sp:dev-handover "<blocker summary from Notes or status>"` | no | no | **STOP** after handover doc; human unblocks |
+| A8 | `status == done` | `task.show.status` | `/sp:dev-wrap <wbs>` (`--agent <value>` preserved when the originating command supplied it; omission remains omission) | no | **no** (wrap's `--merge` is irreversible HITL; never auto) | Operator may re-invoke with `--merge` explicitly later |
+| A9 | `status == cancelled` | `task.show.status` | *(none)* | no | no | **STOP** — no-op; print "cancelled — nothing to advance" |
+
+**Priority when multiple TABLE A rows could match:** lowest row number wins (A1–A9 are mutually
+exclusive by status except A2/A3 which split `todo`).
+
+## 2. TABLE B — Feature-ID path (rollup)
+
+When input is a feature id:
+
+| # | Precondition | Primary signal | Dispatch | probe | Chain? | Stop / notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| B0 | Feature missing / invalid id | `feature show` exit ≠ 0 | *(none)* | no | no | **STOP** — unknown feature |
+| B1 | `feature.status == cancelled` | feature status | *(none)* | no | no | **STOP** |
+| B2 | `feature.status == done` | feature status | *(none)* | no | no | **STOP** — suggest archive/docs only; no auto wrapall |
+| B3 | Feature has ≥1 frontier task | task list under feature | **Recurse TABLE A** on chosen task | per A | per A | Frontier = open (`backlog`\|`todo`\|`wip`\|`testing`\|`blocked`), unblocked (all `dependencies[]` done), prefer WBS-ascending among `todo` then `backlog` then `wip` then `testing` then `blocked` |
+| B4 | No frontier tasks AND `feature.status == backlog` AND AC placeholder/invalid | `feature check` / AC body | `/sp:dev-plan` continuation is not WBS-shaped — **STOP** with: run `/sp:dev-plan --feature <id>` or fix AC then `spur feature check <id>` | no | no | Planning-half entry needs a description; do not invent idea text |
+| B5 | No frontier tasks AND feature has valid AC but zero tasks | feature + empty task roster | **STOP** with: `/sp:dev-plan --feature <id>` (decompose/batch-create) | no | no | Avoid auto-running plan without operator description confirmation in v1 |
+| B6 | No frontier tasks AND all child tasks `done` AND feature in `active`\|`verifying` | task list all done | `/sp:dev-wrapall --feature <id>` (`--agent <value>` preserved when the originating command supplied it; omission remains omission) | no | no | Advances feature via wrapall guards; `--merge` never auto |
+| B7 | No frontier tasks AND mixed cancelled/done only | statuses | **STOP** — print summary; suggest feature status update manually | no | no | |
+| B8 | `feature.status == blocked` | feature status | **STOP** — print feature blocked; do not pick tasks | no | no | |
+
+**Frontier selection algorithm (B3) — precise:**
+
+```
+candidates = tasks where feature_id == ID
+             AND status ∈ {backlog, todo, wip, testing, blocked}
+             AND every dep in dependencies[] has status == done
+order = stable sort by:
+  1. status rank: todo=0, backlog=1, wip=2, testing=3, blocked=4
+  2. WBS ascending (numeric)
+pick = first(candidates)
+if pick is null → TABLE B rows B4–B7
+else → TABLE A(pick)
+```
+
+## 3. TABLE C — Light-gate short-circuit (probe=yes rows only)
+
+**Order is sequential short-circuit** (first match wins). Never parallel in v1 (simpler, lower
+token, deterministic).
+
+| Order | When evaluated | Probe | Signal | Redirect dispatch | Else |
+| --- | --- | --- | --- | --- | --- |
+| C1 | A1, A3, A5 (pre-implement / refine path) | `spur task check <wbs> --json` | Any **L3** finding on sections ∈ {Background, Requirements, Acceptance Criteria, Design, Plan} | Force `/sp:dev-refine <wbs> --auto` (**without** `--next` if already mid-refine; with `--next` only when status was backlog/todo and operator wants chain — default: keep `--next` for A1/A3) | continue |
+| C2 | A3, A5 after C1 clean | Cheap workspace health: `bun run lint` (or project lint) exit ≠ 0 **and** scope inferable from task Solution/Plan paths or default repo | lint/type failures | `/sp:dev-fixall` (optional `--scope` if single package known) | continue |
+| C3 | A5/A6 when Testing empty/N/A **and** verify would fail for missing tests — only if prior implement claims code exists | Coverage/test signal: `bun test` fail attributed to task paths OR explicit "insufficient tests" in prior verify verdict artifact `.spur/run/<wbs>-verdict.json` | test fail / coverage gap | `/sp:dev-unit <wbs> --auto` | continue |
+| C4 | A3/A5/A6 when operator or task tags mention rules, OR `spur rule run` last report dirty in `.spur/` if present | `spur rule run` (default project preset) non-zero with findings | rule findings | **HITL STOP** — print rule summary; suggest `/sp:rule-scan` or `rule-add`/`rule-refine` (do not auto-author rules) | continue |
+| C5 | A6 only | Existing `.spur/run/<wbs>-verdict.json` with FAIL and findings pointing at coverage | verdict artifact | `/sp:dev-unit <wbs>` then re-verify on next invocation (`--once` friendly) | `/sp:dev-verify …` |
+
+**Explicit non-probes in v1:** no freeform chat history; no always-on full `bun run test` for every
+call; no git dirtiness as a route (optional advisory print only).
+
+## 4. Multi-candidate HITL STOP matrix
+
+| Situation | Why not auto | Operator brief options (recommended first) |
+| --- | --- | --- |
+| C2 and C3 both true | lint vs tests both red | (1) fixall (2) unit (3) abort |
+| Feature B3 pick ambiguous because two `todo` same rank — **should not happen** after WBS sort | — | N/A — WBS tie-break is total |
+| Task `todo` but also feature-level AC invalid when invoked via feature id | feature health vs task progress | (1) fix feature AC (2) proceed with task A3 |
+| `testing` with open P1 in Review section | verify vs review-fix | (1) `/sp:dev-review <wbs> --fix blockers-first` (2) verify anyway |
+| `wip` with both checkpoint and dirty Solution L3 | resume vs re-implement | (1) `--continue` (2) implement `--next` |
+
+When HITL STOP fires: print decision-brief (question, stakes, recommended option, alternatives).
+**Do not dispatch** until operator answers (or `--auto` is **not** allowed to break multi-candidate
+ties in v1 — `--auto` only skips confirmations *inside* a single chosen command).
+
+## 5. Chain semantics (success path)
+
+**Canonical definition.** [`--next`](../../spur-dev/references/flag-glossary.md#flag-next) is
+chain-to-completion with propagation: on success, hand the task back to `sp:next-router`, which
+resolves the next dispatch and re-invokes with `--next` still set, until the work is done or a gate
+stops it. The full chain contract (stop conditions, hop bound, reporting) lives in the glossary; this
+section is the routing-table projection of it. Per-row `Stop / notes` columns below name the stop
+condition for each route.
+
+| After successful dispatch | If not `--once` | Stop condition | Notes |
+| --- | --- | --- | --- |
+| `dev-refine … --next` | chains to `dev-run` (status → todo+deps) | unmet deps (A2), guard fail, refine guard fail | Router does not double-chain |
+| `dev-run … --next` | chains to `dev-verify` (status → testing) | non-PASS verify verdict, gate fail | Router does not double-chain |
+| `dev-verify … --next` | attempts done (FSM + provenance guards) | PARTIAL/FAIL verdict → stop review-pending; done → chain complete | Router stops after return |
+| `dev-unit` / `dev-fixall` / `dev-wrap` / `dev-handover` | **no auto re-entry** into router in v1 | operator re-invoke | Keeps token cost bounded; operator re-invokes `/sp:dev-next` |
+| HITL / guard failure | no chain | named in `Stop / notes` | Print recovery one-liner with exact re-run command |
+
+**Hop bound: 8.** A chain running under `--next` performs at most **8 primary dispatches** (router
+re-entries). When the bound is hit without terminal task status, the router stops and emits
+**W-CHAIN-BOUND** (routing-cycle suspected, not completion). The bound is sized for refine → run →
+verify → wrap (4 hops) plus probe short-circuits (`dev-fixall`/`dev-unit`).
+
+**Step budget:** one router invocation performs **at most one primary dispatch** (+ whatever that
+command's own `--next` chain does). It does **not** loop `dev-next` on itself (prevents unbounded
+auto).
+
+### `--once` vs child-embedded `--next` (clarification)
+
+TABLE A rows encode `--next` on refine/run/verify. Operator-facing `--once` on `/sp:dev-next`
+means "only the current step":
+
+1. Build child argv from table.
+2. If `--once`: remove `--next` from child argv (and any router-level re-entry).
+3. Dispatch single step; print P3 with hint to re-run `/sp:dev-next`.
+
+Without `--once`, leave table `--next` intact so refine→run→verify chain runs as today.
+
+> **Redefinition note (feature H8, task 0399, 2026-07-31).** Before the glossary, `--next` carried
+> four incompatible meanings across seven commands; this table was one of the places they collided.
+> Task 0401 reconciled every declaring command against the single definition above. `dev-run --next`
+> as implement-only mode selector is the only genuinely breaking case — replacement is
+> `--mode implement` (row A5 already dispatches that). See ADR-039.
+
+## 6. Non-routes (explicit)
+
+| Temptation | Why forbidden in v1 |
+| --- | --- |
+| Reimplement `task-pipeline.yaml` inside next | Spine owns full pipeline; use `dev-run` without `--next` only if we add a future row — **not default** |
+| Default to `/sp:dev-run --mode full` for every `todo` | Heavier HITL surface; chain-link is the locked auto-advance style |
+| Infer target from git dirty / chat | Locked out of v1 signals |
+| Auto `--merge` on wrap | Irreversible |
+| Auto `rule-add` | Authoring needs human judgment |
+| `dev-runall` as default for feature | Batch is a deliberate aperture; feature path picks **one** frontier task |
+| Lifecycle bypass (`--no-lifecycle`) to force progress | Guards are the product |
+
+## 7. Worked scenarios (stress tests)
+
+**S1 — New task, backlog, empty Plan L3**
+Signals: status=backlog → A1 → C1 may still refine → `/sp:dev-refine 0042 --auto --next` → chains
+to implement/verify.
+
+**S2 — Mid implement, wip, no checkpoint**
+A5 → C1 clean → C2 lint red → short-circuit `/sp:dev-fixall` → stop (no auto re-enter). Operator
+runs `/sp:dev-next 0042` again → A5 → implement.
+
+**S3 — Feature F, three todo tasks, one blocked by dep**
+B3 frontier filter drops blocked-by-dep; WBS-ascending picks lowest ready todo → A3.
+
+**S4 — All tasks done, feature active**
+B6 → `/sp:dev-wrapall --feature F`.
+
+**S5 — testing, verify would fail on tests**
+A6 → C5/C3 → unit first if verdict says so; else verify.
+
+## Source anchors (file:line)
+
+- Task status enum: `packages/domain/src/planning/schema.ts:20`
+- Feature status enum: `packages/domain/src/planning/schema.ts:23`
+- Dev operations map: `plugins/sp/skills/spur-dev/references/dev-operations.md:37-56`
+- `--next` chain on run: `plugins/sp/commands/dev-run.md:104-127`
+- Refine skip-gate sections: `plugins/sp/skills/spur-dev/references/dev-operations.md:114-128`
+- Task lifecycle wip→testing guard: `.spur/workflows/task-lifecycle.yaml:48-54`
+- Decision-brief format: `plugins/sp/skills/spur-dev/references/decision-brief.md`

package/plugins/sp/skills/parallel-execution/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: parallel-execution
+description: "Decide when to fan out independent work across subagents, choose the fan-out pattern, synthesize parallel results. Triggers: \"fan out\", \"run in parallel\", \"parallelize\", \"concurrent execution\", \"multi-agent run\"."
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  category: execution
+  interactions:
+    - technique
+    - pipeline
+  operations:
+    - fan-out
+    - review-panel
+    - investigation
+    - result-synthesis
+see_also:
+  - sp:spur-dev
+  - sp:super-planner
+---
+
+# sp:parallel-execution — Parallel Execution & Fan-Out
+
+The parallel-execution competency — decide when to fan out independent work across subagents, choose the right fan-out pattern, and synthesize parallel results. This skill owns the **decision framework** (when to parallelize) and the **execution patterns** (how to structure fan-out); the spine (`sp:spur-dev`) and batch orchestrator (`sp:super-planner`) consult it when they encounter independent work.
+
+This is a **competency skill** — it teaches the agent *how* to parallelize, not *what* to parallelize. The spine owns the lifecycle and task selection; this skill owns the fan-out mechanics.
+
+## The decision framework
+
+**The one question:** can these items run independently with no shared mutable state and no sequential dependency?
+
+Ask these five questions before fanning out:
+
+| Question | Yes → | No → |
+|----------|-------|------|
+| Do the items share mutable state (files, DB, global config)? | Serialize | Continue |
+| Is there a hard sequential dependency (B needs A's output)? | Serialize A→B | Continue |
+| Do the items target overlapping files (same file:line range)? | Serialize or merge-first | Continue |
+| Is the remaining token budget ≥ (N × estimated cost per subagent)? | Continue | Reduce N or serialize |
+| Are the items truly independent concerns (different skills/modules)? | Fan out | Question whether splitting is artificial |
+
+**Hard rule:** if ANY question in rows 1-3 is Yes, serialize. Rows 4-5 are advisory — they guide N and pattern choice but don't block fan-out.
+
+## Fan-out patterns
+
+Four proven patterns, cataloged in [fan-out-patterns.md](references/fan-out-patterns.md):
+
+| Pattern | Use when | Token cost | Result shape |
+|---------|----------|------------|--------------|
+| **N-way investigation** | One question, N independent search angles | ~N × 3k | Merged findings, deduped |
+| **Competency-lens review** | One artifact, N review dimensions | ~N × 5k | Per-lens verdicts, unified report |
+| **Independent-task batch** | M tasks, zero dependency edges | ~M × 8k | Per-task results, batch summary |
+| **Adversarial verification panel** | One claim, N independent skeptics | ~N × 4k | Vote tally (survives if ≥2/3 affirm) |
+
+**Pattern selection rule:** match the work shape to the pattern. Don't force a pattern onto mismatched work — N-way investigation on dependent tasks produces conflicting results; adversarial panel on a fact-check produces noise.
+
+## Result synthesis
+
+Parallel subagent outputs must be **synthesized**, not concatenated. The synthesis contract:
+
+1. **Dedup** — merge findings with the same `file:line` anchor; keep the highest-severity version.
+2. **Resolve conflicts** — when two subagents disagree on the same claim, surface the disagreement explicitly; don't silently pick one.
+3. **Rank by confidence** — sort synthesized results by confidence (HIGH → MEDIUM → LOW); unresolved conflicts go last.
+4. **Unified format** — emit one coherent output, not N raw dumps.
+
+Full synthesis methodology: [result-synthesis.md](references/result-synthesis.md).
+
+## Subagent execution disciplines
+
+When you dispatch work to a subagent - a fan-out worker, an adversarial reviewer, a research angle -
+four disciplines keep the dispatch reliable and cheap. They apply to every pattern above and are the
+SSOT the batch orchestrator (`sp:super-planner`) and [execution-batch.md](../spur-dev/references/execution-batch.md) point back to. The choice of which **execution surface** carries the dispatch
+(native subagent vs `spur agent run`) is decided by [dispatch-surface.md](references/dispatch-surface.md) - apply it before these disciplines.
+
+### Hand artifacts as files, not pasted context
+
+Never paste bulk context into a dispatch prompt. Write the artifact — the diff, the file set, the
+spec excerpt, the data — to a file and hand the subagent the **path**. Pasting bulk text bloats the
+prompt, truncates unpredictably, and cannot be re-read after compaction. A file handoff is durable,
+re-readable, and keeps the dispatch prompt small enough to reason about.
+
+### Keep a durable progress ledger
+
+Maintain a progress ledger that survives compaction — a file (or the batch report table) recording,
+per dispatched item, its status (pending / running / done / failed) and its result location. When the
+session compacts or a run resumes, the ledger is the source of truth for what already ran; working
+memory is not. Update it as each item terminates, not in one batch at the end.
+
+### Select the cheapest model that fits each role
+
+Match the model to the role. A mechanical extraction or a structural check runs on a cheap model; a
+nuanced design review or a hard implementation wants a stronger one. Paying for the top model on every
+subagent role is waste; using a weak model on a judgment role is a false economy. Choose per role.
+
+### Never pre-judge the reviewer
+
+A reviewer/skeptic subagent must receive the artifact and the contract and nothing that steers its
+verdict. No "don't worry about X", no "this part is fine", no pre-rated severity, no "focus only on
+Y". A pre-judged reviewer confirms your framing instead of testing it — the exact failure the fan-out
+was meant to avoid. Let the reviewer reach its own conclusion.
+
+## Integration with the spine
+
+- **`sp:spur-dev`** owns task selection and lifecycle. When a batch contains independent tasks, the spine consults this skill for the fan-out pattern.
+- **`sp:super-planner`** is the orchestrator that executes the fan-out. Its parallel mode (documented in its agent definition) applies the patterns from this skill.
+- **`/sp:dev-parallel`** is the thin slash-command entry point that delegates to this skill.
+
+## When to use
+
+- Deciding whether a set of tasks can run in parallel.
+- Choosing the right fan-out pattern for a batch.
+- Synthesizing results from multiple subagent runs.
+- The operator says "fan out", "run in parallel", or "parallelize this batch."
+
+Do **not** use this skill for:
+- Sequential pipeline execution — that is `sp:spur-dev`'s execution half.
+- Single-task lifecycle — that is `sp:spur-dev` (`/sp:dev-run`).
+- Batch orchestration logic — that is `sp:super-planner` (the orchestrator); this skill is the *decision support* it consults.
+
+## Gotchas
+
+1. **Silent truncation is a finding.** If you fan out 10 items but only report on 8, the 2 dropped items are a finding — document them explicitly.
+2. **Token budget is real.** Fan-out multiplies token cost. The framework's row 4 is not optional — check `remaining budget` before spawning.
+3. **Same-file overlap = serialize.** Two subagents editing the same file WILL conflict. The framework catches this at decision time; don't override it.
+4. **Synthesis is work.** Merging N outputs is not free — budget ~2k tokens for synthesis per pattern. Plan for it.
+
+## References
+
+| [fan-out-patterns.md](references/fan-out-patterns.md) | Four fan-out patterns, per-pattern token-cost estimates, when-to-use decision table |
+| [result-synthesis.md](references/result-synthesis.md) | Merge/dedup/conflict-resolution strategies, anti-patterns, unified-report template |
+| [dispatch-surface.md](references/dispatch-surface.md) | Native subagent vs `spur agent run` decision rule: default, four escalation triggers, naming requirement, ADR-033 composition, sandbox reliability tax |
+
+## See also
+
+- **`sp:spur-dev`** — the orchestration spine that consults this skill for fan-out decisions.
+- **`sp:super-planner`** — the batch orchestrator that executes fan-out patterns.
+- **`/sp:dev-parallel`** — the slash command entry point for parallel execution.
+
+## Platform Notes
+
+### Claude Code
+
+Native - `Skill()`/`Task()` delegation for subagent spawns. The decision framework is consumed by the agent in-session; fan-out execution uses the **native subagent by default** and escalates to `spur agent run <prompt> --agent <name>` only when a named trigger in [dispatch-surface.md](references/dispatch-surface.md) applies.
+
+### Codex / OpenClaw / OpenCode / Antigravity
+
+Run the decision framework manually; spawn subagents via the platform's native multi-agent mechanism. Parse `--json` outputs for result synthesis.