msd-core/gsd-core/workflows/execute-phase.md

Execute all plans in a phase using wave-based parallel execution. Orchestrator stays lean — delegates plan execution to subagents.

<core_principle> Orchestrator coordinates, not executes. Each subagent loads the full execute-plan context. Orchestrator: discover plans → analyze deps → group waves → spawn agents → handle checkpoints → collect results. </core_principle>

<runtime_compatibility> Subagent spawning is runtime-specific:

• Claude Code: Uses Agent(subagent_type="gsd-executor", ...) — blocks until complete, returns result
• Copilot: Subagent spawning does not reliably return completion signals. Default to sequential inline execution: read and follow execute-plan.md directly for each plan instead of spawning parallel agents. Only attempt parallel spawning if the user explicitly requests it — and in that case, rely on the spot-check fallback in step 3 to detect completion.
• Other runtimes: If Agent/agent tool is unavailable, use sequential inline execution as the fallback. Check for tool availability at runtime rather than assuming based on runtime name.

Fallback rule: If a spawned agent completes its work (commits visible, SUMMARY.md exists) but the orchestrator never receives the completion signal, treat it as successful based on spot-checks and continue to the next wave/plan. Never block indefinitely waiting for a signal — always verify via filesystem and git state. </runtime_compatibility>

<required_reading> Read STATE.md before any operation to load project context. @/.claude/gsd-core/references/agent-contracts.md @/.claude/gsd-core/references/context-budget.md @~/.claude/gsd-core/references/gates.md </required_reading>

<available_agent_types> These are the valid GSD subagent types registered in .claude/agents/ (or equivalent for your runtime). Always use the exact name from this list — do not fall back to 'general-purpose' or other built-in types:

• gsd-executor — Executes plan tasks, commits, creates SUMMARY.md
• gsd-verifier — Verifies phase completion, checks quality gates
• gsd-planner — Creates detailed plans from phase scope
• gsd-phase-researcher — Researches technical approaches for a phase
• gsd-plan-checker — Reviews plan quality before execution
• gsd-debugger — Diagnoses and fixes issues
• gsd-codebase-mapper — Maps project structure and dependencies
• gsd-integration-checker — Checks cross-phase integration
• gsd-nyquist-auditor — Validates verification coverage
• gsd-ui-researcher — Researches UI/UX approaches
• gsd-ui-checker — Reviews UI implementation quality
• gsd-ui-auditor — Audits UI against design requirements </available_agent_types>

Parse `$ARGUMENTS` before loading any context:

• First positional token → PHASE_ARG
• Optional --wave N → WAVE_FILTER
• Optional --gaps-only keeps its current meaning
• Optional --cross-ai → CROSS_AI_FORCE=true (force all plans through cross-AI execution)
• Optional --no-cross-ai → CROSS_AI_DISABLED=true (disable cross-AI for this run, overrides config and frontmatter)

If --wave is absent, preserve the current behavior of executing all incomplete waves in the phase.

Load all context in one call:

_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}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
INIT=$(gsd_run query init.execute-phase "${PHASE_ARG}")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
AGENT_SKILLS=$(gsd_run query agent-skills gsd-executor)

Parse JSON for: executor_model, verifier_model, commit_docs, parallelization, branching_strategy, branch_name, phase_found, phase_dir, phase_number, phase_name, phase_slug, plans, incomplete_plans, plan_count, incomplete_count, state_exists, roadmap_exists, phase_req_ids, response_language.

Model resolution: If executor_model is "inherit", omit the model= parameter from all Agent() calls — do NOT pass model="inherit" to Agent. Omitting the model= parameter causes Claude Code to inherit the current orchestrator model automatically. Only set model= when executor_model is an explicit model name (e.g., "claude-sonnet-4-6", "claude-opus-4-7").

If response_language is set: Include response_language: {value} in all spawned subagent prompts so any user-facing output stays in the configured language.

Read runtime/worktree config and fail closed before any executor dispatch:

RUNTIME=$(gsd_run query config-get runtime --default claude 2>/dev/null || echo "claude")
USE_WORKTREES=$(gsd_run query config-get workflow.use_worktrees 2>/dev/null || echo "true")
EXECUTOR_STALL_INTERVAL_MINUTES=$(gsd_run query config-get executor.stall_detect_interval_minutes 2>/dev/null || echo "5")
EXECUTOR_STALL_THRESHOLD_MINUTES=$(gsd_run query config-get executor.stall_threshold_minutes 2>/dev/null || echo "10")

if [ "$RUNTIME" = "codex" ] && [ "$USE_WORKTREES" != "false" ]; then
  echo "FATAL: Codex execute-phase worktree isolation is unsupported. Set workflow.use_worktrees=false or use a runtime with Agent isolation=\"worktree\" support." >&2
  exit 1
fi
# Sweep orphaned locked worktrees from prior crashed sessions before spawning executors (#3707).
[ "$USE_WORKTREES" != "false" ] && gsd_run query worktree.reap-orphans 2>/dev/null || true
# Auto-degrade to sequential if HEAD has diverged from the worktree fork base (#683).
# Only applies to Claude Code (isolation="worktree" is Claude-Code-specific).
if [ "$RUNTIME" = "claude" ] && [ "$USE_WORKTREES" != "false" ]; then
  _SHOULD_DEGRADE=$(gsd_run query worktree.base-check --pick shouldDegrade 2>/dev/null || true)
  if [ "$_SHOULD_DEGRADE" = "true" ]; then
    _DEGRADE_MSG=$(gsd_run query worktree.base-check --pick message 2>/dev/null || true)
    [ -n "$_DEGRADE_MSG" ] && printf '%s\n' "$_DEGRADE_MSG" >&2
    USE_WORKTREES=false
  fi
fi

Codex maps subagents to spawn_agent, which has no direct Codex mapping for Claude Code's isolation="worktree" parameter. Failing closed prevents main-checkout edits while the workflow believes agents are isolated.

If the project uses git submodules, worktree isolation is unsafe only when a plan touches a submodule path — the executor commit protocol cannot correctly handle submodule commits inside isolated worktrees. The previous behavior unconditionally disabled worktree isolation whenever .gitmodules existed, which penalised every plan in a submodule project even when the plan was nowhere near a submodule. Compute submodule paths once and intersect them per-plan with the plan's declared files_modified frontmatter.

# Parse submodule paths from .gitmodules once (empty if no .gitmodules).
# SUBMODULE_PATHS is a newline-separated list of repo-relative paths.
if [ -f .gitmodules ]; then
  SUBMODULE_PATHS=$(git config --file .gitmodules --get-regexp '^submodule\..*\.path$' 2>/dev/null | awk '{print $2}')
else
  SUBMODULE_PATHS=""
fi

SUBMODULE_PATHS is exported to the execute_waves step, where the per-plan decision actually happens (see "Per-plan worktree decision" sub-step inside execute_waves). The decision is per-plan because different plans in the same wave can touch different files — only plans whose paths intersect a submodule must drop worktree isolation; plans nowhere near a submodule keep parallel isolation.

When USE_WORKTREES (project-level) is false, all executor agents run without isolation="worktree" — they execute sequentially on the main working tree instead of in parallel worktrees. The per-plan decision below has no effect when worktrees are project-disabled.

