Add beads-merge: jj merge driver for .jsonl files

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

Author: Copilot

.github/workflows/beads-merge.yml

@@ -0,0 +1,35 @@
+name: beads-merge
+
+on:
+  push:
+    paths:
+      - "beads-merge/**"
+      - ".github/workflows/beads-merge.yml"
+  pull_request:
+    paths:
+      - "beads-merge/**"
+      - ".github/workflows/beads-merge.yml"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Go
+        uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0
+        with:
+          go-version: "1.24.7"
+          cache-dependency-path: beads-merge/go.sum
+
+      - name: Run tests
+        working-directory: beads-merge
+        run: go test ./... -v
+
+      - name: Build
+        working-directory: beads-merge
+        run: go build -o beads-merge .

README.md

@@ -10,6 +10,7 @@ This repository contains multiple independent projects.
 | [markdown-format](markdown-format/) | alpha | Markdown formatter; command surface and formatting rules are still evolving. |
 | [prrun](prrun/) | beta | Runs binaries from PR releases to speed up verification workflows. |
 | [printpdf](printpdf/) | alpha | Markdown/web-to-PDF tool; rendering pipeline has known gaps documented in project issues. |
+| [beads-merge](beads-merge/) | alpha | 3-way merge tool for beads `.jsonl` issue files; designed for jj version control. |
 | [ingest](ingest/) | pre-alpha | Data ingestion orchestrator; schema and connectors change frequently. |
 | [diagram-dsl](diagram-dsl/) | experimental | TypeScript DSL for diagrams; layout system under active refactor. |
 | [mdbook-comments](mdbook-comments/) | alpha | mdbook preprocessor for paragraph-level commenting with Supabase backend. |

beads-merge/README.md

@@ -0,0 +1,130 @@
+# beads-merge
+
+A 3-way merge tool for beads `.jsonl` issue tracker files, designed to work with jj (Jujutsu version control).
+
+## Overview
+
+`beads-merge` intelligently merges beads issue tracker files by:
+
+- Matching issues by their unique key (`.id`, `.created_at`, `.created_by`)
+- Applying smart merge rules for each field
+- Combining dependency arrays and removing duplicates
+- Outputting conflict markers for unresolvable conflicts
+
+## Usage
+
+```bash
+beads-merge <base-file> <left-file> <right-file>
+```
+
+The tool reads three versions of a `.jsonl` file and outputs the merged result to stdout.
+
+### As a jj Merge Tool
+
+Configure in your jj config (e.g., `~/.jjconfig.toml`):
+
+```toml
+[merge-tools.beads-merge]
+program = "beads-merge"
+merge-args = ["$base", "$left", "$right"]
+```
+
+Then use it with:
+
+```bash
+jj resolve --tool=beads-merge
+```
+
+## Merge Algorithm
+
+### Issue Matching
+
+Issues are matched by their composite key:
+- `.id` - Issue identifier
+- `.created_at` - Creation timestamp
+- `.created_by` - Creator identifier
+
+### Field Merging Rules
+
+For matched issues, fields are merged as follows:
+
+**String fields** (title, description, notes, status, issue_type):
+- If base == left and base != right: take right
+- If base == right and base != left: take left
+- Otherwise: take left (including when both changed to same value)
+
+**Priority** (integer):
+- Same logic as string fields
+
+**Timestamps** (updated_at, closed_at):
+- Take the maximum (latest) value
+- If one is null, take the non-null value
+
+**Dependencies** (array):
+- Combine arrays from both sides
+- Remove duplicates based on (issue_id, depends_on_id, type)
+
+### Conflict Handling
+
+Conflicts are output in standard merge conflict format:
+
+```
+<<<<<<< left
+{"id":"bd-1","title":"Left version",...}
+=======
+{"id":"bd-1","title":"Right version",...}
+>>>>>>> right
+```
+
+Conflicts occur when:
+- An issue is modified in both branches with incompatible changes to the same field
+- An issue is added in both branches with different content
+- An issue is modified in one branch and deleted in the other
+
+## Building
+
+```bash
+# Run tests
+mise run //beads-merge:test
+
+# Build binary
+mise run //beads-merge:build
+
+# Format code
+mise run //beads-merge:fmt
+```
+
+## Examples
+
+### Simple merge
+
+Base:
+```jsonl
+{"id":"bd-1","title":"Original","status":"open","created_at":"2025-10-16T20:51:29+02:00","created_by":"user1"}
+```
+
+Left (updated title):
+```jsonl
+{"id":"bd-1","title":"Updated","status":"open","created_at":"2025-10-16T20:51:29+02:00","created_by":"user1"}
+```
+
+Right (changed status):
+```jsonl
+{"id":"bd-1","title":"Original","status":"closed","created_at":"2025-10-16T20:51:29+02:00","created_by":"user1"}
+```
+
+Result (both changes merged):
+```jsonl
+{"id":"bd-1","title":"Updated","status":"closed","created_at":"2025-10-16T20:51:29+02:00","created_by":"user1"}
+```
+
+### Dependency merge
+
+Left adds dependency on bd-2, right adds dependency on bd-3:
+
+Result combines both dependencies without duplicates.
+
+## Exit Codes
+
+- `0` - Successful merge with no conflicts
+- `1` - Conflicts present (conflict markers in output) or error occurred

beads-merge/go.mod

@@ -0,0 +1,3 @@
+module github.com/neongreen/mono/beads-merge
+
+go 1.24.7