@gobing-ai/spur 0.3.99 → 0.4.1

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

@@ -40,8 +40,9 @@ each would be scope creep for one-liner procedures.
 
 > **`dev-review-session`** is not in this table. It is a thin `Skill()` wrapper over
 > **`sp:session-review`** for an immediate, inline review of the active conversation. Report-only
-> is the default; `--triage` applies pure-doc / one-to-two-line fixes and files remaining actionable
-> findings as implement-ready tasks through the task CLI. It launches no workflow or agent and
+> is the default; `--fix auto` (alias `--triage`) applies pure-doc / one-to-two-line fixes and files
+> remaining actionable findings as implement-ready tasks through the task CLI; `--fix all` fixes
+> every actionable finding inline and files none. It launches no workflow or agent and
 > imports no history. Use it before the active session ends; use history-anatomy for ended sessions,
 > cross-agent windows, trends, or quantitative forensics.
 
@@ -72,20 +73,21 @@ each would be scope creep for one-liner procedures.
 | 2   | review     | `dev-review`        | `Skill()`         | `sp:code-verification` (`review`) + `sp:functional-review` + `sp:code-improvement` | `[--tasks <selector> \| --feature <id>[,<id>] \| --scope <path>[,<path>]] [--agent <inline\|auto\|name>] [--focus <dims>] [--triage] [--worktree [<name>]] [--auto]`                                                                                              |
 | 3   | verify     | `dev-verify`        | `Skill()`         | `sp:code-verification` (`verify`)                                                  | `<wbs> [--agent <inline\|auto\|name>] [--fix <none\|blockers-first\|all>] [--focus <lens>] [--bdd] [--auto] [--force] [--next] [--skip-shippable]`                                                     |
 | 3a  | verifyall  | `dev-verifyall`     | `Skill()` → agent | `sp:spur-dev` (`verifyall`)                                                        | `--tasks <selector> [--feature <id>] [--agent <inline\|auto\|name>] [--fix <none\|blockers-first\|all>] [--focus <lens>] [--bdd] [--auto] [--force] [--next] [--json] [--skip-shippable] [--worktree [<name>]]` |
-| 4   | run        | `dev-run`           | `Skill()`         | `sp:spur-dev` (`run` / `implement`)                                                | `<wbs> [--mode <full\|implement>] [--agent <inline\|auto\|name>] [--auto] [--next] [--wrap] [--continue] [--worktree [<name>]]`                                                                                              |
+| 4   | run        | `dev-run`           | `Skill()`         | `sp:spur-dev` (`run` / `implement`)                                                | `<wbs> [--mode <full\|implement>] [--agent <inline\|auto\|name>] [--auto] [--next] [--wrap] [--continue] [--worktree [<name>]] [--no-summary]`                                                                                              |
 | 5   | refine     | `dev-refine`        | `Skill()`         | `sp:spur-dev` (`refine`)                                                           | `<wbs> [--focus <mode>] [--description <text>] [--depth <standard\|ready>] [--agent <inline\|auto\|name>] [--auto] [--next]`                                                                           |
 | 5a  | refineall  | `dev-refineall`     | `Skill()`         | `sp:spur-dev` (`refineall`)                                                        | `--feature <id> \| --tasks <selector> [--focus <mode>] [--description <text>] [--depth <standard\|ready>] [--agent <inline\|auto\|name>] [--auto] [--keep-going] [--status <s>] [--json] [--worktree [<name>]]` |
 | 6   | plan       | `dev-plan`          | `Skill()`         | inline driver (`idea-pipeline`) or async workflow                                  | `"<description>" [--feature <id>] [--parent <feature-id>] [--skip-design] [--agent <inline\|auto\|name>] [--auto]`                                                                   |
 | 7   | docs       | _(no thin wrapper)_ | `Skill()`         | `sp:doc-evolve`                                                                    | `"<change description>"`                                                                                                                                                                               |
-| 8   | changelog  | `dev-changelog`     | `inline`          | git log + conventional-commit grouping                                             | `[--since <ref>] [--until <ref>] [--version <ver>]`                                                                                                                                                    |
+| 8   | changelog  | `dev-changelog`     | `inline`          | git log + conventional-commit grouping                                             | `[<file>] [--since <ref>] [--until <ref>] [--version <ver>]`                                                                                                                                            |
 | 9   | gitmsg     | `dev-gitmsg`        | `inline`          | bounded diff capture → concern grouping → conventional commit                      | `[--commit] [--squash] [--all] [--scope <path>]`                                                                                                                            |
 | 10  | fixall     | `dev-fixall`        | `inline`          | lint + test fix loop                                                               | `[<validation-command>] [--max-retry <n>] [--scope <path>] [--gate-log <path>] [--findings <anchors>]`                                                                                                 |
 | 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>]]`                      |
-| 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]`                                                                                                                              |
@@ -155,13 +157,39 @@ must not be changed without updating the backing skill.
 ### 4. run
 
 - **Purpose:** Run a task through the execution pipeline (full) or execute a single pipeline step (implement).
