@gobing-ai/spur 0.3.64 → 0.3.66

package/plugins/sp/skills/session-review/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: session-review
+description: "Review the active coding-agent session: separate resolved from open issues with evidence, propose bounded improvements. With --triage, apply pure-doc / 1–2-line fixes inline and file the rest as one task. Triggers: review this session, wrap-up, triage findings."
+license: Apache-2.0
+version: 1.1.0
+metadata:
+  author: spur
+  platforms: "claude-code,codex,openclaw,opencode,antigravity,pi"
+  category: analysis-core
+  interactions:
+    - reviewer
+see_also:
+  - sp:history-anatomy
+  - sp:indexed-context
+  - sp:code-verification
+---
+
+# sp:session-review — Active Session Review
+
+Review the active coding-agent session while its conversation context is still available. Produce a
+compact, evidence-backed report of outcomes, resolved issues, remaining risks, and improvements.
+
+## When to use
+
+Use this skill immediately after focused operations when the operator asks what happened, what was
+resolved, or how the session could improve. Use imported-history analysis for ended sessions,
+cross-agent windows, recurrence, trends, or quantitative performance forensics.
+
+## Arguments
+
+| Argument | Description | Default |
+| --- | --- | --- |
+| `[focus]` | Question or operation to emphasize. It changes ordering, not evidence collection. | full active session |
+| `--triage` | Opt into bounded remediation after the report: apply direct fixes (pure docs / one-to-two-line fixes) inline, then file all remaining actionable findings as exactly one new task via the CLI-gated corpus surface. | off (report-only) |
+
+## Evidence boundary
+
+- Treat the active conversation as the primary evidence plane.
+- Verify each material claim with source evidence from the conversation or a read-only repository
+  check, and cite the exact result or path in the report.
+- Use read-only repository checks only when they confirm a material claim; prefer existing tool
+  results already visible in the session over rerunning commands.
+- Mark an issue **resolved** only when the session shows the symptom, root cause, applied resolution,
+  and verification evidence. Otherwise classify it as open or attempted.
+- Separate observation from inference. Label an unsupported causal explanation as a hypothesis and
+  name the confirmation needed.
+- State `not available` when compaction or missing output removed evidence. Never reconstruct it from
+  memory or claim a verification that did not run.
+
+## Triage mode (`--triage`)
+
+Report-only stays the default. With `--triage`, run the same evidence pass, then remediate in
+three buckets — never skip triage and start fixing from the raw findings list.
+
+1. **Triage every finding into exactly one bucket:**
+   - **Direct fix** — pure documentation work, or a one-to-two-line fix with obvious, local,
+     low-risk scope. Read the root cause first; a "one-liner" that needs design or touches a
+     shared write path is not direct.
+   - **Task** — real, actionable, and not already owned by an existing task. Deferred
+     requirements recorded inside their own task files are pointers, not duplicates.
+   - **Note** — pre-existing, environmental, or ownerless observations; report only.
+2. **Apply direct fixes inline** — smallest surgical diff, project style, and re-verify each
+   with the targeted check (lint / test / the exact command that exhibited the issue).
+3. **Create exactly one task** for the Task bucket through the CLI-gated corpus surface
+   (`spur task create`, then `spur task update <wbs> --section <s> --from-file` per section).
+   One task, not one per finding: each finding keeps its evidence, a suggested fix direction,
+   and an AC where verifiable. Exclude what direct fixes already resolved — say so in the task
+   Background instead.
+4. **Report** — add a Triage section: applied fixes (path + one-line what + verification) and
+   the created task WBS. The Resolved/Open tables keep their evidence rules unchanged.
+
+## Protocol
+
+1. **Resolve scope.** Review the active session from the operator's initiating request through the
+   latest result. Use `[focus]` only to rank relevant material.
+2. **Inventory outcomes.** List requested outcomes and classify each as completed, partial, blocked,
+   or not attempted. Collapse repeated attempts into one outcome.
+3. **Classify issues.** For every material issue, distinguish resolved, open, or attempted. Record
+   root cause only when the evidence boundary supports it.
+4. **Select improvements.** Keep at most three changes that would prevent meaningful recurrence.
+   Apply the placement rule in
+   [the environment-improvement mapping](../../references/environment-lens.md): automate with a
+   check when possible, place coding standards on the review path, and keep always-loaded steering
+   as navigation pointers.
+5. **Render the report.** Use the exact compact output contract below. Omit empty table rows, not
+   headings; write `None observed` when a section has no supported entry.
+
+## Output contract
+
+### Outcome
+
+State the overall result in one to three sentences, including partial or blocked scope.
+
+### Resolved issues
+
+| Issue | Root cause | Resolution | Evidence |
+| --- | --- | --- | --- |
+
+Evidence names the tool result, verification command, or concrete repository state visible in the
+session. Do not list ordinary implementation steps as issues.
+
+### Open issues and risks
+
+| Issue or risk | State | Evidence or confirmation needed |
+| --- | --- | --- |
+
+### Process and environment improvements
+
+For each supported proposal, name its owner surface, expected impact, verification method, and
+reversibility. Proposals remain report-only: apply no change and create no task.
+
+### Triage (only when `--triage` was passed)
+
+| Applied fix / created task | Bucket | What + verification |
+| --- | --- | --- |
+
+One row per applied fix and one per created task (with its WBS). Omit the section entirely when
+`--triage` was not passed.
+
+### Next actions
+
+List only actions needed to finish partial scope, confirm a hypothesis, or preserve a demonstrated
+improvement. Use `None` when the session is complete and no follow-up is justified.
+
+## Boundaries
+
+- Stay in the active host session. Do not delegate; a fresh context loses the evidence being reviewed.
+- Do not launch a workflow, import history, append indexed-context memory, perform baseline
+  comparison or recurrence classification, or emit a twelve-section forensic report; those belong
+  to imported-history analysis.
+- Report-only by default: do not create or update corpus items or edit files. The single exception
+  is `--triage` mode, which permits exactly two mutation classes — direct fixes from the triage
+  bucket, and the one triage task. Anything beyond that stays a proposal.
+- Do not turn a single low-impact observation into a new policy. Report it as a candidate until it
+  recurs or demonstrates a high-impact contract violation.
+
+## Platform notes
+
+On platforms without slash commands, invoke this skill directly before ending the active session.

