Michał Kopeć
c998489c9a
Empty the KB back to the shape ckb-init creates: remove decision records
D-0001 and D-0002, the single graph edge, all five workload summaries and
the generated outputs/okf/ tree, then restore the empty scaffold with
kb_schema_version held at 1.4.
The decisions status-vocabulary table is preserved verbatim, since
ckb-decide and ckb-lint both validate against it. Lint reports 0 findings.
Restore point for the pre-reset content: tag pre-reset-2026-09-20 (0c06cb6).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
66 lines
3.1 KiB
Markdown
66 lines
3.1 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-20
|
|
---
|
|
|
|
# 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`, and `retention`. 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.
|
|
|
|
## 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.
|