Michał Kopeć
65b1e422b3
Decision log (VERSION 1.6.0, kb_schema_version 1.4): - wiki/decisions/ scaffold — numbered NNNN-slug.md records, own index (with status vocabulary) and log - type: decision adds status/decided_on/decided_by/affects/review_on; supersedes/superseded_by carry history and must be set on both sides - New ckb-decide skill: records decisions and answers what/why/who/when, what superseded what, and what is still open. Decision pages are append-only — a changed mind is a new superseding decision - Graph gains decided_by and affects edge types - ckb-ingest routes decisions found in raw material to this format; ckb-retrieve gains the decisions index as a cascade step Scriptified the mechanical skills: - ckb-export-okf/scripts/export_okf.py does the whole OKF transform (frontmatter remap, link rewriting, index/log regeneration, conformance validation); --check validates without writing - ckb-lint/scripts/lint_report.py does the read-only detection half (conformance, freshness, confidence, retention, decisions, orphans, graph, index/log, source.yaml); judgment calls stay with the model Also: removed the duplicate personal quiz skill, fixed stale cbk-quiz doc paths, gitignored __pycache__. 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-01
|
|
---
|
|
|
|
# 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.
|