package/plugins/sp/skills/spur-cli/references/tasks/verbs.md

@@ -54,7 +54,9 @@ frontmatter scalar.
   cancelled`. Two transitions run a target-aware `check` guard (§7.5): `wip→testing` →
   `spur task check <wbs> --as testing`; `testing→done` → `spur task check <wbs> --as done`
   (F92 R3 — each evaluates the transition target, so `testing→done` checks the `done` row).
-  A failing gate blocks the transition.
+  A failing gate blocks the transition. The `wip→testing` guard additionally requires a Solution
+  section citing concrete `file:line` evidence — a missing/unsubstantiated Solution is rejected with
+  `[invalid-solution]`.
 - **`--no-lifecycle`**: suppress lifecycle workflow *run record* creation (use inside pipeline runs
   to avoid orphaned nested lifecycle runs). **It is not a guard bypass** — the `wip→testing` and
   `testing→done` `check` gates above still run; the CLI evaluates them inline when the FSM guard
@@ -230,6 +232,10 @@ only the exact corpus path, with no basename-WBS fallback. Returns exit `1` if n
 
 ## `verdict <wbs>`
 
+There is **no `verify` verb**. The verify leg is three steps: the agent writes its structured
+evidence write-up to `.spur/run/<wbs>-verify-answer.txt`, then `spur task verdict <wbs>` derives
+the verdict artifact, then `spur task record <wbs>` lands it into the task.
+
 Derive a PASS / PARTIAL / FAIL / UNKNOWN verdict from a verify-step answer text file (the agent's
 structured evidence write-up). Replaces the pipeline's verify→record transition's previous grep/shell
 ladder (0108; ADR-022). On a readable answer, emits `.spur/run/<wbs>-verdict.json` (mkdir-p the

package/plugins/sp/skills/spur-cli/references/workflows.md

@@ -255,7 +255,7 @@ the operator accepts it, and never hot-edit a running workflow's shell in place.
 
 ```
 spur workflow validate <file> [--no-schema] [--json]
