-
Notifications
You must be signed in to change notification settings - Fork 0
Core Concepts
The five ideas everything else builds on: docs bound to sources, verdicts computed from git,
trust and altitude labels that route behavior, layers that separate mechanics from judgment,
and a write gate that keeps humans in charge of the judgment half. Ten minutes here makes
every other page obvious. (Normative detail: SCHEMA.md in the repository; mechanics:
docs/HANDBOOK.md.)
The unit of knowledge is a doc: a short markdown file with strict frontmatter. Two fields carry the whole model:
-
sources— typed bindings naming where the fact comes from (file:,file-glob:, and friends; sections of a doc can carry their own narrower bindings). No sources, no doc: the contract is validated at the door. -
derived_from_commit— the anchor: the main-branch commit the fact was true at.
Together they make every fact checkable: the engine can always ask git "did any source of this doc change between its anchor and the current main tip?" — no model calls, no guessing.
Every read answers with a verdict, computed on the spot:
| Verdict | Meaning | Reader's move |
|---|---|---|
healthy |
sources unchanged since the anchor | use it; skip the re-derivation |
stale |
sources changed on the main line | re-check; kaut refresh says exactly what changed |
branch-advisory |
your current branch moved relevant files (main is clean) | fine on main; mind the branch delta |
broken |
a bound source no longer exists at the anchor tree | re-bind or re-derive |
tampered |
store content edited outside the pipeline | withheld entirely — content is not served |
The engine errs toward stale: whenever git cannot prove freshness (unknown anchor, diverged history, unresolvable ref), the verdict degrades. A false "stale" costs one re-check; a false "fresh" ships a bug.
Two labels ride along with every answer:
- Trust (T0–T4) — provenance quality: T0 = mechanically generated from code, up through human-confirmed. Low trust = read skeptically, verify against code.
- Altitude — coverage granularity (landscape / component / endpoint), back-derived from the doc's source bindings. A coarse (landscape) doc can be healthy and still too zoomed-out for your question — its answer arrives with an explicit "confirm in code" directive. Freshness tells you when the doc was true; altitude tells you how closely it covers what you're asking.
The standing discipline both labels serve: knowledge informs — it never authorizes. Healthy + precise is permission to skip re-derivation, never permission to act blindly.
The store is organized into directories that are the taxonomy:
| Layer | Holds | Typical write policy |
|---|---|---|
map/ |
mechanical maps (routes, packages, services) | regenerated by collectors |
runbook/ |
verified operational procedures | agent tier (through the gate) |
domains/ |
how a domain actually works | owner-gated |
decisions/ |
why it is this way (and not the obvious other way) | owner-gated |
contracts/ |
cross-component invariants | owner-gated |
flows/ |
end-to-end behavior across parts | owner-gated |
bootstrap/ |
how to get a working setup from zero | per policy |
What gets stored at all is decided by the litmus test: expensive to re-derive, not cheaply visible in the code, true at the anchor. If an agent can re-derive it from the code in seconds, don't store it — that's what the code is for.
Every write funnels through one chokepoint (a commit into the store's own private git), and the gate decides by layer and provenance. Which layers are agent-tier and which are owner-gated is policy, set per store or workspace; a store with no policy configured runs open (single-user mode — you are both the agent and the owner). The recommended policy:
-
Mechanical (
map/*): regenerate freely — it is a cache of the code, not an opinion. -
Agent tier (e.g.
runbook/*): an agent that verified the fact in this session may land the update directly; the commit is journalled and auditable. -
Owner-gated (decisions / domains / contracts / flows, and every novel doc): nothing
lands without a human. Updates queue as drafts — validated at the queue door
(contract + anchor), committed durably, but never served to readers — and the owner lands
or rejects the batch with
kaut review, one keystroke per doc.
The gate's flip side is tamper containment: content that did not come through the pipeline (an out-of-band edit, a crashed half-write) is not argued with — it is withheld from every reader until restored or legitimately landed. The store is read by AI agents; unreviewed bytes are an injection channel, and the engine treats them as one.
Each project gets its own store — a small private git repository outside your working copy (your repo is never modified; a single ignored pointer file links them). Multi-repo landscapes add a registry and one system store for cross-repo knowledge — see Connecting Your Project.