feat: add dependency visualization to roadmap features

CHANGELOG.md

@@ -1,3 +1,21 @@
+## [Unreleased]
+
+### Added
+- **Roadmap:** Dependency visualization in all roadmap views
+- **Roadmap:** Bidirectional dependency display (dependencies and reverse dependencies)
+- **Roadmap:** Dependency validation with circular and missing dependency detection
+- **Roadmap:** Clickable dependency chips with detail side panel
+- **Roadmap:** Dependency status indicators (completed, in-progress, planned, missing)
+- **Roadmap:** Reverse dependency calculation and display
+
+### Changed
+- Enhanced roadmap data model with dependency metadata
+- Improved roadmap refresh with dependency preservation (TODO in future phase)
+
+### Fixed
+- Duplicate circular dependency path reporting in validator
+- Missing i18n namespace registration for roadmap translations
+
 ## 2.7.2 - Stability & Performance Enhancements
 
 ### ✨ New Features

apps/backend/runners/roadmap/models.py

@@ -26,3 +26,18 @@ class RoadmapConfig:
     model: str = "sonnet"  # Changed from "opus" (fix #433)
     refresh: bool = False  # Force regeneration even if roadmap exists
     enable_competitor_analysis: bool = False  # Enable competitor analysis phase
+
+
+@dataclass
+class RoadmapFeature:
+    """A feature in the roadmap with dependencies."""
+
+    id: str
+    title: str
+    description: str
+    dependencies: list[str]  # List of feature IDs this feature depends on
+    status: str  # e.g., "planned", "in_progress", "completed"
+    reverse_dependencies: list[str] | None = (
+        None  # List of feature IDs that depend on this feature
+    )
+    dependency_validation: dict | None = None  # Validation metadata for dependencies

apps/backend/runners/roadmap/orchestrator.py

@@ -9,15 +9,24 @@
 from pathlib import Path
 
 from client import create_client
-from debug import debug, debug_error, debug_section, debug_success
+from debug import (
+    debug,
+    debug_detailed,
+    debug_error,
+    debug_section,
+    debug_success,
+    debug_warning,
+)
 from init import init_auto_claude_dir
 from phase_config import get_thinking_budget
 from ui import Icons, box, icon, muted, print_section, print_status
 
 from .competitor_analyzer import CompetitorAnalyzer
 from .executor import AgentExecutor, ScriptExecutor
 from .graph_integration import GraphHintsProvider
+from .models import RoadmapFeature
 from .phases import DiscoveryPhase, FeaturesPhase, ProjectIndexPhase
+from .validators import DependencyValidator
 
 
 class RoadmapOrchestrator:
@@ -188,10 +197,124 @@ async def run(self) -> bool:
             return False
         debug_success("roadmap_orchestrator", "Phase 3 complete")
 
+        # Enrich features with dependency validation
+        debug(
+            "roadmap_orchestrator",
+            "Enriching features with dependency validation",
+        )
+        self._enrich_roadmap_features()
+        debug_success("roadmap_orchestrator", "Feature enrichment complete")
+
         # Summary
         self._print_summary()
         return True
 
