merge-resolver

name: merge-resolver version: 2.2.0 description: Resolve merge conflicts by analyzing git history and commit intent. Handles PR conflicts, branch conflicts, and session file conflicts with automated resolution for known patterns. Use when you say "resolve merge conflicts", "fix conflicts on this branch", "PR has conflicts with main", "can't merge due to conflicts", or "resolve PR conflicts". Do NOT use for rebasing, cherry-picking, or complex history rewrites (use git-advanced-workflows). license: MIT model: claude-opus-4-6 metadata: domains: - git - github - merge-conflicts - pr-maintenance type: workflow complexity: advanced

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 0: Execution Capability Precondition (BLOCKING)

Run this self-check FIRST, before any context gathering, analysis, or plan. Conflict resolution requires shell execution: worktree creation, git merge, staging, commit, and git push. Without those tools you can only describe steps, never resolve anything.

If shell execution is unavailable, do NOT produce a step-by-step resolution plan. A plan reads as completed work and is the exact failure this precondition prevents (issue #2646). Return BLOCKED and route execution back to the orchestrator.

Completion rule (applies to every execution phase below): mark a phase complete ONLY when a tool result in this run proves it ran. A plan is not a completion. Never report "create worktree", "merge", "push", or "run gates" as complete from instructions alone.

Phase 1: Context Gathering

Phase 2: Analysis and Resolution

Phase 3: Validation (BLOCKING)

Intent Classification

Classify each side's changes to determine resolution priority.

Priority is a strict priority hierarchy: Security (1) > Bugfix (2) > Feature/Refactor (3) > Style (4). Intent priority is the PRIMARY sort key when two sides conflict. A Security change is NEVER dropped: if it cannot be cleanly combined with the other side, Security wins and the lower-priority change is reapplied around it. Recency and test coverage are tiebreakers ONLY between two changes in the same priority tier; they never let a lower-tier change beat a higher-tier one.

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.

Plugin Manifests (Special Rule)

*/.claude-plugin/plugin.json is NOT accept-theirs. Accepting main's copy makes head version equal to the merge-base and re-trips the plugin version-bump gate with not-bumped (issue #2543). When the two sides differ only in version, the script resolves to one patch bump above the higher side (for example ours 0.5.168 vs theirs 0.5.169 resolves to 0.5.170). Any other field difference, or a prerelease/build-metadata version, blocks auto-resolution and requires manual handling.

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.

verify_no_conflict_markers.py

Verifies that resolution is complete: no still-unmerged (UU) files and no leftover conflict markers in any in-flight change. Replaces the broad git grep -n '<<<<<<<' -- check, which false-fails on intentional fenced examples in committed docs and Serena memories (issue #2424).

python3 .claude/skills/merge-resolver/scripts/verify_no_conflict_markers.py [--cwd PATH] [--json]

Uses git diff HEAD --check (catches leftover markers in working tree + index) plus git diff --name-only --diff-filter=U (catches files still unmerged). Both inspect in-flight changes only, so committed historical content is intentionally ignored.

Exit codes:

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

# 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"