From 89a4d6ed8cbbad58d1e6ec0193d544c9c68f50bc Mon Sep 17 00:00:00 2001 From: Ravi Tharuma <25951435+RaviTharuma@users.noreply.github.com> Date: Sun, 26 Jul 2026 07:31:03 +0200 Subject: [PATCH] fix(routing): warn when contributor auto-routing swaps bd list/ready to the planning store (#4866) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(routing): warn when contributor auto-routing swaps list/ready results bd list and bd ready silently swap to the auto-routed contributor planning store (routing.mode=auto + routing.contributor, set up via `bd init --contributor`) whenever beads.role resolves to contributor. If that store is empty or just doesn't have the issue you expect, the commands report zero results with no indication that anything was routed at all — bd stats and bd show don't go through this path, so they keep reporting the local project truth, making the split look like data loss instead of a routing decision. Print a stderr note (with the local issue count and the fix command) whenever openRoutedReadStore actually swaps the active store for these two commands. JSON output on stdout is unchanged; the note is stderr only and, like the existing ready --json truncation notice, is not gated on --quiet since it communicates a change of data source rather than decorative output. * fix(routing): attribute the routing-swap notice to the matched rule; honor --quiet Addresses the 2026-07-23 maphew/mybd review on gastownhall/beads#4866 (fix/contributor-role-visibility). printContributorRoutingNotice was hardcoded to blame beads.role=contributor and recommend `git config beads.role maintainer` for every routed read, even when the swap was actually caused by routing.maintainer or the unconditional routing.default fallback (internal/routing.DetermineTargetRepo) - misdiagnosing the cause in those cases. - internal/routing: DetermineTargetRepo now delegates to a new DetermineTargetRepoWithRule, which also reports which rule matched (RuleContributor/RuleMaintainer/RuleDefault/RuleExplicitOverride/RuleNone). - cmd/bd/routing_read.go: thread that rule out of determineAutoRoutedRepoPath and openRoutedReadStore, and branch printContributorRoutingNotice's text and remediation command on it via routingNoticeText, so a maintainer- or default-routed swap gets its own accurate wording instead of the contributor-role message. - Gate the notice on !quietFlag, matching quietFlag's documented contract ("Suppress non-essential output (errors only)") and the other non-error stderr notices in this package (tips.go, metrics.go). - Reword the parenthetical issue count to "this project has N total issue(s)" rather than claiming all N are "hidden as a result" of routing, since stats.TotalIssues is an unfiltered COUNT(*) that includes closed/deferred/blocked issues bd ready would never surface anyway; comment the GetStatistics-error fallback (count omitted) as an explicit decision. - Add routing_notice_test.go covering each rule variant's notice text and --quiet suppression; update the existing openRoutedReadStore/ determineAutoRoutedRepoPath tests for the new return signatures. The broader routing x {list,ready} x --quiet x JSON-stdout-isolation subprocess test matrix the review also asked for (non-blocking finding) is left for follow-up; it needs dolt-backed subprocess coverage beyond this fix's scope. Agent-Signature: claude-sonnet-5-medium on behalf of maphew --------- Co-authored-by: Ravi Tharuma Co-authored-by: matt wilkie --- cmd/bd/close.go | 2 +- cmd/bd/list.go | 3 +- cmd/bd/ready.go | 3 +- cmd/bd/routed.go | 2 +- cmd/bd/routing_notice_test.go | 132 ++++++++++++++++++++++++++++++++++ cmd/bd/routing_read.go | 82 ++++++++++++++++++--- cmd/bd/routing_read_test.go | 90 ++++++++++++++++++++++- internal/routing/routing.go | 42 +++++++++-- 8 files changed, 336 insertions(+), 20 deletions(-) create mode 100644 cmd/bd/routing_notice_test.go diff --git a/cmd/bd/close.go b/cmd/bd/close.go index 17eb24347..8e25a869d 100644 --- a/cmd/bd/close.go +++ b/cmd/bd/close.go @@ -704,7 +704,7 @@ func resolveCloseTargets(ctx context.Context, localStore storage.DoltStorage, id return nil, fmt.Errorf("no auto-routed store available") } sharedRoutedTried = true - rs, routed, err := openRoutedReadStore(ctx, localStore) + rs, routed, _, err := openRoutedReadStore(ctx, localStore) if err != nil { return nil, err } diff --git a/cmd/bd/list.go b/cmd/bd/list.go index ce8d037f5..441c00c54 100644 --- a/cmd/bd/list.go +++ b/cmd/bd/list.go @@ -550,12 +550,13 @@ func runListCore(cmd *cobra.Command, _ []string) error { ctx := rootCtx activeStore := store - routedStore, routed, err := openRoutedReadStore(ctx, activeStore) + routedStore, routed, routingRule, err := openRoutedReadStore(ctx, activeStore) if err != nil { return HandleError("%v", err) } if routed { defer func() { _ = routedStore.Close() }() + printContributorRoutingNotice(ctx, activeStore, routingRule) activeStore = routedStore } diff --git a/cmd/bd/ready.go b/cmd/bd/ready.go index e8658e6f8..5348233ec 100644 --- a/cmd/bd/ready.go +++ b/cmd/bd/ready.go @@ -222,12 +222,13 @@ This is useful for agents executing molecules to see which steps can run next.`, if claimReady { CheckReadonly("ready --claim") } else { - routedStore, routed, err := openRoutedReadStore(ctx, activeStore) + routedStore, routed, routingRule, err := openRoutedReadStore(ctx, activeStore) if err != nil { return HandleErrorRespectJSON("%v", err) } if routed { defer func() { _ = routedStore.Close() }() + printContributorRoutingNotice(ctx, activeStore, routingRule) activeStore = routedStore } } diff --git a/cmd/bd/routed.go b/cmd/bd/routed.go index e2109b3b3..574cafe97 100644 --- a/cmd/bd/routed.go +++ b/cmd/bd/routed.go @@ -121,7 +121,7 @@ func resolveAndGetFromStore(ctx context.Context, s storage.DoltStorage, id strin // This is the fallback when the local store doesn't have the issue (GH#2345). // Returns a RoutedResult if the issue is found in the auto-routed store. func resolveViaAutoRouting(ctx context.Context, localStore storage.DoltStorage, id string) (*RoutedResult, error) { - routedStore, routed, err := openRoutedReadStore(ctx, localStore) + routedStore, routed, _, err := openRoutedReadStore(ctx, localStore) if err != nil || !routed { return nil, fmt.Errorf("no auto-routed store available") } diff --git a/cmd/bd/routing_notice_test.go b/cmd/bd/routing_notice_test.go new file mode 100644 index 000000000..16fef1989 --- /dev/null +++ b/cmd/bd/routing_notice_test.go @@ -0,0 +1,132 @@ +// routing_notice_test.go - Tests for the routing-swap stderr notice printed +// by list/ready when reads are auto-routed to a different store. +// +// Deliberately untagged (no `cgo` build tag): printContributorRoutingNotice +// and routingNoticeText don't need a real store or the embedded Dolt server, +// so these tests exercise them with a nil storage.DoltStorage and must stay +// compilable under CGO_ENABLED=0 with the gms_pure_go build tag alongside +// the rest of the pure-Go test suite. + +package main + +import ( + "context" + "strings" + "testing" + + "github.com/steveyegge/beads/internal/routing" +) + +// TestRoutingNoticeText_VariesByRule verifies the notice's reason and fix +// command are branched on the matched routing rule instead of always +// attributing the swap to beads.role=contributor (gastownhall/beads#4866 +// review, 2026-07-23). +func TestRoutingNoticeText_VariesByRule(t *testing.T) { + tests := []struct { + name string + rule routing.RoutingRule + wantReason string + wantFix string + }{ + { + name: "contributor rule", + rule: routing.RuleContributor, + wantReason: "beads.role=contributor", + wantFix: "git config beads.role maintainer", + }, + { + name: "maintainer rule", + rule: routing.RuleMaintainer, + wantReason: "routing.maintainer", + wantFix: "bd config unset routing.maintainer", + }, + { + name: "default rule", + rule: routing.RuleDefault, + wantReason: "routing.default", + wantFix: "bd config unset routing.default", + }, + { + name: "no rule (fallback wording)", + rule: routing.RuleNone, + wantReason: "auto-routing rule", + wantFix: "bd config get", + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + reason, fix := routingNoticeText(tt.rule) + if !strings.Contains(reason, tt.wantReason) { + t.Errorf("routingNoticeText(%v) reason = %q, want substring %q", tt.rule, reason, tt.wantReason) + } + if !strings.Contains(fix, tt.wantFix) { + t.Errorf("routingNoticeText(%v) fix = %q, want substring %q", tt.rule, fix, tt.wantFix) + } + }) + } + + // The contributor-rule wording must not leak into the other rules' + // notices: that mislabeling (fixed `git config beads.role maintainer` + // advice for a maintainer- or default-routed swap) was the review's + // blocking finding. + for _, rule := range []routing.RoutingRule{routing.RuleMaintainer, routing.RuleDefault, routing.RuleNone} { + reason, fix := routingNoticeText(rule) + if strings.Contains(reason, "beads.role") || strings.Contains(fix, "beads.role") { + t.Errorf("routingNoticeText(%v) incorrectly mentions beads.role: reason=%q fix=%q", rule, reason, fix) + } + } +} + +// TestPrintContributorRoutingNotice_TextMatchesRule verifies the emitted +// stderr notice reflects the rule passed in, for each rule variant. +func TestPrintContributorRoutingNotice_TextMatchesRule(t *testing.T) { + origQuiet := quietFlag + quietFlag = false + t.Cleanup(func() { quietFlag = origQuiet }) + + tests := []struct { + name string + rule routing.RoutingRule + want string + }{ + {"contributor", routing.RuleContributor, "beads.role=contributor"}, + {"maintainer", routing.RuleMaintainer, "routing.maintainer"}, + {"default", routing.RuleDefault, "routing.default"}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + out := captureStderr(t, func() { + printContributorRoutingNotice(context.Background(), nil, tt.rule) + }) + if !strings.Contains(out, tt.want) { + t.Errorf("printContributorRoutingNotice(rule=%v) stderr = %q, want substring %q", tt.rule, out, tt.want) + } + }) + } +} + +// TestPrintContributorRoutingNotice_QuietSuppresses verifies --quiet +// suppresses the routing notice, matching the other non-error stderr +// notices in this package (tips.go, metrics.go) that respect quietFlag. +func TestPrintContributorRoutingNotice_QuietSuppresses(t *testing.T) { + origQuiet := quietFlag + t.Cleanup(func() { quietFlag = origQuiet }) + + quietFlag = true + out := captureStderr(t, func() { + printContributorRoutingNotice(context.Background(), nil, routing.RuleContributor) + }) + if out != "" { + t.Errorf("printContributorRoutingNotice() with quietFlag=true wrote stderr = %q, want empty", out) + } + + quietFlag = false + out = captureStderr(t, func() { + printContributorRoutingNotice(context.Background(), nil, routing.RuleContributor) + }) + if out == "" { + t.Error("printContributorRoutingNotice() with quietFlag=false wrote no stderr, want non-empty") + } +} diff --git a/cmd/bd/routing_read.go b/cmd/bd/routing_read.go index b2b31988f..f9b1fd476 100644 --- a/cmd/bd/routing_read.go +++ b/cmd/bd/routing_read.go @@ -3,6 +3,7 @@ package main import ( "context" "fmt" + "os" "path/filepath" "strings" @@ -47,7 +48,7 @@ func getRoutingConfigValue(ctx context.Context, store storage.DoltStorage, key s return strings.TrimSpace(dbValue) } -func determineAutoRoutedRepoPath(ctx context.Context, store storage.DoltStorage) string { +func determineAutoRoutedRepoPath(ctx context.Context, store storage.DoltStorage) (string, routing.RoutingRule) { userRole, err := routing.DetectUserRole(".") if err != nil { debug.Logf("Warning: failed to detect user role: %v\n", err) @@ -88,22 +89,87 @@ func determineAutoRoutedRepoPath(ctx context.Context, store storage.DoltStorage) ExplicitOverride: "", } - return routing.DetermineTargetRepo(routingConfig, userRole, ".") + return routing.DetermineTargetRepoWithRule(routingConfig, userRole, ".") +} + +// routingNoticeText returns the stderr note and remediation command for the +// given routing rule, so the notice always attributes the swap to the rule +// that actually matched instead of hardcoding the contributor-role case. +func routingNoticeText(rule routing.RoutingRule) (reason, fix string) { + switch rule { + case routing.RuleContributor: + // The contributor rule fires on explicit beads.role=contributor OR on + // origin-URL inference with beads.role unset — don't claim the config + // key is set when it may not be. + return "contributor routing (beads.role=contributor, or inferred from the origin URL) routes bd list/ready to the contributor planning store, not this project", + "git config beads.role maintainer" + case routing.RuleMaintainer: + return "routing.maintainer routes bd list/ready to a different planning store than this project", + "bd config unset routing.maintainer" + case routing.RuleDefault: + return "routing.default routes bd list/ready to a different planning store than this project", + "bd config unset routing.default" + default: + return "an auto-routing rule sends bd list/ready to a different planning store than this project", + "bd config get routing.mode routing.contributor routing.maintainer routing.default" + } +} + +// printContributorRoutingNotice tells the user that `bd list`/`bd ready` are +// reading from an auto-routed store instead of the local project database, +// so a short or empty result doesn't look like data loss. Without this, a +// routed-but-unrelated (often empty) planning store silently replaces the +// local result set with no indication anything changed: `bd stats` and +// `bd show ` don't route (see openRoutedReadStore callers), so they keep +// reporting the local project truth while list/ready go quiet — exactly the +// split that makes this so hard to diagnose from the CLI alone. +// +// The notice text and remediation command are branched on rule, the +// routing.RoutingRule that actually matched in determineAutoRoutedRepoPath, +// so a maintainer- or default-routed swap doesn't get misattributed to +// beads.role=contributor. +// +// Gated on !quietFlag: --quiet is documented as "Suppress non-essential +// output (errors only)" (cmd/bd/main.go), and other non-error stderr +// notices in this package (tips.go, metrics.go) respect it the same way. +func printContributorRoutingNotice(ctx context.Context, localStore storage.DoltStorage, rule routing.RoutingRule) { + if quietFlag { + return + } + countSuffix := "" + if localStore != nil { + if stats, err := localStore.GetStatistics(ctx); err == nil { + // stats.TotalIssues is an unfiltered COUNT(*) FROM issues, so it + // includes closed/deferred/blocked issues that bd ready's + // predicates would never surface anyway. Report it as the + // project's total issue count rather than claiming all of them + // are "hidden as a result" of routing. + countSuffix = fmt.Sprintf(" (this project has %d total issue(s))", stats.TotalIssues) + } + // If GetStatistics errors, countSuffix stays empty: the notice is + // still accurate without the count, so the parenthetical is + // silently dropped rather than surfacing a secondary error. + } + reason, fix := routingNoticeText(rule) + fmt.Fprintf(os.Stderr, "note: %s%s.\n", reason, countSuffix) + fmt.Fprintln(os.Stderr, " Fix:", fix) } // openRoutedReadStore opens the auto-routed target store for read commands. -// Returns routed=false when reads should stay in the current store. -func openRoutedReadStore(ctx context.Context, store storage.DoltStorage) (storage.DoltStorage, bool, error) { - repoPath := determineAutoRoutedRepoPath(ctx, store) +// Returns routed=false when reads should stay in the current store. The +// returned routing.RoutingRule identifies which rule matched, for callers +// that print a routing notice. +func openRoutedReadStore(ctx context.Context, store storage.DoltStorage) (storage.DoltStorage, bool, routing.RoutingRule, error) { + repoPath, rule := determineAutoRoutedRepoPath(ctx, store) if repoPath == "" || repoPath == "." { - return nil, false, nil + return nil, false, routing.RuleNone, nil } targetRepoPath := routing.ExpandPath(repoPath) targetBeadsDir := filepath.Join(targetRepoPath, ".beads") targetStore, err := newReadOnlyStoreFromConfig(ctx, targetBeadsDir) if err != nil { - return nil, false, fmt.Errorf("failed to open routed store at %s: %w", targetRepoPath, err) + return nil, false, rule, fmt.Errorf("failed to open routed store at %s: %w", targetRepoPath, err) } - return targetStore, true, nil + return targetStore, true, rule, nil } diff --git a/cmd/bd/routing_read_test.go b/cmd/bd/routing_read_test.go index 9423d522f..ef9d571b5 100644 --- a/cmd/bd/routing_read_test.go +++ b/cmd/bd/routing_read_test.go @@ -8,6 +8,8 @@ import ( "os/exec" "path/filepath" "testing" + + "github.com/steveyegge/beads/internal/routing" ) func TestDetermineAutoRoutedRepoPath_ContributorToPlanning(t *testing.T) { @@ -41,10 +43,91 @@ func TestDetermineAutoRoutedRepoPath_ContributorToPlanning(t *testing.T) { t.Fatalf("chdir repoDir: %v", err) } - got := determineAutoRoutedRepoPath(ctx, sourceStore) + got, rule := determineAutoRoutedRepoPath(ctx, sourceStore) if got != planningDir { t.Fatalf("determineAutoRoutedRepoPath() = %q, want %q", got, planningDir) } + if rule != routing.RuleContributor { + t.Fatalf("determineAutoRoutedRepoPath() rule = %v, want %v", rule, routing.RuleContributor) + } +} + +func TestDetermineAutoRoutedRepoPath_MaintainerToPlanning(t *testing.T) { + initConfigForTest(t) + + tmpDir := t.TempDir() + repoDir := filepath.Join(tmpDir, "repo") + planningDir := filepath.Join(tmpDir, "planning") + + runCmd(t, tmpDir, "git", "init", repoDir) + runCmd(t, repoDir, "git", "config", "beads.role", "maintainer") + + sourceStore := newTestStoreIsolatedDB(t, filepath.Join(repoDir, ".beads", "beads.db"), "srm") + ctx := context.Background() + + if err := sourceStore.SetConfig(ctx, "routing.mode", "auto"); err != nil { + t.Fatalf("failed to set routing.mode: %v", err) + } + if err := sourceStore.SetConfig(ctx, "routing.maintainer", planningDir); err != nil { + t.Fatalf("failed to set routing.maintainer: %v", err) + } + + oldWD, err := os.Getwd() + if err != nil { + t.Fatalf("os.Getwd failed: %v", err) + } + t.Cleanup(func() { + _ = os.Chdir(oldWD) + }) + if err := os.Chdir(repoDir); err != nil { + t.Fatalf("chdir repoDir: %v", err) + } + + got, rule := determineAutoRoutedRepoPath(ctx, sourceStore) + if got != planningDir { + t.Fatalf("determineAutoRoutedRepoPath() = %q, want %q", got, planningDir) + } + if rule != routing.RuleMaintainer { + t.Fatalf("determineAutoRoutedRepoPath() rule = %v, want %v", rule, routing.RuleMaintainer) + } +} + +func TestDetermineAutoRoutedRepoPath_DefaultFallback(t *testing.T) { + initConfigForTest(t) + + tmpDir := t.TempDir() + repoDir := filepath.Join(tmpDir, "repo") + planningDir := filepath.Join(tmpDir, "planning") + + runCmd(t, tmpDir, "git", "init", repoDir) + runCmd(t, repoDir, "git", "config", "beads.role", "maintainer") + + sourceStore := newTestStoreIsolatedDB(t, filepath.Join(repoDir, ".beads", "beads.db"), "srd") + ctx := context.Background() + + // No role-specific repo configured: the unconditional default matches. + if err := sourceStore.SetConfig(ctx, "routing.default", planningDir); err != nil { + t.Fatalf("failed to set routing.default: %v", err) + } + + oldWD, err := os.Getwd() + if err != nil { + t.Fatalf("os.Getwd failed: %v", err) + } + t.Cleanup(func() { + _ = os.Chdir(oldWD) + }) + if err := os.Chdir(repoDir); err != nil { + t.Fatalf("chdir repoDir: %v", err) + } + + got, rule := determineAutoRoutedRepoPath(ctx, sourceStore) + if got != planningDir { + t.Fatalf("determineAutoRoutedRepoPath() = %q, want %q", got, planningDir) + } + if rule != routing.RuleDefault { + t.Fatalf("determineAutoRoutedRepoPath() rule = %v, want %v", rule, routing.RuleDefault) + } } func TestOpenRoutedReadStore_ContributorRouting(t *testing.T) { @@ -83,13 +166,16 @@ func TestOpenRoutedReadStore_ContributorRouting(t *testing.T) { t.Fatalf("chdir repoDir: %v", err) } - routedStore, routed, err := openRoutedReadStore(ctx, sourceStore) + routedStore, routed, rule, err := openRoutedReadStore(ctx, sourceStore) if err != nil { t.Fatalf("openRoutedReadStore() error = %v", err) } if !routed { t.Fatal("openRoutedReadStore() routed = false, want true") } + if rule != routing.RuleContributor { + t.Fatalf("openRoutedReadStore() rule = %v, want %v", rule, routing.RuleContributor) + } defer func() { _ = routedStore.Close() }() prefix, err := routedStore.GetConfig(ctx, "issue_prefix") diff --git a/internal/routing/routing.go b/internal/routing/routing.go index 94eb8298d..0516939ff 100644 --- a/internal/routing/routing.go +++ b/internal/routing/routing.go @@ -173,31 +173,61 @@ type RoutingConfig struct { ExplicitOverride string // Explicit --repo flag override } +// RoutingRule identifies which clause of DetermineTargetRepo matched, so +// callers can explain *why* a repo was routed instead of assuming a single +// cause (e.g. the contributor-role rule). +type RoutingRule int + +const ( + // RuleNone means no routing rule matched; the current repo was used. + RuleNone RoutingRule = iota + // RuleExplicitOverride means config.ExplicitOverride took precedence. + RuleExplicitOverride + // RuleMaintainer means auto mode routed via MaintainerRepo for a + // maintainer-role user. + RuleMaintainer + // RuleContributor means auto mode routed via ContributorRepo for a + // contributor-role user. + RuleContributor + // RuleDefault means the unconditional DefaultRepo fallback matched, + // independent of user role. + RuleDefault +) + // DetermineTargetRepo determines which repo should receive a new issue -// based on routing configuration and user role +// based on routing configuration and user role. func DetermineTargetRepo(config *RoutingConfig, userRole UserRole, repoPath string) string { + repo, _ := DetermineTargetRepoWithRule(config, userRole, repoPath) + return repo +} + +// DetermineTargetRepoWithRule is DetermineTargetRepo, but also reports which +// rule matched so callers can produce an accurate diagnosis (e.g. a notice +// explaining why a read was routed elsewhere) instead of assuming a single +// hardcoded cause. +func DetermineTargetRepoWithRule(config *RoutingConfig, userRole UserRole, repoPath string) (string, RoutingRule) { // Explicit override takes precedence if config.ExplicitOverride != "" { - return config.ExplicitOverride + return config.ExplicitOverride, RuleExplicitOverride } // Auto mode: route based on user role if config.Mode == "auto" { if userRole == Maintainer && config.MaintainerRepo != "" { - return config.MaintainerRepo + return config.MaintainerRepo, RuleMaintainer } if userRole == Contributor && config.ContributorRepo != "" { - return config.ContributorRepo + return config.ContributorRepo, RuleContributor } } // Fall back to default repo if config.DefaultRepo != "" { - return config.DefaultRepo + return config.DefaultRepo, RuleDefault } // No routing configured - use current repo - return "." + return ".", RuleNone } // ExpandPath expands ~ to home directory and resolves relative paths to absolute.