@gobing-ai/spur 0.3.65 → 0.3.67

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

@@ -0,0 +1,69 @@
+---
+name: spur-cli-history
+description: "spur-cli noun reference: operate `spur history` to import coding-agent transcripts, aggregate versioned forensic artifacts, render an artifact without database access, or run the checkpoint-resumed daily pipeline."
+see_also:
+  - spur-cli
+---
+
+# spur history - local forensic analytics
+
+`spur history` is the local history data plane: import transcripts into SQLite, aggregate a
+versioned artifact, render that artifact, or run the daily composition. Command registration and
+CLI guards live in `apps/cli/src/commands/history.ts` (`registerHistoryCommand`); payload contracts
+live in `packages/app/src/services/history-service.ts` (`FanOutResult`, `DailyResult`,
+`HistoryService`, `runHistoryReport`) and `packages/domain/src/analytics/artifact.ts`
+(`HistoryArtifact`).
+
+## Verb map
+
+| Verb | Purpose | Key flags |
+| ---- | ------- | --------- |
+| `import` | Import one source or fan out across all supported sources | `--source <source>` `--file <path>` `--root <path>` `--mode <mode>` `--dry-run` `--source-timeout <ms>` `--json` |
+| `analyze` | Aggregate imported rows and write a versioned forensic artifact | `--since <iso>` `--until <iso>` `--source <source>` `--session <id>` `--run <runId>` `--task <wbs>` `--top <n>` `--out <path>` `--json` |
+| `report [path]` | Purely render an existing artifact; default to `latest.json` | `--mode <name>` `--task <wbs>` `--top <n>` `--json` |
+| `daily` | Run import-all → analyze → artifact → 90-day report pruning once | `--since <iso>` `--until <iso>` `--root <path>` `--source-timeout <ms>` `--mode <name>` `--json` |
+
+Every JSON-capable verb also advertises `--json-envelope`; use the facade's machine-output contract.
+
+## `import` - isolated fan-out
+
+```bash
+bun run apps/cli/src/index.ts history import --source all --dry-run --json
+bun run apps/cli/src/index.ts history import --source codex --mode incremental --json
+bun run apps/cli/src/index.ts history import --source codex --file session.jsonl --mode force-file --json
+```
+
+- `--source all` and a single source use the same per-source fan-out path. A failed/timed-out source
+  does not abort its siblings.
+- Modes are `incremental`, `full`, and `force-file`. `--file` with the default `all` source is a
+  usage error. `--file --mode full` requires `--dry-run`; use `force-file` for a real single-file
+  write.
+- JSON contains `entries`, `warnings`, `exitCode`, and CLI/importer `provenance`. For real-data
+  validation, invoke the source-local CLI and record that provenance; never trust a bare global
+  `spur` that may be stale.
+- Exit `0` when every source is clean/empty, `2` for a mixed failure or any degraded source, and `1`
+  when all sources fail. CLI usage guards also exit `1` on this noun.
+
+## `analyze` - artifact writer
+
+`analyze` performs SQL aggregation over imported history and writes a stable, versioned
+`HistoryArtifact`. Selectors combine with AND. `--top` bounds leaderboards, not totals. `--out`
+overrides the dated report path; otherwise the service writes under `.spur/reports/history/` and
+updates `latest.json`. Human mode renders a summary; `--json` emits the artifact.
+
+## `report` - pure artifact renderer
+
+`report` never opens the database. It reads an explicit artifact or the `latest.json` pointer,
+validates the schema version, optionally narrows the loaded artifact with `--task` / `--top`, and
+renders `default` or `forensics` mode. Unknown modes, invalid `--top`, missing/mismatched task
+dimensions, missing artifacts, and schema mismatches exit `1` instead of silently widening output.
+
+## `daily` - run-once composition
+
+`daily` runs incremental import-all, analyze, artifact write, and report-directory pruning in one
+process. `--since` / `--until` scope analysis only, not import. Checkpoints make a missed run resume
+without double-counting. The result carries `{ fanOut, artifact, pruned, coverage, reportPath? }`;
+its exit code is the fan-out exit code. `--mode` adds a rendered sidecar after analysis.
+
+For the full artifact and data-plane contracts, use `docs/04_DESIGN.md` history sections and
+`docs/design/history-data-processing.md`; do not infer fields from rendered prose.

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