-spur workflow show      <file>
+spur workflow show      <file> [--format <mermaid|todo>] [--json]
 spur workflow run      <file> [--run-id <id>] [--vars <json>] [--dry-run] [--async] [--no-plan] [--quiet/--silent/--verbose] [--detail <level>] [--trace-file] [--no-log] [--steer] [--json]
 spur workflow continue [run-id] [--yes] [--answer <yes|no|cancel>] [--json]
 spur workflow cancel   <run-id> [--json]

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

@@ -234,6 +234,11 @@ or `args="refine <wbs>"` for task refinement, or `args="refineall --feature <id>
 batch refine under a feature (add `--depth ready` for implement-ready freeze). Use `spur agent run`
 for isolated LLM invocations within pipeline steps.
 
+**Argument parsing.** Split `$ARGUMENTS` into target + flags before dispatching. Unknown flags are
+not silently dropped: note them in the plan line, or stop (rule imported from `next-router`,
+task 0701 R3 — e.g. `--worktree` on `dev-refine` is undeclared, so it must be surfaced, never
+discarded).
+
 ### Codex / OpenClaw / OpenCode / Antigravity
 
 Run `spur` CLI via the Bash tool; parse `--json` output. Invoke this skill directly for

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

@@ -32,14 +32,17 @@ each would be scope creep for one-liner procedures.
 > backbone skill (which owns the 4-phase dogfood protocol, the live ledger, and the report template);
 > it does not map to a numbered dev-\* operation. See its command file and the backing skill for details.
 
-> **`dev-find-issue`** is not in this table. It is a thin `Skill()` wrapper over **`sp:issue-finding`**
->(session-log forensics report → optional CLI-gated fix task via `--create-task`). Hygiene /
->post-batch analysis — not a spine pipeline stage. Report-first (task 0556): the default run
->renders the `spur history report --mode forensics` data plane plus model-authored analysis and
->creates nothing; task creation is opt-in behind `--create-task` (`--use-history`/`--no-task` are
->removed). See `plugins/sp/commands/dev-find-issue.md` and
->`plugins/sp/skills/issue-finding/SKILL.md`. After a slow `/sp:dev-runall`, prefer
->`/sp:dev-find-issue [<topic>]` before re-running the batch.
+> **`dev-find-issue`** is not in this table. It is a thin `Skill()` wrapper over
+> **`sp:history-anatomy`** for daily/ad-hoc imported-history forensics: fixed twelve-section report,
+> baseline comparison, cache branch, independent validation, and atomic publication. It never
+> imports history or creates a task. See `plugins/sp/commands/dev-find-issue.md` and
+> `plugins/sp/skills/history-anatomy/SKILL.md`.
+
+> **`dev-review-session`** is not in this table. It is a thin `Skill()` wrapper over
+> **`sp:session-review`** for an immediate, inline, report-only review of the active conversation.
+> It launches no workflow or agent and performs no import, persistence, or mutation. Use it before
+> the active session ends; use history-anatomy for ended sessions, cross-agent windows, trends, or
+> quantitative forensics.
 
 > **`dev-find-conflict`** is not in this table. It is a thin `Skill()` wrapper over
 > **`sp:conflict-finding`** (authority-aware four-pillar semantic audit → optional confirmed,
@@ -233,7 +236,7 @@ must not be changed without updating the backing skill.
 - **Purpose:** Batch-refine a set of tasks (or all refine-eligible tasks under a feature) — resolve a set, topo-sort by dependencies, run per-task `refine`, emit a summary report. Planning-half counterpart of `verifyall` / `runall` for the just-in-time spec-completion gate. With `--depth ready`, batch **implement-ready** freeze before multi-agent implement or runall.
 - **Inputs:**
   - `--feature <id>` **or** `--tasks <selector>` (required — at least one). `--feature` is sugar for `--tasks feature:<id>` (shared selector grammar: explicit WBS list, `feature:<id>`, `ready`, status pseudo-list — [execution-batch.md](execution-batch.md) Step 1). If both are present, `--tasks` wins (one-line note in the report).
-  - Shared refine flags (passed through to each per-task refine): `--focus <mode>`, `--description <text>`, `--depth <standard|ready>`, `--agent <inline|auto|name>`, `--auto`, `--next`.
+  - Shared refine flags (passed through to each per-task refine): `--focus <mode>`, `--description <text>`, `--depth <standard|ready>`, `--agent <inline|auto|name>`, `--auto`.
   - Batch-only flags: `--keep-going` (continue independents after a failure; default halt), `--status <s>` (filter resolved membership; default **`backlog,todo`** — planning-side fill candidates), `--json` (machine-readable batch report).
 - **Backing:** `sp:spur-dev` skill, `refineall` operation (orchestrates; per-task body is the single-task `refine` operation — never a second refine implementation).
 - **Behavior:**
@@ -245,7 +248,7 @@ must not be changed without updating the backing skill.
   6. Emit a batch report (markdown or `--json`) that records `depth` once at the header.
 - **Per-task outcome vocabulary:** `refined` (synthesis wrote sections) | `SKIP` (already meets the active depth bar under `--auto`) | `failed` | `skipped` (dep failed under `--keep-going`) | `not-attempted` (halted) | `blocked` (unmet out-of-set dep).
 - **Batch verdict:** `clean` (all attempted tasks `refined` or `SKIP`) | `halted` (a failure stopped the batch) | `aborted` (cycle / unknown selector / empty set after filter).
-- **`--next` warning:** Passing `--next` chains **each** successful refine into `/sp:dev-run <wbs> --mode implement --auto --next`, which can balloon into implement+verify execution for every task. Prefer refineall without `--next`, then `/sp:dev-runall --feature <id>` for execution. Document the risk in the batch report header when `--next` is set.
+- **`--next` is not accepted** (dropped by feature H8, 2026-07-31 — see `plugins/sp/commands/dev-refineall.md` for the removal record). Chain execution explicitly: refineall, then `/sp:dev-runall --feature <id>`.
 - **`--auto` recommendation:** Batch refine without `--auto` requires per-task interactive Q&A and does not scale. Default operator path: `/sp:dev-refineall --feature <id> --auto`. For implement handoffs: `/sp:dev-refineall --feature <id> --auto --depth ready`.
 - **Delegation:** `Skill(skill="sp:spur-dev", args="refineall $ARGUMENTS")` → per task `Skill(skill="sp:spur-dev", args="refine <wbs> $SHARED_FLAGS")` (shared flags include `--depth` when set).
 

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

@@ -61,6 +61,7 @@ function normalizeArgs(raw: Args): Args {
 ```
 
 **Normalization rules (performed by the command layer before the skill sees $ARGUMENTS, or by the batch resolver):**
