@gobing-ai/spur 0.3.90 → 0.3.92

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

@@ -212,8 +212,15 @@ for wbs in plan:                                       # default sequential mode
              inline-pipeline-driver(task-pipeline.yaml, wbs)
          else:
              spur workflow run task-pipeline.yaml --vars <vars> --async --json
-             follow trace until terminal
+             follow trace until terminal    # spur workflow trace "$RUN" --follow --timeout 600000
+                                            # (timeout → one checkpoint, exit 1; run continues — never cancel/relaunch)
+    if run paused (escalate HITL ask (0933) or standard-profile approve):
+        surface the paused prompt (escalate: .spur/run/<wbs>-question.md via workflow.hitl.ask)
+        operator answers: spur workflow continue --answer-text <answer> "$RUN" (escalate) | continue "$RUN" (approve)
+        resume the SAME run (never relaunch); maxEscalations (default 2) bounds the ask loop
     inspect terminal state + .spur/run/<wbs>-verdict.json
+                                           # accept only if trace .run.runId == $RUN AND verdict mtime ≥ .run.startedAt
+                                           # (else outcome = stale-evidence, non-done; failure policy applies)
     report += outcome(wbs)
     if terminal == failed OR stuck status:
         recovery = recoveryHint(status, wbs)           # Step 3.3b — at most once
@@ -225,11 +232,12 @@ for wbs in plan:                                       # default sequential mode
 emit batch report (per-task outcome + preflight skips + recovery hints + batch verdict)
 ```
 
-Parallel mode keeps the same lifecycle but swaps the inner loop for the independent-task batch
-pattern in [sp:parallel-execution](../../parallel-execution/SKILL.md): identify a zero-edge,
+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`
-invocation in its own subagent/worktree-safe context; synthesize outcomes; recovery stays
-**sequential** (one WBS). If any decision-framework check fails, serialize and record the reason.
+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.
 
 ### 3.1 Per-task execution reuses the pipeline verbatim (R4)
 
@@ -239,15 +247,21 @@ Each task runs through the **standard single-task pipeline** — `task-pipeline.
 execution invokes the workflow engine. The batch loop inspects the result and never redefines a
 step.
 
-**Explicit/parallel path: launch async and poll the trace** (per execution-workflow.md §"Step 2"): a pipeline with
-`agent.run` stages runs for many minutes. Always use `--async` + `spur workflow trace` polling:
+**Explicit/parallel path: launch async, then one bounded follow** (per execution-workflow.md §"Step 2"): a pipeline with
+`agent.run` stages runs for many minutes. Always use `--async` + `spur workflow trace`. The watch is a
+single bounded call — `--timeout 600000` (10 minutes) is the one bound; a hand-rolled poll loop (and the
+retired "10 minutes or 20 polls" rule) is not needed:
 
 ```bash
 RUN=$(spur workflow run task-pipeline.yaml \
   --vars '{"wbs":"<wbs>","profile":"auto","agent":"claude"}' --async --json | jq -r '.runId')
-spur workflow trace "$RUN" --json | jq '{runId, status, terminalState}'   # poll until status is terminal (done/failed)
+spur workflow trace "$RUN" --follow --timeout 600000   # single bounded watch to terminal; checkpoint + exit 1 on timeout
+spur workflow trace "$RUN" --json | jq '.run | {runId, status, startedAt}'   # inspect: identity, status, freshness anchor
 ```
 
+A timed-out follow prints one checkpoint naming the run id and last status and exits 1; the run itself
+continues — never cancel or relaunch it over a watch timeout. Resume the watch with the same command.
+
 ### 3.2 Flag → `--vars` passthrough (R4.2, R4.3)
 
 Only two flags cross the orchestrator→pipeline boundary; both are merged into the per-task
@@ -273,6 +287,26 @@ Each pipeline run ends in one of two terminal states:
   `onEnter` exception). Record `failed` with the blocking reason from the trace. This triggers the
   failure policy.
 
+**Verify-answer table contract (0948 R9).** A verify stage's
+`.spur/run/<wbs>-verify-answer.txt` AC table is exactly four columns:
+`| AC | Status | Evidence Type | Evidence |`. The evidence-type token
+(`test`, `command`, `static-ref`, `manual-review`, `llm-judge`, `n/a`, or a `+`
+compound) is isolated in cell 3. A token merged into the evidence cell fails
+`verify-answer-lint`.
+
+**Driver acceptance (0930 R3).** The trace row and `.spur/run/<wbs>-verdict.json` are accepted as
+terminal evidence only if BOTH hold:
+
+1. **Identity** — the accepted run is the dispatched run: the **trace's** `.run.runId` equals
+   `$RUN` (compare against `spur workflow trace "$RUN" --json | jq -r '.run.runId'`). The verdict
+   artifact itself carries no runId — it is WBS-keyed, so it binds to this run only through the
+   trace identity plus the freshness check below.
+2. **Freshness** — the verdict file's mtime is at least the trace's `.run.startedAt` (a verdict
+   written before this run started is a stale child result, not completion evidence).
+
+Otherwise record outcome **`stale-evidence`** (non-`done`); the failure policy applies. A stale or
+mismatched artifact never authorizes cancelling or relaunching the run.
+
 ### 3.3b One-shot recovery (task 0279 — next-router consumer)
 
 After a non-PASS terminal state (or when the task status is stuck at `wip`/`testing` without a clean
@@ -349,16 +383,16 @@ subagents are meant to hold (task 0508's dispatch contract is preserved unchange
   dep-status lookups (Step 1), and any other controller-side `task show`. A status-only lookup may
   narrow further (`| jq '.status'`), but never widen.
 
-- Green-path trace observation projects to `{runId, status, terminalState}` only:
+- Green-path trace observation projects to `.run | {runId, status, startedAt}` only:
 
   ```bash
