@gobing-ai/spur 0.3.97 → 0.3.99

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

@@ -530,7 +530,7 @@ pass before the invoking tree is written → WT-5. Without `--task-file` nothing
 The shapes are pinned (task 0975 R1; `record-missing` and citation behavior per 0984): idempotent on re-persist;
 success exits 0 printing
 `{"ok":true,"persisted":<n>,"skipped":[{"id":<run-id>,"reason":"id-exists"|"external-key-conflict"|"record-conflict:<file>"|"record-missing:<file>"|"cited-directory:<name>"|"cited-symlink:<name>"|"cited-non-file:<name>"}]}`
-— an `external-key-conflict` skip leaves the target run unchanged; an `id-exists` replay repairs missing owned artifacts and task links without duplicating them. A
+— 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. An `id-exists` replay repairs missing owned artifacts and task links without duplicating them. A
 `record-conflict:<file>` never overwrites a divergent invoking-tree record and causes the delegate to exit 1, retaining the worktree. A
 `record-missing:<file>` skip is a known `task-lifecycle`/`feature-lifecycle` row with no record file
 at all (its inserted DB row still counts in `persisted` — 0984 R5). Any failure
@@ -626,6 +626,20 @@ resolution runs, the loop executes with the worktree as process cwd, and a termi
 retains after the batch report is emitted. Steps 1–5 themselves are not modified — only their cwd
 differs.
 
