- 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>
475 lines
61 KiB
Markdown
475 lines
61 KiB
Markdown
# 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).
|