michal/ckb

Michał Kopeć 474630e2bb Adopt seven ideas from trailhq/Graft; schema 1.4 -> 1.5

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>

2026-09-21 22:44:26 +02:00

3.8 KiB

Raw Permalink Blame History

type	tldr	last_updated
overview	High-level map of the cascade knowledge base's directory structure, frontmatter schema, and layering rules.	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

wiki/ (local) — highest priority, agent-managed
linked/<name>/ (symlinked) — read-only upstream source of truth
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.

3.8 KiB Raw Permalink Blame History