+**Per-call tree pinning (task 1058).** A host shell call starts in an arbitrary directory and
+inherits no cwd from the previous call, so "the loop runs with the worktree as process cwd" is a
+bootstrap convenience, never a carried guarantee. Every host command boundary in this lifecycle —
+corpus reads/writes, the WT-3b commit, WT-4's merge and evidence persistence, the WT-4a
+persist-out — re-selects its intended tree within the same call via the canonical per-call pin
+protocol ([inline-pipeline-driver.md](inline-pipeline-driver.md) § "Per-call execution-tree
+pin"): `cd --` to the quoted absolute tree, verify `pwd -P` against the recorded physical tree,
+verify Git top-level and expected branch, then execute the already-resolved Spur invocation. The
+identity is consumed, not re-derived: it is the WT-3 marker's confirmed `path` + `branch` (or the
+resolved worktree's physical path + checked-out branch in reuse mode). The one deliberate tree
+change is WT-4: the terminal merge actions select the **invoking** tree, not the execution tree —
+and pin it explicitly the same way. FF ancestry, marker and cleanup sequencing remain owned by
+1059.
+
 **Portability (R10).** Use portable `git worktree` commands only. Do **not** depend on the Claude
 Code `EnterWorktree`/`ExitWorktree` tools — the `sp` plugin ships to Codex, Gemini CLI, pi, omp, and
 OpenCode. The underlying git mechanics (create / list / remove / prune, sibling-directory naming,
@@ -765,6 +779,10 @@ the tree's own source:
 
     cd "<worktree>" && bun apps/cli/src/index.ts task check <wbs> --json
 
+Run that as a per-call pin subshell (task 1058) — `cd --` plus the `pwd -P` / git-top-level /
+branch identity checks of the canonical protocol (inline-pipeline-driver.md § "Per-call
+execution-tree pin") — rather than relying on a persistent `cd` between host tool calls.
+
 Confirm isolation by making a distinctive change in the worktree and checking that
 the command reflects it.
 
@@ -832,13 +850,19 @@ Reuse mode resolves the marker by the resolved worktree's `path` (not by `comman
 ### 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:
+worktree** — including the generated task files under `docs/tasks*/` and the kanban index. The
+commit runs as a per-call pinned subshell (task 1058): it selects the execution tree inside the
+same call, verifies the WT-3 identity, and never relies on a persistent `cd` or a trailing
+`cd -` to restore the caller's directory:
 
 ```bash
-cd "../<worktree-dir>"
-git add <files-the-batch-wrote>
-git commit -m "<type>(<scope>): <command> <selector> batch writes"
-cd - >/dev/null
+(
+  cd -- "../<worktree-dir>" || { echo "tree missing: expected ../<worktree-dir>" >&2; exit 1; }
+  [ "$(git branch --show-current)" = "$BRANCH" ] \
+    || { echo "branch mismatch: expected $BRANCH, got $(git branch --show-current)" >&2; exit 1; }
+  git add <files-the-batch-wrote>
+  git commit -m "<type>(<scope>): <command> <selector> batch writes"
+)
 ```
 
 The FF-only git merge carries only commits — uncommitted writes in the worktree would be left
@@ -855,18 +879,66 @@ only what it created*):
 
 ```bash
 # 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"
+# back onto the base ref there. Per-call tree pinning (task 1058, § above): every command
+# below selects the INVOKING tree (where the WT-3 marker lives), re-pinned with the canonical
+# per-call pin protocol in its own subshell — never the execution tree. The whole sequence is
+# fail-stop: checkout, guard, ancestry check, merge, landed verify, persistence, and cleanup
+# each stop explicitly. Every tip/ancestry read uses local refs — no fetch runs anywhere:
+MARKER=".spur/run/worktree-<marker-id>.json"
+git checkout "$BASE_REF" \
+  || { echo "WT-4 halt: checkout $BASE_REF failed - nothing merged, marker stays \"active\"" >&2; exit 1; }   # -> WT-5
 # 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
+# ("Already up to date") while merging nothing — the 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 rev-list --count "$BASE_REF..$BRANCH")" -gt 0 ] \
+  || { echo "WT-4 halt: branch carries no commits - nothing to merge" >&2; exit 1; }   # -> WT-5, marker stays "active"
+# Capture the batch tip BEFORE any cleanup or branch work: every later step (landed verify,
+# mergeCommit, retained report) reads this captured value — a removed branch is never queried.
+BATCH_TIP="$(git rev-parse "$BRANCH")" \
+  || { echo "WT-4 halt: cannot read $BRANCH" >&2; exit 1; }
+# Fresh LOCAL base tip, re-read now; the marker's baseSha may be stale and never governs this
+# decision (an advanced-but-ancestor base still FF-merges, a divergent base halts):
+BASE_TIP="$(git rev-parse "$BASE_REF")" \
+  || { echo "WT-4 halt: cannot read $BASE_REF" >&2; exit 1; }
+# Ancestry check immediately before the sole mutation (the FF merge below). Command/read
+# errors are distinguished from ordinary non-ancestry; both fail closed:
+ANCESTRY_RC=0
+git merge-base --is-ancestor "$BASE_TIP" "$BATCH_TIP" || ANCESTRY_RC=$?
+[ "$ANCESTRY_RC" -gt 1 ] \
+  && { echo "WT-4 halt: ancestry check could not run (git exit $ANCESTRY_RC) - failing closed" >&2; exit 1; }
+[ "$ANCESTRY_RC" -eq 1 ] && {
+  echo "WT-4 halt: divergent - batch tip $BATCH_TIP vs base tip $BASE_TIP" >&2
+  git log --oneline "$BASE_TIP..$BATCH_TIP" >&2   # batch-side divergent commits
+  git log --oneline "$BATCH_TIP..$BASE_TIP" >&2   # base-side divergent commits
+  exit 1; }   # -> WT-5: tree + branch retained, marker stays "active"
 git merge --ff-only "$BRANCH"          # FF-only: never rebase, merge-commit, or resolve conflicts
-# if FF succeeded — WT-4a evidence persistence runs FIRST (Step 5, task 0720 R3):
+[ $? -eq 0 ] \
+  || { echo "WT-4 halt: FF-merge failed - the concurrent-writer race survives every precheck; marker stays \"active\"" >&2; exit 1; }   # -> WT-5
+# Landed verification before anything else runs: the captured BATCH_TIP must be an ancestor of
+# the base ref as it now stands (base tips advancing again later stay valid — this binds the
+# merge result, not the end state):
+LANDED_BASE_TIP="$(git rev-parse "$BASE_REF")" \
+  || { echo "WT-4 halt: cannot read landed base tip" >&2; exit 1; }
+git merge-base --is-ancestor "$BATCH_TIP" "$LANDED_BASE_TIP" \
+  || { echo "WT-4 halt: landed verify failed - $BATCH_TIP is not an ancestor of $LANDED_BASE_TIP" >&2; exit 1; }
+# --- Landed from here on. Any halt below is landed-but-incomplete: it records status
+# --- "retained" + mergeCommit "$BATCH_TIP" via write_marker and stops — never a branch query.
+write_marker () {   # $1 = merged | retained; read-modify-write: preserve WT-3 fields (id, command, selector, createdAt, adopted, adoptedAt); jq already assumed by WT-3/task-resolution flows
+  mkdir -p "$(dirname "$MARKER")"
+  if [ -f "$MARKER" ]; then
+    TMP_MARKER="$(mktemp)"
+    jq --arg s "$1" --arg m "$BATCH_TIP" '.status = $s | .mergeCommit = $m' "$MARKER" > "$TMP_MARKER" \
+      || { echo "WT-4 halt: cannot rewrite marker $MARKER" >&2; rm -f "$TMP_MARKER"; exit 1; }
+    mv "$TMP_MARKER" "$MARKER"
+  else
+    printf '{ "baseRef": "%s", "baseSha": "%s", "branch": "%s", "path": "%s", "status": "%s", "mergeCommit": "%s" }\n' \
+      "$BASE_REF" "$BASE_SHA" "$BRANCH" "$WT_PATH" "$1" "$BATCH_TIP" > "$MARKER"
+  fi
+}
+# WT-4a evidence persistence runs FIRST after the landed verify (Step 5, task 0720 R3):
 # persist the batch report + verdict artifacts AND the per-run provenance (task
 # 0975 R1) into the invoking tree before anything below touches the worktree.
-# Any persistence failure routes to WT-5 — the worktree and branch are retained.
+# Any persistence failure routes to WT-5 — landed-but-incomplete: retained marker + mergeCommit.
 WT_PATH="$(cd "../<worktree-dir>" && pwd)"   # hoisted: needed by WT-4a AND WT-4b below
 # WT-4a provenance persist-out (task 0975 R1): copy the worktree DB's run rows plus
 # the .spur/memory/runs/<runId>.md + .state.json records into THIS tree. Run from the main
@@ -880,7 +952,7 @@ WT_PATH="$(cd "../<worktree-dir>" && pwd)"   # hoisted: needed by WT-4a AND WT-4
 # NOT proceed to WT-4b removal:
 SETUP_SCRIPT=plugins/sp/scripts/inline-run-setup.ts; [ -f config/plugin-scripts.json -a -f "$SETUP_SCRIPT" ] || SETUP_SCRIPT="$(superskill script path sp inline-run-setup.mjs 2>/dev/null)"
 bun "$SETUP_SCRIPT" --persist-out --from "$WT_PATH" "${TASK_FILE_ARGS[@]}" \
-  || { echo "halt: worktree run-record persist-out failed - worktree retained (WT-5)" >&2; exit 1; }
+  || { echo "halt: worktree run-record persist-out failed - worktree retained (WT-5)" >&2; write_marker retained; exit 1; }
 #
 # WT-4b — bounded CWD-holder cleanup (task 0720 R1). $WT_PATH above is the EXACT
 # absolute worktree path; a relative path or a stale entry matches the wrong processes.
@@ -911,39 +983,112 @@ if [ -n "$FINAL" ]; then
   PORTS="$(lsof -nP -a -p "$(echo "$FINAL" | paste -sd, -)" -iTCP -sTCP:LISTEN 2>/dev/null \
     | awk 'NR>1 {print $9}' | sort -u | paste -sd' ' -)"
   echo "halt: worktree still held by PID(s): $FINAL ${PORTS:+listening: $PORTS}" >&2
+  write_marker retained                      # landed-but-incomplete: retained + mergeCommit
   exit 1                                     # -> WT-5: retain worktree + branch,
 fi                                           #   NO prune/remove/branch delete
-git worktree remove "../<worktree-dir>"
-git branch -d "$BRANCH"
+# Pre-removal evidence assertion (task 1067 R1, E71 enforcement): refuse to remove the
+# worktree while it still owns evidence absent from (or divergent from) the invoking tree —
+# the D63 landing skipped persist-out and silently lost verdicts + receipts. Task-file
+# WBSes / run ids ride the same TASK_FILE_ARGS resolved for WT-4a (run ids: --run-id <id>).
+CHECK_SCRIPT=plugins/sp/scripts/persist-out-check.ts; [ -f config/plugin-scripts.json -a -f "$CHECK_SCRIPT" ] || CHECK_SCRIPT="$(superskill script path sp persist-out-check.mjs 2>/dev/null)"
+bun "$CHECK_SCRIPT" --from "$WT_PATH" "${TASK_FILE_ARGS[@]}" \
+  || { echo "WT-4 halt: worktree evidence would be abandoned - persist-out missing or stale (WT-5)" >&2; write_marker retained; exit 1; }
+git worktree remove "../<worktree-dir>" \
+  || { echo "WT-4 halt: worktree remove failed after landed merge $BATCH_TIP" >&2; write_marker retained; exit 1; }
+# Branch deletion runs only after the merge landed, persisted, and the worktree is gone —
+# and it is existence-guarded, so a removed branch is never queried. -D over -d: the landed
+# verify already proved the merge landed, so an unmerged-refusal would only block proven-merged cleanup.
+if git rev-parse --verify --quiet "$BRANCH" >/dev/null; then
+  git branch -D "$BRANCH" || { echo "WT-4 halt: cannot delete branch $BRANCH after landed merge $BATCH_TIP" >&2; write_marker retained; exit 1; }
+fi
 # 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"
+# Success marker, written once and only here: status "merged" + mergeCommit "$BATCH_TIP" —
+# after landed verification, required persistence, and cleanup:
+write_marker merged
 ```
 
-On either guard firing — zero-commit branch (task 0701 R1), or surviving CWD holders (task 0720 R1)
-— fall through to **WT-5**: the worktree and branch are retained, never removed. While any holder
-remains, do **not** run `git worktree prune`, `git worktree remove`, or branch deletion. The holder
+Every halt above stops explicitly and falls through to **WT-5** — zero-commit branch (task 0701
+R1), failed checkout, divergent base, failed FF, persist-out failure (task 0975), or surviving CWD
+holders (task 0720 R1). Pre-merge failures leave the marker at `status: active` and the worktree +
+branch untouched. Landed-but-incomplete failures record `status: retained` + `mergeCommit`
+BATCH_TIP: the merge landed, and the retained report reads the captured tip only. While any holder
+remains, do **not** run `git worktree prune`, `git worktree remove`, or branch deletion — only an
+EMPTY holder set may proceed to those steps. The holder
 halt report names every surviving PID; the listening port is best-effort — a CWD holder may own no
 socket, and `lsof` port discovery failing must not hide the PIDs.
 
 #### Reuse mode — merge, retain
 
-The FF-merge runs identically (same `git checkout "$BASE_REF" && git merge --ff-only "$BRANCH"`),
-but then the worktree and branch are **retained**, not removed:
+The fail-stop merge sequence runs identically — same guard, captured `BATCH_TIP`/`BASE_TIP`,
+ancestry check immediately before FF, `git merge --ff-only`, landed verification (per-call pinned
+to the invoking tree, task 1058) — but no WT-4a/4b/4c and no removal: the worktree and branch are
+**retained**. Pre-merge halts leave the marker `active`; a persistence failure after the landed
+merge records `retained` + `mergeCommit`:
 
 ```bash
-git checkout "$BASE_REF"
-git merge --ff-only "$BRANCH"
-# update marker: status = "merged"  (worktree and branch are intentionally NOT removed)
+# Same fail-stop sequence as create mode (zero-commit guard -> BATCH_TIP/BASE_TIP -> ancestry
+# rc check -> git merge --ff-only -> landed verify); local refs only — no fetch.
+MARKER=".spur/run/worktree-<marker-id>.json"
+git checkout "$BASE_REF" \
+  || { echo "WT-4 halt: checkout $BASE_REF failed - nothing merged, marker stays \"active\"" >&2; exit 1; }   # -> WT-5
+[ "$(git rev-list --count "$BASE_REF..$BRANCH")" -gt 0 ] \
+  || { echo "WT-4 halt: branch carries no commits - nothing to merge" >&2; exit 1; }
+BATCH_TIP="$(git rev-parse "$BRANCH")" || { echo "WT-4 halt: cannot read $BRANCH" >&2; exit 1; }
+BASE_TIP="$(git rev-parse "$BASE_REF")" || { echo "WT-4 halt: cannot read $BASE_REF" >&2; exit 1; }
+ANCESTRY_RC=0
+git merge-base --is-ancestor "$BASE_TIP" "$BATCH_TIP" || ANCESTRY_RC=$?
+[ "$ANCESTRY_RC" -gt 1 ] \
+  && { echo "WT-4 halt: ancestry check could not run (git exit $ANCESTRY_RC) - failing closed" >&2; exit 1; }
+[ "$ANCESTRY_RC" -eq 1 ] && {
+  echo "WT-4 halt: divergent - batch tip $BATCH_TIP vs base tip $BASE_TIP" >&2
+  git log --oneline "$BASE_TIP..$BATCH_TIP" >&2
+  git log --oneline "$BATCH_TIP..$BASE_TIP" >&2
+  exit 1; }   # -> WT-5: tree + branch retained, marker stays "active"
+git merge --ff-only "$BRANCH"          # FF-only: never rebase, merge-commit, or resolve conflicts
+[ $? -eq 0 ] \
+  || { echo "WT-4 halt: FF-merge failed - the concurrent-writer race survives every precheck; marker stays \"active\"" >&2; exit 1; }
+LANDED_BASE_TIP="$(git rev-parse "$BASE_REF")" \
+  || { echo "WT-4 halt: cannot read landed base tip" >&2; exit 1; }
+git merge-base --is-ancestor "$BATCH_TIP" "$LANDED_BASE_TIP" \
+  || { echo "WT-4 halt: landed verify failed - $BATCH_TIP is not an ancestor of $LANDED_BASE_TIP" >&2; exit 1; }
+WT_PATH="<resolved-worktree-path>"   # reuse mode: the adopted tree's physical path
+write_marker () {   # $1 = merged | retained; read-modify-write: preserve WT-3 fields (id, command, selector, createdAt, adopted, adoptedAt); jq already assumed by WT-3/task-resolution flows
+  mkdir -p "$(dirname "$MARKER")"
+  if [ -f "$MARKER" ]; then
+    TMP_MARKER="$(mktemp)"
+    jq --arg s "$1" --arg m "$BATCH_TIP" '.status = $s | .mergeCommit = $m' "$MARKER" > "$TMP_MARKER" \
+      || { echo "WT-4 halt: cannot rewrite marker $MARKER" >&2; rm -f "$TMP_MARKER"; exit 1; }
+    mv "$TMP_MARKER" "$MARKER"
+  else
+    printf '{ "baseRef": "%s", "baseSha": "%s", "branch": "%s", "path": "%s", "status": "%s", "mergeCommit": "%s" }\n' \
+      "$BASE_REF" "$BASE_SHA" "$BRANCH" "$WT_PATH" "$1" "$BATCH_TIP" > "$MARKER"
+  fi
+}
+# Step 5 evidence persistence (task 0720 R3) — required BEFORE the success marker:
+if printf 'batch report %s\n' "$BATCH_TIP" > ".spur/run/worktree-<marker-id>-batch-report.md"; then :; else
+  echo "WT-5 halt: persistence failed after landed merge $BATCH_TIP; recovery reads captured tips only" >&2
+  write_marker retained
+  exit 1
+fi
+# Success marker: status "merged" + mergeCommit "$BATCH_TIP" — written once, only after landed verification and required persistence.
+# The worktree and branch are intentionally NOT removed.
+write_marker merged
 ```
 
 The operator supplied the tree, so the operator owns its lifetime. After a green reuse batch
 `baseRef == $BRANCH`, so the same worktree keeps fast-forwarding on the next invocation instead of
 having to be rebuilt — the continue-the-work loop is stable.
 
-**Fast-forward only.** If the base ref has moved since the worktree was created and FF is
-impossible, do **not** rebase, merge-commit, or resolve conflicts — fall through to the retention
-path (WT-5) and report the divergence. The corpus files (`docs/tasks*/`, kanban/index) are
+**Fast-forward only.** `git merge --ff-only` is the sole mutation of the terminal sequence; every
+other step is a read, a check, a persistence write, or a cleanup, and every tip/ancestry read uses
+local refs — no fetch runs anywhere in this lifecycle. If the fresh `BASE_TIP` is not an ancestor of
+`BATCH_TIP`, the ancestry check halts before the merge: the report names both tips and both
+divergent commit ranges (`$BASE_TIP..$BATCH_TIP` and `$BATCH_TIP..$BASE_TIP`) and falls to the
+retention path (WT-5) with the tree and branch retained. A concurrent writer that lands between the
+ancestry check and the merge still trips `--ff-only` — the race survives every precheck, and a
+failed FF leaves the marker at `status: active`. Do **not** rebase, merge-commit, or resolve
+conflicts. The corpus files (`docs/tasks*/`, kanban/index) are
 auto-generated and conflict-prone; automated conflict resolution over generated files is exactly the
 wrong thing to attempt unattended. FF-only means the merge either is trivially correct or does not
 happen.
@@ -952,8 +1097,10 @@ happen.
 `--worktree --auto` batch — it does **not** pause even though it performs a merge and a branch
 deletion. That is the explicit single exception to Auto-Decision Principle #6 (`cross-cutting.md`),
 which otherwise pauses any `--merge` / branch-deletion action regardless of `--auto`. The exception
-is safe because `git merge --ff-only` and `git branch -d` both fail closed (they refuse rather than
-risk losing work); WT-5 retains the worktree and branch whenever FF is impossible or any task fails.
+is safe because `git merge --ff-only` fails closed (it refuses rather than risk losing work), the
+branch deletion runs only after the merge has landed, persisted, and cleaned up — and is
+existence-guarded (`git rev-parse --verify --quiet`), so a removed branch is never queried;
+WT-5 retains the worktree and branch whenever FF is impossible or any task fails.
 Reuse mode is **narrower** than the carve-out (it merges but does not delete the branch), so the
 carve-out text needs no widening.
 
@@ -982,22 +1129,44 @@ record and the persisted run artifacts are the evidence 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"`. 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 —
+On any per-task failure, batch halt, HITL pause that ends the run, or a WT-4 halt, 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). The
+marker records which class of halt occurred (frozen vocabulary):
+
+- **Pre-merge failure** (failed checkout, zero-commit guard, divergent base, failed FF): the merge
+  never landed, so the marker **stays at `status: active`** — the WT-3 marker stands and WT-5 is
+  its disposition. Nothing was merged onto the base ref.
+- **Landed-but-incomplete failure** (persist-out, holder cleanup, or worktree removal failed after
+  a landed merge): the marker records `status: retained` + `mergeCommit` BATCH_TIP — a truthful
+  report that the merge landed. The retained path reads the captured `BATCH_TIP` only; a removed
+  branch is never queried.
+
+The worktree's own `.spur` lifecycle DB is retained with the tree,
+so nothing is lost on either 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:
 
+**Persist-out skip recovery (task 1067 R2, E71).** When evidence was lost to a landing that
+skipped persist-out (or the pre-removal assertion fired too late), verdicts remain derivable
+from the task records — `spur task show <wbs> --json` carries the recorded verdict and its
+proof block, so a lost `<wbs>-verdict.json` is regenerated by re-recording or copying from
+the task store. Feature run/latest receipts are re-runnable, not recovered: rerun the
+feature-verification workflow in the invoking tree —
+`spur workflow run feature-verification.yaml --vars '{"featureId":"<id>"}'` — which rewrites
+the receipt files it owns. Divergent files are never auto-overwritten; reconcile by hand.
+
 ```
 ## Worktree retained — <command> <selector>
 
-**Halt cause:** <one-line cause — batch halted at task <wbs> / non-FF base ref / HITL pause>
+**Halt cause:** <one-line cause — batch halted at task <wbs> / non-FF base ref / HITL pause / landed-but-incomplete cleanup failure>
 **Worktree path:** ../<worktree-dir>
 **Branch:** sp/<command>-<selector-slug>-<short-id>
 **Base ref:** <base-ref> (<base-sha>)
+**Merge state:** pre-merge failure — nothing landed | landed-but-incomplete — mergeCommit <batch-tip-sha>
 
-The worktree and its branch are intact. Nothing was merged onto the base ref.
+The worktree and its branch are intact.
+pre-merge failure: nothing was merged onto the base ref.
+landed-but-incomplete: the batch merge LANDED as <batch-tip-sha> on <base-ref>; retention covers post-merge persistence/cleanup only.
 Resume, merge, or discard:
 
   resume:  cd <worktree-path> && <command> --continue --worktree <worktree-path>
@@ -1030,6 +1199,16 @@ are long and already resumable via `--continue`; auto-deleting is data loss, aut
 partial result presented as a whole. The answer to "what happens if it fails" is "nothing happens,
 and we tell you where the work is."
 
+**Partial worktree-removal recovery is inspection-only.** If a create-mode run halted partway
+through removal (leftover directory, stale registration), the recovery pass gathers facts and
+nothing else: `git worktree list` (is the tree still registered?), `ls` of the path (what remains
+on disk?), and the marker / `~/.config/spur/projects.json` registration state. Before removing
+anything, verify the leftover path is the batch's **owned** path — match it against the marker's
+`path`/`branch` (or the resolved `--worktree <name>` identity), never a guessed sibling directory.
+Recursive deletion of leftover directories that survived `git worktree remove` is **never
+automatic** — it requires explicit operator authorization. No automatic rebase, recovery merge,
+`git worktree prune`, or holder kill runs on this path.
+
 ### WT-6 — `--continue` re-entry (R7)
 
 A `--continue` resume of a batch started with `--worktree` must re-enter the existing worktree via
@@ -1172,7 +1351,7 @@ integrate(t):
   ├─ 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
+                    → git worktree remove → existence-guarded git branch -D → marker merged
 ```
 
 The merge is always `--ff-only`: a base that will not fast-forward after a clean rebase is a

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

@@ -203,7 +203,9 @@ When `--next` is set and implementation succeeds:
 2. **Record provenance** — `spur task run-link <wbs> --source next-auto --json`. Writes a
    `kind: pipeline` entry into `task_run_links` so the `testing → done` provenance guard
    (lifecycle-adapter.ts L106-131) accepts the in-session implementation path. Idempotent:
-   safe to call even when a pipeline link already exists.
+   safe to call even when a pipeline link already exists. Run it from the same cwd as the
+   `task update` calls in step 1 — per-tree DB isolation makes a link from another tree
+   invisible to this tree's guard.
 3. **On a clean transition:** invoke `/sp:dev-verify <wbs> --auto --next` (`--auto` propagates
    down the whole chain). The verify step's `--next` transition to `done` now passes the
    provenance guard because step 2 recorded the link.

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

@@ -17,17 +17,16 @@ patterns, skill-backed, inline) remains in `dev-operations.md`.
 
 Every flag shared by two or more commands has exactly one entry here. This is the single place a
 shared flag's meaning is stated; command argument-hints and table rows cite it and must not
