fix(beads): prevent routes.jsonl corruption and add doctor check for rig-level routes.jsonl (#377)

* fix(beads): prevent routes.jsonl corruption from bd auto-export When issues.jsonl doesn't exist, bd's auto-export mechanism writes issue data to routes.jsonl, corrupting the routing configuration. Changes: - install.go: Create issues.jsonl before routes.jsonl at town level - manager.go: Create issues.jsonl in rig beads; don't create routes.jsonl (rig-level routes.jsonl breaks bd's walk-up routing to town routes) - Add integration tests for routes.jsonl corruption prevention Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(doctor): add check to detect and fix rig-level routes.jsonl Add RigRoutesJSONLCheck to detect routes.jsonl files in rig .beads directories. These files break bd's walk-up routing to town-level routes.jsonl, causing cross-rig routing failures. The fix unconditionally deletes rig-level routes.jsonl files since bd will auto-export to issues.jsonl on next run. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * test(rig): add verification that routes.jsonl does NOT exist in rig .beads Add explicit test assertion and detailed comment explaining why rig-level routes.jsonl files must not exist (breaks bd walk-up routing to town routes). Also verify that issues.jsonl DOES exist (prevents bd auto-export corruption). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(doctor): ensure town root route exists in routes.jsonl The RoutesCheck now detects and fixes missing town root routes (hq- -> .). This can happen when routes.jsonl is corrupted or was created without the town route during initialization. Changes: - Detect missing hq- route in Run() - Add hq- route in Fix() when missing - Handle case where routes.jsonl is corrupted (regenerate with town route) - Add comprehensive unit tests for route detection and fixing Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * test(beads): fix routing integration test for routes.jsonl corruption The TestBeadsRoutingFromTownRoot test was failing because bd's auto-export mechanism writes issue data to routes.jsonl when issues.jsonl doesn't exist. This corrupts the routing configuration. Fix: Create empty issues.jsonl after bd init to prevent corruption. This mirrors what gt install does to prevent the same bug. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: julianknutsen <julianknutsen@users.noreply.github> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 09:45:26 +00:00
parent a1008f6f58
commit 043a6abc59
10 changed files with 984 additions and 24 deletions
--- a/internal/doctor/rig_routes_jsonl_check.go
+++ b/internal/doctor/rig_routes_jsonl_check.go
@@ -0,0 +1,180 @@
+package doctor
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/steveyegge/gastown/internal/beads"
+	"github.com/steveyegge/gastown/internal/config"
+)
+
+// RigRoutesJSONLCheck detects and fixes routes.jsonl files in rig .beads directories.
+//
+// Rig-level routes.jsonl files are problematic because:
+// 1. bd's routing walks up to find town root (via mayor/town.json) and uses town-level routes.jsonl
+// 2. If a rig has its own routes.jsonl, bd uses it and never finds town routes, breaking cross-rig routing
+// 3. These files often exist due to a bug where bd's auto-export wrote issue data to routes.jsonl
+//
+// Fix: Delete routes.jsonl unconditionally. The SQLite database (beads.db) is the source
+// of truth, and bd will auto-export to issues.jsonl on next run.
+type RigRoutesJSONLCheck struct {
+	FixableCheck
+	// affectedRigs tracks which rigs have routes.jsonl
+	affectedRigs []rigRoutesInfo
+}
+
+type rigRoutesInfo struct {
+	rigName    string
+	routesPath string
+}
+
+// NewRigRoutesJSONLCheck creates a new check for rig-level routes.jsonl files.
+func NewRigRoutesJSONLCheck() *RigRoutesJSONLCheck {
+	return &RigRoutesJSONLCheck{
+		FixableCheck: FixableCheck{
+			BaseCheck: BaseCheck{
+				CheckName:        "rig-routes-jsonl",
+				CheckDescription: "Check for routes.jsonl in rig .beads directories",
+				CheckCategory:    CategoryConfig,
+			},
+		},
+	}
+}
+
+// Run checks for routes.jsonl files in rig .beads directories.
+func (c *RigRoutesJSONLCheck) Run(ctx *CheckContext) *CheckResult {
+	c.affectedRigs = nil // Reset
+
+	// Get list of rigs from multiple sources
+	rigDirs := c.findRigDirectories(ctx.TownRoot)
+
+	if len(rigDirs) == 0 {
+		return &CheckResult{
+			Name:     c.Name(),
+			Status:   StatusOK,
+			Message:  "No rigs to check",
+			Category: c.Category(),
+		}
+	}
+
+	var problems []string
+
+	for _, rigDir := range rigDirs {
+		rigName := filepath.Base(rigDir)
+		beadsDir := filepath.Join(rigDir, ".beads")
+		routesPath := filepath.Join(beadsDir, beads.RoutesFileName)
+
+		// Check if routes.jsonl exists in this rig's .beads directory
+		if _, err := os.Stat(routesPath); os.IsNotExist(err) {
+			continue // Good - no rig-level routes.jsonl
+		}
+
+		// routes.jsonl exists - it should be deleted
+		problems = append(problems, fmt.Sprintf("%s: has routes.jsonl (will delete - breaks cross-rig routing)", rigName))
+
+		c.affectedRigs = append(c.affectedRigs, rigRoutesInfo{
+			rigName:    rigName,
+			routesPath: routesPath,
+		})
+	}
+
+	if len(c.affectedRigs) == 0 {
+		return &CheckResult{
+			Name:     c.Name(),
+			Status:   StatusOK,
+			Message:  fmt.Sprintf("No rig-level routes.jsonl files (%d rigs checked)", len(rigDirs)),
+			Category: c.Category(),
+		}
+	}
+
+	return &CheckResult{
+		Name:     c.Name(),
+		Status:   StatusWarning,
+		Message:  fmt.Sprintf("%d rig(s) have routes.jsonl (breaks routing)", len(c.affectedRigs)),
+		Details:  problems,
+		FixHint:  "Run 'gt doctor --fix' to delete these files",
+		Category: c.Category(),
+	}
+}
+
+// Fix deletes routes.jsonl files in rig .beads directories.
+// The SQLite database (beads.db) is the source of truth - bd will auto-export
+// to issues.jsonl on next run.
+func (c *RigRoutesJSONLCheck) Fix(ctx *CheckContext) error {
+	// Re-run check to populate affectedRigs if needed
+	if len(c.affectedRigs) == 0 {
+		result := c.Run(ctx)
+		if result.Status == StatusOK {
+			return nil // Nothing to fix
+		}
+	}
+
+	for _, info := range c.affectedRigs {
+		if err := os.Remove(info.routesPath); err != nil {
+			return fmt.Errorf("deleting %s: %w", info.routesPath, err)
+		}
+	}
+
+	return nil
+}
+
+// findRigDirectories finds all rig directories in the town.
+func (c *RigRoutesJSONLCheck) findRigDirectories(townRoot string) []string {
+	var rigDirs []string
+	seen := make(map[string]bool)
+
+	// Source 1: rigs.json registry
+	rigsPath := filepath.Join(townRoot, "mayor", "rigs.json")
+	if rigsConfig, err := config.LoadRigsConfig(rigsPath); err == nil {
+		for rigName := range rigsConfig.Rigs {
+			rigPath := filepath.Join(townRoot, rigName)
+			if _, err := os.Stat(rigPath); err == nil && !seen[rigPath] {
+				rigDirs = append(rigDirs, rigPath)
+				seen[rigPath] = true
+			}
+		}
+	}
+
+	// Source 2: routes.jsonl (for rigs that may not be in registry)
+	townBeadsDir := filepath.Join(townRoot, ".beads")
+	if routes, err := beads.LoadRoutes(townBeadsDir); err == nil {
+		for _, route := range routes {
+			if route.Path == "." || route.Path == "" {
+				continue // Skip town root
+			}
+			// Extract rig name (first path component)
+			parts := strings.Split(route.Path, "/")
+			if len(parts) > 0 && parts[0] != "" {
+				rigPath := filepath.Join(townRoot, parts[0])
+				if _, err := os.Stat(rigPath); err == nil && !seen[rigPath] {
+					rigDirs = append(rigDirs, rigPath)
+					seen[rigPath] = true
+				}
+			}
+		}
+	}
+
+	// Source 3: Look for directories with .beads subdirs (for unregistered rigs)
+	entries, err := os.ReadDir(townRoot)
+	if err == nil {
+		for _, entry := range entries {
+			if !entry.IsDir() {
+				continue
+			}
+			// Skip known non-rig directories
+			if entry.Name() == "mayor" || entry.Name() == ".beads" || entry.Name() == ".git" {
+				continue
+			}
+			rigPath := filepath.Join(townRoot, entry.Name())
+			beadsDir := filepath.Join(rigPath, ".beads")
+			if _, err := os.Stat(beadsDir); err == nil && !seen[rigPath] {
+				rigDirs = append(rigDirs, rigPath)
+				seen[rigPath] = true
+			}
+		}
+	}
+
+	return rigDirs
+}
--- a/internal/doctor/rig_routes_jsonl_check_test.go
+++ b/internal/doctor/rig_routes_jsonl_check_test.go
@@ -0,0 +1,206 @@
+package doctor
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestRigRoutesJSONLCheck_Run(t *testing.T) {
+	t.Run("no rigs returns OK", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		// Create minimal town structure
+		if err := os.MkdirAll(filepath.Join(tmpDir, "mayor"), 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		check := NewRigRoutesJSONLCheck()
+		ctx := &CheckContext{TownRoot: tmpDir}
+		result := check.Run(ctx)
+
+		if result.Status != StatusOK {
+			t.Errorf("expected StatusOK, got %v: %s", result.Status, result.Message)
+		}
+	})
+
+	t.Run("rig without routes.jsonl returns OK", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		// Create rig with .beads but no routes.jsonl
+		rigBeads := filepath.Join(tmpDir, "myrig", ".beads")
+		if err := os.MkdirAll(rigBeads, 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		check := NewRigRoutesJSONLCheck()
+		ctx := &CheckContext{TownRoot: tmpDir}
+		result := check.Run(ctx)
+
+		if result.Status != StatusOK {
+			t.Errorf("expected StatusOK, got %v: %s", result.Status, result.Message)
+		}
+	})
+
+	t.Run("rig with routes.jsonl warns", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		rigBeads := filepath.Join(tmpDir, "myrig", ".beads")
+		if err := os.MkdirAll(rigBeads, 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create routes.jsonl (any content - will be deleted)
+		if err := os.WriteFile(filepath.Join(rigBeads, "routes.jsonl"), []byte(`{"prefix":"x-","path":"."}`+"\n"), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		check := NewRigRoutesJSONLCheck()
+		ctx := &CheckContext{TownRoot: tmpDir}
+		result := check.Run(ctx)
+
+		if result.Status != StatusWarning {
+			t.Errorf("expected StatusWarning, got %v: %s", result.Status, result.Message)
+		}
+		if len(result.Details) == 0 {
+			t.Error("expected details about the issue")
+		}
+	})
+
+	t.Run("multiple rigs with routes.jsonl reports all", func(t *testing.T) {
+		tmpDir := t.TempDir()
+
+		// Create two rigs with routes.jsonl
+		for _, rigName := range []string{"rig1", "rig2"} {
+			rigBeads := filepath.Join(tmpDir, rigName, ".beads")
+			if err := os.MkdirAll(rigBeads, 0755); err != nil {
+				t.Fatal(err)
+			}
+			if err := os.WriteFile(filepath.Join(rigBeads, "routes.jsonl"), []byte(`{"prefix":"x-","path":"."}`+"\n"), 0644); err != nil {
+				t.Fatal(err)
+			}
+		}
+
+		check := NewRigRoutesJSONLCheck()
+		ctx := &CheckContext{TownRoot: tmpDir}
+		result := check.Run(ctx)
+
+		if result.Status != StatusWarning {
+			t.Errorf("expected StatusWarning, got %v", result.Status)
+		}
+		if len(result.Details) != 2 {
+			t.Errorf("expected 2 details, got %d: %v", len(result.Details), result.Details)
+		}
+	})
+}
+
+func TestRigRoutesJSONLCheck_Fix(t *testing.T) {
+	t.Run("deletes routes.jsonl unconditionally", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		rigBeads := filepath.Join(tmpDir, "myrig", ".beads")
+		if err := os.MkdirAll(rigBeads, 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create routes.jsonl with any content
+		routesPath := filepath.Join(rigBeads, "routes.jsonl")
+		if err := os.WriteFile(routesPath, []byte(`{"id":"test-abc123","title":"Test Issue"}`+"\n"), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		check := NewRigRoutesJSONLCheck()
+		ctx := &CheckContext{TownRoot: tmpDir}
+
+		// Run check first to populate affectedRigs
+		result := check.Run(ctx)
+		if result.Status != StatusWarning {
+			t.Fatalf("expected StatusWarning, got %v", result.Status)
+		}
+
+		// Fix
+		if err := check.Fix(ctx); err != nil {
+			t.Fatalf("Fix() error: %v", err)
+		}
+
+		// Verify routes.jsonl is gone
+		if _, err := os.Stat(routesPath); !os.IsNotExist(err) {
+			t.Error("routes.jsonl should have been deleted")
+		}
+	})
+
+	t.Run("fix is idempotent", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		rigBeads := filepath.Join(tmpDir, "myrig", ".beads")
+		if err := os.MkdirAll(rigBeads, 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		check := NewRigRoutesJSONLCheck()
+		ctx := &CheckContext{TownRoot: tmpDir}
+
+		// First run - should pass (no routes.jsonl)
+		result := check.Run(ctx)
+		if result.Status != StatusOK {
+			t.Fatalf("expected StatusOK, got %v", result.Status)
+		}
+
+		// Fix should be no-op
+		if err := check.Fix(ctx); err != nil {
+			t.Fatalf("Fix() error on clean state: %v", err)
+		}
+	})
+}
+
+func TestRigRoutesJSONLCheck_FindRigDirectories(t *testing.T) {
+	t.Run("finds rigs from multiple sources", func(t *testing.T) {
+		tmpDir := t.TempDir()
+
+		// Create mayor directory
+		if err := os.MkdirAll(filepath.Join(tmpDir, "mayor"), 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create town-level .beads with routes.jsonl
+		townBeads := filepath.Join(tmpDir, ".beads")
+		if err := os.MkdirAll(townBeads, 0755); err != nil {
+			t.Fatal(err)
+		}
+		routes := `{"prefix":"rig1-","path":"rig1/mayor/rig"}` + "\n"
+		if err := os.WriteFile(filepath.Join(townBeads, "routes.jsonl"), []byte(routes), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create rig1 (from routes.jsonl)
+		if err := os.MkdirAll(filepath.Join(tmpDir, "rig1", ".beads"), 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create rig2 (unregistered but has .beads)
+		if err := os.MkdirAll(filepath.Join(tmpDir, "rig2", ".beads"), 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		check := NewRigRoutesJSONLCheck()
+		rigs := check.findRigDirectories(tmpDir)
+
+		if len(rigs) != 2 {
+			t.Errorf("expected 2 rigs, got %d: %v", len(rigs), rigs)
+		}
+	})
+
+	t.Run("excludes mayor and .beads directories", func(t *testing.T) {
+		tmpDir := t.TempDir()
+
+		// Create directories that should be excluded
+		if err := os.MkdirAll(filepath.Join(tmpDir, "mayor", ".beads"), 0755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.MkdirAll(filepath.Join(tmpDir, ".beads"), 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		check := NewRigRoutesJSONLCheck()
+		rigs := check.findRigDirectories(tmpDir)
+
+		if len(rigs) != 0 {
+			t.Errorf("expected 0 rigs (mayor and .beads should be excluded), got %d: %v", len(rigs), rigs)
+		}
+	})
+}
--- a/internal/doctor/routes_check.go
+++ b/internal/doctor/routes_check.go
@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strings"

 	"github.com/steveyegge/gastown/internal/beads"
 	"github.com/steveyegge/gastown/internal/config"
@@ -72,15 +73,32 @@ func (c *RoutesCheck) Run(ctx *CheckContext) *CheckResult {
 		routeByPath[r.Path] = r.Prefix
 	}

+	var details []string
+	var missingTownRoute bool
+
+	// Check town root route exists (hq- -> .)
+	if _, hasTownRoute := routeByPrefix["hq-"]; !hasTownRoute {
+		missingTownRoute = true
+		details = append(details, "Town root route (hq- -> .) is missing")
+	}
+
 	// Load rigs registry
 	rigsPath := filepath.Join(ctx.TownRoot, "mayor", "rigs.json")
 	rigsConfig, err := config.LoadRigsConfig(rigsPath)
 	if err != nil {
-		// No rigs config is fine - just check existing routes are valid
+		// No rigs config - check for missing town route and validate existing routes
+		if missingTownRoute {
+			return &CheckResult{
+				Name:    c.Name(),
+				Status:  StatusWarning,
+				Message: "Town root route is missing",
+				Details: details,
+				FixHint: "Run 'gt doctor --fix' to add missing routes",
+			}
+		}
 		return c.checkRoutesValid(ctx, routes)
 	}

-	var details []string
 	var missingRigs []string
 	var invalidRoutes []string

@@ -137,22 +155,24 @@ func (c *RoutesCheck) Run(ctx *CheckContext) *CheckResult {
 	}

 	// Determine result
-	if len(missingRigs) > 0 || len(invalidRoutes) > 0 {
+	if missingTownRoute || len(missingRigs) > 0 || len(invalidRoutes) > 0 {
 		status := StatusWarning
-		message := ""
+		var messageParts []string

-		if len(missingRigs) > 0 && len(invalidRoutes) > 0 {
-			message = fmt.Sprintf("%d rig(s) missing routes, %d invalid route(s)", len(missingRigs), len(invalidRoutes))
-		} else if len(missingRigs) > 0 {
-			message = fmt.Sprintf("%d rig(s) missing routing entries", len(missingRigs))
-		} else {
-			message = fmt.Sprintf("%d invalid route(s) in routes.jsonl", len(invalidRoutes))
+		if missingTownRoute {
+			messageParts = append(messageParts, "town root route missing")
+		}
+		if len(missingRigs) > 0 {
+			messageParts = append(messageParts, fmt.Sprintf("%d rig(s) missing routes", len(missingRigs)))
+		}
+		if len(invalidRoutes) > 0 {
+			messageParts = append(messageParts, fmt.Sprintf("%d invalid route(s)", len(invalidRoutes)))
 		}

 		return &CheckResult{
 			Name:    c.Name(),
 			Status:  status,
-			Message: message,
+			Message: strings.Join(messageParts, ", "),
 			Details: details,
 			FixHint: "Run 'gt doctor --fix' to add missing routes",
 		}
@@ -220,16 +240,27 @@ func (c *RoutesCheck) Fix(ctx *CheckContext) error {
 		routeMap[r.Prefix] = true
 	}

+	// Ensure town root route exists (hq- -> .)
+	// This is normally created by gt install but may be missing if routes.jsonl was corrupted
+	modified := false
+	if !routeMap["hq-"] {
+		routes = append(routes, beads.Route{Prefix: "hq-", Path: "."})
+		routeMap["hq-"] = true
+		modified = true
+	}
+
 	// Load rigs registry
 	rigsPath := filepath.Join(ctx.TownRoot, "mayor", "rigs.json")
 	rigsConfig, err := config.LoadRigsConfig(rigsPath)
 	if err != nil {
-		// No rigs config, nothing to fix
+		// No rigs config - just write town root route if we added it
+		if modified {
+			return beads.WriteRoutes(beadsDir, routes)
+		}
 		return nil
 	}

 	// Add missing routes for each rig
-	modified := false
 	for rigName, rigEntry := range rigsConfig.Rigs {
 		prefix := ""
 		if rigEntry.BeadsConfig != nil && rigEntry.BeadsConfig.Prefix != "" {
--- a/internal/doctor/routes_check_test.go
+++ b/internal/doctor/routes_check_test.go
@@ -0,0 +1,304 @@
+package doctor
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestRoutesCheck_MissingTownRoute(t *testing.T) {
+	t.Run("detects missing town root route", func(t *testing.T) {
+		tmpDir := t.TempDir()
+
+		// Create .beads directory with routes.jsonl missing the hq- route
+		beadsDir := filepath.Join(tmpDir, ".beads")
+		if err := os.MkdirAll(beadsDir, 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create routes.jsonl with only a rig route (no hq- route)
+		routesPath := filepath.Join(beadsDir, "routes.jsonl")
+		routesContent := `{"prefix": "gt-", "path": "gastown/mayor/rig"}
+`
+		if err := os.WriteFile(routesPath, []byte(routesContent), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create mayor directory
+		if err := os.MkdirAll(filepath.Join(tmpDir, "mayor"), 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		check := NewRoutesCheck()
+		ctx := &CheckContext{TownRoot: tmpDir}
+		result := check.Run(ctx)
+
+		if result.Status != StatusWarning {
+			t.Errorf("expected StatusWarning, got %v: %s", result.Status, result.Message)
+		}
+		// When no rigs.json exists, the message comes from the early return path
+		if result.Message != "Town root route is missing" {
+			t.Errorf("expected 'Town root route is missing', got %s", result.Message)
+		}
+	})
+
+	t.Run("passes when town root route exists", func(t *testing.T) {
+		tmpDir := t.TempDir()
+
+		// Create .beads directory with valid routes.jsonl
+		beadsDir := filepath.Join(tmpDir, ".beads")
+		if err := os.MkdirAll(beadsDir, 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create routes.jsonl with hq- route
+		routesPath := filepath.Join(beadsDir, "routes.jsonl")
+		routesContent := `{"prefix": "hq-", "path": "."}
+`
+		if err := os.WriteFile(routesPath, []byte(routesContent), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create mayor directory
+		if err := os.MkdirAll(filepath.Join(tmpDir, "mayor"), 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		check := NewRoutesCheck()
+		ctx := &CheckContext{TownRoot: tmpDir}
+		result := check.Run(ctx)
+
+		if result.Status != StatusOK {
+			t.Errorf("expected StatusOK, got %v: %s", result.Status, result.Message)
+		}
+	})
+}
+
+func TestRoutesCheck_FixRestoresTownRoute(t *testing.T) {
+	t.Run("fix adds missing town root route", func(t *testing.T) {
+		tmpDir := t.TempDir()
+
+		// Create .beads directory with empty routes.jsonl
+		beadsDir := filepath.Join(tmpDir, ".beads")
+		if err := os.MkdirAll(beadsDir, 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create empty routes.jsonl
+		routesPath := filepath.Join(beadsDir, "routes.jsonl")
+		if err := os.WriteFile(routesPath, []byte(""), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create mayor directory (no rigs.json needed for this test)
+		if err := os.MkdirAll(filepath.Join(tmpDir, "mayor"), 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		check := NewRoutesCheck()
+		ctx := &CheckContext{TownRoot: tmpDir}
+
+		// Run fix
+		if err := check.Fix(ctx); err != nil {
+			t.Fatalf("Fix failed: %v", err)
+		}
+
+		// Verify routes.jsonl now contains hq- route
+		content, err := os.ReadFile(routesPath)
+		if err != nil {
+			t.Fatalf("Failed to read routes.jsonl: %v", err)
+		}
+
+		if len(content) == 0 {
+			t.Error("routes.jsonl is still empty after fix")
+		}
+
+		contentStr := string(content)
+		if contentStr != `{"prefix":"hq-","path":"."}
+` {
+			t.Errorf("unexpected routes.jsonl content: %s", contentStr)
+		}
+
+		// Verify the check now passes
+		result := check.Run(ctx)
+		if result.Status != StatusOK {
+			t.Errorf("expected StatusOK after fix, got %v: %s", result.Status, result.Message)
+		}
+	})
+
+	t.Run("fix preserves existing routes while adding town route", func(t *testing.T) {
+		tmpDir := t.TempDir()
+
+		// Create .beads directory
+		beadsDir := filepath.Join(tmpDir, ".beads")
+		if err := os.MkdirAll(beadsDir, 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create rig directory structure for route validation
+		rigPath := filepath.Join(tmpDir, "myrig", "mayor", "rig", ".beads")
+		if err := os.MkdirAll(rigPath, 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create routes.jsonl with only a rig route (no hq- route)
+		routesPath := filepath.Join(beadsDir, "routes.jsonl")
+		routesContent := `{"prefix": "my-", "path": "myrig/mayor/rig"}
+`
+		if err := os.WriteFile(routesPath, []byte(routesContent), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create mayor directory
+		if err := os.MkdirAll(filepath.Join(tmpDir, "mayor"), 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		check := NewRoutesCheck()
+		ctx := &CheckContext{TownRoot: tmpDir}
+
+		// Run fix
+		if err := check.Fix(ctx); err != nil {
+			t.Fatalf("Fix failed: %v", err)
+		}
+
+		// Verify routes.jsonl now contains both routes
+		content, err := os.ReadFile(routesPath)
+		if err != nil {
+			t.Fatalf("Failed to read routes.jsonl: %v", err)
+		}
+
+		contentStr := string(content)
+		// Should have both the original rig route and the new hq- route
+		if contentStr != `{"prefix":"my-","path":"myrig/mayor/rig"}
+{"prefix":"hq-","path":"."}
+` {
+			t.Errorf("unexpected routes.jsonl content: %s", contentStr)
+		}
+	})
+
+	t.Run("fix does not duplicate existing town route", func(t *testing.T) {
+		tmpDir := t.TempDir()
+
+		// Create .beads directory with valid routes.jsonl
+		beadsDir := filepath.Join(tmpDir, ".beads")
+		if err := os.MkdirAll(beadsDir, 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create routes.jsonl with hq- route already present
+		routesPath := filepath.Join(beadsDir, "routes.jsonl")
+		originalContent := `{"prefix": "hq-", "path": "."}
+`
+		if err := os.WriteFile(routesPath, []byte(originalContent), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create mayor directory
+		if err := os.MkdirAll(filepath.Join(tmpDir, "mayor"), 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		check := NewRoutesCheck()
+		ctx := &CheckContext{TownRoot: tmpDir}
+
+		// Run fix (should be a no-op)
+		if err := check.Fix(ctx); err != nil {
+			t.Fatalf("Fix failed: %v", err)
+		}
+
+		// Verify routes.jsonl is unchanged (no duplicate)
+		content, err := os.ReadFile(routesPath)
+		if err != nil {
+			t.Fatalf("Failed to read routes.jsonl: %v", err)
+		}
+
+		// File should be unchanged - fix doesn't write when no modifications needed
+		if string(content) != originalContent {
+			t.Errorf("routes.jsonl was modified when it shouldn't have been: %s", string(content))
+		}
+	})
+}
+
+func TestRoutesCheck_CorruptedRoutesJsonl(t *testing.T) {
+	t.Run("corrupted routes.jsonl results in empty routes", func(t *testing.T) {
+		tmpDir := t.TempDir()
+
+		// Create .beads directory with corrupted routes.jsonl
+		beadsDir := filepath.Join(tmpDir, ".beads")
+		if err := os.MkdirAll(beadsDir, 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create corrupted routes.jsonl (malformed lines are skipped by LoadRoutes)
+		routesPath := filepath.Join(beadsDir, "routes.jsonl")
+		if err := os.WriteFile(routesPath, []byte("not valid json"), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create mayor directory
+		if err := os.MkdirAll(filepath.Join(tmpDir, "mayor"), 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		check := NewRoutesCheck()
+		ctx := &CheckContext{TownRoot: tmpDir}
+		result := check.Run(ctx)
+
+		// Corrupted/malformed lines are skipped, resulting in empty routes
+		// This triggers the "Town root route is missing" warning
+		if result.Status != StatusWarning {
+			t.Errorf("expected StatusWarning, got %v: %s", result.Status, result.Message)
+		}
+		if result.Message != "Town root route is missing" {
+			t.Errorf("expected 'Town root route is missing', got %s", result.Message)
+		}
+	})
+
+	t.Run("fix regenerates corrupted routes.jsonl with town route", func(t *testing.T) {
+		tmpDir := t.TempDir()
+
+		// Create .beads directory with corrupted routes.jsonl
+		beadsDir := filepath.Join(tmpDir, ".beads")
+		if err := os.MkdirAll(beadsDir, 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create corrupted routes.jsonl
+		routesPath := filepath.Join(beadsDir, "routes.jsonl")
+		if err := os.WriteFile(routesPath, []byte("not valid json"), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create mayor directory
+		if err := os.MkdirAll(filepath.Join(tmpDir, "mayor"), 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		check := NewRoutesCheck()
+		ctx := &CheckContext{TownRoot: tmpDir}
+
+		// Run fix
+		if err := check.Fix(ctx); err != nil {
+			t.Fatalf("Fix failed: %v", err)
+		}
+
+		// Verify routes.jsonl now contains hq- route
+		content, err := os.ReadFile(routesPath)
+		if err != nil {
+			t.Fatalf("Failed to read routes.jsonl: %v", err)
+		}
+
+		contentStr := string(content)
+		if contentStr != `{"prefix":"hq-","path":"."}
+` {
+			t.Errorf("unexpected routes.jsonl content after fix: %s", contentStr)
+		}
+
+		// Verify the check now passes
+		result := check.Run(ctx)
+		if result.Status != StatusOK {
+			t.Errorf("expected StatusOK after fix, got %v: %s", result.Status, result.Message)
+		}
+	})
+}