feat: add bd doctor check for orphaned issues (bd-5hrq)

- Add CheckOrphanedIssues to detect issues referenced in commits but still open
- Pattern matches (prefix-xxx) in git log against open issues in database
- Reports warning with issue IDs and commit hashes
- Add 8 comprehensive tests for the new check

Also:
- Add tests for mol spawn --attach functionality (bd-f7p1)
- Document commit message convention in AGENT_INSTRUCTIONS.md
- Fix CheckpointWAL to use wrapDBError for consistency

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

cmd/bd/doctor/git.go

@@ -1,12 +1,16 @@
 package doctor
 
 import (
+	"database/sql"
 	"fmt"
 	"os"
 	"os/exec"
 	"path/filepath"
+	"regexp"
 	"strings"
 
+	_ "github.com/ncruces/go-sqlite3/driver"
+	_ "github.com/ncruces/go-sqlite3/embed"
 	"github.com/steveyegge/beads/cmd/bd/doctor/fix"
 	"github.com/steveyegge/beads/internal/git"
 	"github.com/steveyegge/beads/internal/syncbranch"
@@ -501,3 +505,162 @@ func FixMergeDriver(path string) error {
 func FixSyncBranchHealth(path string) error {
 	return fix.DBJSONLSync(path)
 }
+
+// CheckOrphanedIssues detects issues referenced in git commits but still open.
+// This catches cases where someone implemented a fix with "(bd-xxx)" in the commit
+// message but forgot to run "bd close".
+func CheckOrphanedIssues(path string) DoctorCheck {
+	// Skip if not in a git repo (check from path directory)
+	cmd := exec.Command("git", "rev-parse", "--git-dir")
+	cmd.Dir = path
+	if err := cmd.Run(); err != nil {
+		return DoctorCheck{
+			Name:     "Orphaned Issues",
+			Status:   StatusOK,
+			Message:  "N/A (not a git repository)",
+			Category: CategoryGit,
+		}
+	}
+
+	beadsDir := filepath.Join(path, ".beads")
+
+	// Skip if no .beads directory
+	if _, err := os.Stat(beadsDir); os.IsNotExist(err) {
+		return DoctorCheck{
+			Name:     "Orphaned Issues",
+			Status:   StatusOK,
+			Message:  "N/A (no .beads directory)",
+			Category: CategoryGit,
+		}
+	}
+
+	// Get database path from config or use canonical name
+	dbPath := filepath.Join(beadsDir, "beads.db")
+	if _, err := os.Stat(dbPath); os.IsNotExist(err) {
+		return DoctorCheck{
+			Name:     "Orphaned Issues",
+			Status:   StatusOK,
+			Message:  "N/A (no database)",
+			Category: CategoryGit,
+		}
+	}
+
+	// Open database read-only
+	db, err := openDBReadOnly(dbPath)
+	if err != nil {
+		return DoctorCheck{
+			Name:     "Orphaned Issues",
+			Status:   StatusOK,
+			Message:  "N/A (unable to open database)",
+			Category: CategoryGit,
+		}
+	}
+	defer db.Close()
+
+	// Get issue prefix from config
+	var issuePrefix string
+	err = db.QueryRow("SELECT value FROM config WHERE key = 'issue_prefix'").Scan(&issuePrefix)
+	if err != nil || issuePrefix == "" {
+		issuePrefix = "bd" // default
+	}
+
+	// Get all open issue IDs
+	rows, err := db.Query("SELECT id FROM issues WHERE status IN ('open', 'in_progress')")
+	if err != nil {
+		return DoctorCheck{
+			Name:     "Orphaned Issues",
+			Status:   StatusOK,
+			Message:  "N/A (unable to query issues)",
+			Category: CategoryGit,
+		}
+	}
+	defer rows.Close()
+
+	openSet := make(map[string]bool)
+	for rows.Next() {
+		var id string
+		if err := rows.Scan(&id); err == nil {
+			openSet[id] = true
+		}
+	}
+
+	if len(openSet) == 0 {
+		return DoctorCheck{
+			Name:     "Orphaned Issues",
+			Status:   StatusOK,
+			Message:  "No open issues to check",
+			Category: CategoryGit,
+		}
+	}
+
+	// Get issue IDs referenced in git commits
+	cmd = exec.Command("git", "log", "--oneline", "--all")
+	cmd.Dir = path
+	output, err := cmd.Output()
+	if err != nil {
+		return DoctorCheck{
+			Name:     "Orphaned Issues",
+			Status:   StatusOK,
+			Message:  "N/A (unable to read git log)",
+			Category: CategoryGit,
+		}
+	}
+
+	// Parse commit messages for issue references
+	// Match pattern like (bd-xxx) or (bd-xxx.1) including hierarchical IDs
+	pattern := fmt.Sprintf(`\(%s-[a-z0-9.]+\)`, regexp.QuoteMeta(issuePrefix))
+	re := regexp.MustCompile(pattern)
+
+	// Track which open issues appear in commits (with first commit hash)
+	orphanedIssues := make(map[string]string) // issue ID -> commit hash
+	lines := strings.Split(string(output), "\n")
+	for _, line := range lines {
+		if line == "" {
+			continue
+		}
+		matches := re.FindAllString(line, -1)
+		for _, match := range matches {
+			// Extract issue ID (remove parentheses)
+			issueID := strings.Trim(match, "()")
+			if openSet[issueID] {
+				// Only record the first (most recent) commit
+				if _, exists := orphanedIssues[issueID]; !exists {
+					// Extract commit hash (first word of line)
+					parts := strings.SplitN(line, " ", 2)
+					if len(parts) > 0 {
+						orphanedIssues[issueID] = parts[0]
+					}
+				}
+			}
+		}
+	}
+
+	if len(orphanedIssues) == 0 {
+		return DoctorCheck{
+			Name:     "Orphaned Issues",
+			Status:   StatusOK,
+			Message:  "No issues referenced in commits but still open",
+			Category: CategoryGit,
+		}
+	}
+
+	// Build detail message
+	var details []string
+	for id, commit := range orphanedIssues {
+		details = append(details, fmt.Sprintf("%s (commit %s)", id, commit))
+	}
+
+	return DoctorCheck{
+		Name:     "Orphaned Issues",
+		Status:   StatusWarning,
+		Message:  fmt.Sprintf("%d issue(s) referenced in commits but still open", len(orphanedIssues)),
+		Detail:   strings.Join(details, ", "),
+		Fix:      "Run 'bd show <id>' to check if implemented, then 'bd close <id>' if done",
+		Category: CategoryGit,
+	}
+}
+
+// openDBReadOnly opens a SQLite database in read-only mode
+func openDBReadOnly(dbPath string) (*sql.DB, error) {
+	return sql.Open("sqlite3", "file:"+dbPath+"?mode=ro")
+}

cmd/bd/doctor/git_test.go

@@ -1,11 +1,15 @@
 package doctor
 
 import (
+	"database/sql"
 	"os"
 	"os/exec"
 	"path/filepath"
 	"strings"
 	"testing"
+
+	_ "github.com/ncruces/go-sqlite3/driver"
+	_ "github.com/ncruces/go-sqlite3/embed"
 )
 
 // setupGitRepo creates a temporary git repository for testing
@@ -800,3 +804,298 @@ func TestCheckSyncBranchHookCompatibility_OldHookFormat(t *testing.T) {
 		})
 	}
 }
