@gobing-ai/spur 0.3.67 → 0.3.68

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

@@ -421,6 +421,23 @@ 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
+create-mode WT-4 deletes. Before any WT-4 removal, persist them into the **invoking** tree, which
+survives removal:
+
+- Write the emitted batch report to `.spur/run/worktree-<marker-id>-batch-report.md`.
+- Copy each attempted task's `.spur/run/<wbs>-verdict.json` from the worktree to
+  `.spur/run/worktree-<marker-id>-verdicts/<wbs>-verdict.json`.
+- Make the report's per-task verdict references use those persisted invoking-tree paths, not the
+  worktree-local paths that removal deletes.
+
+Evidence persistence precedes destructive cleanup: a persistence failure (unreadable verdict file,
+disk-full, missing directory) routes to **WT-5** — the worktree and branch are retained so a green
+batch can never destroy its own evidence. Reuse mode retains its operator-owned tree but still
+persists the Step 5 report under the invoking tree; the reused tree's `.spur/run/` remains the live
+copy while that tree lives on.
+
 ## Worktree isolation (`--worktree [<name>]`)
 
 When a batch command (`dev-runall`, `dev-refineall`, `dev-verifyall`) is invoked with
@@ -671,14 +688,52 @@ git checkout "$BASE_REF"
 [ "$(git rev-list --count "$BASE_SHA..$BRANCH")" -gt 0 ] \
   || { echo "halt: branch carries no commits - nothing to merge" >&2; false; }   # -> WT-5
 git merge --ff-only "$BRANCH"          # FF-only: never rebase, merge-commit, or resolve conflicts
-# if FF succeeded:
+# if FF succeeded — WT-4a evidence persistence (Step 5, task 0720 R3) runs FIRST:
+# persist the batch report + verdict artifacts into the invoking tree's .spur/run/
+# before anything below touches the worktree. Persistence failure routes to WT-5.
+#
+# WT-4b — bounded CWD-holder cleanup (task 0720 R1). Resolve the EXACT absolute
+# worktree path; a relative path or a stale entry matches the wrong processes.
+WT_PATH="$(cd "../<worktree-dir>" && pwd)"
+# Holders = processes with any open fd under the worktree tree (lsof +D walks the
+# tree; CWD holders are the common case but +D also catches open-file holders —
+# over-match errs toward removal success; a plain -t <dir> matches only the
+# directory itself). Orphaned `serve` proof daemons (PPID 1) are exactly this
+# class: they defeat `git worktree remove` (ENOTEMPTY), defeat rm -rf, while
+# `git worktree prune` still deregisters the tree. Note +D is a full-tree walk,
+# so the wait loop below bounds ITERATIONS (6 × 1s ticks + walk cost), not
+# wall-clock.
+HOLDERS="$(lsof -t +D "$WT_PATH" 2>/dev/null | sort -u)"
+if [ -n "$HOLDERS" ]; then
+  kill -TERM $HOLDERS 2>/dev/null            # 1) TERM first, all holders (unquoted — word-split PID list)
+  for _ in 1 2 3 4 5 6; do                   # 2) bounded wait: 6 × 1s ticks
+    sleep 1
+    [ -z "$(lsof -t +D "$WT_PATH" 2>/dev/null)" ] && break
+  done
+  SURVIVORS="$(lsof -t +D "$WT_PATH" 2>/dev/null | sort -u)"
+  if [ -n "$SURVIVORS" ]; then
+    kill -KILL $SURVIVORS 2>/dev/null       # 3) KILL only the survivors (unquoted — one arg per PID)
+    sleep 1
+  fi
+fi
+# 4) Re-query: only an EMPTY holder set may proceed to remove/prune/branch delete.
+FINAL="$(lsof -t +D "$WT_PATH" 2>/dev/null | sort -u)"
+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
+  exit 1                                     # -> WT-5: retain worktree + branch,
+fi                                           #   NO prune/remove/branch delete
 git worktree remove "../<worktree-dir>"
 git branch -d "$BRANCH"
 # update marker: status = "merged"
 ```
 
-On the zero-commit guard firing, fall through to **WT-5** with the halt cause *"branch carries no
-commits — nothing to merge"*: the worktree and branch are retained, never removed (task 0701 R1).
+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
+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
 
@@ -711,14 +766,28 @@ risk losing work); WT-5 retains the worktree and branch whenever FF is impossibl
 Reuse mode is **narrower** than the carve-out (it merges but does not delete the branch), so the
 carve-out text needs no widening.
 
-**Lifecycle-DB disposition (task 0701 R2d).** The worktree has its own `.spur` lifecycle DB, and
-WT-4/WT-5 remove or retain that tree — the DB state does **not** travel with the merge. The
-**committed task file is authoritative**: after a green merge the branch's task files read
-`done`/`testing` while the invoking tree's DB still reports the pre-batch statuses. Re-sync
-explicitly by replaying the recorded terminal transitions in the invoking tree (`spur task update
-<wbs> <status>` per task, then `spur task record <wbs>`), or treat the batch report's per-task
-table as the source of truth. This is a deliberate choice over auto-migrating DB state: the DB is
-per-tree by design and the committed corpus files are the durable record.
+**Lifecycle-DB disposition (task 0701 R2d, amended by 0720).** The worktree has its own `.spur`
+lifecycle DB, and WT-4/WT-5 remove or retain that tree — the DB state does **not** travel with the
+merge. One contract, no alternatives:
+
+- **Committed task files own lifecycle state.** The **committed task file is authoritative**: after
+  a green merge the branch's task files already read `done`/`testing` in the invoking tree; no
+  `spur task update` or `spur task record` replay runs post-merge. Replay is not "one of two
+  options" — it is removed: it writes `updated_at`-only churn and can never restore worktree-only
+  DB rows.
+- **The persisted invoking-tree artifacts own evidence.** The Step 5 batch report at
+  `.spur/run/worktree-<marker-id>-batch-report.md` and the copied verdict JSONs under
+  `.spur/run/worktree-<marker-id>-verdicts/` (written before WT-4 removal) are the batch/verdict
+  record.
+- **Per-worktree lifecycle DB rows intentionally do not travel.** No `task_run_links` import, no
+  cross-database provenance synthesis — the DB is per-tree by design.
+- **No timestamp-only corpus churn.** Post-merge the invoking tree's DB statuses may read stale
+  relative to the committed files; that divergence is accepted, not repaired. Do not run
+  `task update`/`task record` to "catch up" the DB, and do not repair churn with
+  `git checkout -- docs/tasks*/`.
+
+This is a deliberate choice over auto-migrating DB state: the committed corpus files are the durable
+record and the persisted run artifacts are the evidence record.
 
 ### WT-5 — Failure path: retain and report (R5)
 

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

@@ -1,6 +1,6 @@
 ---
 name: inline-pipeline-driver
-description: "Interactive host-session interpreter for task-pipeline.yaml: execute the existing FSM without a workflow agent subprocess while preserving actions, guards, artifacts, and provenance."
+description: "Interactive host-session interpreter for Spur state-machine pipelines: execute the existing FSM without a workflow agent subprocess while preserving actions, guards, artifacts, and provenance."
 see_also:
   - spur-dev
   - execution-workflow
@@ -9,12 +9,13 @@ see_also:
 
 # Inline Pipeline Driver
 
-This driver is the interactive control-inversion path granted by ADR-047. It applies only when an
-interactive `/sp:dev-run --mode full` or sequential `/sp:dev-runall` invocation omits `--agent` (now
-the inline default, 0687 R1) or passes `--agent inline`. A named executor, `--agent auto`, parallel
-batch mode, `spur workflow run`, and `spur agent run` keep the existing subprocess path.
+This driver is the interactive control-inversion path granted by ADR-047. It applies when an
+interactive `/sp:dev-run --mode full`, sequential `/sp:dev-runall`, `/sp:dev-idea`, or
+`/sp:dev-plan` invocation omits `--agent` or passes `--agent inline`. A named executor,
+`--agent auto`, parallel batch mode, `spur workflow run`, and `spur agent run` keep the existing
+subprocess path.
 
-The project runtime definition — `task-pipeline.yaml`, resolved through the two-tier
+The selected project runtime definition — `task-pipeline.yaml` or `idea-pipeline.yaml`, resolved through the two-tier
 project→bundled model (task 0648/0650, never an unbundled runtime path) — remains the sole
 FSM definition. The driver MUST read that file
 at invocation time. It must not copy the state list, actions, guards, or transition order into a
@@ -22,9 +23,9 @@ command, skill, script, or second workflow.
 
 ## Run setup
 
-1. Resolve `<wbs>`, `--auto`, and any explicit `--vars`; read the YAML and overlay its `vars` defaults
-   with those invocation values. An explicit `vars.agent` / `vars.implementAgent` is an executor
-   selection and therefore chooses the subprocess workflow path.
+1. Resolve the command inputs, `--auto`, and any explicit `--vars`; read the selected YAML and overlay
+   its `vars` defaults with those invocation values. 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/`, and use `.spur/run/<run-id>.log` as the run log.
 3. Resolve the host session id from `.spur/context/.session.json`, accepting the normalized hook key
