@gobing-ai/spur 0.4.0 → 0.4.1

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

package/plugins/sp/skills/spur-dev/references/dev-operations.md

@@ -84,9 +84,10 @@ each would be scope creep for one-liner procedures.
 | 11  | handover   | `dev-handover`      | `inline`          | structured doc generation                                                          | `"<blocker description>"`                                                                                                                                                                              |
 | 11a | job-dump   | `dev-job-dump`      | `Skill()`         | `sp:spur-dev` (`job-dump`) | `--file <path>` |
 | 11b | job-resume | `dev-job-resume`    | `Skill()`         | `sp:spur-dev` (`job-resume`) | `--file <path>` |
-| 12  | brainstorm | `dev-brainstorm`    | `Skill()`         | `sp:brainstorm` (`dev-brainstorm`)                                                 | `<topic> [--depth <basic\|detailed\|comprehensive>] [--options <n>] [--agent <inline\|auto\|name>] [--skip-discovery] [--wayfind] [--task [<feature-id>]] [--feature [<parent-id>]] [--next]`          |
-| 13  | runall     | `dev-runall`        | `Skill()` → agent | `sp:spur-dev` (`runall`) → `sp:super-planner`                                      | `--tasks <selector> [--feature <id>] [--mode <sequential\|parallel>] [--keep-going] [--auto] [--agent <inline\|auto\|name>] [--json] [--wrap] [--next] [--continue] [--worktree [<name>]] [--no-summary]`                      |
-| 13a | parallel   | `dev-parallel`      | `Skill()`         | `sp:parallel-execution`                                                            | `--tasks <selector> [--feature <id>] [--mode <fan-out\|review-panel\|investigation>] [--agent <inline\|auto\|name>] [--json]`                                                                          |
+| 12  | brainstorm | `dev-brainstorm`    | `Skill()`         | `sp:brainstorm` (`dev-brainstorm`)                                                 | `<topic> [--depth <basic\|detailed\|comprehensive>] [--options <n>] [--agent <inline\|auto\|name>] [--skip-discovery] [--task [<feature-id>]] [--feature [<parent-id>]] [--next]`          |
+| 12a | find-way   | `dev-find-way`      | `Skill()`         | `sp:wayfinder` (worktree-isolated)                                                 | `<idea> \| <feature-id> [<wbs>] [--agent <inline\|auto\|name>] [--auto] [--worktree [<name>]] [--wrap]` |
+| 13  | runall     | `dev-runall`        | `Skill()` → agent | `sp:spur-dev` (`runall`) → `sp:super-planner`                                      | `--tasks <selector> [--feature <id>] [--mode <sequential\|parallel>] [--keep-going] [--auto] [--agent <inline\|auto\|name>] [--json] [--wrap] [--next] [--continue] [--worktree [<name>]] [--no-summary] [--defer-gate]`                      |
+| 13a | parallel   | `dev-parallel`      | `Skill()`         | `sp:parallel-execution`                                                            | `--tasks <selector> [--feature <id>] [--mode <fan-out\|review-panel\|investigation>] [--agent <inline\|auto\|name>] [--json] [--defer-gate]`                                                                          |
 | 14  | wrap       | `dev-wrap`          | `Skill()`         | `spur workflow run` (wrapup-pipeline)                                              | `<wbs> [--agent <inline\|auto\|name>] [--auto] [--merge] [--dry-run]`                                                                                                                                 |
 | 15  | wrapall    | `dev-wrapall`       | `Skill()`         | `spur workflow run` (wrapup-pipeline)                                              | `[--since <iso>] [--feature <id>] [--status <s>] [--agent <inline\|auto\|name>] [--auto] [--merge] [--dry-run]`                                                                                        |
 | 16  | idea       | `dev-idea`          | `Skill()`         | inline driver (`idea-pipeline`) or async workflow                                  | `"<idea>" \| --from-file <path> [--skip-design] [--agent <inline\|auto\|name>] [--auto]`                                                                                                                              |
@@ -165,18 +166,29 @@ must not be changed without updating the backing skill.
 
 #### Execution summary
 