+
 - If `--feature FOO` is present and `--tasks` is absent, treat the effective selector as `feature:FOO`.
 - If both are present, `--tasks` wins (with a one-line note in the batch report).
 
@@ -101,7 +102,7 @@ bun run apps/cli/src/index.ts feature check <id> --strict --json
 kickoff** — the driver never re-queries `spur task list` to recompute membership mid-batch (R2.1).
 
 | Selector form | Regex / match | Resolution |
-|---|---|---|
+| --- | --- | --- |
 | Explicit WBS list | `^[0-9, ]+$` | Split on comma; validate each token is a 4-digit WBS; collect the explicit set. (R1.1) |
 | `feature:<id>` (via `--tasks` or `--feature <id>`) | literal `feature:` prefix or `--feature` flag | `spur task list --feature <id> --json`; collect `wbs` from each row. The `--feature` flag is sugar that becomes `--tasks feature:<id>` at the command layer. (R1.3) |
 | `ready` | literal `ready` | Resolve the union of `spur task list --status todo --json` + `spur task list --status backlog --json`, drop tasks with open children (R1.5, umbrella-parent exclusion below), then keep only tasks whose every `dependencies[]` entry resolves to `status == done` (via `spur task show <dep> --json | jq '{wbs, status, dependencies, feature_id}'` — R5 metadata-only). Report each excluded task with its unmet dependency. (R1.4) |
