From 200e0047816f43a2ddd0622847e4bd60802638ce Mon Sep 17 00:00:00 2001
From: Lex Christopherson <lex@glittercowboy.com>
Date: Sat, 17 Jan 2026 02:03:29 -0600
Subject: [PATCH] feat(execute-phase): add --gaps-only flag for gap closure
 execution

After verify-work diagnoses issues and creates fix plans, the next
command now explicitly signals intent with --gaps-only. This eliminates
redundant state discovery where execute-phase had to figure out why it
was being asked to run on an already-complete phase.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 agents/gsd-planner.md                    |  2 +-
 commands/gsd/execute-phase.md            |  6 +++++-
 commands/gsd/verify-work.md              |  2 +-
 get-shit-done/workflows/execute-phase.md | 14 ++++++++++----
 get-shit-done/workflows/verify-work.md   |  4 ++--
 5 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/agents/gsd-planner.md b/agents/gsd-planner.md
index 09425e3e6..fdf9af177 100644
--- a/agents/gsd-planner.md
+++ b/agents/gsd-planner.md
@@ -1296,7 +1296,7 @@ Execute: `/gsd:execute-phase {phase}`
 
 ### Next Steps
 
-Execute: `/gsd:execute-phase {phase}`
+Execute: `/gsd:execute-phase {phase} --gaps-only`
 ```
 
 ## Revision Complete
diff --git a/commands/gsd/execute-phase.md b/commands/gsd/execute-phase.md
index 42b2d22f7..9b8c5a0e0 100644
--- a/commands/gsd/execute-phase.md
+++ b/commands/gsd/execute-phase.md
@@ -1,7 +1,7 @@
 ---
 name: gsd:execute-phase
 description: Execute all plans in a phase with wave-based parallelization
-argument-hint: "<phase-number>"
+argument-hint: "<phase-number> [--gaps-only]"
 allowed-tools:
   - Read
   - Write
@@ -30,6 +30,9 @@ Context budget: ~15% orchestrator, 100% fresh per subagent.
 <context>
 Phase: $ARGUMENTS
 
+**Flags:**
+- `--gaps-only` — Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after verify-work creates fix plans.
+
 @.planning/ROADMAP.md
 @.planning/STATE.md
 </context>
@@ -43,6 +46,7 @@ Phase: $ARGUMENTS
 2. **Discover plans**
    - List all *-PLAN.md files in phase directory
    - Check which have *-SUMMARY.md (already complete)
+   - If `--gaps-only`: filter to only plans with `gap_closure: true`
    - Build list of incomplete plans
 
 3. **Group by wave**
diff --git a/commands/gsd/verify-work.md b/commands/gsd/verify-work.md
index 8cd4f5c30..4ae63bc85 100644
--- a/commands/gsd/verify-work.md
+++ b/commands/gsd/verify-work.md
@@ -156,7 +156,7 @@ Fix plans verified ✓
 
 **Execute fix plans** — run diagnosed fixes
 
-/gsd:execute-phase {Z}
+/gsd:execute-phase {Z} --gaps-only
 
 <sub>/clear first → fresh context window</sub>
 
diff --git a/get-shit-done/workflows/execute-phase.md b/get-shit-done/workflows/execute-phase.md
index a4eb804bb..22f99ea57 100644
--- a/get-shit-done/workflows/execute-phase.md
+++ b/get-shit-done/workflows/execute-phase.md
@@ -71,15 +71,21 @@ ls -1 "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null | sort
 For each plan, read frontmatter to extract:
 - `wave: N` - Execution wave (pre-computed)
 - `autonomous: true/false` - Whether plan has checkpoints
+- `gap_closure: true/false` - Whether plan closes gaps from verification/UAT
 
 Build plan inventory:
 - Plan path
 - Plan ID (e.g., "03-01")
 - Wave number
 - Autonomous flag
+- Gap closure flag
 - Completion status (SUMMARY exists = complete)
 
-Skip completed plans. If all complete, report "Phase already executed" and exit.
+**Filtering:**
+- Skip completed plans (have SUMMARY.md)
+- If `--gaps-only` flag: also skip plans where `gap_closure` is not `true`
+
+If all plans filtered out, report "No matching incomplete plans" and exit.
 </step>
 
 <step name="group_by_wave">
@@ -433,9 +439,9 @@ Present gaps and offer next command:
 
 User runs `/gsd:plan-phase {X} --gaps` which:
 1. Reads VERIFICATION.md gaps
-2. Creates additional plans (04, 05, etc.) to close gaps
-3. User then runs `/gsd:execute-phase {X}` again
-4. Execute-phase runs incomplete plans (04-05)
+2. Creates additional plans (04, 05, etc.) with `gap_closure: true` to close gaps
+3. User then runs `/gsd:execute-phase {X} --gaps-only`
+4. Execute-phase runs only gap closure plans (04-05)
 5. Verifier runs again after new plans complete
 
 User stays in control at each decision point.
diff --git a/get-shit-done/workflows/verify-work.md b/get-shit-done/workflows/verify-work.md
index 56c658f7d..f22a439ca 100644
--- a/get-shit-done/workflows/verify-work.md
+++ b/get-shit-done/workflows/verify-work.md
@@ -505,7 +505,7 @@ Plans verified and ready for execution.
 
 **Execute fixes** — run fix plans
 
-`/clear` then `/gsd:execute-phase {phase}`
+`/clear` then `/gsd:execute-phase {phase} --gaps-only`
 
 ───────────────────────────────────────────────────────────────
 ```
@@ -559,5 +559,5 @@ Default to **major** if unclear. User can correct if needed.
 - [ ] If issues: gsd-planner creates fix plans (gap_closure mode)
 - [ ] If issues: gsd-plan-checker verifies fix plans
 - [ ] If issues: revision loop until plans pass (max 3 iterations)
-- [ ] Ready for `/gsd:execute-phase` when complete
+- [ ] Ready for `/gsd:execute-phase --gaps-only` when complete
 </success_criteria>