-Default on for full-mode `dev-run` and `dev-runall`; `--no-summary` skips it. At command start record
-`SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ)`. When the run settles (done, failed or paused), write each run's
-`spur workflow progress <run-id> --json` to `$TMPDIR/<run-id>-progress.json` and print, verbatim under an
-`### Execution summary` heading:
-`node "$(superskill script path sp run-summary.mjs)" --since "$SINCE" --progress <file> --markdown`
-(`dev-runall`: one `--progress <wbs>=<file>` per attempted run). One file renders one row per state visit;
-several render one row per run; a `driver overhead` row carries host work outside every stage window so rows
-sum to `Total` (omitted when parallel runs overlap). Columns: Stage | Status | Time | Wait | Tool calls |
-Token (total / non-cached) — total counts every input class plus output; non-cached drops cache reads.
-Stage windows with no host transcript record (subprocess executors) render `n/a`, never 0. The summary is
-reporting only: a failure prints `Execution summary: n/a (<reason>)` and never changes the run's outcome.
-Not printed for `--mode implement` (no workflow run).
+Produced by the run's own close (1146 R1), not by a trailing step: `inline-run-setup --close` writes
+`.spur/run/<runId>-summary.md` + `.json` and reports `summaryFile` in its stdout JSON. The driver's only
+job is to print that file's contents under an `### Execution summary` heading, and to pass `--no-summary`
+through to `--close`. `--no-summary` is a `--close` flag: anywhere else it is a usage error.
+
+`/sp:dev-runall` shows one summary per run — each produced by that run's own close, so each window is its own
+`runs.started_at` → close time and no block reuses a batch-wide window — plus one batch roll-up:
+
+```
+node "$(superskill script path sp run-summary.mjs)" --rollup <runId>-summary.json --rollup <runId2>-summary.json
+```
+
+which renders one row per run (that run's own Total) and a bold total of the sums; when run windows overlap it
+also states the wall span from the first start to the last end.
+
+Columns: Stage | Status | Time | Wait | Tool calls | Token (total / non-cached) — total counts every input
+class plus output; non-cached drops cache reads. The actor split under the table partitions the same window —
+operator wait (with its longest single wait), model, shell, subagent, other tools and idle — and those rows sum
+exactly to the window; gate time is shown as an informational `of which gate` row sourced only from this run's
+check receipt (`receipt.runId === runId`), otherwise `n/a (<reason>)`. Any value with no source renders
+`n/a (<reason>)`, never 0. The summary is reporting only: a failure prints
+`Execution summary: n/a (<reason>)` and never changes the run's outcome. Not printed for `--mode implement`
+(no workflow run).
 
 ### 5. refine
 
@@ -441,11 +453,20 @@ gate commands, pending questions and approval requirements.>
   Report the new task WBS and file path; the task lands at `todo`, ready for `/sp:dev-refine`.
 
 - **Delegation:** `Skill(skill="sp:brainstorm", args="dev-brainstorm --context <decision-tree> --options <n>")`
+- **Scope boundary:** brainstorm never charts a multi-session map. A foggy destination stops the run with a recommendation to use `/sp:dev-find-way` (§ 12a).
+
+### 12a. find-way
+
+- **Purpose:** Wayfinding — chart a multi-session investigation map for a foggy destination (`<idea>`), or resolve exactly one ticket of an existing map (`<feature-id> [<wbs>]`).
+- **Isolation (mandatory):** every invocation runs in a git worktree + branch per [execution-batch.md § Worktree isolation](execution-batch.md#worktree-isolation---worktree-name) as a run of one — marker `command: dev-find-way`, `selector` `chart:<slug>` or `<feature-id>:<wbs>`, branch `sp/wayfind-<slug|wbs>-<short-id>`. Omitted `--worktree` equals bare `--worktree` (create); `--worktree <name>` adopts. No in-place or branch-switch mode.
+- **Parallel sessions:** frontier selection excludes tickets held by other `dev-find-way` markers (`active`/`retained`) in the invoking tree's `.spur/run/`, because a `wip` claim is invisible outside its worktree until the merge.
+- **`--wrap`:** work mode only — `/sp:dev-wrap <wbs>` inside the worktree after the ticket reaches `done`, before the WT-3b commit; skipped with a reason in chart mode.
+- **Delegation:** `Skill(skill="sp:wayfinder", args="$ARGUMENTS")` inside the worktree.
 
 ### 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` **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. `--no-summary` skips the [execution summary](#execution-summary) printed after the batch report (one row per attempted run).
+- **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> --fix --json` then `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` and `L4.verifying-incomplete-tasks` (expected pre-run states of a not-yet-run or reopened feature) are reported verbatim but do not abort — the non-aborting set is `NON_ABORTING_PREFLIGHT_CODES` in `plugins/sp/scripts/batch-preflight.ts` and `--fix` repairs are listed under `autoRepairs` — 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. `--no-summary` skips the [execution summary](#execution-summary) printed after the batch report (one row per attempted run).
 - **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`).

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

@@ -0,0 +1,68 @@
+---
+name: execution-batch-continuation
+description: "--continue resume of an interrupted batch (task 1128 split): original frozen identity re-binding (BC-1), checkpoints-as-hints reconciliation (BC-2) and ordering/write-ownership/terminal-mix rules (BC-3). Read it with --continue."
+see_also:
+  - execution-batch
+  - execution-workflow
+---
+
+## Batch continuation (`--continue`) — identity binding + checkpoint reconciliation (task 0919)
+
+`--continue` resumes an interrupted batch against the batch's **original identity** — never
+whatever a fresh selector resolution or a newer unrelated checkpoint would suggest.
+
+### BC-1 — Re-bind the original frozen identity (R1; AC1/AC5)
+
+Resume identity comes from persisted batch artifacts, in priority order:
+
+1. **WT-3 marker** (worktree batches): the marker's `command` + `selector` and worktree
+   name/branch re-derive the original launch (the WT-6 fallback already resolves this way).
+2. **Persisted batch report** (`.spur/run/worktree-<marker-id>-batch-report.md`, or the
+   invoking-tree Step 5 report of a non-worktree batch): its `Plan:` row IS the frozen ordered
+   membership — the resumed loop iterates exactly those WBS rows.
+
+Re-running the selector is a **validation, not a re-definition**: tasks that newly match the
+selector but are absent from the frozen plan are reported `not-admitted` and never executed —
+freshly listed tasks do not join a resumed batch implicitly. A frozen task whose dependencies
+changed after freeze may invalidate its admission: report `blocked (admission invalidated —
+re-plan required)` and stop for operator decision. The authorized frozen set is never silently
+rewritten (Design).
+
+### BC-2 — Checkpoints are hints (R2; AC2)
+
+Do **not** pick the resume point by mtime alone: `ls -t … | head -1` over `.spur/memory/sessions/`
+is identity-blind, so an unrelated later session (different feature or task) must not become
+authoritative. Select candidate checkpoints by identity first, newest first within the match:
+
+- frontmatter `workflow` is `task-pipeline` (or the batch's own workflow), and
+- `feature_id` equals the batch's feature selector, or `task_wbs` is a member of the frozen plan.
+
+Checkpoints matching neither rule are ignored regardless of recency. A matched checkpoint only
+**hints** where the loop left off (`phase`, `next_action` — surface them to the operator); the
+driver then reconciles against authoritative state before skipping or repeating any task:
+
+- **Skip** requires ALL of: task file status `done` AND a persisted PASS verdict artifact
+  (`.spur/run/<wbs>-verdict.json`, or the worktree-persisted
+  `.spur/run/worktree-<marker-id>-verdicts/<wbs>-verdict.json`) consistent with the task's
+current metadata. Anything less is not a valid skip.
+- **Stale or mismatched evidence** — checkpoint claims done but the verdict artifact is missing,
+  the task file moved backwards, or the recorded `source_commit`/`digest` no longer matches —
+  yields outcome `recheck`: re-run that task's pipeline. When reconciliation cannot proceed
+  safely (lost worktree, unresolvable marker), report `blocked` with the reason. Never treat an
+  unverified claim as done.
+
+### BC-3 — Ordering, write ownership, terminal mix, evidence (R3/R4; AC3/AC4)
+
+Sequential dependency-correct execution remains the default; opt-in `--mode parallel` keeps the
+existing proven-independence requirements with one writer per tree (Step 3). Mixed terminal
+results resume under the unchanged failure policy (Step 4). The Step 5 report keeps per-task
+outcomes distinct — `done | failed | blocked | skipped | not-attempted` plus the resume-only
+`recheck` and `not-admitted` — and the batch verdict stays `halted`/`aborted`: a resumed,
+partially-complete batch is never reported `clean`. Worktree evidence survives cleanup via the
+invoking-tree persistence in Step 5 (task 0720 R3); a persistence failure routes to **WT-5**
+(retain tree + branch), so partial outcomes are never silently lost and never read as a completed
+batch.
+
+See [cross-cutting.md](cross-cutting.md) § "Session Checkpoint Convention" for the canonical
+frontmatter fields and the per-task owner-mismatch semantics
+(`packages/app/src/workflow/checkpoint-contract.ts`).

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

@@ -0,0 +1,194 @@
+---
+name: execution-batch-report
+description: "Batch end of the driver loop (task 1128 split): the Step 5 structured Batch Report template, the zero-task rule, the worktree evidence-persistence contract, and Step 6 Batch wrap (--wrap/--next) including the guarded close-out commit. Read it when Step 5 runs; the loop itself stays in execution-batch.md."
+see_also:
+  - execution-batch
+  - execution-workflow
+---
+
+# Batch report and batch wrap
+
+Read at Step 5 and once at batch end (task 1128 R1).
+
+## Step 5 — Batch report (R5.2)
+
+When the batch finishes — clean (all `done`), halted (default failure policy), parked (`paused`:
+one or more tasks sit on an operator question (escalate, 0933) or an approval gate), or aborted
+(cycle / unknown selector) — emit a structured report. The report is the orchestrator's sole
+output; it does not mutate the corpus (the pipeline's `record` step already wrote per-task
+results). A `paused` task is non-terminal — the report marks it `paused` (never `done`) and names
+the resume command. Unless `--no-summary`, follow it with the measured
+[execution summary](dev-operations.md#execution-summary), one `--progress <wbs>=<file>` per attempted run.
+
+```
+## Batch Report — <selector>
+
+**Selector:** <value>
+**Plan:** <n> tasks (ordered: <wbs-list>) · <m> blocked · <p> not-attempted
+**Mode:** stop-the-batch | --keep-going | --auto
+**Verdict:** clean | halted | aborted
+
+| WBS | Status | Reason |
+|-----|--------|--------|
+| 0040 | done | — |
+| 0042 | failed | verify verdict PARTIAL (see .spur/run/0042-verdict.json) |
+| 0050 | not-attempted | batch halted after 0042 (stop-the-batch) |
+| 0051 | skipped | dependency 0040 failed (--keep-going) |
+| 0060 | blocked | unmet out-of-set dep: 0099 is wip |
+
+**Next:** <one-line action — pick up halted run / resolve 0099 / all green, feature H1 complete>
+
+**Excluded from wrap** (only under `--wrap`/`--next`, when some batch tasks are not `done`):
+
+```
+| WBS | Status | Recovery |
+|-----|--------|--------|
+| 0042 | failed | C6 recovery: /sp:dev-run 0042 (residual report: .spur/run/0042-residual-report.md) |
+| 0050 | not-attempted | /sp:dev-next 0050 |
+```
+
+A task with a residual report (failing `residual-sweep` check in its verdict artifact) uses the
+C6 recovery line (re-run the pipeline); every other excluded task uses the next-router A-row
+command for its status (F96 task 0952 R2).
+
+The per-task outcome vocabulary: `done` | `failed` | `blocked` | `skipped` | `not-attempted`,
+plus the resume-only `recheck` (stale/mismatched evidence — pipeline re-run), `not-admitted`
+(post-freeze selector match, never executed — task 0919 BC-1/BC-2), and the parallel-only
+`integration-conflict` (rebase conflict retained for manual integration — task 0931 R4,
+[§ Parallel isolation](#parallel-isolation---mode-parallel)).
+The batch verdict: `clean` (all attempted tasks `done`) | `halted` (a failure stopped the batch) |
+`aborted` (cycle or selector error before any run).
+
+**Zero-task rule (task 0701 R7b).** A selector that resolves to an **empty set after the status
+filter** is an `aborted` verdict (`aborted (empty set after filter)`), matching dev-operations.md
+§5a. Under `--worktree`, **WT-2 is skipped entirely**: no worktree is cut and no WT-3 marker is
+written for a batch with nothing to run. The early-exit report carries zero per-task rows,
+`Steps: 0 derived, 0 executed`, and the `aborted` verdict; no WT-3b commit step and no WT-4/WT-5
+terminal action runs. A contract test pins this
+(`plugins/sp/tests/dogfood-testing/execution-batch-contract.test.ts`).
+
+**Evidence persistence (worktree batches — task 0720 R3).** Copy-out is mandatory.
+A worktree batch's Step 5 report, verdict artifacts, and the batch's own
+`.spur/run` records live in the worktree while the batch runs — exactly the tree
+create-mode WT-4 deletes. Before any WT-4 removal, persist them into the **invoking** tree, which
+survives removal:
+
+- Write the emitted batch report to `.spur/run/worktree-<marker-id>-batch-report.md`.
+- Copy each attempted task's `.spur/run/<wbs>-verdict.json` from the worktree to
+  `.spur/run/worktree-<marker-id>-verdicts/<wbs>-verdict.json`.
+- Make the report's per-task verdict references use those persisted invoking-tree paths, not the
+  worktree-local paths that removal deletes.
+
+Evidence persistence precedes destructive cleanup: a persistence failure (unreadable verdict file,
+disk-full, missing directory) routes to **WT-5** — the worktree and branch are retained so a green
+batch can never destroy its own evidence. Reuse mode retains its operator-owned tree but still
+persists the Step 5 report under the invoking tree; the reused tree's `.spur/run/` remains the live
+copy while that tree lives on. The per-run provenance — the worktree DB's run/action rows and the
+`.spur/memory/runs/<runId>.md` + `.state.json` records — is persisted mechanically by WT-4a's
+`inline-run-setup.ts --persist-out --from <worktree> [--task-file <merged-task>]...` call,
+not by hand.
+
+**Stage records are worktree-local too (0948 R9, E7 Finding 5; persisted by 0975 R1).** Each task's
+own per-stage run record (`.spur/memory/runs/<runId>.md` + `.state.json`) and the worktree DB's run rows are
+written inside the worktree and **are removed with it** in create mode — the E7 batch lost exactly
+this evidence. Copying them out is no longer a manual audit-time duty: WT-4a (create-mode block
+below) runs `inline-run-setup.ts --persist-out --from "$WT_PATH"` **before** WT-4b holder cleanup,
+which copies the run/action/phase/transition/workflow-state rows and both record files into the
+invoking tree.
+
+**Cited evidence rides the same call (0984 R1/R2).** The driver forwards each merged task file with
+repeatable `--task-file <path>` (paths resolved in the invoking tree after the FF merge, e.g.
+`spur task show <wbs> --json` → `.filePath`), and persist-out then copies/verifies every literal
+`.spur/run/<file>` that file cites — WBS verdicts, check receipts, test-gate logs, run-ID records —
+so a merged task file never anchors a path that died with the tree. Abbreviated references
+(`fadca099-…`, `run-*-ac87.log`, `{batch-report.md,…}`) are not literal files and carry no
+obligation; neither do root-qualified paths (`knowledge-kit/.spur/run/…`, `/abs/.spur/run/…`),
+which cite another project's evidence — cite foreign run artifacts that way, never bare. A citation missing in BOTH trees, a divergent cited file (never overwritten — reconcile
+by hand), an unreadable task file, or more than 64 distinct cited files fails the pass → WT-5.
+
+**Durable planes ride it too (E71).** Persist-out copies canonical task verdicts, feature run/latest receipts, nested run artifacts and owned sessions before teardown. Artifact and task-run-link rows are exported with run rows, and stored path references are redirected to the invoking tree. Conflicting or unreadable **owned** retained evidence refuses teardown. A divergent copy of evidence a forwarded task does **not** own (its WBS is not a forwarded task's and its receipt `runId` is not a worktree run row) is `foreign-divergent` (1139 R5): it is skipped, reported as `evidenceSkipped[{name, reason:'foreign-divergent', newer:'invoking'|'worktree'}]`, and the invoking-tree copy is never overwritten — another task's newer verdict can no longer block this batch's teardown. A divergent **owned** file still fails with `durable evidence conflicts`. `persist-out-check` accepts the same foreign-divergent set from the success JSON and does not recompute it.
+
+**Owned evidence rides it too (1012).** With at least one `--task-file`, persist-out also treats as
+copy obligations the worktree's `.spur/run/` direct children named `<wbs>-…` (the WBS is each
+forwarded task file's leading four digits before `_`) or `<runId>-…` (every run row in the worktree
+DB, whichever task it ran) — `<wbs>-verdict.json`, check receipts, route reasons — whether or not
+the task file cites them. They join the cited set: same copy / byte-identical no-op /
+divergent-refuse handling. The 64-file cap bounds citations alone; owned names are bounded per
+owner (each `<wbs>-` / `<runId>-` prefix gets its own 64-file budget, task 1034), so the bound
+scales with the batch and one runaway owner refuses by name before any write. `<runId>.md` /
+`<runId>.state.json` stay with the record copy (a conflict is reported and the delegate refuses teardown). Files
+matching neither a citation nor an ownership prefix are left behind. An absent worktree `.spur/run/`
+means nothing is owned; any other listing failure (not a directory, permission denied) fails the
+pass before the invoking tree is written → WT-5. Without `--task-file` nothing is enumerated.
+
+The shapes are pinned (task 0975 R1; `record-missing`, citation behavior per 0984; `evidenceSkipped` per 1139 R5): idempotent on re-persist;
+success exits 0 printing
+`{"ok":true,"persisted":<n>,"skipped":[{"id":<run-id>,"reason":"id-exists"|"external-key-conflict"|"record-conflict:<file>"|"record-missing:<file>"|"cited-directory:<name>"|"cited-symlink:<name>"|"cited-non-file:<name>"}],"evidenceSkipped":[{"name":<file>,"reason":"foreign-divergent","newer":"invoking"|"worktree"}]}`
+(`evidenceSkipped` is omitted when empty; the same object is written to `<invoking-tree>/.spur/run/persist-out.json` for `persist-out-check` to read)
+— an `external-key-conflict` skip leaves the target run unchanged **and fails the pass (1049)**: the delegate exits 1 printing `{"ok":false,"error":…}` naming the skipped source run ids, because that (workflow, external key) identity already belongs to a different receiving run — the batch was not persisted, so reconcile the source worktree by hand (it stays the provenance owner of record) before any teardown: auditable reconciliation names the original archived DB snapshot and the skipped source run identities, verifies the archive by file hash and by merged-commit ancestry of the source branch, and treats any residual deletion as explicit operator-authorized cleanup under the strict canonical evidence rules above. Task 1149 R1 grades a terminal duplicate lifecycle row (`task-lifecycle`/`feature-lifecycle`) as `external-key-conflict-bookkeeping` (non-fatal), so guarded transitions driven inside the worktree do not block teardown; the receiving lifecycle row is reconciled automatically during persist-out. An `id-exists` replay repairs missing owned artifacts and task links without duplicating them. A
+`record-conflict:<file>` never overwrites a divergent invoking-tree record and causes the delegate to exit 1, retaining the worktree. A
+`record-missing:<file>` skip is a known `task-lifecycle`/`feature-lifecycle` row with no record file
+at all (its inserted DB row still counts in `persisted` — 0984 R5). Any failure
+exits 1 printing `{"ok":false,"error":<message>}` (a worktree DB run id that is not a single safe
+filename component is rejected before any target write). Any persist-out failure
+routes to **WT-5** — worktree and branch retained — the same copy-out-first contract as the
+verdict persistence above. After a green persist-out, `spur workflow progress --json` in the
+invoking tree shows the merged run `done` with its per-action rows.
+
+**Batch roll-up (1146 R3).** After the last run closes, print one `### Execution summary` block per run
+(each from that run's own `summaryFile`, so each window is its own `runs.started_at` → close time), then
+the batch roll-up built from the per-run files:
+
+```bash
+node "$(superskill script path sp run-summary.mjs)" --rollup <runId>-summary.json --rollup <runId2>-summary.json
+```
+
+One row per run carrying that run's own Total, a bold total of the sums, and — when run windows overlap —
+a wall-span line from the first start to the last end. No run block reuses a batch-wide window.
+
+## Step 6 — Batch wrap (`--wrap` / `--next`) (F96 task 0952 R1)
+
+Run **once for the batch**, after the Step 5 report — never per task (dev-operations.md §runall
+agrees; the old "per task" flag-row wording in dev-runall.md was a contradiction, now fixed).
+
+The wrap receives only what it would accept:
+
+1. `vars.tasks` = the JSON-encoded array of batch WBS whose terminal status is `done`. A task that
+   is `failed`/`blocked`/`skipped`/`not-attempted`/`recheck`/`not-admitted` is **excluded** —
+   `wrapup task-resolve` refuses non-done members (wrapup-steps.ts task-resolve), so the driver
+   simply stops handing the wrap tasks it would refuse.
+2. `vars.feature` = the batch feature **only when every task in the frozen batch is `done` or
+   `cancelled`**. Otherwise omit it and print `feature lifecycle not advanced: <n> task(s)
+   unfinished` — advancing a feature while some of its batch tasks are unfinished would overstate
+   completion. Learnings/metrics capture still happens for the done subset.
+3. When the done subset is **empty**, skip the wrap entirely with the reason (e.g. `batch wrap
+   skipped: no done tasks`) instead of invoking wrapup-pipeline on an empty set.
+
+**Repo-wide tripwire (1037).** After the doc-sync exits converge, the pipeline's `doc-tripwire` hop
+runs the TRUSTED CONFIG ONLY `docTripwireCmd` over the still-uncommitted wrap diff before
+metrics-record. The default probes `package.json` for a `test-repo-wide` script and runs
+`bun run test-repo-wide` only when it is declared (a no-op in other projects), so the batch driver
+passes no extra vars. Batch callers override it like any wrap var (`docTripwireCmd` in `--vars`);
+an empty string disables the check while still recording PASS. A FAIL routes the wrap to `failed`
+with already-written learnings/docs preserved — fix the flagged working-diff violation and re-run
+the wrap.
+
+Filtering lives here, in the batch driver — no change to wrapup-pipeline.yaml or wrapup-steps.ts;
+the wrap's refusal of non-done tasks remains the hard invariant.
+
+**Close-out commit (1129 R2/R5).** In sequential mode the wrap's writes (learnings, metrics,
+doc-sync) land in the invoking tree and are committed as ONE close-out commit after the wrap exits.
+Stage them through the guard — never a free-form `git add` — so a concurrent writer's file cannot
+ride into the close-out commit (incident `36f274590`). `$RUN_ID` is the id Step 3 fixed before
+`commit-guard start` (execution-batch.md § Step 3); an unset id makes the guard exit 1 — fail closed:
+
+```bash
+GUARD=plugins/sp/scripts/commit-guard.ts; [ -f config/plugin-scripts.json -a -f "$GUARD" ] || GUARD="$(superskill script path sp commit-guard.mjs 2>/dev/null)"
+bun "$GUARD" check --run "$RUN_ID"                    # 1129 R3: a non-empty foreign list goes in the batch report
+bun "$GUARD" stage --run "$RUN_ID" -- <files the wrap wrote> \
+  || { echo "close-out halt: commit-guard refused a path (foreign, unmerged or conflict-marked); nothing committed" >&2; exit 1; }
+git commit -m "chore(wrap): <command> <selector> close-out writes"
+```
+
+> **Forbidden:** `git add -A` and `git add .` — here as in every driver commit step. In the
+> worktree batch the same rule rides in the WT-3b block above.