jeduden
diff --git a/‎PLAN.md‎
Lines changed: 1 addition & 1 deletion b/‎PLAN.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎cmd/mdsmith/e2e_test.go‎
Lines changed: 232 additions & 0 deletions b/‎cmd/mdsmith/e2e_test.go‎
Lines changed: 232 additions & 0 deletions
diff --git a/‎cmd/mdsmith/mergedriver.go‎
Lines changed: 29 additions & 1 deletion b/‎cmd/mdsmith/mergedriver.go‎
Lines changed: 29 additions & 1 deletion
diff --git a/‎cmd/mdsmith/mergedriver_test.go‎
Lines changed: 22 additions & 0 deletions b/‎cmd/mdsmith/mergedriver_test.go‎
Lines changed: 22 additions & 0 deletions
diff --git a/‎docs/reference/cli/pre-merge-commit.md‎
Lines changed: 9 additions & 0 deletions b/‎docs/reference/cli/pre-merge-commit.md‎
Lines changed: 9 additions & 0 deletions
@@ -149,5 +149,5 @@ footer: |
 | 218 | 🔲     | opus   | [WASM size reduction — CUE-free engine path and tinygo support](plan/218_wasm-size-reduction.md)                                        |
 | 219 | 🔲     | opus   | [Multiplexed AST walk to close the parity gap to mado](plan/219_multiplexed-ast-walk.md)                                                |
 | 219 | 🔲     | opus   | [Route cmd/mdsmith and the LSP through pkg/mdsmith.Session](plan/219_session-cli-lsp-migration.md)                                      |
-| 220 | 🔲     | opus   | [Make the pre-merge-commit hook the single git-index writer](plan/220_git-index-lock-retry.md)                                          |
+| 220 | ✅     | opus   | [Harden the git-index writers against a transient index.lock](plan/220_git-index-lock-retry.md)                                         |
 <?/catalog?>
@@ -1699,6 +1699,238 @@ func TestE2E_MergeDriver_FileOrderingRace_Resolved(t *testing.T) {
 		"check after merge must pass; stderr:\n%s", stderr)
 }
 
