# Historia zmian i referencja schematu

*Przeczytaj to w: [English](CHANGELOG.md) | **Polski***

Ten plik śledzi dwie rzeczy: schemat strony dokładnie w takiej postaci, w
jakiej obowiązuje dziś, oraz to, jak projekt doszedł do swoich obecnych
numerów wersji.

Istnieją **dwa niezależne numery wersji** i nie są tym samym:

| Numer | Mieszka w | Opisuje | Kto go podnosi |
|---|---|---|---|
| `kb_schema_version` | frontmatter `wiki/index.md` | **kontrakt treści** — co strona może zawierać i co te pola znaczą | `ckb-upgrade` (przy potwierdzonej migracji), `ckb-module` (addytywnie, przy instalacji) |
| Wersja szablonu | [`VERSION`](VERSION) | **warstwa narzędziowa** — `AGENTS.md`, skille, skrypty, dokumentacja | `ckb-upgrade`, gdy pobiera nowszy szablon |

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

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

---

## Spis treści

1. [Aktualny schemat strony (1.5)](#aktualny-schemat-strony-kb_schema_version-15)
2. [Historia wersji schematu KB](#historia-wersji-schematu-kb)
3. [Historia wersji szablonu](#historia-wersji-szablonu)
4. [Migracja między wersjami](#migracja-między-wersjami)

---

## Aktualny schemat strony (`kb_schema_version: "1.5"`)

### Frontmatter — każda strona niezastrzeżona

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

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

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

### Frontmatter — strony decyzji

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

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

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

### Zastrzeżone sekcje treści

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

#### `## Sources`

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

```markdown
## Sources

- `raw/archive/2026-09-21/kickoff-notes.md` — sha256:3f9a2c1e (checked 2026-09-21)
```

Okno świeżości to przypuszczenie, że źródło *mogło* się zmienić. Skrót to
fakt, czy *się zmieniło*. Lint przelicza skróty lokalne i oznacza to, co
faktycznie się zmieniło — a to inne i pilniejsze znalezisko niż strona, która
jedynie się zestarzała.

#### `## Crux`

Dosłowne fragmenty tych źródeł — dowód, nigdy parafraza — przypisane do
punktu źródła, z którego pochodzą:

```markdown
## Crux

> FDEs need the VDI *and* a Jira account before day one; the VDI request
> alone takes ten working days.
— `raw/archive/2026-09-21/kickoff-notes.md`, sekcja „Access"
```

Roboczy zakres to od trzech do dziesięciu linijek. Crux zbliżający się
długością do streszczenia nad nim przestał być dowodem i stał się drugą kopią
źródła. Z cytowania zamiast parafrazowania wynikają dwie rzeczy: na pytanie
często da się odpowiedzieć ze strony zamiast z archiwum, a odpływ od źródła
staje się widoczny — streszczenie może po cichu oddalić się od źródła, cytat
albo wciąż się zgadza, albo nie.

Strona bez cytowalnego źródła po prostu nie ma `## Crux`. Pusty albo
sparafrazowany jest gorszy niż żaden, bo wygląda jak dowód.

#### `## Notes`

Pisane przez człowieka i **chronione**. Żaden skill nie może tej sekcji
nadpisać, przeformatować, streścić ani usunąć; regeneracja zachowuje ją co do
bajtu.

```markdown
## Notes

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

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

### Słownik krawędzi

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

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

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

### Zastrzeżony szkielet

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

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

---

## Historia wersji schematu KB

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

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

**Dodano:**

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

**Zmieniono:**

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

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

### 1.4 — 2026-09-01 · rekordy decyzji

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

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

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

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

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

### 1.1 — 2026-07-13 · pierwszy schemat

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

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

---

## Historia wersji szablonu

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

| Wersja | Data | Co weszło | Schemat |
|---|---|---|---|
| **1.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`:

```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](VERSION). Aktualna wersja schematu: pole
`kb_schema_version` w `wiki/index.md`. Licencja:
[Apache License 2.0](LICENSE).