ckb/docs/CHANGELOG.pl.md
Michał Kopeć db3d798e77 Template 2.4.0: merge dev — improvement memory (D-0023, schema 1.8)
Version made by merging dev into main, per D-0022. Contents: SIM features
1–6 from Google's Self-Improvement Memory paper — error book per recurring
problem with attempts (expected/observed/context) and aliases; decisions
with expected_outcome, outcome review, ## Tried; lesson context, upstream
lessons from linked/, ckb-init carry-over, merges; ckb-upgrade b5.

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

518 lines
71 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

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

# 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.
Wersja szablonu stosuje tę samą regułę do narzędzi: wersja **główna**, gdy
znika coś, na czym KB może polegać. Pierwsza taka, 2.0.0, usunęła obsługę
PowerShella. Poprzednia wersja główna dostaje poprawki na gałęzi
utrzymaniowej nazwanej od niej (`1.x`), a `ckb-upgrade` nigdy nie
przechodzi przez wersję główną bez pytania.
---
## Spis treści
1. [Aktualny schemat strony (1.8)](#aktualny-schemat-strony-kb_schema_version-18)
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.8"`)
### 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. |
| `review` | nie | *(1.6)* `draft` / `reviewed` / `needs_update`. Brak pola oznacza „nieśledzone”. `ckb-ingest` zapisuje `draft` na nowych stronach i `needs_update`, gdy zmienia to, co twierdzi strona `reviewed`; `reviewed` ustawia tylko decyzja człowieka (przez `ckb-lint`). |
| `reviewed_by` | nie | *(1.6)* Kto ostatnio przejrzał stronę. Zostaje, gdy strona przechodzi w `needs_update`, jako zapis ostatniego przeglądu. |
| `reviewed_on` | nie | *(1.6)* `YYYY-MM-DD` tego przeglądu. Lint flaguje stronę `reviewed`, której `last_updated` jest późniejsze. |
| `tags` | nie | *(1.6)* Płaska lista po przecinku, np. `tags: retries, billing`. Każdy tag musi być wierszem w `wiki/tags.md`. |
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, dopóki nie ma `outcome_checked` w tym dniu lub później. |
| `expected_outcome` | nie | *(1.8)* Jeden wiersz: co decyzja ma zmienić, zapisany przy jej zapisie. Dodany później kończy się `(added RRRR-MM-DD)`. |
| `outcome` | przy przeglądzie | *(1.8)* `met` / `partly` / `missed` / `unclear` względem `expected_outcome`. Sprawdzane przez lint. |
| `outcome_checked` | przy przeglądzie | *(1.8)* `RRRR-MM-DD` ostatniego przeglądu wyniku; sam datowany wpis trafia do sekcji `## Outcome`. |
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ć.
#### `## Rules`
*(1.6.)* Tylko na stronie zakresu w `wiki/projects/`: zasady zespołu dla tego
projektu, obowiązujące podczas pracy w tym zakresie. Pisane przez człowieka i
chronione dokładnie jak `## Notes`. Ustępują tylko `AGENTS.md`; profil osoby
ustępuje im.
#### Znacznik sprzeczności
*(1.6.)* Nie sekcja, lecz linia w treści, zapisywana tam, gdzie dwa źródła się
nie zgadzają, a nikt nie zdecydował, które ma rację:
```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
```
Zostaje, dopóki człowiek jej nie rozstrzygnie (supersesja, decyzja albo
edycja), a lint wypisuje każdą otwartą (kontrola 18).
### 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 | Powracające problemy (od 1.8: jeden wpis na przyczynę, z każdą próbą, jej oczekiwanym i zaobserwowanym wynikiem oraz kontekstem) |
| `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` |
| `wiki/tags.md` | 1.6 | Własny zamknięty słownik tagów KB (`type: vocabulary`); lint sprawdza względem niego `tags:` |
| `wiki/topics/` | 1.7 | Podsumowania tematów (`type: topic`) budowane przez `ckb-consolidate`, ze skrótami stron członkowskich jako źródłami |
| `wiki/lessons.md` | 1.6 | Lekcje dla całej KB, tworzone przy pierwszym użyciu przez `ckb-profile` (`type: lessons`) |
Każdy podkatalog grupujący strony niesie własny `index.md`, dzięki czemu
nawigacja pozostaje leniwa.
---
## Historia wersji schematu KB
### 1.8 — 2026-11-18 · pamięć ulepszeń
[D-0023](decisions/0023-improvement-memory.md), na wzór Self-Improvement
Memory Google'a (arXiv 2611.18856). Addytywnie:
- **Księga błędów według problemów**: wpisy `## E<n> — <przyczyna>` ze
statusem i tabelą prób (data, zmiana, Expected, Observed, Context);
scalone wpisy zostają jako aliasy `## E4 → E2`.
- **Decyzje**: opcjonalne `expected_outcome`, `outcome`, `outcome_checked`;
opcjonalne sekcje `## Tried` i dopisywana `## Outcome`.
- **Lekcje**: wiersz `Context:` (agent/model, wersja szablonu), opcjonalne
`Carried from:` i `Also recorded:`.
**Migracja** (`ckb-upgrade` krok 7 b5): stara tabela księgi błędów zostaje
pod `## Earlier entries`; nic nie jest uzupełniane wstecz.
### 1.7 — 2026-11-02 · podsumowania tematów
[D-0016](decisions/0016-topic-summaries-and-consolidation.md). Nowy opcjonalny
katalog `wiki/topics/` z `index.md` oraz strony `type: topic` budowane przez
`ckb-consolidate` z grupy stron członkowskich: `## Summary`, `## Members`,
`## Sources` (skróty członków, więc lint wykrywa dryf) i `## Notes`.
Addytywnie. **Migracja** (`ckb-upgrade`, krok 7 b4): dodać
`wiki/topics/index.md` i jego wiersz w indeksie, podnieść wersję; żadne strony
tematów nie są generowane.
### 1.6 — 2026-11-02 · przegląd, sprzeczności, tagi, zasady projektu
Z badania wiedzy dla agentów z 2026-10-31 (funkcje F7, F4, F21, F9, F8),
decyzja [D-0014](decisions/0014-schema-1-6-review-contradictions-tags-profiles.md).
Addytywnie: strona 1.5 jest poprawną stroną 1.6.
- **Pola przeglądu** `review`/`reviewed_by`/`reviewed_on`. Plan nazywał je
`status`, ale strony decyzji używają już `status` z innym słownikiem.
- **Znacznik sprzeczności** `> CONTRADICTION: …` zamiast cichego zwycięzcy.
Daty ważności na poziomie twierdzeń (`valid_from`/`valid_to`) odłożone.
- **`tags`** sprawdzane względem nowego pliku szkieletu `wiki/tags.md`.
- **`## Rules`**, chroniona sekcja na stronach zakresu projektu.
- **`wiki/lessons.md`**, tworzony przy pierwszym użyciu.
Poza `wiki/`, a więc poza schematem, ale w tym samym wydaniu: profile osób w
`workload/profiles/` i skill `ckb-profile`.
**Migracja** (`ckb-upgrade`, krok 7 b3): dodać `wiki/tags.md` i jego wiersz
w indeksie, podnieść wersję. `review` uzupełniane tylko na prośbę i tylko do
`draft`.
### 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 |
|---|---|---|---|
| **2.4.0** | 2026-11-18 | Pamięć ulepszeń (D-0023, schemat 1.8), na wzór Self-Improvement Memory Google'a. **Księga błędów** (sprawdzenie 9 `ckb-lint`): jeden wpis na powracający problem z każdą próbą naprawy, tym, czemu miała zapobiec (zapisane najpierw), co pokazały kolejne przebiegi (`pending` → `held`/`recurred`/`partly`) i przy jakim modelu/szablonie; lint uzupełnia oczekujące obserwacje w każdym przebiegu, ponawia nieudaną naprawę tylko z czymś nowym, scala wpisy w aliasy; nowy szkielet. **Decyzje** (`ckb-decide`): `expected_outcome` przy zapisie, nowa procedura przeglądu wyniku dopisująca do `## Outcome` i ustawiająca `outcome`/`outcome_checked`, sekcja `## Tried` i sprawdzenie, gdy nowa decyzja wybiera kierunek już wypróbowany lub odrzucony. `lint_report.py` sprawdza słownik wyników, zamyka zaległy przegląd, gdy `outcome_checked` ≥ `review_on`, i prosi o wynik, gdy jest `expected_outcome`. **Lekcje** (`ckb-profile`): wiersz `Context:` i zasady stosowania lekcji z innego kontekstu, przejmowania lekcji z baz zewnętrznych, scalania. `session_start.py` wypisuje nowe lekcje z `linked/<nazwa>/wiki/lessons.md` jako `upstream lessons:` i pomija przekreślone. **`ckb-init`** krok 8b proponuje przeniesienie lekcji i problemów z księgi błędów do nowej KB. **`ckb-upgrade`** migracja b5. ADR-y szablonu mogą mieć te same pola. Odłożone: pętla samodoskonalenia szablonu (wymaga ewaluacji). Odrzucone: ładowanie całego zapisu do kontekstu. Testy: `tests/unit/test_sim_memory.py` | 1.8 |
| 2.3.0 | 2026-11-12 | Przepływ gałęzi i wersji (D-0022): nowa gałąź integracyjna `dev`, na którą trafia cała praca; `VERSION` i changelog zmieniają się tylko przy scaleniu `dev` do `experimental`, `test` albo `main` (ścieżki `dev` → `experimental` → `test` → `main`, `dev` → `test` → `main`, `dev` → `main`), a wersja zachowuje numer przy promocji; po wydaniu `main` jest scalana z powrotem do `dev`, `test` i `experimental`; `1.x` ma własne poprawki. `experimental` staje się kanałem *podglądowym*; `dev` nie jest kanałem, a `ckb-init`/`ckb-upgrade` proponują zamiast niej `experimental`. Do tego **skille profilowe** w `user-skills/`, instalowane raz na osobę, a nie na KB: `ckb-create` buduje KB za pomocą `ckb-init` z pobranego szablonu, robi commit na `main` i push do pustego zdalnego repozytorium; `ckb-join` klonuje KB po URL i sprawdza tożsamość git, dowiązania, montowania `linked/` i Pythona, bez commitów. Żaden nie jest kopiowany do KB. Oba podręczniki mają o nich sekcję | 1.7 |
| 2.2.0 | 2026-11-11 | Nowy opcjonalny moduł `convert` (D-0021): skill `ckb-convert` i `convert.py` (biblioteka standardowa; wymaga pandoca, LibreOffice opcjonalnie). `convert` zamienia dowolny plik Markdown z bazy na `.docx`, `.odt`, PDF lub HTML w nazwanym stylu firmowym, `templates/styles/<nazwa>.docx` (dokument referencyjny pandoca; opcjonalnie `<nazwa>.odt`/`<nazwa>.css`). PDF i ODT robi LibreOffice ze sformatowanego `.docx` (osobny profil), więc wszystkie formaty wyglądają tak samo; bez niego PDF robi silnik PDF pandoca, z informacją, że styl nie został zastosowany. Kopia jest czyszczona dla czytelnika spoza bazy: frontmatter → tytuł/autor (bez e-maila)/data/język, początkowy `# H1` → tytuł, komentarze szablonu usunięte, `[[wikilinki]]` i linki do ścieżek bazy → tekst (`--keep-links`), bloki kodu bez zmian. Istniejący plik wynikowy nie jest nadpisywany bez `--force`. **Style bez ręcznego wybierania czcionek:** `new-style` kopiuje domyślny dokument referencyjny pandoca i ustawia czcionkę tekstu i nagłówków, rozmiar, kolor nagłówków, format papieru (A4/Letter) i marginesy w `styles.xml`, motywie i `sectPr` treści, w kolejności wymaganej przez schemat; `--from` przyjmuje firmowy `.docx`/`.dotx` (typ zawartości przepisany, makra odrzucane); `edit-style`, `check-style` (style używane przez pandoca, których brakuje w szablonie), `styles`, `doctor`. Szkielet `templates/styles/README.md`; ustawienia `style`, `format`, `out_dir`, `toc`, `number_sections`, `keep_links` przez `default_config`; kierowanie przez blok modułu w `AGENTS.md`, po `ckb-voice`. Testy: `tests/unit/test_convert.py`, eval `ckb-module/install-convert`. Bez zmiany schematu | 1.7 |
| 2.1.0 | 2026-11-11 | Nowy opcjonalny moduł `voice` (D-0020): skill `ckb-voice`, bez skryptu. Każdy plik prozy zapisywany pod ścieżkami `apply_to` (domyślnie `outputs/answers/`, `outputs/documents/`, `outputs/reports/`, `PROJECT-OVERVIEW*`; `outputs/okf/` i `outputs/starlight/` pominięte) jest przed zapisem przepisywany wybranym głosem, niezależnie od tego, który skill go przygotował; podpięcie to blok modułu w `AGENTS.md`, więc żaden skill bazowy się nie zmienił. **Profile to strony wiki**, `wiki/voice/<nazwa>.md` (`type: voice-profile`, `voice_of: team/person/third-party`, Tone, Formality, Sentence style, Keep, Avoid, Audience, Opinions, Sample, `## Sources`, chronione `## Notes`), tworzone i logowane przez kalibrację z przykładowych dokumentów; stałe preferencje wypowiedziane przy okazji zmieniają jedno pole. **Ustawienia** w `ckb.yaml` (`mode: auto/ask/off`, `profile`, `writer`, `apply_to`, `skip`, `chat`); kolejność profilu: nazwany w prośbie, potem `voice:` na stronie osoby w `workload/profiles/`, potem domyślny. **Zamrożone fragmenty** (frontmatter poza nowym polem `voice:`, Sources, Crux i cytaty z atrybucjami, Notes/Rules, znaczniki sprzeczności, `<private>`, kod, ścieżki, linki, liczby, nazwy, nagłówki szablonu) są porównywane przed zapisem; ogólnikowe twierdzenie jest zgłaszane, nigdy wycinane. `writer:` przekazuje przepisywanie innemu zainstalowanemu skillowi, np. osobistemu `ghost-writer`, z powrotem do `ckb-voice`, gdy go brak. Reguły zaadaptowane z tego skilla. `ckb-module` wpisuje `default_config` z manifestu do `config:` wpisu i przy reinstalacji zachowuje zmienione wartości. Nowy typ `voice-profile` i pole `voice`, addytywnie, bez zmiany schematu | 1.7 |
| 2.0.9 | 2026-11-11 | Tylko testy. Złote wyniki obu eksportów na czystym fixture: dokładna lista plików (`tests/expected/okf-files.txt`, 15 plików; `starlight-files.txt`, 17) i podsumowanie, które każdy wypisuje (`okf-report.txt`, `starlight-report.txt`, z werdyktem zgodności OKF). Treść nie jest porównywana, bo OKF wpisuje datę eksportu. To zamyka ostatni punkt przeglądu skryptów 2.0.0 | 1.7 |
| 2.0.8 | 2026-11-11 | Tylko testy. `tests/unit/test_mcp_server.py` obejmuje serwer mcp z zainstalowanym MCP SDK (2.3.0): kod potwierdzenia potwierdza dokładnie jeden zapis i jest związany z treścią i czasem ważności, zły `kb` jest odrzucany jako pierwszy, `_redact` maskuje sekrety, domyślna i nadpisana lista dozwolonych hostów, obcy nagłówek `Host` dostaje 421 przez prawdziwe HTTP, a host publiczny 200, oraz tokeny OAuth podpisane prawdziwym kluczem RSA — niezweryfikowany e-mail nie przechodzi już listy `@domena`, zweryfikowany przechodzi, `CKB_MCP_OAUTH_TRUST_EMAIL=1` to wyłącza, zła publiczność i wygasłe tokeny są odrzucane. Bez SDK testy są pomijane; `CKB_MCP_PYTHON=<venv>/bin/python bash tests/smoke.sh` je uruchamia. Potwierdzają zmiany serwera z 2.0.4, które dotąd były tylko skompilowane | 1.7 |
| 2.0.7 | 2026-11-11 | Ewaluacje skilli niszczących i zmieniających stan oraz poprawka, którą jedna z nich znalazła; bez nowych funkcji. **`ckb-reset`:** w KB bez repozytorium git krok 0 wymagał „znacznie wyraźniejszego potwierdzenia”, nie mówiąc jakiego, więc dwa przebiegi poprosiły o dwie różne frazy; fraza jest teraz nazwana, **`reset the wiki with no restore point`**, a zwykłe `reset the wiki` się tam nie liczy. **Dziewięć nowych przypadków ewaluacji**, każdy raz wykonany przez agenta 2026-11-11 i zaliczony: `ckb-reset/no-confirm` (inwentarz, nic nie usunięto), `ckb-reset/confirmed` (zwykła fraza odrzucona, ścisła przyjęta; poziom 1 usunięty, szkielet przywrócony, `kb_schema_version` zachowane, raw i szablon nietknięte), `ckb-module/install` i `ckb-module/round-trip` (`AGENTS.md`, `.gitignore`, `ckb.yaml` identyczne co do bajtu po odinstalowaniu), `ckb-upgrade/major-guard` (1.28.7 → 2.x zatrzymuje się i pyta) i `ckb-upgrade/take-major` (VERSION 2.x, `lint_quick.ps1` usunięty, wiki nietknięte), `ckb-decide/supersede` (oba odnośniki ustawione, tekst D-0001 nietknięty), `ckb-ingest/check-in-waits` i `ckb-ingest/reviewed-page` (`needs_update`, `## Notes` co do bajtu). **Runner:** `replies` na odpowiedzi operatora, gdy skill się zatrzymuje; kroki przygotowania `template` (pliki szablonu, opcjonalnie ze starszego refa gita) i `upstream` (lokalne gołe repozytorium dla `ckb-upgrade`); `record` zapisuje zaliczony przebieg jako `reference/` z listą `.deleted`, a `replay` go odtwarza i sprawdza; test dymny odtwarza każdą referencję (dziś pięć). Czytnik frontmattera w runnerze przyjmuje frontmatter zamknięty na końcu pliku | 1.7 |
| 2.0.6 | 2026-11-11 | Testy i poprawka parsera, którą znalazły; bez nowych funkcji. **Czytniki frontmattera są zgodne:** osiem skryptów czytających frontmatter stron (lint, wyszukiwanie, konsolidacja, oba eksporty, dedup, share, serwer mcp) kończy go teraz na linii będącej dokładnie `---`, także na samym końcu pliku; konsolidacja, dedup, OKF i share pomijały frontmatter zamknięty bez końcowego znaku nowej linii, a wyszukiwanie, Starlight i serwer mcp kończyły go na dowolnej linii zaczynającej się od `---`. Nowy `tests/unit/test_frontmatter_contract.py` podaje wszystkim ośmiu te same przypadki. **Każde sprawdzenie lintu działa:** `tests/unit/test_lint_dirty.py` podkłada po jednym błędzie na sprawdzenie (zgodność, świeżość, pewność, retencja, decyzje, sieroty, graf, indeks/log, odciski, crux, przegląd, sprzeczności, tagi) w kopii fixture'a i sprawdza, które dokładnie pliki zgłasza każde z nich; złoty `lint.json` dowodził tylko, że na czystej KB sprawdzenia milczą | 1.7 |
| 2.0.5 | 2026-11-11 | Pozostałe poprawki z przeglądu skryptów 2.0.0, bez nowych funkcji. **`routines.py`:** lista `routines:` zapisana od kolumny 0 (tak pisze PyYAML) jest czytana, a `--add` dopasowuje jej wcięcie; `--do` jest zapisywane jako napis z escape'ami JSON, więc ukośniki odwrotne i cudzysłowy przechodzą w obie strony (`C:\docs` dawało niepoprawny YAML); `--remove` usuwa wiersze kontynuacji wartości wielowierszowej. **`save_conversation.py`:** niezamknięte `<private>` redaguje resztę wiadomości przez wszystkie jej bloki, a nie tylko resztę jednego bloku; metadane poza tekstem są nietknięte. **OKF:** wartości z ` #`, początkowym `- `/`? `/`: ` albo tabulatorem są cytowane (`See issue #42` traciło wszystko po `#`); `# komentarz` w bloku kodu nie jest tytułem strony. **Wyszukiwanie i konsolidacja:** tokeny to słowa Unicode, więc polskie zapytania pasują (`właścicielem` było `cicielem`). **Drobne błędy:** niemożliwa data w nazwie pliku workload nie wywraca już podsumowania sesji; lint czyta frontmatter zamknięty w ostatniej linii bez znaku nowej linii oraz pusty blok; odwołania `wiki/…` bez ukośnika na początku rozwiązują się w krawędziach grafu, zastępowaniu i `affects` oraz liczą się jako jedna strona na liście najczęściej linkowanych; Starlight eksportuje stronę w katalogu głównym nazwaną jak zarezerwowana ścieżka jako `<nazwa>-page`, zamiast ją nadpisywać, rozwiązuje `[[Strona|etykieta]]`, przyjmuje napis jako `source_files` w `edges.json` i buduje przyciski i karty strony startowej z sekcji, które istnieją; oba eksporty usuwają fragmenty `<private>`. Testy dla każdej | 1.7 |
| 2.0.4 | 2026-11-11 | Poprawki bezpieczeństwa z przeglądu skryptów 2.0.0, bez nowych funkcji. **Skan sekretów (sprawdzenie 15):** skanowane są ukryte foldery, `.pem`/`.key`/`.crt`/`.asc`, `.env*` i inne pliki z kropką oraz pliki tekstowe bez rozszerzenia (pomijany jest tylko `.git`, pliki binarne są wykrywane); niecytowane wartości `password: …`, `client_secret=…` i `aws_secret_access_key = …` są wykrywane, gdy wyglądają na sekret (litera i cyfra albo 20+ znaków w mieszanej wielkości), a nie na prozę; limit rozmiaru to 50 MB zamiast 5, a plik ponad nim jest zgłaszany jako nieprzeskanowany, zamiast przechodzić po cichu. **mcp:** `search_kb` zwraca tylko ścieżki, które poda `read_page` (wymieniał trafienia w `workload/` i zapisanych rozmowach podpiętej KB), a zapytanie przekazuje po `--`; odmowa dla `.local.yaml` ignoruje wielkość liter i końcowe kropki; claim `email` z OAuth liczy się tylko z `email_verified: true` (`CKB_MCP_OAUTH_TRUST_EMAIL=1` dla dostawców, którzy go nie wysyłają); ochrona przed DNS rebinding jest domyślnie włączona dla hosta z publicznego URL i loopbacku (`CKB_MCP_ALLOWED_HOSTS` zastępuje listę, `*` ją wyłącza); kod potwierdzenia działa raz. **capture:** adresy link-local i metadanych chmury są zawsze odrzucane, a loopback i sieci prywatne wymagają `--allow-private`, sprawdzanego też przy każdym przekierowaniu; limit 90 s na całe pobieranie; nieznane kodowanie ma zapas, a `<meta charset>` jest czytane; strony z `<form>` zachowują tekst, a `<svg><title>` nie jest tytułem strony; pliki binarne dostają bezpieczne rozszerzenia, nigdy się nie nadpisują i przechodzą kontrolę duplikatów. Testy: korpus sekretów, polityka wyszukiwania i odczytu mcp, pobieranie i parsowanie w capture; zmiany uwierzytelniania i potwierdzeń w serwerze są skompilowane, ale nieuruchomione (brak MCP SDK) | 1.7 |
| 2.0.3 | 2026-11-11 | Poprawki dla Windows z przeglądu skryptów 2.0.0, bez nowych funkcji. **Kodowanie:** wyjście każdego skryptu jest w UTF-8 niezależnie od strony kodowej konsoli (polska nazwa strony albo `→` wywracały lint, start sesji, wyszukiwanie, konsolidację, dedup, eksporty, capture i share na konsoli cp1252); każde wywołanie git/rg/yt-dlp jest dekodowane jako UTF-8 (nazwisko w gicie typu `Łukasz` wywracało `session_start.py`; `Michał` wychodziło zniekształcone i dawało zły slug autora); wejście hooka na stdin jest czytane jako bajty UTF-8 (autozapis po cichu nie działał w folderze użytkownika z polskimi znakami). **BOM:** Markdown, YAML i JSON są czytane jako `utf-8-sig`, więc strona zapisana w Notatniku zachowuje frontmatter. **Końce linii:** odcisk `sha256:` pasuje do pliku w postaci zapisanej, z końcami LF albo CRLF, w `lint_report.py`, `lint_quick.sh` i `consolidate.py`, więc checkout z `core.autocrlf` nie zgłasza już każdego źródła jako zmienionego; odcisk jest porównywany jako prefiks pełnego skrótu, więc poprawny krótszy niż 8 znaków nie jest już CHANGED, a krótszy niż 6 jest zgłaszany jako zbyt krótki. **Ścieżki:** lint wypisuje ścieżki POSIX, a wyszukiwanie prosi ripgrep o separator `/`, więc sygnał dokładnego trafienia działa na Windows. **Hooki:** `start_hook.py`/`autosave_hook.py --install` domyślnie wpisują interpreter, który je uruchomił, w cudzysłowie i z ukośnikami (ścieżka `C:\Program Files\…` psuła polecenie); `--check` zgłasza hook, którego interpretera brak, a plik ustawień, który nie jest obiektem, daje błąd zamiast tracebacku. Nowy `tests/unit/test_windows.py` symuluje konsolę cp1252, pliki CRLF i z BOM, polskie nazwiska w gicie i nietypowe pliki ustawień | 1.7 |
| 2.0.2 | 2026-11-11 | Poprawki bezpieczeństwa z przeglądu skryptów 2.0.0, bez nowych funkcji. **Moduł `share`:** nazwa pliku wiadomości i skrzynki muszą być zwykłymi nazwami, a jej `from`, `share_id` i wersja muszą pasować do skrzynki, inaczej wiadomość jest pomijana z ostrzeżeniem, więc członek kanału nie może już dopisać wierszy do `ckb.yaml` odbiorcy (znak nowej linii w nazwie pliku stawał się blokiem `routines:`) ani pisać poza `raw/inbox/` (`share_id: x/../../wiki/…`); rejestr odrzuca białe znaki i znaki sterujące. Każdy commit, który dotknął wiadomości, musi pochodzić od właściciela skrzynki, nie tylko ten, który ją dodał, a skrzynka wpisana dwa razy w `members.yaml` nie ma właściciela. Tylko zweryfikowane wycofanie ukrywa niewziętą wiadomość. `branch`/`url`/nazwa kanału są sprawdzane, zanim trafią do gita, a `git clone` dostaje `--` (`branch: --upload-pack=…` uruchamiało polecenie). Odebrana kopia zawsze ma `untrusted: true`; pola `untrusted` i przeglądu nadawcy są usuwane. Fragmenty `<private>` są usuwane także z tytułu i `tldr`, a niezamknięty znacznik usuwa resztę tekstu. Bez `lint_report.py` wysyłka jest odrzucana (kod 3), zamiast iść bez skanu. README mówi, że `members.yaml` jest ufany tak, jak jest zapisany; prawdziwą ochroną jest serwer git pilnujący ścieżek. **Moduł `capture`:** wartości we frontmatterze zostają bez cudzysłowu tylko wtedy, gdy nie ma w nich składni YAML, inaczej są zapisywane jako napisy JSON, a tytuł strony to jedna linia, więc `<title>` z `---` nie zamknie już frontmattera i nie zgubi `untrusted: true`. **Lint, sprawdzenie 13:** `## Crux` cytujący rozmowę lub osobę nie wymaga już sekcji `## Sources` (`AGENTS.md` §2); cytujący lokalny plik nadal wymaga. Testy: `tests/unit/` dostaje wrogie przypadki kanału dla share (10), frontmatter capture i sprawdzenie 13 | 1.7 |
| 2.0.1 | 2026-11-11 | Poprawki z przeglądu skryptów 2.0.0, bez nowych funkcji. **Znów Python 3.8:** `removeprefix`/`removesuffix` (3.9+) zastąpione w `lint_report.py`, `retrieve_candidates.py`, `consolidate.py` i serwerze mcp; na 3.8 każda KB z `wiki/graph/edges.json` wywracała lint, kontrolę na starcie sesji, wyszukiwanie i konsolidację. **`routines.py --mark`** nie zapisuje już `last_run:2026-…` bez spacji (niepoprawny YAML dla każdego prawdziwego parsera) w świeżo dodanej rutynie i zostawia końcowy komentarz komentarzem, zamiast doklejać go do wartości. **Eksporty nie wychodzą poza swój folder:** `export_okf.py --out` musi wskazywać folder wewnątrz `outputs/` (jest usuwany i budowany od nowa; `--out .` usuwało repozytorium), a `export_starlight.py` kopiuje obraz tylko z wnętrza `wiki/assets/` do własnych zasobów, więc `../assets/../../x` w treści strony nie może już czytać ani zapisywać plików gdzie indziej. Dokumentacja: skrypt ma osiem skilli rdzenia (brakowało `ckb-consolidate`, `ckb-routine`, `ckb-add-conversation`) w `AGENTS.md`, obu README i obu podręcznikach. Nowy `tests/unit/` (`unittest` z biblioteki standardowej, uruchamiany przez `smoke.sh`): statyczna straż Pythona 3.8 nad każdym dostarczanym skryptem, przebiegi `routines.py`, ograniczenie eksportów do ich folderu i zgodność `AGENTS.md` ze skillami na dysku | 1.7 |
| 2.0.0 | 2026-11-11 | **Zmiana przełomowa: koniec obsługi PowerShella** (D-0019). Usunięte: `ckb-lint/scripts/lint_quick.ps1`, porównanie wersji w PowerShellu w kroku 2 `ckb-upgrade` i każda wzmianka „albo `.ps1`” (`AGENTS.md` reguła E i §3, `ckb-lint`, jego ręczna lista kontrolna, `ckb-sync-changes`, oba README i oba podręczniki). Bez Pythona zapasową kontrolą na starcie sesji jest `lint_quick.sh`, na Windows w Git Bash. Każdy skrypt szablonu i jego modułów jest w Pythonie (`AGENTS.md` §3); `lint_quick.sh` i kontenerowy `entrypoint.sh` modułu `mcp` to nazwane wyjątki. KB, które potrzebują PowerShella, zostają na gałęzi `1.x` (*„przełącz tę KB na gałąź 1.x”*), która dostaje tylko poprawki. `ckb-upgrade` usuwa teraz pliki, które źródło usunęło z folderu skilla lub modułu, który nadal dostarcza; krok 5 wypisuje je jako **Removed files**. Bez zmiany schematu | 1.7 |
| 1.28.1 | 2026-11-11 | Kanał wydawniczy `1.x`: gałąź utrzymaniowa linii 1.x po wydaniu 2.0, tylko poprawki, ostatnia z obsługą PowerShella (D-0019). Dopisany do tabel kanałów w `ckb-init`, `ckb-upgrade`, `AGENTS.md`, obu README i obu podręcznikach oraz do komentarza w `ckb.yaml`. `ckb-upgrade` krok 2: wyższa wersja **główna** w źródle zatrzymuje przebieg przed krokiem 4, cytuje przełomową część wiersza changeloga i proponuje nową wersję główną albo przejście na gałąź utrzymaniową; nigdy nie przechodzi przez nią z rutyny ani trybu wsadowego | 1.7 |
| 1.28.0 | 2026-11-11 | Nowy opcjonalny moduł `share` (D-0018): skill `ckb-share` i `share.py` (`join`/`send`/`unshare`/`list`/`receive`/`status`, biblioteka standardowa + git). **Kanał** to osobne repozytorium git na grupę zaufania z `CHANNEL.md`, `members.yaml` (baza → e-maile właścicieli) i jedną skrzynką tylko do dopisywania na bazę, `mail/<baza>/`, klonowane do `tmp/share/<kanał>/`. **Wysyłka** pakuje samodzielną kopię strony z `outputs/documents/`, `outputs/answers/` lub `wiki/` (`raw/archive/` tylko z `--raw-ok`): bez fragmentów `<private>` i `## Notes`, linki lokalne jako tekst, ścieżki w Sources/Crux oznaczone `<baza>:`; koperta `type: share`, `kind`, `share_id`, `version`, `from`, `to`, `sent_by`, `untrusted: true`; wzorce sekretów z lintu blokują wysyłkę (kod 3), próba pokazuje sekcję wrażliwości z `ABOUT.md`, użytkownik potwierdza. Ponowna wysyłka tworzy kolejną wersję. **Odbiór** kopiuje wiadomości do bazy do `raw/inbox/` z `share_channel`, `share_ref`, `received_on`, `submitted_by` (autor w gicie) i `supersedes_source`; wiadomość, której autor nie jest właścicielem skrzynki, jest NIEZWERYFIKOWANA i brana tylko z `--accept-unverified`; wycofanie staje się żądaniami w `raw/retractions/` dla każdej posiadanej wersji. Rejestr `received:` w należącym do skryptu bloku `share:` w `ckb.yaml` nie pozwala obsłużonym wiadomościom wrócić. `dedup_inbox.py` zgłasza `SAME SHARE`; `ckb-ingest` i `ckb-retract` znają pliki i żądania z share. Test dymny obejmuje dwie bazy i kanał na gołym repozytorium od początku do końca | 1.7 |
| 1.27.0 | 2026-11-02 | Nowy skill bazowy `ckb-feynman`, zaadaptowany ze skilla `feynman` z superhero-tech-super-brain: wyjaśnia jedną stronę prostymi słowami na konkretnym przykładzie, z linią `→ [[page]] · [Tytuł § Nagłówek](/wiki/…#kotwica)` pod każdym fragmentem, potem przypisuje każde rozrzedzone miejsce do luk Wiki, Źródła lub Moje, nie łatając żadnej wiedzą modelu, prosi o wyjaśnienie z powrotem i kończy ponumerowanymi kolejnymi krokami. Kandydaci to strony `review: draft`/`needs_update`, z jednym źródłem, nieaktualne lub ze sprzecznością; strony tematyczne prowadzą do stron członkowskich; odciski Crux sprawdzane jak w kroku 6 `ckb-retrieve`; fragmenty `<private>` nigdy nie są wyjaśniane. Sesje trafiają do `outputs/teaching/feynman/YYYY-MM-DD_<slug>.md` (`type: feynman-session`, `## Sources` z odciskami, ignorowane przez gita razem z `outputs/teaching/`, bez wpisu w `wiki/log.md`); luka w źródłach trafia do `wiki/query-gaps.md` tylko po zgodzie. `ckb-teach-me` pomija ten folder; zaktualizowane `ckb-init`, wiersz routingu w `AGENTS.md`, oba README i oba podręczniki; przypadek eval `ckb-feynman/session` z zapisanym przebiegiem wzorcowym (6/6). `outputs/teaching/` dodane do kontraktu katalogów; `run_evals.py` dopasowuje usunięte pliki semantyką glob (`**` było jednym segmentem) | 1.7 |
| 1.26.2 | 2026-11-10 | `ABOUT.pl.md`: polska para szablonu `ABOUT.md`, jak pozostałe dokumenty `.pl.md`. Gdy oba są wypełnione, agent czyta oba, a przy rozbieżności wygrywa `ABOUT.md` (`AGENTS.md`, `ckb-ingest`); `ckb-init` kopiuje oba i wpisuje odpowiedź po polsku do polskiego pliku; `ckb-upgrade` tworzy go raz w KB poniżej 1.26.2 i nigdy nie odtwarza usuniętego; `ckb-reset` go nie rusza; w module `mcp` `kb_overview` go zawiera, a opis serwera bierze jego `tldr`, pomijając oba placeholdery. `README.pl.md` i `QUICKSTART.pl.md` do niego odsyłają; oba podręczniki go wymieniają | 1.7 |
| 1.26.1 | 2026-11-02 | Dokumentacja: jednostronicowy szybki start, `docs/QUICKSTART.md` i `docs/QUICKSTART.pl.md`, od pustego folderu do pierwszego ingestu, odpowiedzi, lintu i synchronizacji; linki z obu README i obu podręczników | 1.7 |
| 1.26.0 | 2026-11-02 | Wiedza dla agentów, wydanie 3, partia 3 (D-0017). **Moduł capture (F11):** nowy opcjonalny `.agents/modules/capture/` ze skillem `ckb-capture` i `capture_url.py`: link staje się plikiem `raw/inbox/YYYY-MM-DD_<slug>.md` (`type: capture`, `source_url`, `fetched_on`, `fetched_via`, `untrusted: true`, baner) z pobrania biblioteką standardową z wydobyciem czytelnego tekstu; najbliższy zrzut Wayback Machine jest używany tylko, gdy żywa strona zawiodła lub była uboższa; `--from-file` opakowuje tekst pobrany przez samego agenta; PDF-y są zapisywane jako pliki; `--media` zapisuje transkrypcję ze znacznikami czasu przez `yt-dlp`, tylko za zgodą; jedna ponowna próba przy 429/503. `dedup_inbox.py` porównuje `source_url` zrzutu z zarchiwizowanymi zrzutami i bliźniakami w skrzynce, a capture usuwa własny duplikat. **Ewaluacje skilli (F22):** `tests/run_evals.py` (`list`/`prepare`/`check`/`validate`) i pięć strukturalnych przypadków w `tests/evals/` (ingest wsadowy, retrieve bez odpowiedzi i z zachowaniem odpowiedzi, decide, retract), z zapisanym przebiegiem wzorcowym dla `ckb-decide/record` (7/7). **Wielu agentów (F18):** sekcja podręcznika z nieprzetestowanymi konfiguracjami dla Codex CLI, Cursor, OpenCode i Gemini CLI oraz tabelą funkcji tylko dla Claude Code; `AGENTS.md` każe agentom bez wczytywania skilli czytać `SKILL.md`. Test dymny obejmuje capture z lokalnym serwerem i zastępczym Wayback oraz runner ewaluacji w obie strony | 1.7 |
| 1.25.0 | 2026-11-02 | Wiedza dla agentów, wydanie 3, partia 2: utrzymanie, **schemat 1.7** (D-0016). Nowy skill `ckb-consolidate` z `consolidate.py`: raport samych propozycji w `outputs/reports/YYYY-MM-DD_consolidation.md` z grupami tematów (członkowie zakresu, wspólne tagi, połączone grupy od trzech stron) i stanem każdej strony tematu (brak, aktualna, nieaktualna), kandydatami do scalenia (ten sam typ, podobieństwo tytułu/`tldr` ≥ 0,5), brakującymi linkami (dwa wspólne źródła albo jedno plus wspólny zakres), stronami nieaktualnymi lub z dryfem z lintu i starymi wpisami dziennika według miesięcy (dziennik nigdy nie jest przepisywany) (F13). Strony tematów (`type: topic`) w nowym `wiki/topics/`, budowane tylko po akceptacji, ze skrótami stron członkowskich w `## Sources`, więc lint wykrywa dryf; `ckb-retrieve` kieruje pytania „co KB mówi ogólnie” najpierw do `wiki/topics/index.md` (F15). `ckb-upgrade` b4, `ckb-init`, `ckb-reset` znają `wiki/topics/`; `ckb-routine` podsuwa rutynę `Consolidate --confirm` co 14 dni. Test dymny obejmuje grupowanie, stany tematów i raport | 1.7 |
| 1.24.0 | 2026-11-02 | Wiedza dla agentów, wydanie 3, partia 1: wyszukiwanie (D-0015). **Wyszukiwanie po sekcjach (F10):** `retrieve_candidates.py` dodaje listę `bm25` z indeksu SQLite FTS5 (biblioteka standardowa) po sekcjach stron, z tytułem strony, ścieżką nagłówków i `tldr` w osobnej kolumnie kontekstu (contextual retrieval); pamięć podręczna `tmp/ckb-fts.sqlite` odświeża się po mtime, potem sha256 (w pamięci bez `tmp/`, pomijana bez FTS5); kandydaci wymieniają do trzech trafionych sekcji `#kotwica (Nagłówek)`. Nowy benchmark `tests/bench_retrieval.py` na `tests/fixtures/bench-kb/` (12 stron, 20 pytań): hit@1 14/20 i hit@3 20/20 z bm25 i bez. Waga zostaje 1.0, bez strojenia pod zestaw; chybienia biorą się z sygnału `tldr`, który łapie ogólne słowa. **Koszt w tokenach (F12):** `~N tok` przy każdym kandydacie; skill czyta indeks → sekcja → strona. **Dziennik odczytów (F16):** `--opened ŚCIEŻKA…` dopisuje przeczytane strony do `tmp/access.log` (per maszyna); `lint_report.py --cold [DNI]` proponuje przeniesienie nieczytanych stron do sekcji `## Archive` indeksu i niczego nie przenosi. **Formaty odpowiedzi (F17):** `ckb-retrieve` raz proponuje tabelę, wykres, prezentację lub stronę HTML, gdy odpowiedź ma taki kształt. Test dymny obejmuje pamięć indeksu, trafienia sekcji, dziennik odczytów, propozycje `--cold` i benchmark | 1.6 |
| 1.23.0 | 2026-11-02 | Wiedza dla agentów, wydanie 2, **schemat 1.6** (D-0014). **Przegląd (F7):** opcjonalne `review: draft|reviewed|needs_update` z `reviewed_by`/`reviewed_on` (planowane `status` kolidowało ze stronami decyzji); `ckb-ingest` zapisuje `draft` na nowych stronach i `needs_update`, gdy zmienia to, co twierdzi strona przejrzana; kontrola 17 lintu flaguje tylko niespójności i wypisuje kolejkę przeglądu; `ckb-lint` oznacza przegląd na słowo człowieka. **Sprzeczności (F4):** znacznik `> CONTRADICTION:` w treści zamiast cichego zwycięzcy, wypisywany przez kontrolę 18 do rozstrzygnięcia supersesją, decyzją lub edycją; daty ważności twierdzeń odłożone. **Tagi (F21):** `tags:` sprawdzane względem nowego pliku szkieletu `wiki/tags.md` (kontrola 19); `retrieve_candidates.py --tag`; flagi wyszukiwania `DRAFT`/`NEEDS_UPDATE`. **Zakresy i profile (F9):** `AGENTS.md` > chroniona sekcja `## Rules` zakresu projektu > profil osoby w `workload/profiles/`, wypisywany przez podsumowanie startu sesji tylko dla tożsamości sesji. **Lekcje (F8):** tylko na wyraźne polecenie; osobiste w profilu, dla całej KB w `wiki/lessons.md` (przeglądane, zanim się na nich polega); podsumowanie wymienia lekcje nowe od poprzedniej notatki osoby. Nowy skill `ckb-profile`. **Pozostałości:** `.secrets-allow` przyjmuje wpisy `<glob> match:<skrót>`, które obejmują jeden ciąg w każdej linii rosnących transkryptów (także zapasowe bash/PowerShell); otwarte wątki nie drukują się już dwa razy. Starlight pokazuje przegląd i tagi oraz odznakę „Needs update”; OKF przepuszcza nowe pola. `ckb-upgrade` krok 7 b3 migruje 1.5 → 1.6; `ckb-init`/`ckb-reset` znają `tags.md`. Warstwa ładowana zawsze ~7 245 tokenów | 1.6 |
| 1.22.1 | 2026-11-02 | Hooki startują z katalogu głównego projektu. Claude Code uruchamia hook w bieżącym katalogu sesji, więc względna ścieżka `save_conversation.py` w hooku autozapisu `Stop` rozwiązywała się względem folderu, do którego przeszła powłoka: sesja pracująca w zagnieżdżonym repozytorium zapisywała tam swój transkrypt, a w folderze bez skryptu zapis cicho się nie udawał. `autosave_hook.py` i `start_hook.py` zapisują teraz `cd "${CLAUDE_PROJECT_DIR:-.}" && …`; `--check` zgłasza wpis zainstalowany przed tą poprawką jako nieaktualny (podsumowanie startu sesji pyta raz), a `--install` podmienia go, nie ruszając innych hooków. Test dymny uruchamia oba zainstalowane hooki z podfolderu | 1.5 |
| 1.22.0 | 2026-11-02 | Wiedza dla agentów, wydanie 1: siedem funkcji z badania z 2026-10-31, bez zmiany schematu. **Hook startu sesji (F1):** `session_start.py --hook` wypisuje podsumowanie z reguły E jako `additionalContext` hooka `SessionStart` przy starcie, wznowieniu, `/clear` i po każdym kompaktowaniu; `start_hook.py --check/--install/--remove` zarządza nim w ignorowanym przez gita `.claude/settings.local.json`; włączany przez `session: start_hook:` w `ckb.yaml`, z linią `start hook:` w podsumowaniu, gdy oba się nie zgadzają; reguła E zostaje jako zapas (D-0011). **Zachowane odpowiedzi (F2):** krok 8 `ckb-retrieve` proponuje zachowanie istotnej odpowiedzi w `outputs/answers/` (`type: answer`) ze skrótami w `## Sources` i sekcją `## Gaps`, aktualizuje zamiast dublować i wprowadza do wiki tylko przez ingest; kontrola 16 lintu zgłasza zachowane odpowiedzi, których źródła się zmieniły (D-0013). **Meldunek przed ingestem (F3):** zanim cokolwiek zapisze, `ckb-ingest` pokazuje, jak rozumie każde źródło, które strony zmieni i z czym jest sprzeczne, po czym czeka; tryb wsadowy („ingest in batch” albo rutyna z `confirm: false`) to pomija; raport ingestu dostaje sekcję `## Check-in`. **Otwarte wątki (F5):** pola `### Open threads` w notatkach workload (reguła D), zbierane przez `session_start.py` w linię `threads:` z pięcioma najstarszymi i znacznikiem po 30 dniach; bez wspólnego pliku statusu (D-0012). **Deduplikacja przy wejściu (F6):** nowy `ckb-ingest/scripts/dedup_inbox.py` zgłasza `DUPLICATE`, `SAME TEXT`, `CITED`, `SAME URL` i `INBOX TWIN` względem `raw/archive/` oraz cytowanych skrótów i adresów URL przed ingestem. **Ochrona sekretów i prywatności (F19):** kontrola 15 lintu szuka postaci danych uwierzytelniających w commitowanym tekście i fragmentów `<private>` w `wiki/`, maskuje dopasowania, honoruje `.secrets-allow` oparte na skrócie linii; `--quick` ją liczy, `--secrets` uruchamia ją osobno, a `ckb-sync-changes` przed stagingiem; ingest odrzuca, a retrieval nigdy nie cytuje fragmentów `<private>`; `save_conversation.py` je redaguje (D-0013). **Budżet kontekstu (F20):** `lint_report.py --budget` szacuje `AGENTS.md` plus opisy skilli jako znaki ÷ 4; `--quick` flaguje przekroczenie `budget: always_loaded_tokens` (domyślnie 9000). Punkt odniesienia: ~6 620 tokenów w 1.21.0, ~6 810 w 1.22.0. Zapasowe kontrole bash/PowerShell dostają okrojoną kontrolę sekretów; test dymny obejmuje każdy nowy skrypt | 1.5 |
| 1.21.0 | 2026-10-31 | `ABOUT.md`. Nowy plik w katalogu głównym, pisany przez właściciela KB, mówiący, co ta KB zawiera: cel, odbiorcy, zakres (co wchodzi, a co nie), właściciele i kontakty, oczekiwane źródła, poufność, język i terminy; każda sekcja ma komentarz, co w niej napisać; `type: about` z `tldr`. `README.md`/`README.pl.md` linkują do niego pod wskazaniem repozytorium źródłowego, bo samo README należy do szablonu i jest nadpisywane przy aktualizacji. Agenci go czytają i nie edytują bez prośby; pytania o samą KB dostają odpowiedź najpierw z niego, potem z `wiki/overview.md`, które pozostaje podsumowaniem agenta tego, co przetworzono, i teraz do niego linkuje. `ckb-ingest` w Kroku 1 wskazuje materiał spoza zakresu lub wykluczony przez sekcję poufności i przetwarza go tylko na wyraźną prośbę. `ckb-init` kopiuje szkielet i zadaje jedno opcjonalne pytanie o cel i `tldr`; `ckb-upgrade` tworzy go tylko, gdy go brak, i nigdy go nie porównuje; `ckb-reset` nigdy go nie rusza. Moduł `mcp`: `kb_overview` zaczyna się od niego, a opis KB serwera pochodzi z jego `tldr` (zastępczy tekst szkieletu jest pomijany). Zaktualizowano kontrakt katalogów i podręcznik. D-0010 | 1.5 |
| 1.20.0 | 2026-10-30 | Raporty z ingestu. `ckb-ingest` dostaje Krok 8: każde uruchomienie, które coś przetworzyło, zapisuje jeden plik `workload/ingest-reports/YYYY-MM-DD_HHMM_<autor>_ingest.md` (`type: ingest-report`) z listą przyjętych plików z `raw/` wraz ze ścieżką archiwum i odciskiem, zapisanych decyzji, utworzonych/zaktualizowanych encji, innych stron, krawędzi grafu, zasięgu zmian (potwierdzone/rozszerzone/sprzeczne z właścicielami, zamknięte luki w zapytaniach) oraz plików ze skrzynki, których nie przetworzono; każda sekcja zostaje, z `- none`, gdy jest pusta. Zapisywany raz, poza wyszukiwaniem, bez wpisu w `wiki/log.md`, nieruszany przez `ckb-retract`; podfolder, aby `session_start.py` nadal czytał tylko notatki sesji. Dotychczasowy Krok 8 (podsumowanie i przypomnienie o synchronizacji) staje się Krokiem 9 i wskazuje raport. Zaktualizowane: struktura katalogów, podręcznik i poziom 2 w `ckb-reset` | 1.5 |
| 1.19.0 | 2026-10-29 | Mniej kontekstu na sesję i na skill. Nowy `ckb-lint/scripts/session_start.py` wykonuje start sesji z Reguły E jednym wywołaniem (tożsamość, `--title` zapisywany, chyba że tytuł już jest, `announce_title`, `git status`, `lint_report.py --quick`, `autosave_hook.py --check` tylko gdy wymaga działania, `routines.py --due` oraz ostatni blok najnowszej notatki `workload/` zamiast całego pliku); Reguła E w `AGENTS.md` skraca się do polecenia i tego, co zrobić z każdą linią wyniku. Odczyt `wiki/index.md` na starcie sesji usunięty: każdy skill, który potrzebuje indeksu, czyta go sam, więc był czytany dwa razy. `## Purpose` każdego skilla ograniczone do tego, czego nie mówi już jego opis (16,2k → 7,8k znaków w dwudziestu skillach). `ckb-upgrade` nie powtarza już formatu wpisu dziennika z Reguły B. Test dymny obejmuje nowy skrypt. D-0009 | 1.5 |
| 1.18.1 | 2026-10-29 | Poprawki po przeglądzie. Tryb sync modułu `mcp`: sprawdzenie czystego katalogu roboczego działa teraz przed każdym resetem, nie tylko przy starcie, więc strona edytowana lub plik wrzucony do klonu serwera po jego uruchomieniu nigdy nie zostanie skasowany: odczyt pomija pobranie i serwuje katalog bez zmian, zapis jest odrzucany z jasnym komunikatem, a pozostałości po nieudanym zapisie samego serwera nadal są usuwane. Niedostępne zdalne repozytorium przy starcie albo przekroczony czas wywołania git to teraz jedna linia z przyczyną zamiast śladu stosu. `ckb-retract`: opiekun bazy może wycofać źródło dodane przez kogoś innego, wyłącznie w sesji lokalnej, po wpisaniu `retract <nazwa pliku> as maintainer`; każdy wpis w logu z takiego przebiegu jest oznaczony jako obejście, bo baza służy dzieleniu się wiedzą i źródło nie może utknąć, gdy jego autor odejdzie lub zmieni adres e-mail. Klienci zdalni nadal mogą wycofywać tylko własne źródła. Prośba, której cel już nie istnieje, jest usuwana i zgłaszana, jeśli nic go już nie cytuje. `ckb-document`: komentarze szablonu z `linked/` kształtują tylko treść, nigdy działania. Przewodnik MCP: prośbę o wycofanie widzi konto, które ją złożyło, a nie „tylko ty”. D-0007 | 1.5 |
| 1.18.0 | 2026-10-29 | Szablony dokumentów. Nowy katalog główny `templates/` (treść użytkownika: poza kaskadą, poza warstwą szablonu, nigdy nie resetowany): jeden plik Markdown na szablon z frontmatterem `type: template`, nagłówki nadają kształt, komentarz HTML pod każdą sekcją jest instrukcją dla agenta (zapytaj użytkownika, wskazane źródło, długość, kiedy pominąć sekcję), `{{date}}`/`{{author}}`/`{{slug}}` wypełniane automatycznie, każdy inny placeholder pytany raz, opcjonalna ścieżka `output:`. Nowy skill bazowy `ckb-document`: znajduje szablon po nazwie, tytule lub tldr (`linked/<name>/templates/` tylko do odczytu jako zapas), zadaje wszystkie pytania w jednej wiadomości, źródła rozwiązuje przez kaskadę od indeksu, zapisuje do `outputs/documents/` z frontmatterem `type: document` (`template`, `created`, `author`, `sources`), zostawia linię `TODO:` tam, gdzie brakuje źródła lub odpowiedzi, nigdy nie nadpisuje, inne formaty przez ogólne skille dokumentowe z Markdowna; na prośbę wypisuje szablony i przygotowuje szkic nowego. Przykład `templates/status-report.md` i `templates/README.md`; kopiowane przez `ckb-init`, tworzone przez `ckb-upgrade` tylko gdy katalogu brak, pomijane przez `ckb-reset`. D-0008 | 1.5 |
| 1.17.0 | 2026-10-29 | Nowy opcjonalny moduł `mcp`: serwer MCP (`.agents/modules/mcp/server/`) udostępniający bazę aplikacjom Claude (web/desktop) jako własny konektor, Claude Code lub dowolnemu klientowi MCP. **Odczyt:** `kb_overview`, `search_kb` (uruchamia `retrieve_candidates.py`), `read_page`, `list_pages` na `wiki/`, `linked/`, `libs/`, `raw/inbox/`, `raw/archive/`, `outputs/` (te same obszary w każdej bazie podlinkowanej; poza `linked/<name>` żaden symlink nie jest śledzony) oraz własne prośby w `raw/retractions/`. **Zapisy nigdy nie dotykają `wiki/`:** `add_to_inbox` (nowy plik w `raw/inbox/` z `submitted_by`/`submitted_at`/`via: mcp`/`source`, autor w git to zgłaszający), `withdraw_submission` i `request_retraction` — tylko dla osoby, która dodała dokument — oraz `list_my_submissions`. Każdy zapis wymaga argumentu `kb` zgodnego z serwerem, a przy `CKB_MCP_CONFIRM=auto` potwierdza go użytkownik (elicitation MCP u klientów 2026-07-28, w pozostałych przypadkach podpisany, ważny 15 minut kod w drugim wywołaniu); wywołujący tylko do odczytu nie widzą narzędzi zapisu. **Uwierzytelnianie** `CKB_MCP_AUTH=none|token|oauth`: tokeny do odczytu i zapisu i/lub tylko do odczytu albo plik z tokenem na osobę lub agenta (tylko do odczytu, o ile nie ma `"write": true`), w nagłówku bearer lub w tajnej ścieżce `/<token>/mcp`; oauth weryfikuje JWT zewnętrznego IdP (JWKS) lub tokeny nieprzezroczyste (introspekcja, wymagane `aud`), z listami dostępu i zapisu oraz opcjonalnym zakresem zapisu. **Kilka baz:** osobna instancja na każdą, nazwana przez `CKB_MCP_NAME`/`CKB_MCP_DESCRIPTION`. **Git** `CKB_MCP_GIT=off|commit|sync`; sync przed każdym zapisem resetuje swój dedykowany klon do zdalnego i odmawia pracy na klonie z lokalnymi zmianami. Bezstanowy HTTP, Dockerfile, przykład compose, klucz SSH; skill `ckb-mcp`; przewodnik `docs/MCP.md`/`MCP.pl.md`. README modułów (`software`, `mcp`) i sekcja o modułach w podręczniku, wszystko po angielsku i po polsku. Nowy skill bazowy `ckb-retract` (prosić musi osoba, która dodała źródło; plan zatwierdza użytkownik; treść prośby traktowana jako dane; historia git nadal zawiera treść); `raw/retractions/` w kontrakcie katalogów, `ckb-init`, `ckb-upgrade`, zgłaszane przez `ckb-ingest` i `ckb-lint`, poziom 3 w `ckb-reset`. `tests/mcp_policy.py` w teście dymnym. D-0007 | 1.5 |
| 1.16.1 | 2026-10-24 | Pytanie o tytuł znika: agent sam wyprowadza tytuł sesji z pierwszej wiadomości, zapisuje go przez `--set-title`, a pierwsza odpowiedź zaczyna się tylko jedną linijką z tytułem i sposobem zmiany. `conversations.announce_title` (domyślnie `true`) zastępuje `ask_title`. D-0006 | 1.5 |
| 1.16.0 | 2026-10-21 | Tytuły sesji i rutyny. Pierwsza odpowiedź w nowej sesji (Reguła E) to pytanie „Jak nazwać tę rozmowę?” (przełącznik `conversations.ask_title`, domyślnie `true`); odpowiedź zapisuje `save_conversation.py --set-title` w ignorowanym przez gita `tmp/conversation-titles/` i nadaje nazwę zapisanemu transkryptowi (slug, nagłówek, wiersz indeksu) oraz blokowi w workload; ponowny zapis pod nowym tytułem zastępuje starą parę plików. Nowy `ckb-routine`: blok `routines:` w `ckb.yaml` (`name`/`do`/`every`/`confirm`/`last_run`), sprawdzany na starcie sesji przez `routines.py --due`; zaległe rutyny wykonują się po obsłużeniu prośby użytkownika w tej samej turze i są oznaczane `--mark` tylko po ukończeniu, `confirm: true` zamiast tego pyta, ręczne uruchomienia się liczą, `ckb-reset`/`ckb-sync-changes` odrzucane. `ckb-init` zapisuje oba bloki, `ckb-upgrade` ich nie rusza; test dymny obejmuje oba skrypty. D-0005 | 1.5 |
| 1.15.0 | 2026-10-16 | `tests/` tylko w repo szablonu: `ckb-init` już go nie kopiuje, `ckb-upgrade` go nie dostarcza (i raz proponuje usunięcie pozostałej kopii), kontrakt katalogów i dokumentacja o tym mówią. Sam test dymny bez zmian | 1.5 |
| 1.14.0 | 2026-10-16 | Autorstwo we współdzielonych repozytoriach: tożsamość sesji (`git config user.name`/`user.email`, ustalana raz na starcie) opisuje każdą notatkę workload, każdy wpis `wiki/log.md` (nowa linia `**Author:**`, opcjonalna, neutralna dla lintu) i każdą zapisaną rozmowę (`save_conversation.py --author`). Pliki workload stają się jednym na osobę na dzień, `YYYY-MM-DD_<autor>_summary.md` z frontmatterem `type: session`, więc dwie osoby nigdy nie konfliktują w `workload/`; starsze pliki czytane jak dotąd. D-0004 | 1.5 |
| 1.13.0 | 2026-10-16 | Przełącznik autozapisu rozmów: `conversations.autosave` w `ckb.yaml` (domyślnie `false`). Po włączeniu Reguła E zapisuje każdą sesję na jej końcu bez pytania; `ckb-add-conversation` przełącza go na żądanie („save conversations automatically”). Połowa per maszyna: `autosave_hook.py --check/--install/--remove` zarządza hookiem `Stop` Claude Code w ignorowanym przez gita `.claude/settings.local.json`; Reguła E uruchamia kontrolę na starcie sesji przy włączonym autozapisie i pyta przed zmianą konfiguracji maszyny; `save_conversation.py --from-hook` bierze ścieżkę transkryptu ze stdin hooka. `ckb-init` zapisuje blok, `ckb-upgrade` go nie rusza | 1.5 |
| 1.12.0 | 2026-10-16 | `ckb-add-conversation`: na żądanie kopiuje transkrypt sesji Claude Code (JSONL, bajt w bajt) do `raw/saved-conversations/<data>/` wraz z czytelną wersją `.md` i `index.md`; odpowiada na „did we discuss X” / „what did I tell you about Y” z tych plików. Zapisane rozmowy są poza wyszukiwaniem i poza ingestem, dopóki użytkownik nie skopiuje jednej do `raw/inbox/`. Reguła E pyta raz na końcu sesji, czy zapisać; `ckb-retrieve`, `ckb-ingest`, `ckb-reset` (poziom 3) i `ckb-init` znają ten folder; test smoke renderuje transkrypt z fixture | 1.5 |
| 1.11.1 | 2026-10-09 | Pięć usterek naprawionych, wszystkie zgłoszone przez KB pochodną. `retrieve_candidates.py`: `load_pages` przechodzi katalogi w kolejności posortowanej, więc oczekiwany wynik testu nie koduje już kolejności katalogów jednej maszyny (test smoke nie przechodził na czystym klonie); źródło cytowane przez N stron potwierdza teraz wszystkie N, a nie tylko pierwszą napotkaną. `lint_report.py` kontrola 12: cytowany katalog jest legalny i bez skrótu, nie jest już zgłaszany jako brakujący (ta sama poprawka w `lint_quick.sh`/`.ps1`). Kontrola 8: `POINTER` w dzienniku głównym nie jest już czytany jako duplikat wpisu dziennika decyzji, na który wskazuje. Kontrola 13: cytat przypisany do rozmowy lub osoby liczy się jako przypisany, nie jako nieprzypisany. `AGENTS.md` §2 dokumentuje cytowanie katalogów i dwie formy atrybucji; KB testowy pokrywa wszystkie trzy regresje lintu | 1.5 |
| 1.11.0 | 2026-09-29 | Python opcjonalny tam, gdzie to możliwe: wybór interpretera `<python>` (`python3`/`python`/`py -3`) w `AGENTS.md`; instrukcja instalacji per system w podręczniku; zapasowe `lint_quick.sh`/`.ps1` dla kontroli na starcie sesji (testowane smoke wobec `--quick`); ręczna lista kontrolna lintu i ścieżka wyszukiwania bez skryptu; eksporty deklarują Pythona jako wymóg twardy; usunięte wbudowane `python3 -c` z `ckb-upgrade`/`ckb-reset`; D-0003. Kontrola lintu 13 porównuje każdy blok Crux tylko ze źródłem przypisanym pod nim (Crux z wielu źródeł już nie daje fałszywych wyników; cytaty łamane na kilka linii sprawdzane jako jeden blok); KB testowy zyskuje drugie źródło | 1.5 |
| 1.10.0 | 2026-09-24 | Odchudzone opisy i treści skilli (przypadki brzegowe → `references/`); `retrieve_candidates.py` przejmuje fuzję rankingów; dokumentacja przeniesiona do `docs/`, ADR-y szablonu przywrócone w `docs/decisions/`; fixture `tests/` + `smoke.sh`; dołączony `ckb.yaml`; Reguła B nazywa wyjątek dziennika decyzji; szkieletowy `overview.md` opisuje treść, nie schemat; usunięty wyzwalacz „Sync the wiki” | 1.5 |
| 1.9.0 | 2026-09-22 | Kanały wydawnicze: gałęzie `main`/`test`/`experimental`, świadome gałęzi `ckb-init` i `ckb-upgrade`, blok `template:` w `ckb.yaml` | 1.5 |
| 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.
---
## Kanały wydawnicze
Repozytorium szablonu utrzymuje cztery gałęzie wydań i jedną integracyjną:
| Gałąź | Czym jest | Kto powinien ją śledzić |
|---|---|---|
| `main` | **Stabilna** — wydany szablon | Wszyscy, domyślnie |
| `test` | **Kandydat do wydania** — walidowany przed scaleniem do `main` | Każdy, kto pomaga walidować wydanie |
| `experimental` | **Podglądowa** — zmiany scalone z `dev` wcześnie, mogą być zepsute albo wycofane | Osoby rozwijające sam szablon |
| `1.x` | **Utrzymaniowa** — poprawki linii 1.x, ostatniej z PowerShellem | KB, które potrzebują PowerShella |
| `dev` | **Integracyjna** — tu najpierw trafia każda zmiana | Nikt: to nie jest kanał |
**Jak powstaje wersja (D-0022).** `VERSION` i historia w tym pliku zmieniają
się tylko przy scaleniu `dev` do innej gałęzi, nigdy przez commit na `dev`.
Scalenie dostaje kolejny numer według zwykłej zasady (główna dla zmian
łamiących, poboczna dla funkcji, poprawkowa dla poprawek; wygrywa najwyższy
rodzaj w scaleniu) i dopisuje tu swój wiersz. Wersja zachowuje numer przy
promocji: `dev` → `experimental` → `test` → `main`, `dev` → `test` → `main`
albo `dev` → `main`. Scalenie `dev` zabiera wszystko, co na niej jest, więc
wprost do `main` scalaj tylko wtedy, gdy cała `dev` jest gotowa do wydania.
Gdy wersja trafi do `main`, `main` jest scalana z powrotem do `dev`, `test` i
`experimental`, żeby `dev` zaczynała od wydanej wersji, a żaden kanał nie
został w tyle za stabilnym. `1.x` jest
poza tym przepływem: jej poprawki są commitowane i numerowane bezpośrednio na
niej.
Śledzona przez KB gałąź mieszka w `ckb.yaml`:
```yaml
template:
repo: https://git.wierzbowa.cloud/michal/ckb.git
branch: main
```
`ckb-init` ją zapisuje, `ckb-upgrade` czyta ją jako domyślną i aktualizuje przy
przełączeniu. Brak `ckb.yaml` i brak bloku `template:` oznaczają `main`.
Jedna konsekwencja warta poznania: KB, która wzięła narzędzia z `test` albo
`experimental`, może mieć `VERSION` wyższą niż to, co `main` w ogóle wydało.
Porównanie z `main` nie znajdzie wtedy nic nowszego — co jest prawdą, ale
**nie** znaczy „aktualne", i `ckb-upgrade` raportuje to jako „wyprzedza", a nie
jako bieżące. Cofnięcie takiej KB na `main` to *downgrade*: może usunąć skille
i obniżyć `kb_schema_version` poniżej tego, pod co napisano lokalne strony.
Wymaga wyraźnego potwierdzenia, a gdy schemat spadłby poniżej kontraktu
zadeklarowanego przez treść — jest blokowane.
---
## Migracja między wersjami
Powiedz **„upgrade the wiki"** albo **„check for a newer template version"**.
Aby użyć innego kanału, nazwij go: *„upgrade from the test branch"*, *„check
experimental"*, *„switch back to stable"*.
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.
Szablon 1.10 przeniósł `MANUAL*`, `CHANGELOG*` i `OPENSPEC*` z katalogu
głównego do `docs/`. KB aktualizowana z 1.9 lub starszej ma je w katalogu
głównym; `ckb-upgrade` przenosi je i poprawia linki w `README*`. Nic pod
`wiki/` nie jest dotknięte.
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).