Michał Kopeć
6c0d70976c
The template repo now keeps three branches with fixed meanings — main is
stable, test is the release candidate, experimental is development — and
ckb-init/ckb-upgrade can source from any of them instead of only main.
Selection is per-invocation, in words the user already uses ("initialize
from the test branch", "check experimental for updates", "switch back to
stable"), and sticky: the resolved repo and branch are written to a
template: block in ckb.yaml. Without persistence, a KB bootstrapped from
experimental would be silently pulled back to main by its next upgrade.
A missing file or missing block both mean main, so every KB predating
this convention behaves exactly as before.
One consequence needed explicit handling. A KB tracking test or
experimental can sit on a VERSION main has not released yet, so comparing
it against main finds nothing newer — which the version check would have
reported as "up to date". That is true and misleading. ckb-upgrade now
reports it as "ahead", and treats a move back to main as a downgrade:
explicitly confirmed, with the specific losses named, and blocked
outright where kb_schema_version would drop below what local pages are
already written against.
ckb-module is told not to clobber the template: block — a module install
that silently reset a KB's channel would change what its next upgrade
pulls, which is not a module's business.
Documented in both READMEs, both MANUALs and both CHANGELOGs. VERSION
1.8.0 -> 1.9.0; kb_schema_version stays 1.5, since this is tooling rather
than a content contract.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
377 lines
20 KiB
Markdown
377 lines
20 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.
|
||
|
||
---
|
||
|
||
## 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).
|