@@ -24,8 +24,8 @@ use it well*.
 | `reply <msg-id> <body>` | Thread a reply to a message | `--json` |
 | `watch` | Follow an agent inbox - surface new messages as they arrive | `--agent <id>` `--interval <ms>` `--json` |
 
-All verbs accept `--json` for machine consumption. **Exit codes:** `0` success, `1` error, `2`
-invalid usage.
+All verbs accept `--json` and `--json-envelope`. `watch` applies the envelope per emitted row.
+**Exit codes:** `0` success, `1` error, `2` invalid usage.
 
 ## `send` - enqueue a message
 

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

@@ -0,0 +1,59 @@
+---
+name: spur-cli-projects
+description: "spur-cli noun reference: operate `spur projects` to register local project roots, inspect live status, start detached project servers, and stop or remove registry entries."
+see_also:
+  - spur-cli
+---
+
+# spur projects - local multi-project registry
+
+`spur projects` manages the machine-local registry resolved by
+`packages/config/src/projects.ts` (`getProjectsFilePath`) and implemented by
+`packages/app/src/services/project-registry.ts` (`ProjectRegistry`). Server startup is owned by
+`packages/app/src/services/project-start.ts` (`startRegisteredProject`); CLI registration and JSON
+shapes live in `apps/cli/src/commands/projects.ts`.
+
+## Verb map
+
+| Verb | Purpose | Key flags |
+| ---- | ------- | --------- |
+| `add <path>` | Upsert an existing path in the registry | `--name <name>` `--json` |
+| `remove <target>` | Remove an entry by display name or path | `--json` |
+| `list` | List entries with live running status | `--json` |
+| `start <target>` | Start or reuse a detached project server | `--port <n>` `--json` |
+| `stop <target>` | Best-effort stop the listener and clear its recorded port | `--json` |
+
+Every verb also advertises `--json-envelope`; use the facade's machine-output contract. Success is
+exit `0`; validation, registry, spawn, health, or lookup failure is exit `1`.
+
+## Registry behavior
+
+- The default file is `~/.config/spur/projects.json`; `SPUR_PROJECTS_FILE` overrides it. Entries are
+  `{ name, path, port }`, where `port: 0` means stopped.
+- Paths are normalized (including `~`) and existing paths resolve to real paths. Name lookup is
+  case-insensitive. Registry mutations use an advisory lock.
+- `add` requires an existing path, resolves a relative path from the current working directory, and
+  defaults the display name to its basename. It upserts; it does not start a server. The current
+  source does not enforce a `.spur/` marker or directory type.
+- `list` probes recorded ports and heals stale entries to `port: 0` before reporting `running`.
+
+## Server lifecycle
+
+```bash
+spur projects start my-project --json
+spur projects start /path/to/unregistered/project --port 3333 --json
+spur projects stop my-project --json
+```
+
+`start` resolves by name or path. An existing unregistered path is auto-registered. A live recorded
+port is returned idempotently; otherwise the service allocates a port (3000–3999 unless explicitly
+set), spawns `spur serve --host 127.0.0.1 --no-open` detached in the project root, waits for the port,
+then persists it.
+
+`stop` finds processes bound to the recorded port, sends `SIGTERM` best-effort while excluding the
+CLI and its parent, and clears the registry port. It is not a persistent supervisor contract.
+`remove` only removes the registry entry; stop a running project first when process cleanup matters.
+
+Raw JSON success payloads are verb-specific (`project`, `projects`, `removed`, `stopped`, or start
+status fields). Under `--json-envelope` they move beneath `data`; failures normalize beneath
+`error`. Read `apps/cli/src/commands/projects.ts` for exact fields.

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
@@ -221,6 +223,18 @@ the active tasks folder (or `--folder`).
 | `--folder <path>` | Custom tasks folder. |
 | `--json` | Machine-readable report envelope. |
 