+    def _enrich_roadmap_features(self):
+        """Enrich features with dependency validation and reverse dependencies."""
+        roadmap_file = self.output_dir / "roadmap.json"
+        if not roadmap_file.exists():
+            debug_warning(
+                "roadmap_orchestrator", "Roadmap file not found for enrichment"
+            )
+            return None
+
+        try:
+            with open(roadmap_file) as f:
+                roadmap_data = json.load(f)
+
+            features_data = roadmap_data.get("features", [])
+            if not features_data:
+                debug_warning("roadmap_orchestrator", "No features found in roadmap")
+                return None
+
+            # Convert dict features to RoadmapFeature objects
+            features = []
+            for feat_dict in features_data:
+                feature = RoadmapFeature(
+                    id=feat_dict.get("id", ""),
+                    title=feat_dict.get("title", ""),
+                    description=feat_dict.get("description", ""),
+                    dependencies=feat_dict.get("dependencies", []),
+                    status=feat_dict.get("status", "planned"),
+                )
+                features.append(feature)
+
+            # Run validator
+            validator = DependencyValidator()
+            validation_result = validator.validate_all(features)
+
+            debug_detailed(
+                "roadmap_orchestrator",
+                "Validation results",
+                has_missing=validation_result.has_missing,
+                has_circular=validation_result.has_circular,
+                missing_ids=validation_result.missing_ids,
+                circular_paths_count=len(validation_result.circular_paths),
+            )
+
+            # Pre-compute all dependent IDs for efficient lookup
+            all_dependent_ids = {dep for f in features for dep in f.dependencies}
+
+            # Create a mapping of feature IDs to feature data for O(1) lookup
+            # This avoids O(N^2) complexity from repeated linear searches
+            features_by_id = {f.get("id"): f for f in features_data}
+
+            # Enrich each feature
+            enriched_features = []
+            for feature in features:
+                # Find the original feature dict using O(1) lookup
+                feat_dict = features_by_id.get(feature.id, {})
+
+                # Add reverse dependencies (snake_case for JSON, IPC handlers convert to camelCase)
+                feat_dict["reverse_dependencies"] = (
+                    validation_result.reverse_deps_map.get(feature.id, [])
+                )
+
+                # Add validation metadata for features with dependencies
+                if feature.id in all_dependent_ids or len(feature.dependencies) > 0:
+                    feat_dict["dependency_validation"] = {
+                        "has_missing": validation_result.has_missing,
+                        "has_circular": validation_result.has_circular,
+                        "missing_ids": [
+                            mid
+                            for mid in validation_result.missing_ids
+                            if mid in feature.dependencies
+                        ],
+                        "circular_paths": [
+                            cp
+                            for cp in validation_result.circular_paths
+                            if feature.id in cp
+                        ],
+                    }
+
+                enriched_features.append(feat_dict)
+
+            # Update roadmap with enriched features
+            roadmap_data["features"] = enriched_features
+
+            # Write back to file
+            with open(roadmap_file, "w") as f:
+                json.dump(roadmap_data, f, indent=2)
+
+            debug_success(
+                "roadmap_orchestrator",
+                "Enriched roadmap features",
+                features_count=len(enriched_features),
+            )
+            return True
+
+        except Exception as e:
+            # Log enrichment failure - surface error to user rather than hiding it
+            # Enrichment adds reverse dependencies and validation metadata that users expect
+            debug_error(
+                "roadmap_orchestrator",
+                "Failed to enrich roadmap features",
+                error=str(e),
+            )
+            print_status("Feature enrichment failed", "error")
+            print(f"  {muted('Error:')} {e}")
+            return False
+
     def _print_summary(self):
         """Print the final roadmap generation summary."""
         roadmap_file = self.output_dir / "roadmap.json"

apps/backend/runners/roadmap/validators.py