+
+// Tests for CheckOrphanedIssues
+
+func TestCheckOrphanedIssues_NoGitRepo(t *testing.T) {
+	tmpDir := t.TempDir()
+	// No git init - just a plain directory
+
+	check := CheckOrphanedIssues(tmpDir)
+
+	if check.Status != StatusOK {
+		t.Errorf("expected status %q, got %q", StatusOK, check.Status)
+	}
+	if !strings.Contains(check.Message, "not a git repository") {
+		t.Errorf("expected message about not a git repository, got %q", check.Message)
+	}
+}
+
+func TestCheckOrphanedIssues_NoBeadsDir(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	// Initialize git repo WITHOUT creating .beads
+	cmd := exec.Command("git", "init")
+	cmd.Dir = tmpDir
+	if err := cmd.Run(); err != nil {
+		t.Fatal(err)
+	}
+
+	check := CheckOrphanedIssues(tmpDir)
+
+	if check.Status != StatusOK {
+		t.Errorf("expected status %q, got %q", StatusOK, check.Status)
+	}
+	if !strings.Contains(check.Message, "no .beads directory") {
+		t.Errorf("expected message about no .beads directory, got %q", check.Message)
+	}
+}
+
+func TestCheckOrphanedIssues_NoDatabase(t *testing.T) {
+	tmpDir := t.TempDir()
+	setupGitRepoInDir(t, tmpDir)
+
+	// Create .beads directory but no database
+	beadsDir := filepath.Join(tmpDir, ".beads")
+	if err := os.MkdirAll(beadsDir, 0755); err != nil {
+		t.Fatal(err)
+	}
+
+	check := CheckOrphanedIssues(tmpDir)
+
+	if check.Status != StatusOK {
+		t.Errorf("expected status %q, got %q", StatusOK, check.Status)
+	}
+	if !strings.Contains(check.Message, "no database") {
+		t.Errorf("expected message about no database, got %q", check.Message)
+	}
+}
+
+func TestCheckOrphanedIssues_NoOpenIssues(t *testing.T) {
+	tmpDir := t.TempDir()
+	setupGitRepoInDir(t, tmpDir)
+
+	// Create .beads directory and database
+	beadsDir := filepath.Join(tmpDir, ".beads")
+	if err := os.MkdirAll(beadsDir, 0755); err != nil {
+		t.Fatal(err)
+	}
+
+	// Create a minimal SQLite database with schema
+	dbPath := filepath.Join(beadsDir, "beads.db")
+	db, err := sql.Open("sqlite3", dbPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close()
+
+	// Create tables
+	_, err = db.Exec(`
+		CREATE TABLE config (key TEXT PRIMARY KEY, value TEXT);
+		CREATE TABLE issues (id TEXT PRIMARY KEY, status TEXT);
+		INSERT INTO config (key, value) VALUES ('issue_prefix', 'bd');
+	`)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	check := CheckOrphanedIssues(tmpDir)
+
+	if check.Status != StatusOK {
+		t.Errorf("expected status %q, got %q", StatusOK, check.Status)
+	}
+	if !strings.Contains(check.Message, "No open issues") {
+		t.Errorf("expected message about no open issues, got %q", check.Message)
+	}
+}
+
+func TestCheckOrphanedIssues_OpenIssueNotInCommits(t *testing.T) {
+	tmpDir := t.TempDir()
+	setupGitRepoInDir(t, tmpDir)
+
+	// Create .beads directory and database
+	beadsDir := filepath.Join(tmpDir, ".beads")
+	if err := os.MkdirAll(beadsDir, 0755); err != nil {
+		t.Fatal(err)
+	}
+
+	// Create database with an open issue
+	dbPath := filepath.Join(beadsDir, "beads.db")
+	db, err := sql.Open("sqlite3", dbPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = db.Exec(`
+		CREATE TABLE config (key TEXT PRIMARY KEY, value TEXT);
+		CREATE TABLE issues (id TEXT PRIMARY KEY, status TEXT);
+		INSERT INTO config (key, value) VALUES ('issue_prefix', 'bd');
+		INSERT INTO issues (id, status) VALUES ('bd-abc', 'open');
+	`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	db.Close()
+
+	// Create a commit without the issue reference
+	readme := filepath.Join(tmpDir, "README.md")
+	if err := os.WriteFile(readme, []byte("# Test"), 0644); err != nil {
+		t.Fatal(err)
+	}
+	cmd := exec.Command("git", "add", "README.md")
+	cmd.Dir = tmpDir
+	_ = cmd.Run()
+	cmd = exec.Command("git", "commit", "-m", "Initial commit")
+	cmd.Dir = tmpDir
+	_ = cmd.Run()
+
+	check := CheckOrphanedIssues(tmpDir)
+
+	if check.Status != StatusOK {
+		t.Errorf("expected status %q, got %q", StatusOK, check.Status)
+	}
+	if !strings.Contains(check.Message, "No issues referenced") {
+		t.Errorf("expected message about no issues referenced, got %q", check.Message)
+	}
+}
+
+func TestCheckOrphanedIssues_OpenIssueInCommit(t *testing.T) {
+	tmpDir := t.TempDir()
+	setupGitRepoInDir(t, tmpDir)
+
+	// Create .beads directory and database
+	beadsDir := filepath.Join(tmpDir, ".beads")
+	if err := os.MkdirAll(beadsDir, 0755); err != nil {
+		t.Fatal(err)
+	}
+
+	// Create database with an open issue
+	dbPath := filepath.Join(beadsDir, "beads.db")
+	db, err := sql.Open("sqlite3", dbPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = db.Exec(`
+		CREATE TABLE config (key TEXT PRIMARY KEY, value TEXT);
+		CREATE TABLE issues (id TEXT PRIMARY KEY, status TEXT);
+		INSERT INTO config (key, value) VALUES ('issue_prefix', 'bd');
+		INSERT INTO issues (id, status) VALUES ('bd-abc', 'open');
+	`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	db.Close()
+
+	// Create a commit WITH the issue reference
+	readme := filepath.Join(tmpDir, "README.md")
+	if err := os.WriteFile(readme, []byte("# Test"), 0644); err != nil {
+		t.Fatal(err)
+	}
+	cmd := exec.Command("git", "add", "README.md")
+	cmd.Dir = tmpDir
+	_ = cmd.Run()
+	cmd = exec.Command("git", "commit", "-m", "Fix bug (bd-abc)")
+	cmd.Dir = tmpDir
+	_ = cmd.Run()
+
+	check := CheckOrphanedIssues(tmpDir)
+
+	if check.Status != StatusWarning {
+		t.Errorf("expected status %q, got %q (message: %s)", StatusWarning, check.Status, check.Message)
+	}
+	if !strings.Contains(check.Message, "1 issue(s) referenced") {
+		t.Errorf("expected message about 1 issue referenced, got %q", check.Message)
+	}
+	if !strings.Contains(check.Detail, "bd-abc") {
+		t.Errorf("expected detail to contain bd-abc, got %q", check.Detail)
+	}
+}
+
+func TestCheckOrphanedIssues_ClosedIssueInCommit(t *testing.T) {
+	tmpDir := t.TempDir()
+	setupGitRepoInDir(t, tmpDir)
+
+	// Create .beads directory and database
+	beadsDir := filepath.Join(tmpDir, ".beads")
+	if err := os.MkdirAll(beadsDir, 0755); err != nil {
+		t.Fatal(err)
+	}
+
+	// Create database with a CLOSED issue
+	dbPath := filepath.Join(beadsDir, "beads.db")
+	db, err := sql.Open("sqlite3", dbPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = db.Exec(`
+		CREATE TABLE config (key TEXT PRIMARY KEY, value TEXT);
+		CREATE TABLE issues (id TEXT PRIMARY KEY, status TEXT);
+		INSERT INTO config (key, value) VALUES ('issue_prefix', 'bd');
+		INSERT INTO issues (id, status) VALUES ('bd-abc', 'closed');
+	`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	db.Close()
+
+	// Create a commit with the issue reference
+	readme := filepath.Join(tmpDir, "README.md")
+	if err := os.WriteFile(readme, []byte("# Test"), 0644); err != nil {
+		t.Fatal(err)
+	}
+	cmd := exec.Command("git", "add", "README.md")
+	cmd.Dir = tmpDir
+	_ = cmd.Run()
+	cmd = exec.Command("git", "commit", "-m", "Fix bug (bd-abc)")
+	cmd.Dir = tmpDir
+	_ = cmd.Run()
+
+	check := CheckOrphanedIssues(tmpDir)
+
+	// Should be OK because the issue is closed
+	if check.Status != StatusOK {
+		t.Errorf("expected status %q, got %q (message: %s)", StatusOK, check.Status, check.Message)
+	}
+}
+
+func TestCheckOrphanedIssues_HierarchicalIssueID(t *testing.T) {
+	tmpDir := t.TempDir()
+	setupGitRepoInDir(t, tmpDir)
+
+	// Create .beads directory and database
+	beadsDir := filepath.Join(tmpDir, ".beads")
+	if err := os.MkdirAll(beadsDir, 0755); err != nil {
+		t.Fatal(err)
+	}
+
+	// Create database with a hierarchical issue ID
+	dbPath := filepath.Join(beadsDir, "beads.db")
+	db, err := sql.Open("sqlite3", dbPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = db.Exec(`
+		CREATE TABLE config (key TEXT PRIMARY KEY, value TEXT);
+		CREATE TABLE issues (id TEXT PRIMARY KEY, status TEXT);
+		INSERT INTO config (key, value) VALUES ('issue_prefix', 'bd');
+		INSERT INTO issues (id, status) VALUES ('bd-abc.1', 'open');
+	`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	db.Close()
+
+	// Create a commit with the hierarchical issue reference
+	readme := filepath.Join(tmpDir, "README.md")
+	if err := os.WriteFile(readme, []byte("# Test"), 0644); err != nil {
+		t.Fatal(err)
+	}
+	cmd := exec.Command("git", "add", "README.md")
+	cmd.Dir = tmpDir
+	_ = cmd.Run()
+	cmd = exec.Command("git", "commit", "-m", "Fix subtask (bd-abc.1)")
+	cmd.Dir = tmpDir
+	_ = cmd.Run()
+
+	check := CheckOrphanedIssues(tmpDir)
+
+	if check.Status != StatusWarning {
+		t.Errorf("expected status %q, got %q (message: %s)", StatusWarning, check.Status, check.Message)
+	}
+	if !strings.Contains(check.Detail, "bd-abc.1") {
+		t.Errorf("expected detail to contain bd-abc.1, got %q", check.Detail)
+	}
+}