@howlil/ez-agents 3.4.2 → 4.0.0

package/ez-agents/workflows/autonomous.md

@@ -1,6 +1,8 @@
 <purpose>
 
-Drive all remaining milestone phases autonomously. For each incomplete phase: discuss → plan → execute using Skill() flat invocations. Pauses only for explicit user decisions (grey area acceptance, blockers, validation requests). Re-reads ROADMAP.md after each phase to catch dynamically inserted phases.
+Drive all remaining milestone phases autonomously. For each incomplete phase: discuss → plan → execute **ALL tasks in loop** using Skill() flat invocations. Pauses only for explicit user decisions (grey area acceptance, blockers, validation requests). Re-reads ROADMAP.md after each phase to catch dynamically inserted phases.
+
+**Key:** Execute-phase loops through ALL task plans within a phase, not just the phase as a whole.
 
 </purpose>
 
@@ -86,12 +88,12 @@ Exit cleanly.
 ```
 ## Phase Plan
 
-| # | Phase | Status |
-|---|-------|--------|
-| 5 | Skill Scaffolding & Phase Discovery | In Progress |
-| 6 | Smart Discuss | Not Started |
-| 7 | Auto-Chain Refinements | Not Started |
-| 8 | Lifecycle Orchestration | Not Started |
+| # | Phase | Status | Tasks |
+|---|-------|--------|-------|
+| 5 | Skill Scaffolding & Phase Discovery | In Progress | [count] |
+| 6 | Smart Discuss | Not Started | [count] |
+| 7 | Auto-Chain Refinements | Not Started | [count] |
+| 8 | Lifecycle Orchestration | Not Started | [count] |
 ```
 
 **Fetch details for each phase:**
@@ -100,13 +102,13 @@ Exit cleanly.
 DETAIL=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" roadmap get-phase ${PHASE_NUM})
 ```
 
-Extract `phase_name`, `goal`, `success_criteria` from each. Store for use in execute_phase and transition messages.
+Extract `phase_name`, `goal`, `success_criteria`, `task_count` from each. Store for use in execute_phase and transition messages.
 
 </step>
 
 <step name="execute_phase">
 
-## 3. Execute Phase
+## 3. Execute Phase (with Task Loop)
 
 For the current phase, display the progress banner:
 
@@ -114,9 +116,11 @@ For the current phase, display the progress banner:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  EZ ► AUTONOMOUS ▸ Phase {N}/{T}: {Name} [████░░░░] {P}%
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Phase {N} has {task_count} tasks to execute
 ```
 
-Where N = current phase number (from the ROADMAP, e.g., 6), T = total milestone phases (from `phase_count` parsed in initialize step, e.g., 8), P = percentage of all milestone phases completed so far. Calculate P as: (number of phases with `disk_status` "complete" from the latest `roadmap analyze` / T × 100). Use █ for filled and ░ for empty segments in the progress bar (8 characters wide).
+Where N = current phase number (from the ROADMAP, e.g., 6), T = total milestone phases (from `phase_count` parsed in initialize step, e.g., 8), P = percentage of all milestone phases completed so far.
 
 **3a. Smart Discuss**
 
@@ -154,15 +158,95 @@ Skill(skill="ez:plan-phase", args="${PHASE_NUM}")
 
 Verify plan produced output — re-run `init phase-op` and check `has_plans`. If false → go to handle_blocker: "Plan phase ${PHASE_NUM} did not produce any plans."
 
-**3c. Execute**
+**Get task list for loop:**
+
+```bash
+PLANS=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" phase-list-plans ${PHASE_NUM})
+```
+
+Parse JSON for: `plans` array with `plan_number`, `plan_name`, `task_description`, `status` for each plan.
+
+**Filter to incomplete plans:** Keep only plans where `status !== "complete"`.
+
+**Store for task loop:** `plan_list` = array of incomplete plans.
+
+**3c. Execute ALL Tasks in Loop**
+
+Display task execution banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► AUTONOMOUS ▸ Phase {N} Task Execution
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ {task_count} tasks to execute in Phase {N}
+```
+
+**For each plan in `plan_list` (loop through ALL tasks):**
+
+```
+FOR EACH plan IN plan_list:
+```
+
+**3c-i. Display task progress:**
+
+```
+Task {plan.plan_number}/{task_count}: {plan.plan_name}
+[████░░░░] {completed_tasks}/{total_tasks} completed
+```
+
+**3c-ii. Execute single task:**
 
 ```
