gpd-execute-phase

name	gpd-execute-phase
description	Execute all plans in a phase with wave-based parallelization
argument-hint	<phase-number> [--gaps-only]
context_mode	project-required
requires	{"files":[".gpd/ROADMAP.md"],"state":"phase_planned"}
allowed-tools	["read_file","write_file","apply_patch","glob","grep","shell","ask_user"]

<codex_runtime_notes> Codex shell compatibility:

• When shell steps call the GPD CLI, use /Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local instead of the ambient gpd on PATH.
• If you intentionally need the repo environment, keep the runtime pin: GPD_ACTIVE_RUNTIME=codex uv run gpd .... </codex_runtime_notes>

Execute all plans in a phase using wave-based parallel execution.

Orchestrator stays lean: discover plans, analyze dependencies, group into waves, spawn subagents, collect results. Each subagent loads the full execute-plan context and handles its own plan.

Execution scope: Each plan may involve any combination of:

• Derivations -- analytic calculations, symbolic manipulations, proof steps
• Calculations -- numerical computations, parameter sweeps, optimization
• Numerical implementations -- writing simulation code, solvers, integrators
• Data analysis -- processing simulation output, statistical analysis, fitting
• Figure generation -- plots, phase diagrams, schematic illustrations
• LaTeX writing -- manuscript sections, appendices, supplementary material

Context budget: ~15% orchestrator, 100% fresh per subagent.

<execution_context>

Execute all plans in a research phase using wave-based parallel execution. Orchestrator stays lean -- delegates plan execution to subagents. Each plan may involve derivations, calculations, simulations, or analysis with proper checkpointing and validation at each step.

<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 -> validate physics. </core_principle>

<required_reading> Read STATE.md before any operation to load project context. For agent selection strategy and verification failure routing, see @./.codex/get-physics-done/references/orchestration/meta-orchestration.md. </required_reading>

Load all context in one call:

INIT=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local init execute-phase "${PHASE_ARG}")
if [ $? -ne 0 ]; then
  echo "ERROR: gpd initialization failed: $INIT"
  exit 1
fi

Parse JSON for: executor_model, verifier_model, commit_docs, autonomy, review_cadence, research_mode, parallelization, max_unattended_minutes_per_plan, max_unattended_minutes_per_wave, checkpoint_after_n_tasks, checkpoint_after_first_load_bearing_result, checkpoint_before_downstream_dependent_tasks, verifier_enabled, 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, project_contract, contract_intake, effective_reference_intake, active_reference_context, reference_artifacts_content, selected_protocol_bundle_ids, protocol_bundle_context.

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 .gpd/ exists: Offer reconstruct or continue.

Treat project_contract as the authoritative machine-readable execution contract when present. Treat effective_reference_intake as the carry-forward anchor ledger for refs, baselines, prior outputs, and unresolved context gaps. Use active_reference_context and reference_artifacts_content to interpret that ledger, not to replace it with markdown-only guesses.

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

Mode-aware behavior:

• autonomy=supervised: Pause for user confirmation before each wave. Show the plan summary and wait for approval.
• autonomy=balanced (default): Execute waves automatically and pause only if errors, ambiguities, or scope-changing decisions arise at a wave boundary.
• autonomy=yolo: Execute all waves without user prompts on clean passes. Do NOT skip required correctness gates, first-result sanity checks, skeptical review stops, or anchor-gated fanout reviews. A clean pass may auto-continue only after the gate is explicitly cleared.
• research_mode=explore: Favor thoroughness — always run verification, expand context budget.
• research_mode=exploit: Favor speed — skip optional research steps, tighter context budget, but never skip required first-result, skeptical, or pre-fanout review gates.
• research_mode=adaptive: Start with explore-style coverage, then narrow only after prior decisive contract_results, decisive comparison_verdicts, or an explicit approach lock show that the method family is stable. Do NOT narrow just because a wave advanced or one proxy passed.
• Model profile and research mode may change depth, task granularity, or prose volume. They do NOT waive first-result, skeptical, or pre-fanout review gates.
• review_cadence: Controls when bounded review gates appear. autonomy controls who must approve or inspect those gates. These are separate axes.

Check `branching_strategy` from init:

"none": Skip, continue on current branch.

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

git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"

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

Classify the phase type to drive agent selection and context budget decisions. Scan the phase goal and plan objectives for indicator keywords.

