@gobing-ai/spur 0.4.1 → 0.4.3

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

@@ -81,9 +81,45 @@ mode needs its own required args).
 spur feature update H2 active
 ```
 
-Valid statuses: `backlog → active → verifying → blocked → done → cancelled`. The lifecycle engine
-enforces legal transitions; `verifying` is the gate where AC traceability must hold (L4).
-**One active goal** at a time is enforced by `check` (a corpus invariant).
+Valid statuses: `backlog → active → verifying → blocked → done → cancelled`, plus the frozen
+`deprecated`. The lifecycle engine enforces legal transitions; `verifying` is the gate where AC
+traceability must hold (L4). **One active goal** at a time is enforced by `check` (a corpus invariant).
+
+**`deprecated` — frozen, not terminal (ADR-136).** The state means *retained and frozen*: the record
+stays readable and countable, but nothing may attach new work to it or advance it. It is entered from
+`backlog`, `active`, `verifying`, `blocked` and `done`, and left only to `active` (un-deprecate,
+mandatory History entry) or `cancelled` (removed) — every other edge out of `deprecated` is undeclared
+and refused by the graph. The freeze, as shipped:
+
+- **Task links are refused** — `task create`, `update --feature` and `batch-create` exit non-zero and
+  write nothing (no sibling hint; `--no-reopen` is irrelevant for a frozen parent):
+
+  ```
+  parent-feature-status: feature <id> is deprecated (frozen); new tasks cannot link to it. Run removal work under its own feature, or un-deprecate: spur feature update <id> active
+  ```
+
+- **`L4.feature-deprecated`** — `task check` warns (does not error) for a *live* task under a
+  deprecated feature; a terminal task is the correct end state and gets no finding; `--strict`
+  elevates the warning as usual:
+
+  ```
+  Feature "<id>" is deprecated (frozen) — re-parent this live task (`spur task update <wbs> --feature <otherId>`) or cancel it.
+  ```
+
+- **`update --section` still lands** (exit `0`), appending a warning to `warnings[]`:
+
+  ```
+  Feature <id> is deprecated (frozen); change it only as part of removal
+  ```
+
+- **`sync` / `refresh` / `check --fix` never move it** — derivation is sticky and returns the no-op
+  proposal `{ from: 'deprecated', to: 'deprecated', reason: 'Feature is deprecated (frozen)' }`.
+
+- **`advance` refuses** with exit `1`, naming the un-deprecate command:
+
+  ```
+  <id> is deprecated; un-deprecate first: spur feature update <id> active
+  ```
 
 **Scalar field set:**
 
@@ -113,7 +149,8 @@ spur feature advance H2 --to verifying
 ```
 
 Walks the legal forward path (`backlog → active → verifying → done`) hop-by-hop until `--to`
-(default `done`). No-op when already at the target.
+(default `done`). No-op when already at the target; a `deprecated` feature is refused up front (see
+the freeze block above).
 
 ## Acceptance criteria conventions
 
@@ -169,7 +206,8 @@ the AC coverage map. Habits that keep it green:
 Use feature hierarchy for user-facing capabilities and roadmap themes; keep technical-module mapping
 as prose or notes unless the product surface is developer infrastructure. Priority is a scalar field
 (`spur feature update <id> --field priority --value P1`), while status is lifecycle state
-(`backlog → active → verifying → blocked → done → cancelled`). Do not conflate the two.
+(`backlog → active → verifying → blocked → done → cancelled`, plus the frozen `deprecated`). Do not
+conflate the two.
 
 **Structure first:** [features/hierarchy-mece.md](features/hierarchy-mece.md) (MECE roots, when to
 extend vs create). **Then priority:** [features/roadmap-priority.md](features/roadmap-priority.md).
@@ -216,6 +254,9 @@ spur feature sync H2 --force                   # re-derive live: bypass replay +
 spur feature sync H2 --folder docs/custom-tasks --json   # non-default tasks folder
 ```
 
+- **`deprecated` is sticky:** derivation returns no proposal for it
+  (`reason: 'Feature is deprecated (frozen)'`), so neither `sync` nor `check --fix` moves a frozen
+  feature — see the freeze block in §Editing a feature.
 - **`[id]`** syncs one feature; **`--all`** syncs every feature with linked tasks. One of the two is
   required - exit `2` if neither is given.
 - **`--dry-run`** reports proposed transitions without applying. **`--force`** applies a *reopen*

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

@@ -22,7 +22,7 @@ shapes live in `apps/cli/src/commands/projects.ts`.
 | `clean` | Purge missing project folders and terminate lingering processes (alias: `refresh`) | `--no-terminate-processes` `--json` |
 | `list` | List entries with live running status | `--json` `--fleet` |
 | `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` |
+| `stop <target>` | Ownership-verified stop of 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`.
@@ -36,8 +36,8 @@ exit `0`; validation, registry, spawn, health, or lookup failure is exit `1`.
 - `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` automatically heals tilde paths, verifies project directories exist on disk (purging missing entries and terminating lingering processes), and heals stale entries to `port: 0` before reporting `running`.
