Michał Kopeć
474630e2bb
Graft keeps a derived, disposable code graph in sync with a content hash rather than a calendar, and keeps a protected block on every regenerated node. This KB is the opposite kind of store — durable, curated, built from material that cannot be regenerated — but several of Graft's mechanisms port cleanly, and two of them close real gaps here. Schema 1.5 is additive: every 1.4 page remains valid. 1. `## Crux` — verbatim source excerpts alongside the synthesis. A summary can drift silently; a quote either still matches its source or it does not. Lets `ckb-retrieve` ground an answer without a round-trip to the archive, and makes drift mechanically detectable. 2. `## Notes` — human-authored and protected everywhere. Closes a real gap: `ckb-index-external` regenerates connector pages wholesale, so an annotation written there was previously destroyed on the next refresh. 3. `source_fingerprint`/`source_checked` — a digest of the material a page was built from. Freshness by date says a page has aged; a fingerprint says whether its evidence moved. Most valuable for connector-backed libs, where documents change with no notice. 4. `lint_report.py --quick` — a deterministic one-line session-start signal, wired into Rule E next to the existing `git status` check. 5. In-degree as a rank-fusion signal in `ckb-retrieve`, weighted below 1.0: centrality is a prior, not evidence. 6. Blast radius — a new `ckb-ingest` step walking the graph backwards from touched entities to find what the incoming material contradicts, before writing anything. Ingest was additive-first, which is how a wiki accumulates two pages that quietly disagree. 7. Edge vocabulary in `wiki/graph/index.md` rewritten as a question per verb, and completed: `part_of` was written by `ckb-code-map` but never declared. Added `produces`, `configures`, `validates`, `implements`. Lint gains checks 12 (fingerprint drift), 13 (crux verbatimness) and 14 (the protected-Notes rule), verified against a synthetic fixture covering stale digests, missing sources, fabricated quotes and paraphrased evidence. Not adopted: the gitignored regenerable store, the MCP server and CLI daemon, tree-sitter parsing, statusline hooks, telemetry. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2.5 KiB
2.5 KiB
Graph
Edge list and relationship data for the knowledge graph, keyed by entity page.
edges.json holds typed relationships between pages. Created on the first
ingest that extracts entities.
Edge vocabulary
Each verb exists because it answers a question retrieval actually gets asked. If a proposed edge doesn't answer one of these, it doesn't belong in the graph — put it in prose on the page instead.
| Verb | Question it answers | Written by |
|---|---|---|
part_of |
Where does this live? What is it a piece of? | ckb-ingest, ckb-code-map |
uses |
What does this reach for at runtime? | ckb-ingest, ckb-index-external |
depends_on |
What breaks if I change this? | ckb-ingest, ckb-code-map |
produces |
Where does this output come from? | ckb-ingest |
configures |
What changes this thing's behaviour? | ckb-ingest |
validates |
What checks, tests, or judges this? | ckb-ingest |
implements |
What contract must this honour? | ckb-ingest, ckb-spec |
caused |
Why did this happen? | ckb-ingest |
contradicts |
What disagrees with this, unresolved? | ckb-ingest, ckb-lint |
supersedes |
What replaced this, and what did it replace? | ckb-ingest, ckb-decide, ckb-lint |
decided_by |
Who made this call? | ckb-decide |
affects |
What does this decision constrain? | ckb-decide |
has_expertise_in |
Who can answer questions on this? | ckb-ingest |
owns |
Who is responsible for this? | ckb-ingest, ckb-code-map |
mentioned_in |
Which source document discusses this? | ckb-index-external (lib indexes only) |
Conventions:
- One direction per relationship.
part_of,supersedes,depends_on, andusesare canonical; don't also record the inverse (contains,superseded_by, …) as a second edge. Frontmatter carries the inverse where a page needs to state it (superseded_by:), and traversal reads edges both ways regardless. - Evidence, not inference.
has_expertise_inandownsare recorded only from demonstrated evidence — someone attending a meeting is not expertise, and a job title is not ownership. The same applies to every other verb: an absent edge beats a fabricated one. - In-degree is a retrieval signal. How many edges point at a page is a
rough measure of how central it is, and
ckb-retrievefuses it as one ranked list among several. That only works if edges are recorded honestly; padding the graph degrades search rather than improving it.
(No edges recorded yet — populated on the next ingest.)