beads-merge: Add AGENTS.md and jj configuration guide

Co-authored-by: neongreen <1523306+neongreen@users.noreply.github.com>

Author: Copilot

AGENTS.md

@@ -561,3 +561,38 @@ The `.github/workflows/copilot-setup-steps.yml` workflow ensures bd is available
 - [bd Documentation](https://github.com/steveyegge/beads/blob/main/README.md)
 - [bd Workflow Guide](https://github.com/steveyegge/beads/blob/main/WORKFLOW.md)
 - [bd for Agents](https://github.com/steveyegge/beads/blob/main/AGENTS.md)
+
+### Merge Tool Configuration
+
+This repository includes `beads-merge`, a custom 3-way merge tool for `.beads/issues.jsonl` files. To use it with jj:
+
+1. Build the tool: `cd beads-merge && go build -o beads-merge .`
+2. Add to your jj config (`~/.jjconfig.toml`):
+
+```toml
+[merge-tools.beads-merge]
+program = "/absolute/path/to/mono/beads-merge/beads-merge"
+merge-args = ["$base", "$left", "$right"]
+
+[merge-tools.beads-merge.diff-args]
+# Optional: configure for 2-way diff if needed
+program = "diff"
+```
+
+3. Configure automatic merge for .jsonl files in `.beads/`:
+
+```toml
+[merge]
+# Use beads-merge for .beads/issues.jsonl
+tool-edits = [
+  { pattern = ".beads/issues.jsonl", tool = "beads-merge" }
+]
+```
+
+The merge tool will:
+- Match issues by id, created_at, and created_by
+- Intelligently merge field changes
+- Combine dependency arrays
+- Output conflict markers for unresolvable conflicts
+
+See [beads-merge/README.md](./beads-merge/README.md) for details on the merge algorithm.

beads-merge/AGENTS.md

@@ -0,0 +1,36 @@
+# beads-merge Agent Guidelines
+
+## Purpose
+
+beads-merge is a 3-way merge tool specifically for beads `.jsonl` issue files. It implements intelligent merging based on issue identity and field-specific merge strategies.
+
+## Testing Requirements
+
+- All changes to merge logic must include unit tests
+- Test both successful merge cases and conflict scenarios
+- Integration tests should cover real-world merge patterns from `.beads/issues.jsonl`
+
+## Merge Algorithm Constraints
+
+### DO NOT change these without discussion:
+
+1. Issue identity is based on `.id`, `.created_at`, and `.created_by` only
+2. Timestamps (updated_at, closed_at) always use max value
+3. Dependencies are always merged (deduplicated by issue_id + depends_on_id + type)
+4. String fields use 3-way merge (prefer the side that changed from base)
+
+### Fields that need special handling:
+
+- Priority: integer field, handle like strings but compare as numbers
+- Dependencies: array, must deduplicate based on composite key
+
+## Common Issues
+
+### Issue not merging when expected
+Check that `.id`, `.created_at`, and `.created_by` match exactly in all three files. Even minor differences (timezone, precision) will cause issues to be treated as different.
+
+### Dependencies being duplicated
+Ensure the deduplication key includes all three fields: issue_id, depends_on_id, and type. Two dependencies with same issue_id and depends_on_id but different types are distinct.
+
+### Incorrect conflict markers
+Conflicts should only be generated when both sides changed the same field to different values (not when base == left or base == right).