The knowledge graph

Everything Spine answers is grounded in a Product Knowledge Graph (PKG) — a deterministic fact model extracted from your code and your documentation.

Why a graph, not a chat log

Spine’s architecture forbids force-directed layouts: a picture that redraws differently for an identical commit can’t be diffed. Positions are computed once with a seeded layout, so the same commit renders the identical graph every time. Determinism is the feature, not a limitation.

8 node kinds

Node	What it is
Module	a file or package
Type	class, struct, interface
Function	a callable unit
Field	attribute or constant
Endpoint	HTTP route / handler
Entity	data-layer table
Doc	ingested documentation
Intent	the ticket a symbol was last changed for

12 edge kinds

IMPORTS · CONTAINS · CALLS · IMPLEMENTS · READS · WRITES · EXPOSES · CONSUMES · REFERENCES · MENTIONS · SERVES · PROVIDES

Every edge carries a location. For example:

auth.validate   — CALLS →      models.get_user
models.get_user — READS →      password_hash
docs/auth.md    — MENTIONS →   auth.validate

Documentation is a first-class citizen

Spine ingests 7 document formats — .md .rst .txt .html .pdf .docx .xlsx — and turns each into a Doc node linked to the symbols it MENTIONS. That’s what powers doc drift: detecting when a document claims a symbol that no longer exists, or says code is tested when it isn’t.

External docs join too. orchestrator mcp ingest-docs pulls Confluence pages, Jira issues, or chunks from any RAG system’s MCP server — declared under a docs: block in .spine/repos.yaml — into a cache outside the checkout, then binds them to symbols at read time with the same rule as the repo’s own docs. blast_radius, explain_symbol and docs_for list them with their origin, source and age; they never reach understand, state or the committed episteme/, so CI stays reproducible without credentials.

Boundaries

The deterministic build is text-only — no model ever runs in it. .pdf needs the [docs] extra; .docx/.xlsx need [office]. Image OCR ([media]) and audio/video transcription ([asr]) are opt-in and off by default — the model runs only in a separate orchestrator media extract, which commits a transcript the build then reads.

Measured, not asserted

“Grounded” is a number here, not an adjective. Graph accuracy is precision and recall per node and edge kind, against a published hand-labelled corpus of 119 fixture cases (113 single-language, 6 multi-repo) across all 14 front-ends:

orchestrator pkg accuracy            # precision/recall per kind
orchestrator pkg accuracy --check    # CI gate: fails when a gated number drops

Precision is 1.00 on every node kind and every edge kind, in all 13 languages. A committed baseline fails CI when a gated number regresses, so the graph can’t quietly get worse.

Across several repositories

Several repos can merge into one graph, so “what breaks if I change this?” can answer with a caller in a different repo. Declare the set in .spine/repos.yaml:

orchestrator pkg extract --repos
orchestrator investigate --repos      # cross-repo landing sites
orchestrator pkg joins --propose      # derive the join topology from evidence

The joins are derived from evidence, not drawn by hand — and what could not be joined is reported, because a missing cross-repo edge looks exactly like two uncoupled services.