@opengsd/gsd-core 1.12.0 → 1.14.0

package/gsd-core/workflows/quick-batch/steps/worktree-dispatch.md

@@ -0,0 +1,169 @@
+**Step 6: Worktree create + executor dispatch**
+
+This is the batch's MUTATING wave — worktree create/executor dispatch/merge
+are the operations `isolation == "none"` caps to concurrency 1 (row 6),
+unlike planning/research above.
+
+**Auto-degrade on stale fork base (row 38, mirrors `/gsd:quick`'s own #1941
+guard):**
+```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif _gsd_at "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd_run is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; case "$(gsd_run runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@opengsd/gsd-core"'*'}') GSD_IDENTITY_STATUS=ok;; esac; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @opengsd/gsd-core - it is either a different package or an @opengsd/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+if [ "$ISOLATION" = "harness-worktree" ] && [ "${USE_WORKTREES:-true}" != "false" ]; then
+  _QB_SHOULD_DEGRADE=$(gsd_run query worktree.base-check --mode "$ISOLATION" --pick shouldDegrade 2>/dev/null || true)
+  if [ "$_QB_SHOULD_DEGRADE" = "true" ]; then
+    echo "⚠ [#1941] Worktree fork base diverged — auto-degrading quick-batch to sequential mode." >&2
+    USE_WORKTREES=false
+    ISOLATION=none
+  fi
+fi
+gsd_run query dispatch-isolation --raw --force-isolation "$ISOLATION" >/dev/null 2>&1 || true
+```
+
+**Effective concurrency for this MUTATING wave** (`mutating` forces
+`isolation == none` to 1 regardless of `--jobs`/capacity — row 6):
+```bash
+QB_EXEC_CONC_JSON=$(gsd_run quick-batch effective-concurrency --jobs "$JOBS" --task-count "$ITEM_COUNT" --capacity "$CAPACITY" --isolation "$ISOLATION" --mutating --raw)
+EXEC_CONCURRENCY=$(printf '%s' "$QB_EXEC_CONC_JSON" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{const j=JSON.parse(s);process.stdout.write(String(j.concurrency))}catch{process.stdout.write("1")}})')
+```
+
+**Dispatch rounds.** Repeat until no item is eligible-and-not-yet-dispatched
+(bounded by `$ITEM_COUNT` rounds):
+
+1. Re-derive eligibility (also reconciles crash-window/blocked-propagation —
+   safe to call repeatedly, idempotent when nothing changed):
+   ```bash
+   QB_ELIG_JSON=$(gsd_run quick-batch resume --batch "$BATCH_ID" --raw)
+   ```
+   Parse `eligible` (quick ids ready to execute — every dependency already
+   `complete`) and refresh `$BATCH_MANIFEST_JSON` from its `manifest`.
+
+   **Crash-window guard (mirrors `planner-wave.md`'s PLAN.md-existence
+   check one layer earlier — #3677):** `quick-batch resume`'s `eligible` is
+   purely status/dependency-derived; it does NOT know an item already
+   finished executing. A coordinator crash between this step returning
+   (executor committed, `SUMMARY.md` written) and Step 7's merge leaves
+   `BATCH.json` at `pending` with no STATE.md row yet (that row is written
+   only in Step 9) — so on `--resume`, such an item still comes back
+   `eligible` here. Before computing `spawn-plan`, determine which eligible
+   items already have `${item_dir}/${quick_id}-SUMMARY.md` on disk (same
+   `item_dir` derivation via `generate-slug` every other step uses), then
+   let the PURE `quick-batch filter-executed` verb
+   (`filterAlreadyExecuted`, `src/quick-batch-dispatch.cts`) decide which
+   ids are actually safe to spawn — never re-derive that split inline:
+   ```bash
+   EXECUTED_IDS_JSON="[]" # JSON array of quick_ids whose SUMMARY.md already exists on disk this round
+   QB_FILTER_JSON=$(gsd_run quick-batch filter-executed --eligible "$ELIGIBLE_IDS_JSON" --executed "$EXECUTED_IDS_JSON" --raw)
+   ```
+   Parse `spawnEligible` (safe to spawn this round) and `alreadyExecuted`
+   (diagnostic only — report these as "already executed, routing to merge"
+   rather than dispatching them). Replace `$ELIGIBLE_IDS_JSON` with
+   `spawnEligible` before continuing to backpressure below.
+
+   NEVER re-dispatch it into a second worktree for any id `filter-executed`
+   returns in `alreadyExecuted`. It is not lost: Step 7's own mergeable-wave
+   criterion
+   (`gsd-core/workflows/quick-batch/steps/merge-wave.md` Step 1) already
+   picks up any `pending` item with an on-disk `SUMMARY.md` that isn't yet
+   merged, independent of this eligible/spawn list — dropping it here only
+   prevents the duplicate dispatch, it does not remove it from the batch.
+
+2. **Backpressure.** Not every eligible item necessarily spawns this round —
+   cap fan-out at `$EXEC_CONCURRENCY` minus current in-flight count (row
+   27/39):
+   ```bash
+   QB_SPAWN_JSON=$(gsd_run quick-batch spawn-plan --eligible "$ELIGIBLE_IDS_JSON" --capacity "$EXEC_CONCURRENCY" --in-flight "$IN_FLIGHT_COUNT" --raw)
+   ```
+   Parse `spawn` (dispatch these now) and `pending` (leave `pending` in
+   `BATCH.json` — already the case, no write needed; NEVER mark these
+   `failed`, NEVER increase fan-out to compensate).
+
+3. **Create worktrees + dispatch executors, ONE AT A TIME per `spawn` item**
+   (`git worktree add` races on `.git/config.lock` — never simultaneous,
+   `execute-phase.md`'s own discipline):
+
+   For each item in `spawn`, in order:
+
+   ```bash
+   SLUG=$(gsd_run query generate-slug "$description" --raw)
+   ITEM_DIR="${quick_dir}/${quick_id}-${SLUG}"
+   ```
+
+   **`isolation == "harness-worktree"`:** one `Agent()` per message,
+   `run_in_background: true`. Same prompt shape as `/gsd:quick`'s own
+   executor dispatch (Step 6 of `quick.md`) — required_reading, agent skills,
+   `<submodule_commit_guard>` using this project's `$SUBMODULE_PATHS`
+   (identical block, verbatim) — with these differences:
+   ```
+   Agent(
+     prompt="
+   Execute quick-batch item ${quick_id}.
+
+   <required_reading>
+   - ${ITEM_DIR}/${quick_id}-PLAN.md (Plan)
+   - ${STATE_PATH} (Project state — READ ONLY, do not write it)
+   - ./CLAUDE.md or ./.claude/CLAUDE.md (if exists)
+   </required_reading>
+
+   ${AGENT_SKILLS_EXECUTOR}
+
+   <submodule_commit_guard>
+   (same SUBMODULE_PATHS fail-loud guard as /gsd:quick — see gsd-core/workflows/quick.md Step 6)
+   </submodule_commit_guard>
+
+   <constraints>
+   - Execute all tasks in the plan; commit each task atomically
+   - Create summary at: ${ITEM_DIR}/${quick_id}-SUMMARY.md with `status: complete` in frontmatter
+   - NEVER invoke /gsd:quick or any other GSD command — you are a leaf, not a coordinator
+   - NEVER write .planning/quick-batches/${BATCH_ID}/BATCH.json
+   - Do NOT update STATE.md or ROADMAP.md — the orchestrator owns those writes after every item in this dispatch round completes (ADR-1239 single-writer invariant)
+   - Do NOT commit docs artifacts (SUMMARY.md, STATE.md, PLAN.md) — the orchestrator commits them at completion
+   </constraints>
+   ",
+     subagent_type="gsd-executor",
+     model="{executor_model}",
+     {harnessFlag}
+     description="Execute ${quick_id}: ${description}"
+   )
+   ```
+   Record `{agent_id, worktree_path, branch, expected_base, allowed_bases}`
+   from the executor's return into `$QUICK_BATCH_WORKTREE_MANIFEST` (a JSON
+   file, initialized `{"worktrees":[]}` before the first round — same shape
+   `/gsd:quick`'s own `QUICK_WORKTREE_MANIFEST` uses).
+
+   **`isolation == "orchestrator-worktree"`:** GSD creates the worktree
+   (`gsd_run query worktree.create --manifest "$QUICK_BATCH_WORKTREE_MANIFEST" --agent-id ... --path ... --branch ... --base ... --files "$PLAN_FILES" --deletions "$PLAN_DELETIONS"`) then
+   process-spawns the executor via `dispatch-isolation --json --cwd-target
+   --prompt`, exactly as `gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md`'s
+   "orchestrator-worktree" section
+   describes — reuse that mechanism verbatim, substituting this item's
+   `${quick_id}`/`${ITEM_DIR}`/`${quick_id}-PLAN.md` for its
+   `{plan_number}`/`{phase_dir}`/`{plan_file}` placeholders.
+
+   **`isolation == "none"`:** no worktree. Dispatch the executor inline on the
+   primary checkout (same prompt, minus the worktree-only framing), one item
+   at a time — `EXEC_CONCURRENCY` is already forced to 1 in this mode.
+
+   **Durable worktree-recovery persistence (#3677 — `harness-worktree`/
+   `orchestrator-worktree` only, skip for `none`):** immediately after
+   recording `{agent_id, worktree_path, branch, expected_base}` into the
+   EPHEMERAL `$QUICK_BATCH_WORKTREE_MANIFEST` above, ALSO persist the same
+   triple durably onto this item in `BATCH.json`:
+   ```bash
+   gsd_run quick-batch update --batch "$BATCH_ID" --updates '[{"quickId":"'"$quick_id"'","dispatchedWorktree":"'"$worktree_path"'","dispatchedBranch":"'"$branch"'","dispatchedBase":"'"$expected_base"'"}]'
+   ```
+   The ephemeral manifest is a per-process `mktemp` file (same shape
+   `/gsd:quick`'s own `QUICK_WORKTREE_MANIFEST` uses) — it does NOT survive
+   a coordinator crash/restart. A RESUMED coordinator's Step 7
+   (`merge-wave.md`) reads this durable BATCH.json triple as its fallback
+   for any item the crash-window guard above correctly did NOT re-dispatch
+   in the current process.
+
+   > **ORCHESTRATOR RULE — CODEX RUNTIME**: after each `Agent()` call above, wait for it to return before starting the next worktree create.
+
+4. **After every item dispatched this round returns:** verify
+   `${ITEM_DIR}/${quick_id}-SUMMARY.md` exists. If missing, the item stays
+   `pending`/its worktree preserved for diagnosis rather than guessing
+   completion — do not proceed to merge for it this round.
+
+Continue to Step 7 once every eligible item has been dispatched (across
+however many rounds backpressure required) and returned.

package/gsd-core/workflows/quick-batch.md

@@ -0,0 +1,203 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+<purpose>
+Batch several `/gsd:quick`-shaped tasks together (#3676, epic #3344, ADR-1239
+"Quick-batch binding"). ONE coordinator (this workflow) owns every shared
+write — `BATCH.json`, STATE.md, worktree create/merge/cleanup — and never
+delegates them to a leaf. Leaves (planner/researcher/checker/executor/
+verifier) return structured results only; they never invoke `/gsd:quick`,
+never touch `BATCH.json`, and never write STATE.md/ROADMAP.md themselves
+(single-writer invariant).
+
+Dispatch decisions (effective concurrency, deterministic merge order, spawn
+backpressure, failure/verification routing) are computed by the pure
+`quick-batch-dispatch.cts` module (via the `quick-batch` CLI verbs) — this
+workflow never re-derives that logic inline.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-phase-researcher — Researches technical approaches for an item
+- gsd-planner — Creates a plan for one item (`quick-batch` mode)
+- gsd-plan-checker — Reviews one item's plan before execution
+- gsd-executor — Executes one item's plan, commits, creates SUMMARY.md
+- gsd-verifier — Verifies one item's goal achievement
+</available_agent_types>
+
+<process>
+**Step 1: Parse arguments, resolve mode**
+
+```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif _gsd_at "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd_run is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; case "$(gsd_run runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@opengsd/gsd-core"'*'}') GSD_IDENTITY_STATUS=ok;; esac; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @opengsd/gsd-core - it is either a different package or an @opengsd/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+RESPONSE_LANGUAGE=$(gsd_run query config-get response_language --raw --default "" 2>/dev/null || echo "")
+```
+
+**If `response_language` is set:** all user-facing questions/prompts/explanations MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English.
+
+Validate `$ARGUMENTS` through the CLI's own grammar — never re-derive it inline (single source of truth: `parseQuickBatchArgs`, `src/quick-batch-dispatch.cts`). `$ARGUMENTS` is raw, attacker-influenced task text — pass it as ONE quoted argument via `--text` so the shell never word-splits or glob-expands it; `quick-batch parse-args` does the whitespace split itself, in Node, after the shell is done:
+
+```bash
+QB_PARSE_JSON=$(gsd_run quick-batch parse-args --raw --text "$ARGUMENTS")
+QB_PARSE_RC=$?
+if [ $QB_PARSE_RC -ne 0 ]; then
+  echo "$QB_PARSE_JSON" >&2
+  exit 1
+fi
+if [[ "$QB_PARSE_JSON" == @file:* ]]; then QB_PARSE_JSON=$(cat "${QB_PARSE_JSON#@file:}"); fi
+```
+
+Parse `$QB_PARSE_JSON` for `jobs` (`"auto"` or an integer), `validate` (bool), `research` (bool), `resume` (batch id or null). Store as `$JOBS`, `$VALIDATE_MODE`, `$RESEARCH_MODE`, `$RESUME_BATCH_ID`.
+
+Extract the raw task-list text / `--file <path>` from `$ARGUMENTS` (everything that is not `--jobs <v>`, `--validate`, `--research`, `--resume <id>`, or `--file <path>`'s own flag pair).
+
+```bash
+VALIDATE_PARAM=""; if [ "$VALIDATE_MODE" = true ]; then VALIDATE_PARAM="--validate"; fi
+RESEARCH_PARAM=""; if [ "$RESEARCH_MODE" = true ]; then RESEARCH_PARAM="--research"; fi
+INIT=$(gsd_run query init.quick-batch $VALIDATE_PARAM $RESEARCH_PARAM)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+AGENT_SKILLS_PLANNER=$(gsd_run query agent-skills gsd-planner)
+AGENT_SKILLS_EXECUTOR=$(gsd_run query agent-skills gsd-executor)
+AGENT_SKILLS_CHECKER=$(gsd_run query agent-skills gsd-plan-checker)
+AGENT_SKILLS_VERIFIER=$(gsd_run query agent-skills gsd-verifier)
+AGENT_SKILLS_RESEARCHER=$(gsd_run query agent-skills gsd-phase-researcher)
+```
+
+Parse `$INIT` for: `planner_model`, `executor_model`, `checker_model`, `verifier_model`, `researcher_model`, `commit_docs`, `quick_dir`, `quick_batches_dir`, `roadmap_exists`, `planning_exists`.
+
+<!-- #2517 model-omit-on-inherit -->
+
+> **Model omission (#2517).** Every `Agent()` dispatch below (planner, researcher, plan-checker, executor, verifier) MUST omit the `model` parameter entirely when the value it would carry (`planner_model`, `checker_model`, `executor_model`, `verifier_model`, `researcher_model`) is `"inherit"` or empty. An empty value 404s on runtimes without native tier aliases — the default on non-Claude runtimes, where the installer writes `resolve_model_ids:"omit"`. Omitting it inherits the orchestrator's model. See @gsd-core/references/model-profile-resolution.md.
+
+```bash
+STATE_PATH="${quick_dir%/quick}/STATE.md"
+PROJECT_PATH="${quick_dir%/quick}/PROJECT.md"
+USE_WORKTREES=$(gsd_run query config-get workflow.use_worktrees --raw 2>/dev/null || echo "true")
+RUNTIME=$(gsd_run query config-get runtime --default claude --raw 2>/dev/null || echo "claude")
+```
+
+**If `roadmap_exists` is false:** Error — quick-batch requires an active project with ROADMAP.md. Run `/gsd:new-project` first.
+
+If the project uses git submodules, parse `SUBMODULE_PATHS` from `.gitmodules` exactly as `/gsd:quick` does (a fail-loud commit-time guard, applied per item at commit time — see `gsd-core/workflows/quick.md` Step 2 for the identical block, reused verbatim below):
+
+```bash
+if [ -f .gitmodules ]; then
+  SUBMODULE_PATHS=$(git config --file .gitmodules --get-regexp '^submodule\..*\.path$' 2>/dev/null | awk '{print $2}')
+else
+  SUBMODULE_PATHS=""
+fi
+```
+
+**Resolve capacity now (#3676 design row 3-4).** `--jobs auto`/omitted uses this
+value alone; `--jobs N` is capped by it (`min(taskCount, N, capacity)` — the
+`quick-batch effective-concurrency` verb, called per-wave below, does the
+arithmetic; this is only the raw resolve):
+```bash
+CAPACITY=$(gsd_run query dispatch-capacity --raw 2>/dev/null || echo 1)
+```
+
+**Resolve isolation now (row 6, 20-22).** Read
+@gsd-core/references/dispatch-isolation-gate.md and run its `Resolve
+ISOLATION`, `Single-agent dispatch sites`, and `Resolve the harness flag`
+blocks in order; they set `ISOLATION`/`HARNESS_FLAG` via `query
+dispatch-isolation`. `ISOLATION` gates every worktree decision below —
+substitute `{harnessFlag}` in Step 6's `Agent()` with `$HARNESS_FLAG`+comma
+when `ISOLATION = "harness-worktree"`, else empty.
+
+If `USE_WORKTREES` is not `"false"`, sweep orphaned worktrees before dispatching anything (mirrors `/gsd:quick`'s own startup sweep):
+```bash
+if [ "$USE_WORKTREES" != "false" ]; then
+  gsd_run query worktree.reap-orphans 2>/dev/null || true
+fi
+```
+
+Display banner:
+```
+### GSD ► QUICK BATCH
+◆ jobs=${JOBS} validate=${VALIDATE_MODE} research=${RESEARCH_MODE}${RESUME_BATCH_ID:+ resume=${RESUME_BATCH_ID}}
+```
+
+---
+
+**Step 2: Resume or create**
+
+If `$RESUME_BATCH_ID` is set: read and execute `gsd-core/workflows/quick-batch/steps/resume-mode.md`.
+It loads the batch via `quick-batch
+resume`, refuses closed on an unknown batch id or a diverged base revision,
+and sets `$BATCH_ID`/`$BATCH_MANIFEST_JSON` for the steps below. Task-list
+parsing and `quick-batch create` are skipped entirely.
+
+Otherwise: read and execute `gsd-core/workflows/quick-batch/steps/batch-init.md`.
+It parses the task list (inline or `--file`) and creates the
+batch via `quick-batch create`, setting the same `$BATCH_ID`/
+`$BATCH_MANIFEST_JSON` pair.
+
+Either path converges on the same post-condition — continue to Step 3.
+
+---
+
+<!-- gsd:section id="research-phase" when="flag:--research" -->
+If `section_manifest` is `null` or `"research-phase"` is in its `included` list: read and execute `gsd-core/workflows/quick-batch/steps/research-phase.md`. Otherwise skip — do not read the file.
+<!-- /gsd:section -->
+
+---
+
+**Step 4: Per-DAG-layer planning**
+
+Read and execute `gsd-core/workflows/quick-batch/steps/planner-wave.md`. It
+dispatches a planner per eligible item (one `Agent()` per message, full task
+catalog in every prompt), persists parsed `depends_on`/`files_modified` via
+`quick-batch update` after each layer, and — when `$VALIDATE_MODE` — runs the
+per-item plan-checker loop (`gsd-core/workflows/quick-batch/steps/plan-checker-loop.md`)
+before advancing to the next layer.
+
+---
+
+**Step 6: Worktree create + executor dispatch**
+
+Read and execute `gsd-core/workflows/quick-batch/steps/worktree-dispatch.md`.
+Worktree create/executor dispatch is serialized per item (one `git worktree
+add` in flight at a time); already-created worktrees run concurrently up to
+the effective MUTATING-wave concurrency.
+
+---
+
+**Step 7: Deterministic merge**
+
+Read and execute `gsd-core/workflows/quick-batch/steps/merge-wave.md`. Merges
+apply strictly in the wave's original dispatch order (`quick-batch
+merge-eligible`), never completion order.
+
+---
+
+<!-- gsd:section id="verification-wave" when="flag:--validate" -->
+If `section_manifest` is `null` or `"verification-wave"` is in its `included` list: read and execute `gsd-core/workflows/quick-batch/steps/verification-wave.md`. Otherwise skip — do not read the file.
+<!-- /gsd:section -->
+
+---
+
+**Step 9: Completion**
+
+Read and execute `gsd-core/workflows/quick-batch/steps/completion.md`. Calls
+`completeQuickItem` (via `quick-batch complete`) only for a genuinely
+complete item, updates STATE.md, and prints the final batch report.
+
+</process>
+
+<success_criteria>
+- [ ] `--discuss`/`--full` rejected with a usage error before any dispatch
+- [ ] A malformed `--jobs` value rejected before any dispatch
+- [ ] `--resume <batch-id>` skips task-list parsing, dispatches only eligible items
+- [ ] Task list parsed (inline or `--file`, ≥2 items) and batch created otherwise
+- [ ] Planner dispatched per eligible item per DAG layer, full task catalog in prompt, `depends_on`/`files_modified` requested ALWAYS
+- [ ] (--research) Researcher dispatched per item before planning
+- [ ] (--validate) Plan-checker loop runs per item after planning (≤2 iterations)
+- [ ] Worktree create/merge/cleanup serialized; concurrent leaves inside already-created worktrees
+- [ ] `isolation == none` forces a mutating wave's concurrency to 1; a research-only wave is unaffected
+- [ ] Merges apply in deterministic wave order, never completion order
+- [ ] (--validate) Verifier dispatched per item post-merge; `human_needed` never completes the item, `gaps_found` fails it without rollback or retry
+- [ ] A merge_failed/scope_violation item is marked failed with the worktree PRESERVED
+- [ ] `completeQuickItem` called only for genuinely complete items; STATE.md updated; artifacts committed
+</success_criteria>

package/gsd-core/workflows/quick.md

@@ -43,7 +43,7 @@ _GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-pars
 RESPONSE_LANGUAGE=$(gsd_run query config-get response_language --raw --default "" 2>/dev/null || echo "")
 ```
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 
 If `$DESCRIPTION` is empty after parsing, prompt user interactively:
 
@@ -127,9 +127,10 @@ AGENT_SKILLS_PLANNER=$(gsd_run query agent-skills gsd-planner)
 AGENT_SKILLS_EXECUTOR=$(gsd_run query agent-skills gsd-executor)
 AGENT_SKILLS_CHECKER=$(gsd_run query agent-skills gsd-plan-checker)
 AGENT_SKILLS_VERIFIER=$(gsd_run query agent-skills gsd-verifier)
+AGENT_SKILLS_RESEARCHER=$(gsd_run query agent-skills gsd-phase-researcher)
 ```
 
-Parse JSON for: `planner_model`, `executor_model`, `checker_model`, `verifier_model`, `reviewer_model`, `commit_docs`, `branch_name`, `quick_id`, `slug`, `date`, `timestamp`, `quick_dir`, `task_dir`, `roadmap_exists`, `planning_exists`, `response_language`.
+Parse JSON for: `planner_model`, `executor_model`, `checker_model`, `verifier_model`, `reviewer_model`, `researcher_model`, `commit_docs`, `branch_name`, `quick_id`, `slug`, `date`, `timestamp`, `quick_dir`, `task_dir`, `roadmap_exists`, `planning_exists`, `response_language`.
 
 `init.quick` does not emit dedicated `state_path`/`project_path` fields, so derive them from the already-absolute `quick_dir` (#2376 — files handed to a spawned subagent must resolve regardless of that subagent's own cwd):
 ```bash
@@ -286,6 +287,13 @@ If `section_manifest` is `null` or `"research-phase"` is in its `included` list:
 
 **Step 5: Spawn planner (quick mode)**
 
+**Capability gate:**
+```bash
+PLAN_PRE_HOOKS_JSON=$(gsd_run loop render-hooks plan:pre --raw)
+```
+
+**Contribution dispatch (#3778):** read `PLAN_PRE_HOOKS_JSON.activeHooks` directly in context. In registry order, inject only active entries with `kind == "contribution"` and `into == "planner"` into each Quick planner prompt below, using `fragment.inline` verbatim plus resolved `configValues`. Do not paste `rendered`. Empty, inactive, incompatible, or non-planner entries inject nothing and do not error. Reuse this snapshot for revisions; do not render again.
+
 **If `$VALIDATE_MODE`:** Use `quick-full` mode with stricter constraints.
 
 **If NOT `$VALIDATE_MODE`:** Use standard `quick` mode.
@@ -312,6 +320,8 @@ ${AGENT_SKILLS_PLANNER}
 
 **Project skills:** Check .claude/skills/ or .agents/skills/ directory (if either exists) — read SKILL.md files, plans should account for project skill rules
 
+{For each active entry in `PLAN_PRE_HOOKS_JSON` where `kind == "contribution"` and `into == "planner"` (in array order): inject the entry's `fragment.inline` verbatim here, plus its resolved `configValues` when the entry carries them. If no active planner contributions exist, omit this block entirely.}
+
 </planning_context>
 
 <constraints>
@@ -559,7 +569,14 @@ else
 fi
 
 if [ -n "$DIFF_BASE" ]; then
-  CHANGED_FILES=$(git diff --name-only "${DIFF_BASE}..HEAD" -- . ':!.planning' 2>/dev/null | tr '\n' ' ')
+  # #4466: bound the tip at the quick task's own last commit, not HEAD --
+  # QUICK_COMMITS is already the complete, newest-first list of this task's
+  # commits, so its first line is the correct tip. An unbounded `..HEAD`
+  # picks up any later commit landed on the same tree in the window between
+  # this task's commits and this review step (worktree merge-back, a shared
+  # tree, another session) and folds it into this task's own review scope.
+  QUICK_TIP=$(echo "$QUICK_COMMITS" | head -1)
+  CHANGED_FILES=$(git diff --name-only "${DIFF_BASE}..${QUICK_TIP}" -- . ':!.planning' 2>/dev/null | tr '\n' ' ')
 else
   CHANGED_FILES=""
 fi
@@ -619,7 +636,7 @@ Insert after `### Blockers/Concerns` section:
 |---|-------------|------|--------|-----------|
 ```
 
-**Note:** If the table already exists, match its existing column format. If adding `--validate` (or `--full`) to a project that already has quick tasks without a Status column, add the Status column to the header and separator rows, and leave Status empty for the new row's predecessors.
+**Note:** If the table already exists in a legacy (pre-registry) column format, first run `gsd_run quick-tasks-migrate` — the maintainer-decided repair path (#3730) that rewrites the table onto the canonical schema, losslessly bucketing unmapped columns into Description. It is a silent no-op when the table is already canonical or the section is absent, so running it before the first append of every quick task migrates exactly once and never prompts otherwise. After migration, use the canonical column format below.
 
 **7c. Append new row to table:**
 

package/gsd-core/workflows/reapply-patches.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 # Reapply Local Patches Workflow
 
 Invoked by `/gsd:update --reapply` (`commands/gsd/update.md`).
@@ -167,7 +169,7 @@ Check if a `gsd-pristine/` directory exists alongside `gsd-local-patches/`:
 ```bash
 PRISTINE_DIR="$CONFIG_DIR/gsd-pristine"
 ```
-If it exists, the installer saved pristine copies at install time. Use these as the baseline.
+If it exists, the installer saved pristine copies at install time. Use these as the baseline. Both the deterministic verifier and the installer's preserve-check resolve each file's snapshot at its canonical path first and, when that misses, by the SHA-256 recorded in `pristine_hashes` — so a snapshot stored at a legacy path (for example, without the `gsd-core/` prefix an earlier release dropped) is still found and, on the next update, relocated to its canonical path (#4145). When no snapshot resolves under `gsd-pristine/`, the deterministic verifier additionally falls back to Option A's git-history walk itself (read-only, same recorded-hash match), which is what keeps Step 5a coverage non-zero on multi-version updates where the hash-validated regeneration had nothing it could promote (#4135).
 
 ### Option C: No baseline available (two-way fallback)
 If neither git history nor pristine snapshots are available, fall back to two-way comparison — but with **strengthened heuristics** (see Step 3).
@@ -190,6 +192,58 @@ If neither git history nor pristine snapshots are available, fall back to two-wa
 
 ## Step 4: Merge each file
 
+### Step 4 pre-flight: classify superseded customizations (#4136)
+
+Before merging anything, run the deterministic classifier. It computes, per backed-up file,
+whether the user's added lines (diff of the backup against the hash-validated pristine
+baseline) are ALREADY present verbatim in the newly installed version — i.e. upstream
+adopted the customization. That is the only ground on which the `Incorporated` status
+below is valid. Never conclude `Incorporated` from a signature line, a heading, or general
+resemblance: the classifier excludes structural/trivial lines and requires every
+significant user-added line to be present, because a false `Incorporated` silently retires
+a live customization.
+
+```bash
+PRISTINE_DIR="${CONFIG_DIR}/gsd-pristine"
+
+# Build args as a bash array so paths with spaces survive expansion intact.
+CLASSIFY_ARGS=(
+  --patches-dir "$PATCHES_DIR"
+  --config-dir  "$CONFIG_DIR"
+)
+if [ -d "$PRISTINE_DIR" ]; then
+  CLASSIFY_ARGS+=(--pristine-dir "$PRISTINE_DIR")
+fi
+CLASSIFY_ARGS+=(--classify --json)
+
+# Informational: exits 0. The binding gate is Step 5a's post-merge verification run.
+CLASSIFY_OUTPUT="$(node "${GSD_HOME}/gsd-core/bin/verify-reapply-patches.cjs" "${CLASSIFY_ARGS[@]}")"
+INCORPORATED_FILES="$(echo "$CLASSIFY_OUTPUT" | node -e "const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));(d.incorporated_files||[]).forEach(f=>process.stdout.write(f+'\n'))")"
+```
+
+**For every file in `INCORPORATED_FILES`:**
+
+- **Do NOT merge it. Do NOT re-apply its diff.** Leave the newly installed file exactly as
+  shipped — the user's customization is already in it. Re-grafting the diff onto a version
+  that already contains it duplicates the content (both copies run; a stale graft can
+  contradict a richer native upstream step that replaced it).
+- Report the per-file status `Incorporated` — "Already in upstream v{version}" — in the
+  Step 3 summary and the Step 7 report.
+- No Hunk Verification Table rows are required for these files (nothing was merged); the
+  classifier's structured output is the evidence. If EVERY backed-up file is Incorporated,
+  still emit the table with a header row and a single note line naming the incorporated
+  files, so the Step 5b absent-table halt is not tripped. Step 5a passes these files
+  without special-casing — every user-added line is present in the untouched install.
+- This is what ends the re-graft cycle: because the installed file stays identical to what
+  the release ships, the next update's hash comparison no longer flags it as modified, and
+  the file drops out of `gsd-local-patches/` on the next cycle.
+
+Files NOT in `INCORPORATED_FILES` — reported `needs_merge` (with the lines still missing
+from the new version) or `unknown` (no confirmable pristine baseline) — take the normal
+merge paths below, unchanged. If the classifier cannot run at all (e.g. `GSD_HOME`
+unset), fall back to merging every file as before; never report `Incorporated` without the
+classifier's structured confirmation.
+
 For each file in `backup-meta.json`:
 
 1. **Read the backed-up version** (user's modified copy from `gsd-local-patches/`)
@@ -207,6 +261,9 @@ Compare the three versions to isolate changes:
 - Sections changed only by upstream → accept upstream version
 - Sections changed by both → flag as CONFLICT, show both, ask user
 - Sections unchanged by either → use new version (identical to all three)
+- User-added content already present verbatim in the new version → already incorporated
+  upstream — do NOT re-apply it (the file-level outcome is `Incorporated` when ALL
+  user-added content is thus present, as determined by the Step 4 pre-flight classifier)
 
 ### Two-way merge (fallback when no baseline)
 
@@ -263,7 +320,7 @@ After writing each merged file, verify that user modifications survived the merg
 6. **Report status per file:**
    - `Merged` — user modifications applied cleanly (show summary of what was preserved)
    - `Conflict` — user reviewed and chose resolution
-   - `Incorporated` — user's modification was already adopted upstream (only valid when pristine baseline confirms this)
+   - `Incorporated` — user's modification was already adopted upstream (only valid when pristine baseline confirms this — determined exclusively by the Step 4 pre-flight classifier's `incorporated_files`, never by inspection)
 
 **Never report `Skipped — no custom content`.** If a file is in the backup, it has custom content.
 
@@ -305,9 +362,27 @@ VERIFY_STATUS=$?
 DRIFTED_COUNT="$(echo "$VERIFY_OUTPUT" | node -e "const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));process.stdout.write(String(d.drifted||0))")"
 DRIFTED_FILES="$(echo "$VERIFY_OUTPUT"  | node -e "const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));(d.drifted_files||[]).forEach(f=>process.stdout.write(f+'\n'))")"
 NO_BASELINE_COUNT="$(echo "$VERIFY_OUTPUT" | node -e "const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));process.stdout.write(String(d.no_baseline||0))")"
-NO_BASELINE_FILES="$(echo "$VERIFY_OUTPUT"  | node -e "const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));(d.no_baseline_files||[]).forEach(f=>process.stdout.write(f+'\n'))")"
+NO_BASELINE_FILES="$(echo "$VERIFY_OUTPUT" | node -e "const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));(d.no_baseline_files||[]).forEach(f=>process.stdout.write(f+'\n'))")"
+BASELINE_COVERED="$(echo "$VERIFY_OUTPUT" | node -e "const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));process.stdout.write(String(d.baseline_covered||0))")"
+CHECKED_COUNT="$(echo "$VERIFY_OUTPUT" | node -e "const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));process.stdout.write(String(d.checked||0))")"
 ```
 
+**Baseline coverage headline (#4135)** — BEFORE any pass/fail statement, print the coverage
+N-of-M line. A run where 12 of 13 files were not diff-verified must never present the same way
+as a fully-verified one:
+
+```text
+Baseline coverage: {BASELINE_COVERED} of {CHECKED_COUNT} file(s) verified against a pristine
+baseline ({CHECKED_COUNT - BASELINE_COVERED} unverified)
+```
+
+The verifier also reports this on every run (JSON field `baseline_covered`; the human summary
+leads with the same line). Operators who want the gate itself to fail on low coverage (cautious
+environments) pass the opt-in strict flag when invoking the verifier:
+`--min-baseline-coverage <fraction between 0 and 1>` — below the threshold the verifier exits
+with code 3 (a real content failure still exits 1 and outranks it). Without the flag the
+default advisory posture is unchanged.
+
 **If `NO_BASELINE_COUNT` is greater than 0**, emit an advisory warning (non-blocking — the gate still exits 0 for these files). Do NOT halt:
 
 ```text
@@ -437,6 +512,7 @@ Ask user:
 - [ ] No file classified as "no custom content" or "SKIP" — every backed-up file is definitionally modified
 - [ ] Three-way merge used when pristine baseline available (git history or gsd-pristine/)
 - [ ] User modifications identified and merged into new version
+- [ ] Superseded customizations classified `Incorporated` by the deterministic pre-flight classifier (pristine-confirmed) and not re-grafted
 - [ ] Conflicts surfaced to user with both versions shown
 - [ ] Status reported for each file with summary of what was preserved
 - [ ] Post-merge verification checks each file for dropped hunks and warns if content appears missing

package/gsd-core/workflows/remove-phase.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Remove an unstarted future phase from the project roadmap, delete its directory, renumber all subsequent phases to maintain a clean linear sequence, and commit the change. The git commit serves as the historical record of removal.
 </purpose>

package/gsd-core/workflows/remove-workspace.md

@@ -19,7 +19,7 @@ INIT=$(gsd_run query init.remove-workspace "$WORKSPACE_NAME")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 
 Parse JSON for: `workspace_name`, `workspace_path`, `has_manifest`, `strategy`, `repos`, `repo_count`, `dirty_repos`, `has_dirty_repos`.
 

package/gsd-core/workflows/resume-project.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <trigger>
 Use this workflow when:
 - Starting a new session on an existing project
@@ -25,10 +27,12 @@ INIT=$(gsd_run query init.resume)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
-Parse JSON for: `state_exists`, `roadmap_exists`, `project_exists`, `planning_exists`, `has_interrupted_agent`, `interrupted_agent_id`, `commit_docs`.
+Parse JSON for: `state_exists`, `roadmap_exists`, `project_exists`, `planning_exists`, `requirements_exists`, `init_incomplete`, `has_interrupted_agent`, `interrupted_agent_id`, `commit_docs`.
+
+**If `init_incomplete` is true (#4040 — interrupted bootstrap):** `.planning/` exists but initialization never finished — one or more of `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md` were never created. This is NOT a STATE.md-reconstruction case (there is no project history to reconstruct from). Route to initialization recovery: resume `/gsd:new-project`, which continues from the first missing artifact and keeps the existing PROJECT.md and any already-created artifacts. Do not proceed to load_state.
 
 **If `state_exists` is true:** Proceed to load_state
-**If `state_exists` is false but `roadmap_exists` or `project_exists` is true:** Offer to reconstruct STATE.md
+**If `state_exists` is false but `roadmap_exists` or `project_exists` is true (and `init_incomplete` is false):** Offer to reconstruct STATE.md
 **If `planning_exists` is false:** This is a new project - route to /gsd:new-project
 </step>