Dependency graph vizualization

docs/adr-dependency-graph-visualization-framework.md

@@ -0,0 +1,40 @@
+# ADR: Dependency Graph Visualization Framework
+
+Status: accepted
+
+Context: dependency-aware scope propagation needs an interactive graph view where
+curators can inspect fact-to-scope paths, stale nodes, evidence bridges,
+same-layer normalization signals, and review recommendations. The visualization
+must support practical graph exploration rather than only a static diagram.
+
+Decision: use Cytoscape.js for the interactive dependency graph visualization.
+
+Cytoscape.js is selected because it is graph-native: it supports pan, zoom,
+selection, layouts, node and edge styling, filtering, and path highlighting in a
+way that maps directly to the dependency model. It can be embedded inside the
+existing FastAPI-served UI without requiring a full frontend rewrite.
+
+Variants considered:
+
+- React Flow: strong for polished node-card workflows and editable diagrams, but
+  it is more flow-builder-oriented than graph-analysis-oriented. Dense
+  dependency maps and impact-path exploration would require more custom layout
+  discipline.
+- D3: maximum visual control and excellent for bespoke animated propagation, but
+  it carries the highest implementation and maintenance cost. It is too easy to
+  build a compelling custom view that becomes hard to evolve.
+- Mermaid: lightweight and useful for static docs or fallback exports, but not
+  interactive enough for curator workflows that need selection, filtering,
+  pan/zoom, and path drilldown.
+
+Consequences:
+
+- The first visualization implementation should expose graph data as nodes and
+  edges that Cytoscape can consume directly.
+- UI work can remain incremental: a single graph route and JSON endpoint can be
+  added before broader review-workflow screens.
+- Cytoscape styling should encode repo-scoping semantics, not generic graph
+  decoration: node kind, edge strength, dependency type, staleness, and
+  same-layer flags should be visible.
+- Mermaid may still be useful as an export or documentation format, but it is
+  not the primary interactive implementation.

docs/dependency-aware-scope-propagation.md

@@ -47,6 +47,18 @@ The current implementation exposes this through `RegistryService`:
 The impact result includes changed fact keys, impacted items, reason chains,
 maximum propagation depth, breadth, and whether the root scope was affected.
 
+## Interactive Visualization
+
+The accepted implementation framework for the interactive graph view is
+Cytoscape.js. See
+`docs/adr-dependency-graph-visualization-framework.md` for the decision and the
+tradeoffs against React Flow, D3, and Mermaid.
+
+The first UI implementation exposes `/repos/{repository_id}/dependency-graph`
+as a Cytoscape-ready JSON payload and `/ui/repos/{repository_id}/dependency-graph`
+as the graph page. The page supports full graph, impact-only, and selected-path
+views with a detail panel for selected nodes and edges.
+
 ## Metrics
 
 Propagation depth says how far a source change bubbled up. Propagation breadth