@@ -42,13 +43,14 @@ command, skill, script, or second workflow.
      never per action.
    - **Source of truth** = the CLI projection for layer 1; the YAML parsed in step 1 for layer 2.
      Never hand-copy or hand-derive the state list into the driver, a command, a skill, or a script.
-5. Record lifecycle provenance before entering the FSM:
+5. For task execution only, record lifecycle provenance before entering the FSM:
 
    ```bash
    spur task run-link <wbs> --source inline-full --run-id <run-id> --json
    ```
 
-   This is required for the normal `testing → done` provenance guard. It is not a guard bypass.
+   This is required for the normal `testing → done` provenance guard. Planning pipelines have no
+   task lifecycle link and skip this task-specific action.
 
 ## YAML interpreter
 
@@ -61,12 +63,15 @@ Action semantics come from the YAML and the workflow action contract:
 - `shell` — run the expanded command in the project working tree with resolved vars exported as
   environment variables. A non-zero result follows the action's existing failure policy.
 - `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.
 - `file.read.into-var` — read the declared file into the declared run variable before subsequent
   actions/guards.
 - `hitl.confirm` — under `profile=auto`, follow the YAML's auto-skip transition. Otherwise pause,
   surface the prompt, and resume from the same state with the operator's answer.
-- `agent.run` — execute the action's slash command, native-subagent-first (task 0508). Do not call
-  `spur agent run` and do not re-enter `/sp:dev-run --mode full`. Preserve the YAML options: capture
+- `agent.run` — execute the action's input in the host session. Task execution may use the native
+  subagent eligibility below; idea/plan never dispatch a native subagent unless the operator
+  explicitly requested delegation. Do not call `spur agent run` or re-enter a full pipeline. Preserve the YAML options: capture
   `answerFile`; assert `expectFile`; enforce `requireDiff` against a pre-action git snapshot,
   including the task-scope guard; honor declared error policy. `timeoutMs` is recorded as not
   applicable because the host session has no independent kill boundary.