# Resolve Merge Conflicts (Cloud Agent — Safe for PR Branches)

You are a cloud coding agent resolving merge conflicts on a pull-request branch.
Your job is to bring the PR branch up to date with the base branch by **merging**
(not rebasing), resolving every conflict, and pushing a normal commit.

> **⚠️ PROHIBITED operations** — do NOT use any of the following, ever:
>
> - `git rebase` (any form)
> - `git commit --amend`
> - `git push --force` or `git push --force-with-lease`
> - Any command that rewrites or resets branch history
>
> The PR branch must only have new commits added to it.  The cloud agent
> works by creating a normal merge/resolution commit; force-pushing is not
> available and would break the PR.

---

## Step 1 — Sync with the base branch (merge, not rebase)

```bash
git fetch origin
git merge --no-edit origin/<base_branch>
```

Replace `<base_branch>` with the PR's actual base branch name before running the merge command.

If the merge succeeds with no conflicts, go straight to Step 4 (verify, then push).

---

## Step 2 — Identify conflicted files

```bash
git diff --name-only --diff-filter=U
git status --short --unmerged
```

Work through each file one at a time.

---

## Step 3 — Resolve each conflicted file

Use the file-type-specific strategies below.  In each case:

1. Read all three versions:

   ```bash
   git show :1:path/to/file   # common ancestor
   git show :2:path/to/file   # ours (PR branch)
   git show :3:path/to/file   # theirs (base branch)
   ```

2. Apply the appropriate strategy.
3. Stage the resolved file: `git add path/to/file`

### JSON files (e.g. `package.json`, `cspell.json`)

- Merge all unique entries from both versions.
- Re-sort arrays that require alphabetical order (e.g. `cspell.json` words).
- Remove duplicate keys/values.
- Validate syntax: `python -m json.tool path/to/file.json >/dev/null`

### Markdown / documentation files

- Identify which sections were added or changed in each version.
- Merge content preserving document flow and section order.
- Renumber any numbered lists or sections.
- Verify internal links still resolve.

### Code files (`.py`, `.ts`, `.cs`, etc.)

- Determine whether the two sets of changes are independent (include both) or
  overlapping (combine logic to satisfy both intents).
- Do not duplicate logic.
- Preserve imports and dependencies for all merged code.

### YAML / config / Terraform files

- Merge settings additively where possible.
- For conflicting values on the same key, determine the correct value from
  context (PR description, commit history, linked issues).
- Preserve indentation and formatting.

### Navigation tables / index lists

- Collect all unique entries from both versions.
- Re-sort and re-align to match the file's existing convention.

### Binary files

Choose the correct version:

```bash
git checkout --ours   path/to/binary   # keep PR-branch version
git checkout --theirs path/to/binary   # keep base-branch version
git add path/to/binary
```

---

## Step 4 — Verify

Before committing, confirm:

```bash
# No conflict markers remain
grep -rn -e '^<<<<<<< ' -e '^=======$' -e '^>>>>>>> ' .

# All conflicts staged
git diff --name-only --diff-filter=U   # should print nothing

# Review staged changes
git diff --cached
```

---

## Step 5 — Commit and push (normal merge commit)

```bash
# Complete the merge commit (MERGE_HEAD must still exist at this point)
git commit --no-edit          # uses the auto-generated merge commit message
# or, if you want a custom message:
# git commit -m "Merge origin/<base_branch> to resolve conflicts"

# Push normally — NO force flags
git push
```

---

## Step 6 — Optional: run project checks

If `scripts/run-pr-checks.sh` exists in this repository, run it after pushing
to verify the resolved state passes the project's own quality gates:

```bash
bash scripts/run-pr-checks.sh 2>/dev/null || true
```

Failures here are informational — the push has already succeeded and the CI
pipeline will run the authoritative checks.
