AST-Grounded Code-Intelligence Plane

# AST-Grounded Code-Intelligence Plane

Keeps a coding agent anchored to the real codebase — real symbols, signatures, and call relationships — instead of hallucinating APIs.

## Overview
Semantic-only (vector) retrieval misses structural reality: signatures, module boundaries, control flow. Agents then hallucinate parameters, misread inheritance, and emit broken imports. This plane treats code as structural nodes and relations: it parses source into ASTs, extracts each module's public interface as an ABI, writes symbols and dependencies into a knowledge graph, retrieves precise context via hybrid graph+vector search, and renders the AST/control-flow slice the agent is about to touch.

## Architecture (data flow)
Source -> AST. AST -> AST-to-ABI generation -> JSONSchema<ABI> (exported symbols, signatures, types). A fact mapper turns ABI + imports into entity-relation facts (defined_in, calls) written incrementally to the knowledge graph. On a query, hybrid graph+vector retrieval merges docstring vector matches with keyword graph-walks over the call/dependency graph into a precise context subgraph. In parallel, AST control-flowgraph visualization renders the target slice to Mermaid/Graphviz for agent and human review.

## Components
1. AST to ABI generation — AST -> JSONSchema<ABI>. Source: argotorg/solidity.
2. knowledge-graph-persistent-memory-write — EntityRelationFact -> UpdatedKnowledgeGraph. Source: modelcontextprotocol/servers.
3. hybrid-graph-vector-retrieval — (Keywords, VectorQuery) -> ContextSubgraph. Source: HKUDS/LightRAG.
4. AST control flowgraph visualization — AST -> DiagramSource (Mermaid/Graphviz). Source: boa-dev/boa.

## Build
A Python reference (code_intel_plane.py) implements each atom and a CodeIntelligencePlane orchestrator (ingest_module, query_context, render_flow) over a networkx graph, mapping exported symbols and their calls into the graph and returning dependency-aware context subgraphs.

## Acceptance Check
Ingest a mock auth module (login_user calling hash_password and db_fetch_user); assert a query for "login_user" returns the symbol, its module, and its dependencies, and that the control-flow render emits valid Mermaid with the call edges.

## Honest status
The graph/retrieval/visualization wiring is sound, but three pieces are caller-supplied gaps, not provided: a real language AST parser (Python ast, tree-sitter, or the TS compiler API), a real embedding model for the vector lane, and a fact mapper from ABI JSON to graph triples. The reference build's vector "similarity" is a string-match stub. It proves the structure-first grounding flow; it needs a real parse and real embeddings to ground anything. Star atom: AST-to-ABI generation. Differs from LP-DIP: the unit is code structure (AST/ABI/call graph), not page layout.