VIT Workflow: PR Review Gates, Push Reliability & Git Integration Fixes

[LeVarez]

Context

After executing v1.1 phase 01, 7 issues surfaced across the execute-phase, verify-work, and plan-phase workflows. An additional issue was identified during milestone completion. These fall into 7 fix areas tracked as sub-issues below.

Sub-issues

• Configurable PR review gates (plan→phase and phase→milestone) #55 — Configurable PR review gates (plan→phase and phase→milestone)
• Fix plan branch push/merge reliability in execute-phase #56 — Fix plan branch push/merge reliability in execute-phase
• Fix verification 'never complete' and offer_next routing on gaps_found #57 — Fix verification "never complete" and offer_next routing on gaps_found
• Post-phase-merge: rebase active phase branches onto updated milestone #58 — Post-phase-merge: rebase active phase branches onto updated milestone
• Gap closure plans missing GitHub integration (branches, sub-issues, STATE.md) #59 — Gap closure plans missing GitHub integration (branches, sub-issues, STATE.md)
• Fix branch-to-issue linking fallback across 6 commands #60 — Fix branch-to-issue linking fallback across 6 commands
• Complete-milestone should squash milestone commits and clean git tree #71 — Complete-milestone should squash commits and clean git tree

Root Cause Analysis: Plan branches not pushed (v1.1 phase 01)

Evidence:

• Plan branches 01-01, 01-02, 01-03 on origin at a69ce5a (base commit, never updated after execution)
• Plan branch 01-04 on origin at 3cf67e6 (has work, was pushed)
• Local plan branches form a linear chain (sequential execution in one worktree)
• Phase branch still at 129ae08 (executor work never merged back)
• STATE.md on phase branch (commit 129ae08) DID have plan branches populated correctly

Bugs identified:

1. Per-plan push/merge loop (lines 395-448) runs as a BATCH after all executors in a wave. If interrupted, no plans get pushed or merged.
2. Step 10.5 git push origin HEAD only pushes whichever branch HEAD is on (the last plan branch). Other plan branches are left behind.
3. No push happens on early-exit paths (offer_next routes A/B/C).
4. Verifier runs on the phase branch which has no executor work — reports "never complete" / gaps_found.
5. offer_next not reached on gaps_found — user gets no actionable next-steps guidance.
6. Gap closure plans (from verify-work) don't get branches, sub-issues, or STATE.md updates.
7. After phase PR merge into milestone, other active phase branches aren't rebased.
8. Milestone completion leaves messy git tree with 50+ commits instead of squashing to a single commit.

Files to Modify (14 total)

1. .planning/config.json — add 2 config keys
2. .claude/commands/vit/execute-phase.md — main logic (7 zones: 2A-2G)
3. .claude/vit/workflows/execute-phase.md — push step + review gate notes
4. .claude/commands/vit/settings.md — 2 new toggles
5. .claude/vit/references/planning-config.md — document new config
6. .claude/vit/templates/state.md — new PR column values
7. .claude/commands/vit/verify-work.md — add GitHub integration after gap planner
8. .claude/commands/vit/complete-milestone.md — squash + clean git tree
9. .claude/commands/vit/new-project.md — fix branch linking fallback
10. .claude/commands/vit/new-milestone.md — fix branch linking fallback
11. .claude/commands/vit/plan-phase.md — fix branch linking fallback
12. .claude/commands/vit/add-phase.md — fix branch linking fallback
13. .claude/commands/vit/insert-phase.md — fix branch linking fallback
14. .claude/commands/vit/quick.md — fix branch linking fallback

Verification Checklist

• plan_pr_review: false, phase_pr_review: false → no regression
• plan_pr_review: true → stops after wave with PR links, no auto-merge
• Merge plan PRs on GitHub → re-run → detects merged PRs, continues
• phase_pr_review: true → stops with phase PR link after verification
• Merge phase PR → re-run → completes finalization
• /vit:settings shows new toggles, updates config.json
• Phase branch pushed to origin after completion in ALL paths
• Branches appear in GitHub issue Development panel (both gh issue develop and fallback)
• /vit:verify-work → gap plans get sub-issues, branches, STATE.md updates
• /vit:execute-phase --gaps-only → gap plans use dedicated branches, push, merge
• /vit:complete-milestone → git history squashed to single commit, branches cleaned