ref-agents 1.0.0__py3-none-any.whl

ref_agents/tools/context_graph.py

@@ -0,0 +1,839 @@
+"""Context Graph for REF-Agents.
+
+NetworkX-based graph for tracking relationships between:
+- Decisions
+- Patterns
+- Files
+- Issues
+- Agent sessions
+- Stories
+
+Provides causality chains and impact analysis for agent context.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Literal
+
+import networkx as nx
+
+from ref_agents.utils.git_utils import find_project_root
+
+# Valid node and edge types
+NodeType = Literal[
+    "decision",
+    "pattern",
+    "file",
+    "issue",
+    "agent_session",
+    "story",
+    "module",
+    "class",
+    "function",
+]
+EdgeType = Literal[
+    "led_to",
+    "affects",
+    "discovered_by",
+    "applies_to",
+    "supersedes",
+    "depends_on",
+    "imports",
+    "calls",
+    "inherits",
+    "contains",
+]
+
+# AST-origin node types — stored in .ref_cache/ast_graph.json, regenerable
+AST_NODE_TYPES: set[str] = {"module", "class", "function", "file"}
+
+VALID_NODE_TYPES: set[str] = {
+    "decision",
+    "pattern",
+    "file",
+    "issue",
+    "agent_session",
+    "story",
+    "module",
+    "class",
+    "function",
+}
+VALID_EDGE_TYPES: set[str] = {
+    "led_to",
+    "affects",
+    "discovered_by",
+    "applies_to",
+    "supersedes",
+    "depends_on",
+    "imports",
+    "calls",
+    "inherits",
+    "contains",
+}
+
+GRAPH_FILENAME = "context_graph.json"
+
+
+@dataclass
+class ContextNode:
+    """Node in the context graph."""
+
+    id: str
+    node_type: NodeType
+    content: str
+    timestamp: str = field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+    story_id: str = ""
+    # "ast" = extracted by tree-sitter (regenerable); "context" = human/agent-authored
+    origin: str = "context"
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "id": self.id,
+            "node_type": self.node_type,
+            "content": self.content,
+            "timestamp": self.timestamp,
+            "story_id": self.story_id,
+            "origin": self.origin,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ContextNode:
+        """Create from dictionary."""
+        return cls(
+            id=data["id"],
+            node_type=data["node_type"],
+            content=data["content"],
+            timestamp=data.get("timestamp", ""),
+            story_id=data.get("story_id", ""),
+            origin=data.get("origin", "context"),
+            metadata=data.get("metadata", {}),
+        )
+
+
+@dataclass
+class ContextEdge:
+    """Edge in the context graph."""
+
+    from_id: str
+    to_id: str
+    edge_type: EdgeType
+    timestamp: str = field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+    # 1.0 = certain (AST-extracted or human), 0.5–0.9 = inferred (scanner/git/LLM)
+    confidence: float = 1.0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "from_id": self.from_id,
+            "to_id": self.to_id,
+            "edge_type": self.edge_type,
+            "timestamp": self.timestamp,
+            "confidence": self.confidence,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ContextEdge:
+        """Create from dictionary."""
+        return cls(
+            from_id=data["from_id"],
+            to_id=data["to_id"],
+            edge_type=data["edge_type"],
+            timestamp=data.get("timestamp", ""),
+            confidence=float(data.get("confidence", 1.0)),
+            metadata=data.get("metadata", {}),
+        )
+
+
+class ContextGraph:
+    """Directed graph representing the codebase context and decision history."""
+
+    def __init__(self, root: Path | None = None):
+        self._root = root or find_project_root() or Path.cwd()
+
+        # Primary storage (Dashboards, Recovery)
+        self._primary_dir = self._root / "ref-reports"
+        self._primary_file = self._primary_dir / GRAPH_FILENAME
+
+        # Cache storage (Runtime performance)
+        self._cache_dir = self._root / ".ref_cache"
+        self._cache_file = self._cache_dir / GRAPH_FILENAME
+
+        self._graph = nx.DiGraph()
+
+    @property
+    def node_count(self) -> int:
+        """Number of nodes in graph."""
+        return self._graph.number_of_nodes()
+
+    @property
+    def edge_count(self) -> int:
+        """Number of edges in graph."""
+        return self._graph.number_of_edges()
+
+    def add_node(self, node: ContextNode) -> None:
+        """Add a node to the graph.
+
+        Args:
+            node: ContextNode to add.
+
+        Raises:
+            ValueError: If node_type is invalid.
+        """
+        if node.node_type not in VALID_NODE_TYPES:
+            raise ValueError(
+                f"Invalid node_type: {node.node_type}. Must be one of {VALID_NODE_TYPES}"
+            )
+
+        self._graph.add_node(node.id, **node.to_dict())
+
+    def add_edge(  # noqa: PLR0913  # TECH_DEBT: refactor to TypedDict — STORY-046
+        self,
+        from_id: str,
+        to_id: str,
+        edge_type: EdgeType,
+        metadata: dict[str, Any] | None = None,
+        confidence: float = 1.0,
+    ) -> None:
+        """Add an edge between two nodes.
+
+        Args:
+            from_id: Source node ID.
+            to_id: Target node ID.
+            edge_type: Type of relationship.
+            metadata: Optional edge metadata.
+            confidence: Certainty of relationship (1.0=certain, 0.5=inferred).
+
+        Raises:
+            ValueError: If edge_type is invalid or nodes don't exist.
+        """
+        if edge_type not in VALID_EDGE_TYPES:
+            raise ValueError(
+                f"Invalid edge_type: {edge_type}. Must be one of {VALID_EDGE_TYPES}"
+            )
+
+        if from_id not in self._graph:
+            raise ValueError(f"Source node not found: {from_id}")
+        if to_id not in self._graph:
+            raise ValueError(f"Target node not found: {to_id}")
+
+        edge = ContextEdge(
+            from_id=from_id,
+            to_id=to_id,
+            edge_type=edge_type,
+            confidence=confidence,
+            metadata=metadata or {},
+        )
+        self._graph.add_edge(from_id, to_id, **edge.to_dict())
+
+    def get_node(self, node_id: str) -> ContextNode | None:
+        """Get a node by ID.
+
+        Args:
+            node_id: Node identifier.
+
+        Returns:
+            ContextNode if found, None otherwise.
+        """
+        if node_id not in self._graph:
+            return None
+
+        data = dict(self._graph.nodes[node_id])
+        return ContextNode.from_dict(data)
+
+    def get_related(
+        self,
+        node_id: str,
+        edge_types: list[str] | None = None,
+        direction: Literal["outgoing", "incoming", "both"] = "both",
+    ) -> list[ContextNode]:
+        """Get nodes related to a given node.
+
+        Args:
+            node_id: Source node ID.
+            edge_types: Filter by edge types. None = all types.
+            direction: Which edges to follow.
+
+        Returns:
+            List of related ContextNodes.
+        """
+        if node_id not in self._graph:
+            return []
+
+        related_ids: set[str] = set()
+
+        if direction in ("outgoing", "both"):
+            for _, target, data in self._graph.out_edges(node_id, data=True):
+                if edge_types is None or data.get("edge_type") in edge_types:
+                    related_ids.add(target)
+
+        if direction in ("incoming", "both"):
+            for source, _, data in self._graph.in_edges(node_id, data=True):
+                if edge_types is None or data.get("edge_type") in edge_types:
+                    related_ids.add(source)
+
+        return [n for nid in related_ids if (n := self.get_node(nid)) is not None]
+
+    def get_causality_chain(
+        self, node_id: str, max_depth: int = 10
+    ) -> list[ContextNode]:
+        """Get the causal ancestry of a node (led_to, caused_by edges).
+
+        Args:
+            node_id: Starting node ID.
+            max_depth: Maximum traversal depth.
+
+        Returns:
+            List of nodes in causal chain, oldest first.
+        """
+        if node_id not in self._graph:
+            return []
+
+        chain: list[str] = []
+        visited: set[str] = set()
+        current = node_id
+
+        for _ in range(max_depth):
+            visited.add(current)
+            chain.append(current)
+
+            # Find predecessor via led_to edge
+            predecessors = [
+                source
+                for source, _, data in self._graph.in_edges(current, data=True)
+                if data.get("edge_type") == "led_to" and source not in visited
+            ]
+
+            if not predecessors:
+                break
+            current = predecessors[0]
+
+        # Reverse to get oldest first
+        chain.reverse()
+        return [n for nid in chain if (n := self.get_node(nid)) is not None]
+
+    def get_nodes_by_story(self, story_id: str) -> list[ContextNode]:
+        """Get all nodes associated with a story.
+
+        Args:
+            story_id: Story identifier.
+
+        Returns:
+            List of ContextNodes for the story.
+        """
+        nodes = []
+        for node_id in self._graph.nodes:
+            data = self._graph.nodes[node_id]
+            if data.get("story_id") == story_id:
+                nodes.append(ContextNode.from_dict(data))
+        return nodes
+
+    def get_nodes_by_type(self, node_type: NodeType) -> list[ContextNode]:
+        """Get all nodes of a specific type.
+
+        Args:
+            node_type: Type of node to filter by.
+
+        Returns:
+            List of ContextNodes of the given type.
+        """
+        nodes = []
+        for node_id in self._graph.nodes:
+            data = self._graph.nodes[node_id]
+            if data.get("node_type") == node_type:
+                nodes.append(ContextNode.from_dict(data))
+        return nodes
+
+    def query_nodes(self, term: str) -> list[ContextNode]:
+        """Search nodes whose content or ID contains term (case-insensitive).
+
+        Args:
+            term: Search string. Empty string returns [].
+
+        Returns:
+            List of matching ContextNodes.
+        """
+        if not term:
+            return []
+        term_lower = term.lower()
+        results: list[ContextNode] = []
+        for node_id in self._graph.nodes:
+            data = self._graph.nodes[node_id]
+            if (
+                term_lower in data.get("content", "").lower()
+                or term_lower in node_id.lower()
+            ):
+                results.append(ContextNode.from_dict(data))
+        return results
+
+    def subgraph(self, node_id: str, depth: int = 2) -> list[ContextNode]:
+        """Return all nodes within BFS depth of node_id (both directions).
+
+        Args:
+            node_id: Starting node ID.
+            depth: BFS traversal depth. Values <= 0 are treated as 1 (returns
+                direct neighbours). Use get_node() to retrieve only the starting
+                node without traversal.
+
+        Returns:
+            List of ContextNodes in the subgraph (includes starting node).
+        """
+        if node_id not in self._graph:
+            return []
+
+        visited: set[str] = set()
+        frontier: list[str] = [node_id]
+        for _ in range(max(1, depth)):
+            next_frontier: list[str] = []
+            for nid in frontier:
+                if nid in visited:
+                    continue
+                visited.add(nid)
+                for _, t in self._graph.out_edges(nid):
+                    if t not in visited:
+                        next_frontier.append(t)
+                for s, _ in self._graph.in_edges(nid):
+                    if s not in visited:
+                        next_frontier.append(s)
+            frontier = next_frontier
+        # Include final frontier tier — these were reached but not yet expanded
+        visited.update(frontier)
+
+        return [
+            ContextNode.from_dict(dict(self._graph.nodes[nid]))
+            for nid in visited
+            if nid in self._graph
+        ]
+
+    def to_json(self) -> str:
+        """Serialize graph to JSON string.
+
+        Returns:
+            JSON string representation of graph.
+        """
+        nodes = [dict(self._graph.nodes[n]) for n in self._graph.nodes]
+        edges = [dict(self._graph.edges[e]) for e in self._graph.edges]
+
+        return json.dumps({"nodes": nodes, "edges": edges}, indent=2)
+
+    @classmethod
+    def from_json(cls, data: str, root: Path | None = None) -> ContextGraph:
+        """Deserialize graph from JSON string.
+
+        Args:
+            data: JSON string.
+            root: Project root directory.
+
+        Returns:
+            New ContextGraph instance.
+        """
+        graph = cls(root=root)
+        parsed = json.loads(data)
+
+        for node_data in parsed.get("nodes", []):
+            node = ContextNode.from_dict(node_data)
+            graph._graph.add_node(node.id, **node.to_dict())
+
+        for edge_data in parsed.get("edges", []):
+            from_id = edge_data["from_id"]
+            to_id = edge_data["to_id"]
+            if from_id in graph._graph and to_id in graph._graph:
+                graph._graph.add_edge(from_id, to_id, **edge_data)
+
+        return graph
+
+    def save(self) -> Path:
+        """Save graph to disk.
+
+        Context nodes (decisions/patterns/issues) → ref-reports/context_graph.json (durable).
+        AST nodes (module/class/function/file) → .ref_cache/ast_graph.json (regenerable).
+
+        Returns:
+            Path to primary context file.
+        """
+        context_nodes = []
+        ast_nodes = []
+        for n in self._graph.nodes:
+            data = dict(self._graph.nodes[n])
+            if data.get("origin") == "ast":
+                ast_nodes.append(data)
+            else:
+                context_nodes.append(data)
+
+        all_edges = [dict(self._graph.edges[e]) for e in self._graph.edges]
+
+        # Context edges: both endpoints are context nodes
+        context_node_ids = {n["id"] for n in context_nodes}
+        context_edges = [
+            e
+            for e in all_edges
+            if e["from_id"] in context_node_ids and e["to_id"] in context_node_ids
+        ]
+        # AST edges: at least one endpoint is an AST node
+        ast_edges = [e for e in all_edges if e not in context_edges]
+
+        self._primary_dir.mkdir(parents=True, exist_ok=True)
+        self._primary_file.write_text(
+            json.dumps({"nodes": context_nodes, "edges": context_edges}, indent=2)
+        )
+
+        try:
+            self._cache_dir.mkdir(parents=True, exist_ok=True)
+            ast_cache = self._cache_dir / "ast_graph.json"
+            ast_cache.write_text(
+                json.dumps({"nodes": ast_nodes, "edges": ast_edges}, indent=2)
+            )
+        except OSError as e:
+            import structlog
+
+            structlog.get_logger(__name__).warning(
+                "ast_graph_cache_save_failed", error=str(e)
+            )
+
+        return self._primary_file
+
+    @classmethod
+    def load(cls, root: Path | None = None) -> ContextGraph:
+        """Load graph from disk.
+
+        Loads context nodes from ref-reports/context_graph.json (durable).
+        Merges AST nodes from .ref_cache/ast_graph.json if present (regenerable).
+
+        .. warning::
+            Do not call directly — use get_context_graph().
+            Direct calls bypass the singleton and drop in-memory state accumulated
+            since the last save, causing context graph update failures (RC5).
+
+        Args:
+            root: Project root directory.
+
+        Returns:
+            Loaded ContextGraph or empty graph if no files exist.
+        """
+        graph = cls(root=root)
+
+        # Load durable context nodes
+        if graph._primary_file.exists():
+            try:
+                loaded = cls.from_json(graph._primary_file.read_text(), root=root)
+                graph._graph = loaded._graph
+            except (json.JSONDecodeError, ValueError, KeyError) as e:
+                import structlog
+
+                structlog.get_logger(__name__).warning(
+                    "context_graph_primary_load_failed", error=str(e)
+                )
+
+        # Merge AST nodes from cache (optional — missing = needs graph_populate)
+        ast_cache = graph._cache_dir / "ast_graph.json"
+        if ast_cache.exists():
+            try:
+                parsed = json.loads(ast_cache.read_text())
+                for node_data in parsed.get("nodes", []):
+                    node = ContextNode.from_dict(node_data)
+                    if node.id not in graph._graph:
+                        graph._graph.add_node(node.id, **node.to_dict())
+                for edge_data in parsed.get("edges", []):
+                    f, t = edge_data["from_id"], edge_data["to_id"]
+                    if f in graph._graph and t in graph._graph:
+                        graph._graph.add_edge(f, t, **edge_data)
+            except (json.JSONDecodeError, KeyError, TypeError) as e:
+                import structlog
+
+                structlog.get_logger(__name__).warning(
+                    "ast_graph_cache_load_failed", error=str(e)
+                )
+
+        return graph
+
+    def format_for_prompt_graph(
+        self,
+        story_id: str | None = None,
+        depth: int = 2,
+    ) -> str:
+        """Build context string via BFS subgraph instead of flat JSONL.
+
+        Finds story node (or uses all context nodes), BFS to depth, returns
+        ranked markdown. Replaces flat chronological JSONL injection.
+
+        Args:
+            story_id: Story node ID to start BFS from. None = all context nodes.
+            depth: BFS traversal depth.
+
+        Returns:
+            Formatted markdown string for prompt injection.
+        """
+        if self._graph.number_of_nodes() == 0:
+            return ""
+
+        # Collect seed node IDs
+        seeds: list[str] = []
+        if story_id:
+            story_nodes = [
+                n
+                for n in self._graph.nodes
+                if self._graph.nodes[n].get("story_id") == story_id
+                or self._graph.nodes[n].get("node_type") == "story"
+                and story_id in n
+            ]
+            seeds = story_nodes
+
+        if not seeds:
+            # Fall back: 5 most recent non-AST nodes (timestamp desc).
+            # Capped to prevent cross-story context bleed when no active story.
+            non_ast = [
+                n
+                for n in self._graph.nodes
+                if self._graph.nodes[n].get("origin") != "ast"
+            ]
+            non_ast.sort(
+                key=lambda n: self._graph.nodes[n].get("timestamp", ""),
+                reverse=True,
+            )
+            seeds = non_ast[:5]
+
+        if not seeds:
+            return ""
+
+        # BFS from seeds up to depth
+        visited: set[str] = set()
+        frontier = list(seeds)
+        for _ in range(depth):
+            next_frontier: list[str] = []
+            for node_id in frontier:
+                if node_id in visited:
+                    continue
+                visited.add(node_id)
+                for _, target in self._graph.out_edges(node_id):
+                    if target not in visited:
+                        next_frontier.append(target)
+                for source, _ in self._graph.in_edges(node_id):
+                    if source not in visited:
+                        next_frontier.append(source)
+            frontier = next_frontier
+
+        visited.update(frontier)
+
+        # Group by node_type, sort by confidence on incoming edges
+        by_type: dict[str, list[dict[str, Any]]] = {}
+        for node_id in visited:
+            if node_id not in self._graph:
+                continue
+            data = dict(self._graph.nodes[node_id])
+            node_type = data.get("node_type", "unknown")
+            if node_type in AST_NODE_TYPES and data.get("origin") == "ast":
+                continue  # Skip raw AST structural nodes from prompt
+            by_type.setdefault(node_type, []).append(data)
+
+        if not by_type:
+            return ""
+
+        lines: list[str] = ["\n--- SESSION CONTEXT (graph-based) ---\n"]
+        priority = ["decision", "blocker", "pattern", "issue", "story", "note"]
+        ordered = sorted(
+            by_type.keys(), key=lambda k: priority.index(k) if k in priority else 99
+        )
+
+        for node_type in ordered:
+            nodes_of_type = by_type[node_type]
+            lines.append(f"**{node_type.title()}s:**")
+            for n in nodes_of_type[:8]:  # Cap per type
+                sid = f" [{n.get('story_id')}]" if n.get("story_id") else ""
+                lines.append(f"• {n.get('content', '')[:120]}{sid}")
+            lines.append("")
+
+        lines.append("--- END CONTEXT ---\n")
+        return "\n".join(lines)
+
+    def to_html(self) -> str:
+        """Generate self-contained interactive HTML graph viewer (vis.js CDN).
+
+        Returns:
+            HTML string. Write to ref-reports/graph.html to open in browser.
+        """
+        graph_data = self.to_json()
+        parsed = json.loads(graph_data)
+
+        vis_nodes = []
+        color_map = {
+            "decision": "#4A90E2",
+            "pattern": "#7ED321",
+            "issue": "#D0021B",
+            "story": "#9B59B6",
+            "agent_session": "#F5A623",
+            "module": "#50E3C2",
+            "class": "#B8E986",
+            "function": "#C8C8C8",
+            "file": "#8B572A",
+        }
+        for node in parsed.get("nodes", []):
+            vis_nodes.append(
+                {
+                    "id": node["id"],
+                    "label": node.get("content", node["id"])[:40],
+                    "title": node.get("content", ""),
+                    "color": color_map.get(node.get("node_type", ""), "#888888"),
+                    "group": node.get("node_type", "unknown"),
+                }
+            )
+
+        vis_edges = []
+        for i, edge in enumerate(parsed.get("edges", [])):
+            vis_edges.append(
+                {
+                    "id": i,
+                    "from": edge["from_id"],
+                    "to": edge["to_id"],
+                    "label": edge.get("edge_type", ""),
+                    "arrows": "to",
+                    "color": {"opacity": float(edge.get("confidence", 1.0))},
+                }
+            )
+
+        nodes_json = json.dumps(vis_nodes)
+        edges_json = json.dumps(vis_edges)
+
+        return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>REF Context Graph</title>
+<script src="https://cdn.jsdelivr.net/npm/vis-network@9/standalone/umd/vis-network.min.js"></script>
+<style>
+  body {{ margin: 0; background: #1a1a2e; font-family: monospace; color: #eee; }}
+  #graph {{ width: 100vw; height: 90vh; border: none; }}
+  #info {{ padding: 8px 16px; background: #16213e; font-size: 12px; }}
+  #legend {{ display: flex; gap: 12px; flex-wrap: wrap; padding: 6px 16px; background: #0f3460; font-size: 11px; }}
+  .dot {{ width: 10px; height: 10px; border-radius: 50%; display: inline-block; margin-right: 4px; }}
+</style>
+</head>
+<body>
+<div id="info">REF Context Graph &nbsp;|&nbsp; Nodes: {len(vis_nodes)} &nbsp;|&nbsp; Edges: {len(vis_edges)}</div>
+<div id="legend">
+  {"".join(f'<span><span class="dot" style="background:{v}"></span>{k}</span>' for k, v in color_map.items())}
+</div>
+<div id="graph"></div>
+<script>
+const nodes = new vis.DataSet({nodes_json});
+const edges = new vis.DataSet({edges_json});
+const container = document.getElementById("graph");
+const network = new vis.Network(container, {{ nodes, edges }}, {{
+  physics: {{ stabilization: {{ iterations: 150 }}, barnesHut: {{ gravitationalConstant: -8000 }} }},
+  edges: {{ font: {{ size: 10, color: "#aaa" }}, smooth: {{ type: "curvedCW", roundness: 0.2 }} }},
+  nodes: {{ font: {{ color: "#fff", size: 12 }}, shape: "dot", size: 12 }},
+  interaction: {{ hover: true, tooltipDelay: 100 }},
+}});
+network.on("click", p => {{
+  if (p.nodes.length) {{
+    const n = nodes.get(p.nodes[0]);
+    document.getElementById("info").textContent = n.title || n.label;
+  }}
+}});
+</script>
+</body>
+</html>"""
+
+    def to_visualization_json(self) -> str:
+        """Export graph in format suitable for react-flow visualization.
+
+        Returns:
+            JSON string with nodes and edges for frontend.
+        """
+        viz_nodes = []
+        for node_id in self._graph.nodes:
+            data = self._graph.nodes[node_id]
+            viz_nodes.append(
+                {
+                    "id": node_id,
+                    "type": data.get("node_type", "decision"),
+                    "data": {
+                        "label": data.get("content", "")[:50],
+                        "fullContent": data.get("content", ""),
+                        "nodeType": data.get("node_type", ""),
+                        "storyId": data.get("story_id", ""),
+                        "timestamp": data.get("timestamp", ""),
+                    },
+                    "position": {"x": 0, "y": 0},  # Layout computed by frontend
+                }
+            )
+
+        viz_edges = []
+        for idx, (source, target) in enumerate(self._graph.edges):
+            data = self._graph.edges[(source, target)]
+            viz_edges.append(
+                {
+                    "id": f"e{idx}",
+                    "source": source,
+                    "target": target,
+                    "label": data.get("edge_type", ""),
+                    "type": "smoothstep",
+                }
+            )
+
+        return json.dumps({"nodes": viz_nodes, "edges": viz_edges}, indent=2)
+
+
+# Singleton instance for global access
+_context_graph: ContextGraph | None = None
+_watcher_started: bool = False
+
+
+def get_context_graph(root: Path | None = None) -> ContextGraph:
+    """Get or create the global context graph instance.
+
+    On first initialisation, also auto-starts the AST file watcher (RC2) so
+    that incremental graph updates fire on every file save without requiring an
+    explicit context(action="graph_watch") call.
+
+    Args:
+        root: Optional project root. Only used on first call.
+
+    Returns:
+        Global ContextGraph instance.
+    """
+    global _context_graph, _watcher_started
+    if _context_graph is None:
+        _context_graph = ContextGraph.load(root)
+
+        if not _watcher_started:
+            _watcher_started = True
+            try:
+                import threading
+
+                from ref_agents.server import _ast_observers, _context_graph_watch
+
+                _root_str = (
+                    str(_context_graph._root)
+                    if hasattr(_context_graph, "_root")
+                    else ""
+                )
+                if _root_str and _root_str not in _ast_observers:
+                    threading.Thread(
+                        target=_context_graph_watch,
+                        args=(_root_str,),
+                        daemon=True,
+                        name="ref-ast-watcher-auto",
+                    ).start()
+            except (ImportError, OSError, RuntimeError):
+                # Non-fatal: watcher is a best-effort optimisation
+                pass
+
+    return _context_graph
+
+
+def reset_context_graph() -> None:
+    """Reset the global context graph instance. Primarily for testing."""
+    global _context_graph
+    _context_graph = None