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>
80 lines
3.8 KiB
Markdown
80 lines
3.8 KiB
Markdown
---
|
|
type: overview
|
|
tldr: High-level map of the cascade knowledge base's directory structure, frontmatter schema, and layering rules.
|
|
last_updated: 2026-09-21
|
|
---
|
|
|
|
# Knowledge Base Overview
|
|
|
|
This is the local (mutable) layer of a cascade knowledge base.
|
|
It sits above read-only upstream KBs in `../linked/` and `../libs/`.
|
|
|
|
## Cascade Priority
|
|
1. **wiki/** (local) — highest priority, agent-managed
|
|
2. **linked/\<name\>/** (symlinked) — read-only upstream source of truth
|
|
3. **libs/\<name\>/** (git-managed) — read-only external KBs
|
|
|
|
When the same entity exists in multiple layers, the local version wins.
|
|
|
|
## Directory Structure
|
|
```
|
|
.
|
|
├── libs/ # Git-managed external KBs (read-only, gitignored)
|
|
├── linked/ # Symlinks to upstream KBs (read-only)
|
|
├── outputs/ # Generated artifacts from the wiki
|
|
├── raw/ # User-provided source material
|
|
│ └── inbox/ # Drop zone for unprocessed material
|
|
├── tmp/ # Temporary files, caches (gitignored)
|
|
├── wiki/ # Local structured wiki (agent-managed)
|
|
│ ├── query-gaps.md # Failed or missing-answer questions for demand-driven ingest
|
|
│ ├── projects/ # Optional local query scopes
|
|
│ ├── decisions/ # Numbered, append-only decision records
|
|
│ ├── entities/ # Typed entity pages
|
|
│ └── graph/ # Edge lists and relationship data
|
|
└── workload/ # Summaries of discussions and decisions
|
|
```
|
|
|
|
## Page Frontmatter
|
|
Every wiki page carries YAML frontmatter with a required `type` field, plus
|
|
optional `resource`, `tldr`, `confidence`, `quality`, `supersedes`,
|
|
`freshness_window_days`, `retention`, `source_fingerprint`, and
|
|
`source_checked`. Pages with `type: decision` add
|
|
`status`, `decided_on`, `decided_by`, `affects`, and `review_on`. `wiki/index.md` additionally
|
|
declares `kb_schema_version` for the bundle as a whole.
|
|
See AGENTS.md for the full schema.
|
|
|
|
## Reserved Page Sections
|
|
Three `##` headings mean the same thing on every page in every layer:
|
|
|
|
* **`## Sources`** — one bullet per source, each carrying a fingerprint
|
|
(`sha256:` for a local file, `etag:`/`mtime:` for a connector item) and the
|
|
date it was last checked. This is what makes drift detectable mechanically
|
|
rather than by calendar.
|
|
* **`## Crux`** — verbatim excerpts from those sources, attributed to the
|
|
bullet they came from. Evidence, never paraphrase: a quote either still
|
|
matches its source or it doesn't.
|
|
* **`## Notes`** — human-authored and **protected**. No skill rewrites,
|
|
reflows, or drops it; regeneration preserves it byte-for-byte.
|
|
|
|
## Decision Records
|
|
`wiki/decisions/` holds one numbered page per decision (`NNNN-slug.md`),
|
|
recording what was decided, by whom, on what date, why, and which earlier
|
|
decision it supersedes or reverses. Decision pages are **append-only**: the
|
|
substance is never rewritten to match a later change of mind — a new decision
|
|
supersedes the old one and both stay on the record, so "why is it like this?"
|
|
keeps its original answer. Decision-specific frontmatter is `status`,
|
|
`decided_on`, `decided_by`, and optionally `affects` and `review_on`; the
|
|
existing `supersedes`/`superseded_by` pair carries the history. The
|
|
`ckb-decide` skill records them and answers questions about them.
|
|
|
|
## Recursive Indexes
|
|
`entities/`, `graph/`, `decisions/`, and optional topic folders such as
|
|
`projects/` each carry their own `index.md` so navigation stays lazy — read `wiki/index.md`
|
|
first, then only descend into a subdirectory index if its contents are
|
|
relevant to the current task.
|
|
|
|
## Local-First Retrieval Aids
|
|
Project scope pages in `wiki/projects/` can group related sources so a query
|
|
starts narrow before falling back to the full cascade. `wiki/query-gaps.md`
|
|
records questions the wiki could not answer yet, turning failed searches into
|
|
small ingest targets.
|