ckb/CHANGELOG.pl.md

Historia zmian i referencja schematu

Przeczytaj to w: English | 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	warstwa narzędziowa — AGENTS.md, skille, skrypty, dokumentacja	ckb-upgrade, gdy pobiera nowszy szablon

Poruszają się niezależnie i jest to celowe. Możesz wziąć nowszy zestaw skilli bez dotykania choćby jednej strony wiki, a wiki napisane pod starszy schemat nadal działa — po to właśnie jest wersja schematu.

Polityka wersjonowania. Podnoś wersję pomniejszą przy zmianie addytywnej: nowe pole opcjonalne, nowa opcjonalna sekcja treści, nowy opcjonalny plik szkieletu. Podnoś wersję główną przy zmianie łamiącej kompatybilność: zmiana lub usunięcie pola wymaganego albo zmiana istniejącej zastrzeżonej konwencji nazw plików. Nigdy nie było podniesienia wersji głównej — każda dotychczasowa wersja schematu była addytywna, więc dowolna strona napisana od 2026-07-13 jest dziś nadal poprawna.

---

Spis treści

1. Aktualny schemat strony (1.5)
2. Historia wersji schematu KB
3. Historia wersji szablonu
4. Migracja między wersjami

---

Aktualny schemat strony (kb_schema_version: "1.5")

Frontmatter — każda strona niezastrzeżona

Każdy plik .md w wiki/ poza zastrzeżonymi (index.md, log.md) niesie frontmatter YAML. Wymagane jest wyłącznie type; reszta jest opcjonalna i preferowana tam, gdzie ma sens. Parser jest celowo prosty — wyłącznie płaskie pary klucz: wartość, bez zagnieżdżeń.

Pole	Wymagane	Znaczenie
type	tak	Otwarty ciąg: person, project, concept, library, decision, playbook, repository, component, … Nowe wartości są zawsze poprawne; czytelnicy tolerują nierozpoznane.
resource	nie	Kanoniczny URI autorytatywnego źródła zewnętrznego, które opisuje ta strona, trzymany oddzielnie od własnego komentarza wiki.
tldr	nie	Jednozdaniowe streszczenie zoptymalizowane pod odczyt przez LLM. To ono trafia do indeksu i decyduje, czy strona w ogóle zostanie otwarta.
confidence	nie	0.0–1.0. Potwierdzenie przez źródła. Ustawiane przy zapisie, zanika, jeśli nic go nie wzmacnia, rośnie przy nowym zgodnym źródle.
quality	nie	0.0–1.0. Samoocena struktury i cytowań samej strony. Poniżej 0.7 oflagowane do przeglądu.
supersedes	nie	Ścieżka do starszej strony, którą ta zastępuje.
superseded_by	nie	Ścieżka do nowszej strony, która zastąpiła tę. Zawsze ustawiaj obie strony.
last_updated	nie	YYYY-MM-DD. Kiedy zmieniła się strona.
freshness_window_days	nie	Liczba dni, po której lint oznacza stronę jako nieaktualną. Typowo: 90 dla strony wiki, 365 dla decyzji, 30 dla dokumentu z indeksu konektora.
retention	nie	high / medium / low. Strona low jest archiwizowana (nigdy usuwana) po 2× swoim oknie świeżości.
source_fingerprint	nie	(1.5) Skrót źródła, z którego zbudowano stronę — sha256:<8 hex> dla pliku lokalnego albo etag:<wartość> / mtime:<iso8601> dla elementu z konektora.
source_checked	nie	(1.5) YYYY-MM-DD — kiedy ten skrót był ostatnio zweryfikowany. To co innego niż last_updated: ponowne sprawdzenie, które nie wykryło zmiany, przesuwa to pole i zostawia last_updated w spokoju.

Wyłącznie wiki/index.md niesie kb_schema_version. To deklaracja na poziomie całego zbioru, nie pojedynczej strony — same strony nigdy jej nie niosą.

Frontmatter — strony decyzji

Strony z type: decision mieszkają w wiki/decisions/ jako NNNN-slug.md i dodają:

Pole	Wymagane	Znaczenie
status	tak	proposed / accepted / rejected / superseded / reversed. Słownik zdefiniowany w wiki/decisions/index.md i walidowany przez lint.
decided_on	dla accepted/rejected/reversed	YYYY-MM-DD, data podjęcia decyzji.
decided_by	gdy wiadomo	Nazwiska po przecinku. Gdy naprawdę nie wiadomo, wpisz unknown zamiast pomijać pole — „nie wiemy, kto to zdecydował" samo w sobie warto zapisać.
affects	nie	Ścieżki wiki po przecinku, które ta decyzja ogranicza.
review_on	nie	YYYY-MM-DD do ponownego rozważenia. Lint zgłasza je po przekroczeniu daty.

Rekordy decyzji są tylko do dopisywania. Decyzji nigdy nie przepisuje się pod późniejszą zmianę zdania: zapisz nową, która ją zastępuje, a obie zostają na wokandzie.