@@ -185,7 +186,7 @@ node "$(superskill script path sp batch-preflight.mjs)" \
 ```
 
 | Result | Batch action |
-|--------|----------------|
+| -------- | ---------------- |
 | `action: run` | Launch `task-pipeline.yaml` for this WBS (happy path **unchanged**) |
 | `action: skip` code **A2** | Do not launch; report `preflight-skip` + unmet deps (mirrors TABLE A2) |
 | `action: skip` code **A7** | Do not launch; report blocked (handover is operator-side) |
@@ -253,7 +254,7 @@ Only two flags cross the orchestrator→pipeline boundary; both are merged into
 `--vars` JSON:
 
 | Flag | Effect on per-task `--vars` |
-|---|---|
+| --- | --- |
 | `--auto` | sets `"profile":"auto"` (skips the HITL approve gate). Omitting it forwards nothing, so the pipeline uses its default profile (standard — HITL pause surfaces to the operator). (R4.2) |
 | `--agent <value>` | omit/`inline` in interactive sequential mode selects the host driver and is not forwarded. `auto` or a name sets **both** `"agent":"<value>"` and `"implementAgent":"<value>"` so every workflow `agent.run` step — including implement — spawns that executor. Headless omit/inline falls through the executor precedence chain. To pin ONLY implement, pass `--vars '{"implementAgent":"..."}'` separately; that explicit var selects the subprocess path. (R4.3, tasks 0483/0503) |
 
@@ -283,7 +284,7 @@ node "$(superskill script path sp batch-preflight.mjs)" --wbs <wbs> --status <st
 ```
 
 | Rule | Detail |
-|------|--------|
+| ------ | -------- |
 | Budget | **≤ 1** recovery consult per WBS per batch — never loop until done |
 | Default | Print the exact child command in the batch report |
 | `--auto` batch | May dispatch the child **once** when cardinality is 1 and the hop is a single lifecycle command |
@@ -295,7 +296,6 @@ in next-router; this only maps status → primary TABLE A hop for recovery.
 
 ### 3.3c Bounded feature-sync retry suppression (task 0411)
 
-
 During a batch, the per-task `record` step and the wrap-up `feature-transition` step each invoke
 feature status sync. When a feature is L4-gate-blocked (e.g. not all linked tasks are `done`), the
 identical blocked proposal repeats on every call with no intervening input change — in the H9
@@ -413,6 +413,14 @@ The per-task outcome vocabulary: `done` | `failed` | `blocked` | `skipped` | `no
 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`).
+
 ## Worktree isolation (`--worktree [<name>]`)
 
 When a batch command (`dev-runall`, `dev-refineall`, `dev-verifyall`) is invoked with
@@ -487,7 +495,12 @@ Create one worktree on a new branch cut from the current HEAD's ref (the **base
 BASE_REF=$(git rev-parse --abbrev-ref HEAD)
 BASE_SHA=$(git rev-parse HEAD)
 BRANCH="sp/<command>-<selector-slug>-<short-id>"     # e.g. sp/runall-h1-a3f2
