michal/ckb

Michał Kopeć 65b1e422b3 Add decision log, scriptify OKF export and lint detection

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>

2026-09-01 20:50:36 +02:00

3.1 KiB

Raw 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-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

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, 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.

3.1 KiB Raw Blame History