Merge Resolver

Merge Resolver

Resolve merge conflicts by analyzing git history and commit intent.

Quick Start

# Resolve conflicts for a specific PR
python3 .claude/skills/merge-resolver/scripts/resolve_pr_conflicts.py \
    --pr-number 123 --branch-name "fix/my-feature" --target-branch "main"

# Dry-run mode (no side effects)
python3 .claude/skills/merge-resolver/scripts/resolve_pr_conflicts.py \
    --pr-number 123 --branch-name "fix/test" --dry-run

Triggers

Process

Phase 1: Context Gathering

Phase 2: Analysis and Resolution

Phase 3: Validation (BLOCKING)

Intent Classification

Classify each side's changes to determine resolution priority.

Decision Framework

Session File Rules

CRITICAL: Session files from main are immutable audit records.

See references/strategies.md for the full session file resolution workflow.

Auto-Resolvable Patterns

The script auto-resolves these by accepting the target branch version.

Scripts

resolve_pr_conflicts.py

Resolves PR merge conflicts with auto-resolution for known file patterns.

python3 .claude/skills/merge-resolver/scripts/resolve_pr_conflicts.py \
    --pr-number <number> --branch-name <name> [--target-branch <branch>] \
    [--worktree-base-path <path>] [--dry-run]

Exit codes:

When running with --dry-run, exit code 0 indicates that conflicts were fully auto-resolvable and the changes would have been pushed, but no changes were made because of dry-run mode.

Output format (JSON):

{
  "success": true,
  "message": "Successfully resolved conflicts for PR #123",
  "files_resolved": [".agents/HANDOFF.md"],
  "files_blocked": []
}

Security: Branch name validation prevents command injection. Worktree path validation prevents path traversal.

Anti-Patterns

Verification

Success Criteria

Completion Checklist

• All conflicted files staged (git add)
• No UU status in git status --porcelain
• Session log exists at .agents/sessions/
• Session end checklist completed
• Serena memory updated
• Merge commit created
• Branch pushed to origin

Extension Points

Custom Auto-Resolvable Patterns

Add patterns to AUTO_RESOLVABLE_PATTERNS in resolve_pr_conflicts.py.

Custom Resolution Strategies

Add entries in references/strategies.md for domain-specific conflicts.

CI/CD Integration

- name: Resolve conflicts
  env:
    PR_NUMBER: ${{ github.event.pull_request.number }}
    HEAD_REF: ${{ github.head_ref }}
    BASE_REF: ${{ github.base_ref }}
  run: |
    python3 .claude/skills/merge-resolver/scripts/resolve_pr_conflicts.py \
      --pr-number "$PR_NUMBER" \
      --branch-name "$HEAD_REF" \
      --target-branch "$BASE_REF"

Related

• Security: Branch name and path validation prevent injection and traversal
• SESSION-PROTOCOL.md: Session end requirements (blocking gate)
• strategies.md: Detailed resolution patterns for edge cases
• merge-resolver-session-protocol-gap: Memory documenting root cause analysis

Why This Matters

Session protocol validation is a CI blocking gate. Pushing without completing session requirements causes CI failures with "MUST requirement(s) not met" errors.

Validation Commands

# 1. Ensure session log exists
SESSION_LOG=$(ls -t -- .agents/sessions/*.json 2>/dev/null | head -1)
if [ -z "$SESSION_LOG" ]; then
    echo "ERROR: No session log found."
    exit 1
fi

# 2. Run session protocol validator
python3 scripts/validate_session_json.py "$SESSION_LOG"

Session End Checklist (REQUIRED)

Common Failures

Converted and distributed by TomeVault — claim your Tome and manage your conversions.