feat: add bd doctor --check-health for lightweight git hook health checks

- Add --check-health flag for quick, silent health checks (exit 0 on success)
- Check version mismatch (CLI vs database), sync.branch config, outdated hooks
- Add hints.doctor config option to suppress doctor hints globally
- Update post-merge/post-checkout hooks to call bd doctor --check-health
- Suggest running bd doctor in upgrade notification
- Modernize post-checkout hook (bash→sh, use bd sync instead of bd import)

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

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

.beads-hooks/post-checkout

@@ -1,40 +1,50 @@
-#!/usr/bin/env bash
+#!/bin/sh
-# bd-hooks-version: 0.24.2
+# bd-hooks-version: 0.25.1
 #
-# Beads post-checkout hook
+# bd (beads) post-checkout hook
-# Automatically imports JSONL to SQLite database after checking out branches
+#
+# This hook syncs the bd database after a branch checkout:
+# 1. Checks if any .beads/*.jsonl file was updated
+# 2. Runs 'bd sync --import-only' to import changes
 #
-# Install: cp examples/git-hooks/post-checkout .git/hooks/post-checkout && chmod +x .git/hooks/post-checkout
-
 # Arguments provided by git:
 # $1 = ref of previous HEAD
 # $2 = ref of new HEAD
 # $3 = flag (1 if branch checkout, 0 if file checkout)
+#
+# Install: cp examples/git-hooks/post-checkout .git/hooks/post-checkout && chmod +x .git/hooks/post-checkout
 
 # Only run on branch checkouts
-if [[ "$3" != "1" ]]; then
+if [ "$3" != "1" ]; then
     exit 0
 fi
 
-set -e
+# Check if bd is available
-
+if ! command -v bd >/dev/null 2>&1; then
-# Check if bd is installed
-if ! command -v bd &> /dev/null; then
     exit 0
 fi
 
-# Check if issues.jsonl exists
+# Check if we're in a bd workspace
-if [[ ! -f .beads/issues.jsonl ]]; then
+if [ ! -d .beads ]; then
     exit 0
 fi
 