-Skill(skill="ez:execute-phase", args="${PHASE_NUM} --no-transition")
+Skill(skill="ez:execute-phase", args="${PHASE_NUM} --plan ${plan.plan_number} --no-transition")
 ```
 
-**3d. Post-Execution Routing**
+**3c-iii. Verify task completion:**
 
-After execute-phase returns, read the verification result:
+```bash
+TASK_STATUS=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" phase-get-task-status ${PHASE_NUM} ${plan.plan_number})
+```
+
+Parse `status` from JSON (values: "complete", "in_progress", "blocked", "failed").
+
+**If `complete`:**
+- Display: `✅ Task ${plan.plan_number}: ${plan.plan_name} — Complete`
+- Mark task as completed in local tracking
+- Continue to next task in loop
+
+**If `in_progress`:**
+- Display: `⚠ Task ${plan.plan_number}: ${plan.plan_name} — Still in progress`
+- Retry status check once (wait 30 seconds)
+- If still `in_progress` → go to handle_blocker: "Task ${plan.plan_number} did not complete"
+
+**If `blocked` or `failed`:**
+- Read error/blocker details from task status
+- Go to handle_blocker with: "Task ${plan.plan_number} (${plan.plan_name}) ${status}: {details}"
+
+**3c-iv. After each task completes, update phase progress:**
+
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" phase-update-progress ${PHASE_NUM}
+```
+
+**End loop** (continue to next plan in plan_list)
+
+**After ALL tasks complete:**
+
+Display phase completion banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► AUTONOMOUS ▸ Phase {N} Complete ✅
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ All {task_count} tasks completed successfully
+ Phase {N}: {phase_name} — DONE
+```
+
+**3d. Post-Execution Verification**
+
+After all tasks in the phase complete, read the verification result:
 
 ```bash
 VERIFY_STATUS=$(grep "^status:" "${PHASE_DIR}"/*-VERIFICATION.md 2>/dev/null | head -1 | cut -d: -f2 | tr -d ' ')
@@ -185,6 +269,7 @@ Go to handle_blocker: "Execute phase ${PHASE_NUM} did not produce verification r
 Display:
 ```
 Phase ${PHASE_NUM} ✅ ${PHASE_NAME} — Verification passed
+All {task_count} tasks verified
 ```
 
 Proceed to iterate step.
@@ -194,7 +279,7 @@ Proceed to iterate step.
 Read the human_verification section from VERIFICATION.md to get the count and items requiring manual testing.
 
 Display the items, then ask user via AskUserQuestion:
-- **question:** "Phase ${PHASE_NUM} has items needing manual verification. Validate now or continue to next phase?"
+- **question:** "Phase ${PHASE_NUM} has {N} items needing manual verification. Validate now or continue to next phase?"
 - **options:** "Validate now" / "Continue without validation"
 
 On **"Validate now"**: Present the specific items from VERIFICATION.md's human_verification section. After user reviews, ask:
@@ -213,6 +298,7 @@ Read gap summary from VERIFICATION.md (score and missing items). Display:
 ```
 ⚠ Phase ${PHASE_NUM}: ${PHASE_NAME} — Gaps Found
 Score: {N}/{M} must-haves verified
+{gap_count} tasks have gaps
 ```
 
 Ask user via AskUserQuestion:
@@ -227,9 +313,15 @@ Skill(skill="ez:plan-phase", args="${PHASE_NUM} --gaps")
 
 Verify gap plans were created — re-run `init phase-op ${PHASE_NUM}` and check `has_plans`. If no new gap plans → go to handle_blocker: "Gap closure planning for phase ${PHASE_NUM} did not produce plans."
 
-Re-execute:
+**Re-execute ALL gap tasks in loop:**
+
+```bash
+GAP_PLANS=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" phase-list-plans ${PHASE_NUM} --gap-only)
+```
+
+For each gap plan in GAP_PLANS:
 ```
-Skill(skill="ez:execute-phase", args="${PHASE_NUM} --no-transition")
+Skill(skill="ez:execute-phase", args="${PHASE_NUM} --plan ${gap_plan.number} --no-transition")
 ```
 
 Re-read verification status:
@@ -357,7 +449,7 @@ Read the 3-5 most relevant files to understand existing patterns.
 DETAIL=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" roadmap get-phase ${PHASE_NUM})
 ```
 
-Extract `goal`, `requirements`, `success_criteria` from the JSON response.
+Extract `goal`, `requirements`, `success_criteria`, `task_count` from the JSON response.
 
 **Infrastructure detection — check FIRST before generating grey areas:**
 
@@ -542,7 +634,7 @@ Decisions captured: {count} across {area_count} areas
 
 ## 4. Iterate
 
-After each phase completes, re-read ROADMAP.md to catch phases inserted mid-execution (decimal phases like 5.1):
+After each phase completes (ALL tasks executed), re-read ROADMAP.md to catch phases inserted mid-execution (decimal phases like 5.1):
 
 ```bash
 ROADMAP=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" roadmap analyze)
@@ -563,7 +655,7 @@ Check for blockers in the Blockers/Concerns section. If blockers are found, go t
 
 If incomplete phases remain: proceed to next phase, loop back to execute_phase.
 
-If all phases complete, proceed to lifecycle step.
+If all phases complete: proceed to lifecycle step.
 
 </step>
 
@@ -674,6 +766,7 @@ Display final completion banner:
  Milestone: {milestone_version} — {milestone_name}
  Status: Complete ✅
  Lifecycle: audit ✅ → complete ✅ → cleanup ✅
+ All Tasks: {total_tasks} executed across {phase_count} phases
 
  Ship it! 🚀
 ```
@@ -686,16 +779,16 @@ Display final completion banner:
 
 When any phase operation fails or a blocker is detected, present 3 options via AskUserQuestion:
 
-**Prompt:** "Phase {N} ({Name}) encountered an issue: {description}"
+**Prompt:** "Phase {N} ({Name}), Task {task_num} encountered an issue: {description}"
 
 **Options:**
-1. **"Fix and retry"** — Re-run the failed step (discuss, plan, or execute) for this phase
-2. **"Skip this phase"** — Mark phase as skipped, continue to the next incomplete phase
+1. **"Fix and retry"** — Re-run the failed step (discuss, plan, or execute) for this task
+2. **"Skip this task"** — Mark task as skipped, continue to next task in same phase
 3. **"Stop autonomous mode"** — Display summary of progress so far and exit cleanly
 
 **On "Fix and retry":** Loop back to the failed step within execute_phase. If the same step fails again after retry, re-present these options.
 
-**On "Skip this phase":** Log `Phase {N} ⏭ {Name} — Skipped by user` and proceed to iterate.
+**On "Skip this task":** Log `Phase {N}, Task {task_num} ⏭ {task_name} — Skipped by user` and continue to next task in the phase loop.
 
 **On "Stop autonomous mode":** Display progress summary:
 
@@ -704,11 +797,12 @@ When any phase operation fails or a blocker is detected, present 3 options via A
  EZ ► AUTONOMOUS ▸ STOPPED
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
- Completed: {list of completed phases}
- Skipped: {list of skipped phases}
- Remaining: {list of remaining phases}
+ Completed Phases: {list of completed phases}
+ In Progress: Phase {N}, Task {task_num}
+ Skipped Tasks: {list of skipped tasks}
+ Remaining Tasks: {count} tasks in {count} phases
 
- Resume with: /ez:autonomous --from {next_phase}
+ Resume with: /ez:autonomous --from {current_phase}
 ```
 
 </step>
@@ -719,16 +813,23 @@ When any phase operation fails or a blocker is detected, present 3 options via A
 - [ ] All incomplete phases executed in order (smart discuss → plan → execute each)
 - [ ] Smart discuss proposes grey area answers in tables, user accepts or overrides per area
 - [ ] Progress banners displayed between phases
-- [ ] Execute-phase invoked with --no-transition (autonomous manages transitions)
+- [ ] Execute-phase loops through ALL task plans within each phase
+- [ ] Each task plan executed individually with --plan {N} flag
+- [ ] Task progress displayed during loop ([████░░░░] X/Y completed)
+- [ ] Task completion verified after each execution
+- [ ] Failed/blocked tasks route to handle_blocker
+- [ ] After ALL tasks complete, phase verification runs
 - [ ] Post-execution verification reads VERIFICATION.md and routes on status
 - [ ] Passed verification → automatic continue to next phase
 - [ ] Human-needed verification → user prompted to validate or skip
 - [ ] Gaps-found → user offered gap closure, continue, or stop
+- [ ] Gap closure re-executes ALL gap tasks in loop
 - [ ] Gap closure limited to 1 retry (prevents infinite loops)
 - [ ] Plan-phase and execute-phase failures route to handle_blocker
 - [ ] ROADMAP.md re-read after each phase (catches inserted phases)
 - [ ] STATE.md checked for blockers before each phase
 - [ ] Blockers handled via user choice (retry / skip / stop)
+- [ ] Task-level blocker handling (skip task vs skip phase)
 - [ ] Final completion or stop summary displayed
 - [ ] After all phases complete, lifecycle step is invoked (not manual suggestion)
 - [ ] Lifecycle transition banner displayed before audit
@@ -737,7 +838,7 @@ When any phase operation fails or a blocker is detected, present 3 options via A
 - [ ] Audit technical failure (no file/no status) routes to handle_blocker
 - [ ] Complete-milestone invoked via Skill() with ${milestone_version} arg
 - [ ] Cleanup invoked via Skill() — internal confirmation is acceptable (CTRL-01)
-- [ ] Final completion banner displayed after lifecycle
+- [ ] Final completion banner displays total task count
 - [ ] Progress bar uses phase number / total milestone phases (not position among incomplete)
 - [ ] Smart discuss documents relationship to discuss-phase with CTRL-03 note
 </success_criteria>

package/ez-agents/workflows/complete-milestone.md

@@ -24,7 +24,7 @@ When a milestone completes:
 4. Delete REQUIREMENTS.md (fresh one for next milestone)
 5. Perform full PROJECT.md evolution review
 6. Offer to create next milestone inline
-7. Archive UI artifacts (`*-UI-SPEC.md`, `*-UI-REVIEW.md`) alongside other phase documents
+7. Archive UI artifacts (SUMMARY.md, UAT.md) alongside other phase documents
 8. Clean up `.planning/ui-reviews/` screenshot files (binary assets, never archived)
 
 **Context Efficiency:** Archives keep ROADMAP.md constant-size and REQUIREMENTS.md milestone-scoped.

package/ez-agents/workflows/discuss-phase.md

@@ -638,7 +638,7 @@ Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
 
 **Also available:**
 - `/ez:plan-phase ${PHASE} --skip-research` — plan without research
-- `/ez:ui-phase ${PHASE}` — generate UI design contract before planning (if phase has frontend work)
+- Not a frontend phase → Continue without UI spec
 - Review/edit CONTEXT.md before continuing
 
 ---

package/ez-agents/workflows/execute-phase.md

@@ -12,6 +12,34 @@ Read STATE.md before any operation to load project context.
 
 <process>
 
+<auto_invoke>
+Run BEFORE the initialize step. Check flags from ARGUMENTS:
+
+**Flag handling:**
+- If ARGUMENTS contains `--no-auto`: skip all auto_invoke blocks, proceed directly to initialize.
+- If ARGUMENTS contains `--verbose`: display detail for every auto_invoke step.
+
+**Pre-flight health check (always, unless --no-auto):**
+```bash
+SMART_ORCH=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-get smart_orchestration.enabled 2>/dev/null || echo "true")
+```
+If `SMART_ORCH` is `"false"`: skip all auto_invoke, proceed to initialize.
+
+```bash
+HEALTH=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" health --json 2>/dev/null)
+```
+- If output shows status FAIL: display error, STOP execution.
+- If PASS: display `[auto] ✅ health check passed` only when `--verbose` flag is present; otherwise silent.
+
+**Conditional discuss-phase:**
+Read tier from `.planning/config.json` (`release.tier`). If tier is `medium` or `enterprise` AND no CONTEXT.md exists in the phase directory AND `--skip-discussion` is not in ARGUMENTS:
+  → Display: `[auto] Running pre-flight discussion...`
+  → Invoke: Skill(ez:discuss-phase, args: phase_number + " --auto")
+  → Continue to initialize.
+
+If conditions are not met: skip silently.
+</auto_invoke>
+
 <step name="initialize" priority="first">
 Load all context in one call:
 
@@ -103,7 +131,29 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
    - Bad: "Executing terrain generation plan"
    - Good: "Procedural terrain generator using Perlin noise — creates height maps, biome zones, and collision meshes. Required before vehicle physics can interact with ground."
 
-2. **Spawn executor agents:**
+2. **Batch execution (resource-aware):**
+
+   Read `maxParallel` from config (default: 5). If wave has {N} plans:
+   - Batch size = maxParallel
+   - Number of batches = Math.ceil(N / maxParallel)
+   - Execute each batch sequentially, wait for all agents in batch to complete before next batch
+
+   ```bash
+   # Read maxParallel from config
+   MAX_PARALLEL=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-get workflow.maxParallel 2>/dev/null || echo "5")
+
+   # Calculate batches
+   WAVE_PLAN_COUNT={N}
+   BATCH_COUNT=$(( (WAVE_PLAN_COUNT + MAX_PARALLEL - 1) / MAX_PARALLEL ))
+   ```
+
+   **Loop through batches:**
+   - Batch 1: Spawn min(remaining, maxParallel) agents
+   - Wait for all agents in batch to complete
+   - Check for failures before proceeding to next batch
+   - Repeat until all batches complete
+
+3. **Spawn executor agents:**
 
    Pass paths only — executors read files themselves with their fresh 200k context.
    This keeps orchestrator context lean (~10-15%).
@@ -234,20 +284,27 @@ After all waves:
 ```markdown
 ## Phase {X}: {Name} Execution Complete
 
-**Waves:** {N} | **Plans:** {M}/{total} complete
+**Waves:** {N} | **Plans:** {M}/{total} complete | **Blocked:** {B}
 
 | Wave | Plans | Status |
 |------|-------|--------|
 | 1 | plan-01, plan-02 | ✓ Complete |
 | CP | plan-03 | ✓ Verified |
 | 2 | plan-04 | ✓ Complete |
+| 3 | plan-05 | ⚠ Blocked (depends on failed plan-02) |
 
 ### Plan Details
 1. **03-01**: [one-liner from SUMMARY.md]
 2. **03-02**: [one-liner from SUMMARY.md]
 
+### Blocked Plans
+- **{plan-id}**: Blocked — depends on {failed-plan-id} (Wave {N})
+
 ### Issues Encountered
 [Aggregate from SUMMARYs, or "None"]
+
+### Failed Plans
+[List failed plans with error summary, or "None"]
 ```
 </step>
 
@@ -304,6 +361,76 @@ node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs(phase-${PARENT_PHAS
 <step name="verify_phase_goal">
 Verify phase achieved its GOAL, not just completed tasks.
 
+## Design Review Gate (Frontend Phases Only)
+
+**If phase has frontend/UI work:** Spawn ez-design-expert BEFORE verifier.
+
+```bash
+# Check if phase has frontend indicators
+PHASE_SECTION=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" roadmap get-phase "${PHASE_NUMBER}" 2>/dev/null)
+echo "$PHASE_SECTION" | grep -iE "UI|interface|frontend|component|layout|page|screen|view|form|dashboard|widget" > /dev/null 2>&1
+HAS_UI=$?
+```
+
+**If `HAS_UI` is 0 (frontend found):**
+
+```
+Task(
+  prompt="Review UI design quality for phase {phase_number}.
+Phase directory: {phase_dir}
+Check: design token consistency, AI slop patterns, visual hierarchy.
+Report: PASS/PASS_WITH_WARNINGS/FAIL with specific fixes.
+Output: DESIGN-REVIEW.md",
+  subagent_type="ez-design-expert",
+  model="{planner_model}"
+)
+```
+
+**Read verdict:**
+```bash
+grep "^**Status:**" "$PHASE_DIR"/DESIGN-REVIEW.md | cut -d: -f2 | tr -d ' '
+```
+
+| Verdict | Action |
+|---------|--------|
+| `PASS` | → Continue to verifier |
+| `PASS_WITH_WARNINGS` | → Show warnings, continue to verifier |
+| `FAIL` | → Show critical issues, offer `/ez:plan-phase {N} --design-fixes` |
+
+**If FAIL:**
+```
+## ❌ Design Review Failed — Phase {X}: {Name}
+
+**AI Slop Detected:** {specific patterns found}
+
+### Critical Issues
+{List from DESIGN-REVIEW.md}
+
+---
+## ▶ Next Up
+
+`/ez:plan-phase {X} --design-fixes`
+
+<sub>`/clear` first → fresh context window</sub>
+
+Also: `cat {phase_dir}/DESIGN-REVIEW.md` — full report
+```
+
+**If PASS or PASS_WITH_WARNINGS:**
+```
+## ✅ Design Review Complete
+
+**Status:** {PASS | PASS_WITH_WARNINGS}
+
+{Warnings list if any}
+
+Continuing to verification...
+```
+
+---
+
+## Standard Verification
+
 ```
 Task(
   prompt="Verify phase {phase_number} goal achievement.
@@ -447,6 +574,23 @@ Read and follow `~/.claude/ez-agents/workflows/transition.md`, passing through t
 ```
 </step>
 
+<auto_invoke_post>
+Run AFTER all waves complete. Skip if --no-auto is in ARGUMENTS or `smart_orchestration.enabled` is false.
+
+**Post-execution verify-work:**
+Display: `[auto] Running verification...`
+Invoke: Skill(ez:verify-work, args: phase_number)
+- If PASS: display `[auto] ✅ Verification passed`
+- If FAIL: display `⚠️ Verification warnings (non-blocking)` — show details, do NOT block
+
+**Scope creep detection:**
+Check if there is scope creep from DISCUSSION.md (if it exists):
+```bash
+grep -i "scope creep\|out of scope\|BLOCKER" .planning/phases/${PHASE_DIR}/DISCUSSION.md 2>/dev/null
+```
+If any match found: display `[auto] Scope creep detected — creating todos...` → Invoke: Skill(ez:add-todo)
+</auto_invoke_post>
+
 </process>
 
 <context_efficiency>
@@ -454,9 +598,31 @@ Orchestrator: ~10-15% context. Subagents: fresh 200k each. No polling (Task bloc
 </context_efficiency>
 
 <failure_handling>
+**Failure classification:**
+
+- **Transient failures** (API timeout, rate limit 429, network error):
+  - Auto-retry up to 2 times with exponential backoff (1s, 2s, 4s delays)
+  - If retry succeeds: continue execution
+  - If retry fails after 2 attempts: classify as permanent
+
+- **Permanent failures** (logic error, missing file, validation failure):
+  - Stop immediately, do not retry
+  - Report to user with error details
+  - Mark plan as failed
+
+**Dependency-aware failure handling:**
+
+1. After each wave completes, collect failed plan IDs
+2. Before starting next wave, check each plan's `depends_on`:
+   - If depends_on includes any failed plan: mark as **blocked** (skip execution)
+   - If depends_on is clear: execute normally
+3. Track blocked plans in summary output
+
+**Specific scenarios:**
+
 - **classifyHandoffIfNeeded false failure:** Agent reports "failed" but error is `classifyHandoffIfNeeded is not defined` → Claude Code bug, not EZ. 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
+- **Dependency chain breaks:** Wave 1 fails → Wave 2 dependents are **blocked** → report blocked plans, user chooses attempt remaining 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>