fix(routing): auto-enable hydration and flush JSONL after routed create (#1251)

* fix(routing): auto-enable hydration and flush JSONL after routed create

Fixes split-brain bug where issues routed to different repos (via routing.mode=auto)
weren't visible in bd list because JSONL wasn't updated and hydration wasn't configured.

**Problem**: When routing.mode=auto routes issues to a separate repo (e.g., ~/.beads-planning),
those issues don't appear in 'bd list' because:
1. Target repo's JSONL isn't flushed after create
2. Multi-repo hydration (repos.additional) not configured automatically
3. No doctor warnings about the misconfiguration

**Changes**:

1. **Auto-flush JSONL after routed create** (cmd/bd/create.go)
   - After routing issue to target repo, immediately flush to JSONL
   - Tries target daemon's export RPC first (if daemon running)
   - Falls back to direct JSONL export if no daemon
   - Ensures hydration can read the new issue immediately

2. **Enable hydration in bd init --contributor** (cmd/bd/init_contributor.go)
   - Wizard now automatically adds planning repo to repos.additional
   - Users no longer need to manually run 'bd repo add'
   - Routed issues appear in bd list immediately after setup

3. **Add doctor check for hydrated repo daemons** (cmd/bd/doctor/daemon.go)
   - New CheckHydratedRepoDaemons() warns if daemons not running
   - Without daemons, JSONL becomes stale and hydration breaks
   - Suggests: cd <repo> && bd daemon start --local

4. **Add doctor check for routing+hydration mismatch** (cmd/bd/doctor/config_values.go)
   - Validates routing targets are in repos.additional
   - Catches split-brain configuration before users encounter it
   - Suggests: bd repo add <routing-target>

**Testing**: Builds successfully. Unit/integration tests pending.

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

* test(routing): add comprehensive tests for routing fixes

Add unit tests for all 4 routing/hydration fixes:

1. **create_routing_flush_test.go** - Test JSONL flush after routing
   - TestFlushRoutedRepo_DirectExport: Verify direct JSONL export
   - TestPerformAtomicExport: Test atomic file operations
   - TestFlushRoutedRepo_PathExpansion: Test path handling
   - TestRoutingWithHydrationIntegration: E2E routing+hydration test

2. **daemon_test.go** - Test hydrated repo daemon check
   - TestCheckHydratedRepoDaemons: Test with/without daemons running
   - Covers no repos, daemons running, daemons missing scenarios

3. **config_values_test.go** - Test routing+hydration validation
   - Test routing without hydration (should warn)
   - Test routing with correct hydration (should pass)
   - Test routing target not in hydration list (should warn)
   - Test maintainer="." edge case (should pass)

All tests follow existing patterns and use t.TempDir() for isolation.

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

* fix(tests): fix test failures and refine routing validation logic

Fixes test failures and improves validation accuracy:

1. **Fix routing+hydration validation** (config_values.go)
   - Exclude "." from hasRoutingTargets check (current repo doesn't need hydration)
   - Prevents false warnings when maintainer="." or contributor="."

2. **Fix test ID generation** (create_routing_flush_test.go)
   - Use auto-generated IDs instead of hard-coded "beads-test1"
   - Respects test store prefix configuration (test-)
   - Fixed json.NewDecoder usage (file handle, not os.Open result)

3. **Fix config validation tests** (config_values_test.go)
   - Create actual directories for routing paths to pass path validation
   - Tests now verify both routing+hydration AND path existence checks

4. **Fix daemon test expectations** (daemon_test.go)
   - When database unavailable, check returns "No additional repos" not error
   - This is correct behavior (graceful degradation)

All tests now pass:
- TestFlushRoutedRepo* (3 tests)
- TestPerformAtomicExport
- TestCheckHydratedRepoDaemons (3 subtests)
- TestCheckConfigValues routing tests (5 subtests)

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

* docs: clarify when git config beads.role maintainer is needed

Clarify that maintainer role config is only needed in edge case:
- Using GitHub HTTPS URL without credentials
- But you have write access (are a maintainer)

In most cases, beads auto-detects correctly via:
- SSH URLs (git@github.com:owner/repo.git)
- HTTPS with credentials

This prevents confusion - users with SSH or credential-based HTTPS
don't need to manually configure their role.

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

* fix(lint): address linter warnings in routing flush code

- Add missing sqlite import in daemon.go
- Fix unchecked client.Close() error return
- Fix unchecked tempFile.Close() error returns
- Mark unused parameters with _ prefix
- Add nolint:gosec for safe tempPath construction

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

---------

Co-authored-by: Roland Tritsch <roland@ailtir.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

cmd/bd/create.go

@@ -737,6 +737,12 @@ var createCmd = &cobra.Command{
 		// Schedule auto-flush
 		markDirtyAndScheduleFlush()
 
+		// If issue was routed to a different repo, flush its JSONL immediately
+		// so the issue appears in bd list when hydration is enabled (bd-fix-routing)
+		if repoPath != "." {
+			flushRoutedRepo(targetStore, repoPath)
+		}
+
 		// Run create hook
 		if hookRunner != nil {
 			hookRunner.Run(hooks.EventCreate, issue)
@@ -761,6 +767,119 @@ var createCmd = &cobra.Command{
 	},
 }
 
+// flushRoutedRepo ensures the target repo's JSONL is updated after routing an issue.
+// This is critical for multi-repo hydration to work correctly (bd-fix-routing).
+func flushRoutedRepo(targetStore storage.Storage, repoPath string) {
+	ctx := context.Background()
+
+	// Expand the repo path and construct the .beads directory path
+	targetBeadsDir := routing.ExpandPath(repoPath)
+	if !filepath.IsAbs(targetBeadsDir) {
+		// If relative path, make it absolute
+		absPath, err := filepath.Abs(targetBeadsDir)
+		if err != nil {
+			debug.Logf("warning: failed to get absolute path for %s: %v", targetBeadsDir, err)
+			return
+		}
+		targetBeadsDir = absPath
+	}
+
+	// Construct paths for daemon socket and JSONL
+	beadsDir := filepath.Join(targetBeadsDir, ".beads")
+	socketPath := filepath.Join(beadsDir, "bd.sock")
+	jsonlPath := filepath.Join(beadsDir, "issues.jsonl")
+
+	debug.Logf("attempting to flush routed repo at %s", targetBeadsDir)
+
+	// Try to connect to target repo's daemon (if running)
+	flushed := false
+	if client, err := rpc.TryConnect(socketPath); err == nil && client != nil {
+		defer func() { _ = client.Close() }()
+
+		// Daemon is running - ask it to export
+		debug.Logf("found running daemon in target repo, requesting export")
+		exportArgs := &rpc.ExportArgs{
+			JSONLPath: jsonlPath,
+		}
+		if resp, err := client.Export(exportArgs); err == nil && resp.Success {
+			debug.Logf("successfully flushed via target repo daemon")
+			flushed = true
+		} else {
+			if err != nil {
+				debug.Logf("daemon export failed: %v", err)
+			} else {
+				debug.Logf("daemon export error: %s", resp.Error)
+			}
+		}
+	}
+
+	// Fallback: No daemon or daemon flush failed - export directly
+	if !flushed {
+		debug.Logf("no daemon in target repo, exporting directly to JSONL")
+
+		// Get all issues including tombstones (mirrors exportToJSONLDeferred logic)
+		issues, err := targetStore.SearchIssues(ctx, "", types.IssueFilter{IncludeTombstones: true})
+		if err != nil {
+			WarnError("failed to query issues for export: %v", err)
+			return
+		}
+
+		// Perform atomic export (temporary file + rename)
+		if err := performAtomicExport(ctx, jsonlPath, issues, targetStore); err != nil {
+			WarnError("failed to export target repo JSONL: %v", err)
+			return
+		}
+
+		debug.Logf("successfully exported to %s", jsonlPath)
+	}
+}
+
+// performAtomicExport writes issues to JSONL using atomic temp file + rename
+func performAtomicExport(_ context.Context, jsonlPath string, issues []*types.Issue, _ storage.Storage) error {
+	// Create temp file with PID suffix for atomic write
+	tempPath := fmt.Sprintf("%s.tmp.%d", jsonlPath, os.Getpid())
+
+	// Ensure we clean up temp file on error
+	defer func() {
+		// Remove temp file if it still exists (rename failed or error occurred)
+		if _, err := os.Stat(tempPath); err == nil {
+			_ = os.Remove(tempPath)
+		}
+	}()
+
+	// Open temp file for writing
+	tempFile, err := os.Create(tempPath) //nolint:gosec // tempPath is safely constructed from jsonlPath
+	if err != nil {
+		return fmt.Errorf("failed to create temp file: %w", err)
+	}
+
+	// Write issues as JSONL
+	encoder := json.NewEncoder(tempFile)
+	for _, issue := range issues {
+		if err := encoder.Encode(issue); err != nil {
+			_ = tempFile.Close()
+			return fmt.Errorf("failed to encode issue %s: %w", issue.ID, err)
+		}
+	}
+
+	// Sync to disk before rename
+	if err := tempFile.Sync(); err != nil {
+		_ = tempFile.Close()
+		return fmt.Errorf("failed to sync temp file: %w", err)
+	}
+
+	if err := tempFile.Close(); err != nil {
+		return fmt.Errorf("failed to close temp file: %w", err)
+	}
+
+	// Atomic rename
+	if err := os.Rename(tempPath, jsonlPath); err != nil {
+		return fmt.Errorf("failed to rename temp file: %w", err)
+	}
+
+	return nil
+}
+
 func init() {
 	createCmd.Flags().StringP("file", "f", "", "Create multiple issues from markdown file")
 	createCmd.Flags().String("title", "", "Issue title (alternative to positional argument)")