michal/ckb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add bilingual CHANGELOG with full schema and version history

Browse source 
Two version numbers exist in this project and are easy to confuse:
kb_schema_version (the content contract, in wiki/index.md) and VERSION
(the tooling layer). Until now neither had a written history, and the
page schema was documented in four places at three levels of detail.

CHANGELOG.md / CHANGELOG.pl.md consolidate both: the current schema in
full (frontmatter for all pages and for decisions, the three reserved
body sections, the closed edge vocabulary with a "since" column, the
reserved scaffold), then the schema history 1.1-1.5 and the template
history 1.0.0-1.8.0.

The history is reconstructed from git rather than from memory, so it
records what actually happened rather than a tidied version of it:

- There was never a schema 1.0; versioning began at 1.1 on 2026-07-13.
- Template 1.4.0 and 1.5.0 were never published — VERSION jumped from
  1.3.0 to 1.6.0 on 2026-09-01.
- Connector-backed libs shipped as tooling in 1.1.0, but the schema only
  recorded them at 1.2 nine days later. The schema column shows what was
  in effect after each release, with a footnote on the lag.

Registered with ckb-init (copied verbatim into a new KB) and ckb-upgrade
(taken wholesale from upstream rather than merged, since upstream is
authoritative about its own history). Cross-linked from both READMEs and
both MANUALs.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Michał Kopeć 2026-09-21 23:16:43 +02:00
parent 474630e2bb
commit 2c4d57acbc
9 changed files with 724 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
.agents/skills/ckb-init/SKILL.md
View file

@ -217,6 +217,10 @@ actual project entity):
should point somewhere else - it's what lets the new KB's own
`ckb-upgrade` find template updates later.
- `MANUAL.md` and `MANUAL.pl.md` - the task-oriented user guide.
- `CHANGELOG.md` and `CHANGELOG.pl.md` - the full page schema reference plus
the schema and template version histories. Copy verbatim: the history
belongs to the template, not to the new KB, and a fresh KB starts on the
version that history ends at.
- `VERSION` - copy the exact current value; the new KB starts life on the
same template version it was just cloned from.

11
.agents/skills/ckb-upgrade/SKILL.md
View file

@ -16,8 +16,8 @@ neither:
- **Template layer** — the schema/tooling that defines *how* the KB
behaves: `AGENTS.md`/`CLAUDE.md`, `.agents/skills/*`, `LICENSE`,
`VERSION`, `README.md`/`README.pl.md`/`MANUAL.md`/`MANUAL.pl.md`, and the
base `.gitignore` rules. Compared via the root `VERSION` file. Freely
`VERSION`, `README.md`/`README.pl.md`/`MANUAL.md`/`MANUAL.pl.md`/
`CHANGELOG.md`/`CHANGELOG.pl.md`, and the base `.gitignore` rules. Compared via the root `VERSION` file. Freely
upgradable — these files hold no project-specific content.
- **Content layer** — everything the KB has actually learned:
`wiki/entities/`, `wiki/graph/edges.json`, `wiki/index.md`'s entity rows,
@ -149,8 +149,11 @@ The template layer is exactly these paths — never anything under `wiki/`,
symlink)
- `LICENSE`
- `VERSION`
- `README.md`, `README.pl.md`, `MANUAL.md`, `MANUAL.pl.md` — whichever
exist upstream (an older local KB may not have some of these yet)
- `README.md`, `README.pl.md`, `MANUAL.md`, `MANUAL.pl.md`,
`CHANGELOG.md`, `CHANGELOG.pl.md` — whichever exist upstream (an older
local KB may not have some of these yet). Take the changelogs from
upstream wholesale rather than merging: they record the template's
history, which the upstream copy is authoritative about.
- `.agents/skills/<name>/**` for every skill folder present in
`tmp/ckb-upgrade-src/.agents/skills/`
- `.agents/modules/<name>/**` for every optional module present upstream

334
CHANGELOG.md Normal file
View file

