fix(doctor): add .sync.lock and sync_base.jsonl to gitignore (#980)

* fix(doctor): add .sync.lock and sync_base.jsonl to gitignore

Problem:
- .sync.lock and sync_base.jsonl were missing from GitignoreTemplate
- Files introduced in PR #918 (pull-first sync) appeared as untracked

Solution:
- Add patterns to GitignoreTemplate with explanatory comment
- Add patterns to requiredPatterns for bd doctor validation

Impact:
- Existing users get warning via bd doctor, fix via bd doctor --fix
- New repos get correct gitignore on bd init

Fixes: GH#974

* docs(sync): fix sync_base.jsonl tracking status and add tests

Problem:
- SYNC.md incorrectly documented sync_base.jsonl as "git-tracked"
- No tests validated sync state file gitignore patterns

Solution:
- Update Files Reference table: sync_base.jsonl is "not tracked, per-machine"
- Add TestGitignoreTemplate_ContainsSyncStateFiles
- Add TestRequiredPatterns_ContainsSyncStatePatterns

Relates to: GH#974

cmd/bd/doctor/gitignore.go

@@ -46,6 +46,11 @@ beads.left.meta.json
 beads.right.jsonl
 beads.right.meta.json
 
+# Sync state (local-only, per-machine)
+# These files are machine-specific and should not be shared across clones
+.sync.lock
+sync_base.jsonl
+
 # NOTE: Do NOT add negation patterns (e.g., !issues.jsonl) here.
 # They would override fork protection in .git/info/exclude, allowing
 # contributors to accidentally commit upstream issue databases.
@@ -64,6 +69,8 @@ var requiredPatterns = []string{
 	"*.db?*",
 	"redirect",
 	"last-touched",
+	".sync.lock",
+	"sync_base.jsonl",
 }
 
 // CheckGitignore checks if .beads/.gitignore is up to date

cmd/bd/doctor/gitignore_test.go

@@ -1368,3 +1368,43 @@ func TestRequiredPatterns_ContainsRedirect(t *testing.T) {
 		t.Error("requiredPatterns should include 'redirect'")
 	}
 }
+
+// TestGitignoreTemplate_ContainsSyncStateFiles verifies that sync state files
+// introduced in PR #918 (pull-first sync with 3-way merge) are gitignored.
+// These files are machine-specific and should not be shared across clones.
+// GH#974
+func TestGitignoreTemplate_ContainsSyncStateFiles(t *testing.T) {
+	syncStateFiles := []string{
+		".sync.lock",      // Concurrency guard
+		"sync_base.jsonl", // Base state for 3-way merge (per-machine)
+	}
+
+	for _, pattern := range syncStateFiles {
+		if !strings.Contains(GitignoreTemplate, pattern) {
+			t.Errorf("GitignoreTemplate should contain '%s' pattern", pattern)
+		}
+	}
+}
+
+// TestRequiredPatterns_ContainsSyncStatePatterns verifies that bd doctor
+// validates the presence of sync state patterns in .beads/.gitignore.
+// GH#974
+func TestRequiredPatterns_ContainsSyncStatePatterns(t *testing.T) {
+	syncStatePatterns := []string{
+		".sync.lock",
+		"sync_base.jsonl",
+	}
+
+	for _, expected := range syncStatePatterns {
+		found := false
+		for _, pattern := range requiredPatterns {
+			if pattern == expected {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("requiredPatterns should include '%s'", expected)
+		}
+	}
+}

docs/SYNC.md

@@ -174,7 +174,7 @@ For maximum reliability, ensure machine clocks are synchronized via NTP.
 | File | Purpose |
 |------|---------|
 | `.beads/issues.jsonl` | Current state (git-tracked) |
-| `.beads/sync_base.jsonl` | Last-synced state (git-tracked) |
+| `.beads/sync_base.jsonl` | Last-synced state (not tracked, per-machine) |
 | `.beads/.sync.lock` | Concurrency guard (not tracked) |
 | `.beads/beads.db` | SQLite database (not tracked) |