-- `clean` (alias `refresh`) explicitly purges non-existent project directories from `projects.json`, probes live ports for removed entries, and cleanly terminates orphaned listening processes (SIGTERM with bounded wait and SIGKILL escalation). Supports `--no-terminate-processes` to skip process kills.
+- `list` automatically heals tilde paths, verifies project directories exist on disk (purging missing entries and terminating only ownership-verified lingering processes), and heals stale entries to `port: 0` before reporting `running`.
+- `clean` (alias `refresh`) explicitly purges non-existent project directories from `projects.json`, probes live ports for removed entries, and terminates orphaned listeners only after ownership verification (SIGTERM with bounded wait and SIGKILL escalation, each signal gated on `service:spur` identity plus exact project path and a stable PID; foreign or unverified listeners are never signaled). Supports `--no-terminate-processes` to skip process kills.
 - `list --fleet` (0835/0858) additionally resolves each project's `agent.fleet` section from that
   project's `.spur/config.yaml` under the existing verb (no new noun). Per project it prints one line
   per member: instance id (the spec id / mailbox identity), `role`, resolved `executor`,
@@ -76,8 +76,10 @@ port is returned idempotently; otherwise the service allocates a port (3000–39
 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.
+`stop` signals only a listener that proves `service:spur` identity plus the exact registered project
+path with a stable rediscovered PID; it refuses foreign or unverified listeners with exit 1 and
+preserves the port, treats an absent listener as idempotent success, and excludes the CLI and its
+parent. 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

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

@@ -110,6 +110,8 @@ Read this `SKILL.md` plus your mode's files below before the first dispatch; eve
 - --worktree: `references/execution-batch.md`, `references/execution-worktree-setup.md`
 - --mode parallel: `references/execution-batch.md`, `references/execution-parallel-isolation.md`
 
+`--mode auto` reads as sequential-inline until § 2.4a resolves it.
+
 Byte budgets for these sums live in `plugins/sp/tests/bootstrap-budget.test.ts`
 (`BOOTSTRAP_BUDGETS_BYTES`, task 1128); the test fails the build when a mode's bootstrap grows.
 

package/plugins/sp/skills/spur-dev/references/ac-style-guide.md

@@ -88,6 +88,33 @@ DD-06 permissive start: treat only the core tier as must-ship initially; promote
 prove important in a later iteration. (When tiered gating lands in `spur feature check`, these tags
 become the gate input — the CLI stays the validator; this guide stays the convention.)
 
+### Home-node tier (structural, exempt from the orphan sweep)
+
+A **home node** carries one structural or placement scenario that states *where the work lives*
+(e.g. "work on the kk workflow-run ledger has a home node"). No task can cover that statement — it
+describes planning placement, not behaviour — so tag it `@home-node` to remove it from the
+feature-side DD-09 orphan sweep (`L4.uncovered-feature-scenario`):
+
+```gherkin
+@home-node
+Scenario: R1 — Work on the kk workflow run ledger has a home node
+  Given a change that targets the kk workflow run ledger workflow
+  When the change is planned as a feature
+  Then it is feature G7 or a child feature of G7
+```
+
+Rules:
+
+- **Scenario-level tag only.** A `Feature:`-level `@home-node` exempts nothing; the tag is read per
+  scenario.
+- **Exempts the orphan sweep only.** Scenario satisfaction (0340), verdict-row matching, and the
+  known-issues ratchet are unchanged — a tagged scenario a task actually covers is classified
+  exactly as before.
+- **Never a hiding place.** Use it only for a scenario no task can own. A deliberately uncoverable
+  *capability* scenario belongs to `@core`/`@edge` and must stay in the sweep: tagging it
+  `@home-node` hides a real gap. Wording is never the signal.
+- A feature with **no linked task** is still flagged as `L4.orphan-scenarios`, tagged or not.
+
 ## Scenario-title stability
 
 The scenario title is the **identity key** for traceability. When a task references a

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

@@ -23,7 +23,7 @@ The `Skill()` commands back onto six skills: `sp:spur-dev` (planning + execution
 `sp:code-verification` (SECUA review + traceability), `sp:parallel-execution` (fan-out / parallel batch),
 and `sp:brainstorm` (structured ideation). The `runall` operation (#13) is `sp:spur-dev`'s batch entry — it delegates the driver loop to the
 `sp:super-planner` agent (the batch orchestrator) per [execution-batch.md](execution-batch.md).
-`dev-parallel` (#13a) is the parallel counterpart. `dev-brainstorm` carries the two artifact exits — `--task` (one task) and `--feature` (validated
+Parallel task batches are `dev-runall --mode parallel|auto` (`dev-parallel` retired 2026-10-10). `dev-brainstorm` carries the two artifact exits — `--task` (one task) and `--feature` (validated
 feature with BDD AC; the front-half entry that hands off to `dev-plan`). The 4 `inline` commands
 cover git tooling and operational utilities that have no natural skill home — creating a skill for
 each would be scope creep for one-liner procedures.
@@ -86,8 +86,7 @@ each would be scope creep for one-liner procedures.
 | 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] [--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]`                                                                          |
+| 13  | runall     | `dev-runall`        | `Skill()` → agent | `sp:spur-dev` (`runall`) → `sp:super-planner`                                      | `--tasks <selector> [--feature <id>] [--mode <sequential\|parallel\|auto>] [--concurrency <n>] [--keep-going] [--auto] [--agent <inline\|auto\|name>] [--json] [--wrap] [--next] [--continue] [--worktree [<name>]] [--no-summary] [--defer-gate]`                      |
 | 14  | wrap       | `dev-wrap`          | `Skill()`         | `spur workflow run` (wrapup-pipeline)                                              | `<wbs> [--agent <inline\|auto\|name>] [--auto] [--merge] [--dry-run]`                                                                                                                                 |
 | 15  | wrapall    | `dev-wrapall`       | `Skill()`         | `spur workflow run` (wrapup-pipeline)                                              | `[--since <iso>] [--feature <id>] [--status <s>] [--agent <inline\|auto\|name>] [--auto] [--merge] [--dry-run]`                                                                                        |
 | 16  | idea       | `dev-idea`          | `Skill()`         | inline driver (`idea-pipeline`) or async workflow                                  | `"<idea>" \| --from-file <path> [--skip-design] [--agent <inline\|auto\|name>] [--auto]`                                                                                                                              |

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

@@ -126,7 +126,7 @@ 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-conflict:<file>` never overwrites a divergent invoking-tree record and causes the delegate to exit 1, retaining the worktree. Before reconciling one by hand, check **what** the invoking record is: when the run closed `done` inside a linked worktree the owning tree holds that run's **WT-0 landing obligation** (`landing: required branch=… path=… base=…`, see [execution-worktree-landing.md § WT-0](execution-worktree-landing.md#wt-0--markerless-worktree-runs)) — a 3-line record that is *not* a stub of the worktree's stage narrative, so copying the worktree record over it destroys the very obligation a later merge must rewrite. The reconciliation is therefore: discharge the obligation in place (`landing: merged <sha>` or `landing: retained`), and preserve the worktree narrative beside it (e.g. `<runId>.worktree-provenance.md`) rather than in place of it. 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
@@ -178,6 +178,11 @@ the wrap's refusal of non-done tasks remains the hard invariant.
 
 **Close-out commit (1129 R2/R5).** In sequential mode the wrap's writes (learnings, metrics,
 doc-sync) land in the invoking tree and are committed as ONE close-out commit after the wrap exits.
+**Under `--worktree` they land in the EXECUTION tree instead** and ride the branch as its own commit
+on `$BRANCH`: Step 6 runs before WT-4, so a close-out commit on the base ref would advance it and
+make the batch's own FF-merge impossible (the fresh base tip would no longer be an ancestor of the
+batch tip — the step that makes the close-out the report's own contradiction). The close-out commit
+is never a point on the base ref.
 Stage them through the guard — never a free-form `git add` — so a concurrent writer's file cannot
 ride into the close-out commit (incident `36f274590`). `$RUN_ID` is the id Step 3 fixed before
 `commit-guard start` (execution-batch.md § Step 3); an unset id makes the guard exit 1 — fail closed:

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

@@ -204,7 +204,18 @@ For each dependency edge to a task **outside** the frozen set, resolve its curre
 
 ### 2.4 Topological sort
 
-Topological-sort the remaining in-set, non-blocked tasks using Kahn's algorithm:
+Do not hand-run the sort — compute it. Write the remaining in-set, non-blocked tasks to a temp file
+as a JSON array of `{wbs, dependencies, files?}` (`dependencies` from `spur task show <wbs> --json`
+frontmatter; `files` = repo paths the task's Design/Plan names, omit when it names none) and run:
+
+```bash
+node "$(superskill script path sp batch-plan.mjs)" order --tasks <tasks.json> [--concurrency <n>]
+# → {"order":[…],"waves":[[…],…],"cycle":null|[…],"overlaps":[…],"mode":"sequential|parallel","reason":"…"}
+```
+
+`order` is the execution plan; a non-null `cycle` is the abort below. `waves`, `overlaps`, `mode`
+and `reason` feed `--mode auto` (§ 2.4a) and the batch report. The script implements Kahn's
+algorithm (ADR-130 glue over `scheduleBatch` in `packages/app/src/workflow/plan-projection.ts`):
 
 1. Seed the queue with zero-indegree nodes, **sorted WBS-ascending** (deterministic tie-break).
 2. Repeatedly dequeue the lowest-WBS zero-indegree node, emit it, decrement its successors'
@@ -214,7 +225,35 @@ Topological-sort the remaining in-set, non-blocked tasks using Kahn's algorithm:
 **Cycle handling (R2.3):** a cycle aborts the **entire batch** before any task runs. Reconstruct a
 representative cycle path via DFS over the remaining unsorted nodes and report it (e.g.
 `0040 → 0042 → 0040`). Do not run any task in a cyclic batch — running a prefix would partially
-execute work whose ordering is undefined.
+execute work whose ordering is undefined. The script reports it as `cycle` (e.g.
+`["0040","0042","0040"]`) with an empty `order`.
+
+**File overlap.** Two tasks that declare the same file get a serialization edge oriented by their
+dependency order (`overlaps[]` records each), so overlap never creates a cycle and never puts
+overlapping tasks in the same wave (`sp:parallel-execution` row 3). It only matters under parallel
+execution; sequential order stays a valid topological order either way.
+
+### 2.4a `--mode auto` resolution
+
+`--mode auto` is decided **once, here, by the active orchestrator** (the host session, or
+`sp:super-planner` when an explicit executor is set), after freeze, Step 2.3 blocking and
+the § 2.4 schedule, and before any task runs:
+
+| Condition (first match wins) | Resolved mode |
+| --- | --- |
+| `--worktree` present | `sequential` (parallel rejects `--worktree`) |
+| `--agent inline` explicitly passed | `sequential` (inline is the host-session driver) |
+| script `mode` is `sequential` (fewer than 2 tasks, `--concurrency 1`, or every wave holds one task) | `sequential` |
+| script `mode` is `parallel` | `parallel` |
+
+- **Sequential resolution** continues the Step 3 loop with the frozen `order` (host-inline, or
+  subprocess per task under an explicit executor).
+- **Parallel resolution** hands off to the explicit/parallel path as
+  `runall --tasks <order as comma WBS list> --mode parallel` plus the operator's other flags. The
+  explicit list carries the frozen membership, so the feature preflight (Step 1) is not re-run.
+- `--defer-gate` survives only a parallel resolution; a sequential one drops it.
+- The batch report records `mode: auto → <resolved>` with the script's `reason`, the widest wave,
+  and any `overlaps`.
 
 ### 2.5 Result
 
@@ -321,8 +360,8 @@ emit batch report (per-task outcome + preflight skips + recovery hints + autoRep
 ```
 
 Parallel mode keeps the same lifecycle but swaps the inner loop for the per-task-worktree fan-out
-specified in [§ Parallel isolation](#parallel-isolation---mode-parallel): identify a zero-edge,
-non-overlapping subset; **preflight each** selected task; run each ready task's `task-pipeline.yaml`
+specified in [§ Parallel isolation](#parallel-isolation---mode-parallel): take the zero-edge,
+non-overlapping frontier from the § 2.4 schedule's waves; **preflight each** selected task; run each ready task's `task-pipeline.yaml`
 invocation in its own create-mode worktree; integrate by rebase + `--ff-only` as tasks finish;
 recovery stays **sequential** (one WBS). If any decision-framework check fails, serialize and
 record the reason.
@@ -567,15 +606,25 @@ The cheap rule gates fail fast when run first — the full-gate run is dominated
 suite, so a gate run that dies at `test-post-check` or `corpus-check` wastes most of its wall time.
 Before launching a full `spur-check-new`:
 
-1. **Run the two rule gates first** — `bun run test-pre-check` (43 rules: `no-console-output`,
+1. **Run the static checks first** — `bun run lint` (biome over the whole tree plus every workspace
+   typecheck). They fail in ~20 s and are the two defects that most often kill a full launch: a
+   formatting miss in a touched test file, or a generated declaration surface that no longer lists a
+   new export. Measured 2026-10-12: two consecutive `spur-check` launches died here and each spent
+   its whole wall time before reaching the suite.
+2. **Then the two rule gates** — `bun run test-pre-check` (43 rules: `no-console-output`,
    `no-direct-process-spawn`, `cli-*`, `require-corresponding-test`) and `bun run test-post-check`
    (`every-export-has-tsdoc`, `coverage-gate`). They catch boundary/TSDoc violations in seconds.
-2. **Promoted code must satisfy the boundary rules `scripts/` never enforced.** A command module
+   Two `coverage-gate` facts change how you call post-check: it **fails closed when
+   `.coverage/lcov.info` is absent**, which is the normal state of a fresh worktree, so run it after
+   the suite has written coverage or expect that one error instead of reading it as a finding; and a
+   targeted `bun test <file>` **overwrites** the tracefile, so post-check judges partial data if it
+   runs after one (the `coverage-gate` rule's own header documents both facts).
+3. **Promoted code must satisfy the boundary rules `scripts/` never enforced.** A command module
    moving from `scripts/` into `apps/cli/src` must route output through the `CommandOutput` seam (no
    `console.*`), spawn processes via `NodeProcessExecutor` (no `Bun.spawnSync`), get a
    `runtime-boundaries` fs-io exemption for sync reads (mirrors `task.ts`), and a non-command helper
    must not live in `apps/cli/src/commands/` (the noun scan treats every file there as a noun).
-3. **Doc/TSDoc edits shift `file:line` anchors** cited by other tasks — the per-task gate surfaces
+4. **Doc/TSDoc edits shift `file:line` anchors** cited by other tasks — the per-task gate surfaces
    them as `L4.anchor-subject-mismatch` (0775: the corpus sweep retired; run `spur task check <wbs>`
    on touched tasks). Repoint the shifted citations (via `spur task update --section`)
 

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

@@ -45,7 +45,10 @@ emit batch report (per-task outcomes + preflight skips + recovery hints + batch
 - **Eligibility (R2).** A task becomes eligible only when all of its in-set dependencies are
   **integrated** onto the base ref — pipeline-terminal is not enough, because its branch must
   rebase over theirs. Omitting `--mode` stays sequential; this loop is entered only via
-  `--mode parallel` on `/sp:dev-runall`.
+  `--mode parallel` on `/sp:dev-runall`, directly or as a `--mode auto` resolution
+  ([execution-batch.md § 2.4a](execution-batch.md#24a---mode-auto-resolution)).
+- **Fan-out set.** Run order and eligibility come from the § 2.4 `batch-plan.mjs order` schedule;
+  its file-overlap edges are in-set dependencies here, so overlapping tasks never run at once.
 - **Workdir.** `spur workflow run` records the launch workdir (0784 R1), so launch with `cwd` = the
   task worktree: resume and `.spur/run/` artifact paths resolve there. Read the verdict from
   `$WT/.spur/run/<wbs>-verdict.json` before integration; WT-4a persists it into the invoking tree.

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

@@ -16,6 +16,28 @@ When the batch completes with **no failed task**, fast-forward-merge the worktre
 base ref. The terminal action after the merge differs by mode (ownership rule: *the flag removes
 only what it created*):
 
+**Duplicate-WBS sweep before the merge (observed 2026-10-12).** WBS allocation is per-tree — a
+worktree's allocator reads only its own corpus and DB — so two trees cut from the same base both
+allocate the same next number, and the collision surfaces only here (measured: the F42 batch's
+residual task shipped as `1183` while the base ref had already given `1183` to another task, so the
+file had to be re-filed before landing). Run this against the ref you are about to merge INTO:
+
+```bash
+TARGET=<base-ref>; BRANCH=sp/<branch>
+for f in $(git diff --diff-filter=A --name-only "$(git merge-base "$TARGET" "$BRANCH")..$BRANCH" -- docs \
+           | grep -E '^docs/tasks[0-9]*/'); do
+  wbs=$(basename "$f" | cut -c1-4)
+  git ls-tree -r --name-only "$TARGET" -- docs | grep -qE "/${wbs}_" && echo "COLLISION $wbs $f"
+done
+```
+
+A hit means one file must lose: keep the target's task, re-create the branch's task in the invoking
+tree through `spur task create` (the allocator picks the next free number), and drop the branch's
+file in the merge resolution — never land both, and never renumber by hand. Verified against a
+fixture (flags a duplicate, silent on a free WBS). The pathspec form is load-bearing: `-- docs` plus
+the `^docs/tasks[0-9]*/` filter, because plain `docs/tasks*` matches nothing under `ls-tree` here and
+`:(glob)` magic is rejected by `ls-tree`/`diff` (it works for `git status`).
+
 #### Create mode — merge, remove, delete
 
 ```bash

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

@@ -180,6 +180,13 @@ main-repo hooks from inside the "isolated" tree. Scripts are skipped only at thi
 a normal clone keeps `prepare`. The worktree still gets a usable dependency tree — the install
 exists so the first `bun test` resolves workspace imports.
 
+**Generated trees are still missing after the install.** A gitignored generated tree does not ride the
+worktree, so any suite comparing the canonical source against its generated copy fails until the
+generator runs. In this repo that is `apps/cli/config/` (from `bun run bundle:config`): without it
+`plugins/sp/tests/command-flag-parity.test.ts` fails on the missing generated pipeline YAML under that
+directory (observed 2026-10-12, A91 batch). Run the generator once after a create-mode install, and
+again after a rebase or merge that touches the canonical workflow sources it is built from.
+
 #### Reuse mode (`--worktree <name>`)
 
 Creation is **skipped entirely**. `$BRANCH` is the resolved worktree's already-checked-out branch; a
@@ -374,6 +381,13 @@ same call, verifies the WT-3 identity, and never relies on a persistent `cd` or
 > concurrent writer happened to leave in the tree — the two incidents this guard exists for are
 > `a94f9f431` and `36f274590` — so a driver stages only through `commit-guard stage`.
 
+> **`stage` takes files, never directories.** A directory argument is refused as `(unchanged since
+> base)` and stages *nothing*, so a task whose diff lives in a moved tree must expand the changed
+> paths (`git status --porcelain` plus the filter for the task's own files) instead of passing
+> `plugins/sp/hooks` or `packages/app/tests/hooks`. Symptom observed on 2026-10-12 (A91 batch): the
+> first commit captured only the pre-staged `git mv`/`git rm` renames and needed an amend to carry
+> the rest of the task.
+
 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.

package/plugins/sp/skills/spur-dev/references/flag-glossary.md

@@ -148,7 +148,7 @@ halt-on-first-failure. Never silently retried; the failure is still reported.
 
 ### `--defer-gate` — opt-in parallel-batch gate policy (task 1111 / H15)
 
-**Applies to:** `/sp-dev-runall --mode parallel`, `/sp-dev-parallel --mode fan-out`.
+**Applies to:** `/sp-dev-runall --mode parallel`, and `--mode auto` when it resolves to parallel.
 **Default:** off — every task pipeline runs its own FULL project gate inside its worktree.
 
 With `--defer-gate`, each task's `test` / `test-recheck` hop runs the **light tier** (changed-scope
@@ -167,9 +167,10 @@ Two properties are load-bearing and are asserted structurally:
   project gate; the per-task token is `DEFERRED`, and the `test → triage` /
   `test-recheck → triage` guards accept it only while `deferQualityGate = "true"`.
 
-`--defer-gate` without `--mode parallel` is rejected — the flag exists to move one full gate from N
-worktrees to the one place the integrated tree exists. Sequential and inline batches never set the
-var. ADR-124 carries the dated clarification.
+`--defer-gate` with `--mode sequential` (or omitted `--mode`) is rejected — the flag exists to move
+one full gate from N worktrees to the one place the integrated tree exists. Under `--mode auto` it
+applies only if the batch resolves to parallel; a sequential resolution drops it with a report note.
+Sequential and inline batches never set the var. ADR-124 carries the dated clarification.
 
 **Anchor:** `#flag-defer-gate`.
 
@@ -177,11 +178,11 @@ var. ADR-124 carries the dated clarification.
 
 **Anchor:** `#flag-concurrency`.
 
-`dev-runall` under `--mode parallel` (task 0931): at most `<n>` task pipelines run at once
+`dev-runall` under `--mode parallel` (task 0931), or `--mode auto` resolved to parallel: at most `<n>` task pipelines run at once
 (default 2, `n ≥ 1`). A dependent task starts only after every in-set dependency has been
 **integrated** onto the base ref — see
 [execution-batch.md § Parallel isolation](execution-batch.md#parallel-isolation---mode-parallel).
-Ignored in sequential mode. Each worker is one more concurrent quality gate; raise it only when
+Ignored in sequential mode; `--concurrency 1` pins `--mode auto` to sequential. Each worker is one more concurrent quality gate; raise it only when
 the host has the CPU for it.
 
 ### `--continue` — resume an interrupted batch from checkpoint
@@ -271,12 +272,12 @@ is the contract; divergence between `--dry-run` and the real run is a bug.
 
 **Anchor:** `#flag-tasks`.
 
-Batch operation (`dev-parallel`, `dev-refineall`, `dev-review`, `dev-runall`, `dev-verifyall`). An
+Batch operation (`dev-refineall`, `dev-review`, `dev-runall`, `dev-verifyall`). An
 explicit selector — WBS list, status pseudo-list (`todo`, `wip`), `feature:<id>`, or `ready` —
 resolving to the set the batch runs over. On `dev-review` the selector is restricted to the
 review-safe forms: comma WBS list and `feature:<id>` — status pseudo-lists and `ready` are
-rejected (they select work to do, not work to review). Required on `dev-parallel`, `dev-runall`,
-and `dev-verifyall`, where `--feature` is an optional restrictor. On `dev-refineall` it is instead
+rejected (they select work to do, not work to review). Required on `dev-runall` and
+`dev-verifyall`, where `--feature` is an optional restrictor. On `dev-refineall` it is instead
 one of a required pair — supply exactly one of `--feature` or `--tasks`.
 
 ### `--mode <kind>` — select an execution mode
@@ -284,8 +285,9 @@ one of a required pair — supply exactly one of `--feature` or `--tasks`.
 **Anchor:** `#flag-mode`.
 
 Select an execution mode: `full|implement` on `dev-run` (full pipeline vs implement-only),
-`sequential|parallel` on `dev-runall` (serial vs fanned-out-independent-subset),
-`fan-out|review-panel|investigation` on `dev-parallel`, the reconstruction depth
+`sequential|parallel|auto` on `dev-runall` (serial, fanned-out independent subset, or chosen from the
+frozen batch's dependency waves — see [execution-batch.md § 2.4](execution-batch.md#24-topological-sort)),
+the reconstruction depth
 `briefing|structure|architecture|design|full` on `dev-reverse`, and `daily|ad-hoc` on
 `dev-find-issue` (the history-anatomy report mode). Mode selection is explicit and orthogonal
 to `--next`.

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

@@ -86,7 +86,9 @@ fallback) — labels are display addresses only, never an execution key.
 1. Resolve the command inputs, `--auto`, and any explicit `--vars` — **without reading the selected
    YAML yet**. An explicit non-inline executor selection chooses the subprocess workflow path.
 2. Allocate a collision-resistant inline run id (`uuidgen`, with a timestamp/pid fallback), create
-   `.spur/run/` for attempt staging and `.spur/memory/runs/` for retained records, and use the two-file run record (task 0927) — append lines to
+   `.spur/run/` and the run's scratch subdirectory `.spur/run/<run-id>/` for attempt staging (action
+   batches, captured stage output, temporary status/answer files) plus `.spur/memory/runs/` for
+   retained records, and use the two-file run record (task 0927) — append lines to
    `.spur/memory/runs/<run-id>.md` and read machine state from `.spur/memory/runs/<run-id>.state.json`.
    The run id lives in those two files and the persisted run row — never stage it in an ad-hoc
    `*.env` file: the `no-env-files` gate rule flags any `.env` name, so run-scoped staging files
@@ -439,9 +441,9 @@ Action semantics come from the YAML and the workflow action contract:
   recheck's `no-progress` guard honours it, so a cap-kill reads as a red gate the next time. Preserve
   the signal-induced receipt under a distinct name (`<wbs>-check-receipt.false-fail-<signal>.json`)
   and say so in the run log before re-running: never delete it silently, and never report a
-  cap-killed attempt as a genuine gate failure. Measured this session: one foreground gate call
-  (25.6 min host-wide lock wait + 7.4 min runtime) was SIGTERM-killed at the host cap and produced
-  exactly that false FAIL receipt.
+  cap-killed attempt as a genuine gate failure. Measured 2026-10-10 (before the gate-lock removal):
+  one foreground gate call (25.6 min host-wide lock wait + 7.4 min runtime) was SIGTERM-killed at the
+  host cap and produced exactly that false FAIL receipt.
 - `note` — append the expanded message to the inline run log.
 - `doctor.probe` — run the declared Spur doctor once, persist its status file, and apply any
   `setVars` result (including a resolved executor) before the next action or state.
@@ -606,7 +608,7 @@ prompt the host cannot see is invisible until join. Record one run-log line per
 stage <id> permission precheck: ok | <missing capability>
 ```
 
-Read-only investigation fan-out (`/sp:dev-parallel --mode investigation`) dispatches read-only
+Read-only investigation fan-out (N-way investigation) dispatches read-only
 worker shapes by construction — see the [pre-dispatch permission
 rule](../../parallel-execution/references/fan-out-patterns.md).
 
@@ -761,21 +763,14 @@ grading its own work defeats the stage. A continuation stage also dispatches fre
 same-task subagent exists (the earlier stage ran host-inline or below the dispatch floor), when a
 host-owned gate sat between the stages, or when the platform cannot address completed subagents.
 
-**Implement and test-fix workers never run the full gate (task 1127 R8 / task 1142 R3).** Since 1127 the full gate
-takes a host-wide lock (`SPUR_GATE_LOCK_DIR`, default `~/.config/spur/run/full-gate.lock`):
-concurrent full-gate runs serialize, and a manual `spur-check` (wrapped via
-`scripts/commands/gate-lock.ts`) holds the same lock. A dispatched **implement** or `test-fix` child
-that re-ran the full gate would queue behind every other gate on the host and burn its dispatch
-timeout waiting instead of working. Workers use the light tier as their iteration check (task 1142 R3) in exact order:
+**Implement and test-fix workers never run the full gate (task 1142 R3).** Workers use the light tier as their iteration check (task 1142 R3) in exact order:
 1. the **changed-path matrix** (`code-implementation/SKILL.md` § Changed-path targeted checks) over the paths they touched;
 2. the resolved `quality-gate` script in `light` mode (source-repo probe, else the installed twin) (biome, per-workspace typecheck, rule presets, related tests).
-Neither step takes the full-gate lock. The pipeline's `test` and `test-recheck` hops remain the only full gate. Carry
+Neither step takes the full gate. The pipeline's `test` and `test-recheck` hops remain the only full gate. Carry
 `--gate-log <path>` through to the child **verbatim**: never paraphrase it into "re-run the named
-gate command". That paraphrase is not cosmetic — it dropped this rule in the H15 run (task
-Background, seq 232) and sent a worker into the locked gate. The pipeline's next `test` (recheck)
-stage re-acquires the lock and delivers the deciding verdict; that deciding run may wait for a live
-holder, so a queued worker's effective budget is dispatch timeout minus observed lock queue wait,
-not the timeout alone.
+gate command". That paraphrase is not cosmetic — it sent a worker into a full gate run instead of
+targeted iteration checks. The pipeline's next `test` (recheck)
+stage delivers the deciding verdict.
 
 **Null or timed-out dispatch (task 1134 R9).** The dispatch bound stays the existing YAML
 `timeoutMs` (`implementTimeoutMs` / `stepTimeoutMs`), passed to the host dispatch as today — R9 adds
@@ -840,6 +835,19 @@ The quality gate's `proofDigest` certifies a specific tree. Two rules protect it
    before a review dispatch is spent. The mismatch routes through the existing tripwire to `failed`;
    there is no new re-certify path.
 
+**A host-driven pass that skips the `test` hop has no digest-bound receipt.** `proofDigest` is
+captured by the `test` state's `proof.fingerprint` action, so hops driven out of band — an operator
+implementing/verifying/recording by hand, or an audit of a task whose gate the host ran directly —
+leave no `.spur/run/<wbs>-check-receipt.json`. The deciding artifacts are then
+`.spur/run/<wbs>-test-gate.status` plus its gate log. Two consequences, in order of preference:
+
+1. **Drive the pipeline** for anything that must be certified: only a digest-bound full receipt
+   satisfies a review/verify/record boundary (`sp-spur-check`), and the `test` hop owns the capture.
+2. **When a host-driven pass is unavoidable, say so in the verdict** — name the status file and gate
+   log as the evidence and grade confidence `MEDIUM`. A `HIGH` claim needs re-runnable evidence from a
+   checked path (the `sp-code-verification` ladder); claiming a receipt that was never written is the
+   failure mode this note exists to prevent (observed across four A91 tasks, 2026-10-12).
+
 **A mismatch names the drifted paths (R5).** At gate entry the pipeline snapshots the non-corpus tree
 state (`git status --porcelain=v1 -uall` plus `git diff --name-only HEAD`, excluding
 `docs/tasks*` / `docs/features*`) into `.spur/run/<run-id>-gate-paths.txt`. On a mismatch the
@@ -914,21 +922,25 @@ verdict artifact exists (tasks 0617, 0619 — the clobbering spiral).
 
 ## Running the full gate (task 0872 / 1127 R7)
 
-The full gate serializes behind a host-wide lock and legitimately runs 10-25 minutes. Two rules keep
-it from becoming a hazard (both violated once on 2026-10-10, blocking every other session for ~11
-minutes and aborting the run's own verification):
+The full gate legitimately runs 10-25 minutes. Two rules keep it from becoming a hazard (both
+violated once on 2026-10-10, aborting the run's own verification):
 
 - **Never wrap it in an external `timeout`, and never treat its runtime as a hang.** An outer bound
-  that fires mid-suite leaves the holder alive holding the lock while the caller believes it is gone.
-- **Run it detached and poll the log**, so losing the foreground call cannot lose the holder:
+  that fires mid-suite leaves a half-finished suite behind while the caller believes it is gone.
+- **Run it detached and poll the log**, so losing the foreground call cannot lose the run:
 
   ```bash
   nohup bash -c 'bun run spur-check > /tmp/gate.log 2>&1; echo "EXIT=$?" >> /tmp/gate.log' &
   ```
 
-- **Never kill a gate holder whose pid is alive.** The waiter line `waiting for holder (… held Nms)`
-  is printed only after `isProcessAlive(held.claim.pid)` succeeded, so a printed holder is a live one
-  by construction; only the lock's own dead-pid reclaim is authorised to clear a claim.
+- **Preserve a signal-induced receipt.** A cap-killed attempt leaves a red receipt that the next
+  recheck's `no-progress` guard honours, so it reads as a genuine failure unless the receipt is kept
+  under a distinct name and the run log says so.
+
+> Historical (task 1127, removed in task 1173): these rules were once stated in terms of a host-wide
+> `full-gate.lock`. The lock mechanism was deleted (`refactor(gate): remove gate-lock mechanism and
+> simplify quality-gate`), so nothing serializes gate runs today — the guidance above stands on its
+> own without it.
 
 ## Runtime interface contracts (from run evidence)