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>
518 lines
71 KiB
Markdown
518 lines
71 KiB
Markdown
# 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).
|