---
name: "Mergemaster should resolve merge conflicts instead of leaving conflict markers on master"
---

# Story 119: Mergemaster should resolve merge conflicts instead of leaving conflict markers on master

## Problem

When mergemaster squash-merges a feature branch that conflicts with current master, conflict markers end up committed to master. This breaks the frontend build and requires manual intervention.

## Root Cause

There is a race condition between `run_squash_merge` and the file watcher:

1. `git merge --squash` runs on the main working tree
2. The squash brings `.story_kit/work/` files from the feature branch (e.g. story moved to `2_current`)
3. The watcher detects these file changes and auto-commits — including any conflict markers in frontend/server files
4. `run_squash_merge` checks the exit status and aborts, but the watcher already committed the broken state

The merge tool itself does the right thing (aborts on conflicts at `agents.rs:2157-2171`), but the watcher races it.

## Proposed Solution: Merge-Queue Branch

1. Create a `merge-queue` branch that always tracks master
2. Mergemaster performs squash-merges on `merge-queue` instead of master
3. If the merge is clean and gates pass, fast-forward master to merge-queue
4. If conflicts occur, the watcher does not care (it only watches the main worktree)
5. Mergemaster can resolve conflicts on the merge-queue branch without affecting master
6. If resolution fails, reset merge-queue to master and report the conflict

## Also Required: Pause Watcher During Merges

Add a lock/pause mechanism to the watcher that `merge_agent_work` acquires before running `git merge --squash`. The watcher skips auto-commits while the lock is held. This is a belt-and-suspenders defense — even with the merge-queue branch, we want the watcher to not interfere with merge operations.

**Implement both approaches** — the merge-queue branch for isolation, and the watcher pause as a safety net.

## Also Update Mergemaster Prompt

- Remove the instruction to NOT resolve conflicts
- Instead instruct mergemaster to resolve simple conflicts (e.g. both branches adding code at same location)
- For complex conflicts (semantic changes to the same logic), still report to human

## Key Files

- `server/src/agents.rs` — `run_squash_merge` (lines 2136-2199), `merge_agent_work` (lines 992-1066)
- `server/src/http/mcp.rs` — `tool_merge_agent_work` (lines 1392-1425)
- `server/src/io/watcher.rs` — file watcher that races with the merge
- `.story_kit/project.toml` — mergemaster prompt (lines 210-232)

## Acceptance Criteria

- [ ] Merge conflicts never leave conflict markers on master
- [ ] Mergemaster resolves simple additive conflicts automatically
- [ ] Complex conflicts are reported clearly without breaking master
- [ ] Frontend build stays clean throughout the merge process
- [ ] Existing tests pass