-git worktree add "../<repo>-<command>-<selector-slug>-<short-id>" -b "$BRANCH" "$BASE_REF"
+# `git worktree add -b` creates the branch BEFORE the directory, so a failed create leaves a
+# dangling branch and the natural retry dies on "a branch named ... already exists"
+# (task 0701 R2b). Wrap the create: on failure, delete the branch — or derive a fresh
+# short-id per attempt — before surfacing the error.
+git worktree add "../<repo>-<command>-<selector-slug>-<short-id>" -b "$BRANCH" "$BASE_REF" \
+  || { git branch -D "$BRANCH"; false; }
 ```
 
 Branch and directory names are derived (command + selector slug + short id); the create path never
@@ -497,10 +510,15 @@ not resolve is an error, not a create).
 A fresh worktree has no `node_modules` (gitignored), so the first `bun test` or
 typecheck fails on the first workspace import. Install before any task work:
 
-    cd "../<worktree-dir>" && bun install --frozen-lockfile
+    cd "../<worktree-dir>" && bun install --frozen-lockfile --ignore-scripts
 
 `--frozen-lockfile` pins the worktree to `bun.lock` rather than re-resolving,
-so the worktree's dependency tree matches the base ref's.
+so the worktree's dependency tree matches the base ref's. `--ignore-scripts` is required, not
+stylistic (task 0701 R2a): worktrees share the main tree's `.git`, and this repo's `prepare`
+script is `lefthook install` (`package.json`) — a bare install rewrites the operator's
+main-repo hooks from inside the "isolated" tree. Scripts are skipped only at this call site;
+a normal clone keeps `prepare`. The worktree still gets a usable dependency tree — the install
+exists so the first `bun test` resolves workspace imports.
 
 #### Reuse mode (`--worktree <name>`)
 
@@ -510,8 +528,8 @@ invoking tree's current HEAD ref (not the worktree's branch) and `BASE_SHA` is
 `git merge-base <BASE_REF> <BRANCH>` — so WT-4's FF-merge lands the worktree's accumulated commits
 onto the invoking tree's base ref, exactly as create mode does.
 
-`bun install --frozen-lockfile` runs **only when `node_modules` is absent** in the resolved
-worktree. A warm reused tree does not re-pay the install; a cold one (hand-made, or a retained tree
+`bun install --frozen-lockfile --ignore-scripts` runs **only when `node_modules` is absent** in
+the resolved worktree (same `--ignore-scripts` rationale as create mode — task 0701 R2a). A warm reused tree does not re-pay the install; a cold one (hand-made, or a retained tree
 whose deps were removed) installs exactly once before the first task. This is the R3 conditional
 install rule (source: task 0481) — create mode always installs because a fresh tree is always cold.
 
@@ -570,7 +588,9 @@ verb) whose path argument you control.
 
 Worktree identity lives on disk under `.spur/run/`, not only in the orchestrator's memory, so a
 session that dies mid-batch is recoverable. Write the marker at creation and update it at the
-terminal transition (merged / retained). Schema:
+terminal transition (merged / retained). The marker is written to the **invoking** tree's
+`.spur/run/` (task 0701 R2c) — the tree where the driver process started, not the worktree's own
+`.spur/run/` — so WT-6's resume scan finds it regardless of where the operator stands. Schema:
 
 ```json
 {
@@ -617,6 +637,22 @@ Reuse mode resolves the marker by the resolved worktree's `path` (not by `comman
   (AGENTS.md one-writer-per-tree; task 0487 R5). Overridable with `--force` (the operator can tell
   a crashed-session marker from a live-session one; the harness cannot).
 
+### WT-3b — Commit the batch's writes on `$BRANCH` (task 0701 R1)
+
+Before any terminal action, commit the batch's corpus writes **on `$BRANCH`, inside the
+worktree** — including the generated task files under `docs/tasks*/` and the kanban index:
+
+```bash
+cd "../<worktree-dir>"
+git add <files-the-batch-wrote>
+git commit -m "<type>(<scope>): <command> <selector> batch writes"
+cd - >/dev/null
+```
+
+The FF-only git merge carries only commits — uncommitted writes in the worktree would be left
+behind by the merge and then destroyed by create mode's `git worktree remove`. WT-3b exists so
+that can never happen.
+
 ### WT-4 — Success path (R4)
 
 When the batch completes with **no failed task**, fast-forward-merge the worktree branch onto the
@@ -629,6 +665,11 @@ only what it created*):
 # Run these from the main tree (not inside the worktree) - you merge the worktree branch
 # back onto the base ref there:
 git checkout "$BASE_REF"