Zastrzeżone sekcje treści

(Nowość w 1.5.) Cztery nagłówki ## znaczą to samo na każdej stronie w każdej warstwie kaskady. Wszystkie są opcjonalne; tam, gdzie występują, znaczą dokładnie to i nic innego.

## Sources

Skąd wzięła się strona. Po jednym punkcie na źródło, każdy ze skrótem:

## 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ą:

## 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.

## Notes

<!-- Twoje. Żaden skill tego nie nadpisuje. -->

Ma to największe znaczenie na stronach, które agent regeneruje — indeksy konektorów, mapy kodu — gdzie cała reszta jest odrzucana i budowana od nowa przy kolejnym przebiegu. To jedyne miejsce, w którym adnotacja przetrwa. Strony decyzji celowo nie mają ## Notes: nic ich nie regeneruje, a rekord tylko-do-dopisywania ze swobodnie edytowalnym blokiem adnotacji zaprasza dokładnie do tej wstecznej korekty, której zasada append-only ma zapobiegać.

Słownik krawędzi

Relacje mieszkają w wiki/graph/edges.json (oraz we własnym graph/edges.json każdego indeksu konektora). Słownik jest zamknięty, a każdy czasownik zdefiniowany przez pytanie, na jakie odpowiada — jeśli proponowana krawędź nie odpowiada na żadne z nich, jej miejsce jest w tekście strony.

Czasownik	Pytanie, na jakie odpowiada	Od
part_of	Gdzie to mieszka? Czego jest częścią?	1.5
uses	Po co to sięga w czasie działania?	1.1
depends_on	Co się zepsuje, jeśli to zmienię?	1.1
produces	Skąd bierze się ten wynik?	1.5
configures	Co zmienia zachowanie tej rzeczy?	1.5
validates	Co to sprawdza, testuje albo ocenia?	1.5
implements	Jakiego kontraktu to musi dotrzymać?	1.5
caused	Dlaczego to się stało?	1.1
contradicts	Co jest z tym sprzeczne i nierozstrzygnięte?	1.1
supersedes	Co to zastąpiło i co ono zastąpiło?	1.1
decided_by	Kto podjął tę decyzję?	1.4
affects	Co ta decyzja ogranicza?	1.4
has_expertise_in	Kto potrafi odpowiedzieć na pytania o to?	1.3
owns	Kto za to odpowiada?	1.3
mentioned_in	Który dokument źródłowy o tym mówi?	1.2 (tylko indeksy libs)

Zapisuj po jednym kierunku na relację — part_of, supersedes, depends_on i uses są kanoniczne, a odwrotność nie jest przechowywana jako druga krawędź. Zapisuj krawędzie wyłącznie na podstawie wykazanych dowodów; brak krawędzi jest lepszy niż krawędź zmyślona, a napompowany graf pogarsza wyszukiwanie zamiast je poprawiać (stopień wejściowy jest sygnałem rankingowym).

Zastrzeżony szkielet

Ścieżka	Od	Do czego służy
wiki/index.md	1.1	Tabela routingu; jedyna strona niosąca kb_schema_version
wiki/overview.md	1.1	Mapa KB z lotu ptaka
wiki/log.md	1.1	Dziennik zmian wiki/ w odwrotnej chronologii
wiki/error-book.md	1.1	Problemy systemowe wraz z przyczyną i naprawą
wiki/entities/	1.1	Typowane strony encji
wiki/graph/	1.1	edges.json plus słownik w index.md
wiki/query-gaps.md	1.2	Pytania, na które wiki nie umiało odpowiedzieć, napędzające ingest sterowany popytem
wiki/projects/	1.2	Opcjonalne lokalne zakresy zapytań
wiki/decisions/	1.4	Numerowane rekordy decyzji tylko-do-dopisywania, z własnym log.md

Każdy podkatalog grupujący strony niesie własny index.md, dzięki czemu nawigacja pozostaje leniwa.

---

Historia wersji schematu KB

1.5 — 2026-09-21 · dowody, skróty źródeł i dokończony słownik krawędzi

Zaadaptowane z analizy trailhq/Graft, warstwy kontekstu dla agentów kodujących, która utrzymuje wyprowadzony graf kodu w zgodzie ze źródłem przez skróty treści, a nie daty, i chroni blok pisany przez użytkownika na każdym regenerowanym węźle. Magazyn Graftu jest jednorazowy i odtwarzalny; ten nie jest, więc większość jego projektu się nie przenosi — ale kilka mechanizmów tak, a dwa z nich zamknęły tu realne luki.

Dodano:

