[IanMayo]

Why

Two things had outgrown grep.

Source. 1,581 TypeScript/Python files across ~20 workspace packages under two package managers, so "what actually consumes this?" was grep plus judgement.

The ADR citation network. 39 decisions live as ### ADR-NNN: headings inside a single ~19k-word decisions.md, cited 608 times across markdown, TypeScript, Python and LinkML YAML — ADR-030 alone 63 times. scripts/check-adr-refs.sh validated only the LinkML YAML subset, so roughly 90% of citations were unchecked, and the network was navigable only by grepping one very large file.

Scope is developer tooling only — not analyst-facing, not product code, nothing shipped changes.

What this adds

• graphifyy==0.9.35 (Apache-2.0), invoked via uvx, never a workspace dependency so it cannot reach a shipped artefact (Article IX).
• Code-only extraction — tree-sitter AST, zero LLM calls, no API key, no network. Verified byte-identical across consecutive builds; GRAPH_REPORT.md records Token cost: 0 input · 0 output. ~14,300 nodes / ~30,000 edges in ~45s.
• scripts/extract-adr-graph.py — extracts the ADR citation graph deterministically (39 nodes, 501 cites edges).
• scripts/check-adr-refs.sh widened from LinkML YAML to the whole repo, plus malformed-ID detection. ~1.5s, stays in task lint.
• .mcp.json registers the first-party MCP server so Claude Code queries the graph instead of grepping.
• task graph:build / refresh / report / pages, .graphifyignore for scoping.
• graphify-publish.yml deploys the committed pages to gh-pages under code-graph/, plus an advisory freshness job.

Why we extract the ADR graph ourselves

Two graphify behaviours made its own extraction unusable here:

1. Its generic docref extractor zero-pads IDs to four digits, so its nodes never join our three-digit convention.
2. --code-only skips markdown entirely — where most citations live.

Edges anchor to graphify's recorded source_file values rather than re-derived node IDs, so they survive upstream changes to ID slugging. The in-place merge is idempotent. Graphify's own merge-graphs is unusable — it is built for cross-repository merges and namespaces every node (repo::…), severing exactly those anchors.

This is not a gate

knip, the custom rules in shared/eslint-rules/, pyright and tsc keep answering closed questions and failing the build. The graph answers open ones. Its clearest payoff is surfacing couplings that should become new shared/eslint-rules/ entries — that directory has grown whenever someone happened to notice a pattern; this makes it deliberate.

The publish workflow never runs on pull requests and cannot block a merge.

Known limits (recorded in ADR-041 and the guide)

• The LinkML chain is invisible. shared/schemas LinkML → generated Pydantic/TS → consumers crosses a code generator no AST parser sees. The graph shows consumers of the generated types but cannot link them back to the schema. This is the chain Article II and ADR-033 care most about — do not read coverage into it.
• The graph is an index, never a record. Even code-only extraction is 97% EXTRACTED / 3% INFERRED. It is not evidence and must never be cited as provenance.
• No repo-wide force-directed page. Graphify refuses that rendering above 5,000 nodes; we have ~14,300. Published pages are a D3 collapsible tree plus the smaller interactive ADR graph.
• Community labels are placeholders — naming needs an LLM backend we deliberately do not configure. god-nodes is unaffected and gives meaningful hubs (SelectionContext 237 edges, ContextType 144, create_catalog() 116).
• specs/ excluded — 2.6M words, value banked on delivery.

Repository weight

graphify-out/ is committed (~17MB, of which graph.json is 15MB) so a fresh clone can query immediately and the published HTML is deployed rather than regenerated. cache/ and the incremental manifest stay ignored as machine state. The merge writes compact + sort_keys, ~3MB smaller than pretty-printed and byte-reproducible.

Ordering is load-bearing: cluster-only rewrites graph.json with its own serialiser, re-inflating it and collapsing same-endpoint edges (501 → 266). The ADR merge runs last in every task.

Verification