+# Guard (task 0701 R1): a zero-commit branch makes the FF-only git merge exit 0
+# ("Already up to date") while merging nothing — the two lines below would then delete
+# the worktree holding the only copy of the batch's writes. Refuse instead:
+[ "$(git rev-list --count "$BASE_SHA..$BRANCH")" -gt 0 ] \
+  || { echo "halt: branch carries no commits - nothing to merge" >&2; false; }   # -> WT-5
 git merge --ff-only "$BRANCH"          # FF-only: never rebase, merge-commit, or resolve conflicts
 # if FF succeeded:
 git worktree remove "../<worktree-dir>"
@@ -636,6 +677,9 @@ git branch -d "$BRANCH"
 # update marker: status = "merged"
 ```
 
+On the zero-commit guard firing, fall through to **WT-5** with the halt cause *"branch carries no
+commits — nothing to merge"*: the worktree and branch are retained, never removed (task 0701 R1).
+
 #### Reuse mode — merge, retain
 
 The FF-merge runs identically (same `git checkout "$BASE_REF" && git merge --ff-only "$BRANCH"`),
@@ -667,12 +711,23 @@ risk losing work); WT-5 retains the worktree and branch whenever FF is impossibl
 Reuse mode is **narrower** than the carve-out (it merges but does not delete the branch), so the
 carve-out text needs no widening.
 
+**Lifecycle-DB disposition (task 0701 R2d).** The worktree has its own `.spur` lifecycle DB, and
+WT-4/WT-5 remove or retain that tree — the DB state does **not** travel with the merge. The
+**committed task file is authoritative**: after a green merge the branch's task files read
+`done`/`testing` while the invoking tree's DB still reports the pre-batch statuses. Re-sync
+explicitly by replaying the recorded terminal transitions in the invoking tree (`spur task update
+<wbs> <status>` per task, then `spur task record <wbs>`), or treat the batch report's per-task
+table as the source of truth. This is a deliberate choice over auto-migrating DB state: the DB is
+per-tree by design and the committed corpus files are the durable record.
+
 ### WT-5 — Failure path: retain and report (R5)
 
 On any per-task failure, batch halt, HITL pause that ends the run, or non-FF merge from WT-4, the
 worktree directory and branch are left **intact**. No destructive automation on this path under any
 flag combination (`--auto`, `--force`, `--keep-going` — all leave the worktree in place). Update the
-marker: `status = "retained"`. Emit a retention report in the existing halt-report shape:
+marker: `status = "retained"`. The worktree's own `.spur` lifecycle DB is retained with the tree,
+so nothing is lost on this path (see the WT-4 lifecycle-DB disposition for the merged case —
+task 0701 R2d). Emit a retention report in the existing halt-report shape:
 
 ```
 ## Worktree retained — <command> <selector>
@@ -706,7 +761,8 @@ its WT-3 marker rather than creating a second one. Marker lookup tries two paths
    This path covers the common resume shapes: the operator remembers the name used last time, or
    passes the path (tier-1 match).
 2. **Command+selector fallback (bare `--worktree` or absent flag)** — scan