USE_WORKTREES is also automatically set to false for the duration of a run when worktree base-check detects that the orchestrator HEAD has diverged from the worktree fork base (the #683 condition — e.g. an unmerged milestone or feature branch). This check runs only when RUNTIME=claude because isolation="worktree" is a Claude Code-specific feature; other runtimes do not use it. The auto-degrade prints a one-line warning to stderr and falls through to the sequential path so executors do not hit the exit-42 worktree-branch-check halt. To restore parallel worktree execution, set worktree.baseRef:"head" in .claude/settings.local.json (or run gsd-tools worktree set-baseref) — this makes the fork base track the live HEAD instead of a fixed remote ref. The worktree-branch-check exit-42 guard inside each executor remains in place as a backstop.

Read context window size for adaptive prompt enrichment:

CONTEXT_WINDOW=$(gsd_run query config-get context_window 2>/dev/null || echo "200000")

When CONTEXT_WINDOW >= 500000 (1M-class models), subagent prompts include richer context:

• Executor agents receive prior wave SUMMARY.md files and the phase CONTEXT.md/RESEARCH.md
• Verifier agents receive all PLAN.md, SUMMARY.md, CONTEXT.md files plus REQUIREMENTS.md
• This enables cross-phase awareness and history-aware verification

When CONTEXT_WINDOW < 200000 (sub-200K models), subagent prompts are thinned to reduce static overhead:

• Executor agents omit extended deviation rule examples and checkpoint examples from inline prompt — load on-demand via @~/.claude/gsd-core/references/executor-examples.md
• Planner agents omit extended anti-pattern lists and specificity examples from inline prompt — load on-demand via @~/.claude/gsd-core/references/planner-antipatterns.md
• Core rules and decision logic remain inline; only verbose examples and edge-case lists are extracted
• This reduces executor static overhead by ~40% while preserving behavioral correctness

If phase_found is false: Error — phase directory not found. If plan_count is 0: Error — no plans found in phase. If state_exists is false but .planning/ exists: Offer reconstruct or continue.

When parallelization is false, plans within a wave execute sequentially.

Runtime detection for Copilot: Check if the current runtime is Copilot by testing for the @gsd-executor agent pattern or absence of the Agent() subagent API. If running under Copilot, force sequential inline execution regardless of the parallelization setting — Copilot's subagent completion signals are unreliable (see <runtime_compatibility>). Set COPILOT_SEQUENTIAL=true internally and skip the execute_waves step in favor of check_interactive_mode's inline path for each plan.

REQUIRED — Sync chain flag with intent. If user invoked manually (no --auto), clear the ephemeral chain flag from any previous interrupted --auto chain. This prevents stale _auto_chain_active: true from causing unwanted auto-advance. This does NOT touch workflow.auto_advance (the user's persistent settings preference). You MUST execute this bash block before any config reads:

# REQUIRED: prevents stale auto-chain from previous --auto runs
if [[ ! "$ARGUMENTS" =~ --auto ]]; then
  gsd_run query config-set workflow._auto_chain_active false || true
fi

Resolve MVP_MODE once via the centralized phase.mvp-mode query verb (precedence chain: CLI flag → ROADMAP **Mode:** mvp → workflow.mvp_mode config → false):

MVP_FLAG_ARG=""
if [[ "$ARGUMENTS" =~ (^|[[:space:]])--mvp([[:space:]]|$) ]]; then MVP_FLAG_ARG="--cli-flag"; fi
MVP_MODE=$(gsd_run query phase.mvp-mode "${PHASE_NUMBER}" $MVP_FLAG_ARG --pick active)
TDD_MODE=$(gsd_run query config-get workflow.tdd_mode 2>/dev/null || echo "false")

Before trusting `STATE.md` or dispatching any executor, derive `CURRENT_PLAN_ID` from the active incomplete plan in `INIT`, then search recent history: ```bash CURRENT_PLAN_ID="{phase_number}-{plan_padded}" SUMMARY_PATH="{phase_dir}/{plan_padded}-SUMMARY.md" PLAN_COMMITS=$(git log --oneline --grep="${CURRENT_PLAN_ID}" -30) ``` If production commits exist and `SUMMARY.md is missing`, stop before spawning a new executor; continuing risks duplicate work and stale `STATE.md`/ROADMAP progress. Offer these recovery options: - `close out manually` — inspect commits, write SUMMARY.md, then update STATE/ROADMAP. - `re-execute from scratch` — revert or supersede partial commits before dispatch. - `mark-and-skip` — record the anomaly and move on only with explicit confirmation.

MVP+TDD gate. Task-scoped enforcement runs inside plan execution (immediately before each implementation step), where TASK_FILE, PLAN_ID, and TASK_ID are defined. Keep the same predicate and RED-commit contract:

if [ "$MVP_MODE" = "true" ] && [ "$TDD_MODE" = "true" ]; then
  IS_BEHAVIOR_ADDING=$(gsd_run query task.is-behavior-adding "$TASK_FILE" --pick is_behavior_adding)
  if [ "$IS_BEHAVIOR_ADDING" = "true" ]; then
    RED_COMMIT=$(git log --oneline --grep="^test(${PHASE_NUMBER}-${PLAN_ID}):" -- "**/*.test.*" "**/*.spec.*" "tests/" | head -1)
    if [ -z "$RED_COMMIT" ]; then
      gsd_run query state.update last_gate_trip "${PLAN_ID}/${TASK_ID}" || true
      echo "MVP+TDD GATE TRIPPED: missing RED commit for ${PLAN_ID}/${TASK_ID}"
      exit 1
    fi
  fi
fi

Pure doc-only / config-only / test-only tasks return is_behavior_adding=false and are exempt. When the gate trips, Read ~/.claude/gsd-core/references/execute-mvp-tdd.md for the exact halt report format.

**MANDATORY — Check for blocking anti-patterns before any other work.**

Look for a .continue-here.md in the current phase directory:

ls ${phase_dir}/.continue-here.md 2>/dev/null || true

If .continue-here.md exists, parse its "Critical Anti-Patterns" table for rows with severity = blocking.

If one or more blocking anti-patterns are found:

This step cannot be skipped. Before proceeding to check_interactive_mode or any other step, the agent must demonstrate understanding of each blocking anti-pattern by answering all three questions for each one:

1. What is this anti-pattern? — Describe it in your own words, not by quoting the handoff.
2. How did it manifest? — Explain the specific failure that caused it to be recorded.
3. What structural mechanism (not acknowledgment) prevents it? — Name the concrete step, checklist item, or enforcement mechanism that stops recurrence.

Write these answers inline before continuing. If a blocking anti-pattern cannot be answered from the context in .continue-here.md, stop and ask the user for clarification.

If no .continue-here.md exists, or no blocking rows are found: Proceed directly to check_interactive_mode.

**Parse `--interactive` flag from $ARGUMENTS.**

If --interactive flag present: Switch to interactive execution mode.

Interactive mode executes plans sequentially inline (no subagent spawning) with user checkpoints between tasks. The user can review, modify, or redirect work at any point.

Interactive execution flow:

1. Load plan inventory as normal (discover_and_group_plans)

2. For each plan (sequentially, ignoring wave grouping):

   a. Present the plan to the user:

   ## Plan {plan_id}: {plan_name}
   
   Objective: {from plan file}
   Tasks: {task_count}
   
   Options:
   - Execute (proceed with all tasks)
   - Review first (show task breakdown before starting)
   - Skip (move to next plan)
   - Stop (end execution, save progress)
   

   b. If "Review first": Read and display the full plan file. Ask again: Execute, Modify, Skip.

   c. If "Execute": Read and follow ~/.claude/gsd-core/workflows/execute-plan.md inline (do NOT spawn a subagent). Execute tasks one at a time.

   d. After each task: Pause briefly. If the user intervenes (types anything), stop and address their feedback before continuing. Otherwise proceed to next task.

   e. After plan complete: Show results, commit, create SUMMARY.md, then present next plan.

3. After all plans: proceed to verification (same as normal mode).

Benefits of interactive mode:

• No subagent overhead — dramatically lower token usage
• User catches mistakes early — saves costly verification cycles
• Maintains GSD's planning/tracking structure
• Best for: small phases, bug fixes, verification gaps, learning GSD

Skip to handle_branching step (interactive plans execute inline after grouping).

Check `branching_strategy` from init:

"none": Skip, continue on current branch.

"phase" or "milestone": Use pre-computed branch_name from init.

Fork the new phase branch off origin/HEAD (the project's default branch), not the current HEAD — otherwise consecutive phases compound and stay unpushed (#2916). If $BRANCH_NAME already exists locally, reuse it as-is.

DEFAULT_BRANCH=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')
DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}

if git show-ref --verify --quiet "refs/heads/$BRANCH_NAME"; then
  git switch "$BRANCH_NAME" || { echo "ERROR: Could not switch to existing branch '$BRANCH_NAME'." >&2; exit 1; }
else
  if ! git fetch --quiet origin "$DEFAULT_BRANCH"; then  # #2916
    git show-ref --verify --quiet "refs/remotes/origin/$DEFAULT_BRANCH" \
      || { echo "ERROR: fetch origin/$DEFAULT_BRANCH failed and no local copy exists. Refusing to create '$BRANCH_NAME' off current HEAD (#2916)." >&2; exit 1; }
    echo "WARNING: fetch origin/$DEFAULT_BRANCH failed; using local copy as base." >&2
  fi
  if [ -n "$(git status --porcelain)" ]; then
    echo "WARNING: Uncommitted changes will be carried onto '$BRANCH_NAME' (branched off origin/$DEFAULT_BRANCH, not previous HEAD)."
  else
    git switch --quiet "$DEFAULT_BRANCH" 2>/dev/null && git merge --ff-only --quiet "origin/$DEFAULT_BRANCH" 2>/dev/null || true
  fi
  # Pinned base + fail-fast: on success HEAD is exactly at origin/$DEFAULT_BRANCH,
  # so a post-creation merge-base or "ahead-of" guard would be unreachable. The
  # explicit base argument here is the single source of correctness for #2916.
  git checkout -b "$BRANCH_NAME" "origin/$DEFAULT_BRANCH" \
    || { echo "ERROR: Could not create '$BRANCH_NAME' from origin/$DEFAULT_BRANCH (#2916)." >&2; exit 1; }
fi

All subsequent commits go to this branch. User handles merging.

From init JSON: `phase_dir`, `plan_count`, `incomplete_count`.

Report: "Found {plan_count} plans in {phase_dir} ({incomplete_count} incomplete)"

Update STATE.md for phase start:

gsd_run query state.begin-phase --phase "${PHASE_NUMBER}" --name "${PHASE_NAME}" --plans "${PLAN_COUNT}"

This updates Status, Last Activity, Current focus, Current Position, and plan counts in STATE.md so frontmatter and body text reflect the active phase immediately.

Load plan inventory with wave grouping in one call:

PLAN_INDEX=$(gsd_run query phase-plan-index "${PHASE_NUMBER}")

Parse JSON for: phase, plans[] (each with id, wave, autonomous, objective, files_modified, task_count, has_summary), waves (map of wave number → plan IDs), incomplete, has_checkpoints.

Filtering: Skip plans where has_summary: true. If --gaps-only: also skip non-gap_closure plans. If WAVE_FILTER is set: also skip plans whose wave does not equal WAVE_FILTER.

Wave safety check: If WAVE_FILTER is set and there are still incomplete plans in any lower wave that match the current execution mode, STOP and tell the user to finish earlier waves first. Do not let Wave 2+ execute while prerequisite earlier-wave plans remain incomplete.

If all filtered: "No matching incomplete plans" → exit.

Report:

## Execution Plan

**Phase {X}: {Name}** — {total_plans} matching plans across {wave_count} wave(s)

{If WAVE_FILTER is set: `Wave filter active: executing only Wave {WAVE_FILTER}`.}

| Wave | Plans | What it builds |
|------|-------|----------------|
| 1 | 01-01, 01-02 | {from plan objectives, 3-8 words} |
| 2 | 01-03 | ... |

**Optional step 2.5 — Delegate plans to an external AI runtime.**

This step runs after plan discovery and before normal wave execution. It identifies plans that should be delegated to an external AI command and executes them via stdin-based prompt delivery. Plans handled here are removed from the execute_waves plan list so the normal executor skips them.

Activation logic:

1. If CROSS_AI_DISABLED is true (--no-cross-ai flag): skip this step entirely.
2. If CROSS_AI_FORCE is true (--cross-ai flag): mark ALL incomplete plans for cross-AI execution.
3. Otherwise: check each plan's frontmatter for cross_ai: true AND verify config workflow.cross_ai_execution is true. Plans matching both conditions are marked for cross-AI.

CROSS_AI_ENABLED=$(gsd_run query config-get workflow.cross_ai_execution 2>/dev/null || echo "false")
CROSS_AI_CMD=$(gsd_run query config-get workflow.cross_ai_command 2>/dev/null || echo "")
CROSS_AI_TIMEOUT=$(gsd_run query config-get workflow.cross_ai_timeout 2>/dev/null || echo "300")

If no plans are marked for cross-AI: Skip to execute_waves.

If plans are marked but cross_ai_command is empty: Error — tell user to set workflow.cross_ai_command via gsd-tools.cjs query config-set workflow.cross_ai_command "<command>".

For each cross-AI plan (sequentially):

1. Construct the task prompt from the plan file:

   • Extract <objective> and <tasks> sections from the PLAN.md
   • Append PROJECT.md context (project name, description, tech stack)
   • Format as a self-contained execution prompt

2. Check for dirty working tree before execution:

   if ! git diff --quiet HEAD 2>/dev/null; then
     echo "WARNING: dirty working tree detected — the external AI command may produce uncommitted changes that conflict with existing modifications"
   fi
   

3. Run the external command from the project root, writing the prompt to stdin. Never shell-interpolate the prompt — always pipe via stdin to prevent injection:

   echo "$TASK_PROMPT" | timeout "${CROSS_AI_TIMEOUT}s" ${CROSS_AI_CMD} > "$CANDIDATE_SUMMARY" 2>"$ERROR_LOG"
   EXIT_CODE=$?
   

4. Evaluate the result:

   Success (exit 0 + valid summary):

   • Read $CANDIDATE_SUMMARY and validate it contains meaningful content (not empty, has at least a heading and description — a valid SUMMARY.md structure)
   • Write it as the plan's SUMMARY.md file
   • Update STATE.md plan status to complete
   • Update ROADMAP.md progress
   • Mark plan as handled — skip it in execute_waves

   Failure (non-zero exit or invalid summary):

   • Display the error output and exit code
   • Warn: "The external command may have left uncommitted changes or partial edits in the working tree. Review git status and git diff before proceeding."
   • Offer three choices:
     • retry — run the same plan through cross-AI again
     • skip — fall back to normal executor for this plan (re-add to execute_waves list)
     • abort — stop execution entirely, preserve state for resume

5. After all cross-AI plans processed: Remove successfully handled plans from the incomplete plan list so execute_waves skips them. Any skipped-to-fallback plans remain in the list for normal executor processing.

Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`, sequential if `false`.

Orchestrator cwd-drift guard (FIRST ACTION at execute_waves entry — #48):

A prior Agent(isolation="worktree") dispatch can silently leave the orchestrator's cwd inside an agent worktree (or a subdirectory of one). Every subsequent orchestrator-side git call would then target the wrong tree — this is how a wrong-base merge nearly shipped ~1000 files. Resolve the worktree root (so a subdirectory cwd cannot skew the check) and refuse if it is an agent worktree. The discriminator is the per-agent branch namespace worktree-agent-*, NOT the .claude/worktrees/ path: the orchestrator may itself be legitimately invoked from a feature worktree under .claude/worktrees/, so a path-substring refusal would break legitimate runs. Do NOT pin to git worktree list's first entry — that is the main worktree, the wrong target when the orchestrator legitimately runs from a feature worktree.

ORCHESTRATOR_WT=$(git rev-parse --show-toplevel 2>/dev/null) || {
  echo "FATAL: execute_waves entry is not inside a git worktree (#48)." >&2; exit 1; }
ORCH_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
if printf '%s' "$ORCH_BRANCH" | grep -Eq '^worktree-agent-'; then
  echo "FATAL: orchestrator cwd is inside an agent worktree (branch '$ORCH_BRANCH', root '$ORCHESTRATOR_WT') — refusing to execute waves (#48). A prior isolation=\"worktree\" dispatch drifted the cwd; re-run from the orchestrator's own worktree." >&2
  exit 1
fi
# Pin to the worktree root; each later orchestrator-side block re-pins the same way
# (see the #3174 cleanup guard). Treat $ORCHESTRATOR_WT as the canonical root for the
# rest of the phase — prefer `git -C "$ORCHESTRATOR_WT"` for cross-step git calls,
# since a bare `cd` does not persist across separate tool invocations.
export ORCHESTRATOR_WT
cd "$ORCHESTRATOR_WT" || { echo "FATAL: cannot cd to orchestrator worktree '$ORCHESTRATOR_WT' (#48)." >&2; exit 1; }

Stream-idle-timeout prevention — checkpoint heartbeats (#2410):

Multi-plan phases can accumulate enough subagent context that the Claude API SSE layer terminates with Stream idle timeout - partial response received between a large tool_result and the next assistant turn (seen on Claude Code

• Opus 4.7 at ~200K+ cache_read). To keep the stream warm, emit short assistant-text heartbeats — no tool call, just a literal line — at every wave and plan boundary. Each heartbeat MUST start with [checkpoint] so tooling and /gsd:manager's background-completion handler can grep partial transcripts. {P}/{Q} is the phase-wide completed/total plans counter and increases monotonically across waves. {status} is complete (success), failed (executor error), or checkpoint (human-gate returned).

[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} starting, {wave_plan_count} plan(s), {P}/{Q} plans done
[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} starting ({P}/{Q} plans done)
[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} {status} ({P}/{Q} plans done)
[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} complete, {P}/{Q} plans done ({wave_success}/{wave_plan_count} ok)

For each wave:

1. Intra-wave files_modified overlap check (BEFORE spawning):

   Before spawning any agents for this wave, inspect the files_modified list of all plans in the wave. Check every pair of plans in the wave — if any two plans share even one file in their files_modified lists, those plans have an implicit dependency and MUST NOT run in parallel.

   Detection algorithm (pseudocode):

   seen_files = {}
   overlapping_plans = []
   for each plan in wave_plans:
     for each file in plan.files_modified:
       if file in seen_files:
         overlapping_plans.add(plan, seen_files[file])  # both plans overlap on this file
       else:
         seen_files[file] = plan
   

   If overlap is detected:

   • Warn the user:

     ⚠ Intra-wave files_modified overlap detected in Wave {N}:
       Plan {A} and Plan {B} both modify {file}
       Running these plans sequentially to avoid parallel worktree conflicts.
     

   • Override PARALLELIZATION to false for this wave only — run all plans in the wave sequentially regardless of the global parallelization setting.
   • This is a safety net for plans that were incorrectly assigned to the same wave. The planner should have caught this; flag it as a planning defect so the user can replan the phase if desired.

   If no overlap: proceed normally (parallel if PARALLELIZATION=true).

2. Describe what's being built (BEFORE spawning):

   First, emit the wave-start checkpoint heartbeat as a literal assistant-text line — no tool call (#2410). Do NOT skip this even for single-plan waves; it is required before any further reasoning or spawning:

   [checkpoint] phase {PHASE_NUMBER} wave {N}/{M} starting, {wave_plan_count} plan(s), {P}/{Q} plans done
   

   Then read each plan's <objective>. Extract what's being built and why.

   ---
   ## Wave {N}
   
   **{Plan ID}: {Plan Name}**
   {2-3 sentences: what this builds, technical approach, why it matters}
   
   Spawning {count} agent(s)... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
   ---
   

   • Bad: "Executing terrain generation plan"
   • Good: "Procedural terrain generator using Perlin noise — creates height maps, biome zones, and collision meshes. Required before vehicle physics can interact with ground."

2.5. Per-plan worktree decision (run for each plan in this wave BEFORE its dispatch):

Read and execute gsd-core/workflows/execute-phase/steps/per-plan-worktree-gate.md for each plan. It extracts PLAN_FILES from the plan's JSON, intersects against SUBMODULE_PATHS (with normalization, bidirectional matching, and glob-prefix handling), and sets USE_WORKTREES_FOR_PLAN to false when the plan touches a submodule path. Append plan_id to a WAVE_WORKTREE_PLANS accumulator when USE_WORKTREES_FOR_PLAN != false.

The dispatch branches in step 3 below MUST gate on USE_WORKTREES_FOR_PLAN for the current plan, not on the project-level USE_WORKTREES.

3. Spawn executor agents:

   Emit a plan-start heartbeat (literal line, no tool call) immediately before each Agent() dispatch (#2410):

   [checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} starting ({P}/{Q} plans done)

   Pass paths only — executors read files themselves with their fresh context window. For 200k models, this keeps orchestrator context lean (~10-15%). For 1M+ models (Opus 4.6, Sonnet 4.6), richer context can be passed directly.

   Worktree mode (USE_WORKTREES_FOR_PLAN is not false — evaluated per-plan in step 2.5):

   Before spawning, capture the current HEAD:

   EXPECTED_BASE=$(git rev-parse HEAD)
   DISPATCH_TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
   EXPECTED_BRANCH=$(git rev-parse --abbrev-ref HEAD)
   if [ "${USE_WORKTREES_FOR_PLAN:-true}" != "false" ] && [ -z "${WAVE_WORKTREE_MANIFEST:-}" ]; then
     WAVE_WORKTREE_MANIFEST=$(mktemp "${TMPDIR:-/tmp}/gsd-worktree-wave-XXXXXX.json")
     # Persist the dispatch-time orchestrator worktree root so wave-cleanup can pin back to the
     # orchestrator's OWN worktree — NOT `git worktree list`'s first entry (always the main
     # checkout), which pins a non-primary (per-phase lane) orchestrator off its branch (#630).
     # Dispatch runs from the orchestrator's lane, so show-toplevel here is the correct root.
     ORCH_ROOT=$(git rev-parse --show-toplevel)
     ORCH_ROOT="$ORCH_ROOT" MANIFEST="$WAVE_WORKTREE_MANIFEST" node -e 'const fs=require("fs");fs.writeFileSync(process.env.MANIFEST,JSON.stringify({orchestrator_root:process.env.ORCH_ROOT||null,worktrees:[]})+"\n")'
     export WAVE_WORKTREE_MANIFEST
   fi
   

   Sequential dispatch for parallel execution (waves with 2+ agents): Dispatch each Agent() call one at a time with run_in_background: true. Do NOT send all Agent calls in a single message: simultaneous git worktree add calls race on .git/config.lock. Agents still run in parallel once their worktrees are created.

   # CORRECT: one Agent() per message with run_in_background: true
   # WRONG: multiple Agent() calls in one message -> .git/config.lock contention
   

   Agent(
     subagent_type="gsd-executor",
     description="Execute plan {plan_number} of phase {phase_number}",
     # Only include model= when executor_model is an explicit model name.
     # When executor_model is "inherit", omit this parameter entirely so
     # Claude Code inherits the orchestrator model automatically.
     model="{executor_model}",  # omit this line when executor_model == "inherit"
     isolation="worktree",
     prompt="
       <objective>
       Execute plan {plan_number} of phase {phase_number}-{phase_name}.
       Commit each task atomically. Create SUMMARY.md.
       Do NOT update STATE.md or ROADMAP.md — the orchestrator owns those writes after all worktree agents in the wave complete.
       </objective>
   
       <worktree_branch_check>
       ORCHESTRATOR build-time embed (NOT a sub-agent runtime step): before this dispatch, read `gsd-core/references/worktree-branch-check.md`, substitute `{EXPECTED_BASE}` with the base SHA captured above ({EXPECTED_BASE}), and replace this note with that fragment's `<worktree_branch_check>` block so the dispatched prompt carries the runnable guard verbatim — do not pass this instruction through in its place.
       Per-commit HEAD/cwd-drift/path-guard: `agents/gsd-executor.md` steps 0/0a/0b + `references/worktree-path-safety.md` (in <execution_context>).
       </worktree_branch_check>
   
       <parallel_execution>
       You are running as a PARALLEL executor agent in a git worktree. Worktree path safety (cwd-drift, absolute-path guards) is in `worktree-path-safety.md` (loaded below).
       Run `git commit` normally — hooks run by default. Do NOT pass `--no-verify`
       unless the orchestrator surfaces `workflow.worktree_skip_hooks=true` in this
       prompt; silent bypass violates project CLAUDE.md guidance (#2924).
   
       IMPORTANT: Do NOT modify STATE.md or ROADMAP.md. execute-plan.md
       auto-detects worktree mode (`.git` is a file, not a directory) and skips
       shared file updates automatically. The orchestrator updates them centrally
       after merge.
   
       REQUIRED: SUMMARY.md MUST be committed before you return. In worktree mode the
       git_commit_metadata step in execute-plan.md commits SUMMARY.md and REQUIREMENTS.md
       only (STATE.md and ROADMAP.md are excluded automatically). Do NOT skip or defer
       this commit — the orchestrator force-removes the worktree after you return, and
       any uncommitted SUMMARY.md will be permanently lost (#2070).
       REQUIRED ORDER: Write SUMMARY.md → commit → only then any narration. No text between Write and commit (truncation risk; #2070 rescue is not primary defense).
       </parallel_execution>
   
       <execution_context>
       @~/.claude/gsd-core/workflows/execute-plan.md
       @~/.claude/gsd-core/templates/summary.md
       @~/.claude/gsd-core/references/checkpoints.md
       @~/.claude/gsd-core/references/tdd.md
       @~/.claude/gsd-core/references/worktree-path-safety.md
       ${CONTEXT_WINDOW < 200000 ? '' : '@~/.claude/gsd-core/references/executor-examples.md'}
       </execution_context>
   
       <files_to_read>
       Read these files at execution start using the Read tool.
       First resolve repo root so every path is anchored:
       \`PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)\`
       - ${PROJECT_ROOT}/{phase_dir}/{plan_file} (Plan)
       - ${PROJECT_ROOT}/.planning/PROJECT.md (Project context — core value, requirements, evolution rules)
       - ${PROJECT_ROOT}/.planning/STATE.md (State)
       - ${PROJECT_ROOT}/.planning/config.json (Config, if exists)
       ${CONTEXT_WINDOW >= 500000 ? `
       - ${PROJECT_ROOT}/${phase_dir}/*-CONTEXT.md (User decisions from discuss-phase — honors locked choices)
       - ${PROJECT_ROOT}/${phase_dir}/*-RESEARCH.md (Technical research — pitfalls and patterns to follow)
       - ${PROJECT_ROOT}/${prior_wave_summaries} (SUMMARY.md files from earlier waves in this phase — what was already built)
       ` : ''}
       - ${PROJECT_ROOT}/CLAUDE.md (Project instructions, if exists — follow project-specific guidelines and coding conventions)
       - ${PROJECT_ROOT}/.claude/skills/ or ${PROJECT_ROOT}/.agents/skills/ (Project skills, if either exists — list skills, read SKILL.md for each, follow relevant rules during implementation)
       </files_to_read>
   
       ${AGENT_SKILLS}
   
       <mcp_tools>
       If CLAUDE.md or project instructions reference MCP tools (e.g. jCodeMunch, context7,
       or other MCP servers), prefer those tools over Grep/Glob for code navigation when available.
       MCP tools often save significant tokens by providing structured code indexes.
       Check tool availability first — if MCP tools are not accessible, fall back to Grep/Glob.
       </mcp_tools>
   
       <success_criteria>
       - [ ] All tasks executed
       - [ ] Each task committed individually
       - [ ] SUMMARY.md created in plan directory
       - [ ] No modifications to shared orchestrator artifacts (the orchestrator handles all post-wave shared-file writes)
       </success_criteria>
     "
   )
   

   Immediately after each worktree Agent() spawn returns metadata, atomically append {agent_id, worktree_path, branch, expected_base} to WAVE_WORKTREE_MANIFEST. If any field is missing, stop and ask for recovery instead of scanning all agent worktrees.

   ORCHESTRATOR FAIL-CLOSED RULE (#48): worktree_branch_check is verify-only — an executor that hits a base/HEAD-namespace mismatch prints FATAL: and exits 42 instead of self-recovering. If any executor result reports a FATAL:/exit 42 (or its commits never appear because it halted at the check), mark that plan blocked: do NOT merge or clean up its worktree (preserve it for inspection), do NOT count the wave as successful, and surface the mismatch with recovery guidance to the user. The orchestrator — the worktree lifecycle owner — performs any base correction (e.g. recreate the worktree on {EXPECTED_BASE}); the sub-agent never does. Never proceed past a halted executor on the assumption it succeeded.

   ORCHESTRATOR RULE — CODEX RUNTIME: After calling Agent() above to spawn executor agent(s), stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.

   Sequential mode (USE_WORKTREES_FOR_PLAN is false — either project-level USE_WORKTREES=false, or per-plan submodule intersection forced it false in step 2.5):

   Omit isolation="worktree" from the Agent call. Replace the <parallel_execution> block with:

       <sequential_execution>
       You are running as a SEQUENTIAL executor agent on the main working tree.
       Use normal git commits (with hooks). Do NOT use --no-verify.
       REQUIRED ORDER: Write SUMMARY.md → commit → only then any narration. No text between Write and commit (truncation risk; #2070 rescue is not primary defense).
       </sequential_execution>
   

   The sequential mode Agent prompt uses the same structure as worktree mode but with these differences in success_criteria — since there is only one agent writing at a time, there are no shared-file conflicts:

       <success_criteria>
       - [ ] All tasks executed
       - [ ] Each task committed individually
       - [ ] SUMMARY.md created in plan directory
       - [ ] STATE.md updated with position and decisions
       - [ ] ROADMAP.md updated with plan progress (via `roadmap update-plan-progress`)
       </success_criteria>
   

   When worktrees are disabled for a plan (per-plan or project-level), that plan's executor runs on the main working tree. If any plan in the current wave dropped to sequential mode, execute the affected plan(s) one at a time to avoid concurrent writes to the main working tree — plans in the same wave that retained worktree isolation can still run in parallel alongside the sequential ones, but two non-worktree plans in the same wave must serialize. When the project-level USE_WORKTREES=false, all plans in the wave serialize regardless of the PARALLELIZATION setting.

4. Wait for all agents in wave to complete.

   Plan-complete heartbeat (#2410): as each executor returns (or is verified via spot-check below), emit one line — complete advances {P}, failed and checkpoint do not but still warm the stream:

   [checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} complete ({P}/{Q} plans done)
   [checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} failed ({P}/{Q} plans done)
   [checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} checkpoint ({P}/{Q} plans done)
   

   Completion signal fallback (Copilot and runtimes where Agent() may not return):

   If a spawned agent does not return a completion signal but appears to have finished its work, do NOT block indefinitely. Instead, verify completion via spot-checks:

   # For each plan in this wave, check if the executor finished:
   SUMMARY_EXISTS=$(test -f "{phase_dir}/{plan_number}-{plan_padded}-SUMMARY.md" && echo "true" || echo "false")
   COMMITS_FOUND=$(git log --oneline --all --grep="{phase_number}-{plan_padded}" --since="1 hour ago" | head -1)
   COMMITS_SINCE_DISPATCH=$(git log "${EXPECTED_BRANCH}" --since="${DISPATCH_TS}" --oneline | head -1)
   

   If SUMMARY.md exists AND commits are found: The agent completed successfully — treat as done and proceed to step 5. Log: "✓ {Plan ID} completed (verified via spot-check — completion signal not received)"

   If SUMMARY.md does NOT exist after a reasonable wait: The agent may still be running or may have failed silently. Check git log --oneline -5 for recent activity. If commits are still appearing, wait longer. If no activity, report the plan as failed and route to the failure handler in step 6.

   Configurable stall surveillance (#3212): Every ${EXECUTOR_STALL_INTERVAL_MINUTES} minutes while waiting, inspect git log "${EXPECTED_BRANCH}" --since="${DISPATCH_TS}" for activity. If no completion signal, no SUMMARY.md, and no expected-branch commits appear for ${EXECUTOR_STALL_THRESHOLD_MINUTES} minutes, pause and ask for one recovery path: continue waiting, kill and retry, or kill and switch to inline execution.

   This fallback applies automatically to all runtimes. Claude Code's Agent() normally returns synchronously, but the fallback ensures resilience if it doesn't.

5. Post-wave hook validation (parallel mode only): Hooks run on every executor commit by default (#2924); this post-wave run only fires when workflow.worktree_skip_hooks=true opted out of per-commit hooks:

   SKIP_HOOKS=$(gsd_run query config-get workflow.worktree_skip_hooks 2>/dev/null || echo "false")
   if [ "$SKIP_HOOKS" = "true" ]; then
     # Stash uncommitted changes under a named ref so we always pop (bare `git stash` strands them on hook/script failure). #3542: `refs/stash` is shared across worktrees, so this helper runs ONLY in the orchestrator's main checkout after all wave worktrees have been merged + removed; executors are forbidden from running any `git stash` subcommand (see `<destructive_git_prohibition>` in `agents/gsd-executor.md`).
     STASHED=false
     if (! git diff --quiet || ! git diff --cached --quiet) && git stash push -u -m "gsd-post-wave-hook-$$" >/dev/null 2>&1; then STASHED=true; fi
     git hook run pre-commit 2>&1 || echo "⚠ Pre-commit hooks failed — review before continuing"
     [ "$STASHED" = "true" ] && (git stash pop >/dev/null 2>&1 || echo "⚠ Could not pop gsd-post-wave-hook stash — recover manually")
   fi
   

   If hooks fail: report the failure and ask "Fix hook issues now?" or "Continue to next wave?"

5.5. Worktree cleanup (when isolation="worktree" was used):

Standard wave contract: Each wave's worktrees merge to main via the templated path below before the next wave's worktrees fork. The cleanup loop runs once per wave at the end of the wave lifecycle. Worktrees created in wave N must be fully removed before wave N+1 forks new ones.

Cross-wave dependency deviation (supported execution mode): When the orchestrator legitimately deviates from the standard wave model — for example, a phase with cross-wave plan dependencies that requires custom inter-worktree base-update merges (e.g., merge: bring 09-01 + 09-02 into 09-03 base) — the cleanup loop below is NOT automatically re-entered for those custom merges. The deviation path produces correct final history but bypasses this loop, leaving worktree-agent-* directories in place. Use the cleanup-tail snippet below to remove any residual worktrees after such a deviation.

When executor agents ran in worktree isolation, their commits land on temporary branches in separate working trees. After the wave completes, merge these changes back and clean up:

Manifest source of truth (#3384): Cleanup consumes the WAVE_WORKTREE_MANIFEST created and populated during executor dispatch in step 3. Do not recreate or truncate it here.

Prefer the bounded helper, which validates branch identity, expected base, deletion diffs, merge result, and worktree removal before deleting the temporary branch. If the helper reports a blocked cleanup, resolve the reported manifest entry and rerun the same command. Do not fall back to broad worktree discovery.

[ -n "${WAVE_WORKTREE_MANIFEST:-}" ] && [ -f "$WAVE_WORKTREE_MANIFEST" ] || {
  echo "BLOCKED: missing WAVE_WORKTREE_MANIFEST; refusing broad worktree cleanup (#3384)." >&2
  exit 1
}

# Guard: pin cleanup back to the orchestrator's OWN worktree and fail on branch drift (#3174, #630).
# Resolve from the dispatch-time orchestrator root persisted in the manifest — NOT `git worktree
# list`'s first entry, which is always the main checkout and would pin a non-primary (per-phase
# lane) orchestrator off its own branch, tripping the #3174 assertion below (#630). Byte-identical
# for a primary orchestrator (its root IS the first entry); the fallback covers pre-#630 manifests.
PRIMARY_WT=$(MANIFEST="$WAVE_WORKTREE_MANIFEST" node -e 'const fs=require("fs");try{const j=JSON.parse(fs.readFileSync(process.env.MANIFEST,"utf8"));if(j&&j.orchestrator_root)process.stdout.write(String(j.orchestrator_root))}catch(e){}')
[ -n "$PRIMARY_WT" ] || PRIMARY_WT=$(git worktree list --porcelain | awk '/^worktree /{print substr($0,10); exit}')
if [ -z "$PRIMARY_WT" ]; then
  echo "FATAL: could not resolve orchestrator worktree before cleanup" >&2
  exit 1
fi
if [ -n "$PRIMARY_WT" ] && [ "$(pwd -P 2>/dev/null)" != "$(cd "$PRIMARY_WT" 2>/dev/null && pwd -P)" ]; then echo "⚠ Orchestrator CWD drifted to $(pwd) — pinning to $PRIMARY_WT before worktree cleanup (#3174)"; cd "$PRIMARY_WT" || { echo "FATAL: cannot cd to primary worktree $PRIMARY_WT" >&2; exit 1; }; fi
ORCH_BRANCH=$(git rev-parse --abbrev-ref HEAD)
[ -z "${EXPECTED_BRANCH:-}" ] || [ "$ORCH_BRANCH" = "$EXPECTED_BRANCH" ] || { echo "FATAL: orchestrator on '$ORCH_BRANCH' but expected '$EXPECTED_BRANCH' before worktree cleanup — refusing to merge (#3174-class drift)" >&2; exit 1; }

# Fail closed: SDK refusal (safety guard #3174/#3384) must surface — do not swallow exit 1.
gsd_run query worktree.cleanup-wave --manifest "$WAVE_WORKTREE_MANIFEST" || exit 1

Cleanup-tail snippet (use after any wave whose merges did not flow through the templated path above):

If the orchestrator deviated from the standard wave merge path (e.g., custom inter-worktree base-update merges with merge: bring … style messages), run this snippet after the custom merges are complete. It reads only WAVE_WORKTREE_MANIFEST; do not discover unrelated worktree-agent-* worktrees.

# Cleanup-tail: pin orchestrator CWD to its OWN worktree before cleanup-tail (#3174, #630).
# Same fix as the templated path: resolve the dispatch-time orchestrator root from the manifest,
# not `git worktree list`'s first entry (always the main checkout — wrong for a lane orchestrator).
PRIMARY_WT=$(MANIFEST="$WAVE_WORKTREE_MANIFEST" node -e 'const fs=require("fs");try{const j=JSON.parse(fs.readFileSync(process.env.MANIFEST,"utf8"));if(j&&j.orchestrator_root)process.stdout.write(String(j.orchestrator_root))}catch(e){}')
[ -n "$PRIMARY_WT" ] || PRIMARY_WT=$(git worktree list --porcelain | awk '/^worktree /{print substr($0,10); exit}')
if [ -n "$PRIMARY_WT" ] && [ "$(pwd -P 2>/dev/null)" != "$(cd "$PRIMARY_WT" 2>/dev/null && pwd -P)" ]; then echo "⚠ Orchestrator CWD drifted to $(pwd) — pinning to $PRIMARY_WT before cleanup-tail (#3174)"; cd "$PRIMARY_WT" || { echo "FATAL: cannot cd to primary worktree $PRIMARY_WT" >&2; exit 1; }; fi
# Cleanup-tail: remove residual agent worktrees after a cross-wave-dependency deviation.
# Uses only the current wave manifest to avoid touching unrelated active agents (#3384).
WT_PATHS_FILE=$(mktemp "${TMPDIR:-/tmp}/gsd-worktree-paths-XXXXXX")
node -e 'const fs=require("fs");const p=process.env.WAVE_WORKTREE_MANIFEST;try{if(!p)throw new Error("WAVE_WORKTREE_MANIFEST is unset");if(!fs.existsSync(p))throw new Error("manifest does not exist");const s=fs.readFileSync(p,"utf8");if(!s.trim())throw new Error("manifest is empty");const j=JSON.parse(s);for(const w of j.worktrees||[])if(w.worktree_path)console.log(w.worktree_path)}catch(e){console.error(`ERROR: cannot read worktree manifest ${p||"(unset)"}: ${e.message}`);process.exit(1)}' > "$WT_PATHS_FILE" || { echo "BLOCKED: cannot read WAVE_WORKTREE_MANIFEST; refusing cleanup (#3384)." >&2; exit 1; }
while IFS= read -r WT; do
  [ -z "$WT" ] && continue
  WT_BRANCH=$(git -C "$WT" rev-parse --abbrev-ref HEAD 2>/dev/null)
  [ -z "$WT_BRANCH" ] || [ "$WT_BRANCH" = "HEAD" ] && continue
  echo "Cleaning up residual worktree: $WT (branch: $WT_BRANCH)"
  git worktree unlock "$WT" 2>/dev/null || true
  if ! git worktree remove "$WT" --force; then
    WT_NAME=$(basename "$WT")
    if [ -f ".git/worktrees/${WT_NAME}/locked" ]; then
      echo "⚠ Worktree $WT is locked — unlock failed; manual cleanup required:"
      echo "    git worktree unlock \"$WT\" && git worktree remove \"$WT\" --force && git branch -D \"$WT_BRANCH\""
    else
      echo "⚠ Residual worktree at $WT — remove failed; manual cleanup required"
    fi
  else
    git branch -D "$WT_BRANCH" 2>/dev/null || true
  fi
done < "$WT_PATHS_FILE"
git worktree prune

When to skip step 5.5:

If no plan in this wave used worktree isolation (project-level USE_WORKTREES=false OR every plan in the wave had USE_WORKTREES_FOR_PLAN=false — i.e. WAVE_WORKTREE_PLANS from step 2.5 is empty): all agents ran on the main working tree — skip this step entirely.

If the orchestrator merged via custom messages (cross-wave-dependency deviation): the templated cleanup loop above was not triggered for those merges. Run the cleanup-tail snippet above instead. After the snippet completes, proceed to step 5.6.

If at least one plan used worktrees but others did not: still run this cleanup — it iterates over actual git worktree list output and only merges back the worktrees that were created, leaving sequential plans' commits on the main tree untouched.

If no worktrees found at runtime: Skip silently — agents may have been spawned without worktree isolation, or the orchestrator already cleaned them up.

5.6. Post-merge build & test gate:

After merging all worktrees in a wave (parallel mode), or after the last plan completes (serial mode), run a build and then the project's test suite to catch cross-plan integration issues that individual worktree self-checks cannot detect (e.g., conflicting type definitions, removed exports, import changes, link errors).

This addresses the Generator self-evaluation blind spot identified in Anthropic's harness engineering research: agents reliably report Self-Check: PASSED even when merging their work creates failures.

Read and execute gsd-core/workflows/execute-phase/steps/post-merge-gate.md.

5.7. Post-wave shared artifact update (when at least one plan used worktrees, skip if tests failed):

When any executor agent in this wave ran with isolation="worktree", that agent skipped STATE.md and ROADMAP.md updates to avoid last-merge-wins overwrites. The orchestrator is the single writer for these files. After worktrees are merged back, update shared artifacts once for every completed plan in the wave (worktree-mode plans and sequential plans that ran on the main tree but deferred to the orchestrator for tracking writes).

Only update tracking when tests passed (TEST_EXIT=0). If tests failed or timed out, skip the tracking update — plans should not be marked as complete when integration tests are failing or inconclusive.

# Guard: only update tracking if post-merge tests passed
# Timeout (124) is treated as inconclusive — do NOT mark plans complete
if [ "${TEST_EXIT}" -eq 0 ]; then
  # Update ROADMAP plan progress for each completed plan in this wave
  for plan_id in {completed_plan_ids}; do
    gsd_run query roadmap.update-plan-progress "${PHASE_NUMBER}" "${plan_id}" "complete"
  done

  # Only commit tracking files if they actually changed
  if ! git diff --quiet .planning/ROADMAP.md .planning/STATE.md 2>/dev/null; then
    gsd_run query commit "docs(phase-${PHASE_NUMBER}): update tracking after wave ${N}" --files .planning/ROADMAP.md .planning/STATE.md
  fi
elif [ "${TEST_EXIT}" -eq 124 ]; then
  echo "⚠ Skipping tracking update — test suite timed out. Plans remain in-progress. Run tests manually to confirm."
else
  echo "⚠ Skipping tracking update — post-merge tests failed (exit ${TEST_EXIT}). Plans remain in-progress until tests pass."
fi

Where WAVE_PLAN_IDS is the space-separated list of plan IDs that completed in this wave.

If no plan in this wave used worktrees (project-level USE_WORKTREES=false OR WAVE_WORKTREE_PLANS is empty): sequential agents already updated STATE.md and ROADMAP.md themselves — skip this step.

5.8. Handle test gate failures (when WAVE_FAILURE_COUNT > 0):

## ⚠ Post-Merge Test Failure (cumulative failures: ${WAVE_FAILURE_COUNT})

Wave {N} worktrees merged successfully, but {M} tests fail after merge.
This typically indicates conflicting changes across parallel plans
(e.g., type definitions, shared imports, API contracts).

Failed tests:
{first 10 lines of failure output}

Options:
1. Fix now (recommended) — resolve conflicts before next wave
2. Continue — failures may compound in subsequent waves

Note: If WAVE_FAILURE_COUNT > 1, strongly recommend "Fix now" — compounding failures across multiple waves become exponentially harder to diagnose.

If "Fix now": diagnose failures (typically import conflicts, missing types, or changed function signatures from parallel plans modifying the same module). Fix, commit as fix: resolve post-merge conflicts from wave {N}, re-run tests.

Why this matters: Worktree isolation means each agent's Self-Check passes in isolation. But when merged, add/add conflicts in shared files (models, registries, CLI entry points) can silently drop code. The post-merge gate catches this before the next wave builds on a broken foundation.

6. Report completion — spot-check claims first:

   Wave-close heartbeat (#2410): after spot-checks finish (pass or fail), before the ## Wave {N} Complete summary, emit as a literal line:

   [checkpoint] phase {PHASE_NUMBER} wave {N}/{M} complete, {P}/{Q} plans done ({wave_success}/{wave_plan_count} ok)
   

   For each SUMMARY.md:

   • Verify first 2 files from key-files.created exist on disk
   • Check git log --oneline --all --grep="{phase}-{plan}" returns ≥1 commit
   • Check for ## Self-Check: FAILED marker

   If ANY spot-check fails: report which plan failed, route to failure handler — ask "Retry plan?" or "Continue with remaining waves?"

   If pass:

   ---
   ## Wave {N} Complete
   
   **{Plan ID}: {Plan Name}**
   {What was built — from SUMMARY.md}
   {Notable deviations, if any}
   
   {If more waves: what this enables for next wave}
   ---
   

7. Handle failures: Step 7.0 — classify before branching (#3095):

   CLASS_JSON=$(gsd_run query agent.classify-failure -- "$AGENT_RETURN_BODY")
   CLASS=$(echo "$CLASS_JSON" | jq -r '.class')
   SENTINEL=$(echo "$CLASS_JSON" | jq -r '.sentinel // empty')
   RETRY_AFTER=$(echo "$CLASS_JSON" | jq -r '.retryAfterSeconds // empty')
   if [ -n "$RETRY_AFTER" ]; then RETRY_HINT="  Provider hinted retry-after: ${RETRY_AFTER}s"; else RETRY_HINT=""; fi
   

   One classifier branch handles sentinels across Claude/Copilot/Codex/Gemini. Reference: docs/research/provider-rate-limit-signals.md. Step 7.1 — class == "quota-exceeded": Do not offer "retry now". Run step-5 spot-check first; if SUMMARY.md is missing but commits exist, route to safe-resume (state.verify-against-disk) instead of immediate redispatch.

   ⚠ Plan {plan_id} terminated by provider quota / rate limit
     Runtime sentinel: {SENTINEL}
     {RETRY_HINT}
     Partial commits on worktree branch: {N}
     SUMMARY.md present: {yes|no}
     1. Wait for quota reset, then resume (recommended)
   2. Switch to a different runtime / model and resume
   3. Abort phase and report partial state
   

   Re-run /gsd:execute-phase after quota reset for Option 1. Step 7.2 — class == "classify-handoff-bug": If error contains classifyHandoffIfNeeded is not defined, treat as Claude runtime bug. Run the same step-5 spot-checks; PASS => treat as success, FAIL => fall through. Step 7.3 — class == "unknown-failure": Report failed plan and ask Continue/Stop; continuing may cascade into dependent plan failures.

7b. Pre-wave dependency check (waves 2+ only): Before wave N+1, run gsd-tools.cjs query verify.key-links {phase_dir}/{plan}-PLAN.md for each upcoming plan. If any PRIOR-wave artifact link fails, present: - ## Cross-Plan Wiring Gap with plan/link/from/pattern rows - Options: investigate+fix before continue, or continue with cascade risk Skip key-links that reference files in the CURRENT (upcoming) wave. 8. Execute checkpoint plans between waves — see <checkpoint_handling>. 9. Proceed to next wave. Plans with autonomous: false require user interaction. Auto-mode checkpoint handling: Read auto-advance config (chain flag OR user preference — same boolean as check.auto-mode):

AUTO_MODE=$(gsd_run query check auto-mode --pick active 2>/dev/null || echo "false")

When executor returns a checkpoint AND AUTO_MODE is true:

• human-verify → Auto-spawn continuation agent with {user_response} = "approved". Log ⚡ Auto-approved checkpoint.
• decision → Auto-spawn continuation agent with {user_response} = first option from checkpoint details. Log ⚡ Auto-selected: [option].
• human-action → Present to user (existing behavior below). Auth gates cannot be automated.

Standard flow (not auto-mode, or human-action type):

1. Spawn agent for checkpoint plan
2. Agent runs until checkpoint task or auth gate → returns structured state
3. Agent return includes: completed tasks table, current task + blocker, checkpoint type/details, what's awaited
4. Present to user:

   ## Checkpoint: [Type]
   
   **Plan:** 03-03 Dashboard Layout
   **Progress:** 2/3 tasks complete
   
   [Checkpoint Details from agent return]
   [Awaiting section from agent return]
   

5. User responds: "approved"/"done" | issue description | decision selection
6. Spawn continuation agent (NOT resume) using continuation-prompt.md template:
   • {completed_tasks_table}: From checkpoint return
   • {resume_task_number} + {resume_task_name}: Current task
   • {user_response}: What user provided
   • {resume_instructions}: Based on checkpoint type
7. Continuation agent verifies previous commits, continues from resume point
8. Repeat until plan completes or user stops

Why fresh agent, not resume: Resume relies on internal serialization that breaks with parallel tool calls. Fresh agents with explicit state are more reliable.

Checkpoints in parallel waves: Agent pauses and returns while other parallel agents may complete. Present checkpoint, spawn continuation, wait for all before next wave.

After all waves:

## Phase {X}: {Name} Execution Complete

**Waves:** {N} | **Plans:** {M}/{total} complete

| Wave | Plans | Status |
|------|-------|--------|
| 1 | plan-01, plan-02 | ✓ Complete |
| CP | plan-03 | ✓ Verified |
| 2 | plan-04 | ✓ Complete |

### Plan Details
1. **03-01**: [one-liner from SUMMARY.md]
2. **03-02**: [one-liner from SUMMARY.md]

### Issues Encountered
[Aggregate from SUMMARYs, or "None"]

Security gate check:

SECURITY_CFG=$(gsd_run query config-get workflow.security_enforcement --raw 2>/dev/null || echo "true")
SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)

If SECURITY_CFG is false: skip.

If SECURITY_CFG is true AND SECURITY_FILE is empty (no SECURITY.md yet): Include in the next-steps routing output:

⚠ Security enforcement enabled — run before advancing:
  /gsd:secure-phase {PHASE} ${GSD_WS}

If SECURITY_CFG is true AND SECURITY.md exists: check frontmatter threats_open. If > 0:

⚠ Security gate: {threats_open} threats open
  /gsd:secure-phase {PHASE} — resolve before advancing

**Optional step — TDD collaborative review.**

TDD_MODE=$(gsd_run query config-get workflow.tdd_mode 2>/dev/null || echo "false")

Skip if TDD_MODE is false.

When TDD_MODE is true, check whether any completed plans in this phase have type: tdd in their frontmatter:

TDD_PLANS=$(grep -rl "^type: tdd" "${PHASE_DIR}"/*-PLAN.md 2>/dev/null | wc -l | tr -d ' ')

If TDD_PLANS > 0: Insert end-of-phase collaborative review checkpoint.

1. Collect all SUMMARY.md files for TDD plans
2. For each TDD plan summary, verify the RED/GREEN/REFACTOR gate sequence:
   • RED gate: A failing test commit exists (test(...) commit with MUST-fail evidence)
   • GREEN gate: An implementation commit exists (feat(...) commit making tests pass)
   • REFACTOR gate: Optional cleanup commit (refactor(...) commit, tests still pass)
3. If any TDD plan is missing the RED or GREEN gate commits, flag it:

   ⚠ TDD gate violation: Plan {plan_id} missing {RED|GREEN} phase commit.
     Expected commit pattern: test({phase}-{plan}): ... → feat({phase}-{plan}): ...
   

4. Present collaborative review summary:

   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    TDD REVIEW — Phase {X}
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   
   TDD Plans: {TDD_PLANS} | Gate violations: {count}
   
   | Plan | RED | GREEN | REFACTOR | Status |
   |------|-----|-------|----------|--------|
   | {id} |  ✓  |   ✓   |    ✓     | Pass   |
   | {id} |  ✓  |   ✗   |    —     | FAIL   |
   

Escalation under MVP+TDD. When MVP_MODE=true AND TDD_MODE=true, the review verdict escalates from advisory to blocking: missing RED or GREEN gate commits prevent marking the phase complete.

Phase blocked: {N} TDD plan(s) violate the RED→GREEN gate sequence under MVP+TDD.
Resolve and re-run /gsd execute-phase, or override with
/gsd execute-phase {phase} --force-mvp-gate to ship anyway.

--force-mvp-gate is the escape hatch (documented, not yet implemented). Policy is:

• MVP_MODE=true AND TDD_MODE=true: violations are blocking unless explicitly overridden.
• otherwise: violations are advisory/non-blocking and are surfaced for review. The verifier agent (step verify_phase_goal) still checks TDD discipline in both cases.

If `WAVE_FILTER` was used, re-run plan discovery after execution:

POST_PLAN_INDEX=$(gsd_run query phase-plan-index "${PHASE_NUMBER}")

Apply the same "incomplete" filtering rules as earlier:

• ignore plans with has_summary: true
• if --gaps-only, only consider gap_closure: true plans

If incomplete plans still remain anywhere in the phase:

• STOP here
• Do NOT run phase verification
• Do NOT mark the phase complete in ROADMAP/STATE
• Present:

## Wave {WAVE_FILTER} Complete

Selected wave finished successfully. This phase still has incomplete plans, so phase-level verification and completion were intentionally skipped.

/gsd:execute-phase {phase} ${GSD_WS}                # Continue remaining waves
/gsd:execute-phase {phase} --wave {next} ${GSD_WS}  # Run the next wave explicitly

If no incomplete plans remain after the selected wave finishes:

• continue with the normal phase-level verification and completion flow below
• this means the selected wave happened to be the last remaining work in the phase

**This step is REQUIRED and must not be skipped.** Auto-invoke code review on the phase's source changes. Advisory only — never blocks execution flow.

Config gate:

CODE_REVIEW_ENABLED=$(gsd_run query config-get workflow.code_review 2>/dev/null || echo "true")

If CODE_REVIEW_ENABLED is "false": display "Code review skipped (workflow.code_review=false)" and proceed to next step.

Invoke review:

Skill(skill="gsd-code-review", args="${PHASE_NUMBER}")

Check results using deterministic path (not glob):

PADDED=$(printf "%02d" "${PHASE_NUMBER}")
REVIEW_FILE="${PHASE_DIR}/${PADDED}-REVIEW.md"
REVIEW_STATUS=$(sed -n '/^---$/,/^---$/p' "$REVIEW_FILE" | grep "^status:" | head -1 | cut -d: -f2 | tr -d ' ')

If REVIEW_STATUS is not "clean" and not "skipped" and not empty, display:

Code review found issues. Consider running:
/gsd:code-review ${PHASE_NUMBER} --fix

Error handling: If the Skill invocation fails or throws, catch the error, display "Code review encountered an error (non-blocking): {error}" and proceed to next step. Review failures must never block execution.

Regardless of review result, ALWAYS proceed to close_parent_artifacts → regression_gate → verify_phase_goal.

**For decimal/polish phases only (X.Y pattern):** Close the feedback loop by resolving parent UAT and debug artifacts.

Skip if phase number has no decimal (e.g., 3, 04) — only applies to gap-closure phases like 4.1, 03.1.

1. Detect decimal phase and derive parent:

# Check if phase_number contains a decimal
if [[ "$PHASE_NUMBER" == *.* ]]; then
  PARENT_PHASE="${PHASE_NUMBER%%.*}"
fi

2. Find parent UAT file:

PARENT_INFO=$(gsd_run query find-phase "${PARENT_PHASE}" --raw)
# Extract directory from PARENT_INFO JSON, then find UAT file in that directory

If no parent UAT found: Skip this step (gap-closure may have been triggered by VERIFICATION.md instead).

3. Update UAT gap statuses:

Read the parent UAT file's ## Gaps section. For each gap entry with status: failed:

• Update to status: resolved

4. Update UAT frontmatter:

If all gaps now have status: resolved:

• Update frontmatter status: diagnosed → status: resolved
• Update frontmatter updated: timestamp

5. Resolve referenced debug sessions:

For each gap that has a debug_session: field:

• Read the debug session file
• Update frontmatter status: → resolved
• Update frontmatter updated: timestamp
• Move to resolved directory:

mkdir -p .planning/debug/resolved
mv .planning/debug/{slug}.md .planning/debug/resolved/

6. Commit updated artifacts:

gsd_run query commit "docs(phase-${PARENT_PHASE}): resolve UAT gaps and debug sessions after ${PHASE_NUMBER} gap closure" --files .planning/phases/*${PARENT_PHASE}*/*-UAT.md .planning/debug/resolved/*.md

Run prior phases' test suites to catch cross-phase regressions BEFORE verification.

Skip if: This is the first phase (no prior phases), or no prior VERIFICATION.md files exist.

Step 1: Discover prior phases' test files

# Find all VERIFICATION.md files from prior phases in current milestone
PRIOR_VERIFICATIONS=$(find .planning/phases/ -name "*-VERIFICATION.md" ! -path "*${PHASE_NUMBER}*" 2>/dev/null)

Step 2: Extract test file lists from prior verifications

For each VERIFICATION.md found, look for test file references:

• Lines containing test, spec, or __tests__ paths
• The "Test Suite" or "Automated Checks" section
• File patterns from key-files.created in corresponding SUMMARY.md files that match *.test.* or *.spec.*

Collect all unique test file paths into REGRESSION_FILES.

Step 3: Run regression tests (if any found)

# Resolve test command: project config > Makefile > language sniff
REG_TEST_CMD=$(gsd_run query config-get workflow.test_command --default "" 2>/dev/null || true)
if [ -z "$REG_TEST_CMD" ]; then
  if [ -f "Makefile" ] && grep -q "^test:" Makefile; then
    REG_TEST_CMD="make test"
  elif [ -f "Justfile" ] || [ -f "justfile" ]; then
    REG_TEST_CMD="just test"
  elif [ -f "package.json" ]; then
    REG_TEST_CMD="npm test"
  elif [ -f "Cargo.toml" ]; then
    REG_TEST_CMD="cargo test"
  elif [ -f "go.mod" ]; then
    REG_TEST_CMD="go test ./..."
  elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
    REG_TEST_CMD="python -m pytest ${REGRESSION_FILES} -q --tb=short"
  else
    REG_TEST_CMD="true"
  fi
fi
# Detect test runner and run prior phase tests
eval "$REG_TEST_CMD" 2>&1

Step 4: Report results

If all tests pass:

✓ Regression gate: {N} prior-phase test files passed — no regressions detected

→ Proceed to verify_phase_goal

If any tests fail:

## ⚠ Cross-Phase Regression Detected

Phase {X} execution may have broken functionality from prior phases.

| Test File | Phase | Status | Detail |
|-----------|-------|--------|--------|
| {file} | {origin_phase} | FAILED | {first_failure_line} |

Options:
1. Fix regressions before verification (recommended)
2. Continue to verification anyway (regressions will compound)
3. Abort phase — roll back and re-plan

Use AskUserQuestion to present the options.

Post-execution schema drift detection. Catches false-positive verification where build/types pass because TypeScript types come from config, not the live database.

Run after execution completes but BEFORE verification marks success.

SCHEMA_DRIFT=$(gsd_run query verify.schema-drift "${PHASE_NUMBER}" 2>/dev/null)

Parse JSON result for: drift_detected, blocking, schema_files, orms, unpushed_orms, message.

If drift_detected is false: Skip to verify_phase_goal.

If drift_detected is true AND blocking is true:

Check for override:

SKIP_SCHEMA=$(echo "${GSD_SKIP_SCHEMA_CHECK:-false}")

If SKIP_SCHEMA is true:

Display:

⚠ Schema drift detected but GSD_SKIP_SCHEMA_CHECK=true — bypassing gate.

Schema files changed: {schema_files}
ORMs requiring push: {unpushed_orms}

Proceeding to verification (database may be out of sync).

→ Continue to verify_phase_goal.

If SKIP_SCHEMA is not true:

BLOCK verification. Display:

## BLOCKED: Schema Drift Detected

Schema-relevant files changed during this phase but no database push command
was executed. Build and type checks pass because TypeScript types come from
config, not the live database — verification would produce a false positive.

Schema files changed: {schema_files}
ORMs requiring push: {unpushed_orms}

Required push commands:
{For each unpushed ORM, show the push command from the message}

Options:
1. Run push command now (recommended) — execute the push, then re-verify
2. Skip schema check (GSD_SKIP_SCHEMA_CHECK=true) — bypass this gate
3. Abort — stop execution and investigate

If TEXT_MODE is true, present as a plain-text numbered list. Otherwise use AskUserQuestion.

If user selects option 1: Present the specific push command(s) to run. After user confirms execution, re-run the schema drift check. If it passes, continue to verify_phase_goal.

If user selects option 2: Set override and continue to verify_phase_goal.

If user selects option 3: Stop execution. Report partial completion.

Post-execution structural drift detection (#2003). Non-blocking by contract: any internal error here MUST fall through to `verify_phase_goal`. The phase is never failed by this gate.

Load and follow the full step spec from gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md — covers the SDK call, JSON contract, warn vs auto-remap branches, mapper spawn template, and the two workflow.drift_* config keys.

Verify phase achieved its GOAL, not just completed tasks.

VERIFIER_SKILLS=$(gsd_run query agent-skills gsd-verifier)

Agent(
  description="Verify phase {phase_number} goal achievement",
  prompt="Verify phase {phase_number} goal achievement.
Phase directory: {phase_dir}
Phase goal: {goal from ROADMAP.md}
Phase requirement IDs: {phase_req_ids}
Check must_haves against actual codebase.
Cross-reference requirement IDs from PLAN frontmatter against REQUIREMENTS.md — every ID MUST be accounted for.
Create VERIFICATION.md.

<files_to_read>
Read these files before verification:
- {phase_dir}/*-PLAN.md (All plans — understand intent, check must_haves)
- {phase_dir}/*-SUMMARY.md (All summaries — cross-reference claimed vs actual)
- .planning/REQUIREMENTS.md (Requirement traceability)
${CONTEXT_WINDOW >= 500000 ? `- {phase_dir}/*-CONTEXT.md (User decisions — verify they were honored)
- {phase_dir}/*-RESEARCH.md (Known pitfalls — check for traps)
- Prior VERIFICATION.md files from earlier phases (regression check)
` : ''}
</files_to_read>

${VERIFIER_SKILLS}",
  subagent_type="gsd-verifier",
  model="{verifier_model}"
)

ORCHESTRATOR RULE — CODEX RUNTIME: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.

Read status via the canonical query (scoped to frontmatter, covers missing/unknown cases):

VERIFICATION=$(gsd_run query verification.status "$PHASE_DIR" 2>/dev/null)
STATUS=$(printf '%s' "$VERIFICATION" | jq -r '.status' 2>/dev/null || echo "")
NEXT_ACTION=$(printf '%s' "$VERIFICATION" | jq -r '.next_action' 2>/dev/null || echo "")
NEXT_COMMAND=$(printf '%s' "$VERIFICATION" | jq -r '.next_command' 2>/dev/null || echo "")

Route on $STATUS: if passed, proceed to update_roadmap. Otherwise keep the phase pending — present $NEXT_ACTION to the user and, when $NEXT_COMMAND is non-empty, show it as the next command to run. The query covers all cases including missing files (missing) and unexpected values (unknown), so no per-status arm needs to be listed here.

If human_needed:

Step A: Persist human verification items as UAT file.

Create {phase_dir}/{phase_num}-UAT.md using UAT template format:

---
status: testing
phase: {phase_num}-{phase_name}
source: [{phase_num}-VERIFICATION.md]
started: [now ISO]
updated: [now ISO]
---

## Current Test

number: 1
name: {first human_verification item description}
expected: |
  {expected behavior from VERIFICATION.md}
awaiting: user response

## Tests

{For each human_verification item from VERIFICATION.md:}

### {N}. {item description}
expected: {expected behavior from VERIFICATION.md}
result: [pending]

## Summary

total: {count}
passed: 0
issues: 0
pending: {count}
skipped: 0
blocked: 0

## Gaps

Commit the file:

gsd_run query commit "test({phase_num}): persist human verification items as UAT" --files "{phase_dir}/{phase_num}-UAT.md"

Step B: Present to user:

## ◷ Phase {X}: {Name} — Human Verification Needed

All automated checks passed. {N} item(s) require human testing before this phase can be marked complete:

{From VERIFICATION.md human_verification section}

Tests saved to `{phase_num}-UAT.md`.

When ready to run the tests:

`/gsd:verify-work {X} ${GSD_WS}`

Verify-work will walk you through each item and mark the phase complete when all tests pass.

Do NOT advance the phase from this branch. Phase completion is handled by verify-work's auto-transition after UAT passes.

If user acknowledges without reporting issues (including "ok", "noted", "ack", "got it", "approved", "done", "yes", "pass", or similar): Stop. The phase remains pending. No further orchestrator action — wait for the user to run /gsd:verify-work.

If user reports issues now (before running verify-work): Proceed to gap closure as currently implemented.

If gaps_found:

## ⚠ Phase {X}: {Name} — Gaps Found

**Score:** {N}/{M} must-haves verified
**Report:** {phase_dir}/{phase_num}-VERIFICATION.md

### What's Missing
{Gap summaries from VERIFICATION.md}

---
## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}

`/clear` then:

`/gsd:plan-phase {X} --gaps ${GSD_WS}`

Also: `cat {phase_dir}/{phase_num}-VERIFICATION.md` — full report
Also: `/gsd:verify-work {X} ${GSD_WS}` — manual testing first

Gap closure cycle: /gsd:plan-phase {X} --gaps ${GSD_WS} reads VERIFICATION.md → creates gap plans with gap_closure: true → user runs /gsd:execute-phase {X} --gaps-only ${GSD_WS} → verifier re-runs.

**Mark phase complete and update all tracking files:**

COMPLETION=$(gsd_run query phase.complete "${PHASE_NUMBER}")

The CLI handles:

• Marking phase checkbox [x] with completion date
• Updating Progress table (Status → Complete, date)
• Updating plan count to final
• Advancing STATE.md to next phase
• Updating REQUIREMENTS.md traceability
• Scanning for verification debt (returns warnings array)

Extract from result: next_phase, next_phase_name, is_last_phase, warnings, has_warnings.

If has_warnings is true:

## Phase {X} marked complete with {N} warnings:

{list each warning}

These items are tracked and will appear in `/gsd:progress` and `/gsd:audit-uat`.

gsd_run query commit "docs(phase-{X}): complete phase execution" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md {phase_dir}/*-VERIFICATION.md

**Auto-copy phase learnings to global store (when enabled).**

This step runs AFTER phase completion and SUMMARY.md is written. It copies any LEARNINGS.md entries from the completed phase to the global learnings store at ~/.gsd/knowledge/.

Check config gate:

GL_ENABLED=$(gsd_run query config-get features.global_learnings --raw 2>/dev/null || echo "false")

If GL_ENABLED is not true: Skip this step entirely (feature disabled by default).

If enabled:

1. Check if LEARNINGS.md exists in the phase directory (use the phase_dir value from init context)
2. If found, copy to global store:

gsd_run query learnings.copy 2>/dev/null || echo "⚠ Learnings copy failed — continuing"

Copy failure must NOT block phase completion.

**Auto-close pending todos tagged for this phase (#2433).**

This step runs AFTER update_roadmap marks the phase complete. It moves any pending todos that carry resolves_phase: <current-phase-number> to the completed directory.

PHASE_NUM="${PHASE_NUMBER}"
PENDING_DIR=".planning/todos/pending"
COMPLETED_DIR=".planning/todos/completed"
mkdir -p "$COMPLETED_DIR"

CLOSED=()
for TODO_FILE in "$PENDING_DIR"/*.md; do
  [ -f "$TODO_FILE" ] || continue
  # Extract resolves_phase from YAML frontmatter (first --- block only)
  RP=$(awk '/^---/{c++;next} c==1 && /^resolves_phase:/{print $2;exit} c==2{exit}' "$TODO_FILE" 2>/dev/null || true)
  if [ "$RP" = "$PHASE_NUM" ] || [ "$RP" = "\"$PHASE_NUM\"" ]; then
    mv "$TODO_FILE" "$COMPLETED_DIR/"
    CLOSED+=("$(basename "$TODO_FILE")")
  fi
done

if [ ${#CLOSED[@]} -gt 0 ]; then
  gsd_run query commit "docs(phase-${PHASE_NUMBER}): auto-close ${#CLOSED[@]} todo(s) resolved by this phase" --files .planning/todos/completed/ .planning/STATE.md|| true
  echo "◆ Closed ${#CLOSED[@]} todo(s) resolved by Phase ${PHASE_NUMBER}:"
  for f in "${CLOSED[@]}"; do echo "  ✓ $f"; done
fi

If no todos have resolves_phase: <this-phase>: Skip silently — this step is always additive and never blocks phase completion.

**Evolve PROJECT.md to reflect phase completion (prevents planning document drift — #956):**

PROJECT.md tracks validated requirements, decisions, and current state. Without this step, PROJECT.md falls behind silently over multiple phases.

1. Read .planning/PROJECT.md
2. If the file exists and has a ## Validated Requirements or ## Requirements section:
   • Move any requirements validated by this phase from Active → Validated
   • Add a brief note: Validated in Phase {X}: {Name}
3. If the file has a ## Current State or similar section:
   • Update it to reflect this phase's completion (e.g., "Phase {X} complete — {one-liner}")
4. Update the Last updated: footer to today's date
5. Commit the change:

gsd_run query commit "docs(phase-{X}): evolve PROJECT.md after phase completion" --files .planning/PROJECT.md

Skip this step if .planning/PROJECT.md does not exist.

Exception: If gaps_found, the verify_phase_goal step already presents the gap-closure path (/gsd:plan-phase {X} --gaps). No additional routing needed — skip auto-advance.

No-transition check (spawned by auto-advance chain):

Parse --no-transition flag from $ARGUMENTS.

If --no-transition flag present:

Execute-phase was spawned by plan-phase's auto-advance. Do NOT run transition.md. After verification passes and roadmap is updated, return completion status to parent:

## PHASE COMPLETE

Phase: ${PHASE_NUMBER} - ${PHASE_NAME}
Plans: ${completed_count}/${total_count}
Verification: {Passed | Gaps Found}

[Include aggregate_results output]

STOP. Do not proceed to auto-advance or transition.

If --no-transition flag is NOT present:

Auto-advance detection:

1. Parse --auto flag from $ARGUMENTS
2. Read consolidated auto-mode (active = chain flag OR user preference; chain flag already synced in init step):

   AUTO_MODE=$(gsd_run query check auto-mode --pick active 2>/dev/null || echo "false")
   

If --auto flag present OR AUTO_MODE is true (AND verification passed with no gaps):

╔══════════════════════════════════════════╗
║  AUTO-ADVANCING → TRANSITION             ║
║  Phase {X} verified, continuing chain    ║
╚══════════════════════════════════════════╝

Execute the transition workflow inline (do NOT use Agent — orchestrator context is ~10-15%, transition needs phase completion data already in context):

Read and follow ~/.claude/gsd-core/workflows/transition.md, passing through the --auto flag so it propagates to the next phase invocation.

If neither --auto nor AUTO_MODE is true:

STOP. Do not auto-advance. Do not execute transition. Do not plan next phase. Present options to the user and wait.

IMPORTANT: There is NO /gsd-transition command. Never suggest it. The transition workflow is internal only.

Check whether CONTEXT.md already exists for the next phase:

ls .planning/phases/*{next}*/{next}-CONTEXT.md 2>/dev/null || echo "no-context"

If CONTEXT.md does not exist for the next phase, present:

## ✓ Phase {X}: {Name} Complete

/gsd:progress ${GSD_WS} — see updated roadmap
/gsd:discuss-phase {next} ${GSD_WS} — start here: discuss next phase before planning  ← recommended
/gsd:plan-phase {next} ${GSD_WS} — plan next phase (skip discuss)
/gsd:execute-phase {next} ${GSD_WS} — execute next phase (skip discuss and plan)

If CONTEXT.md exists for the next phase, present:

## ✓ Phase {X}: {Name} Complete

/gsd:progress ${GSD_WS} — see updated roadmap
/gsd:plan-phase {next} ${GSD_WS} — start here: plan next phase (CONTEXT.md already present)  ← recommended
/gsd:discuss-phase {next} ${GSD_WS} — re-discuss next phase
/gsd:execute-phase {next} ${GSD_WS} — execute next phase (skip planning)

Only suggest the commands listed above. Do not invent or hallucinate command names.

<context_efficiency> Orchestrator: ~10-15% context for 200k windows, can use more for 1M+ windows. Subagents: fresh context each (200k-1M depending on model). No polling (Agent blocks). No context bleed.

For 1M+ context models, consider:

• Passing richer context (code snippets, dependency outputs) directly to executors instead of just file paths
• Running small phases (≤3 plans, no dependencies) inline without subagent spawning overhead
• Relaxing /clear recommendations — context rot onset is much further out with 5x window </context_efficiency>

<failure_handling>

• Quota / rate-limit (any runtime — #3095): Agent return body contains a sentinel like usage limit, rate limit, 429, too many requests, RESOURCE_EXHAUSTED, usage_limit_reached. Route via gsd-tools.cjs query agent.classify-failure → class: "quota-exceeded". Do not offer retry-now; the right action is wait-for-reset and resume.
• classifyHandoffIfNeeded false failure: Agent reports "failed" but error is classifyHandoffIfNeeded is not defined → Claude Code bug, not GSD. Spot-check (SUMMARY exists, commits present) → if pass, treat as success
• Agent fails mid-plan: Missing SUMMARY.md → report, ask user how to proceed
• Dependency chain breaks: Wave 1 fails → Wave 2 dependents likely fail → user chooses attempt or skip
• All agents in wave fail: Systemic issue → stop, report for investigation
• Checkpoint unresolvable: "Skip this plan?" or "Abort phase execution?" → record partial progress in STATE.md </failure_handling>

Re-run `/gsd:execute-phase {phase}` → discover_plans finds completed SUMMARYs → skips them → resumes from first incomplete plan → continues wave execution.

STATE.md tracks: last completed plan, current wave, pending checkpoints.