maestro-flow 0.1.4 → 0.2.0

package/workflows/execute.md

@@ -1,413 +1,427 @@
-# Execute Workflow
-
-Wave-based parallel execution with atomic commits, breakpoint resume, and optional sync/reflection.
-
----
-
-## Prerequisites
-
-- Phase has a completed plan: `plan.json` + `.task/TASK-*.json` exist
-- `index.json` present with `plan.waves` populated
-- OR: executionContext handoff received from `/workflow:plan`
-
----
-
-## Phase Resolution
-
-```
-Input: <phase> argument (number or slug) OR --dir <path>
-
-IF --dir <path> is provided:
-  1. Set PHASE_DIR = <path> (absolute or relative to project root)
-  2. Validate directory exists and contains index.json
-  3. Set SCRATCH_MODE = true (skip roadmap validation, phase transition)
-  4. Set PHASE_NUM = null, PHASE_SLUG = directory basename
-
-ELSE (standard phase resolution):
-  1. If number: find .workflow/phases/{NN}-*/index.json
-  2. If slug: find .workflow/phases/*-{slug}/index.json
-  3. Validate plan exists (index.json.plan.task_count > 0)
-  4. Set PHASE_DIR = resolved path
-```
-
----
-
-## Flag Processing
-
-| Flag | Effect |
-|------|--------|
-| `--auto-commit` | Override config: commit after each task completion |
-| `--method agent\|cli` | Override execution method (default: config.json.execution.method) |
-| `--dir <path>` | Use arbitrary directory instead of phase resolution (skip roadmap validation) |
-
----
-
-## E1: Load Plan
-
-**Purpose:** Build or receive the execution queue.
-
-### From executionContext handoff (preferred)
-
-```
-If executionContext is available in memory:
-  planObject = executionContext.planObject
-  explorations = executionContext.explorations
-  clarifications = executionContext.clarifications
-  executionMethod = executionContext.executionMethod
-  Skip disk reload
-```
-
-### From disk (fallback / resume)
-
-```
-Read ${PHASE_DIR}/index.json
-Read ${PHASE_DIR}/plan.json
-
-executionMethod = --method flag || config.json.execution.method || "agent"
-```
-
-### Detect completed tasks (breakpoint resume)
-
-```
-completed_tasks = []
-For each task_id in index.json.plan.task_ids:
-  Read .task/${task_id}.json
-  If status == "completed":
-    completed_tasks.push(task_id)
-
-If completed_tasks.length > 0:
-  Log "Resuming: {completed_tasks.length}/{total} tasks already completed"
-  Filter completed tasks out of wave execution queue
-  Set current_wave = first wave with pending tasks
-```
-
-### Build wave execution queue
-
-```
-waves = plan.json.waves (or index.json.plan.waves)
-
-execution_queue = []
-For each wave in waves:
-  pending_tasks = wave.tasks.filter(t => !completed_tasks.includes(t))
-  If pending_tasks.length > 0:
-    execution_queue.push({ wave: wave.wave, tasks: pending_tasks })
-```
-
-### Output
-- In-memory: execution_queue, executionMethod, loaded task definitions
-
----
-
-## E1.5: Load Project Specs
-
-```
-specs_content = maestro spec load --category execution
-```
-
-Pass specs_content to each executor agent in E2.
-
----
-
-## E2: Wave Parallel Execution
-
-**Purpose:** Execute tasks wave by wave, parallel within each wave.
-
-### Execution Loop
-
-```
-For each wave in execution_queue (sequential):
-
-  Log "=== Wave {wave.wave}: {wave.tasks.length} tasks ==="
-
-  Update index.json:
-    execution.current_wave = wave.wave
-    execution.started_at = execution.started_at || now()
-
-  # State tracking (once, on first wave entry)
-  If first_wave_entry (current_wave == execution_queue[0].wave):
-    Read .workflow/state.json
-    If state.json.status != "executing":
-      state.json.status = "executing"
-      state.json.phases_summary.in_progress += 1
-      state.json.last_updated = now()
-      Write .workflow/state.json
-
-  For each task_id in wave.tasks (parallel):
-
-    # --- Per-task execution ---
-
-    1. Load task definition
-       Read .task/${task_id}.json (lazy loading)
-
-    2. Spawn workflow-executor agent (fresh 200k context)
-       Input:
-         - Task definition (.task/${task_id}.json)
-         - Phase context (index.json goal, success_criteria)
-         - Relevant summaries from prior waves (.summaries/ of deps)
-         - Execution method override (if --method cli)
-         - Project specs (specs_content from E1.5 — coding conventions, architecture constraints, quality rules)
-        - Phase context decisions (context.md — Locked/Free/Deferred classification)
-        - Phase analysis scores (analysis.md — 6-dimension evaluation)
-
-       Agent responsibilities:
-         a. Read task definition (read_first, files, action, convergence.criteria)
-         b. Implement the task (create/modify files per task.files)
-         c. Verify convergence.criteria pass
-         d. If verification fails: auto-fix (max 3 attempts)
-         e. If auto-fix fails: write checkpoint, mark task as "blocked"
-         f. Atomic commit (if auto-commit enabled):
-            git add <task files>
-            git commit -m "{type}({slug}): {task.title}"
-         g. Write .summaries/${task_id}-summary.md
-         h. Update .task/${task_id}.json:
-            status = "completed" | "blocked"
-
-    3. Collect result
-       result = { task_id, status, summary_path, commit_hash }
-
-    # --- End per-task ---
-
-  Wait for all tasks in wave to complete
-
-  # Post-wave processing
-  For each result in wave_results:
-    Update index.json.execution:
-      tasks_completed += (completed count)
-      commits.push({ hash, task, message }) for each commit
-
-  If any task blocked:
-    Log "Wave {wave.wave}: {blocked_count} tasks blocked"
-    AskUserQuestion:
-      "Tasks blocked: {blocked_list}. Continue to next wave or stop?"
-      Options: [Continue (skip blocked), Stop and review]
-    If stop: break execution loop
-
-  Log "=== Wave {wave.wave} complete ==="
-```
-
-### Deviation Rule
-
-```
-Per task, max 3 auto-fix attempts:
-  Attempt 1: Re-read error, try alternative approach
-  Attempt 2: Simplify implementation
-  Attempt 3: Minimal viable implementation
-
-If all 3 fail:
-  Mark task as "blocked" with checkpoint data:
-    .task/${task_id}.json.meta.checkpoint = {
-      attempt: 3,
-      last_error: "...",
-      partial_files: [...]
-    }
-  Continue wave (other tasks unaffected)
-```
-
----
-
-## E2.5: Post-Wave Validation
-
-**Purpose:** Validate execution integrity after all waves complete, before sync and reflection. Catches missing summaries, status inconsistencies, and tech stack constraint violations early.
-
-### Check 1: Summary Existence
-
-```
-For each task_id in index.json.plan.task_ids:
-  Read .task/${task_id}.json
-  If status == "completed":
-    If NOT file exists .summaries/${task_id}-summary.md:
-      violations.push({
-        type: "missing_summary",
-        severity: "warning",
-        task_id: task_id,
-        message: "Completed task ${task_id} has no summary file at .summaries/${task_id}-summary.md"
-      })
-```
-
-### Check 2: Task Status Consistency
-
-```
-For each task_id in index.json.plan.task_ids:
-  Read .task/${task_id}.json
-  task_status = task.status
-
-  # Verify completed tasks were actually in the execution results
-  If task_status == "completed":
-    If task_id NOT in wave_results (collected from E2):
-      violations.push({
-        type: "status_mismatch",
-        severity: "warning",
-        task_id: task_id,
-        message: "Task ${task_id} status is 'completed' but was not part of execution results"
-      })
-
-  # Verify tasks that ran successfully are marked completed
-  If task_id in wave_results AND wave_results[task_id].status == "completed":
-    If task_status != "completed":
-      violations.push({
-        type: "status_mismatch",
-        severity: "critical",
-        task_id: task_id,
-        message: "Task ${task_id} completed execution but .task/${task_id}.json status is '${task_status}'"
-      })
-```
-
-### Check 3: Tech Stack Constraint Compliance
-
-```
-# Load specs constraints from E1.5 specs_content (already loaded)
-tech_constraints = extract tech_stack constraints from specs_content
-  # e.g., allowed_languages, disallowed_imports, required_patterns
-
-If tech_constraints is not empty:
-  # Collect files modified during execution
-  modified_files = []
-  For each task_id in completed_tasks:
-    Read .task/${task_id}.json
-    For each file in task.files:
-      modified_files.push(file.path)
-
-  # Scan modified files for disallowed imports
-  For each file_path in modified_files:
-    If file exists ${file_path}:
-      file_content = Read ${file_path}
-      For each constraint in tech_constraints.disallowed_imports:
-        If file_content matches constraint.pattern:
-          violations.push({
-            type: "tech_stack_violation",
-            severity: "critical",
-            task_id: associated_task_id,
-            file: file_path,
-            message: "File ${file_path} contains disallowed import matching '${constraint.pattern}': ${constraint.reason}"
-          })
-```
-
-### Gate Logic
-
-```
-critical_violations = violations.filter(v => v.severity == "critical")
-warnings = violations.filter(v => v.severity == "warning")
-
-If warnings.length > 0:
-  Log "Post-wave validation: {warnings.length} warning(s)"
-  For each warning in warnings:
-    Log "  WARN: ${warning.message}"
-
-If critical_violations.length > 0:
-  Log "Post-wave validation: {critical_violations.length} critical violation(s)"
-  For each violation in critical_violations:
-    Log "  CRITICAL: ${violation.message}"
-
-  # Block execution
-  index.json.status = "blocked"
-  index.json.execution.blocked_reason = "Post-wave validation failed with critical violations"
-  index.json.execution.violations = violations
-  index.json.updated_at = now()
-  Write index.json
-
-  Abort: "Post-wave validation failed. Fix critical violations before proceeding."
-
-# No critical violations — continue to E3
-Log "Post-wave validation passed ({warnings.length} warnings, 0 critical)"
-```
-
----
-
-## E3: Auto Sync
-
-**Purpose:** Update codebase documentation after execution.
-
-```
-If config.json.codebase.auto_sync_after_execute == true:
-  Trigger /workflow:sync logic:
-    1. Detect changed files (git diff from execution start)
-    2. Map changes to doc-index.json components/features
-    3. Update affected entries
-    4. Refresh tech-registry and feature-maps as needed
-Else:
-  Log "Auto-sync disabled. Run /workflow:sync manually if needed."
-```
-
----
-
-## E4: Reflection (Optional)
-
-**Purpose:** Record strategy observations for future iterations.
-
-```
-If config.json.workflow.reflection == true:
-  Review execution results:
-    - Which tasks completed smoothly?
-    - Which required auto-fix attempts?
-    - Any blocked tasks?
-    - Patterns observed?
-
-  Append to ${PHASE_DIR}/reflection-log.md:
-    ## Reflection - Wave Execution {timestamp}
-    - Strategy adjustments: [...]
-    - Patterns noted: [...]
-    - Blocked tasks: [...]
-
-  Update index.json.reflection:
-    rounds += 1
-    strategy_adjustments.push(new adjustments)
-```
-
----
-
-## Final State Update
-
-```
-all_completed = index.json.execution.tasks_completed == index.json.execution.tasks_total
-
-If all_completed:
-  index.json.status = "verifying"  (ready for /workflow:verify)
-  index.json.execution.completed_at = now()
-  Log "All tasks completed. Run /workflow:verify to validate results."
-Else:
-  index.json.status = "executing"  (partial, can resume)
-  Log "{completed}/{total} tasks completed. Re-run /workflow:execute to resume."
-
-index.json.updated_at = now()
-
-# Update project state.json (skip in SCRATCH_MODE)
-If NOT SCRATCH_MODE:
-  Read .workflow/state.json
-  If all_completed:
-    state.json.status = "verifying"
-  state.json.last_updated = now()
-  Write .workflow/state.json
-```
-
----
-
-## Error Handling
-
-| Error | Action |
-|-------|--------|
-| Phase directory not found | Abort: "Phase {phase} not found." |
-| No plan exists | Abort: "No plan found. Run /workflow:plan first." |
-| Task file missing | Skip task, log error, continue wave |
-| Agent spawn fails | Retry once, then mark task as "blocked" |
-| Git commit fails | Log warning, continue (task still marked completed) |
-| All tasks in wave blocked | Stop execution, report blocked wave |
-
----
-
-## Breakpoint Resume
-
-The execute workflow is fully resumable:
-
-```
-State tracking in index.json.execution:
-  tasks_completed: N     # Count of finished tasks
-  current_wave: W        # Last active wave
-  commits: [...]         # All commits made
-
-Re-running /workflow:execute <phase>:
-  1. Reads index.json.execution.tasks_completed
-  2. Checks each .task/TASK-*.json status
-  3. Builds queue of remaining tasks
-  4. Continues from next pending wave
-  5. No duplicate execution of completed tasks
-```
+# Execute Workflow
+
+Wave-based parallel execution with atomic commits, breakpoint resume, and optional sync/reflection.
+
+---
+
+## Prerequisites
+
+- Phase has a completed plan: `plan.json` + `.task/TASK-*.json` exist
+- `index.json` present with `plan.waves` populated
+- OR: executionContext handoff received from `/workflow:plan`
+
+---
+
+## Phase Resolution
+
+```
+Input: <phase> argument (number or slug) OR --dir <path>
+
+IF --dir <path> is provided:
+  1. Set PHASE_DIR = <path> (absolute or relative to project root)
+  2. Validate directory exists and contains index.json
+  3. Set SCRATCH_MODE = true (skip roadmap validation, phase transition)
+  4. Set PHASE_NUM = null, PHASE_SLUG = directory basename
+
+ELSE (standard phase resolution):
+  1. If number: find .workflow/phases/{NN}-*/index.json
+  2. If slug: find .workflow/phases/*-{slug}/index.json
+  3. Validate plan exists (index.json.plan.task_count > 0)
+  4. Set PHASE_DIR = resolved path
+```
+
+---
+
+## Flag Processing
+
+| Flag | Effect |
+|------|--------|
+| `--auto-commit` | Override config: commit after each task completion |
+| `--method agent\|cli` | Override execution method (default: config.json.execution.method) |
+| `--dir <path>` | Use arbitrary directory instead of phase resolution (skip roadmap validation) |
+
+---
+
+## E1: Load Plan
+
+**Purpose:** Build or receive the execution queue.
+
+### From executionContext handoff (preferred)
+
+```
+If executionContext is available in memory:
+  planObject = executionContext.planObject
+  explorations = executionContext.explorations
+  clarifications = executionContext.clarifications
+  executionMethod = executionContext.executionMethod
+  Skip disk reload
+```
+
+### From disk (fallback / resume)
+
+```
+Read ${PHASE_DIR}/index.json
+Read ${PHASE_DIR}/plan.json
+
+executionMethod = --method flag || config.json.execution.method || "agent"
+```
+
+### Detect completed tasks (breakpoint resume)
+
+```
+completed_tasks = []
+For each task_id in index.json.plan.task_ids:
+  Read .task/${task_id}.json
+  If status == "completed":
+    completed_tasks.push(task_id)
+
+If completed_tasks.length > 0:
+  Log "Resuming: {completed_tasks.length}/{total} tasks already completed"
+  Filter completed tasks out of wave execution queue
+  Set current_wave = first wave with pending tasks
+```
+
+### Build wave execution queue
+
+```
+waves = plan.json.waves (or index.json.plan.waves)
+
+execution_queue = []
+For each wave in waves:
+  pending_tasks = wave.tasks.filter(t => !completed_tasks.includes(t))
+  If pending_tasks.length > 0:
+    execution_queue.push({ wave: wave.wave, tasks: pending_tasks })
+```
+
+### Output
+- In-memory: execution_queue, executionMethod, loaded task definitions
+
+---
+
+## E1.5: Load Project Specs
+
+```
+specs_content = maestro spec load --category execution
+```
+
+Pass specs_content to each executor agent in E2.
+
+---
+
+## E2: Wave Parallel Execution
+
+**Purpose:** Execute tasks wave by wave, parallel within each wave.
+
+### Execution Loop
+
+```
+For each wave in execution_queue (sequential):
+
+  Log "=== Wave {wave.wave}: {wave.tasks.length} tasks ==="
+
+  Update index.json:
+    execution.current_wave = wave.wave
+    execution.started_at = execution.started_at || now()
+
+  # State tracking (once, on first wave entry)
+  If first_wave_entry (current_wave == execution_queue[0].wave):
+    Read .workflow/state.json
+    If state.json.status != "executing":
+      state.json.status = "executing"
+      state.json.phases_summary.in_progress += 1
+      state.json.last_updated = now()
+      Write .workflow/state.json
+
+  For each task_id in wave.tasks (parallel):
+
+    # --- Per-task execution ---
+
+    # Note: parallel tasks will overwrite; last-write-wins is acceptable for an advisory field
+    0. Mark task active in state.json
+       Read .workflow/state.json
+       state.json.current_task_id = task_id
+       state.json.last_updated = now()
+       Write .workflow/state.json
+
+    1. Load task definition
+       Read .task/${task_id}.json (lazy loading)
+
+    2. Spawn workflow-executor agent (fresh 200k context)
+       Input:
+         - Task definition (.task/${task_id}.json)
+         - Phase context (index.json goal, success_criteria)
+         - Relevant summaries from prior waves (.summaries/ of deps)
+         - Execution method override (if --method cli)
+         - Project specs (specs_content from E1.5 — coding conventions, architecture constraints, quality rules)
+        - Phase context decisions (context.md — Locked/Free/Deferred classification)
+        - Phase analysis scores (analysis.md — 6-dimension evaluation)
+
+       Agent responsibilities:
+         a. Read task definition (read_first, files, action, convergence.criteria)
+         b. Implement the task (create/modify files per task.files)
+         c. Verify convergence.criteria pass
+         d. If verification fails: auto-fix (max 3 attempts)
+         e. If auto-fix fails: write checkpoint, mark task as "blocked"
+         f. Atomic commit (if auto-commit enabled):
+            git add <task files>
+            git commit -m "{type}({slug}): {task.title}"
+         g. Write .summaries/${task_id}-summary.md
+         h. Update .task/${task_id}.json:
+            status = "completed" | "blocked"
+
+    3. Collect result
+       result = { task_id, status, summary_path, commit_hash }
+
+    4. Clear current_task_id in state.json
+       Read .workflow/state.json
+       state.json.current_task_id = null
+       state.json.last_updated = now()
+       Write .workflow/state.json
+
+    # --- End per-task ---
+
+  Wait for all tasks in wave to complete
+
+  # Post-wave processing
+  For each result in wave_results:
+    Update index.json.execution:
+      tasks_completed += (completed count)
+      commits.push({ hash, task, message }) for each commit
+
+  If any task blocked:
+    Log "Wave {wave.wave}: {blocked_count} tasks blocked"
+    AskUserQuestion:
+      "Tasks blocked: {blocked_list}. Continue to next wave or stop?"
+      Options: [Continue (skip blocked), Stop and review]
+    If stop: break execution loop
+
+  Log "=== Wave {wave.wave} complete ==="
+```
+
+### Deviation Rule
+
+```
+Per task, max 3 auto-fix attempts:
+  Attempt 1: Re-read error, try alternative approach
+  Attempt 2: Simplify implementation
+  Attempt 3: Minimal viable implementation
+
+If all 3 fail:
+  Mark task as "blocked" with checkpoint data:
+    .task/${task_id}.json.meta.checkpoint = {
+      attempt: 3,
+      last_error: "...",
+      partial_files: [...]
+    }
+  Continue wave (other tasks unaffected)
+```
+
+---
+
+## E2.5: Post-Wave Validation
+
+**Purpose:** Validate execution integrity after all waves complete, before sync and reflection. Catches missing summaries, status inconsistencies, and tech stack constraint violations early.
+
+### Check 1: Summary Existence
+
+```
+For each task_id in index.json.plan.task_ids:
+  Read .task/${task_id}.json
+  If status == "completed":
+    If NOT file exists .summaries/${task_id}-summary.md:
+      violations.push({
+        type: "missing_summary",
+        severity: "warning",
+        task_id: task_id,
+        message: "Completed task ${task_id} has no summary file at .summaries/${task_id}-summary.md"
+      })
+```
+
+### Check 2: Task Status Consistency
+
+```
+For each task_id in index.json.plan.task_ids:
+  Read .task/${task_id}.json
+  task_status = task.status
+
+  # Verify completed tasks were actually in the execution results
+  If task_status == "completed":
+    If task_id NOT in wave_results (collected from E2):
+      violations.push({
+        type: "status_mismatch",
+        severity: "warning",
+        task_id: task_id,
+        message: "Task ${task_id} status is 'completed' but was not part of execution results"
+      })
+
+  # Verify tasks that ran successfully are marked completed
+  If task_id in wave_results AND wave_results[task_id].status == "completed":
+    If task_status != "completed":
+      violations.push({
+        type: "status_mismatch",
+        severity: "critical",
+        task_id: task_id,
+        message: "Task ${task_id} completed execution but .task/${task_id}.json status is '${task_status}'"
+      })
+```
+
+### Check 3: Tech Stack Constraint Compliance
+
+```
+# Load specs constraints from E1.5 specs_content (already loaded)
+tech_constraints = extract tech_stack constraints from specs_content
+  # e.g., allowed_languages, disallowed_imports, required_patterns
+
+If tech_constraints is not empty:
+  # Collect files modified during execution
+  modified_files = []
+  For each task_id in completed_tasks:
+    Read .task/${task_id}.json
+    For each file in task.files:
+      modified_files.push(file.path)
+
+  # Scan modified files for disallowed imports
+  For each file_path in modified_files:
+    If file exists ${file_path}:
+      file_content = Read ${file_path}
+      For each constraint in tech_constraints.disallowed_imports:
+        If file_content matches constraint.pattern:
+          violations.push({
+            type: "tech_stack_violation",
+            severity: "critical",
+            task_id: associated_task_id,
+            file: file_path,
+            message: "File ${file_path} contains disallowed import matching '${constraint.pattern}': ${constraint.reason}"
+          })
+```
+
+### Gate Logic
+
+```
+critical_violations = violations.filter(v => v.severity == "critical")
+warnings = violations.filter(v => v.severity == "warning")
+
+If warnings.length > 0:
+  Log "Post-wave validation: {warnings.length} warning(s)"
+  For each warning in warnings:
+    Log "  WARN: ${warning.message}"
+
+If critical_violations.length > 0:
+  Log "Post-wave validation: {critical_violations.length} critical violation(s)"
+  For each violation in critical_violations:
+    Log "  CRITICAL: ${violation.message}"
+
+  # Block execution
+  index.json.status = "blocked"
+  index.json.execution.blocked_reason = "Post-wave validation failed with critical violations"
+  index.json.execution.violations = violations
+  index.json.updated_at = now()
+  Write index.json
+
+  Abort: "Post-wave validation failed. Fix critical violations before proceeding."
+
+# No critical violations — continue to E3
+Log "Post-wave validation passed ({warnings.length} warnings, 0 critical)"
+```
+
+---
+
+## E3: Auto Sync
+
+**Purpose:** Update codebase documentation after execution.
+
+```
+If config.json.codebase.auto_sync_after_execute == true:
+  Trigger /workflow:sync logic:
+    1. Detect changed files (git diff from execution start)
+    2. Map changes to doc-index.json components/features
+    3. Update affected entries
+    4. Refresh tech-registry and feature-maps as needed
+Else:
+  Log "Auto-sync disabled. Run /workflow:sync manually if needed."
+```
+
+---
+
+## E4: Reflection (Optional)
+
+**Purpose:** Record strategy observations for future iterations.
+
+```
+If config.json.workflow.reflection == true:
+  Review execution results:
+    - Which tasks completed smoothly?
+    - Which required auto-fix attempts?
+    - Any blocked tasks?
+    - Patterns observed?
+
+  Append to ${PHASE_DIR}/reflection-log.md:
+    ## Reflection - Wave Execution {timestamp}
+    - Strategy adjustments: [...]
+    - Patterns noted: [...]
+    - Blocked tasks: [...]
+
+  Update index.json.reflection:
+    rounds += 1
+    strategy_adjustments.push(new adjustments)
+```
+
+---
+
+## Final State Update
+
+```
+all_completed = index.json.execution.tasks_completed == index.json.execution.tasks_total
+
+If all_completed:
+  index.json.status = "verifying"  (ready for /workflow:verify)
+  index.json.execution.completed_at = now()
+  Log "All tasks completed. Run /workflow:verify to validate results."
+Else:
+  index.json.status = "executing"  (partial, can resume)
+  Log "{completed}/{total} tasks completed. Re-run /workflow:execute to resume."
+
+index.json.updated_at = now()
+
+# Update project state.json (skip in SCRATCH_MODE)
+If NOT SCRATCH_MODE:
+  Read .workflow/state.json
+  If all_completed:
+    state.json.status = "verifying"
+  state.json.current_task_id = null  # safety clear: no task is active once the wave loop exits
+  state.json.last_updated = now()
+  Write .workflow/state.json
+```
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Phase directory not found | Abort: "Phase {phase} not found." |
+| No plan exists | Abort: "No plan found. Run /workflow:plan first." |
+| Task file missing | Skip task, log error, continue wave |
+| Agent spawn fails | Retry once, then mark task as "blocked" |
+| Git commit fails | Log warning, continue (task still marked completed) |
+| All tasks in wave blocked | Stop execution, report blocked wave |
+
+---
+
+## Breakpoint Resume
+
+The execute workflow is fully resumable:
+
+```
+State tracking in index.json.execution:
+  tasks_completed: N     # Count of finished tasks
+  current_wave: W        # Last active wave
+  commits: [...]         # All commits made
+
+Re-running /workflow:execute <phase>:
+  1. Reads index.json.execution.tasks_completed
+  2. Checks each .task/TASK-*.json status
+  3. Builds queue of remaining tasks
+  4. Continues from next pending wave
+  5. No duplicate execution of completed tasks
+```