@gobing-ai/spur 0.4.0 → 0.4.2

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

@@ -23,7 +23,7 @@ The `Skill()` commands back onto six skills: `sp:spur-dev` (planning + execution
 `sp:code-verification` (SECUA review + traceability), `sp:parallel-execution` (fan-out / parallel batch),
 and `sp:brainstorm` (structured ideation). The `runall` operation (#13) is `sp:spur-dev`'s batch entry — it delegates the driver loop to the
 `sp:super-planner` agent (the batch orchestrator) per [execution-batch.md](execution-batch.md).
-`dev-parallel` (#13a) is the parallel counterpart. `dev-brainstorm` carries the two artifact exits — `--task` (one task) and `--feature` (validated
+Parallel task batches are `dev-runall --mode parallel|auto` (`dev-parallel` retired 2026-10-10). `dev-brainstorm` carries the two artifact exits — `--task` (one task) and `--feature` (validated
 feature with BDD AC; the front-half entry that hands off to `dev-plan`). The 4 `inline` commands
 cover git tooling and operational utilities that have no natural skill home — creating a skill for
 each would be scope creep for one-liner procedures.
@@ -84,9 +84,9 @@ 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\|auto>] [--concurrency <n>] [--keep-going] [--auto] [--agent <inline\|auto\|name>] [--json] [--wrap] [--next] [--continue] [--worktree [<name>]] [--no-summary] [--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 +165,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 +452,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,199 @@
+---
+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.
+**Under `--worktree` they land in the EXECUTION tree instead** and ride the branch as its own commit
+on `$BRANCH`: Step 6 runs before WT-4, so a close-out commit on the base ref would advance it and
+make the batch's own FF-merge impossible (the fresh base tip would no longer be an ancestor of the
+batch tip — the step that makes the close-out the report's own contradiction). The close-out commit
+is never a point on the base ref.
+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.