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 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.

Rename, never content-merge. An add/add conflict on an append-only evidence artifact (session logs .agents/sessions/*, QA reports .agents/qa/*, retrospectives .agents/retrospective/*) means two branches wrote different records to the same filename. Keep both files: accept the base branch version at the original name, rename the head branch version with a distinguishing suffix (keep the session number, append an issue or topic slug), and update any index or report that references the renamed file. Never merge the two contents into one file. PR #4856 proved the anti-pattern: merging both sessions' prose into one file would have destroyed two accurate records to produce one false one (.agents/retrospective/2026-08-10-pr-4856-session-log-collision.md). Issue #4751 tracks preventing the collision at allocation time.

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.

Add/add caveat: accept-theirs alone is wrong for an add/add conflict on an append-only evidence artifact (.agents/sessions/*, .agents/qa/*, .agents/retrospective/*), because it silently discards the head branch's own record. After accepting theirs, restore the head branch version under a renamed path per the Session File Rules above. The script does not do the rename half; handle it manually.

Plugin Manifests (Special Rule)

*/.claude-plugin/plugin.json is NOT accept-theirs. When the two sides differ only in version, the script resolves them without manual handling:

• Either side omits version: the merged manifest carries none. ADR-092 deleted the field from all three manifests, and the version-field gate (validate_plugin_version_bump.py) fails when one carries it. This is the shape every branch opened before ADR-092 hits when it merges a fixed main.
• Both sides carry plain semver: one patch bump above the higher side (for example ours 0.5.168 vs theirs 0.5.169 resolves to 0.5.170). Retained only for branches that predate the deletion on both sides; the merged manifest then still carries a field the gate rejects, so delete it before pushing.

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/governance/PROJECT-CONSTRAINTS.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 --cached --check MERGE_HEAD when a merge is in progress (MERGE_HEAD present) to avoid false positives from whitespace already in the incoming branch (issue #4058). Falls back to git diff HEAD --check outside merge state. Both forms use git diff --name-only --diff-filter=U to catch still-unmerged files.

Exit codes:

Anti-Patterns

Verification

Success Criteria

Completion Checklist

• All conflicted files staged (git add)
• No UU status in git status --porcelain
• Any conflicted session logs preserved as separate valid records
• Per-issue handoff updated when work remains
• 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
• .claude/rules/session-logs.md: Optional log and continuity requirements
• strategies.md: Detailed resolution patterns for edge cases
• merge-resolver-session-protocol-gap: Memory documenting root cause analysis

Why This Matters

Session logs are historical records once created. A malformed staged or explicitly supplied log still fails validation.

Validation Commands

# Validate an existing log only when one is part of the merge.
uv run python scripts/validate_session_json.py ".agents/sessions/<log>.json"

Session End Checklist

Common Failures