@ -0,0 +1,334 @@
# 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.
---
## Contents
1. [Current page schema (1.5)](#current-page-schema-kb_schema_version-15)
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.5"`)
### 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. |
`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.
### 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` |
Every subdirectory that groups pages carries its own `index.md`, so
navigation stays lazy.
---
## KB schema version history
### 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 |
|---|---|---|---|
| **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.
---
## Migrating between versions
Say **"upgrade the wiki"** or **"check for a newer template version"**. 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.
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).

341
CHANGELOG.pl.md Normal file
View file

@ -0,0 +1,341 @@
# Historia zmian i referencja schematu
*Przeczytaj to w: [English](CHANGELOG.md) | **Polski***
Ten plik śledzi dwie rzeczy: schemat strony dokładnie w takiej postaci, w
jakiej obowiązuje dziś, oraz to, jak projekt doszedł do swoich obecnych
numerów wersji.
Istnieją **dwa niezależne numery wersji** i nie są tym samym:
| Numer | Mieszka w | Opisuje | Kto go podnosi |
|---|---|---|---|
| `kb_schema_version` | frontmatter `wiki/index.md` | **kontrakt treści** — co strona może zawierać i co te pola znaczą | `ckb-upgrade` (przy potwierdzonej migracji), `ckb-module` (addytywnie, przy instalacji) |
| Wersja szablonu | [`VERSION`](VERSION) | **warstwa narzędziowa** — `AGENTS.md`, skille, skrypty, dokumentacja | `ckb-upgrade`, gdy pobiera nowszy szablon |
Poruszają się niezależnie i jest to celowe. Możesz wziąć nowszy zestaw skilli
bez dotykania choćby jednej strony wiki, a wiki napisane pod starszy schemat
nadal działa — po to właśnie jest wersja schematu.
**Polityka wersjonowania.** Podnoś wersję **pomniejszą** przy zmianie
addytywnej: nowe pole opcjonalne, nowa opcjonalna sekcja treści, nowy
opcjonalny plik szkieletu. Podnoś wersję **główną** przy zmianie łamiącej
kompatybilność: zmiana lub usunięcie pola wymaganego albo zmiana istniejącej
zastrzeżonej konwencji nazw plików. Nigdy nie było podniesienia wersji
głównej — każda dotychczasowa wersja schematu była addytywna, więc dowolna
strona napisana od 2026-07-13 jest dziś nadal poprawna.
---
## Spis treści
1. [Aktualny schemat strony (1.5)](#aktualny-schemat-strony-kb_schema_version-15)
2. [Historia wersji schematu KB](#historia-wersji-schematu-kb)
3. [Historia wersji szablonu](#historia-wersji-szablonu)
4. [Migracja między wersjami](#migracja-między-wersjami)
---
## Aktualny schemat strony (`kb_schema_version: "1.5"`)
### Frontmatter — każda strona niezastrzeżona
Każdy plik `.md` w `wiki/` poza zastrzeżonymi (`index.md`, `log.md`) niesie
frontmatter YAML. Wymagane jest wyłącznie `type`; reszta jest opcjonalna i
preferowana tam, gdzie ma sens. Parser jest celowo prosty — wyłącznie płaskie
pary `klucz: wartość`, bez zagnieżdżeń.
| Pole | Wymagane | Znaczenie |
|---|---|---|
| `type` | **tak** | Otwarty ciąg: `person`, `project`, `concept`, `library`, `decision`, `playbook`, `repository`, `component`, … Nowe wartości są zawsze poprawne; czytelnicy tolerują nierozpoznane. |
| `resource` | nie | Kanoniczny URI autorytatywnego źródła zewnętrznego, które opisuje ta strona, trzymany oddzielnie od własnego komentarza wiki. |
| `tldr` | nie | Jednozdaniowe streszczenie zoptymalizowane pod odczyt przez LLM. To ono trafia do indeksu i decyduje, czy strona w ogóle zostanie otwarta. |
| `confidence` | nie | `0.0`–`1.0`. Potwierdzenie przez źródła. Ustawiane przy zapisie, zanika, jeśli nic go nie wzmacnia, rośnie przy nowym zgodnym źródle. |
| `quality` | nie | `0.0`–`1.0`. Samoocena struktury i cytowań samej strony. Poniżej `0.7` oflagowane do przeglądu. |
| `supersedes` | nie | Ścieżka do starszej strony, którą ta zastępuje. |
| `superseded_by` | nie | Ścieżka do nowszej strony, która zastąpiła tę. **Zawsze ustawiaj obie strony.** |
| `last_updated` | nie | `YYYY-MM-DD`. Kiedy zmieniła się *strona*. |
| `freshness_window_days` | nie | Liczba dni, po której lint oznacza stronę jako nieaktualną. Typowo: 90 dla strony wiki, 365 dla decyzji, 30 dla dokumentu z indeksu konektora. |
| `retention` | nie | `high` / `medium` / `low`. Strona `low` jest archiwizowana (nigdy usuwana) po 2× swoim oknie świeżości. |
| `source_fingerprint` | nie | *(1.5)* Skrót źródła, z którego zbudowano stronę — `sha256:<8 hex>` dla pliku lokalnego albo `etag:<wartość>` / `mtime:<iso8601>` dla elementu z konektora. |
| `source_checked` | nie | *(1.5)* `YYYY-MM-DD` — kiedy ten skrót był ostatnio zweryfikowany. To co innego niż `last_updated`: ponowne sprawdzenie, które nie wykryło zmiany, przesuwa to pole i zostawia `last_updated` w spokoju. |
Wyłącznie `wiki/index.md` niesie `kb_schema_version`. To deklaracja na
poziomie całego zbioru, nie pojedynczej strony — same strony nigdy jej nie
niosą.
### Frontmatter — strony decyzji
Strony z `type: decision` mieszkają w `wiki/decisions/` jako `NNNN-slug.md` i
dodają:
| Pole | Wymagane | Znaczenie |
|---|---|---|
| `status` | **tak** | `proposed` / `accepted` / `rejected` / `superseded` / `reversed`. Słownik zdefiniowany w `wiki/decisions/index.md` i walidowany przez lint. |
| `decided_on` | dla `accepted`/`rejected`/`reversed` | `YYYY-MM-DD`, data podjęcia decyzji. |
| `decided_by` | gdy wiadomo | Nazwiska po przecinku. Gdy naprawdę nie wiadomo, wpisz `unknown` zamiast pomijać pole — „nie wiemy, kto to zdecydował" samo w sobie warto zapisać. |
| `affects` | nie | Ścieżki wiki po przecinku, które ta decyzja ogranicza. |
| `review_on` | nie | `YYYY-MM-DD` do ponownego rozważenia. Lint zgłasza je po przekroczeniu daty. |
Rekordy decyzji są **tylko do dopisywania**. Decyzji nigdy nie przepisuje się
pod późniejszą zmianę zdania: zapisz nową, która ją zastępuje, a obie zostają
na wokandzie.
### Zastrzeżone sekcje treści
*(Nowość w 1.5.)* Cztery nagłówki `##` znaczą to samo na każdej stronie w
każdej warstwie kaskady. Wszystkie są opcjonalne; tam, gdzie występują,
znaczą dokładnie to i nic innego.
#### `## Sources`
Skąd wzięła się strona. Po jednym punkcie na źródło, każdy ze skrótem:
```markdown
## Sources
- `raw/archive/2026-09-21/kickoff-notes.md` — sha256:3f9a2c1e (checked 2026-09-21)
```
Okno świeżości to przypuszczenie, że źródło *mogło* się zmienić. Skrót to
fakt, czy *się zmieniło*. Lint przelicza skróty lokalne i oznacza to, co
faktycznie się zmieniło — a to inne i pilniejsze znalezisko niż strona, która
jedynie się zestarzała.
#### `## Crux`
Dosłowne fragmenty tych źródeł — dowód, nigdy parafraza — przypisane do
punktu źródła, z którego pochodzą:
```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`, sekcja „Access"
```
Roboczy zakres to od trzech do dziesięciu linijek. Crux zbliżający się
długością do streszczenia nad nim przestał być dowodem i stał się drugą kopią
źródła. Z cytowania zamiast parafrazowania wynikają dwie rzeczy: na pytanie
często da się odpowiedzieć ze strony zamiast z archiwum, a odpływ od źródła
staje się widoczny — streszczenie może po cichu oddalić się od źródła, cytat
albo wciąż się zgadza, albo nie.
Strona bez cytowalnego źródła po prostu nie ma `## Crux`. Pusty albo
sparafrazowany jest gorszy niż żaden, bo wygląda jak dowód.
#### `## Notes`
Pisane przez człowieka i **chronione**. Żaden skill nie może tej sekcji
nadpisać, przeformatować, streścić ani usunąć; regeneracja zachowuje ją co do
bajtu.
```markdown
## Notes
<!-- Twoje. Żaden skill tego nie nadpisuje. -->
```
Ma to największe znaczenie na stronach, które agent *regeneruje* — indeksy
konektorów, mapy kodu — gdzie cała reszta jest odrzucana i budowana od nowa
przy kolejnym przebiegu. To jedyne miejsce, w którym adnotacja przetrwa.
Strony decyzji celowo nie mają `## Notes`: nic ich nie regeneruje, a rekord
tylko-do-dopisywania ze swobodnie edytowalnym blokiem adnotacji zaprasza
dokładnie do tej wstecznej korekty, której zasada append-only ma zapobiegać.
### Słownik krawędzi
Relacje mieszkają w `wiki/graph/edges.json` (oraz we własnym
`graph/edges.json` każdego indeksu konektora). Słownik jest zamknięty, a każdy
czasownik zdefiniowany przez pytanie, na jakie odpowiada — jeśli proponowana
krawędź nie odpowiada na żadne z nich, jej miejsce jest w tekście strony.
| Czasownik | Pytanie, na jakie odpowiada | Od |
|---|---|---|
| `part_of` | Gdzie to mieszka? Czego jest częścią? | 1.5 |
| `uses` | Po co to sięga w czasie działania? | 1.1 |
| `depends_on` | Co się zepsuje, jeśli to zmienię? | 1.1 |
| `produces` | Skąd bierze się ten wynik? | 1.5 |
| `configures` | Co zmienia zachowanie tej rzeczy? | 1.5 |
| `validates` | Co to sprawdza, testuje albo ocenia? | 1.5 |
| `implements` | Jakiego kontraktu to musi dotrzymać? | 1.5 |
| `caused` | Dlaczego to się stało? | 1.1 |
| `contradicts` | Co jest z tym sprzeczne i nierozstrzygnięte? | 1.1 |
| `supersedes` | Co to zastąpiło i co ono zastąpiło? | 1.1 |
| `decided_by` | Kto podjął tę decyzję? | 1.4 |
| `affects` | Co ta decyzja ogranicza? | 1.4 |
| `has_expertise_in` | Kto potrafi odpowiedzieć na pytania o to? | 1.3 |
| `owns` | Kto za to odpowiada? | 1.3 |
| `mentioned_in` | Który dokument źródłowy o tym mówi? | 1.2 (tylko indeksy libs) |
Zapisuj po jednym kierunku na relację — `part_of`, `supersedes`,
`depends_on` i `uses` są kanoniczne, a odwrotność nie jest przechowywana jako
druga krawędź. Zapisuj krawędzie wyłącznie na podstawie wykazanych dowodów;
brak krawędzi jest lepszy niż krawędź zmyślona, a napompowany graf pogarsza
wyszukiwanie zamiast je poprawiać (stopień wejściowy jest sygnałem
rankingowym).
### Zastrzeżony szkielet
| Ścieżka | Od | Do czego służy |
|---|---|---|
| `wiki/index.md` | 1.1 | Tabela routingu; jedyna strona niosąca `kb_schema_version` |
| `wiki/overview.md` | 1.1 | Mapa KB z lotu ptaka |
| `wiki/log.md` | 1.1 | Dziennik zmian `wiki/` w odwrotnej chronologii |
| `wiki/error-book.md` | 1.1 | Problemy systemowe wraz z przyczyną i naprawą |
| `wiki/entities/` | 1.1 | Typowane strony encji |
| `wiki/graph/` | 1.1 | `edges.json` plus słownik w `index.md` |
| `wiki/query-gaps.md` | 1.2 | Pytania, na które wiki nie umiało odpowiedzieć, napędzające ingest sterowany popytem |
| `wiki/projects/` | 1.2 | Opcjonalne lokalne zakresy zapytań |
| `wiki/decisions/` | 1.4 | Numerowane rekordy decyzji tylko-do-dopisywania, z własnym `log.md` |
Każdy podkatalog grupujący strony niesie własny `index.md`, dzięki czemu
nawigacja pozostaje leniwa.
---
## Historia wersji schematu KB
### 1.5 — 2026-09-21 · dowody, skróty źródeł i dokończony słownik krawędzi
Zaadaptowane z analizy [trailhq/Graft](https://github.com/trailhq/Graft),
warstwy kontekstu dla agentów kodujących, która utrzymuje wyprowadzony graf
kodu w zgodzie ze źródłem przez skróty treści, a nie daty, i chroni blok
pisany przez użytkownika na każdym regenerowanym węźle. Magazyn Graftu jest
jednorazowy i odtwarzalny; ten nie jest, więc większość jego projektu się nie
przenosi — ale kilka mechanizmów tak, a dwa z nich zamknęły tu realne luki.
**Dodano:**
- **`## Crux`** — dosłowne fragmenty źródeł obok syntezy. Pozwala
`ckb-retrieve` ugruntować odpowiedź bez powrotu do archiwum (gdy skrót się
wciąż zgadza) i czyni odpływ od źródła wykrywalnym.
- **`## Notes`** — pisane przez człowieka i chronione wszędzie. To zamknęło
realną lukę: `ckb-index-external` regeneruje strony konektora w całości,
więc napisana tam adnotacja ginęła dotąd przy kolejnym odświeżeniu.
- **`## Sources`** — sformalizowane jako sekcja zastrzeżona z jednym
punktem ze skrótem na źródło. Wcześniej nieformalna konwencja, na której
`ckb-retrieve` polegało, ale której żaden skill faktycznie nie określał.
- **`source_fingerprint` / `source_checked`** we frontmatterze.
- **Czasowniki krawędzi** `part_of`, `produces`, `configures`, `validates`,
`implements`. `part_of` naprawiło żywą niespójność: `ckb-code-map`
zapisywał go od szablonu 1.7.0, a schemat nigdy go nie deklarował.
**Zmieniono:**
- `wiki/graph/index.md` przepisany jako tabela pytanie-na-czasownik wraz z
konwencjami dotyczącymi kierunku krawędzi i dowodów.
- `ckb-ingest` dostał krok promienia rażenia: przed zapisem przejdź graf
wstecz od dotkniętych encji, żeby ustalić, co nadchodzący materiał
potwierdza, rozszerza albo z czym jest sprzeczny, i wskaż właścicieli
dotkniętych stron. Ingest był dotąd przede wszystkim addytywny, a tak
właśnie wiki gromadzi dwie strony, które po cichu się ze sobą nie zgadzają.
- `ckb-retrieve` wtapia stopień wejściowy grafu jako jedną z rankowanych list,
z wagą poniżej 1.0 — centralność jest przesłanką, nie dowodem.
- Reguła E (start sesji) uruchamia teraz `lint_report.py --quick` obok
`git status`: deterministyczny jednoliniowy sygnał gnicia wiedzy, niekosztujący
żadnych tokenów modelu.
- Lint zyskał kontrole 12 (odpływ skrótu źródła), 13 (dosłowność sekcji Crux)
i 14 (zasada chronionego `## Notes`).
**Kompatybilność:** w pełni addytywna. Strona 1.4 bez żadnej z nowych sekcji
i pól jest poprawną stroną 1.5. Migracja nigdy nie wytworzy `## Crux` —
zmyślanie cytatów to dokładnie ta porażka, której ta sekcja ma zapobiegać.
### 1.4 — 2026-09-01 · rekordy decyzji
**Dodano:** strony `type: decision` w `wiki/decisions/` jako `NNNN-slug.md`,
z `status`, `decided_on`, `decided_by`, `affects`, `review_on`; czasowniki
krawędzi `decided_by` i `affects`; `wiki/decisions/index.md` wraz z własnym
`log.md`; zasadę append-only. Odpowiada na „dlaczego jest tak, jak jest",
„kto zdecydował" i „co zmieniło tę decyzję" bezpośrednim wyszukaniem zamiast
zgadywania pełnotekstowego. Właścicielem jest skill `ckb-decide`.
### 1.3 — 2026-08-06 · krawędzie osoba–temat
**Dodano:** czasowniki krawędzi `has_expertise_in` i `owns`, dzięki którym
„kto wie o X" i „kto jest właścicielem X" to wyszukanie w grafie, a nie
przeszukiwanie pełnotekstowe. Zapisywane wyłącznie na podstawie wykazanych
dowodów — obecność na spotkaniu to nie ekspertyza, a stanowisko to nie
własność.
### 1.2 — 2026-07-29 · zakresy zapytań, luki i libs oparte na konektorach
**Dodano:** `wiki/projects/` (opcjonalne lokalne zakresy zapytań grupujące
powiązane strony, źródła i obszary grafu); `wiki/query-gaps.md` (nieudane
wyszukiwania zapisane jako przyszłe cele ingestu);
`raw/archive/<YYYY-MM-DD>/` jako utrzymywane przez agenta miejsce
archiwizacji; `libs/<name>/` oparte na konektorach, z pisanym przez
użytkownika `source.yaml`, należącym do agenta generowanym indeksem oraz
czasownikiem krawędzi `mentioned_in` używanym wewnątrz tych indeksów.
### 1.1 — 2026-07-13 · pierwszy schemat
Pierwszy wersjonowany kontrakt, wydany wraz z pierwszym commitem. Ustanowił
zestaw pól frontmatteru (`type`, `resource`, `tldr`, `confidence`, `quality`,
`supersedes`/`superseded_by`, `last_updated`, `freshness_window_days`,
`retention`), podstawowe czasowniki krawędzi (`uses`, `depends_on`, `caused`,
`contradicts`, `supersedes`), szkielet `wiki/`, zasadę priorytetu kaskady i
rekurencyjną konwencję indeksu i dziennika.
Wersji 1.0 nigdy nie było: wersjonowanie zaczęło się od pierwszego
opublikowanego schematu.
---
## Historia wersji szablonu
Warstwa narzędziowa — `AGENTS.md`/`CLAUDE.md`, skille, skrypty, dokumentacja.
Niezależna od schematu treści powyżej.
| Wersja | Data | Co weszło | Schemat |
|---|---|---|---|
| **1.8.0** | 2026-09-21 | Siedem pomysłów zaadaptowanych z Graftu: crux/notes/skróty źródeł, tryb `--quick` lintu, ranking po stopniu wejściowym, promień rażenia w ingeście, dokończony słownik krawędzi | → 1.5 |
| 1.7.0 | 2026-09-20 | Opcjonalne moduły (`.agents/modules/`, `ckb-module`, `ckb.yaml`); moduł `software` z `ckb-code-map` i `ckb-spec`; `ckb-reset`; dokumentacja OpenSpec | 1.4 |
| 1.6.1 | 2026-09-01 | Naprawa fałszywie dodatnich znalezisk uszkodzonych krawędzi w kontroli grafu | 1.4 |
| 1.6.0 | 2026-09-01 | `ckb-decide`; wykrywająca połowa lintu przeniesiona do `lint_report.py`; eksport OKF przeniesiony do `export_okf.py` | → 1.4 |
| 1.3.0 | 2026-08-06 | Fuzja rankingów, deduplikacja i ponowny ranking w `ckb-retrieve`; wyszukiwanie ekspertyzy i własności | → 1.3 |
| 1.2.1 | 2026-07-29 | `AGENTS.md` skompresowany — przepływy przeniesione do skilli, zostawiając mały, zawsze ładowany zestaw reguł | 1.2 |
| 1.2.0 | 2026-07-29 | Zakresy projektów, luki zapytań, wyszukiwanie weryfikowane względem źródła | → 1.2 |
| 1.1.0 | 2026-07-20 | `libs/` oparte na konektorach z samodzielnym indeksowaniem źródeł zewnętrznych (`ckb-index-external`) | 1.1 \* |
| 1.0.0 | 2026-07-17 | Pierwszy otagowany szablon: pełny zestaw skilli, `LICENSE`, `MANUAL`, dokumentacja dwujęzyczna | 1.1 |
\* `libs/` oparte na konektorach weszły jako narzędzia w 1.1.0, ale schemat
zapisał je — kontrakt `source.yaml`, kształt generowanego indeksu, czasownik
`mentioned_in` — dopiero w 1.2, dziewięć dni później. Takie doganianie się
tych dwóch numerów jest normalne i dlatego kolumna schematu pokazuje, co
obowiązywało *po* danym wydaniu szablonu, a nie czego to wydanie dotyczyło.
Wersje 1.4.0 i 1.5.0 nigdy nie zostały opublikowane — szablon przeskoczył z
1.3.0 na 1.6.0 dnia 2026-09-01.
---
## Migracja między wersjami
Powiedz **„upgrade the wiki"** albo **„check for a newer template version"**.
Skill `ckb-upgrade` sprawdza kanoniczne repozytorium szablonu, aktualizuje
warstwę narzędziową w miejscu i — osobno, i wyłącznie po twoim wyraźnym
potwierdzeniu — migruje istniejącą treść `wiki/` do bieżącego schematu,
zachowując każdy już zebrany fakt.
Te dwie połowy są celowo rozdzielone. Wzięcie nowszych skilli nigdy nie
przepisuje twoich stron, a migracja treści nigdy nie jest cicha: zgłasza, co
zamierza zmienić, zbiera wszystko, co musiała wywnioskować (na przykład
brakujące `type`), do twojego potwierdzenia i loguje każdą dotkniętą stronę w
`wiki/log.md` z adnotacją, że to uzupełnienie migracyjne schematu, a nie nowa
wiedza.
Ponieważ każda dotychczasowa wersja schematu była addytywna, starsze wiki
działa bez migracji. Migrację warto zrobić po to, żeby nowsze kontrole miały
sens — uzupełnione skróty źródeł dają lintowi cokolwiek do weryfikacji — a
nie dlatego, że bez niej coś jest zepsute.
---
## Wersja i licencja
Aktualna wersja szablonu: [VERSION](VERSION). Aktualna wersja schematu: pole
`kb_schema_version` w `wiki/index.md`. Licencja:
[Apache License 2.0](LICENSE).

5
MANUAL.md
View file

@ -6,8 +6,9 @@ This is the human-facing manual for working with a Cascade Knowledge Base
(this repo). It's written for the *person* using the wiki, not the agent —
for the agent's own operating rules, see [AGENTS.md](AGENTS.md) /
[CLAUDE.md](CLAUDE.md). For a feature-by-feature technical overview, see
[README.md](README.md). This document is task-oriented: "I want to do X —
what do I say, and what happens?"
[README.md](README.md). For the page schema in full and the version
histories behind it, see [CHANGELOG.md](CHANGELOG.md). This document is
task-oriented: "I want to do X — what do I say, and what happens?"
Everywhere below, "say" means typing it to whatever AI coding agent you're
using against this repo (Claude Code, or another agent that reads

4
MANUAL.pl.md
View file

@ -6,7 +6,9 @@ To jest podręcznik dla *człowieka* korzystającego z Cascade Knowledge Base
(tego repozytorium) — nie dla agenta. Zasady działania samego agenta
znajdziesz w [AGENTS.md](AGENTS.md) / [CLAUDE.md](CLAUDE.md). Techniczny,
funkcja-po-funkcji przegląd znajdziesz w [README.md](README.md) (lub
[README.pl.md](README.pl.md)). Ten dokument jest zorientowany na zadania:
[README.pl.md](README.pl.md)). Pełny schemat strony wraz z historią obu
numerów wersji znajdziesz w [CHANGELOG.pl.md](CHANGELOG.pl.md). Ten dokument
jest zorientowany na zadania:
„chcę zrobić X — co mam powiedzieć i co się wtedy stanie?”
Wszędzie poniżej „powiedz” oznacza napisanie tego do dowolnego agenta AI,

3
README.md
View file

@ -18,6 +18,9 @@ If this KB documents software you're building, the optional `software` module
adds `src/` repositories and spec-driven development — see
[OPENSPEC.md](OPENSPEC.md) ([Polski](OPENSPEC.pl.md)).
For the page schema in full, and for how both version numbers got where they
are, see [CHANGELOG.md](CHANGELOG.md) ([Polski](CHANGELOG.pl.md)).
---
## Directory Structure

3
README.pl.md
View file

@ -19,6 +19,9 @@ Jeśli ta baza dokumentuje tworzone przez Ciebie oprogramowanie, opcjonalny modu
`software` dodaje repozytoria w `src/` i pracę sterowaną specyfikacją — zobacz
[OPENSPEC.pl.md](OPENSPEC.pl.md) ([English](OPENSPEC.md)).
Pełny schemat strony oraz historię obu numerów wersji znajdziesz w
[CHANGELOG.pl.md](CHANGELOG.pl.md) ([English](CHANGELOG.md)).
---
## Struktura katalogów

26
workload/2026-09-21_summary.md
View file

@ -53,3 +53,29 @@ clean; both exporters run clean.
**Not done:** ideas beyond 1-7 (Graft's token-budgeted `map` view was idea 8
and out of scope). No wiki content was fingerprinted, because this wiki is an
empty scaffold — the conventions take effect on the next ingest.
## [2026-09-21] Docs — CHANGELOG.md / CHANGELOG.pl.md
Added a bilingual changelog + schema reference at the repo root, following the
existing `.md`/`.pl.md` doc convention. Contents: the full current page schema
(frontmatter for all pages and for decisions, the three reserved body sections,
the closed edge vocabulary with a "since" column, the reserved scaffold), the
KB schema version history 1.1-1.5, the template VERSION history 1.0.0-1.8.0,
and a migration section.
History reconstructed from git, not from memory: `VERSION` and
`wiki/index.md` were read back at each commit that changed them, and each
release's diff was inspected to describe what it actually contained.
Two facts worth keeping:
- There was never a schema 1.0. Versioning began at 1.1 (c56348b, 2026-07-13).
- Template 1.4.0 and 1.5.0 were never published — VERSION jumped 1.3.0 -> 1.6.0
on 2026-09-01. Recorded as a note rather than papered over.
- Connector-backed libs shipped in template 1.1.0 but the schema only recorded
them at 1.2, nine days later; the table's schema column shows what was in
effect after each release, with a footnote explaining the lag.
Registered the new files with `ckb-init` (copied verbatim into a new KB) and
`ckb-upgrade` (taken wholesale from upstream, never merged — upstream is
authoritative about its own history). Cross-linked from README.md,
README.pl.md, MANUAL.md, MANUAL.pl.md.