740ba0d8a3
Emitted-Drift-Ack-Growth: execute-phase.md — #4628 consumer wiring: ready_plans parse pointer, not-ready named skip, and waiting condition 2b reference to the ready-wave-gate step file Co-authored-by: sim <sim@local>
91 KiB
<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-aware dispatch (#2508 Phase 4). GSD workflows dispatch specialized subagents by role. Before dispatching on a built-in-only runtime (kimi-code — three built-ins only), resolve the role to a built-in via
gsd_run query resolve-dispatch-type --requested <role> --raw. On named-dispatch runtimes (Claude/OpenCode/…) the role is returned unchanged; on kimi-code it maps tocoder/explore/planby role-suffix. The persona rides${AGENT_SKILLS_<ROLE>}(Phase 3) regardless. See @gsd-core/references/runtime-aware-dispatch.md.
<runtime_compatibility> Subagent spawning is runtime-specific:
- Claude Code: Uses
Agent(subagent_type="gsd-executor", ...)— backgrounded by default; verify completion - 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.
- Codex: native subagent sessions can end abnormally (
turn_aborted) after the plan work is already committed. Completion is decided by the step-4 artifact reconciliation (SUMMARY + matching recent commits), not by the session's terminal state (#4217). - Other runtimes: If
Agent/agenttool is genuinely unavailable (e.g. a backgrounded Claude Code agent per #853, or a non-Claude runtime), use sequential inline execution as the fallback for executor parallelization only. IfAgentIS available (top-level Claude Code), you MUST spawn gsd-executor agents — inline execution is not authorized. Check for actual tool availability, not 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>
Compact Content Gate. Read and follow gsd-core/references/compact-content-gate.md now — it states the workflow.compact_content check and the resolution rule this spine defers to. When it directs a Read, read gsd-core/workflows/execute-phase/detail/elaboration.md in full before continuing past this point; its content elaborates on two steps below (check_interactive_mode, cross_ai_delegation).
- First positional token →
PHASE_ARG - Optional
--wave N→WAVE_FILTER - Optional
--gaps-onlykeeps 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.
_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
WAVE_PARAM=""; if [[ "$ARGUMENTS" =~ (^|[[:space:]])--wave[[:space:]]+([^[:space:]-][^[:space:]]*) ]]; then WAVE_PARAM="--wave ${BASH_REMATCH[2]}"; fi
INIT=$(gsd_run query init.execute-phase "${PHASE_ARG}" $WAVE_PARAM)
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, requirements_path, section_manifest.
section_manifest (#2932) gates the three steps/*.md reads below: read a step file only when its id is in section_manifest.included (equivalently, its path is in section_manifest.read); skip it — without reading — when its id is in section_manifest.excluded. When section_manifest is null (degraded: manifest artifact missing/unreadable), read all three unconditionally — the safe superset.
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 orchestrator model automatically. Only set model= when executor_model is an explicit model name (e.g., "claude-sonnet-5", "claude-opus-4-8").
@~/.claude/gsd-core/references/execute-phase-response-language.md
Read runtime/worktree config and fail closed before any executor dispatch:
RUNTIME=$(gsd_run query config-get runtime --default claude --raw 2>/dev/null || echo "claude")
USE_WORKTREES=$(gsd_run query config-get workflow.use_worktrees --raw 2>/dev/null || echo "true")
EXECUTOR_STALL_INTERVAL_MINUTES=$(gsd_run query config-get executor.stall_detect_interval_minutes --raw 2>/dev/null || echo "5")
EXECUTOR_STALL_THRESHOLD_MINUTES=$(gsd_run query config-get executor.stall_threshold_minutes --raw 2>/dev/null || echo "10")
# Resolve ISOLATION + apply its guards: read and execute the "Resolve ISOLATION"
# section of execute-phase/steps/executor-isolation-dispatch.md. It sets
# ISOLATION (harness-worktree|orchestrator-worktree|none), forces none when
# USE_WORKTREES=false, fails closed when a host has no primitive, sweeps orphans,
# and applies the #683 fork-base auto-degrade.
ISOLATION — not RUNTIME — is the ONLY fan-out branch point; never add a RUNTIME = "codex" test here. Per-host dispatch detail lives in execute-phase/steps/executor-isolation-dispatch.md (read from step 3).
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. 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 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 is false, ISOLATION is forced to none: executors run sequentially on the main working tree. The per-plan decision below has no effect when worktrees are project-disabled.
USE_WORKTREES and ISOLATION are also reset for the run when worktree base-check detects the orchestrator HEAD has diverged from the worktree fork base (#683 — e.g. an unmerged milestone branch). This runs for any isolated run, not only Claude: fork-base divergence is a property of the repository, so it degrades a GSD-created worktree exactly as a harness-created one. 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. Setting worktree.baseRef:"head" restores parallel execution only where GSD itself creates the worktrees (orchestrator-managed runtimes — Codex, OpenCode, Kimi, Kimi Code); harness-isolated runtimes (Claude Code, Cursor) do not read the setting (#48, verified 5/5; upstream claude-code#44965), so there the check compares against the real fork base and parallel execution returns once HEAD is merged/pushed so origin/HEAD matches it (#3659). 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 --raw 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)
EXECUTE_POST_HOOKS_JSON=$(gsd_run loop render-hooks execute:post --raw)
TDD_MODE=$(gsd_run loop render-hooks execute:post --active-cap tdd)
TDD gate. Task-scoped enforcement runs inside plan execution (immediately before each implementation step), where TASK_FILE, PLAN_ID, and TASK_ID are defined. #4011: the gate keys on TDD_MODE ALONE — a discipline gate coupled to the product-scope MVP_MODE flag was silently inert on every non-MVP phase, contradicting gsd-core/references/tdd.md's contract that workflow.tdd_mode binds for all type: tdd plans. MVP mode remains free to imply TDD; it is no longer required by it. Keep the same predicate and RED-commit contract:
if [ "$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
# #4003: same anchored scope and milestone bound as safe_resume_gate — a padded
# literal grep hard-halts on a correct unpadded RED commit.
# #4619: PHASE_NUMBER may be decimal/N-segment; zero-strip only the leading
# integer segment, escape the rest for the ERE below.
PHASE_INT=${PHASE_NUMBER%%.*}; PHASE_FRAC=${PHASE_NUMBER#"$PHASE_INT"}
PHASE_N="$((10#$PHASE_INT))${PHASE_FRAC//./\\.}"
PLAN_N=$((10#${PLAN_ID}))
PLAN_SCOPE_RE="^[a-z]+\((0*${PHASE_N})-(0*${PLAN_N})\):" # TDD gate's own scope check
TDD_MILESTONE_BASE=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
# #4379: this pathspec IS the gate's definition of "a test file". It was
# JS/TS-only, so Go tripped on every task; and `**/` never matches a
# root-level path, so a root `foo.test.js` was invisible too. Bare globs
# match at every depth. NOT widened to ordinary source — that would make
# the gate pass on any in-scope commit. Trade-offs and the Rust gap:
# references/tdd.md § Create first test file.
RED_COMMIT=$(git log --oneline -E ${TDD_MILESTONE_BASE:+"$TDD_MILESTONE_BASE..HEAD"} --grep="${PLAN_SCOPE_RE}" -- "*.test.*" "*.spec.*" "tests/" "__tests__/" "*_test.go" "test_*.py" "*_test.py" "*_test.exs" "*_spec.rb" "*_test.rb" | head -1)
if [ -z "$RED_COMMIT" ]; then
gsd_run query state.update last_gate_trip "${PLAN_ID}/${TASK_ID}" || true
echo "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.
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:
- What is this anti-pattern? — Describe it in your own words, not by quoting the handoff.
- How did it manifest? — Explain the specific failure that caused it to be recorded.
- 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.
Skip to handle_branching step (interactive plans execute inline after grouping).
Check `branching_strategy` from init:"none": Read and execute execute-phase/steps/protected-branch.md.
"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=$(gsd_run query git.base-branch 2>/dev/null \
|| git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||' \
|| echo 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 (#2916); --no-track (#2498). #2639: warn if local ahead of origin.
AHEAD=$(git rev-list --count "origin/$DEFAULT_BRANCH..$DEFAULT_BRANCH" 2>/dev/null || echo 0)
[ "$AHEAD" != "0" ] && [ -n "$AHEAD" ] && echo "WARNING: $DEFAULT_BRANCH is $AHEAD ahead of origin — '$BRANCH_NAME' won't include those commits (#2639)." >&2
git checkout -b "$BRANCH_NAME" "origin/$DEFAULT_BRANCH" --no-track \
|| { 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[], waves, incomplete, runnable, ready_plans, has_checkpoints — full per-plan fields and the #4628 readiness rules: read and follow execute-phase/steps/ready-wave-gate.md.
Filtering: Skip plans where has_summary: true. Additionally skip any plan whose blocked_by array is non-empty (#2830) — it depends, directly or transitively, on a plan that halted at a designed stop rather than completing — and report it by name: "Skipping {plan.id}: blocked by halted {blocked_by.join(', ')}". Never silently drop a blocked plan from the report; it must appear by name with its reason, not merely vanish from the executable list. This rule is additive to the has_summary skip, not a replacement for it. Additionally skip any incomplete plan with ready: false (#4628 — see execute-phase/steps/ready-wave-gate.md; never dispatch a not-ready plan). 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 — do NOT exit unconditionally (#2868). "No plan work left" and "phase fully
done" are different conditions: a run can be interrupted between the final wave's SUMMARY and
verify_phase_goal (most commonly by a checkpoint plan that is retired but still writes a SUMMARY),
leaving a phase that looks complete from every index yet never produced *-VERIFICATION.md. A
third condition looks identical to the first two by plan_count alone but is neither: some filtered
plans were filtered because they are blocked (non-empty blocked_by, #2830), not because they
are done. Blocked-and-incomplete must never be reported as finished.
VERIFY_STATUS=$(gsd_run query verification status "${PHASE_DIR}" --pick status)
# #3684: checkbox = marked-complete; report fields can claim a no-op write (#3685).
ANALYZE=$(gsd_run query roadmap.analyze)
if [[ "$ANALYZE" == @file:* ]]; then ANALYZE=$(cat "${ANALYZE#@file:}"); fi
PHASE_MARKED=$(echo "$ANALYZE"|jq -r --arg p "$PHASE_NUMBER" 'def n:sub("^0+(?=[0-9])";"");.phases[]|select(((.number//.phase_number|tostring|n))==($p|n))|.roadmap_complete'|head -1)
Evaluate in this exact order — the first matching condition decides the outcome; do not evaluate later conditions once one matches:
- A filter is active (
--gaps-only, orWAVE_FILTERset): report "No matching incomplete plans" → exit, unchanged. A filtered run finding nothing left in ITS slice says nothing about whether the phase as a whole is done, and must never jump to verification. - No filter is active, and at least one filtered plan was skipped because of a non-empty
blocked_by(irrespective ofVERIFY_STATUS): the phase is NOT finished — it is stuck on a halt. A plan with no SUMMARY and no dispatched work must never be treated as done merely because nothing was left to filter. Report:"Phase stuck: {blocked plan ids} blocked by halted {their blocked_by ids} — resolve the halt, do not resume verification."→ exit. Do not fall through to condition 3; this is not a completion state. 2b. No filter is active, no blocked-plan skip occurred, and at least one filtered plan was skipped becauseready: false(#4628) — the phase is WAITING on incomplete predecessors, not finished: report it by name and exit before any completion state (execute-phase/steps/ready-wave-gate.md). - No filter is active, and every filtered plan was filtered by
has_summaryalone (no blocked-plan skip occurred):VERIFY_STATUS == missing: the plans are all summarized but the run never reached the tail gates. Report:"All {plan_count} plans are summarized but no VERIFICATION.md exists — resuming at the phase gates (#2868)."SKIPcross_ai_delegation,execute_wavesandcheckpoint_handling— there is no wave work to do — and continue directly ataggregate_results, NOTcode_review_gate.aggregate_resultsis the only step that runs theSECURITY_FILE/ secure-phase threats-open gate, and it reads exclusively from on-disk${PHASE_DIR}artifacts (*-SUMMARY.md,*-SECURITY.mdvials) and independentgsd_runcalls — nothing it reads is produced only byexecute_wavesorcheckpoint_handling— so it tolerates having executed no plans in this run. From there the run proceeds exactly as a normal one:aggregate_results→code_review_gate→close_parent_artifacts→regression_gate→verify_phase_goal→update_roadmap. Never skipaggregate_results,code_review_gateorregression_gateon this path — the manual workaround this replaces skipped all three, and that gap is the reason this route exists rather than telling users to spawn the verifier by hand.VERIFY_STATUS≠missing+PHASE_MARKEDistrue: genuinely finished. Report "No matching incomplete plans" → exit, unchanged.VERIFY_STATUS≠missing+PHASE_MARKEDnottrue— the run died betweenverify_phase_goalandupdate_roadmap(#3684): verification EXISTS — do not redo it or the gates already run. Report"Phase {X} is verified but never marked complete — resuming at update_roadmap (#3684)."and continue directly atupdate_roadmap; the tail steps then run in their normal order.
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 | ... |
For each marked plan: build a self-contained prompt from the plan's <objective>/<tasks> plus PROJECT.md context, warn on a dirty working tree, then run the configured command wrapped in gsd_run run-with-timeout "${CROSS_AI_TIMEOUT}" (config workflow.cross_ai_timeout, default 300s) — never run it unbounded — with the prompt piped to stdin, never shell-interpolated, to prevent injection. On success (exit 0): validate the captured SUMMARY output is non-empty and structurally valid before writing it as the plan's SUMMARY.md, update STATE/ROADMAP, mark handled. On failure (non-zero exit, or the summary fails that validation): show the error, warn about possible partial edits, and offer retry / skip (falls back to the normal executor) / abort. Successfully handled plans are removed from execute_waves' list; skipped-to-fallback plans remain in it.
Exact bash and per-branch wording: gsd-core/workflows/execute-phase/detail/elaboration.md § 2.
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 agent-/worktree-agent-/worktree-wf_, NOT the 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.
# gsd:guard=orchestrator-cwd-drift
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-|worktree-wf_)'; 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
# #1856 handoff: the refusal above is correct, but on its own it is a dead end —
# this worktree may hold committed fixes AND uncommitted work, and "re-run from
# the orchestrator's worktree" silently means abandoning them. Report exactly
# what is stranded and how to integrate it. Every command here is DIAGNOSTIC:
# each is `|| true`-guarded so a failure degrades to the plain refusal above
# rather than crashing before the message prints.
_WT_BASE=""
for _ref in "$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null || true)" \
origin/next origin/main next main; do
[ -n "$_ref" ] || continue
if git rev-parse --verify --quiet "$_ref" >/dev/null 2>&1; then _WT_BASE="$_ref"; break; fi
done
_WT_AHEAD=""
[ -n "$_WT_BASE" ] && _WT_AHEAD=$(git rev-list --count "$_WT_BASE..HEAD" 2>/dev/null || true)
# Count BEFORE truncating, so a long list reports its true size rather than
# under-reporting what is stranded — which is the whole point of this report.
_WT_DIRTY_ALL=$(git status --porcelain 2>/dev/null || true)
_WT_DIRTY_N=0
[ -n "$_WT_DIRTY_ALL" ] && _WT_DIRTY_N=$(printf '%s\n' "$_WT_DIRTY_ALL" | wc -l | tr -d ' ')
_WT_HAS_COMMITS=0
[ -n "$_WT_AHEAD" ] && [ "$_WT_AHEAD" -gt 0 ] 2>/dev/null && _WT_HAS_COMMITS=1
echo "" >&2
echo "── Handoff: what is in this worktree (#1856) ──" >&2
if [ "$_WT_HAS_COMMITS" -eq 1 ]; then
echo " $_WT_AHEAD commit(s) on '$ORCH_BRANCH' not on '$_WT_BASE':" >&2
git log --oneline --no-decorate "$_WT_BASE..HEAD" 2>/dev/null | head -20 | sed 's/^/ /' >&2 || true
[ "$_WT_AHEAD" -gt 20 ] 2>/dev/null && echo " … and $((_WT_AHEAD - 20)) more" >&2
echo " These live ONLY on this branch. Switching away without integrating loses them." >&2
fi
if [ -n "$_WT_DIRTY_ALL" ]; then
echo " $_WT_DIRTY_N uncommitted change(s) still in this worktree:" >&2
printf '%s\n' "$_WT_DIRTY_ALL" | head -20 | sed 's/^/ /' >&2
[ "$_WT_DIRTY_N" -gt 20 ] 2>/dev/null && echo " … and $((_WT_DIRTY_N - 20)) more" >&2
fi
if [ "$_WT_HAS_COMMITS" -eq 1 ] || [ -n "$_WT_DIRTY_ALL" ]; then
echo "" >&2
echo " To integrate before continuing:" >&2
[ -n "$_WT_DIRTY_ALL" ] && echo " 1. git add -A && git commit -m 'wip: recover worktree state' # from THIS worktree" >&2
echo " 2. cd <orchestrator worktree> # a checkout whose branch is NOT agent-*/worktree-agent-*" >&2
echo " 3. git merge --no-ff $ORCH_BRANCH # or: git cherry-pick <sha>... for selected commits" >&2
echo " 4. re-run the phase from there" >&2
echo " Verify with: git log --oneline ${_WT_BASE:-HEAD}..$ORCH_BRANCH" >&2
fi
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}iscomplete(success),failed(executor error), orcheckpoint(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:
@~/.claude/gsd-core/references/execute-phase-wave-guard.md
@~/.claude/gsd-core/references/execute-phase-context-guard.md
-
Intra-wave files_modified overlap check (BEFORE spawning):
Before spawning any agents for this wave, inspect the
files_modifiedlist of all plans in the wave. Check every pair of plans in the wave — if any two plans share even one file in theirfiles_modifiedlists, 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] = planIf 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
PARALLELIZATIONtofalsefor 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). - Warn the user:
-
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 doneThen 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 and biome zones. Required before vehicle physics."
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 gate on both USE_WORKTREES and USE_WORKTREES_FOR_PLAN (#2474).
2.75. Execute:wave:pre capability dispatch:
WAVE_PRE_HOOKS_JSON=$(gsd_run loop render-hooks execute:wave:pre --raw)
Contribution dispatch: inject every kind == "contribution" fragment per @gsd-core/references/loop-hook-dispatch.md (skip when none); one naming an alternate wave dispatch replaces step 3's inline loop.
Step dispatch: kind == "step" per @gsd-core/references/loop-hook-dispatch.md; never blocks or redirects executor spawning. ⚠ Validate ref.command in-context before any shell use.
-
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.
Substitute
{plan_id}in the prompt below with this plan'sidfield from thephase-plan-indexJSON loaded in step 1 (the same field referred to elsewhere in this workflow asplan.id) — unmodified and un-truncated, never a paraphrase. The guard hooks compare this value verbatim against the sentinel the per-plan gate wrote (per-plan-worktree-gate.md'splan_id); a paraphrase or an omission costs the dispatch its recorded isolation decision.Executor routing (#1689/#3370). Per plan, run
gsd-core/workflows/execute-phase/steps/per-plan-executor-routing.mdto setEXECUTOR_TYPEforsubagent_type="{EXECUTOR_TYPE}"below.TDD-applicability resolution (#4266/#4272). Run
gsd-core/workflows/execute-phase/steps/tdd-applicability-resolution.md.Worktree mode (
USE_WORKTREESandUSE_WORKTREES_FOR_PLANnotfalse):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:-true}" != "false" ] && [ "${USE_WORKTREES_FOR_PLAN:-true}" != "false" ] && [ -z "${WAVE_WORKTREE_MANIFEST:-}" ]; then M=$(mktemp "${TMPDIR:-/tmp}/gsd-worktree-wave-XXXXXX") && mv "$M" "$M.json" && WAVE_WORKTREE_MANIFEST="$M.json" || exit 1 # XXXXXX must be path-final on BSD/macOS (#1520) # 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 fiIsolation model. The block below is the
harness-worktreepath. Fororchestrator-worktreeuse the dispatch below it; fornoneuse sequential mode. Both are detailed inexecute-phase/steps/executor-isolation-dispatch.md.Sequential dispatch for parallel execution (waves with 2+ agents): Dispatch each
Agent()call one at a time withrun_in_background: true. Do NOT send all Agent calls in a single message: simultaneousgit worktree addcalls 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 contentionAgent( subagent_type="{EXECUTOR_TYPE}", 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" # The host's OWN declared isolation flag (`harnessFlag` from # `dispatch-isolation --json`; see the isolation-dispatch fragment). # Emit the declared token — do NOT hardcode a runtime's flag. {harnessFlag}, prompt=" <objective> Execute plan {plan_number} of phase {phase_number}-{phase_name}. [gsd:dispatch phase="{phase_number}" plan="{plan_id}"] 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 + `gsd-core/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> ORCHESTRATOR build-time embed (NOT a sub-agent runtime step): before this dispatch, read each file listed below and replace this note with those files' contents, inlined verbatim in this block in the listed order. Never leave `@`-include lines in the dispatched prompt — `@path` never expands inside an Agent() `prompt="..."` string (#3324), so an include arrives as literal text the executor never sees. - `~/.claude/gsd-core/workflows/execute-plan.md` - `~/.claude/gsd-core/templates/summary.md` - `~/.claude/gsd-core/references/checkpoints.md` ${TDD_APPLICABLE ? '- `~/.claude/gsd-core/references/tdd.md`' : ''} # #3990/#4265: type: tdd, tdd="true", or workflow.tdd_mode - `~/.claude/gsd-core/references/worktree-path-safety.md` ${CONTEXT_WINDOW < 200000 ? '' : '- `~/.claude/gsd-core/references/executor-examples.md`'} </execution_context> <required_reading> 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) </required_reading> ${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> " )After each
Agent()returns, parse executor-returned worktree metadata (<worktree_metadata>) before harness metadata, then record the{agent_id, worktree_path, branch, expected_base}entry withgsd_run query worktree.record-agent --manifest "$WAVE_WORKTREE_MANIFEST" --agent-id … --path … --branch … --base … --files "$PLAN_FILES" --deletions "$PLAN_DELETIONS". The verb validates every field at write time using thecleanup-wavereader's own rules (write-strict--agent-id), failing loudly with a recovery hint rather than appending an under-populated entry the reader would later drop silently. On a non-zero exit or any missing field: stop and ask for recovery instead of scanning worktrees.Worktree recovery policy (#48 + #1292): See
execute-phase/steps/worktree-recovery-policy.md— FAIL-CLOSED rule for base/HEAD-namespace mismatches AND isolated-run fail-safe recovery.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. While waiting, run the step-4 completion surveillance; if the child's session ends abnormally — including
turn_aborted— reconcile artifacts perexecute-phase/steps/completion-reconciliation.mdbefore classifying the plan (#4217).Orchestrator-managed worktree dispatch (
ISOLATION=orchestrator-worktree): read and executeexecute-phase/steps/executor-isolation-dispatch.md. GSD creates each worktree (worktree create) and spawns the executor into it; the orchestrator performs every git operation. Merge-back and cleanup are the existing manifest-scoped gauntlet, unchanged.Sequential mode (
USE_WORKTREES_FOR_PLANisfalse— either project-levelUSE_WORKTREES=false, or per-plan submodule intersection forced it false in step 2.5):Omit
isolation="worktree"from the Agent call. Before composing the prompt, read and executeexecute-phase/steps/sequential-root-pin.md(#4254) — it owns the sequential root-pin build-time embed and the wave serialization rules.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. Run the `<project_root_pin>` guard before your first Edit/Write and before every commit (#4254). 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> <project_root_pin> {ORCHESTRATOR build-time embed: bound step-0p guard per sequential-root-pin.md — never this note} </project_root_pin>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> -
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 —
completeadvances{P},failedandcheckpointdo 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 reconciliation (EVERY runtime — any spawn whose terminal response may not arrive):
If a spawned agent does not return a normal terminal completion response — or its session ends abnormally (interrupted, aborted, closed, killed, timed out,
turn_aborted, including ends the orchestrator itself initiated) — do NOT block indefinitely and do NOT classify the plan as failed yet. Read and executegsd-core/workflows/execute-phase/steps/completion-reconciliation.md— reconcile the plan artifacts FIRST, classify SECOND: SUMMARY present AND matching recent commits → complete (proceed to step 5, do NOT re-dispatch); no completion evidence → the failure handler. Verify, never wait.Configurable stall surveillance (#3212): Every
${EXECUTOR_STALL_INTERVAL_MINUTES}minutes while waiting, inspectgit 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, orkill and switch to inline execution.A working executor is never steered (#4218). The threshold measures time WITHOUT PROGRESS, not total runtime. Before treating an executor as stalled — and before sending it any message — read and execute
execute-phase/steps/executor-progress-policy.md. -
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=trueopted out of per-commit hooks:SKIP_HOOKS=$(gsd_run query config-get workflow.worktree_skip_hooks --raw 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") fiIf 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.
If the user declines to merge a worktree or a worktree over-reached scope, apply the worktree recovery policy (execute-phase/steps/worktree-recovery-policy.md) — never default to editing main.
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.75. Execute:wave:post capability dispatch:
After worktree merge, post-merge tests, and tracking updates, dispatch capability hooks registered at execute:wave:post. The primary hook is the ui.safety-gate gate from the UI capability — it verifies that any frontend files changed in this wave conform to the UI-SPEC contract.
WAVE_POST_HOOKS_JSON=$(gsd_run loop render-hooks execute:wave:post --raw)
Read the activeHooks array from WAVE_POST_HOOKS_JSON in-context (do NOT pipe through a shell parser).
If activeHooks is empty or absent: Skip silently to step 5.8.
Contribution dispatch: inject every kind == "contribution" fragment per @gsd-core/references/loop-hook-dispatch.md (skip when none), before the gates below.
Step dispatch: dispatch every kind == "step" hook per @gsd-core/references/loop-hook-dispatch.md (skip when none) — not one shape of one. A step here is advisory: it never blocks wave completion. ⚠ Validate ref.command in-context before any shell use (third-party manifest input) — loop-hook-dispatch.md § step. ref.skill == "code-review" (#3661): the generic contract's bare skill dispatch carries no phase argument, but code-review.md's initialize step requires one (PHASE_ARG="${1}") or it reports "Phase not found" and exits — pass it explicitly, mirroring step code_review_gate below: Skill(skill="gsd-code-review", args="${PHASE_NUMBER}").
For each active entry where kind == "gate" (process in array order): read and execute gsd-core/workflows/execute-phase/steps/wave-post-gate-hooks.md for the full evaluation contract (check validation, onError, blocking semantics, mapper spawn). When all active gates are processed without a blocking halt, continue to step 5.8.
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 (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.
-
Report completion — spot-check claims first:
Wave-close heartbeat (#2410): after spot-checks finish (pass or fail), before the
## Wave {N} Completesummary, 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.createdexist on disk - Check
git log --oneline --all --grep="{phase}-{plan}"returns ≥1 commit - Check for
## Self-Check: FAILEDmarker
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} --- - Verify first 2 files from
-
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=""; fiOne classifier branch handles sentinels across Claude/Copilot/Codex/Antigravity. Reference:
docs/research/provider-rate-limit-signals.md. Abnormal ends reconcile first (#4217): an abnormal session end (turn_aborted-class) routes through the step-4 artifact reconciliation BEFORE classifying the failure — artifacts decide. Step 7.1 —class == "quota-exceeded": follow the quota-recovery fragment below. Step 7.2 —class == "classify-handoff-bug": If error containsclassifyHandoffIfNeeded 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.
@~/.claude/gsd-core/references/execute-phase-quota-recovery.md
@~/.claude/gsd-core/references/execute-phase-between-wave-reset.md
- Execute checkpoint plans between waves — see
<checkpoint_handling>. - Proceed to next wave.
Plans with
autonomous: falserequire user interaction. Auto-mode checkpoint handling: Read auto-advance config (chain flag OR user preference — same boolean ascheck.auto-mode):
AUTO_MODE=$(gsd_run query check auto-mode --pick active 2>/dev/null)
When executor returns a checkpoint AND AUTO_MODE is true:
- human-verify → Auto-spawn continuation agent with
{user_response}="approved". Log⚡ Auto-approved checkpoint. Exceptblocking-human. - decision → Auto-spawn continuation agent with
{user_response}= first option from checkpoint details. Log⚡ Auto-selected: [option]. Exceptblocking-human. - human-action → Present to user (existing behavior below). Auth gates cannot be automated.
Carve-out — overrides all branches above. If the returned Gate: is blocking-human (precondition-unmet, #3210), or its <what-built> mentions Package verification required before install or Package install failed — human verification required, never auto-approve or auto-select. Present to user (standard flow). Log ⛔ blocking-human gate — auto-mode suspended.
Standard flow (not auto-mode, human-action, or blocking-human):
- Spawn agent for checkpoint plan
- Agent runs until checkpoint task or auth gate → returns structured state
- Agent return includes: completed tasks table, current task + blocker, checkpoint type/details, what's awaited
- 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] - User responds: "approved"/"done" | issue description | decision selection
- 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
- Continuation agent verifies previous commits, continues from resume point
- 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:
VERIFY_POST_HOOKS_JSON=$(gsd_run loop render-hooks verify:post --raw)
SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
Dispatch every kind == "step" hook per @gsd-core/references/loop-hook-dispatch.md (skip when none). The secure-phase routing below applies when that specific hook is active.
If no active secure-phase step hook exists: skip.
If an active secure-phase step hook exists 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 an active secure-phase step hook exists AND SECURITY.md exists: check frontmatter threats_open. If > 0:
⚠ Security gate: {threats_open} threats open
/gsd:secure-phase {PHASE} — resolve before advancing
If section_manifest is null or "partial-wave" is in its included list: read and execute gsd-core/workflows/execute-phase/steps/partial-wave.md. Otherwise skip — do not read the file.
Capability gate:
EXECUTE_POST_HOOKS_JSON=${EXECUTE_POST_HOOKS_JSON:-$(gsd_run loop render-hooks execute:post --raw)}
Dispatch kind == "step" hooks per @gsd-core/references/loop-hook-dispatch.md. ref.skill == "code-review":
If no active code-review step hook exists: display "Code review skipped (code-review capability inactive)" and proceed to gate dispatch.
Invoke review:
Skill(skill="gsd-${ref.skill}", 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 gate dispatch. Review failures must never block execution.
Execute:post gate hook dispatch. After code review, dispatch all active gate hooks from EXECUTE_POST_HOOKS_JSON where kind == "gate". ⚠ Validate check before shell use (third-party manifest input) — loop-hook-dispatch.md § gate. For each, run the form below, or — for a predicate gate (ADR-2008 / #2008) — gsd_run check predicate --predicate '<predicate JSON>' --phase-number "${PHASE_NUMBER}" --raw:
GATE_RESULT=$(gsd_run check ${hook.check.query} "${PHASE_NUMBER}" --raw)
CHECK_EXIT=$?
Gate evaluation uses the same two-step contract as execute:wave:post above.
TDD review escalation (overrides the advisory default for the tdd.review-checkpoint gate only). The tdd execute:post gate is declared blocking: false, so by the generic contract above it displays its message/table and continues. There is ONE documented exception (see ~/.claude/gsd-core/references/execute-mvp-tdd.md): when TDD_MODE=true AND GATE_RESULT.block == true (one or more TDD plans miss a RED or GREEN gate commit; #4011 — no MVP condition), the end-of-phase TDD review escalates from advisory to blocking under TDD — refuse to mark the phase complete and present:
Phase blocked: {N} TDD plan(s) violate the RED→GREEN gate sequence under 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 documented, not-yet-implemented escape hatch.) Outside TDD mode, TDD-review violations remain advisory (table shown, execution continues).
Proceed rule: If TDD_MODE && GATE_RESULT.block == true for tdd.review-checkpoint: STOP — do NOT proceed to close_parent_artifacts, regression_gate, verify_phase_goal, or phase.complete. Otherwise proceed normally.
If section_manifest is null or "gap-closure-artifacts" is in its included list: read and execute gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md. Otherwise skip — do not read the file.
If section_manifest is null or "regression-gate" is in its included list: read and execute gsd-core/workflows/execute-phase/steps/regression-gate.md. Otherwise skip — do not read the file.
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.
<required_reading>
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)
- {requirements_path} (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)
` : ''}
</required_reading>
${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. If the session ends abnormally (
turn_aborted), reconcile via theverification.statusquery below — the session's terminal state is not evidence of failure (#4217).
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: Proceed to gap closure.
If gaps_found: @~/.claude/gsd-core/references/execute-phase-requirement-revert.md
## ⚠ 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.
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
warningsarray)
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
This step runs AFTER phase completion and SUMMARY.md is written. It produces the phase's
learnings artifact (the sole producer is otherwise the user-invoked
/gsd:extract-learnings) and copies it 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:
- Run the
extract-learningsworkflow for the JUST-COMPLETED phase (itswrite_learningsstep writes{phase_dir}/{PADDED_PHASE}-LEARNINGS.md). Extraction failure must NOT block phase completion — report the failure and continue. - Copy the phase artifact to the global store:
gsd_run query learnings.copy 2>/dev/null || echo "⚠ Learnings copy failed — continuing"
Copy failure must NOT block phase completion.
**Auto-close todos whose `resolves_phase` matches this phase (#2433)**, after `update_roadmap`.shopt -s nullglob 2>/dev/null; setopt NULL_GLOB 2>/dev/null
PENDING_DIR=".planning/todos/pending"
COMPLETED_DIR=".planning/todos/completed"
mkdir -p "$COMPLETED_DIR"
PHASE_NUM="${PHASE_NUMBER}"
#2576
normalize_phase_num() {
printf '%s' "${1//\"/}" | sed 's/^0*\([0-9]\)/\1/'
}
PHASE_NUM_NORM=$(normalize_phase_num "$PHASE_NUM")
CLOSED=()
for TODO_FILE in "$PENDING_DIR"/*.md; do
[ -f "$TODO_FILE" ] || continue
RP=$(awk '/^---/{c++;next} c==1 && /^resolves_phase:/{print $2;exit} c==2{exit}' "$TODO_FILE" 2>/dev/null || true)
RP_NORM=$(normalize_phase_num "$RP")
[ -n "$RP_NORM" ] && [ "$RP_NORM" = "$PHASE_NUM_NORM" ] || continue
mv "$TODO_FILE" "$COMPLETED_DIR/"
CLOSED+=("$(basename "$TODO_FILE")")
done
if [ ${#CLOSED[@]} -gt 0 ]; then
ADDED=(); REMOVED=()
for f in "${CLOSED[@]}"; do ADDED+=("$COMPLETED_DIR/$f"); REMOVED+=("$PENDING_DIR/$f"); done
gsd_run query commit "docs(phase-${PHASE_NUMBER}): close ${#CLOSED[@]} resolved todo(s)" --files "${ADDED[@]}" .planning/STATE.md --files-removed "${REMOVED[@]}" || true
echo "◆ Closed ${#CLOSED[@]} todo(s) for Phase ${PHASE_NUMBER}:"; printf ' ✓ %s\n' "${CLOSED[@]}"
fi
No matches: skip silently, never blocks.
**#1526 — Delegate post-completion to the transition workflow** (parity: the auto-chain path must run the SAME post-processing as a normal transition). `phase.complete` (`update_roadmap` above) and verification (`verify_phase_goal`) already ran, so invoke transition in **post-completion mode**: SKIP its `verify_completion` and `update_roadmap_and_state` (re-running `phase.complete` would double-write state) and BEGIN at `evolve_project`, running the full set through `offer_next_phase`.@~/.claude/gsd-core/workflows/transition.md
<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 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 viagsd_run 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>
STATE.md tracks: last completed plan, current wave, pending checkpoints.