ckb/docs/CHANGELOG.md
Michał Kopeć c57ddceffd Template 2.2.0: voice and convert modules
- 2.1.0 new opt-in `voice` module (D-0020): skill ckb-voice rewrites every
  prose file written under apply_to (outputs/answers, documents, reports,
  PROJECT-OVERVIEW) in a voice whose profile is a wiki page,
  wiki/voice/<name>.md (type voice-profile); settings in ckb.yaml (mode,
  profile, writer, apply_to, skip, chat); frozen spans never change, vague
  claims flagged not cut; `writer:` delegates to an external rewriting
  skill such as a personal ghost-writer. ckb-module writes a manifest's
  default_config into the entry's config:. Eval ckb-module/install-voice.
- 2.2.0 new opt-in `convert` module (D-0021): skill ckb-convert and
  convert.py turn Markdown into Word/ODT/PDF/HTML through pandoc with a
  house style in templates/styles/; unit tests and eval
  ckb-module/install-convert.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 20:57:39 +01:00

475 lines
61 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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:<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:
```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
<!-- 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:
```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/<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.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/<name>.docx` (pandoc's reference document; optional `<name>.odt`/`<name>.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/<name>.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, `<private>`, 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=<venv>/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 `<private>` 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 `<name>-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 `<private>` 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 `<meta charset>` is read; `<form>` pages keep their text and an `<svg><title>` 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. `<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|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).