PHASE_GOAL=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local roadmap get-phase "${phase_number}" | /Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local json get .goal --default "")
PLAN_OBJECTIVES=""
for plan in "$phase_dir"/*-PLAN.md; do
  OBJ=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local frontmatter get "$plan" --field objective 2>/dev/null)
  PLAN_OBJECTIVES="${PLAN_OBJECTIVES} ${OBJ}"
done
PHASE_TEXT="${PHASE_GOAL} ${PLAN_OBJECTIVES}"

Classify using keyword matching (a phase may have multiple classes):

PHASE_CLASSES=()
echo "$PHASE_TEXT" | grep -qiE "derive|prove|show that|analytical|closed.form|exact result" && PHASE_CLASSES+=("derivation")
echo "$PHASE_TEXT" | grep -qiE "simulat|compute|discretiz|grid|convergence|benchmark|finite.element|Monte Carlo|numerical" && PHASE_CLASSES+=("numerical")
echo "$PHASE_TEXT" | grep -qiE "survey|review|compare approaches|what is known|prior work|literature" && PHASE_CLASSES+=("literature")
echo "$PHASE_TEXT" | grep -qiE "write paper|draft|manuscript|submit|LaTeX" && PHASE_CLASSES+=("paper-writing")
echo "$PHASE_TEXT" | grep -qiE "define|set up framework|establish conventions|Lagrangian|Hamiltonian|action" && PHASE_CLASSES+=("formalism")
echo "$PHASE_TEXT" | grep -qiE "analyz|compare|interpret|extract|fit|scaling" && PHASE_CLASSES+=("analysis")
echo "$PHASE_TEXT" | grep -qiE "verify|cross.check|reproduce|validate|test against" && PHASE_CLASSES+=("validation")
[ ${#PHASE_CLASSES[@]} -eq 0 ] && PHASE_CLASSES+=("mixed")

Log the classification: "Phase ${phase_number} classified as: ${PHASE_CLASSES[*]}"

Use classification for:

• Agent selection (see agent-infrastructure.md Meta-Orchestration Intelligence > Agent Selection by Phase Type)
• Context budget targets (see agent-infrastructure.md Meta-Orchestration Intelligence > Context Budget Allocation)
• Verifier check prioritization (derivation phases promote dimensional / limit / identity-critical checks; numerical phases promote 5.5 convergence and 5.14 statistics; validation phases run the full relevant registry)
• Computation-type-aware execution adaptation (see adapt_to_computation_type below)

Translate the phase classification into concrete execution parameters that drive wave-loop behavior. Set these variables before entering `execute_waves`:

# Defaults
CONVENTION_LOCK_REQUIRED=false
PRE_EXECUTION_AGENTS=()
INTER_WAVE_CHECKS=("convention" "dimensional")
EXECUTOR_CONTEXT_HINT="standard"
WAVE_TIMEOUT_FACTOR=1.0
FORCE_SEQUENTIAL=false
YOLO_RESTRICTIONS=()

Per-class overrides (applied cumulatively for multi-class phases):

Class	Parameter Overrides
derivation	CONVENTION_LOCK_REQUIRED=true — refuse to start if conventions unlocked. INTER_WAVE_CHECKS+=("identity_scan") — check for unverified identities between waves. EXECUTOR_CONTEXT_HINT="derivation-heavy" — hint executors to allocate 70% of context to step-by-step work. WAVE_TIMEOUT_FACTOR=1.5 — derivations run longer. YOLO_RESTRICTIONS+=("no_skip_verification") — even in yolo mode, do NOT skip verification for derivation phases (sign errors cost more than the verification).
numerical	INTER_WAVE_CHECKS+=("convergence_spot_check") — between waves, scan SUMMARY for convergence metrics and flag regressions. EXECUTOR_CONTEXT_HINT="code-heavy" — hint executors to reserve context for code output and numerical tables. PRE_EXECUTION_AGENTS+=("experiment-designer") — if experiment-designer is enabled, spawn before wave 1 to validate parameter ranges.
literature	FORCE_SEQUENTIAL=true — literature plans build on each other's findings; parallel risks redundant searches. EXECUTOR_CONTEXT_HINT="reading-heavy" — hint executors to budget for large literature ingestion. INTER_WAVE_CHECKS=("convention") — skip dimensional checks (no equations).
paper-writing	PRE_EXECUTION_AGENTS+=("notation-coordinator") — ensure notation glossary is current before any section drafting. INTER_WAVE_CHECKS+=("latex_compile") — compile after each wave to catch LaTeX errors early. EXECUTOR_CONTEXT_HINT="prose-heavy" — hint executors to balance equation density with exposition.
formalism	CONVENTION_LOCK_REQUIRED=true. PRE_EXECUTION_AGENTS+=("notation-coordinator") — conventions must be established before framework setup. INTER_WAVE_CHECKS+=("identity_scan").
analysis	INTER_WAVE_CHECKS+=("plausibility_scan") — between waves, scan results for physically implausible values (NaN, sign changes, order-of-magnitude jumps).
validation	YOLO_RESTRICTIONS+=("no_skip_verification" "no_skip_inter_wave") — validation phases must run all checks regardless of autonomy mode. INTER_WAVE_CHECKS+=("identity_scan" "convergence_spot_check" "plausibility_scan") — run all inter-wave checks.

Apply overrides:

for CLASS in "${PHASE_CLASSES[@]}"; do
  case "$CLASS" in
    derivation)
      CONVENTION_LOCK_REQUIRED=true
      INTER_WAVE_CHECKS+=("identity_scan")
      EXECUTOR_CONTEXT_HINT="derivation-heavy"
      WAVE_TIMEOUT_FACTOR=1.5
      YOLO_RESTRICTIONS+=("no_skip_verification")
      ;;
    numerical)
      INTER_WAVE_CHECKS+=("convergence_spot_check")
      EXECUTOR_CONTEXT_HINT="code-heavy"
      PRE_EXECUTION_AGENTS+=("experiment-designer")
      ;;
    literature)
      FORCE_SEQUENTIAL=true
      EXECUTOR_CONTEXT_HINT="reading-heavy"
      INTER_WAVE_CHECKS=("convention")
      ;;
    paper-writing)
      PRE_EXECUTION_AGENTS+=("notation-coordinator")
      INTER_WAVE_CHECKS+=("latex_compile")
      EXECUTOR_CONTEXT_HINT="prose-heavy"
      ;;
    formalism)
      CONVENTION_LOCK_REQUIRED=true
      PRE_EXECUTION_AGENTS+=("notation-coordinator")
      INTER_WAVE_CHECKS+=("identity_scan")
      ;;
    analysis)
      INTER_WAVE_CHECKS+=("plausibility_scan")
      ;;
    validation)
      YOLO_RESTRICTIONS+=("no_skip_verification" "no_skip_inter_wave")
      INTER_WAVE_CHECKS+=("identity_scan" "convergence_spot_check" "plausibility_scan")
      ;;
  esac
done

echo "Execution adaptation: convention_lock=${CONVENTION_LOCK_REQUIRED}, pre_agents=[${PRE_EXECUTION_AGENTS[*]}], inter_wave=[${INTER_WAVE_CHECKS[*]}], context_hint=${EXECUTOR_CONTEXT_HINT}, timeout_factor=${WAVE_TIMEOUT_FACTOR}"

Convention lock enforcement:

If CONVENTION_LOCK_REQUIRED=true:

CONV_STATUS=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local --raw convention check)
if [ "$CONV_STATUS" != "locked" ] && [ "$CONV_STATUS" != "complete" ]; then
  echo "ERROR: Phase class (${PHASE_CLASSES[*]}) requires locked conventions before execution."
  echo "Convention status: ${CONV_STATUS}"
  echo ""
  echo "Fix with one of:"
  echo "  gpd convention set"
  echo "  $gpd-validate-conventions"
  echo ""
  echo "HALTING — convention errors in derivation/formalism phases compound across every step."
  exit 1
fi

This is a hard gate. When CONVENTION_LOCK_REQUIRED=true and conventions are not locked, execution MUST NOT proceed. Do not skip this gate in any autonomy mode (including yolo). Convention errors are irreversible — they invalidate all downstream results.

Pre-execution agent spawning:

If PRE_EXECUTION_AGENTS is non-empty, spawn them sequentially before wave 1:

for AGENT_TYPE in "${PRE_EXECUTION_AGENTS[@]}"; do
  case "$AGENT_TYPE" in
    notation-coordinator)
      AGENT_MODEL=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local resolve-model gpd-notation-coordinator)
      # Spawn notation-coordinator to verify/establish conventions
      # task(subagent_type="gpd-notation-coordinator", model="{AGENT_MODEL}", readonly=false, ...)
      ;;
    experiment-designer)
      AGENT_MODEL=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local resolve-model gpd-experiment-designer)
      # Spawn experiment-designer to validate parameter ranges
      # task(subagent_type="gpd-experiment-designer", model="{AGENT_MODEL}", readonly=false, ...)
      ;;
  esac
done

Force-sequential override:

If FORCE_SEQUENTIAL=true, override PARALLELIZATION to false for this phase regardless of config setting. Log: "Phase class (${PHASE_CLASSES[*]}) forces sequential execution within waves."

YOLO mode restrictions:

If autonomy=yolo and YOLO_RESTRICTIONS is non-empty, restrict yolo behavior:

• no_skip_verification: Do not skip the verification step even in yolo mode. Derivation and validation phases produce irreversible errors that cost more to debug than to verify.
• no_skip_inter_wave: Do not skip inter-wave gates even in yolo mode. Convention drift between waves in these phase types creates compound errors.

Log any restrictions: "YOLO mode restricted for phase class (${PHASE_CLASSES[*]}): ${YOLO_RESTRICTIONS[*]}"

Context hint propagation:

Include EXECUTOR_CONTEXT_HINT in the executor spawn prompt so subagents can self-regulate:

<context_hint>{EXECUTOR_CONTEXT_HINT}</context_hint>

Hint meanings:

• standard: Default allocation — balanced between derivation, code, and prose.
• derivation-heavy: Reserve 70% of context for step-by-step mathematical work. Minimize prose. Use \therefore not paragraphs.
• code-heavy: Reserve space for code blocks, numerical output tables, and convergence plots. Summarize analytical steps briefly.
• reading-heavy: Reserve space for literature citations and comparisons. Budget for reading 5-10 paper summaries.
• prose-heavy: Balance equations with exposition. Every equation needs 2-3 sentences of context.

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

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

Run structural validation on all plans before execution begins:

VALIDATION_FAILED=false

# Validate each plan's frontmatter and structure
for plan in "$phase_dir"/*-PLAN.md; do
  if ! gpd verify plan "$plan"; then
    echo "ERROR: plan-structure validation failed for $(basename "$plan")"
    VALIDATION_FAILED=true
  fi
done

# Validate wave dependencies
if ! gpd phase validate-waves "$phase_number"; then
  echo "ERROR: wave dependency validation failed"
  VALIDATION_FAILED=true
fi

# Check cross-references in plans
for plan in "$phase_dir"/*-PLAN.md; do
  if ! gpd verify references "$plan"; then
    echo "ERROR: reference validation failed for $(basename "$plan")"
    VALIDATION_FAILED=true
  fi
done

if [ "$VALIDATION_FAILED" = true ]; then
  echo "Structural validation failed. Fix the issues above before proceeding."
fi

If VALIDATION_FAILED is true: Present all collected errors to the user. Do not proceed with execution until structural issues are resolved.

Load plan inventory with wave grouping in one call:

PLAN_INDEX=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local phase index "${phase_number}")

Parse JSON for: phase, plans[] (each with id, wave, interactive, 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 all filtered: "No matching incomplete plans" -> exit.

Intra-wave dependency validation: Verify that no plan's depends_on references another plan in the SAME wave (which would be a circular dependency within a wave):

INTRA_WAVE_CONFLICT=false
# For each wave, check that no plan depends on another plan in the same wave
for WAVE_NUM in $(echo "$PLAN_INDEX" | /Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local json keys .waves); do
  WAVE_PLANS=$(echo "$PLAN_INDEX" | /Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local json list ".waves[\"$WAVE_NUM\"]")
  for PLAN_ID in $WAVE_PLANS; do
    DEPS=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local frontmatter get \
      "${phase_dir}/${PLAN_ID}-PLAN.md" --field depends_on 2>/dev/null)
    for DEP in $(echo "$DEPS" | tr ',' ' '); do
      if echo "$WAVE_PLANS" | grep -q "^${DEP}$"; then
        echo "ERROR: Plan ${PLAN_ID} depends on ${DEP}, but both are in wave ${WAVE_NUM}"
        INTRA_WAVE_CONFLICT=true
      fi
    done
  done
done

Parallel file conflict detection: For waves with 2+ plans, check files_modified frontmatter for overlaps:

FILE_CONFLICT=false
# For each wave with 2+ plans, check for file modification overlaps
for WAVE_NUM in $(echo "$PLAN_INDEX" | /Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local json keys .waves); do
  WAVE_PLANS=($(echo "$PLAN_INDEX" | /Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local json list ".waves[\"$WAVE_NUM\"]"))
  if [ ${#WAVE_PLANS[@]} -gt 1 ]; then
    ALL_FILES=()
    for PLAN_ID in "${WAVE_PLANS[@]}"; do
      FILES=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local frontmatter get \
        "${phase_dir}/${PLAN_ID}-PLAN.md" --field files_modified 2>/dev/null)
      for F in $(echo "$FILES" | tr ',' ' '); do
        if [[ " ${ALL_FILES[*]} " =~ " ${F} " ]]; then
          echo "WARNING: File '${F}' modified by multiple plans in wave ${WAVE_NUM}"
          FILE_CONFLICT=true
        fi
        ALL_FILES+=("${F}")
      done
    done
  fi
done

If INTRA_WAVE_CONFLICT is true: STOP — present the dependency issue and do not proceed. If FILE_CONFLICT is true: WARN — present the overlap and offer to serialize the conflicting plans within the wave.

Report:

## Execution Plan

**Phase {X}: {Name}** -- {total_plans} plans across {wave_count} waves

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

Translate cadence config plus wave risk into concrete execution boundaries before any executor is spawned.

REVIEW_CADENCE=$(echo "$INIT" | /Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local json get .review_cadence --default adaptive)
MAX_UNATTENDED_MINUTES_PER_PLAN=$(echo "$INIT" | /Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local json get .max_unattended_minutes_per_plan --default 45)
MAX_UNATTENDED_MINUTES_PER_WAVE=$(echo "$INIT" | /Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local json get .max_unattended_minutes_per_wave --default 90)
CHECKPOINT_AFTER_N_TASKS=$(echo "$INIT" | /Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local json get .checkpoint_after_n_tasks --default 3)
CHECKPOINT_AFTER_FIRST_RESULT=$(echo "$INIT" | /Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local json get .checkpoint_after_first_load_bearing_result --default true)
CHECKPOINT_BEFORE_DOWNSTREAM=$(echo "$INIT" | /Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local json get .checkpoint_before_downstream_dependent_tasks --default true)

Core invariant: autonomy decides who gets interrupted. review_cadence decides when the system must stop, inspect, or re-question. Even in yolo, required first-result and pre-fanout gates still run; the difference is that a clean pass can auto-continue.

These gates are task-level safety rails, not line-by-line interruptions. Even in supervised, checkpoint after each plan task or required gate, not after every algebraic micro-step.

For each wave, classify whether downstream fanout is risky:

• risky when a wave has multiple plans and any later wave depends on it
• risky when any plan has task_count >= CHECKPOINT_AFTER_N_TASKS, no authored checkpoints, or is likely to exceed MAX_UNATTENDED_MINUTES_PER_PLAN
• risky for derivation, formalism, numerical, or validation phase classes
• risky when file conflicts, convention-lock requirements, or benchmark-critical anchors are present
• risky when the wave creates a new estimator, baseline, or branch point whose downstream usefulness depends on a decisive comparison still to be earned
• never mark a wave "safe" merely because it happens later in the phase or follows an earlier partial pass

When a wave is risky:

• set FIRST_RESULT_GATE_REQUIRED=true
• set PRE_FANOUT_REVIEW_REQUIRED=true
• set SEGMENT_TASK_CAP=${CHECKPOINT_AFTER_N_TASKS}
• force bounded continuation segments even when the authored plan has no checkpoints

When a wave is not risky:

• keep bounded execution available for long plans, wall-clock budgets, and context pressure
• allow checkpoint-free plans to run normally when task count is small and fanout is low

Skeptical re-questioning rule: if the first material result only validates a proxy, internal consistency story, or supporting artifact while decisive anchors, benchmark references, or contract-backed acceptance tests remain unresolved, stop and explicitly re-question the framing before allowing downstream fanout. Record:

• weakest unchecked anchor
• what still looks assumed rather than verified
• the disconfirming observation that would most quickly break the current path
• which downstream plans would become wasted work if that decisive evidence failed

Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true` AND `FORCE_SEQUENTIAL=false`, sequential otherwise. (Literature phases force sequential execution — see `adapt_to_computation_type`.)

For each wave:

1. Convention lock check (before parallel execution):

   Before launching parallel plans, verify convention consistency:

   /Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local convention check
   

   • If conventions are unlocked for any field that parallel plans will use, LOCK them first via gpd convention set
   • Do NOT proceed with parallel execution if convention conflicts exist

   Pre-flight convention check for parallel waves: Before spawning wave executors in parallel, verify all plans in the wave reference the same convention_lock values. For each plan in the wave, extract any convention references (metric signature, Fourier convention, unit system) and cross-compare. If any plan's conventions differ from the locked values, resolve the discrepancy before spawning. This prevents the most insidious class of parallel execution bugs: two agents computing with different sign conventions whose results are later combined.

2. Create wave-level checkpoint before any plan in the wave starts:

   WAVE_CHECKPOINT="gpd-checkpoint/phase-${phase_number}-wave-${WAVE_NUM}-$(date +%s)-$$"
   git tag "${WAVE_CHECKPOINT}"
   

   Store the tag for wave-level recovery.

3. Describe what's being done (BEFORE spawning):

   Read each plan's <objective>. Extract what's being computed/derived and why.

   ---
   ## Wave {N}
   
   **{Plan ID}: {Plan Name}**
   {2-3 sentences: what this derives/computes/simulates, mathematical approach, why it matters for the overall research}
   
   Spawning {count} agent(s)...
   ---
   

   • Bad: "Executing Hamiltonian diagonalization plan"
   • Good: "Diagonalizing the spin-chain Hamiltonian using Bethe ansatz -- extracts exact energy spectrum and correlation functions in the thermodynamic limit. Required before computing transport coefficients in Wave 3."

   If this wave is marked risky fanout: run probe_then_fanout instead of blind full-wave scaleout.

   • First launch each risky plan only to its first-result gate or bounded segment boundary
   • Collect first-result sanity outcomes, decisive-evidence status, and anchor status
   • Only unlock the remainder of the wave when those gates pass with decisive evidence or the remaining work is explicitly independent of the unresolved comparison
   • If any plan fails the gate or requires re-questioning, STOP the wave before spawning more downstream work

4. Spawn executor agents:

   Pass paths only -- executors read files themselves with their fresh 200k context. This keeps orchestrator context lean (~10-15%).

   Runtime delegation: Spawn a subagent for the task below. Adapt the task() call to your runtime's agent spawning mechanism. If model resolves to null or an empty string, omit it so the runtime uses its default model. Always pass readonly=false for file-producing agents. If subagent spawning is unavailable, execute these steps sequentially in the main context.

   task(
     subagent_type="gpd-executor",
     model="{executor_model}",
     readonly=false,
     prompt="First, read ./.codex/agents/gpd-executor.md for your role and instructions.
   
       <objective>
       Execute plan {plan_number} of phase {phase_number}-{phase_name}.
       Commit each task atomically. Create SUMMARY.md.
       Return state updates (position, decisions, metrics) in your response -- do NOT write STATE.md directly.
       </objective>
   
       <context_hint>{EXECUTOR_CONTEXT_HINT}</context_hint>
       <phase_class>{PHASE_CLASSES}</phase_class>
       <protocol_bundles>{selected_protocol_bundle_ids}</protocol_bundles>
       <protocol_bundle_context>{protocol_bundle_context}</protocol_bundle_context>
       <review_cadence>{REVIEW_CADENCE}</review_cadence>
       <max_unattended_minutes_per_plan>{MAX_UNATTENDED_MINUTES_PER_PLAN}</max_unattended_minutes_per_plan>
       <max_unattended_minutes_per_wave>{MAX_UNATTENDED_MINUTES_PER_WAVE}</max_unattended_minutes_per_wave>
       <segment_task_cap>{SEGMENT_TASK_CAP}</segment_task_cap>
       <first_result_gate>{FIRST_RESULT_GATE_REQUIRED}</first_result_gate>
       <checkpoint_before_downstream>{CHECKPOINT_BEFORE_DOWNSTREAM}</checkpoint_before_downstream>
       <bounded_execution>{true}</bounded_execution>
   
       <files_to_read>
       Read these files at execution start using the read_file tool:
       - Workflow: ./.codex/get-physics-done/workflows/execute-plan.md
       - Summary template: ./.codex/get-physics-done/templates/summary.md
       - Checkpoints ref: ./.codex/get-physics-done/references/orchestration/checkpoints.md
       - Validation ref: ./.codex/get-physics-done/references/verification/core/verification-core.md (+ domain-specific verification file)
       - Plan: {phase_dir}/{plan_file}
       - State: .gpd/STATE.md
       - Config: .gpd/config.json (if exists)
       </files_to_read>
   
       <success_criteria>
       - [ ] All tasks executed with mathematical rigor
       - [ ] Each task committed individually
       - [ ] Dimensional consistency verified at each step
       - [ ] Limiting cases checked where specified in plan
       - [ ] SUMMARY.md created in plan directory
       - [ ] State updates returned (NOT written to STATE.md directly)
       </success_criteria>
     "
   )
   

5. Wait for all agents in wave to complete.

   Progress feedback during wave execution: As each plan completes (or fails), immediately report to the user:

   [Phase {N}, Wave {W}] Plan {plan_id} complete ({completed}/{total} in wave)
     Result: {one-line summary from SUMMARY.md or failure reason}
   

   This ensures the user sees progress even when waves have multiple parallel plans. Do not wait for the entire wave to finish before showing any output.

   If any executor agent fails to spawn or returns an error: Check if the agent committed any work (git log --oneline -3). If commits exist, the agent may have completed but failed to report — spot-check output files and proceed. If no work was done, record the plan as failed for this wave. After all other agents complete, report failed plans and offer: 1) Retry failed plans in a new wave, 2) Execute failed plans in the main context, 3) Skip failed plans and continue. Do not abort the entire phase for individual plan failures.

6. Report completion -- spot-check claims first:

   For each SUMMARY.md:

   • Verify first 2 files from key-files.created exist on disk

   • Check git log --oneline --grep="{phase}-{plan}" returns >=1 commit

   • Check for ## Self-Check: FAILED marker

   • Check for ## Validation: FAILED marker (physics-specific)

   • Validate the gpd_return envelope:

     RETURN_CHECK=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local --raw validate-return "${SUMMARY_FILE}")
     if [ "$RETURN_CHECK" != "passed" ]; then
       echo "WARNING: validate-return failed for $(basename "$SUMMARY_FILE")"
       # Mark plan as NEEDS_REVIEW but continue — missing envelope is not fatal
     fi
     

   If ANY spot-check fails: report which plan failed, route to wave_failure_handling -- do NOT silently continue.

   IMPORTANT: Executor subagents MUST NOT write STATE.md directly. Return state updates (position, decisions, metrics) in the structured return envelope. The orchestrator applies them sequentially after each agent completes. This prevents parallel write conflicts where multiple agents overwrite each other's STATE.md changes.

   After each plan completes successfully (not just after each wave), the orchestrator runs:

   1. gpd state advance immediately
   2. gpd state record-metric for the completed plan
   3. This ensures crash recovery loses at most ONE plan's state, not an entire wave

   If pass:

   ---
   ## Wave {N} Complete
   
   **{Plan ID}: {Plan Name}**
   {What was derived/computed -- from SUMMARY.md}
   {Notable deviations or unexpected results, if any}
   {Limiting cases verified: list}
   
   {If more waves: what this enables for next wave}
   ---
   

   • Bad: "Wave 2 complete. Proceeding to Wave 3."
   • Good: "Spin-chain spectrum computed -- Bethe ansatz solution yields N-magnon energies with correct Heisenberg limit. Finite-size scaling exponents match CFT prediction (nu = 1.00 +/- 0.02). Transport coefficient calculation (Wave 3) can now use these eigenstates."

7. Handle failures -- see wave_failure_handling below.

8. Execute checkpoint plans between waves -- see <checkpoint_handling>.

   Before unlocking downstream dependent waves, confirm that risky-wave plans passed the first meaningful review point:

   • the first load-bearing result exists
   • the result is tied to a contract-relevant output, not only a proxy
   • one quick sanity/benchmark/convention check passed
   • decisive anchors still missing were explicitly named and re-questioned if necessary
   • if the contract owed a decisive comparison, either that comparison now has a pass verdict or the downstream work was explicitly scoped so it does not rely on that unresolved claim

   If this gate fails: STOP — do not let wrong early assumptions scale out.

   Machine-state requirement for risky fanout gates: when this review point pauses execution, record it as live execution state, not only prose. Emit an execution gate event with:

   • checkpoint_reason: pre_fanout
   • pre_fanout_review_pending: true
   • downstream_locked: true
   • last_result_label or last_artifact_path for the first load-bearing output being reviewed
   • skeptical_requestioning_required: true when the first result still looks proxy-only, anchor-thin, or otherwise short of the decisive evidence the contract still owes
   • skeptical_requestioning_summary, weakest_unchecked_anchor, and disconfirming_observation whenever skeptical re-questioning is required

   If the runtime or agent only emits a fanout-lock event, normalize it into the same live review stop: treat the lock as checkpoint_reason=pre_fanout, mark waiting_for_review=true, and keep downstream locked until the review is explicitly cleared.

   Gate clears are reason-scoped: clearing first_result must not erase pre_fanout or skeptical review flags, and skeptical re-questioning should be cleared explicitly when it is resolved.

   For pre_fanout, the matching gate-clear and fanout unlock are separate transitions: the clear records the review outcome, the unlock releases downstream work. Keep the segment live on status, notify, and resume surfaces until both have been observed. Do not silently continue on "looks fine" prose alone.

9. Inter-wave verification gate (if more waves remain):

   Before spawning the next wave, run lightweight verification on the just-completed wave's outputs. This catches errors cheaply before they propagate to downstream waves.

   Determine if gate is enabled from init/context fields only:

   • if review_cadence == dense: enable inter-wave verification
   • if review_cadence == adaptive: enable it when the completed wave established or challenged a decisive evidence path, introduced a new baseline/estimator that later waves depend on, or left any skeptical or pre-fanout state unresolved
   • if review_cadence == sparse: skip the routine gate unless the just-completed wave triggered a failed sanity check, anchor gap, or pre-fanout dependency warning

   If enabled:

   First, collect the SUMMARY.md files produced by the just-completed wave:

   # Collect SUMMARY files from the plans that executed in the current wave
   wave_summaries=()
   for PLAN_ID in $(echo "$PLAN_INDEX" | /Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local json list ".waves[\"$WAVE_NUM\"]"); do
     SUMMARY_PATH="${phase_dir}/${PLAN_ID}-SUMMARY.md"
     [ -f "$SUMMARY_PATH" ] && wave_summaries+=("$SUMMARY_PATH")
   done
   

   Run lightweight checks on the wave's SUMMARY.md outputs:

   a. Convention consistency — verify convention lock hasn't drifted:

   CONV_CHECK=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local --raw convention check)
   if [ "$CONV_CHECK" = "incomplete" ]; then
     echo "WARNING: Convention lock has unlocked fields"
   fi
   

   b. Dimensional spot-check — scan the wave's SUMMARY.md files for key results and verify dimensional consistency:

   For each SUMMARY.md produced in the just-completed wave, extract key equations (from key_results or equations frontmatter fields) and verify that:

   • Both sides of each equation have the same dimensions
   • Function arguments are dimensionless
   • No bare dimensionful quantities appear where dimensionless ones are expected

   This is a lightweight scan (~2-5k tokens), not a full dimensional analysis. It checks the SUMMARY outputs, not the derivation internals.

   c. Unverified identity scan — check for IDENTITY_CLAIM tags without verification:

   # Scan wave artifacts for unverified identity claims
   PHASE_ARTIFACT_DIR="artifacts/phases/${phase_number}-${phase_slug}"
   for summary in ${wave_summaries[@]}; do
     grep -rl "IDENTITY_SOURCE: training_data" \
       "$summary" "${PHASE_ARTIFACT_DIR}" figures/ data/ simulations/ paper/figures/ \
       2>/dev/null | while read f; do
       if ! grep -q "IDENTITY_VERIFIED:" "$f" 2>/dev/null; then
         echo "WARNING: Unverified training_data identity in $f"
       fi
     done
   done
   

   Prefer paths surfaced through SUMMARY key-files or contract deliverables. Do not assume durable artifacts live beside the SUMMARY in .gpd/phases/**.

   If unverified identities are found: flag as WARNING. These identities may be correct but have not been numerically tested — downstream waves building on them carry unquantified risk.

   d. Computation-type-specific checks (driven by INTER_WAVE_CHECKS from adapt_to_computation_type):

   If convergence_spot_check in INTER_WAVE_CHECKS (numerical phases):

   Scan the wave's SUMMARY.md files for convergence-related metrics. Look for keywords: convergence, error, residual, tolerance, iterations, grid_size. Flag if:

   • A convergence metric worsened compared to the previous wave's output
   • A residual exceeds 1e-3 without explicit justification
   • An iteration count hit a hard limit (suggests non-convergence)

   for summary in ${wave_summaries[@]}; do
     # Extract numerical metrics from SUMMARY frontmatter or key_results
     grep -iE "converge|residual|error.*=.*[0-9]|tolerance" "$summary" 2>/dev/null | while read line; do
       echo "CONVERGENCE: $line"
     done
   done
   

   If plausibility_scan in INTER_WAVE_CHECKS (analysis/validation phases):

   Scan the wave's SUMMARY.md outputs for physically implausible values:

   • NaN or Inf in results
   • Negative values where positivity is expected (energies of bound states, probabilities, cross-sections)
   • Order-of-magnitude jumps (>10x) between related quantities in successive waves

   for summary in ${wave_summaries[@]}; do
     grep -iE "NaN|Inf|= -[0-9]|diverge" "$summary" 2>/dev/null | while read line; do
       echo "PLAUSIBILITY WARNING: $line"
     done
   done
   

   If latex_compile in INTER_WAVE_CHECKS (paper-writing phases):

   If pdflatex is available, compile the paper after each wave to catch LaTeX errors early:

   if command -v pdflatex &>/dev/null && [ -f paper/main.tex ]; then
     cd paper && pdflatex -interaction=nonstopmode main.tex 2>&1 | grep -E "^!" | head -5
     cd ..
   fi
   

   Flag any LaTeX errors as WARNING — they should be fixed before the next wave adds more content.

   If any check fails:

   ---
   ## Inter-wave verification gate
   
   **Convention check:** {PASS | WARNING: {details}}
   **Dimensional check:** {PASS | WARNING: {details}}
   **Identity check:** {PASS | WARNING: {N} unverified training_data identities}
   **Convergence check:** {PASS | WARNING: {details} | SKIPPED (not numerical phase)}
   **Plausibility check:** {PASS | WARNING: {details} | SKIPPED (not analysis/validation phase)}
   **LaTeX compile:** {PASS | WARNING: {N} errors | SKIPPED (not paper-writing phase)}
   
   Options:
   1. Continue to next wave (accept warnings)
   2. Fix issues before continuing
   3. Stop execution and investigate
   ---
   

   Present options and wait for user response (or auto-continue in YOLO mode if both are warnings, not errors — unless YOLO_RESTRICTIONS includes no_skip_inter_wave, in which case always present).

   If disabled: Skip verification gate, proceed directly to step 10. Exception: if YOLO_RESTRICTIONS includes no_skip_inter_wave, the gate runs even when disabled by config.

   Cost: ~2-5k tokens per inter-wave gate. For a 4-wave phase with deep-theory profile, this is ~10-15k tokens overhead — negligible compared to the cost of a sign error propagating through 3 subsequent waves.

10. Inter-wave transition display:

Before spawning the next wave, display a physics-meaningful progress update that connects what was just computed to what comes next:

---
Wave {N} -> Wave {N+1} transition

Completed: {brief physics summary of wave N results -- e.g., "Exact diagonalization of 2D Hubbard model for N=4,8,12 sites"}
Enables: {what wave N+1 will use from these results -- e.g., "Finite-size scaling analysis using the energy spectra from Wave 1"}
Starting: {brief description of wave N+1 plans -- e.g., "Extracting critical exponents via data collapse (plans 03, 04)"}
---

Extract the "Completed" summary from the wave N completion report (step 6 above). Extract "Enables" and "Starting" from the wave N+1 plan objectives. Keep each line to one sentence.

11. Proceed to next wave.

When a plan within a wave fails (spot-check failure, agent crash, or plan-level failure reported by execute-plan):

1. Identify the failure and its downstream impact:

# Collect all plans from waves AFTER the current wave
LATER_PLANS=()
for LATER_WAVE in $(echo "$PLAN_INDEX" | /Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local json keys .waves | awk -v w="$WAVE_NUM" '$1 > w'); do
  for P in $(echo "$PLAN_INDEX" | /Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local json list ".waves[\"$LATER_WAVE\"]"); do
    LATER_PLANS+=("$P")
  done
done

# Which of those later plans depend on the failed plan?
DEPENDENT_PLANS=()
for LATER_PLAN in "${LATER_PLANS[@]}"; do
  DEPS=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local frontmatter get \
    "${phase_dir}/${LATER_PLAN}-PLAN.md" --field depends_on 2>/dev/null)
  if echo "$DEPS" | grep -q "${FAILED_PLAN_ID}"; then
    DEPENDENT_PLANS+=("${LATER_PLAN}")
  fi
done

2. Report failure with dependency analysis:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GPD > WAVE {N} FAILURE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**Failed plan:** {PLAN_ID} -- {plan name}
**Reason:** {failure description from spot-check or agent report}

### Wave {N} Status
| Plan | Status |
| ---- | ------ |
| {plan-A} | Passed |
| {plan-B} | FAILED |
| {plan-C} | Passed |

### Downstream Impact
Plans that depend on {FAILED_PLAN_ID} (will be auto-skipped):
{list of dependent plans with their wave numbers, or "None -- no downstream dependencies"}

──────────────────────────────────────────────────────
Options:
  1. "Rollback failed plan only" (preferred) -- revert only the commits from the failed plan
     using the TASK_COMMITS record. Keep all successful plans in this wave.
  2. "Continue" -- skip failed plan + dependents, execute remaining waves
  3. "Rollback wave" -- revert all wave {N} work to wave checkpoint
  4. "Stop" -- halt phase execution, preserve all completed work
──────────────────────────────────────────────────────

3. Handle user choice:

Continue:

• Mark the failed plan as skipped in the wave tracker

• Auto-skip all plans in DEPENDENT_PLANS in subsequent waves with message:

  Skipping {PLAN_ID}: depends on failed plan {FAILED_PLAN_ID}
  

• Track skipped plans in SKIPPED_PLANS array with reasons for the recovery report

• Proceed to next wave, filtering out dependent plans

Rollback wave:

• Revert to the wave checkpoint:

  WAVE_CHECKPOINT_COMMIT=$(git rev-list -n 1 "${WAVE_CHECKPOINT}")
  git revert --no-commit HEAD...${WAVE_CHECKPOINT_COMMIT}
  git commit -m "$(cat <<EOF
  revert: rollback wave ${WAVE_NUM} of phase ${phase_number}
  
  Failed plan: ${FAILED_PLAN_ID}
  Reason: ${FAILURE_REASON}
  Checkpoint: ${WAVE_CHECKPOINT}
  EOF
  )"
  

• Ask: "Retry wave {N}?" or "Stop execution?"

• If retry: re-enter the wave execution loop for wave N

• If stop: proceed to recovery report

Stop:

• Preserve all committed work
• Proceed directly to recovery report

4. Auto-skip dependent plans during subsequent waves:

When processing plans in waves N+1, N+2, etc., check each plan against the SKIPPED_PLANS list:

for DEP in $(echo "$PLAN_DEPS" | tr ',' ' '); do
  if [[ " ${SKIPPED_PLANS[*]} " =~ " ${DEP} " ]]; then
    echo "SKIP: Plan ${PLAN_ID} depends on skipped/failed plan ${DEP}"
    SKIPPED_PLANS+=("${PLAN_ID}:depends_on_${DEP}")
    continue 2
  fi
done

Handoff verification: Do not trust the runtime handoff status by itself. Verify expected output files, the structured return envelope, and git commits before treating a subagent as failed.

Plans with `interactive: true` require user interaction.

Flow:

1. Spawn agent for checkpoint plan

2. Agent runs until checkpoint task or validation gate -> returns structured state

3. Agent return includes: completed tasks table, current task + blocker, checkpoint type/details, what's awaited, and the bounded execution segment envelope

   • For first-result or pre-fanout pauses, the bounded segment envelope must also carry:
     • checkpoint_reason
     • first_result_gate_pending or pre_fanout_review_pending
     • pre_fanout_review_cleared when review was accepted but downstream unlock is still outstanding
     • skeptical_requestioning_required
     • skeptical_requestioning_summary
     • weakest_unchecked_anchor
     • disconfirming_observation
     • downstream_locked

4. Present to user:

   ## Checkpoint: [Type]
   
   **Plan:** 03-03 Perturbation Expansion
   **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 ./.codex/get-physics-done/templates/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 (see template for type-specific instructions)
   • {execution_segment}: The returned bounded-segment state, including checkpoint cause, current cursor, resume preconditions, downstream-lock status, and any skeptical re-questioning fields that must survive into the continuation

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.

**Before aggregating results, estimate context consumption:**

Count the SUMMARY files that will be read and estimate their impact on orchestrator context:

SUMMARY_COUNT=$(ls "${phase_dir}"/*-SUMMARY.md 2>/dev/null | wc -l)
ESTIMATED_TOKENS=$(( SUMMARY_COUNT * 3000 ))
CONTEXT_BUDGET=${CONTEXT_BUDGET:-200000}  # Model-dependent; 200k for most current models
BUDGET_PERCENT=$(( ESTIMATED_TOKENS * 100 / CONTEXT_BUDGET ))

If BUDGET_PERCENT exceeds 15%: warn before proceeding:

WARNING: Reading ${SUMMARY_COUNT} SUMMARY files will consume ~${BUDGET_PERCENT}% of orchestrator context.
Consider using summary-extract for one-liners only instead of full SUMMARY reads.

If >15%, use summary-extract for one-liners instead of reading full SUMMARY files:

for summary in "${phase_dir}"/*-SUMMARY.md; do
  /Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local summary-extract "$summary" --field one_liner
done

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]

### Validation Summary

[Aggregate limiting case checks, dimensional consistency results, cross-checks]

### Issues Encountered

[Aggregate from SUMMARYs, or "None"]

**After all waves complete successfully, inventory generated figures/plots into FIGURE_TRACKER.md:**

Scan all SUMMARY.md files from this phase for figure-related artifacts:

# Find figures referenced in SUMMARY files
for SUMMARY in "${phase_dir}"/*-SUMMARY.md; do
  # Extract key-files.created entries that look like figures
  grep -E '\.(pdf|png|eps|svg|jpg|jpeg|tiff)' "$SUMMARY" 2>/dev/null
done

# Also scan durable figure roots for generated plot files
PHASE_ARTIFACT_DIR="artifacts/phases/${phase_number}-${phase_slug}"
find "${PHASE_ARTIFACT_DIR}" figures/ paper/figures/ -maxdepth 3 \
  \( -name "*.pdf" -o -name "*.png" -o -name "*.eps" \) 2>/dev/null | \
  grep -iE "fig|plot|phase_diag|spectrum|convergence|diagram" 2>/dev/null

Generated figures and plots should live in stable workspace roots such as artifacts/phases/${phase_number}-${phase_slug}/, figures/, or paper/figures/, not under .gpd/phases/**.

If any figures found:

Read the figure tracker template:

cat ./.codex/get-physics-done/templates/paper/figure-tracker.md

If .gpd/paper/FIGURE_TRACKER.md already exists: Append new figures to the existing registry. Do not overwrite existing entries.

If it does not exist: Create it from the template:

mkdir -p .gpd/paper

Write .gpd/paper/FIGURE_TRACKER.md with:

• One entry per discovered figure/plot
• Source phase set to the current phase number
• Source file set to the script or notebook that generated it (from SUMMARY key-files)
• Data file(s) set to any associated data files (from SUMMARY key-files)
• Status set to "Data ready" or "Draft" based on file inspection
• Last updated set to today's date

Commit:

PRE_CHECK=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local pre-commit-check --files .gpd/paper/FIGURE_TRACKER.md 2>&1) || true
echo "$PRE_CHECK"

/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local commit \
  "docs(phase-${phase_number}): update figure tracker" \
  --files .gpd/paper/FIGURE_TRACKER.md

If no figures found: Skip silently (not all phases produce visual outputs).

Experimental comparison artifact: If any plan in this phase compared theoretical predictions with experimental or observational data (PHENO-type objectives, or plans whose SUMMARY mentions "experimental comparison", "pull", "chi-squared", or "theory vs data"), create .gpd/paper/EXPERIMENTAL_COMPARISON.md using ./.codex/get-physics-done/templates/paper/experimental-comparison.md. Populate with comparison tables, pull values, and discrepancy classifications from the plan SUMMARYs. Skip if no experimental comparison was performed.

**After all waves complete (including any failures, skips, or rollbacks), generate a recovery report.**

This step runs unconditionally -- for fully successful phases it is a brief confirmation; for phases with failures it is the critical decision point.

1. Collect execution outcomes:

# Collect all plan IDs from the phase plan index
ALL_PLAN_IDS=($(echo "$PLAN_INDEX" | /Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local json pluck .plans id))

# Initialize outcome tracking arrays
# Note: FAILED_IDS, SKIPPED_IDS, and their reason maps should be maintained
# by the orchestrator during execute_waves and wave_failure_handling steps.
# FAILED_IDS+=("plan_id") when a plan fails spot-checks or agent reports failure.
# SKIPPED_IDS+=("plan_id") when a plan is auto-skipped due to dependency on failed plan.
declare -A FAILURE_REASONS  # Map plan_id -> failure description
declare -A SKIP_REASONS     # Map plan_id -> "depends_on_${dep_id}"

PLANS_SUCCEEDED=()    # Plans with SUMMARY.md and passing spot-checks
PLANS_FAILED=()       # Plans that failed during execution
PLANS_SKIPPED=()      # Plans skipped due to dependency on failed plans
PLANS_ROLLED_BACK=()  # Plans whose work was reverted

for PLAN_ID in "${ALL_PLAN_IDS[@]}"; do
  if [ -f "${phase_dir}/${PLAN_ID}-SUMMARY.md" ]; then
    PLANS_SUCCEEDED+=("${PLAN_ID}")
  elif [[ " ${FAILED_IDS[*]} " =~ " ${PLAN_ID} " ]]; then
    PLANS_FAILED+=("${PLAN_ID}:${FAILURE_REASONS[$PLAN_ID]}")
  elif [[ " ${SKIPPED_IDS[*]} " =~ " ${PLAN_ID} " ]]; then
    PLANS_SKIPPED+=("${PLAN_ID}:${SKIP_REASONS[$PLAN_ID]}")
  fi
done

2. Present recovery report:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GPD > PHASE {X} EXECUTION REPORT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

### Results

| Plan | Status | Detail |
| ---- | ------ | ------ |
| {id} | Passed | {one-liner from SUMMARY} |
| {id} | FAILED | {failure reason} |
| {id} | Skipped | Depends on failed {dep_id} |

**Summary:** {succeeded_count} passed, {failed_count} failed, {skipped_count} skipped

3. If ALL plans passed: Proceed to verify_phase_goal as normal. Report is informational only.

4. If ANY failures or skips occurred:

Create a recovery section in the phase directory. For physics-specific root cause analysis, consult ./.codex/get-physics-done/templates/recovery-plan.md:

RECOVERY_FILE="${phase_dir}/PHASE-RECOVERY.md"

Write PHASE-RECOVERY.md:

---
phase: { PHASE_NUMBER }
phase_name: { PHASE_NAME }
created: { ISO timestamp }
plans_succeeded: [{ list }]
plans_failed: [{ list }]
plans_skipped: [{ list }]
checkpoint_tags: [{ list of all remaining gpd-checkpoint tags for this phase }]
---

# Phase {X} Recovery

## Execution Summary

{succeeded_count}/{total_count} plans completed successfully.

## Failed Plans

### {PLAN_ID}: {plan name}

- **Failed at:** Task {N} -- {task name}
- **Reason:** {detailed failure reason}
- **Checkpoint:** {checkpoint tag, if preserved}
- **Recovery:** See RECOVERY-{PLAN}.md (created by execute-plan)

## Skipped Plans

### {PLAN_ID}: {plan name}

- **Skipped because:** Depends on failed plan {dep_id}
- **Would have computed:** {objective from PLAN.md}

## Recovery Options

1. Fix failing plans and re-execute: `$gpd-execute-phase {X}` (auto-detects partial completion)
2. Re-plan failed tasks: `$gpd-plan-phase {X} --gaps` (creates new plans for unfinished work)
3. Revise phase goal: `$gpd-discuss-phase {X}` (rethink approach based on what failed)
4. Continue to next phase: `$gpd-plan-phase {X+1}` (if remaining work is non-critical)

Commit recovery document:

PRE_CHECK=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local pre-commit-check --files "${RECOVERY_FILE}" .gpd/STATE.md 2>&1) || true
echo "$PRE_CHECK"

/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local commit \
  "docs(phase-${phase_number}): phase recovery report" \
  --files "${RECOVERY_FILE}" .gpd/STATE.md

5. Offer actionable next steps based on failure pattern:

──────────────────────────────────────────────────────
## Next Steps

{If single plan failed, rest passed:}
  The failure is isolated. Fix and re-execute:
  `$gpd-execute-phase {X}` -- will resume from the failed plan

{If multiple plans failed in same wave:}
  Multiple failures in Wave {N} suggest a systemic issue.
  Review the phase approach before retrying:
  `$gpd-discuss-phase {X}` -- reassess methodology

{If failures cascaded through dependencies:}
  The root failure in {ROOT_PLAN} cascaded to {N} dependent plans.
  Fix the root cause first:
  Review: ${phase_dir}/RECOVERY-{ROOT_PLAN}.md

{If all plans failed:}
  Complete phase failure. The phase goal or approach may need revision:
  `$gpd-plan-phase {X}` -- re-plan from scratch
──────────────────────────────────────────────────────

**If `verifier_enabled` is false** (from init JSON config / `workflow.verifier` in config.json): Skip phase verification entirely. Log: "Verification skipped (disabled in config)." Proceed directly to phase transition (update_roadmap step).

Verify phase achieved its GOAL, not just completed tasks.

Phase-class-aware verification: Pass the phase classification (from classify_phase step) to the verifier so it can prioritize checks:

• Derivation phases: Promote 5.1 dimensional analysis, 5.2 numerical spot-checks, 5.3 limiting cases, and any domain-specific identity or symmetry checks surfaced by the loaded verifier checklist.
• Numerical phases: Promote 5.5 numerical convergence, 5.14 statistical validation, 5.2 numerical spot-checks, and benchmark reproduction when the contract names a decisive anchor.
• Formalism phases: Promote 5.1 dimensional analysis, 5.3 limiting cases, 5.9 Ward identities / sum rules when applicable, and literature cross-checks for the defining equations.
• Validation phases: Run the full relevant universal registry plus every required contract-aware check. Validation IS the purpose of the phase.
• Analysis phases: Promote 5.7 order-of-magnitude checks, 5.8 physical plausibility, 5.6 literature cross-checks, and any contract-aware fit or estimator checks needed by the claim.

Include in the verifier spawn prompt: <phase_class>{PHASE_CLASSES}</phase_class> so the verifier can adjust its check prioritization.

Follow the verification workflow. Read ./.codex/get-physics-done/workflows/verify-phase.md using the read_file tool.

Read status after verification completes:

grep "^status:" "$phase_dir"/*-VERIFICATION.md | head -1 | cut -d: -f2 | tr -d ' '

Status	Action
passed	-> update_roadmap
completed	-> update_roadmap (interactive verify-work equivalent)
human_needed	Present items for human review, get approval or feedback
expert_needed	Domain expert review required; present items, escalate
gaps_found	Present gap summary, offer $gpd-plan-phase {phase} --gaps
diagnosed	Gaps were debugged; review fixes, then -> update_roadmap
validating	Verification in progress; wait or re-run verify-phase

If human_needed:

## Phase {X}: {Name} -- Human Verification Required

All automated checks passed. {N} items need human review:

{From VERIFICATION.md human_verification section}

"approved" -> continue | Report issues -> gap closure

If gaps_found:

## Phase {X}: {Name} -- Gaps Found

**Score:** {N}/{M} contract targets verified
**Report:** {phase_dir}/{phase}-VERIFICATION.md

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

### Physics Issues
{Any dimensional inconsistencies, failed limiting cases, or conservation law violations}

---
## >> Next Up

`$gpd-plan-phase {X} --gaps`

<sub>`/clear` first -> fresh context window</sub>

Also: `cat {phase_dir}/{phase}-VERIFICATION.md` -- full report
Also: `$gpd-verify-work {X}` -- manual review first

Gap closure cycle: $gpd-plan-phase {X} --gaps reads VERIFICATION.md -> creates gap plans with gap_closure: true -> user runs $gpd-execute-phase {X} --gaps-only -> automatic re-verification (below).

Smart failure recovery (replaces blunt circuit breaker):

Before triggering gap closure, classify the failure to select the minimum-cost recovery strategy. See agent-infrastructure.md Meta-Orchestration Intelligence > Feedback Loop Intelligence for the full classification table.

# Count failed contract targets and classify
FAILED_COUNT=$(grep -c "status: failed" "${phase_dir}"/*-VERIFICATION.md 2>/dev/null || echo 0)
TOTAL_COUNT=$(grep -c "status:" "${phase_dir}"/*-VERIFICATION.md 2>/dev/null || echo 0)

Failure Pattern	Recovery	Cost
1 contract target failed, rest passed	Re-execute the specific failing plan only	1 subagent
Multiple failures, same error type (e.g., all sign errors)	Spawn notation-coordinator to check conventions, then re-execute	2 subagents
Multiple failures, different error types	Escalate to user -- approach may be fundamentally wrong	0 (user decides)
Same gap persists after 1 gap-closure	Spawn debugger to identify root cause before 2nd attempt	1-2 subagents

For localized failures (1 contract target): Skip full gap-closure planning. Instead, directly re-execute the single plan that produced the failed result with explicit error context:

task(
  subagent_type="gpd-executor",
  model="{executor_model}",
  readonly=false,
  prompt="First, read ./.codex/agents/gpd-executor.md for your role and instructions.

  Re-execute plan {FAILED_PLAN} with focus on fixing: {FAILURE_DESCRIPTION}.
  The verifier found: {VERIFICATION_DETAIL}.
  Read the original SUMMARY.md for what was attempted. Fix the specific error.

  <context_hint>{EXECUTOR_CONTEXT_HINT}</context_hint>
  <phase_class>{PHASE_CLASSES}</phase_class>
  <protocol_bundles>{selected_protocol_bundle_ids}</protocol_bundles>
  <protocol_bundle_context>{protocol_bundle_context}</protocol_bundle_context>

  <files_to_read>
  - Workflow: ./.codex/get-physics-done/workflows/execute-plan.md
  - Plan: {phase_dir}/{FAILED_PLAN}-PLAN.md
  - Previous SUMMARY: {phase_dir}/{FAILED_PLAN}-SUMMARY.md
  - State: .gpd/STATE.md
  </files_to_read>",
  description="Targeted re-execution of {FAILED_PLAN}"
)

For systematic failures: Spawn notation-coordinator first to check for convention drift, then re-execute with corrected conventions.

For persistent failures (same gap after 1 cycle): Spawn debugger BEFORE the second gap-closure attempt:

DEBUGGER_MODEL=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local resolve-model gpd-debugger)

task(
  subagent_type="gpd-debugger",
  model="{debugger_model}",
  readonly=false,
  prompt="First, read ./.codex/agents/gpd-debugger.md for your role and instructions.
  Investigate why gap closure did not resolve this verification failure.
  read_file: {VERIFICATION_FILE}, {GAP_CLOSURE_SUMMARY}, {ORIGINAL_SUMMARY}
  Identify the root cause and recommend: fix-and-retry vs re-plan vs escalate.",
  description="Diagnose persistent verification failure"
)

Circuit breaker (hard stop): Maximum 2 verification-gap closure cycles. After 2 failed verification cycles (with debugger diagnosis on the second), STOP the loop. Present a diagnostic summary to the user:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GPD > CIRCUIT BREAKER: VERIFICATION LOOP HALTED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase {X} has failed verification twice after gap closure attempts.

### Attempt 1
- Gaps found: {list from first VERIFICATION.md}
- Gap closure plans: {list of plans created}
- Re-verification result: {what still failed}

### Attempt 2
- Remaining gaps: {list from second VERIFICATION.md}
- Gap closure plans: {list of plans created}
- Re-verification result: {what still failed}

### Root Cause Hypothesis
{System's best hypothesis for why gap closure is not resolving the issue}

### Suggested Actions
1. `$gpd-debug` — Systematic investigation of the persistent failure
2. `$gpd-discuss-phase {X}` — Reassess the approach with fresh perspective
3. Manual intervention — The issue may require researcher insight

Do NOT attempt a third automated cycle.

After gap closure execution completes (--gaps-only mode):

Automatically re-verify the phase to confirm gaps are closed:

VERIFIER_MODEL=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local resolve-model gpd-verifier)

task(
  subagent_type="gpd-verifier",
  model="{verifier_model}",
  readonly=false,
  prompt="First, read ./.codex/agents/gpd-verifier.md for your role and instructions.

Re-verify Phase {PHASE_NUMBER} after gap closure.

<phase_class>{PHASE_CLASSES}</phase_class>

<files_to_read>
Read these files using the read_file tool:
- Verification: {phase_dir}/{phase}-VERIFICATION.md
- All SUMMARY.md files in {phase_dir}/
- State: .gpd/STATE.md
- Roadmap: .gpd/ROADMAP.md
</files_to_read>

Focus on the gaps that were marked as 'failed' or 'diagnosed' in the previous verification.
Check whether the gap closure plans have resolved each issue.
Update VERIFICATION.md with new status for each gap.
Return verification status: passed | gaps_found.",
  description="Re-verify Phase {PHASE_NUMBER} after gap closure"
)

If the verifier agent fails to spawn or returns an error: Proceed without automated re-verification. Note in the phase status that post-gap-closure verification was skipped. The user should run $gpd-verify-work separately to confirm gaps are closed.

Re-verification Result	Action
passed	Mark phase complete, proceed to update_roadmap
gaps_found	Report remaining gaps and STOP -- do not auto-loop. Present: "Re-verification found {N} remaining gaps. Review: {phase_dir}/{phase}-VERIFICATION.md"

Run a rapid cross-phase consistency check to catch convention violations and sign errors before they propagate to future phases.

Resolve consistency checker model:

CONSISTENCY_MODEL=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local resolve-model gpd-consistency-checker)

Spawn the consistency checker in rapid mode:

task(prompt="First, read ./.codex/agents/gpd-consistency-checker.md for your role and instructions.

rapid {PHASE_NUMBER}

Check phase {PHASE_NUMBER} results against the full conventions ledger and all accumulated project state. Read conventions from state.json via: gpd convention list And from SUMMARY.md frontmatter convention fields. read_file: .gpd/STATE.md, .gpd/state.json read_file: All SUMMARY.md files from phase {PHASE_NUMBER}

Return consistency_status with any issues found. ", subagent_type="gpd-consistency-checker", model="{consistency_model}", readonly=false, description="Rapid consistency check")

If the consistency checker agent fails to spawn or returns an error: Proceed without cross-phase consistency checking for this wave. Note in the phase status that consistency verification was skipped. The user should run $gpd-validate-conventions after execution completes to catch any convention drift.

If INCONSISTENT: STOP execution. Present issues to user with resolution options:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GPD > CONVENTION INCONSISTENCY DETECTED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

{issues from consistency checker}

──────────────────────────────────────────────────────
Options:
  1. "Resolve conventions" -- spawn notation coordinator to fix (Recommended)
  2. "Force continue" -- proceed despite inconsistency (--force-inconsistent)
  3. "Stop" -- halt and investigate manually
──────────────────────────────────────────────────────

If "Resolve conventions": Spawn gpd-notation-coordinator to fix the conflicts:

NOTATION_MODEL=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local resolve-model gpd-notation-coordinator)

task(
  subagent_type="gpd-notation-coordinator",
  model="{notation_model}",
  readonly=false,
  prompt="First, read ./.codex/agents/gpd-notation-coordinator.md for your role and instructions.

<task>
Resolve convention inconsistencies found by consistency checker after phase {PHASE_NUMBER} execution.
</task>

<issues>
{consistency_checker_issues}
</issues>

<project_context>
read_file: .gpd/STATE.md, .gpd/state.json, .gpd/CONVENTIONS.md
read_file: All SUMMARY.md files from phase {PHASE_NUMBER}
Load conventions: gpd convention list
</project_context>

<output>
1. Update convention lock via gpd convention set (if lock is wrong)
2. Update CONVENTIONS.md (if doc is stale)
3. Flag any phase artifacts that need re-execution with corrected conventions
4. Return CONVENTION UPDATE or CONVENTION CONFLICT
</output>
",
  description="Resolve convention conflicts after Phase {PHASE_NUMBER}"
)

If the notation coordinator agent fails to spawn or returns an error: The consistency issues remain unresolved. Offer: 1) Retry notation coordinator, 2) Resolve conflicts manually by editing CONVENTIONS.md and using gpd convention set, 3) Force continue with known inconsistencies (log to DECISIONS.md). Do not silently proceed — convention errors compound across phases.

Handle notation-coordinator return:

• CONVENTION UPDATE: Conventions fixed. Commit CONVENTIONS.md. If any phase artifacts were flagged for re-execution, present them to user. Continue to phase completion.
• CONVENTION CONFLICT: Unresolvable conflict requiring user decision. Present options and wait.

If "Force continue": Log the forced override to DECISIONS.md:

/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local state add-decision \
  --phase "${phase_number}" \
  --summary "Forced past consistency check (--force-inconsistent)" \
  --rationale "${USER_RATIONALE}"

If WARNING: Present warnings, ask user whether to proceed or investigate. If CONSISTENT: Continue to phase completion.

Mark phase complete in ROADMAP.md (date, status).

Follow the full transition protocol. Read ./.codex/get-physics-done/workflows/transition.md using the read_file tool for PROJECT.md evolution, DECISIONS.md updates, and parallel phase detection.

PRE_CHECK=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local pre-commit-check --files .gpd/ROADMAP.md .gpd/STATE.md "${phase_dir}"/*-VERIFICATION.md .gpd/REQUIREMENTS.md 2>&1) || true
echo "$PRE_CHECK"

/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local commit "docs(phase-${phase_number}): complete phase execution" --files .gpd/ROADMAP.md .gpd/STATE.md "${phase_dir}"/*-VERIFICATION.md .gpd/REQUIREMENTS.md

**After successful phase completion (all plans passed + verification passed):**

Remove all gpd-checkpoint/* tags for this phase -- they are no longer needed.

# List all checkpoint tags for this phase
PHASE_TAGS=$(git tag -l "gpd-checkpoint/phase-${phase_number}-*")

if [ -n "${PHASE_TAGS}" ]; then
  echo "Cleaning up ${phase_number} checkpoint tags..."
  for TAG in ${PHASE_TAGS}; do
    git tag -d "${TAG}" 2>/dev/null
  done
  echo "Checkpoint tags removed for phase ${phase_number}."
fi

If there were ANY failures during the phase (even if subsequently resolved via re-execution), keep all checkpoint tags. They provide audit trail and enable future rollback if issues surface later.

Decision logic:

Condition	Action
All plans passed + verification passed	Delete all gpd-checkpoint/phase-{X}-* tags
Any plans failed (even if kept partial)	Keep all checkpoint tags
Verification found gaps	Keep all checkpoint tags
Phase marked complete after gap closure	Delete checkpoint tags from successful re-run only

If more phases:

## Next Up

**Phase {X+1}: {Name}** -- {Goal}

`$gpd-plan-phase {X+1}`

<sub>`/clear` first for fresh context</sub>

If milestone complete:

MILESTONE COMPLETE!

All {N} phases executed.

`$gpd-complete-milestone`

<context_efficiency> Orchestrator: ~10-15% context. Subagents: fresh 200k each. No polling (Task blocks). No context bleed. </context_efficiency>

<failure_handling>

• False failure report despite delivered work: Spot-check (SUMMARY exists, commits present, expected artifacts exist) -> if pass, treat as success
• Agent fails mid-plan: Missing SUMMARY.md -> report, route to wave_failure_handling for user decision
• Dependency chain breaks: Wave N plan fails -> identify Wave N+1 dependents via depends_on frontmatter -> auto-skip with clear message -> user chooses at wave level
• All agents in wave fail: Systemic issue -> stop, report for investigation, offer wave-level rollback
• Checkpoint unresolvable: "Skip this plan?" or "Abort phase execution?" -> record partial progress in STATE.md
• Physics validation failure: Dimensional inconsistency or conservation law violation detected -> STOP, do not proceed to next wave, report for investigation </failure_handling>

Re-run `$gpd-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.

Partial completion detection: execute-plan's detect_previous_attempt step checks git log for task-level commits. Plans with partial commits offer resume-from-task-N. Plans with RECOVERY-{PLAN}.md files surface recovery options.

<ui_patterns>

Visual patterns for user-facing GPD output. Orchestrators @-reference this file.

Stage Banners

Use for major workflow transitions.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GPD ► {STAGE NAME}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Stage names (uppercase):

• FORMULATING PROBLEM
• SURVEYING LITERATURE
• DEFINING SCOPE
• CREATING ROADMAP
• PLANNING PHASE {N}
• EXECUTING WAVE {N}
• VERIFYING
• PHASE {N} COMPLETE ✓
• MILESTONE COMPLETE ⚛️

---

Checkpoint Boxes

User action required. 62-character width.

╔══════════════════════════════════════════════════════════════╗
║  CHECKPOINT: {Type}                                          ║
╚══════════════════════════════════════════════════════════════╝

{Content}

──────────────────────────────────────────────────────────────
→ {ACTION PROMPT}
──────────────────────────────────────────────────────────────

Types:

• CHECKPOINT: Verification Required → → Type "approved" or describe issues
• CHECKPOINT: Decision Required → → Select: option-a / option-b
• CHECKPOINT: Action Required → → Type "done" when complete
• CHECKPOINT: Physics Check Required → → Confirm dimensional consistency / limiting cases

---

Status Symbols

✓  Complete / Passed / Verified
✗  Failed / Inconsistent / Divergent
◆  In Progress
○  Pending
⚡ Auto-verified (dimensional analysis, symmetry check)
⚠  Warning (suspicious but not proven wrong)
⚛️  Milestone complete (only in banner)
∇  Gradient/field operation in progress
∞  Divergence detected
≈  Approximate agreement

---

Progress Display

Phase/milestone level:

Progress: ████████░░ 80%

Task level:

Tasks: 2/4 complete

Plan level:

Plans: 3/5 complete

Convergence display (numerical phases):

Convergence: |δE| = 2.3e-6 → 1.1e-8 → 4.7e-11  ✓ (tol: 1e-8)

---

Spawning Indicators

◆ Spawning researcher...

◆ Spawning 4 researchers in parallel...
  → Symmetry analysis
  → Perturbative expansion
  → Numerical estimation
  → Literature cross-check

✓ Researcher complete: SYMMETRY_ANALYSIS.md written

---

Next Up Block

Always at end of major completions.

───────────────────────────────────────────────────────────────

## ▶ Next Up

**{Identifier}: {Name}** — {one-line description}

`{copy-paste command}`

<sub>`/clear` first → fresh context window</sub>

───────────────────────────────────────────────────────────────

**Also available:**
- `$gpd-alternative-1` — description
- `$gpd-alternative-2` — description

───────────────────────────────────────────────────────────────

---

Error Box

╔══════════════════════════════════════════════════════════════╗
║  ERROR                                                       ║
╚══════════════════════════════════════════════════════════════╝

{Error description}

**To fix:** {Resolution steps}

---

Physics-Specific Display Elements

Equation reference:

Eq. (3.14): H = p²/2m + V(x)

Unit annotation:

[E] = GeV    [L] = fm    [T] = fm/c

Parameter table:

| Parameter | Value | Units | Source |
|-----------|-------|-------|--------|
| m_e       | 0.511 | MeV/c² | PDG 2024 |
| α         | 1/137.036 | dimensionless | CODATA |
| Λ_QCD     | 217 | MeV | lattice |

Verification summary:

Checks:
  ✓ Dimensional analysis
  ✓ Non-relativistic limit → Schrodinger equation
  ✓ Energy conservation (ΔE/E < 1e-12)
  ⚠ Gauge invariance (numerical, not exact)
  ○ Lorentz covariance (pending)

---

Tables

| Phase | Status | Plans | Progress |
|-------|--------|-------|----------|
| 1     | ✓      | 3/3   | 100%     |
| 2     | ◆      | 1/4   | 25%      |
| 3     | ○      | 0/2   | 0%       |