@@ -0,0 +1,149 @@
+"""
+Dependency validators for roadmap features.
+"""
+
+from dataclasses import dataclass
+
+# Import RoadmapFeature based on execution context
+# When run as module: use relative import
+# When run as script: use absolute import
+if __package__:
+    from .models import RoadmapFeature
+else:
+    from runners.roadmap.models import RoadmapFeature
+
+
+@dataclass
+class ValidationResult:
+    """Result of dependency validation."""
+
+    has_missing: bool
+    has_circular: bool
+    missing_ids: list[str]
+    circular_paths: list[list[str]]
+    reverse_deps_map: dict[str, list[str]]
+
+
+class DependencyValidator:
+    """Validates and enriches feature dependencies."""
+
+    def validate_all(self, features: list[RoadmapFeature]) -> ValidationResult:
+        """
+        Validates all dependencies in the roadmap.
+
+        Args:
+            features: List of features to validate
+
+        Returns:
+            ValidationResult with validation metadata
+        """
+        # Find missing dependencies
+        missing_ids = self._find_missing_deps(features)
+
+        # Detect circular dependencies
+        circular_paths = self._detect_circular_deps(features)
+
+        # Calculate reverse dependencies
+        reverse_deps_map = self._calculate_reverse_deps(features)
+
+        return ValidationResult(
+            has_missing=len(missing_ids) > 0,
+            has_circular=len(circular_paths) > 0,
+            missing_ids=missing_ids,
+            circular_paths=circular_paths,
+            reverse_deps_map=reverse_deps_map,
+        )
+
+    def _find_missing_deps(self, features: list[RoadmapFeature]) -> list[str]:
+        """Find dependencies that reference non-existent features."""
+        valid_ids = {f.id for f in features}
+        missing = set()
+
+        for feature in features:
+            for dep_id in feature.dependencies:
+                if dep_id not in valid_ids:
+                    missing.add(dep_id)
+
+        return sorted(missing)
+
+    def _detect_circular_deps(self, features: list[RoadmapFeature]) -> list[list[str]]:
+        """
+        Detect circular dependencies using three-color DFS.
+
+        Uses WHITE (0), GRAY (1), BLACK (2) marking:
+        - WHITE: Not yet visited
+        - GRAY: Currently being processed (in current path)
+        - BLACK: Fully processed
+
+        Time complexity: O(V + E) where V = features, E = dependencies
+        """
+        graph = {f.id: f.dependencies for f in features}
+        circular_paths = []
+        seen_cycles = set()  # Track normalized cycles for deduplication
+
+        # Three-color DFS: WHITE=0, GRAY=1, BLACK=2
+        WHITE, GRAY, BLACK = 0, 1, 2
+        color = {f.id: WHITE for f in features}
+
+        def normalize_cycle(cycle: list[str]) -> str:
+            """Rotate cycle to start from smallest ID for deduplication."""
+            if not cycle or len(cycle) < 2:
+                return ""
+            # Remove last element (duplicate of first)
+            cycle_without_dup = cycle[:-1]
+            min_idx = cycle_without_dup.index(min(cycle_without_dup))
+            # Rotate to start from minimal element
+            rotated = cycle_without_dup[min_idx:] + cycle_without_dup[:min_idx]
+            return ",".join(rotated)
+
+        def dfs(node: str, path: list[str]) -> None:
+            """DFS with backtracking - O(V + E) complexity."""
+            color[node] = GRAY
+            path.append(node)
+
+            for neighbor in graph.get(node, []):
+                if neighbor not in graph:
+                    continue  # Skip non-existent nodes
+
+                if color[neighbor] == GRAY:
+                    # Found a cycle - neighbor is in current path
+                    cycle_start = path.index(neighbor)
+                    cycle = path[cycle_start:] + [neighbor]
+                    # Normalize and deduplicate
+                    normalized = normalize_cycle(cycle)
+                    if normalized not in seen_cycles:
+                        seen_cycles.add(normalized)
+                        circular_paths.append(cycle)
+                elif color[neighbor] == WHITE:
+                    # Recurse into unvisited nodes
+                    dfs(neighbor, path)
+
+            # Backtrack
+            path.pop()
+            color[node] = BLACK
+
+        # Run DFS from each unvisited node
+        for feature_id in graph:
+            if color[feature_id] == WHITE:
+                dfs(feature_id, [])
+
+        return circular_paths
+
+    def _calculate_reverse_deps(
+        self, features: list[RoadmapFeature]
+    ) -> dict[str, list[str]]:
+        """Calculate which features depend on each feature."""
+        reverse_deps: dict[str, list[str]] = {}
+
+        # Initialize all features with empty list
+        for feature in features:
+            reverse_deps[feature.id] = []
+
+        # Build reverse dependency map
+        for feature in features:
+            for dep_id in feature.dependencies:
+                if dep_id not in reverse_deps:
+                    reverse_deps[dep_id] = []
+                reverse_deps[dep_id].append(feature.id)
+
+        return reverse_deps

apps/backend/runners/roadmap_runner.py

@@ -32,7 +32,7 @@
 from debug import debug, debug_error, debug_warning
 
 # Import from refactored roadmap package
-from roadmap import RoadmapOrchestrator
+from runners.roadmap import RoadmapOrchestrator
 
 
 def main():

apps/frontend/src/main/ipc-handlers/roadmap-handlers.ts

@@ -57,6 +57,7 @@ export function registerRoadmapHandlers(
     async (_, projectId: string): Promise<IPCResult<Roadmap | null>> => {
       const project = projectStore.getProject(projectId);
       if (!project) {
+        debugLog('[Roadmap GET] Project not found:', projectId);
         return { success: false, error: 'Project not found' };
       }
 
@@ -170,6 +171,13 @@ export function registerRoadmapHandlers(
             impact: feature.impact || 'medium',
             phaseId: feature.phase_id,
             dependencies: feature.dependencies || [],
+            reverseDependencies: (feature.reverse_dependencies as string[]) || undefined,
+            dependencyValidation: feature.dependency_validation as {
+              hasMissing: boolean;
+              hasCircular: boolean;
+              missingIds: string[];
+              circularPaths: string[][];
+            } | undefined,
             status: feature.status || 'under_review',
             acceptanceCriteria: feature.acceptance_criteria || [],
             userStories: feature.user_stories || [],
@@ -377,6 +385,8 @@ export function registerRoadmapHandlers(
           impact: feature.impact,
           phase_id: feature.phaseId,
           dependencies: feature.dependencies || [],
+          reverse_dependencies: feature.reverseDependencies || [],
+          dependency_validation: feature.dependencyValidation || undefined,
           status: feature.status,
           acceptance_criteria: feature.acceptanceCriteria || [],
           user_stories: feature.userStories || [],