Post-phase-merge: rebase active phase branches onto updated milestone

[LeVarez]

Parent: #54

Problem

After a phase completes and its PR is merged into the milestone branch (user action via GitHub), other active phase branches remain based on the old milestone state. For example, after phase 01's PR merges into milestone/v1.1, feature/v1.1-02-docs-site still points to a69ce5a instead of being rebased onto the merge commit a2b53ba.

The workflow doesn't:

1. Tell the user to merge the PR before continuing
2. Pull the updated milestone branch before starting the next phase
3. Rebase other active phase branches onto the updated milestone

Changes (execute-phase.md, zone 2G)

Fix 1 — Update offer_next Route A messaging

After showing the next phase command, add merge instructions:

## Before continuing

1. Merge the phase PR on GitHub:
   gh pr merge {PR_NUM} --merge
2. Pull the updated milestone branch:
   git checkout milestone/{MILESTONE} && git pull
3. Then proceed to the next phase

Fix 2 — Milestone pull + active branch rebase at step 0.5

Before resolving the worktree for the next phase:

# Pull latest milestone
MILESTONE_BRANCH="milestone/${MILESTONE}"
git fetch origin "$MILESTONE_BRANCH"
git checkout "$MILESTONE_BRANCH" && git pull --ff-only origin "$MILESTONE_BRANCH" || true

# Rebase all other active phase branches
ACTIVE_BRANCHES=$(grep "| ${MILESTONE}/" .planning/STATE.md | grep -o 'feature/[^ |]*' | grep -v "$DESIGNATED_BRANCH")
for BRANCH in $ACTIVE_BRANCHES; do
  if git rev-parse --verify "$BRANCH" 2>/dev/null; then
    REBASE_RESULT=$(git checkout "$BRANCH" && git rebase "$MILESTONE_BRANCH" 2>&1 || echo "REBASE_FAILED")
    if echo "$REBASE_RESULT" | grep -q "CONFLICT\|REBASE_FAILED"; then
      git rebase --abort
      echo "⚠ Could not rebase $BRANCH — rebase manually"
    else
      git push origin "$BRANCH" --force-with-lease || true
      echo "◆ Rebased $BRANCH onto $MILESTONE_BRANCH"
    fi
  fi
done

Fix 3 — Same pull + rebase in plan-phase step 0

Before creating the next phase's plan branch.

Files

• .claude/commands/vit/execute-phase.md (zone 2G)
• .claude/commands/vit/plan-phase.md (step 0)
• .claude/vit/workflows/execute-phase.md (offer_next)

[LeVarez]

Implementation note: force-with-lease safety

The rebase uses --force-with-lease (not --force) when pushing rebased branches. This ensures:

• If another engineer pushed to the branch since our last fetch, the push is rejected rather than silently overwriting their work
• The abort-on-conflict path prevents leaving branches in a broken rebase state

When this runs

This rebase should happen at the entry point of execute-phase and plan-phase — before any work begins on the next phase. It's a "bring everything up to date" step.

Worktree consideration

If phase branches have active worktrees, git checkout may fail. The rebase loop should handle this:

# Check if branch has an active worktree
WORKTREE=$(git worktree list --porcelain | grep -B2 "branch refs/heads/$BRANCH" | grep "^worktree " | sed 's/worktree //')
if [ -n "$WORKTREE" ]; then
  # Rebase in the worktree instead
  cd "$WORKTREE" && git pull --rebase origin "$MILESTONE_BRANCH" 2>/dev/null
  cd "$WORKTREE" && git push origin "$BRANCH" --force-with-lease 2>/dev/null || true
fi