Fixes F7-F11 from the 2.0.0 script review: - UTF-8 stdout/stderr in every script; UTF-8 decoding of git/rg/yt-dlp output and of hook stdin - utf-8-sig reads, so BOM files keep their frontmatter - fingerprints match LF or CRLF checkouts (lint, lint_quick.sh, consolidate); prefix match on the full digest; short ones reported - POSIX paths in lint output; rg --path-separator / - hook installers default to the running interpreter, quote paths, --check reports a missing interpreter, odd settings are an error New tests/unit/test_windows.py. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
51 KiB
Changelog & Schema Reference
Read this in: English | Polski
This file tracks two things: the page schema exactly as it stands today, and how this project arrived at its current version numbers.
There are two independent version numbers, and they are not the same thing:
| Number | Lives in | Describes | Who bumps it |
|---|---|---|---|
kb_schema_version |
frontmatter of wiki/index.md |
the content contract - what a page may contain and what those fields mean | ckb-upgrade (on a confirmed migration), ckb-module (additively, on install) |
| Template version | VERSION |
the tooling layer - AGENTS.md, the skills, the scripts, the docs |
ckb-upgrade, when it pulls a newer template |
They move independently on purpose. You can take a newer set of skills without touching a single wiki page, and a wiki authored against an older schema keeps working - that is what the schema version is for.
Versioning policy. Bump the minor version for an additive change: a new optional field, a new optional body section, a new optional scaffold file. Bump the major version for a breaking one: changing or removing a required field, or changing an existing reserved filename convention. There has never been a major bump; every schema version to date has been additive, so any page written since 2026-07-13 is still valid today.
The template version follows the same rule for the tooling: major when
something a KB may rely on is removed. Its first major, 2.0.0, removed
PowerShell support. The previous major keeps getting fixes on a maintenance
branch named after it (1.x), and ckb-upgrade never crosses a major
without asking.
Contents
- Current page schema (1.7)
- KB schema version history
- Template version history
- Migrating between versions
Current page schema (kb_schema_version: "1.7")
Frontmatter — every non-reserved page
Every .md file under wiki/ except the reserved ones (index.md,
log.md) carries YAML frontmatter. Only type is required; the rest are
optional, and preferred where meaningful. The parser is deliberately simple -
flat key: value pairs only, no nesting.
| Field | Required | Meaning |
|---|---|---|
type |
yes | Open string: person, project, concept, library, decision, playbook, repository, component, … New values are always valid; readers tolerate unrecognised ones. |
resource |
no | Canonical URI of the authoritative external source this page describes, kept separate from the wiki's own commentary. |
tldr |
no | One-sentence summary optimised for LLM reading. This is what the index shows and what decides whether a page gets opened at all. |
confidence |
no | 0.0–1.0. Source corroboration. Set on write, decays if nothing reinforces it, raised by a new source that agrees. |
quality |
no | 0.0–1.0. Self-evaluation of the page's own structure and citations. Below 0.7 is flagged for review. |
supersedes |
no | Path to the older page this one replaces. |
superseded_by |
no | Path to the newer page that replaced this one. Always set both sides. |
last_updated |
no | YYYY-MM-DD. When the page last changed. |
freshness_window_days |
no | Days before lint flags the page as stale. Typical: 90 for a wiki page, 365 for a decision, 30 for a connector-indexed document. |
retention |
no | high / medium / low. A low page is archived (never deleted) after 2× its freshness window. |
source_fingerprint |
no | (1.5) Digest of the source this page was built from - sha256:<8 hex> for a local file, or etag:<value> / mtime:<iso8601> for a connector item. |
source_checked |
no | (1.5) YYYY-MM-DD - when that digest was last verified. Distinct from last_updated: a re-check that finds nothing changed advances this and leaves last_updated alone. |
review |
no | (1.6) draft / reviewed / needs_update. Absent means "not tracked". ckb-ingest writes draft on new pages and needs_update when it changes what a reviewed page claims; only a person's say-so sets reviewed (via ckb-lint). |
reviewed_by |
no | (1.6) Who last reviewed the page. Kept when the page moves to needs_update, as the record of the last review. |
reviewed_on |
no | (1.6) YYYY-MM-DD of that review. Lint flags a reviewed page whose last_updated is later. |
tags |
no | (1.6) Flat comma list, e.g. tags: retries, billing. Every tag must be a row in wiki/tags.md. |
wiki/index.md alone carries kb_schema_version. It is a bundle-level
declaration, not a per-page one - individual pages never carry it.
Frontmatter — decision pages
Pages with type: decision live in wiki/decisions/ as NNNN-slug.md and
add:
| Field | Required | Meaning |
|---|---|---|
status |
yes | proposed / accepted / rejected / superseded / reversed. The vocabulary is defined in wiki/decisions/index.md and validated by lint. |
decided_on |
for accepted/rejected/reversed |
YYYY-MM-DD, the date the call was made. |
decided_by |
when known | Comma-separated names. Where genuinely unknown, write unknown rather than omitting the field - "we don't know who decided this" is itself worth recording. |
affects |
no | Comma-separated wiki paths this decision constrains. |
review_on |
no | YYYY-MM-DD to revisit. Lint reports these once the date passes. |
Decision records are append-only. A decision is never rewritten to match a later change of mind: record a new one that supersedes it, and both stay on the record.
Reserved body sections
(New in 1.5.) Four ## headings mean the same thing on every page in every
layer of the cascade. All are optional; where present, they mean exactly this
and nothing else.
## Sources
Where the page came from. One bullet per source, each carrying a fingerprint:
## Sources
- `raw/archive/2026-09-21/kickoff-notes.md` — sha256:3f9a2c1e (checked 2026-09-21)
A freshness window is a guess that a source might have moved. A fingerprint is a fact about whether it did. Lint recomputes local digests and flags what actually changed, which is a different and more urgent finding than a page that has merely aged.
## Crux
Verbatim excerpts from those sources - evidence, never paraphrase - attributed to the source bullet they came from:
## Crux
> FDEs need the VDI *and* a Jira account before day one; the VDI request
> alone takes ten working days.
— `raw/archive/2026-09-21/kickoff-notes.md`, under "Access"
Three to ten lines is the working range. A Crux approaching the length of the summary above it has stopped being evidence and become a second copy of the source. Two things follow from quoting rather than paraphrasing: a question can often be answered from the page instead of the archive, and drift becomes visible - a summary can wander from its source silently, a quote either still matches or it does not.
A page with no quotable source simply has no ## Crux. An empty or
paraphrased one is worse than none, because it looks like evidence.
## Notes
Human-authored, and protected. No skill may rewrite, reflow, summarise or drop this section; regeneration preserves it byte-for-byte.
## Notes
<!-- Yours. Never rewritten by any skill. -->
This matters most on pages the agent regenerates - connector indexes, code
maps - where everything else is discarded and rebuilt on the next run. It is
the only place an annotation survives. Decision pages deliberately have no
## Notes: nothing regenerates them, and an append-only record with a freely
editable annotation block invites exactly the retroactive revision the
append-only rule exists to prevent.
## Rules
(1.6.) On a wiki/projects/ scope page only: the team's rules for that
project, which apply while working inside the scope. Human-authored and
protected exactly like ## Notes. They yield only to AGENTS.md; a person's
profile yields to them.
The contradiction marker
(1.6.) Not a section but a body line, written where two sources disagree and nobody has decided which is right:
> CONTRADICTION: three retries (`raw/archive/2026-09-01/kickoff-notes.md`) vs five retries (`raw/archive/2026-11-02/runbook.md`) — found 2026-11-02
It stays until a person resolves it (supersession, a decision, or an edit), and lint lists every open one (check 18).
Edge vocabulary
Relationships live in wiki/graph/edges.json (and each connector index's own
graph/edges.json). The vocabulary is closed, and each verb is defined by the
question it answers - if a proposed edge answers none of them, it belongs in
the page's prose instead.
| Verb | Question it answers | Since |
|---|---|---|
part_of |
Where does this live? What is it a piece of? | 1.5 |
uses |
What does this reach for at runtime? | 1.1 |
depends_on |
What breaks if I change this? | 1.1 |
produces |
Where does this output come from? | 1.5 |
configures |
What changes this thing's behaviour? | 1.5 |
validates |
What checks, tests, or judges this? | 1.5 |
implements |
What contract must this honour? | 1.5 |
caused |
Why did this happen? | 1.1 |
contradicts |
What disagrees with this, unresolved? | 1.1 |
supersedes |
What replaced this, and what did it replace? | 1.1 |
decided_by |
Who made this call? | 1.4 |
affects |
What does this decision constrain? | 1.4 |
has_expertise_in |
Who can answer questions on this? | 1.3 |
owns |
Who is responsible for this? | 1.3 |
mentioned_in |
Which source document discusses this? | 1.2 (lib indexes only) |
Record one direction per relationship - part_of, supersedes,
depends_on and uses are canonical, and the inverse is not stored as a
second edge. Record edges only from demonstrated evidence; an absent edge
beats a fabricated one, and a padded graph degrades retrieval rather than
improving it (in-degree is used as a ranking signal).
Reserved scaffold
| Path | Since | Purpose |
|---|---|---|
wiki/index.md |
1.1 | Routing table; the only page carrying kb_schema_version |
wiki/overview.md |
1.1 | High-level map of the KB |
wiki/log.md |
1.1 | Reverse-chronological change log for wiki/ |
wiki/error-book.md |
1.1 | Systemic issues with root cause and fix |
wiki/entities/ |
1.1 | Typed entity pages |
wiki/graph/ |
1.1 | edges.json plus the vocabulary in index.md |
wiki/query-gaps.md |
1.2 | Questions the wiki could not answer, driving demand-driven ingest |
wiki/projects/ |
1.2 | Optional local query scopes |
wiki/decisions/ |
1.4 | Numbered, append-only decision records, with their own log.md |
wiki/tags.md |
1.6 | The KB's own closed tag vocabulary (type: vocabulary); lint checks tags: against it |
wiki/topics/ |
1.7 | Topic summaries (type: topic) built by ckb-consolidate, with member-page digests as sources |
wiki/lessons.md |
1.6 | KB-wide lessons, created on first use by ckb-profile (type: lessons) |
Every subdirectory that groups pages carries its own index.md, so
navigation stays lazy.
KB schema version history
1.7 — 2026-11-02 · topic summaries
D-0016. A new optional
directory wiki/topics/ with an index.md, and type: topic pages built by
ckb-consolidate from a cluster of member pages: ## Summary, ## Members,
## Sources (member digests, so lint flags drift) and ## Notes. Additive.
Migration (ckb-upgrade Step 7 b4): add wiki/topics/index.md and its
routing row, bump the version; no topic pages are generated.
1.6 — 2026-11-02 · review, contradictions, tags, project rules
From the 2026-10-31 agent-knowledge research (features F7, F4, F21, F9, F8), decided in D-0014. Additive: a 1.5 page is a valid 1.6 page.
- Review fields
review/reviewed_by/reviewed_on. The plan's name wasstatus, which decision pages already use with a different vocabulary. - Contradiction marker
> CONTRADICTION: …instead of a silent winner. Claim-levelvalid_from/valid_toare deferred. tagschecked against the new scaffold filewiki/tags.md.## Rules, a protected section on project scope pages.wiki/lessons.md, created on first use.
Outside wiki/ and so outside the schema, but shipped together: per-person
profiles in workload/profiles/ and the ckb-profile skill.
Migration (ckb-upgrade Step 7 b3): add wiki/tags.md and its index
row, bump the version. review is backfilled only on request, and only to
draft.
1.5 — 2026-09-21 · evidence, fingerprints, and a completed edge vocabulary
Adopted from an analysis of trailhq/Graft, a context layer for coding agents that keeps a derived code graph in sync via content hashes rather than dates, and protects a user-authored block on every regenerated node. Graft's store is disposable and regenerable; this one is not, so most of its design does not transfer - but several mechanisms do, and two of them closed real gaps here.
Added:
## Crux- verbatim source excerpts alongside the synthesis. Letsckb-retrieveground an answer without a round-trip to the archive (when the fingerprint still matches), and makes drift detectable.## Notes- human-authored and protected everywhere. This closed a real gap:ckb-index-externalregenerates connector pages wholesale, so an annotation written there was previously destroyed on the next refresh.## Sources- formalised as a reserved section with one fingerprinted bullet per source. Previously an informal convention thatckb-retrieverelied on but no skill actually specified.source_fingerprint/source_checkedfrontmatter.- Edge verbs
part_of,produces,configures,validates,implements.part_offixed a live inconsistency:ckb-code-maphad been writing it since template 1.7.0 while the schema never declared it.
Changed:
wiki/graph/index.mdrewritten as a question-per-verb table with conventions on edge direction and evidence.ckb-ingestgained a blast-radius step: before writing, walk the graph backwards from touched entities to find what the incoming material confirms, extends or contradicts, and name the owners of affected pages. Ingest had been additive-first, which is how a wiki accumulates two pages that quietly disagree.ckb-retrievefuses graph in-degree as one ranked list among several, weighted below 1.0 - centrality is a prior, not evidence.- Rule E (session start) now runs
lint_report.py --quickalongsidegit status: a deterministic one-line knowledge-rot signal costing no model tokens. - Lint gained checks 12 (fingerprint drift), 13 (crux verbatimness) and 14
(the protected-
## Notesrule).
Compatibility: fully additive. A 1.4 page with none of the new sections or
fields is valid 1.5. A migration will never manufacture a ## Crux -
inventing quotes is precisely the failure that section exists to prevent.
1.4 — 2026-09-01 · decision records
Added: type: decision pages under wiki/decisions/ as NNNN-slug.md,
with status, decided_on, decided_by, affects, review_on; the
decided_by and affects edge verbs; wiki/decisions/index.md and its own
log.md; the append-only rule. Answers "why is it like this", "who decided",
and "what changed that decision" as direct lookups instead of a full-text
guess. Owned by the ckb-decide skill.
1.3 — 2026-08-06 · people-to-topic edges
Added: the has_expertise_in and owns edge verbs, making "who knows
about X" and "who owns X" a graph lookup rather than a full-text search.
Recorded only from demonstrated evidence - attending a meeting is not
expertise, and a job title is not ownership.
1.2 — 2026-07-29 · query scopes, gaps, and connector-backed libs
Added: wiki/projects/ (optional local query scopes grouping related
pages, sources and graph areas); wiki/query-gaps.md (failed searches
recorded as future ingest targets); raw/archive/<YYYY-MM-DD>/ as the
agent-maintained filing destination; connector-backed libs/<name>/ with a
user-authored source.yaml, an agent-owned generated index, and the
mentioned_in edge verb used inside those indexes.
1.1 — 2026-07-13 · initial schema
The first versioned contract, shipped with the initial commit. Established
the frontmatter field set (type, resource, tldr, confidence,
quality, supersedes/superseded_by, last_updated,
freshness_window_days, retention), the core edge verbs (uses,
depends_on, caused, contradicts, supersedes), the wiki/ scaffold,
the cascade priority rule, and the recursive index-and-log convention.
There was never a 1.0: versioning began with the first published schema.
Template version history
The tooling layer - AGENTS.md/CLAUDE.md, the skills, the scripts, the
docs. Independent of the content schema above.
| Version | Date | What landed | Schema |
|---|---|---|---|
| 2.0.3 | 2026-11-11 | Windows fixes from the 2.0.0 script review, no new features. Encoding: every script's output is UTF-8 whatever the console code page (a Polish page name or a → crashed lint, session start, retrieve, consolidate, dedup, the exporters, capture and share on a cp1252 console); every git/rg/yt-dlp call is decoded as UTF-8 (a git name like Łukasz crashed session_start.py; Michał came out garbled and gave the wrong author slug); hook input on stdin is read as UTF-8 bytes (autosave silently never saved under a non-ASCII user folder). BOM: Markdown, YAML and JSON are read as utf-8-sig, so a page saved by Notepad keeps its frontmatter. Line endings: a sha256: fingerprint matches the file as stored, with LF or with CRLF endings, in lint_report.py, lint_quick.sh and consolidate.py, so a core.autocrlf checkout no longer reports every source as changed; a fingerprint is compared as a prefix of the full digest, so a correct one shorter than 8 characters no longer reads as CHANGED, and one under 6 is reported as too short to check. Paths: lint prints POSIX paths and retrieve asks ripgrep for / separators, so the exact-match signal works on Windows. Hooks: start_hook.py/autosave_hook.py --install default to the interpreter that ran them, quoted with forward slashes (a C:\Program Files\… path broke the command); --check reports a hook whose interpreter is missing, and a settings file that isn't an object is an error, not a traceback. New tests/unit/test_windows.py simulates a cp1252 console, CRLF and BOM files, Polish git names and odd settings files |
1.7 |
| 2.0.2 | 2026-11-11 | Security fixes from the 2.0.0 script review, no new features. share module: a message's file name and mailbox must be plain names, and its from, share_id and version must match its mailbox, or it is ignored with a warning, so a channel member can no longer write lines into the receiver's ckb.yaml (a newline in a file name became a routines: block) or reach outside raw/inbox/ (share_id: x/../../wiki/…); the ledger refuses whitespace and control characters. Every commit that touched a message must come from an owner of its mailbox, not only the one that added it, and a mailbox listed twice in members.yaml is unowned. Only a verified retraction hides a message not yet taken. Channel branch/url/name are validated before they reach git, and git clone gets -- (a branch: --upload-pack=… ran a command). The received copy always carries untrusted: true; the sender's untrusted and review fields are dropped. <private> spans are stripped from the title and tldr too, and an unclosed tag drops the rest of the text. With no lint_report.py the send is refused (exit 3) instead of going out unscanned. README states that members.yaml is trusted as written; a git host enforcing paths is the real guard. capture module: frontmatter values are left plain only when nothing in them is YAML syntax, else written as JSON strings, and the page title is one line, so a <title> with --- in it can no longer close the frontmatter and drop untrusted: true. Lint check 13: a ## Crux quoted from a chat or a person no longer needs a ## Sources section (AGENTS.md §2); one quoting a local file still does. Tests: tests/unit/ gains hostile-channel cases for share (10), capture frontmatter, and check 13 |
1.7 |
| 2.0.1 | 2026-11-11 | Fixes from the 2.0.0 script review, no new features. Python 3.8 again: removeprefix/removesuffix (3.9+) replaced in lint_report.py, retrieve_candidates.py, consolidate.py and the mcp server; on 3.8 any KB with wiki/graph/edges.json crashed lint, the session-start check, retrieve and consolidate. routines.py --mark no longer writes last_run:2026-… with no space (invalid YAML for any real parser) on a freshly added routine, and keeps a trailing comment as a comment instead of making it part of the value. Exporters stay inside their folder: export_okf.py --out must name a folder inside outputs/ (it is deleted and rebuilt; --out . used to delete the repo), and export_starlight.py copies an image only from inside wiki/assets/ to inside its own assets, so ../assets/../../x in page text can no longer read or write files elsewhere. Docs: the script count is eight core skills (ckb-consolidate, ckb-routine, ckb-add-conversation were missing) in AGENTS.md, both READMEs and both manuals. New tests/unit/ (stdlib unittest, run by smoke.sh): a static Python 3.8 guard over every shipped script, routines.py round-trips, exporter containment, and AGENTS.md consistency with the skills on disk |
1.7 |
| 2.0.0 | 2026-11-11 | Breaking: PowerShell support removed (D-0019). ckb-lint/scripts/lint_quick.ps1 is deleted, and so are the PowerShell version comparison in ckb-upgrade Step 2 and every "or the .ps1" mention (AGENTS.md Rule E and §3, ckb-lint, its manual checklist, ckb-sync-changes, both READMEs and manuals). Without Python, the session-start fallback is lint_quick.sh, on Windows under Git Bash. Every script the template and its modules ship is Python (AGENTS.md §3); lint_quick.sh and the mcp container entrypoint.sh are the named exceptions. KBs that need PowerShell stay on the 1.x branch ("switch this KB to the 1.x branch"), which gets fixes only. ckb-upgrade now deletes files that upstream removed from a skill or module folder it still ships, listed as Removed files in Step 5. No schema change |
1.7 |
| 1.28.1 | 2026-11-11 | Release channel 1.x: the maintenance branch for the 1.x line once 2.0 ships, fixes only, and the last line with PowerShell support (D-0019). Listed in the channel tables of ckb-init, ckb-upgrade, AGENTS.md, both READMEs and both manuals, and in the ckb.yaml comment. ckb-upgrade Step 2: a higher major version upstream stops the run before Step 4, quotes the breaking part of the upstream changelog row, and offers the new major or a switch to the maintenance branch; never crossed from a routine or batch run |
1.7 |
| 1.28.0 | 2026-11-11 | New opt-in share module (D-0018): skill ckb-share and share.py (join/send/unshare/list/receive/status, stdlib + git). A channel is a separate git repo per trust group with CHANNEL.md, members.yaml (kb → owner emails) and one append-only mailbox per KB, mail/<kb>/, cloned into tmp/share/<channel>/. Send packs a self-contained copy of an outputs/documents/, outputs/answers/ or wiki/ page (raw/archive/ only with --raw-ok): <private> spans and ## Notes dropped, local links as text, Sources/Crux paths marked <kb>:; envelope type: share, kind, share_id, version, from, to, sent_by, untrusted: true; lint's secret patterns block the send (exit 3), a dry run prints the ABOUT.md sensitivity section, the user confirms. Re-sending makes the next version. Receive copies messages addressed to the KB into raw/inbox/ with share_channel, share_ref, received_on, submitted_by (git author) and supersedes_source; a message whose git author is not an owner of its mailbox is UNVERIFIED and taken only with --accept-unverified; a retraction becomes raw/retractions/ requests for every held version. A received: ledger in the script-owned share: block of ckb.yaml keeps handled messages from returning. dedup_inbox.py reports SAME SHARE; ckb-ingest and ckb-retract know share files and requests. Smoke test covers two KBs and a bare-repo channel end to end |
1.7 |
| 1.27.0 | 2026-11-02 | New core skill ckb-feynman, adapted from the feynman skill in superhero-tech-super-brain: explains one page in plain words with a concrete example and a → [[page]] · [Title § Heading](/wiki/…#anchor) line under each block, then sorts every thin spot into Wiki, Sources or Mine gaps without filling any from model knowledge, asks for an explain-back and ends with numbered next moves. Candidates come from review: draft/needs_update, single-source, stale or contradicted pages; topic pages are followed to their members; Crux fingerprints are checked as in ckb-retrieve Step 6; <private> spans are never explained. Sessions go to outputs/teaching/feynman/YYYY-MM-DD_<slug>.md (type: feynman-session, fingerprinted ## Sources, gitignored with outputs/teaching/, no wiki/log.md entry); a Sources gap reaches wiki/query-gaps.md only on a yes. ckb-teach-me skips the folder; ckb-init, AGENTS.md routing row, both READMEs and manuals updated; eval case ckb-feynman/session with a recorded reference run (6/6). outputs/teaching/ added to the directory contract; run_evals.py matches deleted files with glob semantics (** was one segment) |
1.7 |
| 1.26.2 | 2026-11-10 | ABOUT.pl.md: the Polish pair of the ABOUT.md scaffold, like the other .pl.md docs. Agents read both when both are filled in and ABOUT.md wins on a conflict (AGENTS.md, ckb-ingest); ckb-init copies both and puts a Polish answer in the Polish file; ckb-upgrade creates it once for KBs below 1.26.2 and never recreates a deleted one; ckb-reset leaves it alone; the mcp server's kb_overview includes it and its description falls back to its tldr, ignoring either placeholder. README.pl.md and QUICKSTART.pl.md point to it; both manuals list it |
1.7 |
| 1.26.1 | 2026-11-02 | Docs: a one-page quickstart, docs/QUICKSTART.md and docs/QUICKSTART.pl.md, from an empty folder to the first ingest, answer, lint and sync; linked from both READMEs and both manuals |
1.7 |
| 1.26.0 | 2026-11-02 | Agent-knowledge release 3, batch 3 (D-0017). Capture module (F11): new opt-in .agents/modules/capture/ with skill ckb-capture and capture_url.py: a link becomes raw/inbox/YYYY-MM-DD_<slug>.md (type: capture, source_url, fetched_on, fetched_via, untrusted: true, a banner) from a stdlib fetch with readable-text extraction; the Wayback Machine's closest snapshot is used only when the live page failed or was thinner; --from-file wraps text the agent fetched itself; PDFs are saved as files; --media writes a timestamped transcript through yt-dlp, only with consent; one retry on 429/503. dedup_inbox.py compares a capture's source_url with archived captures and inbox twins, and capture removes its own duplicate. Skill evals (F22): tests/run_evals.py (list/prepare/check/validate) and five structural cases in tests/evals/ (ingest batch, retrieve unanswerable and keep-answer, decide, retract), with a recorded reference run for ckb-decide/record (7/7). Multi-agent (F18): manual section with untested setups for Codex CLI, Cursor, OpenCode and Gemini CLI and a table of Claude Code-only features; AGENTS.md tells agents without skill loading to read SKILL.md. Smoke test covers capture against a local server and Wayback stand-in, and the eval runner both ways |
1.7 |
| 1.25.0 | 2026-11-02 | Agent-knowledge release 3, batch 2: maintenance, schema 1.7 (D-0016). New skill ckb-consolidate with consolidate.py: a proposals-only report in outputs/reports/YYYY-MM-DD_consolidation.md with topic clusters (scope members, shared tags, linked groups of three or more) and whether each topic page is missing, current or outdated, merge candidates (same type, title/tldr overlap ≥ 0.5), missing links (two shared sources, or one plus a shared scope), stale/drifted pages from lint, and old log entries by month (the log is never rewritten) (F13). Topic pages (type: topic) in the new wiki/topics/, built only on approval, with member-page digests in ## Sources so lint flags drift; ckb-retrieve routes "what does the KB say overall" questions to wiki/topics/index.md first (F15). ckb-upgrade b4, ckb-init, ckb-reset know wiki/topics/; ckb-routine suggests a fortnightly Consolidate --confirm. Smoke test covers clustering, topic states and the report |
1.7 |
| 1.24.0 | 2026-11-02 | Agent-knowledge release 3, batch 1: retrieval (D-0015). Section search (F10): retrieve_candidates.py adds a bm25 list from a stdlib SQLite FTS5 index of page sections, with the page title, heading path and tldr in a separate context column (contextual retrieval); the cache tmp/ckb-fts.sqlite refreshes by mtime then sha256 (in memory without tmp/, skipped without FTS5); candidates list up to three #anchor (Heading) section hits. New benchmark tests/bench_retrieval.py over tests/fixtures/bench-kb/ (12 pages, 20 questions): hit@1 14/20 and hit@3 20/20 with and without bm25. Weight kept at 1.0 rather than tuned; the misses come from the tldr signal over-matching generic words. Token costs (F12): ~N tok per candidate; the skill reads index → section → page. Access log (F16): --opened PATH… appends pages read to the per-machine tmp/access.log; lint_report.py --cold [DAYS] proposes moving unread pages to a ## Archive index section, never moves anything. Answer formats (F17): ckb-retrieve offers a table, chart, deck or HTML page once when the answer has that shape. Smoke test covers the index cache, section hits, the access log, cold proposals and the benchmark |
1.6 |
| 1.23.0 | 2026-11-02 | Agent-knowledge release 2, schema 1.6 (D-0014). Review (F7): optional `review: draft | reviewed |
| 1.22.1 | 2026-11-02 | Hooks start from the project root. Claude Code runs a hook in the session's current directory, so the autosave Stop hook's relative save_conversation.py path resolved against whatever folder the shell had moved into: a session working inside a nested repo saved its transcript there, and in a folder without the script the save failed silently. autosave_hook.py and start_hook.py now write cd "${CLAUDE_PROJECT_DIR:-.}" && …; --check reports an entry installed before this fix as outdated (the session-start brief asks once), and --install replaces it without touching other hooks. Smoke test runs both installed hooks from a subfolder |
1.5 |
| 1.22.0 | 2026-11-02 | Agent-knowledge release 1: seven features from the 2026-10-31 research, no schema change. Session-start hook (F1): session_start.py --hook prints the Rule E brief as SessionStart additionalContext on startup, resume, /clear and after every compaction; start_hook.py --check/--install/--remove manages it in the gitignored .claude/settings.local.json; opt-in via session: start_hook: in ckb.yaml, with a start hook: brief line when the two disagree; Rule E stays the fallback (D-0011). Kept answers (F2): ckb-retrieve Step 8 offers to keep a substantial answer in outputs/answers/ (type: answer) with fingerprinted ## Sources and ## Gaps, updates rather than duplicates, and files back only through ingest; lint check 16 reports kept answers whose sources moved (D-0013). Ingest check-in (F3): before writing, ckb-ingest shows its reading of each source, the pages it will touch and what it contradicts, then waits; batch mode ("ingest in batch", or a confirm: false routine) skips it; the ingest report gains ## Check-in. Open threads (F5): ### Open threads checkboxes in workload notes (Rule D), collected by session_start.py into a threads: line with the five oldest and a 30-day stale mark; no shared status file (D-0012). Capture-time dedup (F6): new ckb-ingest/scripts/dedup_inbox.py reports DUPLICATE, SAME TEXT, CITED, SAME URL and INBOX TWIN against raw/archive/ and cited fingerprints/URLs before ingest. Secret and privacy guards (F19): lint check 15 scans committed text for credential shapes and wiki/ for <private> spans, masks matches, honours a line-hash .secrets-allow; --quick counts it, --secrets runs it alone and ckb-sync-changes runs it before staging; ingest drops and retrieval never quotes <private> spans; save_conversation.py redacts them (D-0013). Context budget (F20): lint_report.py --budget estimates AGENTS.md plus skill descriptions at characters ÷ 4; --quick flags it above budget: always_loaded_tokens (default 9000). Baseline: ~6,620 tokens at 1.21.0, ~6,810 at 1.22.0. Bash/PowerShell quick fallbacks gain a reduced secret check; smoke test covers every new script |
1.5 |
| 1.21.0 | 2026-10-31 | ABOUT.md. New root file, written by the KB's owner, stating what the KB holds: purpose, audience, scope (in and out), owners and contacts, expected sources, sensitivity, language and terms, each shipped as a comment saying what to write; type: about with a tldr. README.md/README.pl.md link to it under the source-repo pointer, since the README itself is the template's and is overwritten on upgrade. Agents read it and never edit it unless asked; questions about the KB itself are answered from it before wiki/overview.md, which stays the agent's summary of what was ingested and now links to it. ckb-ingest Step 1 names material outside its scope or ruled out by its sensitivity section and ingests it only on the user's say-so. ckb-init copies the scaffold and asks one optional question for Purpose and tldr; ckb-upgrade creates it only when missing and never diffs it; ckb-reset never touches it. mcp module: kb_overview starts with it and the server's KB description comes from its tldr (the scaffold placeholder is ignored). Directory contract and manual updated. D-0010 |
1.5 |
| 1.20.0 | 2026-10-30 | Ingest reports. ckb-ingest gains Step 8: every run that ingested something writes one file, workload/ingest-reports/YYYY-MM-DD_HHMM_<author>_ingest.md (type: ingest-report), listing raw files taken in and their archive path and fingerprint, decisions recorded, entities created/updated, other pages, graph edges, the blast radius (confirmed/extended/contradicted with owners, query gaps closed) and inbox files not ingested; every section kept with - none when empty. Written once, outside retrieval, no wiki/log.md entry, untouched by ckb-retract; a subfolder so session_start.py keeps reading only session notes. The old Step 8 (summary and sync reminder) becomes Step 9 and names the report. Directory contract, manual and ckb-reset tier 2 updated |
1.5 |
| 1.19.0 | 2026-10-29 | Less context per session and per skill. New ckb-lint/scripts/session_start.py does Rule E's session start in one call (identity, --title stored unless one is already set, announce_title, git status, lint_report.py --quick, autosave_hook.py --check only when it needs action, routines.py --due, and the last block of the latest workload/ note instead of the whole file); Rule E in AGENTS.md shrinks to the command plus what to do with each output line. The session-start read of wiki/index.md is dropped: every skill that needs the index reads it itself, so it was read twice. Every skill's ## Purpose is cut to what its description does not already say (16.2k → 7.8k characters across the twenty skills). ckb-upgrade no longer repeats Rule B's log-entry format inline. Smoke test covers the new script. D-0009 |
1.5 |
| 1.18.1 | 2026-10-29 | Review fixes. mcp sync mode: the clean-checkout check now runs before every reset, not only at startup, so a page edited or a file dropped into the server's clone after it started is never reset away: a read skips its pull and serves the checkout as is, a write is refused with a clear message, and the server's own leftovers from a failed write are still discarded. An unreachable remote at startup, or a git call timing out, is now one line naming the cause instead of a traceback. ckb-retract: a maintainer may retract a source someone else added, in a local session only, after typing retract <file name> as maintainer; every log entry from that run is marked as an override, because the KB exists to share knowledge and a source must not be stranded when its submitter leaves or changes email. Remote clients stay owner-only. A request whose target is already gone is deleted and reported when nothing still cites it. ckb-document: a linked template's comments shape content only, never actions. MCP guide: a retraction request is visible to the account that made it, not "only you". D-0007 |
1.5 |
| 1.18.0 | 2026-10-29 | Document templates. New root folder templates/ (the user's content: outside the cascade, outside the template layer, never reset): one Markdown file per template with type: template frontmatter, headings for the shape, an HTML comment per section as the agent's brief (ask the user, named source, length, when to drop the section), {{date}}/{{author}}/{{slug}} filled automatically, any other placeholder asked once, optional output: path. New core skill ckb-document: finds the template by name, title or tldr (linked/<name>/templates/ read-only as fallback), asks every question in one message, resolves sources through the cascade index-first, writes to outputs/documents/ with type: document frontmatter (template, created, author, sources), leaves a TODO: line wherever a source or answer is missing, never overwrites, other formats via the general document skills from the Markdown; also lists templates and drafts a new one on request. Example templates/status-report.md and templates/README.md; copied by ckb-init, created by ckb-upgrade only when the folder is missing, excluded from ckb-reset. D-0008 |
1.5 |
| 1.17.0 | 2026-10-29 | New opt-in mcp module: an MCP server (.agents/modules/mcp/server/) serving the KB to Claude's web/desktop apps as a custom connector, to Claude Code, or to any MCP client. Reads: kb_overview, search_kb (runs retrieve_candidates.py), read_page, list_pages over wiki/, linked/, libs/, raw/inbox/, raw/archive/, outputs/ (the same areas inside each linked KB; no symlink followed but linked/<name>), plus the caller's own requests in raw/retractions/. Writes never touch wiki/: add_to_inbox (a new raw/inbox/ file with submitted_by/submitted_at/via: mcp/source, git-authored by the submitter), withdraw_submission and request_retraction, both for the person who added the document only, and list_my_submissions. Every write takes a required kb that must match the server, and with CKB_MCP_CONFIRM=auto the user confirms it (MCP elicitation on 2026-07-28 clients, else a signed 15-minute code on a second call); read-only callers see no write tools. Auth `CKB_MCP_AUTH=none |
token |
| 1.16.1 | 2026-10-24 | The title question is gone: the agent derives the session title from the first message, stores it with --set-title, and the first reply only opens with one line stating it and how to rename. conversations.announce_title (default true) replaces ask_title. D-0006 |
1.5 |
| 1.16.0 | 2026-10-21 | Session titles and routines. Rule E's first reply in a new session is the question "What should this conversation be called?" (switch conversations.ask_title, default true); the answer is stored with save_conversation.py --set-title in gitignored tmp/conversation-titles/ and names the saved transcript (slug, heading, index row) and the workload block; a re-save under a new title replaces the old pair. New ckb-routine: routines: in ckb.yaml (name/do/every/confirm/last_run), checked at session start by routines.py --due; due routines run after the user's request in the same turn and are --marked only when they complete, confirm: true asks instead, manual runs count, ckb-reset/ckb-sync-changes refused. ckb-init writes both blocks, ckb-upgrade leaves them alone; smoke test covers both scripts. D-0005 |
1.5 |
| 1.15.0 | 2026-10-16 | tests/ is template-repo only: ckb-init no longer copies it, ckb-upgrade no longer ships it (and offers once to delete a leftover copy), directory contract and docs say so. The smoke test itself is unchanged |
1.5 |
| 1.14.0 | 2026-10-16 | Authorship for shared repos: the session identity (git config user.name/user.email, resolved once at session start) stamps every workload note, every wiki/log.md entry (new **Author:** line, optional, lint-neutral) and every saved conversation (save_conversation.py --author). Workload files become one per person per day, YYYY-MM-DD_<author>_summary.md with type: session frontmatter, so two people never merge-conflict in workload/; older files are read as before. D-0004 |
1.5 |
| 1.13.0 | 2026-10-16 | Conversation autosave switch: conversations.autosave in ckb.yaml (default false). On, Rule E saves every session at its end without asking; ckb-add-conversation toggles it on request ("save conversations automatically"). Per-machine half: autosave_hook.py --check/--install/--remove manages a Claude Code Stop hook in gitignored .claude/settings.local.json; Rule E runs the check at session start when autosave is on and asks before changing machine configuration; save_conversation.py --from-hook takes the transcript path from hook stdin. ckb-init writes the block, ckb-upgrade leaves it alone |
1.5 |
| 1.12.0 | 2026-10-16 | ckb-add-conversation: on request, copies the session's Claude Code transcript (JSONL, byte for byte) into raw/saved-conversations/<date>/ with a readable .md rendering and an index.md; answers "did we discuss X" / "what did I tell you about Y" from those files. Saved conversations are outside retrieval and outside ingest until the user copies one into raw/inbox/. Rule E asks once at session end whether to save; ckb-retrieve, ckb-ingest, ckb-reset (tier 3) and ckb-init know the folder; smoke test renders a fixture transcript |
1.5 |
| 1.11.1 | 2026-10-09 | Five defects fixed, all reported by a downstream KB. retrieve_candidates.py: load_pages walks sorted, so a golden expectation no longer encodes one machine's directory order (the smoke test failed on a clean clone); a source cited by N pages now corroborates all N instead of whichever page was walked first. lint_report.py check 12: a cited directory is legal and unfingerprinted, no longer reported as missing (same fix in lint_quick.sh/.ps1). Check 8: a root-log POINTER is no longer read as a duplicate of the decisions-log entry it points at. Check 13: a quote attributed to a conversation or a person counts as attributed, not unattributed. AGENTS.md §2 documents directory citations and the two attribution shapes; fixture KB covers all three lint regressions |
1.5 |
| 1.11.0 | 2026-09-29 | Python made optional where it can be: <python> interpreter resolution (python3/python/py -3) in AGENTS.md; per-OS install guide in the manual; lint_quick.sh/.ps1 fallback for the session-start check (smoke-tested against --quick); manual lint checklist and no-script retrieval path; exporters state Python as a hard requirement; inline python3 -c dropped from ckb-upgrade/ckb-reset; D-0003. Lint check 13 matches each Crux block only against the source attributed under it (multi-source Crux no longer cross-fails; wrapped quotes matched as one block); fixture KB gains a second source |
1.5 |
| 1.10.0 | 2026-09-24 | Skill descriptions and bodies slimmed (edge cases → references/); retrieve_candidates.py takes over rank fusion; docs moved to docs/, template ADRs restored to docs/decisions/; tests/ fixture + smoke.sh; ckb.yaml shipped; Rule B names the decisions-log exception; scaffold overview.md describes content, not schema; "Sync the wiki" trigger dropped |
1.5 |
| 1.9.0 | 2026-09-22 | Release channels: main/test/experimental branches, branch-aware ckb-init and ckb-upgrade, template: block in ckb.yaml |
1.5 |
| 1.8.0 | 2026-09-21 | Seven ideas adopted from Graft: crux/notes/fingerprints, --quick lint mode, in-degree ranking, ingest blast radius, completed edge vocabulary |
→ 1.5 |
| 1.7.0 | 2026-09-20 | Opt-in modules (.agents/modules/, ckb-module, ckb.yaml); the software module with ckb-code-map and ckb-spec; ckb-reset; OpenSpec docs |
1.4 |
| 1.6.1 | 2026-09-01 | Fixed false-positive broken-edge findings in the lint graph check | 1.4 |
| 1.6.0 | 2026-09-01 | ckb-decide; detection half of lint moved into lint_report.py; OKF export moved into export_okf.py |
→ 1.4 |
| 1.3.0 | 2026-08-06 | Rank fusion, dedupe and rerank in ckb-retrieve; expertise and ownership lookups |
→ 1.3 |
| 1.2.1 | 2026-07-29 | AGENTS.md compressed - workflows moved out into skills, leaving a small always-loaded rule set |
1.2 |
| 1.2.0 | 2026-07-29 | Project scopes, query gaps, source-verified retrieval | → 1.2 |
| 1.1.0 | 2026-07-20 | Connector-backed libs/ with self-contained external source indexing (ckb-index-external) |
1.1 * |
| 1.0.0 | 2026-07-17 | First tagged template: full skill set, LICENSE, MANUAL, bilingual docs |
1.1 |
* Connector-backed libs shipped as tooling in 1.1.0, but the schema only
recorded them - the source.yaml contract, the generated index shape, the
mentioned_in verb - at 1.2, nine days later. The two numbers catching up
with each other like this is normal, and is why the schema column shows what
was in effect after each template release rather than what the release was
about.
Versions 1.4.0 and 1.5.0 were never published - the template jumped from 1.3.0 to 1.6.0 on 2026-09-01.
Release channels
The template repo keeps three branches, and the version histories above track
main only:
| Branch | What it is | Who should track it |
|---|---|---|
main |
Stable - the released template | Everyone, by default |
test |
Release candidate - validated before merging to main |
Anyone helping validate a release |
experimental |
Development - active work, may be broken or reverted | People developing the template itself |
The branch a KB tracks lives in ckb.yaml:
template:
repo: https://git.wierzbowa.cloud/michal/ckb.git
branch: main
ckb-init writes it, ckb-upgrade reads it as the default and updates it when
you switch. No ckb.yaml and no template: block both mean main.
One consequence worth knowing: a KB that took tooling from test or
experimental can sit on a VERSION that main has not released yet.
Comparing it against main then finds nothing newer - which is true, but is
not the same as "up to date", and ckb-upgrade reports it as "ahead"
rather than as current. Moving such a KB back to main is a downgrade: it
can remove skills and lower kb_schema_version below what local pages are
written against. It requires an explicit confirmation, and is blocked outright
where the schema would drop below the content's own declared contract.
Migrating between versions
Say "upgrade the wiki" or "check for a newer template version". To use
a different channel, name it: "upgrade from the test branch", "check
experimental", "switch back to stable". The
ckb-upgrade skill checks the canonical template repo, updates the tooling
layer in place, and - separately, and only after you explicitly confirm -
migrates existing wiki/ content up to the current schema while preserving
every fact already collected.
The two halves are deliberately separate. Taking newer skills never rewrites
your pages, and a content migration is never silent: it reports what it
intends to change, batches anything it had to infer (such as a missing type)
for your confirmation, and logs every touched page in wiki/log.md marked as
a schema-migration backfill rather than new knowledge.
Template 1.10 moved MANUAL*, CHANGELOG* and OPENSPEC* from the repo
root into docs/. A KB upgrading from 1.9 or older has them at the root;
ckb-upgrade moves them and updates the links in README*. Nothing under
wiki/ is affected.
Because every schema version so far has been additive, an older wiki keeps working unmigrated. Migration is worth doing to make the newer checks meaningful - backfilled fingerprints are what give lint anything to verify - not because anything is broken without it.
Version & License
Current template version: VERSION. Current schema version: the
kb_schema_version field in wiki/index.md. Licensed under the
Apache License 2.0.