-re-define it. The shared-flag set is derived mechanically from the 28 command argument-hints (a flag
+re-define it. The shared-flag set is derived mechanically from all live `dev-*` command argument-hints (a flag
 counts as shared when it appears in two or more); flags appearing on a single command stay documented
 in that command's body and are not listed here.
 
-**Reference form (mechanically detectable).** A command file points at a glossary entry with a
-markdown link whose link target is the entry's anchor — `[`--next`](#flag-next)`. The anchor is
-always `#flag-<name>` where `<name>` is the flag minus its leading `--` (so `--keep-going` →
-`#flag-keep-going`). The test gate (`command-flag-parity.test.ts`, task 0403) finds these references
-with the regex ``\[`--<flag>`\]\(#flag-`` over each command file — **a shared flag declared without
-this reference fails the build.** Prose-only citations (the flag name mentioned in a sentence but not
-in the link form) do not count; the reference must be the link.
+**Reference form (mechanically detectable).** Each `dev-*` command carries exactly one canonical
+footer link to `../skills/spur-dev/references/flag-glossary.md`, enforced by
+`scripts/commands/validate-commands.ts` (task 0412). Per-flag deep links are not required.
+`command-flag-parity.test.ts` derives shared flags from all live hints and requires exactly one
+canonical glossary entry per shared flag. Each entry retains its `#flag-<name>` anchor, where
+`<name>` is the flag minus its leading `--` (so `--keep-going` → `#flag-keep-going`), for navigation.
 
 **Availability rule.** Two flags are only declared where the underlying capability already exists:
 `--json` where the command already produces a structured result a script could consume; `--auto`

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

@@ -75,6 +75,9 @@ the human/native presentation layer — labels are display addresses only, never
 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/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
+   use `<run-id>-*` names with `.md`/`.json`/`.txt`/`.status` extensions only.
 3. **Authoritative run identity (task 0804 R1, fail-closed).** Persist the run row through the
    internal delegate before any stage executes — this is what makes bound `run.artifact` record
    accept the inline run (0785 R3):
@@ -139,7 +142,10 @@ the human/native presentation layer — labels are display addresses only, never
    safety checks succeed, create/adopt and `cd` into the execution tree; confirm absolute cwd,
    branch, base SHA, and ownership. An invalid/empty target, unsupported mode, ambiguous ownership,
    or stale target stops without creating a tree or discarding work. All subsequent tools, agents,
-   corpus writes, and run artifacts use the confirmed execution tree.
+   corpus writes, and run artifacts use the confirmed execution tree — **re-selected per call, not
+   inherited**: a host shell call starts in an arbitrary directory and carries no cwd from the
+   previous call, so every later call runs inside the **Per-call execution-tree pin** protocol
+   below (task 1058), which consumes the identity confirmed here.
 8. **Publish the workflow inventory (R4), BEFORE reading the YAML.** Resolve the selected workflow
    through the same project/bundled resolver as execution and run
    `spur workflow show <resolved-file> --no-logo --format todo --json`. Validate the projection with
@@ -183,6 +189,12 @@ the human/native presentation layer — labels are display addresses only, never
    This is required for the normal `testing → done` provenance guard. Planning pipelines have no
    task lifecycle link and skip this task-specific action.
 
+   **Run it from the task's execution tree.** Every tree has an isolated `.spur` DB, so a link
+   recorded from the invoking tree never satisfies a worktree's guard — the exact failure that
+   forced audited `--provenance-bypass` on tasks 1029/1030 (E93). Under `--worktree`, enter the
+   worktree first and run this command (and every lifecycle-touching command: `task record`,
+   `task update <wbs> testing|done`) from the worktree root.
+
 ### Idea-pipeline quick start (0887 R1/R2)
 
 Minimum files to read for `/sp:dev-idea` inline runs — then drive `idea-pipeline.yaml`:
@@ -212,6 +224,91 @@ Expected artifacts per stage (all run-scoped under `.spur/run/<run-id>-*`):
 | ready-prepare | `-idea-ready.json` |
 | handoff-finalize | `-idea-handoff.md` |
 
+## Per-call execution-tree pin (task 1058)
+
+A host shell tool call may start in an arbitrary directory; no earlier call's `cd` is input to the
+next call. During inline run `95522d21` that drift silently landed corpus writes in the invoking
+tree instead of the run worktree. Every host-session corpus command — reads, writes, absolute
+section-input files and output artifacts — therefore selects the confirmed execution tree **within
+the same tool call**, in a self-contained subshell. The identity is never re-derived: it is the
+tree path, branch and resolved Spur invocation confirmed at bootstrap isolation (step 7) and, for
+batch worktrees, recorded in the WT-3 marker (execution-batch.md). The resolved invocation is
+field 4 of the dispatch payload — never a bare `spur`.
+
+Template — every host shell call follows this shape; paths are quoted because trees may contain
+spaces:
+
+```bash
+(
+  cd -- "$SPUR_TREE" || { echo "tree missing: expected $SPUR_TREE" >&2; exit 1; }
+  ACTUAL_TREE="$(pwd -P)"
+  [ "$ACTUAL_TREE" = "$SPUR_TREE" ] || { echo "tree mismatch: expected $SPUR_TREE, got $ACTUAL_TREE" >&2; exit 1; }
+  GIT_TOP="$(git rev-parse --show-toplevel)" || exit 1
+  [ "$GIT_TOP" = "$SPUR_TREE" ] || { echo "toplevel mismatch: expected $SPUR_TREE, got $GIT_TOP" >&2; exit 1; }
+  ACTUAL_BRANCH="$(git branch --show-current)"
+  [ "$ACTUAL_BRANCH" = "$SPUR_BRANCH" ] || { echo "branch mismatch: expected $SPUR_BRANCH, got $ACTUAL_BRANCH" >&2; exit 1; }
+  exec <resolved-spur-invocation> task show <wbs> --json   # the already-resolved CLI command
+)
+```
+
+Rules (R1):
+
+- **Pin reads as well as writes.** `task show`, `feature show`, `workflow show` and `task check`
+  use the same subshell — a read from the wrong tree is a wrong answer, not a harmless one.
+- **Validate the returned `filePath`.** A pinned `task show --json` must return a `filePath`
+  inside the expected configured corpus/tree. Configured task folders may intentionally live
+  outside the default `docs/tasks` — check membership in the configured folder set, not one
+  literal path.
+- **Prove sections with a fresh pinned read.** After a section write, re-run a pinned
+  `task show <wbs> --json` and assert the new body there; a heading-only grep is not proof of
+  section contents.
+- **Resolve section input/output paths before changing tree.** `--section <name> --from-file
+  <path>`, `answerFile`/`expectFile` and run artifacts are resolved against the confirmed tree
+  (dispatch field 5) before the subshell `cd`s.
+- **Fail closed before writing.** A failed `cd` or any identity mismatch exits nonzero naming
+  expected vs actual, before the CLI runs — there is no designated exit code; consumers read
+  nonzero and the named expected/actual trees. A PWD assertion alone cannot select a tree: `cd`
+  first, then verify the physical path and repository identity.
+- **Native tool cwd options are additive.** A tool-level cwd/`cd` pin may additionally set the
+  call's directory, but never replaces the identity checks above.
+- **Host-only scope.** Engine `shell` actions already bind `context.workdir`
+  (`packages/app/src/workflow/actions/shell.ts:98`) — leave them alone. No service-wide
+  `process.chdir`, no new public flag, no helper framework.
+
+The `spur …` command examples in this driver (run setup, workflow inventory, `task run-link`,
+fingerprint capture, record/done sequencing) abbreviate the pinned subshell form for readability;
+each executes inside the template above with the confirmed tree, branch and resolved invocation
+substituted. A dispatched subagent inherits the same duty: its own tool calls may each start in
+an arbitrary directory, so every shell call the delegate makes re-pins the execution tree with
+the identity supplied in the dispatch payload — never re-derived.
+
+## Chunked implement dispatch contract (cap-limited worker models, task 1066)
+
+Cap-limited worker executors die on monolithic implement briefs: the output cap is consumed by
+one giant thinking block before any file action lands. Recognized failure signature —
+consecutive implement dispatches end with `stopReason=length` and **zero output** (no tool
+call, no file write), optionally with a `contact_supervisor` call mid-death. The trigger is
+the observed signature, never a model name: any executor that exhibits it is treated as
+cap-limited for the rest of the run.
+
+Before dispatching an `implement` stage to a worker executor:
+
+1. **Chunk the brief.** Split the implement scope into small, independent dispatches ordered
+   by dependency (e.g. test cases → doc rewrite → task sections), one bounded objective per
+   dispatch. Never pack the whole task plan into one dispatch.
+2. **Cap thinking.** Instruct the worker to keep every thinking block under ~150 words and act
+   between thoughts; never plan the whole task in one block.
+3. **Fallback ladder.** A worker still dying with the signature: re-chunk the remaining scope
+   smaller once; still failing → execute the stage host-inline (the driver's inline stage
+   fallback) and record the fallback in the run log.
+
+Evidence (2026-10-02, task 1059 implement stage, runall-D63-2ebbd97c): 4/4 single-shot
+implement dispatches died `stopReason=length` on a 16k-output-cap worker; the same scope in
+three chunked dispatches with the thinking cap succeeded 3/3. See the pitfalls 2026-10-02
+entry and `.spur/memory/runs/runall-D63-2ebbd97c.md`.
+
+## Comprehensive-check retention and evidence (R7/R8)
+
 ## Comprehensive-check retention and evidence (R7/R8)
 
 **R7 — comprehensive checks stay at their owning boundaries.** Quick readiness and plan projection are
@@ -293,7 +390,8 @@ Action semantics come from the YAML and the workflow action contract:
   `verify-verdict`: verdict `PASS`), `proofBinding: current` is honored against a freshly captured
   proof digest — capture it with `bun "$SETUP_SCRIPT" --fingerprint --task-file <task path>
   [--feature-file <feature path>]`, the same entry point used at Run setup, which prints the engine
-  `sha256:<hex>` digest. Run it from the worktree root (cwd feeds the git-tree half of the digest)
+  `sha256:<hex>` digest. Run it inside a per-call pin subshell for the confirmed execution tree
+  (the cwd feeds the git-tree half of the digest)
   and pass the same `--feature-file` the run folded in — omitting it, or running from elsewhere,
   yields a different digest and the mismatch surfaces later as a refused `run.artifact`
   registration — and the run-scoped review-completion marker exists — then appends one provenance
@@ -311,6 +409,10 @@ Action semantics come from the YAML and the workflow action contract:
 
 **Native-subagent dispatch (R2 eligibility, evaluated before each action):**
 
+Before dispatching an `implement` stage to a worker executor, apply the chunked implement
+dispatch contract (§ Chunked implement dispatch contract): chunk the brief, cap thinking
+blocks, and know the fallback ladder before spending a dispatch.
+
 1. The invocation is one of the two interactive inline full-pipeline surfaces (`dev-run --mode full`
    or sequential `dev-runall`) and the resolved selector is inline — i.e. `--agent` **omitted**
    (0687 R1 default) or `--agent inline` passed explicitly (0687 R2 generalized from omit-only).
@@ -388,7 +490,10 @@ boundary, and a delegate left to re-derive them re-derives them against its own
    that invocation and MUST NOT rely on a bare `spur`: a competing `spur` earlier on the delegate's
    PATH otherwise wins. Setting `SPUR_BIN` alone does **not** change bare-command resolution — only
    using the supplied invocation does. Spur-owned scripted calls take it through the existing
-   `--spur-bin` flag rather than a new mechanism.
+   `--spur-bin` flag rather than a new mechanism. A delegate's tool calls may each start in an
+   arbitrary directory, so every shell call the delegate makes re-pins the execution tree per the
+   **Per-call execution-tree pin** protocol using this supplied identity — never an inherited cwd
+   and never a re-derivation.
 5. The **resolved absolute output path** (`answerFile`/`expectFile`, resolved as above) and the
    **owning stage's artifact contract** — for a verify stage, the compact contract below.
 6. **The implement-stage acceptance-evidence requirement** — for the implement stage and any stage
@@ -633,6 +738,8 @@ tasks (0617, 0619) because the sections were hand-written **before** the verdict
    ```bash
    # verdict artifact first (shape: {wbs, verdict, requirements:[{id,status,evidence}], checks:[], source})
    # then the record hop; then re-write Testing/Solution if record's backfill is thinner than intended.
+   # Both calls are per-call pinned (task 1058): the record hop selects the execution tree inside
+   # the same tool call — never through a cwd a previous call happened to leave behind.
    spur task update <wbs> wip --no-lifecycle
    spur task record <wbs> --solution-from-diff --transition testing
    ```