From 228d78c18051301b7b1bd6d2748f7ce9d87c4420 Mon Sep 17 00:00:00 2001
From: Peter Chanthamynavong <peterkc@hey.com>
Date: Tue, 20 Jan 2026 14:05:07 -0800
Subject: [PATCH] fix(routing): disable auto-routing by default (#1177)

Change routing.mode default from "auto" to "" (empty/disabled).

This fixes GH#1165 where fresh `bd init --prefix X` followed by
`bd create` would unexpectedly route to ~/.beads-planning and fail
with "database not initialized: issue_prefix config is missing".

Auto-routing now requires explicit opt-in via:
- `bd init --contributor` flag, OR
- `bd config set routing.mode auto`

Includes test verifying the default and doc updates clarifying
the opt-in requirement.
---
 docs/CONTRIBUTOR_NAMESPACE_ISOLATION.md |  2 +-
 docs/ROUTING.md                         |  5 ++++-
 internal/config/config.go               |  2 +-
 internal/config/config_test.go          | 29 +++++++++++++++++++++++++
 4 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/docs/CONTRIBUTOR_NAMESPACE_ISOLATION.md b/docs/CONTRIBUTOR_NAMESPACE_ISOLATION.md
index e83ca3a2..45b7f5aa 100644
--- a/docs/CONTRIBUTOR_NAMESPACE_ISOLATION.md
+++ b/docs/CONTRIBUTOR_NAMESPACE_ISOLATION.md
@@ -126,7 +126,7 @@ accordingly:
 
 2. **Routing Configuration** (`internal/config/config.go`):
    ```go
-   v.SetDefault("routing.mode", "auto")
+   v.SetDefault("routing.mode", "")  // Empty = disabled by default
    v.SetDefault("routing.default", ".")
    v.SetDefault("routing.contributor", "~/.beads-planning")
    ```
diff --git a/docs/ROUTING.md b/docs/ROUTING.md
index 2ef27d49..9780fb3f 100644
--- a/docs/ROUTING.md
+++ b/docs/ROUTING.md
@@ -45,7 +45,10 @@ bd create "Fix bug" -p 1
 Routing is configured via the database config:
 
 ```bash
-# Set routing mode (auto = detect role, explicit = always use default)
+# Auto-routing is disabled by default (routing.mode="")
+# Enable with:
+bd init --contributor
+# OR manually:
 bd config set routing.mode auto
 
 # Set default planning repo
diff --git a/internal/config/config.go b/internal/config/config.go
index d99ce1e6..5a8aa0ec 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -112,7 +112,7 @@ func Initialize() error {
 	v.SetDefault("remote-sync-interval", "30s")
 
 	// Routing configuration defaults
-	v.SetDefault("routing.mode", "auto")
+	v.SetDefault("routing.mode", "")
 	v.SetDefault("routing.default", ".")
 	v.SetDefault("routing.maintainer", ".")
 	v.SetDefault("routing.contributor", "~/.beads-planning")
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
index 80937c39..b47deb3e 100644
--- a/internal/config/config_test.go
+++ b/internal/config/config_test.go
@@ -941,6 +941,35 @@ external_projects:
 	})
 }
 
+func TestRoutingModeDefaultIsEmpty(t *testing.T) {
+	// GH#1165: routing.mode must default to empty (disabled)
+	// to prevent unexpected auto-routing to ~/.beads-planning
+	// Isolate from environment variables
+	restore := envSnapshot(t)
+	defer restore()
+
+	// Initialize config
+	if err := Initialize(); err != nil {
+		t.Fatalf("Initialize() returned error: %v", err)
+	}
+
+	// Verify routing.mode defaults to empty string (disabled)
+	if got := GetString("routing.mode"); got != "" {
+		t.Errorf("GetString(routing.mode) = %q, want \"\" (empty = disabled by default)", got)
+	}
+
+	// Verify other routing defaults are still set correctly
+	if got := GetString("routing.default"); got != "." {
+		t.Errorf("GetString(routing.default) = %q, want \".\"", got)
+	}
+	if got := GetString("routing.maintainer"); got != "." {
+		t.Errorf("GetString(routing.maintainer) = %q, want \".\"", got)
+	}
+	if got := GetString("routing.contributor"); got != "~/.beads-planning" {
+		t.Errorf("GetString(routing.contributor) = %q, want \"~/.beads-planning\"", got)
+	}
+}
+
 func TestValidationConfigDefaults(t *testing.T) {
 	// Isolate from environment variables
 	restore := envSnapshot(t)