• ## Crux — dosłowne fragmenty źródeł obok syntezy. Pozwala ckb-retrieve ugruntować odpowiedź bez powrotu do archiwum (gdy skrót się wciąż zgadza) i czyni odpływ od źródła wykrywalnym.
• ## Notes — pisane przez człowieka i chronione wszędzie. To zamknęło realną lukę: ckb-index-external regeneruje strony konektora w całości, więc napisana tam adnotacja ginęła dotąd przy kolejnym odświeżeniu.
• ## Sources — sformalizowane jako sekcja zastrzeżona z jednym punktem ze skrótem na źródło. Wcześniej nieformalna konwencja, na której ckb-retrieve polegało, ale której żaden skill faktycznie nie określał.
• source_fingerprint / source_checked we frontmatterze.
• Czasowniki krawędzi part_of, produces, configures, validates, implements. part_of naprawiło żywą niespójność: ckb-code-map zapisywał go od szablonu 1.7.0, a schemat nigdy go nie deklarował.

Zmieniono:

• wiki/graph/index.md przepisany jako tabela pytanie-na-czasownik wraz z konwencjami dotyczącymi kierunku krawędzi i dowodów.
• ckb-ingest dostał krok promienia rażenia: przed zapisem przejdź graf wstecz od dotkniętych encji, żeby ustalić, co nadchodzący materiał potwierdza, rozszerza albo z czym jest sprzeczny, i wskaż właścicieli dotkniętych stron. Ingest był dotąd przede wszystkim addytywny, a tak właśnie wiki gromadzi dwie strony, które po cichu się ze sobą nie zgadzają.
• ckb-retrieve wtapia stopień wejściowy grafu jako jedną z rankowanych list, z wagą poniżej 1.0 — centralność jest przesłanką, nie dowodem.
• Reguła E (start sesji) uruchamia teraz lint_report.py --quick obok git status: deterministyczny jednoliniowy sygnał gnicia wiedzy, niekosztujący żadnych tokenów modelu.
• Lint zyskał kontrole 12 (odpływ skrótu źródła), 13 (dosłowność sekcji Crux) i 14 (zasada chronionego ## Notes).

Kompatybilność: w pełni addytywna. Strona 1.4 bez żadnej z nowych sekcji i pól jest poprawną stroną 1.5. Migracja nigdy nie wytworzy ## Crux — zmyślanie cytatów to dokładnie ta porażka, której ta sekcja ma zapobiegać.

1.4 — 2026-09-01 · rekordy decyzji

Dodano: strony type: decision w wiki/decisions/ jako NNNN-slug.md, z status, decided_on, decided_by, affects, review_on; czasowniki krawędzi decided_by i affects; wiki/decisions/index.md wraz z własnym log.md; zasadę append-only. Odpowiada na „dlaczego jest tak, jak jest", „kto zdecydował" i „co zmieniło tę decyzję" bezpośrednim wyszukaniem zamiast zgadywania pełnotekstowego. Właścicielem jest skill ckb-decide.

1.3 — 2026-08-06 · krawędzie osoba–temat

Dodano: czasowniki krawędzi has_expertise_in i owns, dzięki którym „kto wie o X" i „kto jest właścicielem X" to wyszukanie w grafie, a nie przeszukiwanie pełnotekstowe. Zapisywane wyłącznie na podstawie wykazanych dowodów — obecność na spotkaniu to nie ekspertyza, a stanowisko to nie własność.

1.2 — 2026-07-29 · zakresy zapytań, luki i libs oparte na konektorach

Dodano: wiki/projects/ (opcjonalne lokalne zakresy zapytań grupujące powiązane strony, źródła i obszary grafu); wiki/query-gaps.md (nieudane wyszukiwania zapisane jako przyszłe cele ingestu); raw/archive/<YYYY-MM-DD>/ jako utrzymywane przez agenta miejsce archiwizacji; libs/<name>/ oparte na konektorach, z pisanym przez użytkownika source.yaml, należącym do agenta generowanym indeksem oraz czasownikiem krawędzi mentioned_in używanym wewnątrz tych indeksów.

1.1 — 2026-07-13 · pierwszy schemat

Pierwszy wersjonowany kontrakt, wydany wraz z pierwszym commitem. Ustanowił zestaw pól frontmatteru (type, resource, tldr, confidence, quality, supersedes/superseded_by, last_updated, freshness_window_days, retention), podstawowe czasowniki krawędzi (uses, depends_on, caused, contradicts, supersedes), szkielet wiki/, zasadę priorytetu kaskady i rekurencyjną konwencję indeksu i dziennika.

Wersji 1.0 nigdy nie było: wersjonowanie zaczęło się od pierwszego opublikowanego schematu.

---

Historia wersji szablonu

Warstwa narzędziowa — AGENTS.md/CLAUDE.md, skille, skrypty, dokumentacja. Niezależna od schematu treści powyżej.

Wersja	Data	Co weszło	Schemat
1.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 trzy gałęzie, a powyższe historie wersji śledzą wyłącznie main:

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	Rozwojowa — bieżąca praca, może być zepsuta albo wycofana	Osoby rozwijające sam szablon

Śledzona przez KB gałąź mieszka w ckb.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.

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. Aktualna wersja schematu: pole kb_schema_version w wiki/index.md. Licencja: Apache License 2.0.