Check	Result
Two consecutive builds byte-identical	✅ same SHA256
Build with no API key / no network	✅ Token cost: 0 input · 0 output
--merge idempotent over 3 runs	✅ stable +172 nodes / +501 edges
affected "ADR-030" --relation cites	✅ matches grep ground truth with file:line
explain "ADR-033"	✅ resolves title, degree 14
check-adr-refs.sh	✅ 608 citations / 39 ADRs; negative test fails correctly
ruff check .	✅ passes
Repo lint guards	✅ pass (check-eslint-drift-wiring.cjs fails on a clean tree too — pre-existing, unrelated)

Findings surfaced along the way

• ADR-031 and ADR-032 are cited from 12 files but never written. The numbering note in decisions.md shows they were reserved for the Mark task #016 as complete in backlog #248/feat(087): logical result ID registry with change events #249 extractions. They are allowlisted in RESERVED with a pointer — worth deciding whether to write them or retire the references.
• The repo is otherwise clean: no other dangling or malformed ADR references across all 608 citations.

---

Generated by Claude Code

[github-actions]

📋 Backlog Navigator

Review this PR's BACKLOG.md edits interactively:

👉 Open in Backlog Navigator

_{Updated for a6cde7e — the navigator reads BACKLOG.md live from this PR's head branch, so no rebuild is needed.}

[github-actions]

🕸️ Code Graph Preview

The interactive knowledge graph built from this PR:

👉 Open the code graph

Page	Scope
Whole repository	Collapsible tree, all nodes
ADR citation graph	Which code and docs cite which decision
Graph report	Hubs and communities

_{Updated for a6cde7e — deployed from the pages committed on this branch, not rebuilt.
GitHub Pages can take a minute to serve a fresh deploy.
The graph needs internet access (D3 and vis-network load from CDNs).}

[IanMayo]

Closing — the graph did not earn its place. Recording the evidence so this isn't re-litigated later.

What was measured

The graph was trialled against the 20 most recent open issues. Result: one clear win, two partial, seventeen no help.

The win (#675 — Layers panel not refreshing after a Chat-agent change) was real and verified: affected "LayersTreeProvider" returns seven dependents, and runToolTool.ts is not among them, while executeTool.ts is and calls addResultLayer at line 329. The Chat-agent path structurally cannot refresh the Layers panel. But grep -rln LayersTreeProvider yields the same file list — the graph's contribution was presentation, not capability.

Why it doesn't generalise

• It is precise only when you already know the symbol. affected "<known symbol>" gives exact dependents with line numbers. query "what enables tools when a feature is selected" is keyword-seeded BFS with no semantic understanding — it seeded from Selected (a Storybook story), tools() (the CLI) and TOOLS (a model-routing probe), then walked outward from those wrong seeds. A developer picking up an unfamiliar ticket is in the second case by definition, so the tool is sharpest exactly where it is needed least.
• It cannot cross Python↔TypeScript. That boundary is MCP/stdio at runtime and invisible to AST — the same root cause as the LinkML blind spot documented in the PR body. Issue Selecting feature in layers panel does not enable context-sensitive tools #674 spans exactly that boundary.
• The ticket flow does not fit. Of the 20 issues, 14 are new-feature specs (7 of them the E09 epic) and 2 are TODO promotions that already cite exact file:line. Only 4 are "navigate existing code" problems.
• The published pages were reviewed and judged not useful — 9.5MB of the 26MB, plus three workflows to maintain.

That does not justify 26MB of committed artefacts, four workflows, and ongoing rebuild discipline.

What survives

The widened scripts/check-adr-refs.sh is independent of graphify and stands on its own. It validates 610 ADR citations repo-wide instead of ~60 (previously only LinkML YAML — roughly 90% went unchecked), adds malformed-ID detection, and immediately found ADR-031 and ADR-032 cited from 12 files but never written. Around 130 lines of bash, no artefacts, no workflows.

That is being reopened as a small replacement PR.

Also worth keeping separately

python-lint.yml runs unpinned uvx ruff, so CI drifts to whatever is latest while task lint uses lockfile-pinned uv run ruff. The two can never agree — a newer ruff enabled Markdown code-block formatting and flagged 104 untouched files. That is a genuine pre-existing bug (Article IX.2) and is worth fixing on its own, independently of anything here.

---

Generated by Claude Code