---
allowed-tools: Bash, Read, Write
---

# Epic Merge

Merge completed epic from worktree back to main branch.

## Usage

/pm:epic-merge


## Quick Check

1. **Verify worktree exists:**

   ```bash
   git worktree list | grep "epic-$ARGUMENTS" || echo "❌ No worktree for epic: $ARGUMENTS"

Check for active agents: Read .claude/epics/$ARGUMENTS/execution-status.md If active agents exist: "⚠️ Active agents detected. Stop them first with: /pm:epic-stop $ARGUMENTS"

Instructions

1. Pre-Merge Validation

Navigate to worktree and check status:

cd ../epic-$ARGUMENTS

# Check for uncommitted changes
if [[ $(git status --porcelain) ]]; then
  echo "⚠️ Uncommitted changes in worktree:"
  git status --short
  echo "Commit or stash changes before merging"
  exit 1
fi

# Check branch status
git fetch origin
git status -sb

2. Run Safety Gate (Required)

Before merging, run the safety gate to ensure all checks pass:

cd ../epic-$ARGUMENTS

echo "🔒 Running Safety Gate..."
echo ""

# The safety gate runs:
# 1. Tests with coverage (80% threshold)
# 2. Linting (ruff + mypy)
# 3. Security scan (dependencies, secrets, SAST)
# 4. Code review (blocking issues check)

Execute the safety gate command:

echo "🔒 Running Safety Gate..."
if ! /safety-gate; then
  echo ""
  echo "❌ Safety Gate Failed"
  echo ""
  echo "The safety gate detected issues that must be addressed before merging."
  echo ""
  echo "To fix these issues:"
  echo "1. Run /safety-gate --fix to attempt auto-remediation"
  echo "2. Or manually fix the issues and re-run /pm:epic-merge"
  echo ""
  echo "Merge blocked until all safety checks pass."
  exit 1
fi

echo "✅ Safety gate passed - proceeding with merge"

If safety gate passes, continue to the next step.

3. Update Epic Documentation

Get current datetime: date -u +"%Y-%m-%dT%H:%M:%SZ"

Update .claude/epics/$ARGUMENTS/epic.md:

Set status to "completed"
Update completion date
Add final summary

4. Push Final Changes

Ensure all work is pushed before merging:

cd ../epic-$ARGUMENTS
git push origin epic/$ARGUMENTS

5. Return to Main Repo and Merge

# Get the main repo path (parent of worktree)
main_repo=$(git -C ../epic-$ARGUMENTS rev-parse --git-common-dir | xargs dirname)
cd "$main_repo"

# Ensure main is up to date
git checkout main
git pull origin main

# Attempt merge
echo "Merging epic/$ARGUMENTS to main..."
git merge epic/$ARGUMENTS --no-ff -m "Merge epic: $ARGUMENTS

Completed features:
$(cd .claude/epics/$ARGUMENTS && ls *.md 2>/dev/null | grep -E '^[0-9]+' | while read f; do
  echo "- $(grep '^name:' $f | cut -d: -f2)"
done)

Closes epic #$(grep 'github:' .claude/epics/$ARGUMENTS/epic.md | grep -oE '#[0-9]+')"

6. Handle Merge Conflicts

If merge fails with conflicts:

# Check conflict status
git status

echo "
❌ Merge conflicts detected!

Conflicts in:
$(git diff --name-only --diff-filter=U)

Options:
1. Resolve manually:
   - Edit conflicted files
   - git add {files}
   - git commit

2. Abort merge:
   git merge --abort

3. Get help:
   /pm:epic-resolve $ARGUMENTS

Worktree preserved at: ../epic-$ARGUMENTS
"
exit 1

7. Post-Merge Cleanup

If merge succeeds:

# Push to remote
git push origin main

# Remove worktree
git worktree remove ../epic-$ARGUMENTS
echo "✅ Worktree removed: ../epic-$ARGUMENTS"

# Delete branch locally
git branch -d epic/$ARGUMENTS

# Delete branch remotely
git push origin --delete epic/$ARGUMENTS 2>/dev/null || true

# Prune stale worktree references
git worktree prune

# Archive epic locally
mkdir -p .claude/epics/archived/
mv .claude/epics/$ARGUMENTS .claude/epics/archived/
echo "✅ Epic archived: .claude/epics/archived/$ARGUMENTS"

8. Update GitHub Issues

Close related issues:

# Get issue numbers from epic
epic_issue=$(grep 'github:' .claude/epics/archived/$ARGUMENTS/epic.md | grep -oE '[0-9]+$')

# Close epic issue
gh issue close $epic_issue -c "Epic completed and merged to main"

# Close task issues
for task_file in .claude/epics/archived/$ARGUMENTS/[0-9]*.md; do
  issue_num=$(grep 'github:' $task_file | grep -oE '[0-9]+$')
  if [ ! -z "$issue_num" ]; then
    gh issue close $issue_num -c "Completed in epic merge"
  fi
done

9. Final Output

✅ Epic Merged Successfully: $ARGUMENTS

Summary:
  Branch: epic/$ARGUMENTS → main
  Commits merged: {count}
  Files changed: {count}
  Issues closed: {count}

Cleanup completed:
  ✓ Worktree removed
  ✓ Branch deleted (local and remote)
  ✓ Epic archived
  ✓ GitHub issues closed

Next steps:
  - Deploy changes if needed
  - Start new epic: /pm:prd-new {feature}
  - View completed work: git log --oneline -20

Conflict Resolution Help

If conflicts need resolution:

The epic branch has conflicts with main.

This typically happens when:
- Main has changed since epic started
- Multiple epics modified same files
- Dependencies were updated

To resolve:
1. Open conflicted files
2. Look for <<<<<<< markers
3. Choose correct version or combine
4. Remove conflict markers
5. git add {resolved files}
6. git commit
7. git push

Or abort and try later:
  git merge --abort

Important Notes

Always check for uncommitted changes first
Run tests before merging when possible
Use --no-ff to preserve epic history
Archive epic data instead of deleting
Close GitHub issues to maintain sync
Follow /rules/worktree-operations.md for cleanup