+// setupConflictingMergeRepo builds a repo whose `ours` and `theirs`
+// branches both regenerate PLAN.md's catalog (ours adds plan 02,
+// theirs adds plan 03), so merging conflicts inside the generated
+// section and the mdsmith merge driver runs. git-hook-sync is
+// enabled and the merge driver + hook are installed; ours is left
+// checked out, ready to merge theirs.
+func setupConflictingMergeRepo(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	gitInit(t, dir)
+
+	writeFixture(t, dir, ".mdsmith.yml",
+		"rules:\n  catalog: true\n  include: true\n  git-hook-sync: true\n")
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "plan"), 0o755))
+	writeFixture(t, dir, "plan/01.md", fmt.Sprintf(planTmpl, 1, 1, "🔲", 1))
+	writeFixture(t, dir, "PLAN.md", planMdTmpl)
+
+	_, stderr, code := runBinaryInDir(t, dir, "", "merge-driver", "install")
+	require.Equal(t, 0, code, "install failed: %s", stderr)
+	_, stderr, code = runBinaryInDir(t, dir, "", "fix", "PLAN.md")
+	require.Equal(t, 0, code, "seed fix failed: %s", stderr)
+	gitCommit(t, dir, "seed")
+	seedSHA := strings.TrimSpace(gitInDir(t, dir, "rev-parse", "HEAD"))
+
+	// ours adds plan 02, theirs adds plan 03: both rewrite PLAN.md's
+	// catalog body, so merging conflicts inside the generated section.
+	completePlanOnBranch(t, dir, "ours", seedSHA, 2)
+	completePlanOnBranch(t, dir, "theirs", seedSHA, 3)
+	gitInDir(t, dir, "checkout", "ours")
+	return dir
+}
+
+// TestE2E_PreMergeCommit_ConflictingMergeResolvesWithHookSync runs the
+// merge-queue model (`git merge --no-ff --no-commit`, then the
+// pre-merge-commit hook, then `git commit`) on a *conflicting* merge of
+// a driver-managed generated file, with git-hook-sync (MDS048) enabled
+// — the shape of the failing queue run.
+//
+// ours adds plan 02 and theirs adds plan 03, so both rewrite PLAN.md's
+// generated catalog and `git merge` invokes the mdsmith merge driver on
+// PLAN.md while git holds .git/index.lock. The driver must resolve the
+// conflict (regenerate the catalog from every plan file) WITHOUT running
+// MDS048's in-process `git add` — that add would race the merge for the
+// lock. MDS048 still runs in the hook afterward, when git no longer
+// holds the lock.
+//
+// This guards the concern that dropping MDS048 from the merge driver
+// could leave the conflict unresolved: it asserts the catalog resolves
+// to list every plan, the merge commits cleanly, .gitattributes
+// survives, the worktree is clean, and no stale .git/index.lock remains.
+func TestE2E_PreMergeCommit_ConflictingMergeResolvesWithHookSync(t *testing.T) {
+	if _, err := exec.LookPath("git"); err != nil {
+		t.Skip("git not available")
+	}
+	dir := setupConflictingMergeRepo(t)
+
+	mergeOut, mergeErr := exec.Command("git", "-C", dir,
+		"-c", "commit.gpgsign=false",
+		"merge", "--no-ff", "--no-commit", "theirs").CombinedOutput()
+	// `git merge --no-commit` exits non-zero by design, and some git
+	// versions print "CONFLICT" even when a merge driver resolves the
+	// file — so assert resolution directly: no unmerged index paths.
+	require.Empty(t, strings.TrimSpace(gitInDir(t, dir, "ls-files", "-u")),
+		"merge driver must leave no unmerged paths (conflict resolved); "+
+			"merge exit=%v output:\n%s", mergeErr, mergeOut)
+
+	hook := exec.Command(filepath.Join(gitHooksDir(t, dir), "pre-merge-commit"))
+	hook.Dir = dir
+	hookOut, hookErr := hook.CombinedOutput()
+	require.NoErrorf(t, hookErr, "pre-merge-commit hook failed: %s", hookOut)
+
+	commitOut, err := exec.Command("git", "-C", dir,
+		"-c", "commit.gpgsign=false",
+		"commit", "--no-edit").CombinedOutput()
+	require.NoErrorf(t, err, "git commit (merge) failed: %s", commitOut)
+
+	// Conflict resolved: the committed catalog lists all three plans.
+	committedPlan := gitInDir(t, dir, "show", "HEAD:PLAN.md")
+	for _, id := range []string{"1", "2", "3"} {
+		assert.Regexp(t, `\| `+id+` +\|`, committedPlan,
+			"merged PLAN.md catalog must list plan %s; got:\n%s", id, committedPlan)
+	}
+	assert.NotContains(t, committedPlan, "<<<<<<<",
+		"no conflict markers may survive into the merge commit")
+
+	// .gitattributes survived, no stale lock, clean worktree.
+	committedAttrs := gitInDir(t, dir, "show", "HEAD:.gitattributes")
+	assert.Contains(t, committedAttrs, "merge=mdsmith",
+		"merge commit must keep the managed .gitattributes")
+	assert.NoFileExists(t, filepath.Join(dir, ".git", "index.lock"),
+		"no stale .git/index.lock may remain after the merge")
+	status := strings.TrimSpace(gitInDir(t, dir, "status", "--porcelain"))
+	assert.Empty(t, status,
+		"worktree must be clean after the merge commit; got:\n%s", status)
+
+	_, stderr, code := runBinaryInDir(t, dir, "", "check", ".")
+	assert.Equal(t, 0, code, "check after merge must pass; stderr:\n%s", stderr)
+}
+
+// TestE2E_PreMergeCommit_NoCommitMergeCapturesBoth exercises the
+// invocation model the merge queue uses: `git merge --no-ff
+// --no-commit`, then the pre-merge-commit hook, then a separate `git
+// commit`. It is the plan-220 integration acceptance criterion.
+//
+// The repo carries a deliberately stale .gitattributes managed block
+// (missing the canonical *.markdown include) and a PLAN.md whose
+// catalog has not yet been regenerated for a newly merged plan file.
+// The hook's single `mdsmith fix .` then has real work on two fronts:
+// MDS048 rewrites .gitattributes and stages it (its in-process staging
+// is kept, not dropped), and the catalog rule regenerates PLAN.md
+// (staged by the hook's own hardened staging loop). The resulting
+// merge commit must capture both, and the worktree must be clean.
+//
+// The branches are arranged so the merge has no PLAN.md/.gitattributes
+// conflict: `theirs` adds plan/02.md without regenerating PLAN.md, and
+// `ours` touches only an unrelated file. That keeps the per-file merge
+// driver from pre-regenerating .gitattributes in the worktree, so the
+// stale managed block survives to hook time and MDS048 has a genuine
+// correction to stage — the realistic shape of the queue bug.
+
+// setupNoConflictMergeRepo builds the repo and two branches for
+// TestE2E_PreMergeCommit_NoCommitMergeCapturesBoth: the merge driver
+// and hook are installed, a deliberately stale .gitattributes managed
+// block (missing *.markdown) is committed directly via git so no later
+// `mdsmith fix` re-canonicalises it, `theirs` adds plan/02.md without
+// regenerating PLAN.md, and `ours` makes an unrelated change. ours is
+// left checked out, ready to merge theirs.
+func setupNoConflictMergeRepo(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	gitInit(t, dir)
+
+	writeFixture(t, dir, ".mdsmith.yml",
+		"rules:\n  catalog: true\n  include: true\n  git-hook-sync: true\n")
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "plan"), 0o755))
+	writeFixture(t, dir, "plan/01.md", fmt.Sprintf(planTmpl, 1, 1, "🔲", 1))
+	writeFixture(t, dir, "PLAN.md", planMdTmpl)
+
+	_, stderr, code := runBinaryInDir(t, dir, "", "merge-driver", "install")
+	require.Equal(t, 0, code, "install failed: %s", stderr)
+	_, stderr, code = runBinaryInDir(t, dir, "", "fix", "PLAN.md")
+	require.Equal(t, 0, code, "seed fix failed: %s", stderr)
+
+	staleAttrs := "# BEGIN mdsmith merge-driver\n" +
+		"*.md merge=mdsmith\n" +
+		"# END mdsmith merge-driver\n"
+	writeFixture(t, dir, ".gitattributes", staleAttrs)
+	gitCommit(t, dir, "seed (stale .gitattributes)")
+	seedSHA := strings.TrimSpace(gitInDir(t, dir, "rev-parse", "HEAD"))
+
+	gitInDir(t, dir, "checkout", "-q", "-b", "theirs", seedSHA)
+	writeFixture(t, dir, "plan/02.md", fmt.Sprintf(planTmpl, 2, 2, "🔲", 2))
+	gitInDir(t, dir, "add", "plan/02.md")
+	gitInDir(t, dir, "-c", "commit.gpgsign=false", "commit", "-q", "-m",
+		"add plan 2 (catalog intentionally not regenerated)")
+
+	gitInDir(t, dir, "checkout", "-q", "-b", "ours", seedSHA)
+	writeFixture(t, dir, "NOTES.txt", "note\n")
+	gitInDir(t, dir, "add", "NOTES.txt")
+	gitInDir(t, dir, "-c", "commit.gpgsign=false", "commit", "-q", "-m", "ours note")
+	return dir
+}
+
+func TestE2E_PreMergeCommit_NoCommitMergeCapturesBoth(t *testing.T) {
+	if _, err := exec.LookPath("git"); err != nil {
+		t.Skip("git not available")
+	}
+	dir := setupNoConflictMergeRepo(t)
+
+	// Step 1: `git merge --no-ff --no-commit`, leaving the commit
+	// uncreated, exactly as the merge-queue action does.
+	out, err := exec.Command("git", "-C", dir,
+		"-c", "commit.gpgsign=false",
+		"merge", "--no-ff", "--no-commit", "theirs").CombinedOutput()
+	// A clean --no-commit merge exits non-zero ("stopped before
+	// committing as requested"); only a real conflict is a failure.
+	if err != nil {
+		require.NotContains(t, string(out), "CONFLICT",
+			"merge must apply cleanly with no conflict: %s", out)
+	}
+
+	// Precondition: the stale block survived to hook time (the driver
+	// did not pre-regenerate it), so MDS048 has a real correction.
+	preHookAttrs, readErr := os.ReadFile(filepath.Join(dir, ".gitattributes"))
+	require.NoError(t, readErr)
+	require.NotContains(t, string(preHookAttrs), "*.markdown merge=mdsmith",
+		"the stale .gitattributes must survive to hook time for this test "+
+			"to exercise MDS048's regeneration; got:\n%s", preHookAttrs)
+
+	// Step 2: run the installed hook, exactly as the action does.
+	hookPath := filepath.Join(gitHooksDir(t, dir), "pre-merge-commit")
+	hookCmd := exec.Command(hookPath)
+	hookCmd.Dir = dir
+	hookOut, hookErr := hookCmd.CombinedOutput()
+	require.NoErrorf(t, hookErr, "pre-merge-commit hook failed: %s", hookOut)
+
+	// Step 3: create the merge commit.
+	out, err = exec.Command("git", "-C", dir,
+		"-c", "commit.gpgsign=false",
+		"commit", "--no-edit").CombinedOutput()
+	require.NoErrorf(t, err, "git commit (merge) failed: %s", out)
+
+	// The merge commit's tree must contain both the regenerated
+	// .gitattributes (now including the previously missing *.markdown
+	// line, staged by MDS048) and the regenerated PLAN.md catalog (now
+	// listing plan 2, staged by the hook's staging loop).
+	committedAttrs := gitInDir(t, dir, "show", "HEAD:.gitattributes")
+	assert.Contains(t, committedAttrs, "*.markdown merge=mdsmith",
+		"merge commit must capture the regenerated .gitattributes "+
+			"(the *.markdown include MDS048 added); got:\n%s",
+		committedAttrs)
+
+	committedPlan := gitInDir(t, dir, "show", "HEAD:PLAN.md")
+	assert.Regexp(t, `\| 1 +\|`, committedPlan,
+		"merge commit's PLAN.md must list plan 1; got:\n%s", committedPlan)
+	assert.Regexp(t, `\| 2 +\|`, committedPlan,
+		"merge commit's PLAN.md must list the merged plan 2 (catalog "+
+			"regenerated by the hook); got:\n%s", committedPlan)
+
+	// The worktree must be clean: every regenerated file the hook
+	// touched is committed, nothing left modified or untracked.
+	status := gitInDir(t, dir, "status", "--porcelain")
+	assert.Empty(t, strings.TrimSpace(status),
+		"worktree must be clean after the hook+commit flow; git status:\n%s", status)
+
+	// A fresh check must pass — catches a structurally broken PLAN.md
+	// (malformed table, leftover markers) that the catalog-row regexps
+	// above would miss on a clean-but-wrong tree.
+	_, checkStderr, checkCode := runBinaryInDir(t, dir, "", "check", ".")
+	assert.Equal(t, 0, checkCode, "check after merge must pass; stderr:\n%s", checkStderr)
+}
+
 // gitInit initializes a git repo with isolated user/sign config so
 // commits succeed on machines that have global signing turned on.
 func gitInit(t *testing.T, dir string) {
 
@@ -328,6 +328,34 @@ func readAndRestore(pathname string, backup []byte, backupErr error, mode os.Fil
 	return fixed, 0
 }
 
+// mergeDriverRules is the fix rule set the merge driver runs: every
+// registered rule except those that mutate the git index (rules
+// implementing rule.GitIndexMutator — today only MDS048,
+// git-hook-sync).
+//
+// git invokes the merge driver from inside `git merge`, which holds
+// `.git/index.lock` for the whole merge. A rule whose Fix runs an
+// in-process `git add` (e.g. githooks.StageGitattributes) would be a
+// second index writer racing the parent `git merge` for that lock,
+// which can leave a stale `.git/index.lock` that fails the staging
+// step and bounces the merge queue. The merge driver only needs the
+// content-regenerating rules to resolve a conflict, so index-mutating
+// rules are dropped; the pre-merge-commit hook still runs them
+// afterward, when git no longer holds the lock. Filtering by the
+// capability interface (not a rule ID) excludes any future
+// index-mutating rule automatically.
+func mergeDriverRules() []rule.Rule {
+	all := rule.All()
+	out := make([]rule.Rule, 0, len(all))
+	for _, r := range all {
+		if m, ok := r.(rule.GitIndexMutator); ok && m.MutatesGitIndex() {
+			continue
+		}
+		out = append(out, r)
+	}
+	return out
+}
+
 // fixFileInPlace runs the mdsmith fix pipeline on a single file.
 func fixFileInPlace(path string, maxBytes int64) error {
 	cfg, _, err := loadConfig("")
@@ -337,7 +365,7 @@ func fixFileInPlace(path string, maxBytes int64) error {
 
 	fixer := &fixpkg.Fixer{
 		Config:           cfg,
-		Rules:            rule.All(),
+		Rules:            mergeDriverRules(),
 		StripFrontMatter: frontMatterEnabled(cfg),
 		Logger:           &vlog.Logger{},
 		MaxInputBytes:    maxBytes,
 
@@ -10,10 +10,32 @@ import (
 	"testing"
 
 	"github.com/jeduden/mdsmith/internal/githooks"
+	"github.com/jeduden/mdsmith/internal/rule"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
+func TestMergeDriverRules_ExcludesGitIndexMutators(t *testing.T) {
+	// Precondition: MDS048 (git-hook-sync) is a registered git-index
+	// mutator, so the exclusion is meaningful rather than a no-op.
+	mds048 := rule.ByID("MDS048")
+	require.NotNil(t, mds048, "precondition: MDS048 must be registered")
+	m, ok := mds048.(rule.GitIndexMutator)
+	require.True(t, ok && m.MutatesGitIndex(),
+		"precondition: MDS048 must declare rule.GitIndexMutator")
+
+	rules := mergeDriverRules()
+	for _, r := range rules {
+		gm, ok := r.(rule.GitIndexMutator)
+		assert.False(t, ok && gm.MutatesGitIndex(),
+			"the merge driver runs inside `git merge` (which holds "+
+				".git/index.lock); it must exclude every git-index-mutating "+
+				"rule, but %s remained", r.ID())
+	}
+	assert.NotEmpty(t, rules,
+		"mergeDriverRules must still run the content-regenerating rules")
+}
+
 func TestStripSectionConflicts_Diff3CatalogConflict(t *testing.T) {
 	// diff3-style conflict markers include a ||||||| base section
 	// between <<<<<<< and =======. The merge driver must strip all
 
@@ -11,6 +11,15 @@ Manage a Git `pre-merge-commit` hook that runs
 commit is created. Modified `.md` / `.markdown` files are
 re-staged automatically.
 
+A concurrent git process can briefly hold
+`.git/index.lock`. When `git add` fails for that reason,
+the hook retries with a bounded backoff. A transient
+lock no longer aborts the merge. The hook never deletes
+a lock it did not create. If the lock outlasts the
+retries, the hook prints `index locked` and exits
+non-zero, so the merge stops instead of committing a
+partially staged tree.
+
 ```text
 mdsmith pre-merge-commit <subcommand> [args]
 ```