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>
48 lines
2.5 KiB
Markdown
48 lines
2.5 KiB
Markdown
# 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`,
|
|
and `uses` are 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_in` and `owns` are 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-retrieve` fuses 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.)*
|