-- **Inputs:** `<wbs>` (required). `--mode <full|implement>` selects the execution mode. `implement` invokes `sp:code-implementation` inline by default. Interactive `full` resolves the selector uniformly (task 0687): omit ≡ explicit `--agent inline`; full mode reads `task-pipeline.yaml` and drives its actions/guards in the host session — host-controlled and non-subprocess, with 0508 eligibility applying to the resolved-inline selector (eligible `agent.run` stages dispatch once to a native subagent, host fallback)). `--agent auto`, a name, or headless invocation launches the workflow subprocess. `--agent <inline|auto|name>` selects the execution surface (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips the HITL approve gate / confirmations and propagates down the `--next` chain. `--next` controls chaining only and never changes the mode; a pipeline implement stage must invoke `/sp:dev-run <wbs> --mode implement`. On implement success with `--next`, transition `todo → wip → testing` through the FSM (guards honored — no `--no-lifecycle`) + chain to `/sp:dev-verify <wbs> --auto --next`. On a guard failure, stop as review-pending. **Partial-deliverable rule:** if the task ships only part of its requirements (e.g. an R1/R2 split with the rest in a follow-up task), the `## Solution` section must state that explicitly and the verify verdict will record the scope. `--worktree [<name>]` runs the full pipeline inside an isolated git worktree (create or reuse; FF-merge on success, retain on failure) — the batch lifecycle in [execution-batch.md § Worktree isolation](execution-batch.md#worktree-isolation---worktree-name) applied to a batch of one; rejected with `--mode implement`. `--wrap` hands off to `/sp:dev-wrap <wbs>` after the main step; the `--agent` selector is preserved into that handoff when supplied (omission remains omission), and the wrap hop reports its own trigger-3 subprocess override per the wrap contract.
+- **Inputs:** `<wbs>` (required). `--mode <full|implement>` selects the execution mode. `implement` invokes `sp:code-implementation` inline by default. Interactive `full` resolves the selector uniformly (task 0687): omit ≡ explicit `--agent inline`; full mode reads `task-pipeline.yaml` and drives its actions/guards in the host session — host-controlled and non-subprocess, with 0508 eligibility applying to the resolved-inline selector (eligible `agent.run` stages dispatch once to a native subagent, host fallback)). `--agent auto`, a name, or headless invocation launches the workflow subprocess. `--agent <inline|auto|name>` selects the execution surface (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips the HITL approve gate / confirmations and propagates down the `--next` chain. `--next` controls chaining only and never changes the mode; a pipeline implement stage must invoke `/sp:dev-run <wbs> --mode implement`. On implement success with `--next`, transition `todo → wip → testing` through the FSM (guards honored — no `--no-lifecycle`) + chain to `/sp:dev-verify <wbs> --auto --next`. On a guard failure, stop as review-pending. **Partial-deliverable rule:** if the task ships only part of its requirements (e.g. an R1/R2 split with the rest in a follow-up task), the `## Solution` section must state that explicitly and the verify verdict will record the scope. `--worktree [<name>]` runs the full pipeline inside an isolated git worktree (create or reuse; FF-merge on success, retain on failure) — the batch lifecycle in [execution-batch.md § Worktree isolation](execution-batch.md#worktree-isolation---worktree-name) applied to a batch of one; rejected with `--mode implement`. `--no-summary` skips the [execution summary](#execution-summary) printed after a full-mode run. `--wrap` hands off to `/sp:dev-wrap <wbs>` after the main step; the `--agent` selector is preserved into that handoff when supplied (omission remains omission), and the wrap hop reports its own trigger-3 subprocess override per the wrap contract.
 - **Backing:** `sp:spur-dev` skill — `run` operation for the full pipeline (the spine drives it); `sp:code-implementation` competency skill for the implement step (the spine dispatches to it).
 - **Modes:**
   - **`full`** (default): Drive the full pipeline — precheck → implement → test → review → approve(HITL) → verify → record → done. Interactive omit/inline uses [inline-pipeline-driver.md](inline-pipeline-driver.md) (host-controlled; eligible stages may use a native subagent); explicit/headless executor selection invokes `spur workflow run task-pipeline.yaml --vars '{"wbs":"<wbs>"}'` (with `profile: auto` when `--auto`). Both monitor/surface HITL and preserve the YAML gates. `--next` never changes this mode.
   - **`implement`** (explicit `--mode implement` only): Execute only the implement step. Read the task's `## Requirements` / `## Design` / `## Plan`, write the code that satisfies them, author the `## Solution` change-map section (file:line + what/why per changed file) via `spur task update <wbs> --section Solution --from-file`. This is the implement step the pipeline calls — it is NOT the pipeline driver. With `--next`: on success, transition `todo → wip → testing` through the FSM (guards honored — no `--no-lifecycle`) + chain to `/sp:dev-verify <wbs> --auto --next`; on a guard failure, stop as review-pending. **Partial-deliverable rule:** if the task ships only part of its requirements (e.g. an R1/R2 split with the rest in a follow-up task), the `## Solution` and `## Review` sections MUST carry a `⚠️ PARTIAL` marker naming the deferred part and the follow-up WBS — see `plugins/sp/commands/dev-run.md` → "Section ownership".
 - **Delegation:** `Skill(skill="sp:spur-dev", args="run-inline $ARGUMENTS")` for interactive full omit/inline (resolved-inline semantics, task 0687); `Skill(skill="sp:spur-dev", args="run $ARGUMENTS")` for explicit/headless full mode; `Skill(skill="sp:code-implementation", args="$ARGUMENTS")` for implement mode.
 
+#### Execution summary
+
+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
 
 - **Purpose:** Refine a task's requirements via structured Q&A — clarify scope, elicit missing details, tighten acceptance criteria before execution. Optional **implement-ready** depth freezes Design/Requirements/Plan so another agent can implement without inventing design, and is also the path for **evaluating and correcting an existing task** — a review-triage filing, a stale backlog capture, or any task whose claims and proposed fixes may no longer hold.
@@ -425,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.
+- **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`).
@@ -519,7 +556,7 @@ is the procedure. The backing is a combination of git CLI, `spur` CLI, and agent
 ### 8. changelog
 
 - **Purpose:** Generate a structured changelog from git commits between two refs.
-- **Inputs:** `--since <ref>` (default: last tag), `--until <ref>` (default: `HEAD`), `--version <ver>` (default: auto-detect from latest tag).
+- **Inputs:** `<file>` (optional positional, e.g. `CHANGELOG.md`; default: stdout), `--since <ref>` (default: last tag), `--until <ref>` (default: `HEAD`), `--version <ver>` (default: auto-detect from latest tag).
 - **Backing:** `inline` — git log + conventional-commit grouping.
 - **Behavior:**
   1. Resolve `--since`: if not given, use the most recent tag (`git describe --tags --abbrev=0`). If no tags exist, use the repo root commit.
@@ -529,14 +566,10 @@ is the procedure. The backing is a combination of git CLI, `spur` CLI, and agent
   5. Format as markdown:
      - `keepachangelog` (default): `## [<version>] - <date>` header, then category headings per the keepachangelog convention — `### Added` / `### Fixed` / `### Changed` / `### Removed` / `### Other` — mapped from conventional-commit types.
      - `simple`: flat bulleted list grouped by type heading (`### feat`, `### fix`, …).
-  6. Print the changelog to stdout. If the operator wants it in `CHANGELOG.md`, they redirect or paste.
-  7. Verify the emitted section against git and close with one line: `Verification: HIGH|MEDIUM|LOW — <first failing check and deviation, or 'all checks passed'>`.
-     - **Coverage** — bullet count equals the commit count in `<since>..<until>`, and every short hash appears exactly once.
-     - **Mapping** — per-category bullet counts match the conventional-type counts (`feat`→`Added`, `fix`→`Fixed`, other recognized types→`Changed`, unrecognized→`Other`).
-     - **Header** — `[<version>] - <date>` matches the resolved `--version` (or detected tag) and the header date.
-     - **Citations** — a bullet that asserts API/library behavior or a version/dependency claim beyond its commit summary carries a source citation: an official docs URL, or a local `path:line` verified against the installed manifest/lockfile (`package.json`, lockfile, or the cited file). A commit hash is provenance for what shipped, not a citation for what the API/library does; an uncited claim is flagged inline on the bullet (`(uncited: <claim>)`) rather than silently dropped.
-     - **HIGH** — all checks pass with every API/library claim cited. **MEDIUM** — coverage intact but mapping or header deviates, or at least one API/library claim lacks a source citation. **LOW** — coverage broken (missing/duplicate hashes), the range cannot be reconciled against git, or a citation fails verification (dead URL, or a `path:line` that does not support the claim).
-- **Invariants:** Never mutates `CHANGELOG.md` directly — the command surface is stdout-only; writing it to a file (e.g. appending to `CHANGELOG.md`) is the operator's redirect choice, never the command's.
+  6. Emit: with `<file>`, insert the section into that file above its newest `## [` release heading (or after its title when none exists) and touch nothing else in the file; without `<file>`, print it to stdout.
+  7. Self-check before emitting: every short hash in `<since>..<until>` appears exactly once. Fix any miss or duplicate; do not report a verdict.
+  8. Reply in at most three lines: the range, bullet counts per category, and the output target.
+- **Invariants:** Output is derived from `git log` only. No quality gates — no lint/test/`spur-check`/rule runs, citation or manifest lookups, confidence ratings, or edits beyond the one inserted section. The file is left uncommitted.
 
 ### 9. gitmsg
 

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.