# Changelog & Schema Reference *Read this in: **English** | [Polski](CHANGELOG.pl.md)* 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`](../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 1. [Current page schema (1.7)](#current-page-schema-kb_schema_version-17) 2. [KB schema version history](#kb-schema-version-history) 3. [Template version history](#template-version-history) 4. [Migrating between versions](#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:` / `mtime:` 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: ```markdown ## 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: ```markdown ## 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. ```markdown ## Notes ``` 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: ```markdown > 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](decisions/0016-topic-summaries-and-consolidation.md). 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](decisions/0014-schema-1-6-review-contradictions-tags-profiles.md). Additive: a 1.5 page is a valid 1.6 page. - **Review fields** `review`/`reviewed_by`/`reviewed_on`. The plan's name was `status`, which decision pages already use with a different vocabulary. - **Contradiction marker** `> CONTRADICTION: …` instead of a silent winner. Claim-level `valid_from`/`valid_to` are deferred. - **`tags`** checked against the new scaffold file `wiki/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](https://github.com/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. Lets `ckb-retrieve` ground 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-external` regenerates 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 that `ckb-retrieve` relied on but no skill actually specified. - `source_fingerprint` / `source_checked` frontmatter. - Edge verbs `part_of`, `produces`, `configures`, `validates`, `implements`. `part_of` fixed a live inconsistency: `ckb-code-map` had been writing it since template 1.7.0 while the schema never declared it. **Changed:** - `wiki/graph/index.md` rewritten as a question-per-verb table with conventions on edge direction and evidence. - `ckb-ingest` gained 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-retrieve` fuses 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 --quick` alongside `git 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-`## Notes` rule). **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//` as the agent-maintained filing destination; connector-backed `libs//` 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.2.0** | 2026-11-11 | New opt-in `convert` module (D-0021): skill `ckb-convert` and `convert.py` (stdlib; needs pandoc, LibreOffice optional). `convert` turns any KB Markdown file into `.docx`, `.odt`, PDF or HTML in a named house style, `templates/styles/.docx` (pandoc's reference document; optional `.odt`/`.css`). PDF and ODT are made by LibreOffice from the styled `.docx` (private profile), so every format looks the same; without it PDF falls back to a pandoc PDF engine and says the style wasn't applied. The copy is cleaned for outside readers: frontmatter → title/author (no e-mail)/date/lang, a leading `# H1` → title, template comments dropped, `[[wikilinks]]` and KB-path links → text (`--keep-links`), code blocks untouched. An existing output is refused without `--force`. **Styles without fonts by hand:** `new-style` copies pandoc's default reference and sets body/heading font, size, heading colour, paper (A4/Letter) and margins in `styles.xml`, the theme and the body `sectPr` in schema order; `--from` takes a company `.docx`/`.dotx` (content type rewritten, macros refused); `edit-style`, `check-style` (styles pandoc uses that a template lacks), `styles`, `doctor`. Scaffold `templates/styles/README.md`; settings `style`, `format`, `out_dir`, `toc`, `number_sections`, `keep_links` via `default_config`; routed by the module's `AGENTS.md` block, after `ckb-voice`. Tests: `tests/unit/test_convert.py`, eval `ckb-module/install-convert`. No schema change | 1.7 | | 2.1.0 | 2026-11-11 | New opt-in `voice` module (D-0020): skill `ckb-voice`, no script. Every prose file written under the configured `apply_to` paths (default `outputs/answers/`, `outputs/documents/`, `outputs/reports/`, `PROJECT-OVERVIEW*`; `outputs/okf/` and `outputs/starlight/` skipped) is rewritten in a voice before it is saved, whichever skill drafted it; the hook is the module's `AGENTS.md` block, so no core skill changed for it. **Profiles are wiki pages**, `wiki/voice/.md` (`type: voice-profile`, `voice_of: team/person/third-party`, Tone, Formality, Sentence style, Keep, Avoid, Audience, Opinions, Sample, `## Sources`, protected `## Notes`), created and logged by calibration from sample documents; standing preferences said in passing update one field. **Settings** in `ckb.yaml` (`mode: auto/ask/off`, `profile`, `writer`, `apply_to`, `skip`, `chat`); profile precedence: named in the request, then `voice:` on the person's `workload/profiles/` page, then the default. **Frozen spans** (frontmatter except a new `voice:` field, Sources, Crux and quotes with attributions, Notes/Rules, contradiction markers, ``, code, paths, links, numbers, names, a template's headings) are diffed before writing; a vague claim is flagged, never cut. `writer:` hands the rewrite to another installed skill such as a personal `ghost-writer`, with fallback. Rules adapted from that skill. `ckb-module` reads a manifest's `default_config` into the entry's `config:` and keeps edited values on reinstall. New type `voice-profile` and field `voice`, additive, no schema bump | 1.7 | | 2.0.9 | 2026-11-11 | Tests only. Golden outputs for both exporters on the clean fixture: the exact file list (`tests/expected/okf-files.txt`, 15 files; `starlight-files.txt`, 17) and the summary each prints (`okf-report.txt`, `starlight-report.txt`, including the OKF conformance verdict). Content is not compared, because OKF stamps the export date. This closes the last item of the 2.0.0 script review | 1.7 | | 2.0.8 | 2026-11-11 | Tests only. `tests/unit/test_mcp_server.py` covers the mcp server with the MCP SDK installed (2.3.0): a confirmation code confirms exactly one write and is bound to its payload and lifetime, a wrong `kb` is refused first, `_redact` masks secrets, the allowed-hosts default and override, a foreign `Host` header gets 421 over real HTTP while the public host gets 200, and OAuth tokens signed with a real RSA key — an unverified email no longer passes an `@domain` allow list, a verified one does, `CKB_MCP_OAUTH_TRUST_EMAIL=1` opts out, wrong audience and expired tokens fail. Without the SDK the tests skip; `CKB_MCP_PYTHON=/bin/python bash tests/smoke.sh` runs them. These confirm the 2.0.4 server changes, which until now were only compiled | 1.7 | | 2.0.7 | 2026-11-11 | Skill evals for the destructive and stateful skills, and the fix one of them found; no new features. **`ckb-reset`:** in a KB with no git repository, Step 0 asked for "a much more explicit confirmation" without saying what, so two runs asked for two different phrases; the phrase is now named, **`reset the wiki with no restore point`**, and the plain `reset the wiki` does not count there. **Nine new eval cases**, each run once by an agent on 2026-11-11 and passing: `ckb-reset/no-confirm` (inventory, nothing deleted), `ckb-reset/confirmed` (the plain phrase refused, the strict one accepted; tier 1 gone, scaffold back, `kb_schema_version` kept, raw/template untouched), `ckb-module/install` and `ckb-module/round-trip` (`AGENTS.md`, `.gitignore`, `ckb.yaml` byte-identical after uninstall), `ckb-upgrade/major-guard` (1.28.7 → 2.x stops and asks) and `ckb-upgrade/take-major` (VERSION 2.x, `lint_quick.ps1` deleted, wiki untouched), `ckb-decide/supersede` (both links set, D-0001's text untouched), `ckb-ingest/check-in-waits` and `ckb-ingest/reviewed-page` (`needs_update`, `## Notes` byte-for-byte). **Runner:** `replies` for the operator's answers when a skill stops and waits; setup steps `template` (template files, optionally from an older git ref) and `upstream` (a local bare repo for `ckb-upgrade`); `record` saves a passing run as `reference/` with a `.deleted` list and `replay` rebuilds and checks it; the smoke test replays every reference (five today). The runner's frontmatter reader takes frontmatter closed at end of file | 1.7 | | 2.0.6 | 2026-11-11 | Tests, and the parser fix they found; no new features. **Frontmatter readers agree:** the eight scripts that read page frontmatter (lint, retrieve, consolidate, both exporters, dedup, share, the mcp server) now all end it at a line that is exactly `---`, including one at the very end of the file; consolidate, dedup, OKF and share missed frontmatter closed without a final newline, and retrieve, Starlight and the mcp server ended it at any line starting with `---`. New `tests/unit/test_frontmatter_contract.py` feeds all eight the same cases. **Every lint check fires:** `tests/unit/test_lint_dirty.py` plants one fault per check (conformance, freshness, confidence, retention, decisions, orphans, graph, index/log, fingerprints, crux, review, contradictions, tags) in a copy of the fixture and asserts exactly which files each reports; the golden `lint.json` only proved the checks stay quiet on a clean KB | 1.7 | | 2.0.5 | 2026-11-11 | The remaining fixes from the 2.0.0 script review, no new features. **`routines.py`:** a `routines:` list written at column 0 (as PyYAML writes it) is read, and `--add` matches its indent; `--do` is written as a JSON-escaped string, so backslashes and quotes round-trip (`C:\docs` made invalid YAML); `--remove` takes a multi-line value's continuation lines. **`save_conversation.py`:** an unclosed `` redacts the rest of the message across its content blocks, not only the rest of one block; metadata outside the text is untouched. **OKF:** values with ` #`, a leading `- `/`? `/`: ` or a tab are quoted (`See issue #42` lost everything after `#`); a `# comment` in a code block is not the page title. **Search and consolidation:** tokens are Unicode words, so Polish queries match (`właścicielem` was `cicielem`). **Low-severity batch:** an impossible date in a workload file name no longer crashes the session brief; lint reads frontmatter closed on the last line without a newline, and an empty block; `wiki/…` references without a leading slash resolve in graph edges, supersession and `affects`, and count as one page in the most-linked list; Starlight exports a root page named like a reserved route as `-page` instead of overwriting it, resolves `[[Page|label]]`, accepts a string `source_files` in `edges.json`, and builds the splash buttons and cards from the sections that exist; both exporters drop `` spans. Tests for each | 1.7 | | 2.0.4 | 2026-11-11 | Security fixes from the 2.0.0 script review, no new features. **Secret scan (lint check 15):** hidden folders, `.pem`/`.key`/`.crt`/`.asc`, `.env*` and other dotfiles, and extensionless text files are scanned (only `.git` is skipped, binary files are detected); unquoted `password: …`, `client_secret=…` and `aws_secret_access_key = …` values are found when they look like secrets (a letter and a digit, or 20+ characters in mixed case), not prose; the size limit is 50 MB instead of 5 and a file over it is reported as not scanned instead of passed silently. **mcp:** `search_kb` returns only paths `read_page` would serve (it listed matches in a linked KB's `workload/` and saved conversations), and passes the query after `--`; the `.local.yaml` refusal ignores case and trailing dots; an OAuth `email` claim counts only with `email_verified: true` (`CKB_MCP_OAUTH_TRUST_EMAIL=1` for IdPs that never send it); DNS-rebinding protection is on by default for the public URL's host and loopback (`CKB_MCP_ALLOWED_HOSTS` replaces the list, `*` turns it off); a confirmation code works once. **capture:** link-local and cloud-metadata addresses are always refused and loopback/private networks need `--allow-private`, checked again on every redirect; a 90 s limit on the whole download; an unknown charset falls back and `` is read; `
` pages keep their text and an `` is not the page title; binary captures get safe extensions, never overwrite each other and are duplicate-checked. Tests: secret corpus, mcp search/read policy, capture fetching and parsing; the server's auth and confirmation changes are compiled but not run here (no MCP SDK) | 1.7 | | 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. `` 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 `` 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|needs_update` with `reviewed_by`/`reviewed_on` (the plan's `status` clashed with decision pages); `ckb-ingest` writes `draft` on new pages and `needs_update` when it changes what a reviewed page claims; lint check 17 flags only inconsistencies and prints a review queue; `ckb-lint` marks reviews on the person's say-so. **Contradictions (F4):** a `> CONTRADICTION:` body marker instead of a silent winner, listed by lint check 18 until resolved by supersession, a decision or an edit; claim-level validity dates deferred. **Tags (F21):** `tags:` checked against the new scaffold `wiki/tags.md` (check 19); `retrieve_candidates.py --tag`; `DRAFT`/`NEEDS_UPDATE` retrieval flags. **Scopes and profiles (F9):** `AGENTS.md` > a project scope's protected `## Rules` > a person's profile in `workload/profiles/`, printed by the session-start brief for the session identity only. **Lessons (F8):** on an explicit trigger only; personal in the profile, KB-wide in `wiki/lessons.md` (reviewed before relied on); the brief lists lessons new since the person's previous note. New skill `ckb-profile`. **Carry-over:** `.secrets-allow` accepts `<glob> match:<hash>` entries that cover one string on every line of growing transcripts (bash/PowerShell fallbacks too); open threads no longer print twice. Starlight shows review and tags and a "Needs update" badge; OKF passes the new fields through. `ckb-upgrade` Step 7 b3 migrates 1.5 → 1.6; `ckb-init`/`ckb-reset` know `tags.md`. Always-loaded ~7,245 tokens | 1.6 | | 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|oauth`: read-write and/or read-only tokens, or a per-person/agent file (read-only unless `"write": true`), as bearer header or `/<token>/mcp` secret path; oauth verifies an external IdP's JWTs (JWKS) or opaque tokens (introspection, `aud` required) with allow/writer lists and an optional write scope. **Several KBs:** one instance each, named by `CKB_MCP_NAME`/`CKB_MCP_DESCRIPTION`. **Git** `CKB_MCP_GIT=off|commit|sync`; sync resets its dedicated clone to the remote before every write and refuses a clone with local work. Stateless HTTP, Dockerfile, compose example, SSH deploy key; skill `ckb-mcp`; user guide `docs/MCP.md`/`MCP.pl.md`. Module READMEs (`software`, `mcp`) and a modules section in the manual, all in English and Polish. New core skill `ckb-retract` (requester must be whoever added the source; plan approved by the user; request text treated as data; git history still holds the content); `raw/retractions/` added to the directory contract, `ckb-init`, `ckb-upgrade`, flagged by `ckb-ingest` and `ckb-lint`, tier 3 in `ckb-reset`. `tests/mcp_policy.py` in the smoke test. D-0007 | 1.5 | | 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 `--mark`ed 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`: ```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](../VERSION). Current schema version: the `kb_schema_version` field in `wiki/index.md`. Licensed under the [Apache License 2.0](../LICENSE).