-   `.spur/run/worktree-*.json` for a marker whose `command` + `selector` match the current
+   `.spur/run/worktree-*.json` **in the invoking tree** (where WT-3 wrote the marker —
+   task 0701 R2c) for a marker whose `command` + `selector` match the current
    invocation and whose `status` is `active` or `retained`. Create-mode runs that did not name their
    tree resolve here.
 3. **Found by either path** → `cd` into the marker's `path`, skip WT-1/WT-2 (no new worktree), and
@@ -769,7 +825,7 @@ time. Before launching a full `spur-check-new`:
 ## AC traceability
 
 | AC | Where satisfied |
-|---|---|
+| --- | --- |
 | R1.1–R1.4 (selector grammar) | Step 1 — selector resolution table |
 | R1.5 (umbrella-parent exclusion) | Step 1 — "Umbrella-parent exclusion" paragraph |
 | R2.1 (freeze at kickoff) | Step 2.1 |
@@ -793,6 +849,7 @@ time. Before launching a full `spur-check-new`:
 When a batch contains tasks with **zero dependency edges between them** and **no file-overlap conflicts**, the orchestrator can fan them out in parallel instead of running them sequentially. This is an **orchestrator-level optimization** — the per-task pipeline (`task-pipeline.yaml`) is unchanged; only the execution order differs.
 
 **Decision framework:** `sp:parallel-execution` owns the full fan-out decision logic and patterns. Consult its [fan-out-patterns.md](../../parallel-execution/references/fan-out-patterns.md) before parallelizing. The orchestrator's responsibility is:
+
 1. Identify the independent subset from the topo-sorted batch (tasks with no edges to each other).
 2. Check for file-overlap conflicts (two tasks touching the same `file:line` range must serialize).
 3. Verify token budget supports N-way fan-out.
@@ -803,7 +860,6 @@ When a batch contains tasks with **zero dependency edges between them** and **no
 
 **See also:** `sp:parallel-execution` skill, `sp:super-planner` agent (parallel mode), `/sp:dev-parallel` command.
 
-
 ## Subagent execution disciplines
 
 Parallel fan-out and any subagent dispatch obey the four disciplines owned by

package/plugins/sp/skills/spur-dev/references/inline-pipeline-driver.md

@@ -32,14 +32,16 @@ command, skill, script, or second workflow.
    `host-session-<run-id>` and record that fallback in the log; provenance must never be blank or
    guessed from an executor subprocess.
 4. Render the two-layer plan into the host todo list (task 0596):
-   - **Layer 1** = the pipeline's `states` in declaration order, with the active state marked — the
-     same order `renderRunPlan` / `spur workflow run --dry-run` previews.
-   - **Layer 2** = the active state's `onEnter` actions (`kind` + resolved `input`/`command`), shown
-     only for the active state.
+   - **Layer 1** = `spur workflow show <pipeline-yaml> --format todo --json` → its `steps[]`: the
+     declared state inventory in declaration order with `initial` / `terminal` / `failure` /
+     `pause` / `loopBack` / `conditional` markers. Mark the active state. Never re-derive this
+     list from the YAML.
+   - **Layer 2** = the active state's `onEnter` actions (`kind` + resolved `input`/`command`), from
+     the YAML parsed in step 1, shown only for the active state.
    - **Refresh cadence** = stage boundaries only (when the current state changes after a transition),
      never per action.
-   - **Source of truth** = the YAML parsed in step 1 plus the dry-run walk — never hand-copy the
-     state list into the driver, a command, a skill, or a script.
+   - **Source of truth** = the CLI projection for layer 1; the YAML parsed in step 1 for layer 2.
+     Never hand-copy or hand-derive the state list into the driver, a command, a skill, or a script.
 5. Record lifecycle provenance before entering the FSM:
 
    ```bash