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.