+## `migrate-anchors`
+
+Qualify ambiguous in-repo evidence anchors to repo-relative paths across the task corpus. Run
+`--dry-run` first: unambiguous matches are reported in `qualified`, multiple matches in `ambiguous`
+without rewriting, and schema-incompatible files in `skipped`. The write path uses the planning
+service rather than raw file edits.
+
+```bash
+spur task migrate-anchors --dry-run --json
+spur task migrate-anchors --json
+```
+
 ## `resolve <file-path>`
 
 Map a file path to its **owning task** — returns the WBS + task file. Strategies, in order: direct
@@ -230,6 +244,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
@@ -323,6 +341,19 @@ A free-form prose answer (no tables, or tables missing the required headers) yie
 the artifact source and directs the operator to `/sp:dev-verify <wbs>`. Re-run verify with the
 table format above.
 
+## `verifyall-aggregate`
+
+Read a JSON array of `{wbs,outcome[,reason]}` rows from `--from-file` (default
+`.spur/run/verifyall-batch-input.json`) and derive one deterministic batch verdict. Valid outcomes
+are `PASS`, `PARTIAL`, `FAIL`, `NOT-STARTED`, and `UNKNOWN`; `NOT-STARTED` rows are reported but
+excluded from rollup. Exit `1` when the aggregate verdict is `FAIL` or the input is invalid.
+
+## `scaffold-tests <wbs>`
+
+Generate BDD stubs from the task's Acceptance Criteria. `--file <path>` overrides the target test
+file; `--folder <path>` overrides task lookup. JSON reports the target plus created, skipped,
+drifted, and warning results.
+
 ## `refresh-roster <wbs>`
 
 Regenerate a parent task's sub-task roster block in `## Plan` — the marker-delimited table that the
@@ -361,12 +392,15 @@ spur task sections <wbs> <init|add|list> [name] [--folder] [--json]
 spur task list     [--status <s>] [--phase <p>] [--parent <wbs>] [--feature <id>] [--folder] [--json]
 spur task refresh  [--folder] [--json]
 spur task migrate  [--dry-run] [--folder] [--json]
+spur task migrate-anchors [--dry-run] [--json]
 spur task refresh-roster <wbs> [--folder] [--json]
 spur task batch-create --file <path> [--folder] [--json]
 spur task record   <wbs> [--verdict-file <p>] [--solution-from-diff] [--transition <s>] [--folder] [--json]
 spur task verdict  <wbs> [--from-answer <p>] [--folder] [--json]
+spur task verifyall-aggregate [--from-file <path>] [--json]
 spur task check    [wbs] [--strict] [--as <status>] [--strict-core] [--folder] [--json]
 spur task resolve  <file-path> [--strict] [--folder] [--json]
 spur task path     <wbs> [--folder] [--json]
 spur task run-link <wbs> [--source <src>] [--run-id <id>] [--json]
+spur task scaffold-tests <wbs> [--file <path>] [--folder] [--json]
 ```

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

@@ -26,7 +26,7 @@ use it well*.
 | `start <agent-id>` | Start a supervised agent process (requires `spur serve`) | `--server <url>` `--json` |
 | `stop <agent-id>` | Stop a supervised agent process (requires `spur serve`) | `--server <url>` `--json` |
 
-All verbs accept `--json` for machine consumption. `--server <url>` (default:
+All verbs except the text-only `assign` accept `--json` and `--json-envelope`. `--server <url>` (default:
 `http://localhost:3000/api`) targets the supervisor API started by `spur serve`. **Exit codes:** `0`
 success, `1` error, `2` invalid usage.
 

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

@@ -264,6 +264,12 @@ spur workflow list     [--json]
 spur workflow trace    [run-id] [--workflow <name>] [--status <s>] [--since <iso>] [--last <n>] [--follow] [--poll <ms>] [--output] [--json]
 ```
 
+### `show` - project a definition
+
+`spur workflow show <file>` renders the declared graph as Mermaid. `--format todo` instead emits a
+declared-step checklist; `--json` serializes the selected projection. This verb intentionally does
+not advertise `--json-envelope` because its JSON projection is a kept-raw document surface.
+
 | Flag (on `run`) | Effect |
 | --------------- | ------ |
 | `--vars <json>` | Per-run variable overrides (JSON object). Merged over the workflow's `vars`. Values must be strings. User vars win over injected defaults (`spurBin`). |

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

@@ -236,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:**
@@ -248,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