-# Import issues from JSONL
+# Check if any JSONL file exists in .beads/
-echo "🔗 Importing beads issues from JSONL..."
+if ! ls .beads/*.jsonl >/dev/null 2>&1; then
-
+    exit 0
-if bd import -i .beads/issues.jsonl 2>/dev/null; then
-    echo "✓ Beads issues imported successfully"
-else
-    echo "Warning: bd import failed"
 fi
 
+# Run bd sync --import-only to import the updated JSONL
+if ! output=$(bd sync --import-only 2>&1); then
+    echo "Warning: Failed to sync bd changes after checkout" >&2
+    echo "$output" >&2
+    echo "" >&2
+    echo "Run 'bd doctor --fix' to diagnose and repair" >&2
+    # Don't fail the checkout, just warn
+fi
+
+# Run quick health check (silent on success, hints if issues found)
+# This catches version mismatches, outdated hooks, etc.
+bd doctor --check-health 2>/dev/null || true
+
 exit 0

.beads-hooks/post-merge

@@ -1,5 +1,5 @@
 #!/bin/sh
-# bd-hooks-version: 0.24.2
+# bd-hooks-version: 0.25.1
 #
 # bd (beads) post-merge hook
 #
@@ -38,8 +38,12 @@ if ! output=$(bd sync --import-only 2>&1); then
     echo "Warning: Failed to sync bd changes after merge" >&2
     echo "$output" >&2
     echo "" >&2
-    echo "Run 'bd sync --import-only' manually to resolve" >&2
+    echo "Run 'bd doctor --fix' to diagnose and repair" >&2
     # Don't fail the merge, just warn
 fi
 
+# Run quick health check (silent on success, hints if issues found)
+# This catches version mismatches, outdated hooks, etc.
+bd doctor --check-health 2>/dev/null || true
+
 exit 0

cmd/bd/doctor.go

@@ -47,10 +47,14 @@ type doctorResult struct {
 }
 
 var (
-	doctorFix bool
+	doctorFix       bool
-	perfMode  bool
+	perfMode        bool
+	checkHealthMode bool
 )
 
+// ConfigKeyHintsDoctor is the config key for suppressing doctor hints
+const ConfigKeyHintsDoctor = "hints.doctor"
+
 var doctorCmd = &cobra.Command{
 	Use:   "doctor [path]",
 	Short: "Check beads installation health",
@@ -107,6 +111,12 @@ Examples:
 			return
 		}
 
+		// Run quick health check if --check-health flag is set
+		if checkHealthMode {
+			runCheckHealth(absPath)
+			return
+		}
+
 		// Run diagnostics
 		result := runDiagnostics(absPath)
 
@@ -225,6 +235,190 @@ func applyFixes(result doctorResult) {
 	}
 }
 
+// runCheckHealth runs lightweight health checks for git hooks.
+// Silent on success, prints a hint if issues detected.
+// Respects hints.doctor config setting.
+func runCheckHealth(path string) {
+	beadsDir := filepath.Join(path, ".beads")
+
+	// Check if .beads/ exists
+	if _, err := os.Stat(beadsDir); os.IsNotExist(err) {
+		// No .beads directory - nothing to check
+		return
+	}
+
+	// Check if hints.doctor is disabled in config
+	if hintsDisabled(beadsDir) {
+		return
+	}
+
+	// Run lightweight checks
+	var issues []string
+
+	// Check 1: Database version mismatch (CLI vs database bd_version)
+	if issue := checkVersionMismatch(beadsDir); issue != "" {
+		issues = append(issues, issue)
+	}
+
+	// Check 2: Sync branch not configured
+	if issue := checkSyncBranchQuick(beadsDir); issue != "" {
+		issues = append(issues, issue)
+	}
+
+	// Check 3: Outdated git hooks
+	if issue := checkHooksQuick(path); issue != "" {
+		issues = append(issues, issue)
+	}
+
+	// If any issues found, print hint
+	if len(issues) > 0 {
+		fmt.Fprintf(os.Stderr, "💡 bd doctor recommends a health check:\n")
+		for _, issue := range issues {
+			fmt.Fprintf(os.Stderr, "   • %s\n", issue)
+		}
+		fmt.Fprintf(os.Stderr, "   Run 'bd doctor' for details, or 'bd doctor --fix' to auto-repair\n")
+		fmt.Fprintf(os.Stderr, "   (Suppress with: bd config set %s false)\n", ConfigKeyHintsDoctor)
+		os.Exit(1)
+	}
+	// Silent exit on success
+}
+
+// hintsDisabled checks if hints.doctor is set to "false" in the database config.
+func hintsDisabled(beadsDir string) bool {
+	// Get database path
+	var dbPath string
+	if cfg, err := configfile.Load(beadsDir); err == nil && cfg != nil && cfg.Database != "" {
+		dbPath = cfg.DatabasePath(beadsDir)
+	} else {
+		dbPath = filepath.Join(beadsDir, beads.CanonicalDatabaseName)
+	}
+
+	// Check if database exists
+	if _, err := os.Stat(dbPath); os.IsNotExist(err) {
+		return false // Can't check config, assume hints enabled
+	}
+
+	// Open database read-only to check config
+	db, err := sql.Open("sqlite3", "file:"+dbPath+"?mode=ro")
+	if err != nil {
+		return false
+	}
+	defer db.Close()
+
+	var value string
+	err = db.QueryRow("SELECT value FROM config WHERE key = ?", ConfigKeyHintsDoctor).Scan(&value)
+	if err != nil {
+		return false // Key not set, assume hints enabled
+	}
+
+	return strings.ToLower(value) == "false"
+}
+
+// checkVersionMismatch checks if CLI version differs from database bd_version.
+func checkVersionMismatch(beadsDir string) string {
+	// Get database path
+	var dbPath string
+	if cfg, err := configfile.Load(beadsDir); err == nil && cfg != nil && cfg.Database != "" {
+		dbPath = cfg.DatabasePath(beadsDir)
+	} else {
+		dbPath = filepath.Join(beadsDir, beads.CanonicalDatabaseName)
+	}
+
+	// Check if database exists
+	if _, err := os.Stat(dbPath); os.IsNotExist(err) {
+		return "" // No database, skip check
+	}
+
+	// Open database read-only
+	db, err := sql.Open("sqlite3", "file:"+dbPath+"?mode=ro")
+	if err != nil {
+		return ""
+	}
+	defer db.Close()
+
+	var dbVersion string
+	err = db.QueryRow("SELECT value FROM metadata WHERE key = 'bd_version'").Scan(&dbVersion)
+	if err != nil {
+		return "" // Can't read version, skip
+	}
+
+	if dbVersion != "" && dbVersion != Version {
+		return fmt.Sprintf("Version mismatch (CLI: %s, database: %s)", Version, dbVersion)
+	}
+
+	return ""
+}
+
+// checkSyncBranchQuick checks if sync.branch is configured.
+func checkSyncBranchQuick(beadsDir string) string {
+	// Get database path
+	var dbPath string
+	if cfg, err := configfile.Load(beadsDir); err == nil && cfg != nil && cfg.Database != "" {
+		dbPath = cfg.DatabasePath(beadsDir)
+	} else {
+		dbPath = filepath.Join(beadsDir, beads.CanonicalDatabaseName)
+	}
+
+	// Check if database exists
+	if _, err := os.Stat(dbPath); os.IsNotExist(err) {
+		return "" // No database, skip check
+	}
+
+	// Open database read-only
+	db, err := sql.Open("sqlite3", "file:"+dbPath+"?mode=ro")
+	if err != nil {
+		return ""
+	}
+	defer db.Close()
+
+	var value string
+	err = db.QueryRow("SELECT value FROM config WHERE key = 'sync.branch'").Scan(&value)
+	if err != nil || value == "" {
+		return "sync.branch not configured"
+	}
+
+	return ""
+}
+
+// checkHooksQuick does a fast check for outdated git hooks.
+func checkHooksQuick(path string) string {
+	hooksDir := filepath.Join(path, ".git", "hooks")
+
+	// Check if .git/hooks exists
+	if _, err := os.Stat(hooksDir); os.IsNotExist(err) {
+		return "" // No git hooks directory, skip
+	}
+
+	// Check post-merge hook version (most likely to be outdated after merge)
+	hookPath := filepath.Join(hooksDir, "post-merge")
+	content, err := os.ReadFile(hookPath) // #nosec G304 - path is controlled
+	if err != nil {
+		return "" // Hook doesn't exist, skip (will be caught by full doctor)
+	}
+
+	// Look for version marker
+	hookContent := string(content)
+	if !strings.Contains(hookContent, "bd-hooks-version:") {
+		return "" // Not a bd hook or old format, skip
+	}
+
+	// Extract version
+	for _, line := range strings.Split(hookContent, "\n") {
+		if strings.Contains(line, "bd-hooks-version:") {
+			parts := strings.SplitN(line, ":", 2)
+			if len(parts) == 2 {
+				hookVersion := strings.TrimSpace(parts[1])
+				if hookVersion != Version {
+					return fmt.Sprintf("Git hooks outdated (%s → %s)", hookVersion, Version)
+				}
+			}
+			break
+		}
+	}
+
+	return ""
+}
+
 func runDiagnostics(path string) doctorResult {
 	result := doctorResult{
 		Path:       path,
@@ -1933,4 +2127,5 @@ func checkDeletionsManifest(path string) doctorCheck {
 func init() {
 	rootCmd.AddCommand(doctorCmd)
 	doctorCmd.Flags().BoolVar(&perfMode, "perf", false, "Run performance diagnostics and generate CPU profile")
+	doctorCmd.Flags().BoolVar(&checkHealthMode, "check-health", false, "Quick health check for git hooks (silent on success)")
 }

cmd/bd/templates/hooks/post-checkout

@@ -1,40 +1,50 @@
-#!/usr/bin/env bash
+#!/bin/sh
 # bd-hooks-version: 0.25.1
 #
-# Beads post-checkout hook
+# bd (beads) post-checkout hook
-# Automatically imports JSONL to SQLite database after checking out branches
+#
+# This hook syncs the bd database after a branch checkout:
+# 1. Checks if any .beads/*.jsonl file was updated
+# 2. Runs 'bd sync --import-only' to import changes
 #
-# Install: cp examples/git-hooks/post-checkout .git/hooks/post-checkout && chmod +x .git/hooks/post-checkout
-
 # Arguments provided by git:
 # $1 = ref of previous HEAD
 # $2 = ref of new HEAD
 # $3 = flag (1 if branch checkout, 0 if file checkout)
+#
+# Install: cp examples/git-hooks/post-checkout .git/hooks/post-checkout && chmod +x .git/hooks/post-checkout
 
 # Only run on branch checkouts
-if [[ "$3" != "1" ]]; then
+if [ "$3" != "1" ]; then
     exit 0
 fi
 
-set -e
+# Check if bd is available
-
+if ! command -v bd >/dev/null 2>&1; then
-# Check if bd is installed
-if ! command -v bd &> /dev/null; then
     exit 0
 fi
 
-# Check if issues.jsonl exists
+# Check if we're in a bd workspace
-if [[ ! -f .beads/issues.jsonl ]]; then
+if [ ! -d .beads ]; then
     exit 0
 fi
 
-# Import issues from JSONL
+# Check if any JSONL file exists in .beads/
-echo "🔗 Importing beads issues from JSONL..."
+if ! ls .beads/*.jsonl >/dev/null 2>&1; then
-
+    exit 0
-if bd import -i .beads/issues.jsonl 2>/dev/null; then
-    echo "✓ Beads issues imported successfully"
-else
-    echo "Warning: bd import failed"
 fi
 
+# Run bd sync --import-only to import the updated JSONL
+if ! output=$(bd sync --import-only 2>&1); then
+    echo "Warning: Failed to sync bd changes after checkout" >&2
+    echo "$output" >&2
+    echo "" >&2
+    echo "Run 'bd doctor --fix' to diagnose and repair" >&2
+    # Don't fail the checkout, just warn
+fi
+
+# Run quick health check (silent on success, hints if issues found)
+# This catches version mismatches, outdated hooks, etc.
+bd doctor --check-health 2>/dev/null || true
+
 exit 0

cmd/bd/templates/hooks/post-merge

@@ -38,8 +38,12 @@ if ! output=$(bd sync --import-only 2>&1); then
     echo "Warning: Failed to sync bd changes after merge" >&2
     echo "$output" >&2
     echo "" >&2
-    echo "Run 'bd sync --import-only' manually to resolve" >&2
+    echo "Run 'bd doctor --fix' to diagnose and repair" >&2
     # Don't fail the merge, just warn
 fi
 
+# Run quick health check (silent on success, hints if issues found)
+# This catches version mismatches, outdated hooks, etc.
+bd doctor --check-health 2>/dev/null || true
+
 exit 0

cmd/bd/version_tracking.go

@@ -122,6 +122,7 @@ func maybeShowUpgradeNotification() {
 	// Display notification
 	fmt.Printf("🔄 bd upgraded from v%s to v%s since last use\n", previousVersion, Version)
 	fmt.Println("💡 Run 'bd upgrade review' to see what changed")
+	fmt.Println("💊 Run 'bd doctor' to verify upgrade completed cleanly")
 
 	// Check if BD_GUIDE.md exists and needs updating
 	checkAndSuggestBDGuideUpdate()

examples/git-hooks/post-checkout

@@ -1,39 +1,50 @@
-#!/usr/bin/env bash
+#!/bin/sh
+# bd-hooks-version: 0.25.1
 #
-# Beads post-checkout hook
+# bd (beads) post-checkout hook
-# Automatically imports JSONL to SQLite database after checking out branches
+#
+# This hook syncs the bd database after a branch checkout:
+# 1. Checks if any .beads/*.jsonl file was updated
+# 2. Runs 'bd sync --import-only' to import changes
 #
-# Install: cp examples/git-hooks/post-checkout .git/hooks/post-checkout && chmod +x .git/hooks/post-checkout
-
 # Arguments provided by git:
 # $1 = ref of previous HEAD
 # $2 = ref of new HEAD
 # $3 = flag (1 if branch checkout, 0 if file checkout)
+#
+# Install: cp examples/git-hooks/post-checkout .git/hooks/post-checkout && chmod +x .git/hooks/post-checkout
 
 # Only run on branch checkouts
-if [[ "$3" != "1" ]]; then
+if [ "$3" != "1" ]; then
     exit 0
 fi
 
-set -e
+# Check if bd is available
-
+if ! command -v bd >/dev/null 2>&1; then
-# Check if bd is installed
-if ! command -v bd &> /dev/null; then
     exit 0
 fi
 
-# Check if issues.jsonl exists
+# Check if we're in a bd workspace
-if [[ ! -f .beads/issues.jsonl ]]; then
+if [ ! -d .beads ]; then
     exit 0
 fi
 
-# Import issues from JSONL
+# Check if any JSONL file exists in .beads/
-echo "🔗 Importing beads issues from JSONL..."
+if ! ls .beads/*.jsonl >/dev/null 2>&1; then
-
+    exit 0
-if bd import -i .beads/issues.jsonl 2>/dev/null; then
-    echo "✓ Beads issues imported successfully"
-else
-    echo "Warning: bd import failed"
 fi
 
+# Run bd sync --import-only to import the updated JSONL
+if ! output=$(bd sync --import-only 2>&1); then
+    echo "Warning: Failed to sync bd changes after checkout" >&2
+    echo "$output" >&2
+    echo "" >&2
+    echo "Run 'bd doctor --fix' to diagnose and repair" >&2
+    # Don't fail the checkout, just warn
+fi
+
+# Run quick health check (silent on success, hints if issues found)
+# This catches version mismatches, outdated hooks, etc.
+bd doctor --check-health 2>/dev/null || true
+
 exit 0

examples/git-hooks/post-merge

@@ -1,5 +1,5 @@
 #!/bin/sh
-# bd-hooks-version: 0.22.1
+# bd-hooks-version: 0.25.1
 #
 # bd (beads) post-merge hook
 #
@@ -38,8 +38,12 @@ if ! output=$(bd sync --import-only 2>&1); then
     echo "Warning: Failed to sync bd changes after merge" >&2
     echo "$output" >&2
     echo "" >&2
-    echo "Run 'bd sync --import-only' manually to resolve" >&2
+    echo "Run 'bd doctor --fix' to diagnose and repair" >&2
     # Don't fail the merge, just warn
 fi
 
+# Run quick health check (silent on success, hints if issues found)
+# This catches version mismatches, outdated hooks, etc.
+bd doctor --check-health 2>/dev/null || true
+
 exit 0