-  spur workflow trace "$RUN" --json | jq '{runId, status, terminalState}'
+  spur workflow trace "$RUN" --json | jq '.run | {runId, status, startedAt}'
   ```
 
-  The controller decides continue/halt from `status`/`terminalState` (ADR-044: judge a run by
-  `status === 'done'`, never by string-matching a `finalState` name) plus the bounded verdict
-  artifact `.spur/run/<wbs>-verdict.json`. It never streams or re-reads a full trace merely to
-  summarize status.
+  The controller decides continue/halt from `.run.status` (ADR-044: judge a run by
+  `status === 'done'`, never by string-matching a `finalState` name) plus the accepted verdict
+  artifact `.spur/run/<wbs>-verdict.json` under the §3.3 acceptance rule (identity + freshness).
+  It never streams or re-reads a full trace merely to summarize status.
 
 **Failure-path reads are bounded.** On a failed/blocked task, request only the terminal error and
 the minimal anchor set the batch report needs (e.g. the blocking finding line, the unmet-dep WBS,
@@ -386,9 +420,12 @@ derivable from the same dependency graph built in Step 2.
 
 ## Step 5 — Batch report (R5.2)
 
-When the batch finishes — clean (all `done`), halted (default failure policy), or aborted (cycle /
-unknown selector) — emit a structured report. The report is the orchestrator's sole output; it does
-not mutate the corpus (the pipeline's `record` step already wrote per-task results).
+When the batch finishes — clean (all `done`), halted (default failure policy), parked (`paused`:
+one or more tasks sit on an operator question (escalate, 0933) or an approval gate), or aborted
+(cycle / unknown selector) — emit a structured report. The report is the orchestrator's sole
+output; it does not mutate the corpus (the pipeline's `record` step already wrote per-task
+results). A `paused` task is non-terminal — the report marks it `paused` (never `done`) and names
+the resume command.
 
 ```
 ## Batch Report — <selector>
