/foundry:report-citation-graph

The graph layer — a WRAP over native MCP. Plain-text files are the source of truth; the graph is a derived, reproducible cache.

Procedure

1. Build/refresh the cache:

   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/foundry-build-citation-graph.py" --subdir docs --subdir specs --subdir foundry

   Writes .foundry/graph.json (nodes + forward edges + materialized backlinks — the O(1) "what cites X" reverse index, delta-1) pinned to a source_signature (staleness).
2. Query natively via MCP. The foundry-graph MCP server (.mcp.json, auto-discovered) serves three tools the MODEL calls directly: graph_backlinks(node) (O(1)), graph_neighbors(node), graph_node(node). This is the "make the graph native via MCP" realization — the first Foundry MCP server.
3. Enforcement is agentic, never CI: broken-reference checks live in /foundry:coherence-check (source-filtered, advisory), not a perpetually-red CI gate.

FRESH-FALLBACK CONTRACT (coherence-substrate)

The committed .foundry/graph.json is a derived cache with no auto-rebuild hook — it can be stale relative to the corpus. Every consumer that reads the cache (its broken_edges, backlinks, out_of_scope) MUST first run the content-based staleness gate:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/foundry-build-citation-graph.py" --check-stale

• exit 0 (CURRENT) → the cache matches the corpus over its recorded build_scope; trust it.
• non-zero (STALE) → a tracked doc changed, the builder version skewed, or the graph is absent/pre-substrate. Do NOT trust the cache — re-walk fresh (rebuild via step 1) and use the freshly-built graph. Never read a stale graph's broken_edges/backlinks.

(The doctor staleness line this sentence originally named was retired with the drop-in registry; staleness is read via foundry_graph.is_stale by the MCP server, and it never flips DOCTOR-RED). The blocking merge-gate consumer of staleness this line originally named was retired; staleness is now surfaced advisorily (foundry_graph.is_stale, read by foundry-graph-mcp.py). The staleness signature is content-based (stable across checkouts), not mtime.

Inputs / Outputs

• In: the corpus (docs/, specs/, foundry/ markdown). Out: .foundry/graph.json (cache) + the live foundry-graph MCP tools.

Endpoint trust

The MCP server is stdio (loopback by construction — no network surface); enumerated in .mcp.json (allowlist, no auto-discovery of external servers); the served graph is pinned to its source_signature.

Anti-patterns

• Treating graph.json as the source of truth — it's a derived cache; rebuild from the files.
• A broken-edge CI gate — broken-edge sweeping is agentic (/foundry:coherence-check, advisory), not CI.
• An unauthenticated network MCP variant — stdio/loopback only at v1; an HTTP variant needs token/mTLS + pinned identity.