# Code Graph Protocol

## Purpose

Define when and how agents/skills use the **code knowledge graph** (Graphify)
for **structural / relational** code questions — the kind Grep and even LSP
answer poorly: "what connects auth to the database", "what breaks if I change
this", "which modules form a cluster", "show the path between these two pieces".
The graph filters the codebase to the relevant *subgraph* before Claude reads
anything, the same economy principle as the LSP and (former) RAG tiers.

## Scope

**In**: choosing the graph vs LSP vs Grep vs Git for code retrieval; the native
Graphify commands to call; fallback rules.
**Out**: single-symbol reference/definition lookups (see
`agents/code-search-protocol.md` → LSP tier); documentation synthesis (see
`agents/llm-wiki-methodology.md`).

## Gating

Conditional on `features.has_code_graph: true` in `baldart.config.yml`. When the
flag is `false`/missing **or** the `graphify` CLI is not installed, agents **fall
back silently** to the LSP → Grep → Git hierarchy. Never block a task on the
graph being absent — surface setup gaps through `baldart doctor`
(`Code graph` line + `graph-install` / `graph-rebuild` actions), not mid-task.

Graphify is a single language-agnostic tool (tree-sitter, 28 languages,
local/offline). The graph lives at `${graph.output_dir}/graph.json` (default
`graphify-out/graph.json`); a stale graph (built from an older commit than HEAD)
is rebuilt by doctor / the native post-commit hook, not by the querying agent.

## Composition with Graphify's native always-on mode

Graphify ships its **own** Claude/Codex integration: `graphify <platform> install`
writes a graph-first section to the tool's instruction file + a pre-tool hook
that nudges the assistant to query the graph before grepping, and a native
`/graphify` skill. **This protocol does not duplicate that** — it tells BALDART's
own agents *when* the graph is the right tier and *which* native command to run.
Prefer the native skill / MCP when present; the CLI commands below always work
post-install with no registration.

## Retrieval hierarchy (relational queries first)

For a **structural / relational** query, the order is:

1. **Code graph** — `graphify query`/`path`/`explain`/`affected` (or the
   `graphify-mcp` MCP tools when registered). Best for multi-hop relationships,
   blast-radius, clustering, "how do these connect".
2. **LSP** — when it collapses to a single symbol's references/definition
   (`features.has_lsp_layer: true`). See `agents/code-search-protocol.md`.
3. **Grep** — textual patterns (comments, magic strings, config keys).
4. **Git log** — when/why something changed.

For a **symbol or textual** query, skip the graph and start at LSP/Grep per the
code-search-protocol — the graph adds nothing there.

## Native commands (all offline, 0 API cost)

Run via Bash (the CLI is on `$PATH` once installed); `--graph` defaults to
`graphify-out/graph.json`:

| Need | Command |
|------|---------|
| Free-text traversal for a question | `graphify query "how does auth reach the DB"` |
| Path between two nodes | `graphify path "LoginController" "UserRepository"` |
| Explain a node + its neighbours | `graphify explain "SessionService"` |
| Blast radius (reverse impact) | `graphify affected "computeBaseFileSha"` |
| Cluster / hub overview | read `graphify-out/GRAPH_REPORT.md` (god nodes, communities) |

`graphify query` accepts `--budget N` (token cap, default 2000) and `--dfs`.
`graphify affected` accepts `--depth N` and `--relation R`.

## Query-type discrimination

| Query shape | Start with |
|-------------|------------|
| "what connects X to Y" / "path from X to Y" | code graph (`path`/`query`) |
| "what breaks if I change X" / impact | code graph (`affected`) |
| "which parts form a cluster / the core abstractions" | code graph (`GRAPH_REPORT.md`) |
| `handleSubmit`, `UserSchema` (single symbol refs/def) | LSP |
| `"TODO: …"`, a config key, a regex | Grep |
| "when did X change" | Git log |

## Budget

- **Graph**: up to **3 graph commands per task** for a relational question. If
  still unclear, read the specific files the graph pointed to — don't keep
  traversing. `--budget` caps `query` output.
- Falls back to the existing LSP/Grep budgets when the graph is unavailable.

## Fallback rules

- `graphify` not installed / `has_code_graph: false` → silent fallback to
  LSP → Grep → Git. No prompt mid-task.
- `graph.json` missing or stale → still usable; note the staleness in reasoning
  and let doctor/the hook rebuild it. Don't rebuild inline during a read task
  (rebuild is a side effect owned by `doctor` / `graphify-bootstrap` / the
  nightly `doc-graph-align` routine).
- A graph command errors / returns nothing → fall back to LSP/Grep for that query.

## See also

- `framework/.claude/skills/graphify-bootstrap/SKILL.md` — install + verify + build.
- `framework/.claude/skills/graph-align/SKILL.md` — on-demand doc/graph alignment.
- `framework/agents/code-search-protocol.md` — LSP/Grep/Git hierarchy.
- `framework/agents/llm-wiki-methodology.md` — how `GRAPH_REPORT.md` feeds the wiki.
- `framework/docs/CODE-GRAPH-LAYER.md` — install lifecycle, schema, invariants.