@@ -407,9 +444,25 @@ not mutate the corpus (the pipeline's `record` step already wrote per-task resul
 | 0060 | blocked | unmet out-of-set dep: 0099 is wip |
 
 **Next:** <one-line action — pick up halted run / resolve 0099 / all green, feature H1 complete>
+
+**Excluded from wrap** (only under `--wrap`/`--next`, when some batch tasks are not `done`):
+
+```
+| WBS | Status | Recovery |
+|-----|--------|--------|
+| 0042 | failed | C6 recovery: /sp:dev-run 0042 (residual report: .spur/run/0042-residual-report.md) |
+| 0050 | not-attempted | /sp:dev-next 0050 |
 ```
 
-The per-task outcome vocabulary: `done` | `failed` | `blocked` | `skipped` | `not-attempted`.
+A task with a residual report (failing `residual-sweep` check in its verdict artifact) uses the
+C6 recovery line (re-run the pipeline); every other excluded task uses the next-router A-row
+command for its status (F96 task 0952 R2).
+
+The per-task outcome vocabulary: `done` | `failed` | `blocked` | `skipped` | `not-attempted`,
+plus the resume-only `recheck` (stale/mismatched evidence — pipeline re-run), `not-admitted`
+(post-freeze selector match, never executed — task 0919 BC-1/BC-2), and the parallel-only
+`integration-conflict` (rebase conflict retained for manual integration — task 0931 R4,
+[§ Parallel isolation](#parallel-isolation---mode-parallel)).
 The batch verdict: `clean` (all attempted tasks `done`) | `halted` (a failure stopped the batch) |
 `aborted` (cycle or selector error before any run).
 
@@ -421,8 +474,9 @@ written for a batch with nothing to run. The early-exit report carries zero per-
 terminal action runs. A contract test pins this
 (`plugins/sp/tests/dogfood-testing/execution-batch-contract.test.ts`).
 
-**Evidence persistence (worktree batches — task 0720 R3).** A worktree batch's Step 5 report and
-verdict artifacts live in the worktree's own `.spur/run/` while the batch runs — exactly the tree
+**Evidence persistence (worktree batches — task 0720 R3).** Copy-out is mandatory.
+A worktree batch's Step 5 report, verdict artifacts, and the batch's own
+`.spur/run` records live in the worktree while the batch runs — exactly the tree
 create-mode WT-4 deletes. Before any WT-4 removal, persist them into the **invoking** tree, which
 survives removal:
 
@@ -438,13 +492,44 @@ batch can never destroy its own evidence. Reuse mode retains its operator-owned
 persists the Step 5 report under the invoking tree; the reused tree's `.spur/run/` remains the live
 copy while that tree lives on.
 
+**Stage records are worktree-local too (0948 R9, E7 Finding 5).** The persisted report and verdict
+JSONs above are the batch's *summary* evidence. Each task's own per-stage run record
+(`.spur/run/<runId>.md` + `.state.json`, plus gate/answer artifacts) is written inside the
+worktree's `.spur/run/` and **is removed with the worktree** in create mode. A merged batch
+therefore leaves no per-stage run record in the invoking tree unless it is copied out. Anything
+auditing "what did this batch actually run?" must copy those records out **before** WT-4 removal —
+the E7 batch lost exactly this evidence this way. The rule is the same one above: copy out first,
+then remove; a copy failure retains the worktree.
+
+## Step 6 — Batch wrap (`--wrap` / `--next`) (F96 task 0952 R1)
+
+Run **once for the batch**, after the Step 5 report — never per task (dev-operations.md §runall
+agrees; the old "per task" flag-row wording in dev-runall.md was a contradiction, now fixed).
+
+The wrap receives only what it would accept:
+
+1. `vars.tasks` = the JSON-encoded array of batch WBS whose terminal status is `done`. A task that
+   is `failed`/`blocked`/`skipped`/`not-attempted`/`recheck`/`not-admitted` is **excluded** —
+   `wrapup task-resolve` refuses non-done members (wrapup-steps.ts task-resolve), so the driver
+   simply stops handing the wrap tasks it would refuse.
+2. `vars.feature` = the batch feature **only when every task in the frozen batch is `done` or
+   `cancelled`**. Otherwise omit it and print `feature lifecycle not advanced: <n> task(s)
+   unfinished` — advancing a feature while some of its batch tasks are unfinished would overstate
+   completion. Learnings/metrics capture still happens for the done subset.
+3. When the done subset is **empty**, skip the wrap entirely with the reason (e.g. `batch wrap
+   skipped: no done tasks`) instead of invoking wrapup-pipeline on an empty set.
+
+Filtering lives here, in the batch driver — no change to wrapup-pipeline.yaml or wrapup-steps.ts;
+the wrap's refusal of non-done tasks remains the hard invariant.
+
 ## Worktree isolation (`--worktree [<name>]`)
 
 When a batch command (`dev-runall`, `dev-refineall`, `dev-verifyall`) is invoked with
 [`--worktree [<name>]`](flag-glossary.md#flag-worktree), the entire driver loop runs inside an
 isolated git worktree instead of the operator's working directory. This section owns the worktree
-lifecycle for the sequential batch loop. Per-task worktrees and `--mode parallel` isolation stay out
-of scope (task 0142 Slice A); `--worktree --mode parallel` is rejected.
+lifecycle for the sequential batch loop. `--mode parallel` has its own per-task isolation — see
+[§ Parallel isolation](#parallel-isolation---mode-parallel); `--worktree --mode parallel` is
+rejected there (parallel mode already isolates each task in its own worktree).
 
 **Startup ordering (task 0814 R3).** Resolve the selector/status filter and run the quick
 command-aware readiness (the `quickReadiness` contract in `batch-preflight.ts`) **before** creating
@@ -525,6 +610,14 @@ Create one worktree on a new branch cut from the current HEAD's ref (the **base
 `feat/…` branch, not literally `main`). Location follows the sibling-directory convention in
 [worktree-patterns.md](../../branch-workflow/references/worktree-patterns.md):
 
+**Location rule (0948 R9) — never under `.spur/`.** The default root is the **sibling** directory
+(`../<repo>-<command>-<selector-slug>-<short-id>`). A worktree nested under `.spur/` breaks Biome's
+vcs-root detection: `bunx biome check .` inside it reports `Checked 0 files`, so lint/format silently
+no-op for the whole run. Verified in both directions — a sibling worktree reports a non-zero file
+count (`Checked 1076 files` at the time of the fix) while a `.spur/`-nested one reports
+`Checked 0 files`. If a project's tooling needs a custom root, keep it **outside** any path that a
+VCS-root-detecting tool treats as ignorable.
+
 ```bash
 BASE_REF=$(git rev-parse --abbrev-ref HEAD)
 BASE_SHA=$(git rev-parse HEAD)
@@ -537,6 +630,13 @@ git worktree add "../<repo>-<command>-<selector-slug>-<short-id>" -b "$BRANCH" "
   || { git branch -D "$BRANCH"; false; }
 ```
 
+**Worktree root is outside `.spur/` (0948 R9).** The default create path is that
+sibling directory, which sits next to the repository and not under it. Do not
+put the default root at `.spur/worktrees` or any other gitignored path: Biome's
+`vcs.useIgnoreFile` then treats the checkout as empty ("Checked 0 files") and
+the quality gate cannot see the tree. Same class as the eval-pipeline worktree
+move off `.spur/tmp/` (task 0610).
+
 Branch and directory names are derived (command + selector slug + short id); the create path never
 takes an operator-supplied name (R8.3 — no create-with-name; `--worktree <name>` where `<name>` does
 not resolve is an error, not a create).
@@ -743,6 +843,8 @@ if [ -n "$FINAL" ]; then
 fi                                           #   NO prune/remove/branch delete
 git worktree remove "../<worktree-dir>"
 git branch -d "$BRANCH"
+# WT-4c — clean up registry entry in ~/.config/spur/projects.json (task 0924)
+spur projects remove "$WT_PATH" 2>/dev/null || spur projects clean --json 2>/dev/null || true
 # update marker: status = "merged"
 ```
 
@@ -828,7 +930,7 @@ Resume, merge, or discard:
 
   resume:  cd <worktree-path> && <command> --continue --worktree <worktree-path>
   merge:   git checkout <base-ref> && git merge <branch>     # resolve conflicts manually
-  discard: git worktree remove <worktree-path> && git branch -D <branch>
+  discard: git worktree remove <worktree-path> && git branch -D <branch> && spur projects remove <worktree-path>
 ```
 
 The report reuses the [`--next` chain contract](flag-glossary.md#--next-chain-contract) halt-report
@@ -867,8 +969,10 @@ fallback, because `<name>` was explicit and unambiguous intent.
 - **`dev-next`** does not get `--worktree` — it dispatches a single step; per-step isolation is not
   worth the worktree cost. `dev-run` is different: it drives a whole task pipeline, so it does get
   the flag.
-- **`--mode parallel`** is rejected when combined with `--worktree` — per-task worktrees and
-  parallel isolation remain task 0142 Slice A.
+- **`--mode parallel`** is rejected when combined with `--worktree` — parallel mode already
+  isolates each task in its own worktree
+  ([§ Parallel isolation](#parallel-isolation---mode-parallel)), and reuse mode
+  (`--worktree <name>`) has no per-task meaning.
 - **`--mode implement`** is rejected when combined with `--worktree` on `dev-run` — that mode *is*
   the pipeline's implement stage (bug-742) and runs in whatever tree the driver set up; a second
   worktree would split one task's evidence across two trees.
@@ -882,13 +986,6 @@ While the batch runs, corpus writes (`spur task update`, `spur feature update`)
 the merge (WT-4) or manual integration (WT-5) propagates the writes back. Worth one line in each
 command doc so it does not read as a bug.
 
-## Still out of scope
-
-- **Interactive within-step Q&A** — a headless subprocess `agent.run` agent asking the operator a
-  real question. This waits for the workspace module + inbox module + the agent fleet.
-  `sp:super-planner` surfaces blockers/HITL only at the **batch boundary** (between task runs), not
-  from inside a pipeline step.
-
 ## Gate preflight (dogfood 2026-08-21, feature A3)
 
 The A3 batch burned multiple full `spur-check-new` runs (~2 min each) that failed only at the tail
@@ -930,21 +1027,107 @@ time. Before launching a full `spur-check-new`:
 | 0510 R2 (feature-derived strict preflight) | Step 1 — "Feature-derived strict preflight (R2, task 0510)" |
 | 0510 R5 (metadata-only host controller) | Step 3.4 + projected `task show` / trace snippets in Step 1, 2.3, 3.1 |
 
-## Parallel Execution
+## Parallel isolation (`--mode parallel`)
 
-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.
+Under `--mode parallel` (task 0931) every concurrently running task gets its **own create-mode git
+worktree** (`sp/run-<wbs>-<short-id>`, cut from the current base-ref tip). Two task pipelines never
+share a working tree, and the main tree receives no task writes while the batch runs. The per-task
+pipeline (`task-pipeline.yaml`) is unchanged — only where it runs and when dependents may start
+differ. The fan-out decision framework (independence, overlap, budget) stays owned by
+[sp:parallel-execution](../../parallel-execution/SKILL.md); this section owns the isolation +
+integration lifecycle and reuses WT-1…WT-5 by reference — it defines no new worktree mechanics.
 
-**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:
+### Driver loop
 
-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.
-4. Dispatch via `spur agent run` per task (trigger 4: workspace isolation required for parallel fan-out).
-5. Synthesize results per the [result-synthesis contract](../../parallel-execution/references/result-synthesis.md).
+```
+WT-1 once on the main tree (dirty → abort)          # one precheck for the whole batch, not per task
+ready = topo frontier; running = {}; integrated = set()
+while ready or running:
+    while |running| < CONCURRENCY and ready has t with deps(t) ⊆ integrated:
+        WT-2 create  sp/run-<wbs>-<short-id> (branch sp/run-<wbs>-<short-id>) from BASE_REF tip
+        WT-3 marker  {command: dev-runall, selector: <wbs>, batchId: <batchId>}
+                     # WT-3 schema fields (path, branch, baseRef, baseSha) + batchId shared by every marker
+        RUN[t] = (cd "$WT" && spur workflow run task-pipeline.yaml \
+                  --vars '{"wbs":"<wbs>","deferFeatureSync":"true",...}' --async --json)
+    wait for any RUN terminal        # trace poll --follow --timeout 600000; stale-evidence rule applies
+    on done:    WT-3b commit on $BRANCH → integrate(t)
+    on failed:  WT-5 retain (marker retained); failure policy — stop-the-batch default / --keep-going subtree skip
+    on timeout/paused:  WT-5 retain; run is non-terminal (HITL approve pause or poll bound) — stop-the-batch
+                        default / --keep-going subtree skip; the report marks the task `non-terminal`, never `done`
+post: feature sync + refresh per touched feature, one chore(corpus) commit (generated regions, R5)
+emit batch report (per-task outcomes + preflight skips + recovery hints + batch verdict)
+```
 
-**Parallel vs. sequential:** the default is sequential (topo-sort order). Parallel is an opt-in via `--mode parallel` on `sp:super-planner` or `/sp:dev-parallel`. When in doubt, run sequentially — parallel is only beneficial when tasks are provably independent.
+- **Bound (R2).** `CONCURRENCY` is the [`--concurrency <n>`](flag-glossary.md#flag-concurrency)
+  value: default **2**, `n ≥ 1`; at most that many pipelines run at once.
+- **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`.
+- **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.
 
-**See also:** `sp:parallel-execution` skill, `sp:super-planner` agent (parallel mode), `/sp:dev-parallel` command.
+### Integration — rebase, then fast-forward only (R3)
+
+Pipeline-terminal is not terminal under parallel mode. The orchestrator integrates each succeeded
+task from the main tree; integrations are **serialized** (one at a time) in completion order:
+
+```
+integrate(t):
+  git -C "$WT" rebase "$BASE_REF"                # replay onto the CURRENT base tip (re-read per integration)
+  ├─ rebase fails → git -C "$WT" rebase --abort → conflict path (R4) below
+  └─ rebase clean → git checkout "$BASE_REF" → zero-commit guard → git merge --ff-only "$BRANCH"
+                    → WT-4a verdict persist → WT-4b holders → WT-4c registry
+                    → git worktree remove → git branch -d → marker merged
+```
+
+The merge is always `--ff-only`: a base that will not fast-forward after a clean rebase is a
+conflict (R4). The pipeline never creates a merge commit, and no conflict is ever resolved
+automatically. `BASE_REF` is re-read at each integration so a task that finished late rebases over
+everything integrated before it.
+
+### Conflict — retain, report, block (R4)
+
+A failed rebase is aborted (`git -C "$WT" rebase --abort`), which leaves the worktree clean on its
+original branch tip. The worktree and branch are **retained** (WT-5, marker `retained`) and the
+task's outcome is `integration-conflict`. There is no auto-resolution — not for generated paths,
+not for anything. The batch report's row names the worktree path, the branch, and the manual
+commands:
+
+```
+resume:  cd <worktree-path> && git rebase <BASE_REF>   # the operator resolves, never the driver
+merge:   git checkout <BASE_REF> && git merge --ff-only <branch>
+discard: git worktree remove <worktree-path> && git branch -D <branch> && spur projects remove <worktree-path>
+```
+
+The task's dependent subtree is blocked under the normal failure policy (Step 4). Resuming a
+retained parallel batch with `--continue` is future work; today a retained task is resumed
+per-task with `/sp:dev-run <wbs> --worktree <branch>`.
+
+### Generated regions — defer the sync, regenerate once (R5)
+
+The only per-task writer of feature files is the `record` step's post-record feature sync
+(`task-pipeline.yaml`, the `feature-sync-bounded` wrapper). Parallel launches set
+the pipeline var `deferFeatureSync: "true"` (default `"false"`): the record step appends
+`feature sync deferred to batch integration` to the task report and skips the sync, so task
+branches never touch feature files or `docs/features/INDEX.md`. After the last integration, on the
+base ref, the orchestrator runs the same bounded wrapper plus `spur feature refresh --feature <f>`
+once per touched feature and commits the result as one `chore(corpus)` commit. Sequential and
+inline runs keep the default `"false"` and are unchanged. Any rebase conflict — on a generated
+path or any other — is an R4 `integration-conflict`; there is no path-based exception.
+
+**Report.** Step 5's per-task outcome vocabulary gains the parallel-only `integration-conflict`;
+its row carries `worktree`, `branch`, and the manual commands above. Under parallel mode `done`
+means **integrated onto the base ref**, not merely pipeline-terminal.
+
+**`--worktree` is rejected under parallel mode.** `--worktree --mode parallel` fails with
+"parallel mode already isolates each task in its own worktree" — reuse mode (`--worktree <name>`)
+has no per-task meaning (WT-7). Run parallel batches without `--worktree`, or run them sequentially
+with it.
+
+**See also:** `sp:parallel-execution` skill (fan-out decision framework), `sp:super-planner` agent
+(parallel mode), `execution-batch.md` § Worktree isolation (WT-1…WT-7 mechanics).
 
 ## Subagent execution disciplines
 
@@ -956,18 +1139,63 @@ Parallel fan-out and any subagent dispatch obey the four disciplines owned by
 - **Per-role model selection** — the cheapest model that fits each role (`--agent` pins the executor; the discipline picks the model per role).
 - **Never pre-judge the reviewer** — verify/review subagents receive artifact + contract only; no pre-rated severity, no "do not flag X".
 
-## Checkpoint read on batch resume
-
-When resuming an interrupted batch run, read the latest checkpoint from
-`.spur/memory/sessions/` before re-launching:
-
-```bash
-ls -t .spur/memory/sessions/*.md 2>/dev/null | head -1
-```
-
-The checkpoint's YAML frontmatter contains `session_id`, `workflow`, `task_wbs` or `feature_id`,
-`phase`, `last_gate`, `timestamp`, and `next_action`. Surface `next_action` to the operator
-before resuming. The batch driver reads the checkpoint to determine which task was last
-attempted and whether it reached a terminal state. Checkpoints are working memory — the task
-files and the frozen task set are the authoritative state. See
-[cross-cutting.md](cross-cutting.md) § "Session Checkpoint Convention" for the full format.
+## Batch continuation (`--continue`) — identity binding + checkpoint reconciliation (task 0919)
+
+`--continue` resumes an interrupted batch against the batch's **original identity** — never
+whatever a fresh selector resolution or a newer unrelated checkpoint would suggest.
+
+### BC-1 — Re-bind the original frozen identity (R1; AC1/AC5)
+
+Resume identity comes from persisted batch artifacts, in priority order:
+
+1. **WT-3 marker** (worktree batches): the marker's `command` + `selector` and worktree
+   name/branch re-derive the original launch (the WT-6 fallback already resolves this way).
+2. **Persisted batch report** (`.spur/run/worktree-<marker-id>-batch-report.md`, or the
+   invoking-tree Step 5 report of a non-worktree batch): its `Plan:` row IS the frozen ordered
+   membership — the resumed loop iterates exactly those WBS rows.
+
+Re-running the selector is a **validation, not a re-definition**: tasks that newly match the
+selector but are absent from the frozen plan are reported `not-admitted` and never executed —
+freshly listed tasks do not join a resumed batch implicitly. A frozen task whose dependencies
+changed after freeze may invalidate its admission: report `blocked (admission invalidated —
+re-plan required)` and stop for operator decision. The authorized frozen set is never silently
+rewritten (Design).
+
+### BC-2 — Checkpoints are hints (R2; AC2)
+
+Do **not** pick the resume point by mtime alone: `ls -t … | head -1` over `.spur/memory/sessions/`
+is identity-blind, so an unrelated later session (different feature or task) must not become
+authoritative. Select candidate checkpoints by identity first, newest first within the match:
+
+- frontmatter `workflow` is `task-pipeline` (or the batch's own workflow), and
+- `feature_id` equals the batch's feature selector, or `task_wbs` is a member of the frozen plan.
+
+Checkpoints matching neither rule are ignored regardless of recency. A matched checkpoint only
+**hints** where the loop left off (`phase`, `next_action` — surface them to the operator); the
+driver then reconciles against authoritative state before skipping or repeating any task:
+
+- **Skip** requires ALL of: task file status `done` AND a persisted PASS verdict artifact
+  (`.spur/run/<wbs>-verdict.json`, or the worktree-persisted
+  `.spur/run/worktree-<marker-id>-verdicts/<wbs>-verdict.json`) consistent with the task's
+current metadata. Anything less is not a valid skip.
+- **Stale or mismatched evidence** — checkpoint claims done but the verdict artifact is missing,
+  the task file moved backwards, or the recorded `source_commit`/`digest` no longer matches —
+  yields outcome `recheck`: re-run that task's pipeline. When reconciliation cannot proceed
+  safely (lost worktree, unresolvable marker), report `blocked` with the reason. Never treat an
+  unverified claim as done.
+
+### BC-3 — Ordering, write ownership, terminal mix, evidence (R3/R4; AC3/AC4)
+
+Sequential dependency-correct execution remains the default; opt-in `--mode parallel` keeps the
+existing proven-independence requirements with one writer per tree (Step 3). Mixed terminal
+results resume under the unchanged failure policy (Step 4). The Step 5 report keeps per-task
+outcomes distinct — `done | failed | blocked | skipped | not-attempted` plus the resume-only
+`recheck` and `not-admitted` — and the batch verdict stays `halted`/`aborted`: a resumed,
+partially-complete batch is never reported `clean`. Worktree evidence survives cleanup via the
+invoking-tree persistence in Step 5 (task 0720 R3); a persistence failure routes to **WT-5**
+(retain tree + branch), so partial outcomes are never silently lost and never read as a completed
+batch.
+
+See [cross-cutting.md](cross-cutting.md) § "Session Checkpoint Convention" for the canonical
+frontmatter fields and the per-task owner-mismatch semantics
+(`packages/app/src/workflow/checkpoint-contract.ts`).

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

@@ -138,7 +138,7 @@ spur workflow trace "$RUN" --follow --output   # streams the run; --output shows
 burned ~110 min in 47 sleeps and 55 trace polls waiting on one run; ADR-047 mandates pipe-free
 observation). `--follow` is a blocking human-streaming mode (no `--json`); run it in the session
 background and let its exit report the terminal verdict. Use `spur workflow trace "$RUN" --follow
---output` to stream the non-interactive agent output to `.spur/run/<runId>.log` as it lands.
+--output` to stream the non-interactive agent output to `.spur/run/<runId>.md` as it lands.
 
 Synchronous invocation (`--json` without `--async`) is acceptable **only** for short pipelines
 (< 2 min, e.g. precheck-only or a dry-run). Do not use it for the full task pipeline.
@@ -260,7 +260,10 @@ an executor failed — the executor is swappable via config, the pipeline is not
 **When an `agent.run` step fails (timeout, non-zero exit, empty output):**
 
 1. **Diagnose, don't bypass.** Check `spur agent doctor <executor>` — is the agent
-   installed? Is auth present? Then check `.spur/config.yaml` → which role/executor does the
+   installed and usable? Doctor reports usability plus availability provenance (`owner`,
+   `since`, `reason`, snapshot `age`); it is read-only and a stale availability snapshot never
+   enables an executor — `spur agent usage` is the preflight availability signal. Then check
+   `.spur/config.yaml` → which role/executor does the
    run resolve to (`agent.default` role → stage-registry tier ladder)? Which model does that
    executor use? Could that model be out of tokens, rate-limited, or deprecated?
 2. **Switch executors, don't abandon the pipeline.** Override the agent for the run:
@@ -275,12 +278,18 @@ an executor failed — the executor is swappable via config, the pipeline is not
    Manual section fills outside either driver are indistinguishable from pipeline output and bypass
    the provenance contract silently.
 
-**Known diagnostic gap:** `spur agent doctor` checks installation, version, and auth — it
-cannot detect token quota exhaustion, model deprecation, or rate limits. An executor
-configured with `agent: omp` + `model: <provider/model>` passes doctor if `omp` is
+**Known diagnostic gap:** `spur agent doctor` checks installation, version, and usability
+(read-only, with availability provenance from `spur agent usage`; a stale snapshot never
+enables) — it cannot detect mid-run token quota exhaustion, model deprecation, or rate limits.
+An executor configured with `agent: omp` + `model: <provider/model>` passes doctor if `omp` is
 installed, even if the model is unavailable. If an `agent.run` times out with no useful
 diagnostic, suspect the model, not the agent binary.
 
+Executor switching also interacts with run-scoped session policy (coder `reuse`,
+reviewer/planner/scribe `fresh`): see the session-policy summary in
+[cross-cutting.md#inline-default-execution-surface](cross-cutting.md#inline-default-execution-surface);
+this file does not restate that contract.
+
 ## Large tasks and timed-out implement resume (task 0424)
 
 Two obligations when driving a task that may not fit one implement pass.

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

@@ -126,6 +126,17 @@ Batch operation only (`dev-refineall`, `dev-runall`). When a task in the batch
 fails, skip its in-batch dependents and continue the independent ones, instead of the default
 halt-on-first-failure. Never silently retried; the failure is still reported.
 
+### `--concurrency <n>` — parallel batch worker bound
+
+**Anchor:** `#flag-concurrency`.
+
+`dev-runall` under `--mode parallel` (task 0931): 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
+the host has the CPU for it.
+
 ### `--continue` — resume an interrupted batch from checkpoint
 
 **Anchor:** `#flag-continue`.
@@ -248,7 +259,8 @@ the effect are per-command — this flag is a family, not one behavior:
   offered target (rank-1 or the explicit id) and forwards `--auto` to the children. Optional feature
   id names the target instead of offering rank 1.
 - `dev-debug` `[<wbs>]` — **attaches** findings to an existing task. Optional WBS names it.
-- `dev-dogfood` (no value) — **records** run outcomes against the task under test.
+- `dev-dogfood` (no value) — **creates** a new review-template task for the run's findings
+  (`spur task create --template review`); it does not attach to or update the task under test.
 
 ### `--since <ref>` — lower bound on a range
 
@@ -333,7 +345,9 @@ pauses, even under `--auto`.
 **Anchor:** `#flag-max-retry`.
 
 Bound the retry loop on fix-family commands (`dev-dogfood`, `dev-fixall`, `dev-gtd`). After `n` consecutive
-failed fix attempts, stop and ask the operator rather than looping indefinitely.
+failed fix attempts, stop and ask the operator rather than looping indefinitely. On `dev-dogfood`
+the default is `2` (fix mode) and `--max-retry 0` selects observe-only — matching the backing
+`sp:dogfood-testing` skill; the command table and the skill must not drift on this default.
 
 ### `--full` — rewrite a `--next` run as full pipeline
 
@@ -428,8 +442,9 @@ merges but never removes. This keeps the continue-the-work loop stable — after
 `-`**, so `--worktree --auto` is the bare create form and `--agent`/`--feature`/etc. are never
 swallowed as the name. `--worktree=<name>` is the unambiguous spelling. `/sp:dev-next` does not get
 the flag (single _step_; not worth the worktree cost — unlike `dev-run`, which isolates a whole
-task pipeline), `--worktree --mode parallel` is rejected (per-task parallel isolation stays task
-0142), and `--worktree --mode implement` is rejected on `dev-run` (that mode _is_ the pipeline's
+task pipeline), `--worktree --mode parallel` is rejected (parallel mode already isolates each task
+in its own worktree — [execution-batch.md § Parallel isolation](execution-batch.md#parallel-isolation---mode-parallel)),
+and `--worktree --mode implement` is rejected on `dev-run` (that mode _is_ the pipeline's
 implement stage and runs in the driver's tree). The full lifecycle — name resolution, dirty-tree
 precheck, creation or adoption, crash-safe marker, merge-or-retain, and `--continue` re-entry — is
 specified in [execution-batch.md § Worktree isolation](execution-batch.md#worktree-isolation---worktree-name).

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

@@ -72,10 +72,18 @@ reserved for this specific planning/execution split).
 **HITL** (human-in-the-loop) — a workflow state that pauses for explicit operator approval
 before continuing (`hitl.confirm`). A HITL gate is never auto-dismissed by the engine; `--auto`
 can only route *around* one whose objective precondition is already met (see the `--auto`
-routing contract in `cross-cutting.md`).
+routing contract in `cross-cutting.md`). A `decision` option (0911) pins that action's policy:
+`mode: never` forces the human responder, `mode: evidence` lets the optional DecisionMaker answer
+only from verified prior action evidence (deferring otherwise), and absence keeps the 0910
+implicit behavior when `workflow.hitlDecisionMaker` is enabled.
 Avoid: *prompt* (reserved for LLM input text), *interrupt* (implies an exception, not a planned
 pause point).
 
+**DecisionMaker** — optional provider-backed responder for executed `hitl.confirm`/`hitl.select`
+actions (ADR-123), enabled via `workflow.hitlDecisionMaker: true` and `TYPESAFE_API_KEY`.
+Evidence answers clear the answer variable and record `statusVar: accepted/deferred`; unresolved
+cases defer or delegate to the human. Offline readiness: `spur self status`.
+
 **WBS** (work-breakdown-structure ID) — the four-digit task identifier (e.g. `0187`) that
 names a task file and its position in the corpus. WBS IDs are assigned once and never reused.
 Avoid: *task ID* alone (acceptable in prose, but *WBS* is the canonical term when precision