feat: add cross-project dependency support - config and external: prefix (bd-66w1, bd-om4a)

Config (bd-66w1):
- Add external_projects config for mapping project names to paths
- Add GetExternalProjects() and ResolveExternalProjectPath() functions
- Add config documentation and tests

External deps (bd-om4a):
- bd dep add accepts external:project:capability syntax
- External refs stored as-is in dependencies table
- GetBlockedIssues includes external deps in blocked_by list
- blocked_issues_cache includes external dependencies
- Add validation and parsing helpers for external refs

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

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

internal/config/config.go

@@ -120,6 +120,10 @@ func Initialize() error {
 	// Maps directory patterns to labels for automatic filtering in monorepos
 	v.SetDefault("directory.labels", map[string]string{})
 
+	// External projects for cross-project dependency resolution (bd-h807)
+	// Maps project names to paths for resolving external: blocked_by references
+	v.SetDefault("external_projects", map[string]string{})
+
 	// Read config file if it was found
 	if configFileSet {
 		if err := v.ReadInConfig(); err != nil {
@@ -263,6 +267,43 @@ func GetMultiRepoConfig() *MultiRepoConfig {
 	}
 }
 
+// GetExternalProjects returns the external_projects configuration.
+// Maps project names to paths for cross-project dependency resolution.
+// Example config.yaml:
+//
+//	external_projects:
+//	  beads: ../beads
+//	  gastown: /absolute/path/to/gastown
+func GetExternalProjects() map[string]string {
+	return GetStringMapString("external_projects")
+}
+
+// ResolveExternalProjectPath resolves a project name to its absolute path.
+// Returns empty string if project not configured or path doesn't exist.
+func ResolveExternalProjectPath(projectName string) string {
+	projects := GetExternalProjects()
+	path, ok := projects[projectName]
+	if !ok {
+		return ""
+	}
+
+	// Expand relative paths from config file location or cwd
+	if !filepath.IsAbs(path) {
+		cwd, err := os.Getwd()
+		if err != nil {
+			return ""
+		}
+		path = filepath.Join(cwd, path)
+	}
+
+	// Verify path exists
+	if _, err := os.Stat(path); err != nil {
+		return ""
+	}
+
+	return path
+}
+
 // GetIdentity resolves the user's identity for messaging.
 // Priority chain:
 //  1. flagValue (if non-empty, from --identity flag)

internal/config/config_test.go

@@ -451,6 +451,146 @@ func TestGetIdentity(t *testing.T) {
 	}
 }
 
+func TestGetExternalProjects(t *testing.T) {
+	err := Initialize()
+	if err != nil {
+		t.Fatalf("Initialize() returned error: %v", err)
+	}
+
+	// Test default (empty map)
+	got := GetExternalProjects()
+	if got == nil {
+		t.Error("GetExternalProjects() returned nil, want empty map")
+	}
+	if len(got) != 0 {
+		t.Errorf("GetExternalProjects() = %v, want empty map", got)
+	}
+
+	// Test with Set
+	Set("external_projects", map[string]string{
+		"beads":   "../beads",
+		"gastown": "/absolute/path/to/gastown",
+	})
+
+	got = GetExternalProjects()
+	if len(got) != 2 {
+		t.Errorf("GetExternalProjects() has %d items, want 2", len(got))
+	}
+	if got["beads"] != "../beads" {
+		t.Errorf("GetExternalProjects()[beads] = %q, want \"../beads\"", got["beads"])
+	}
+	if got["gastown"] != "/absolute/path/to/gastown" {
+		t.Errorf("GetExternalProjects()[gastown] = %q, want \"/absolute/path/to/gastown\"", got["gastown"])
+	}
+}
+
+func TestGetExternalProjectsFromConfig(t *testing.T) {
+	// Create a temporary directory for config file
+	tmpDir := t.TempDir()
+
+	// Create a config file with external_projects
+	configContent := `
+external_projects:
+  beads: ../beads
+  gastown: /path/to/gastown
+  other: ./relative/path
+`
+	beadsDir := filepath.Join(tmpDir, ".beads")
+	if err := os.MkdirAll(beadsDir, 0750); err != nil {
+		t.Fatalf("failed to create .beads directory: %v", err)
+	}
+
+	configPath := filepath.Join(beadsDir, "config.yaml")
+	if err := os.WriteFile(configPath, []byte(configContent), 0600); err != nil {
+		t.Fatalf("failed to write config file: %v", err)
+	}
+
+	// Change to tmp directory
+	t.Chdir(tmpDir)
+
+	// Initialize viper
+	err := Initialize()
+	if err != nil {
+		t.Fatalf("Initialize() returned error: %v", err)
+	}
+
+	// Test that external_projects is loaded correctly
+	got := GetExternalProjects()
+	if len(got) != 3 {
+		t.Errorf("GetExternalProjects() has %d items, want 3", len(got))
+	}
+	if got["beads"] != "../beads" {
+		t.Errorf("GetExternalProjects()[beads] = %q, want \"../beads\"", got["beads"])
+	}
+	if got["gastown"] != "/path/to/gastown" {
+		t.Errorf("GetExternalProjects()[gastown] = %q, want \"/path/to/gastown\"", got["gastown"])
+	}
+	if got["other"] != "./relative/path" {
+		t.Errorf("GetExternalProjects()[other] = %q, want \"./relative/path\"", got["other"])
+	}
+}
+
+func TestResolveExternalProjectPath(t *testing.T) {
+	// Create a temporary directory structure
+	tmpDir := t.TempDir()
+
+	// Create a project directory to resolve to
+	projectDir := filepath.Join(tmpDir, "beads-project")
+	if err := os.MkdirAll(projectDir, 0750); err != nil {
+		t.Fatalf("failed to create project directory: %v", err)
+	}
+
+	// Create config file
+	beadsDir := filepath.Join(tmpDir, ".beads")
+	if err := os.MkdirAll(beadsDir, 0750); err != nil {
+		t.Fatalf("failed to create .beads directory: %v", err)
+	}
+
+	configContent := `
+external_projects:
+  beads: beads-project
+  missing: nonexistent-path
+  absolute: ` + projectDir + `
+`
+	configPath := filepath.Join(beadsDir, "config.yaml")
+	if err := os.WriteFile(configPath, []byte(configContent), 0600); err != nil {
+		t.Fatalf("failed to write config file: %v", err)
+	}
+
+	// Change to tmp directory
+	t.Chdir(tmpDir)
+
+	// Initialize viper
+	err := Initialize()
+	if err != nil {
+		t.Fatalf("Initialize() returned error: %v", err)
+	}
+
+	// Test resolving a relative path that exists
+	got := ResolveExternalProjectPath("beads")
+	if got != projectDir {
+		t.Errorf("ResolveExternalProjectPath(beads) = %q, want %q", got, projectDir)
+	}
+
+	// Test resolving a path that doesn't exist
+	got = ResolveExternalProjectPath("missing")
+	if got != "" {
+		t.Errorf("ResolveExternalProjectPath(missing) = %q, want empty string", got)
+	}
+
+	// Test resolving a project that isn't configured
+	got = ResolveExternalProjectPath("unknown")
+	if got != "" {
+		t.Errorf("ResolveExternalProjectPath(unknown) = %q, want empty string", got)
+	}
+
+	// Test resolving an absolute path
+	got = ResolveExternalProjectPath("absolute")
+	if got != projectDir {
+		t.Errorf("ResolveExternalProjectPath(absolute) = %q, want %q", got, projectDir)
+	}
+}
+
 func TestGetIdentityFromConfig(t *testing.T) {
 	// Create a temporary directory for config file
 	tmpDir := t.TempDir()

internal/storage/sqlite/blocked_cache.go

@@ -11,6 +11,7 @@
 // The blocked_issues_cache table stores issue_id values for all issues that are currently
 // blocked. An issue is blocked if:
 //   - It has a 'blocks' dependency on an open/in_progress/blocked issue (direct blocking)
+//   - It has a 'blocks' dependency on an external:* reference (cross-project blocking, bd-om4a)
 //   - Its parent is blocked and it's connected via 'parent-child' dependency (transitive blocking)
 //
 // The cache is maintained automatically by invalidating and rebuilding whenever:
@@ -112,16 +113,27 @@ func (s *SQLiteStorage) rebuildBlockedCache(ctx context.Context, exec execer) er
 	}
 
 	// Rebuild using the recursive CTE logic
+	// Includes both local blockers (open issues) and external refs (bd-om4a)
 	query := `
 		INSERT INTO blocked_issues_cache (issue_id)
 		WITH RECURSIVE
 		  -- Step 1: Find issues blocked directly by dependencies
+		  -- Includes both local blockers (open issues) and external references
 		  blocked_directly AS (
+		    -- Local blockers: issues with open status
 		    SELECT DISTINCT d.issue_id
 		    FROM dependencies d
 		    JOIN issues blocker ON d.depends_on_id = blocker.id
 		    WHERE d.type = 'blocks'
 		      AND blocker.status IN ('open', 'in_progress', 'blocked', 'deferred')
+
+		    UNION
+
+		    -- External blockers: always blocking until resolved (bd-om4a)
+		    SELECT DISTINCT d.issue_id
+		    FROM dependencies d
+		    WHERE d.type = 'blocks'
+		      AND d.depends_on_id LIKE 'external:%'
 		  ),
 
 		  -- Step 2: Propagate blockage to all descendants via parent-child

internal/storage/sqlite/ready.go

@@ -274,12 +274,17 @@ func (s *SQLiteStorage) GetStaleIssues(ctx context.Context, filter types.StaleFi
 
 // GetBlockedIssues returns issues that are blocked by dependencies or have status=blocked
 // Note: Pinned issues are excluded from the output (beads-ei4)
+// Note: Includes external: references in blocked_by list (bd-om4a)
 func (s *SQLiteStorage) GetBlockedIssues(ctx context.Context) ([]*types.BlockedIssue, error) {
 	// Use UNION to combine:
 	// 1. Issues with open/in_progress/blocked status that have dependency blockers
 	// 2. Issues with status=blocked (even if they have no dependency blockers)
 	// Use GROUP_CONCAT to get all blocker IDs in a single query (no N+1)
 	// Exclude pinned issues (beads-ei4)
+	//
+	// For blocked_by_count and blocker_ids:
+	// - Count local blockers (open issues) + external refs (external:*)
+	// - External refs are always considered "open" until resolved (bd-om4a)
 	rows, err := s.db.QueryContext(ctx, `
 		SELECT
 		    i.id, i.title, i.description, i.design, i.acceptance_criteria, i.notes,
@@ -290,16 +295,22 @@ func (s *SQLiteStorage) GetBlockedIssues(ctx context.Context) ([]*types.BlockedI
 		FROM issues i
 		LEFT JOIN dependencies d ON i.id = d.issue_id
 		    AND d.type = 'blocks'
-		    AND EXISTS (
-		        SELECT 1 FROM issues blocker
-		        WHERE blocker.id = d.depends_on_id
-		        AND blocker.status IN ('open', 'in_progress', 'blocked', 'deferred')
+		    AND (
+		        -- Local blockers: must be open/in_progress/blocked/deferred
+		        EXISTS (
+		            SELECT 1 FROM issues blocker
+		            WHERE blocker.id = d.depends_on_id
+		            AND blocker.status IN ('open', 'in_progress', 'blocked', 'deferred')
+		        )
+		        -- External refs: always included (resolution happens at query time)
+		        OR d.depends_on_id LIKE 'external:%'
 		    )
 		WHERE i.status IN ('open', 'in_progress', 'blocked', 'deferred')
 		  AND i.pinned = 0
 		  AND (
 		      i.status = 'blocked'
 		      OR i.status = 'deferred'
+		      -- Has local open blockers
 		      OR EXISTS (
 		          SELECT 1 FROM dependencies d2
 		          JOIN issues blocker ON d2.depends_on_id = blocker.id
@@ -307,6 +318,13 @@ func (s *SQLiteStorage) GetBlockedIssues(ctx context.Context) ([]*types.BlockedI
 		            AND d2.type = 'blocks'
 		            AND blocker.status IN ('open', 'in_progress', 'blocked', 'deferred')
 		      )
+		      -- Has external blockers (always considered blocking until resolved)
+		      OR EXISTS (
+		          SELECT 1 FROM dependencies d3
+		          WHERE d3.issue_id = i.id
+		            AND d3.type = 'blocks'
+		            AND d3.depends_on_id LIKE 'external:%'
+		      )
 		  )
 		GROUP BY i.id
 		ORDER BY i.priority ASC