Template 1.28.1: 1.x maintenance channel, major-version guard (D-0019)

Adds the `1.x` release channel (fixes only, last line with PowerShell
support) to every channel table, and makes ckb-upgrade stop and ask before
crossing a major version, offering the maintenance branch instead.
D-0019 records the 2.0 plan: drop PowerShell, scripts stay in Python.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Michał Kopeć 2026-11-11 13:47:37 +01:00
parent 3f5debdbe6
commit 8415004031
15 changed files with 137 additions and 17 deletions

View file

@ -65,13 +65,14 @@ Use a user-supplied URL instead if they named one ("initialize from
#### Which branch (the release channel)
The canonical repo keeps three branches, and they are not interchangeable:
The canonical repo keeps four branches, and they are not interchangeable:
| Branch | What it is | Use it when |
|---|---|---|
| `main` | **Stable.** The released template. | Always, unless the user says otherwise. **This is the default.** |
| `test` | **Release candidate.** Changes validated before they reach `main`. | The user is helping validate a release, or needs a fix that has landed but not shipped. |
| `experimental` | **Development.** Active work; may be broken, may be reverted. | The user is developing the template itself, or explicitly wants the newest ideas and accepts the risk. |
| `1.x` | **Maintenance.** The 1.x line after 2.0: fixes only; the last line with PowerShell support. | The user needs PowerShell, or asks for 1.x by name. |
Default to `main`. Take a different branch only when the user asks for one,
in whatever words: "initialize from the test branch", "use experimental",
@ -263,7 +264,7 @@ template:
```
Use the URL and branch actually resolved in Step 3 - the user's fork URL if
they named one, `test`/`experimental` if they asked for that channel. Write
they named one, `test`/`experimental`/`1.x` if they asked for that channel. Write
this block **even for the default** `main`/canonical case: an explicit record
is what makes a later channel switch visible, and it costs one file.

View file

@ -21,7 +21,7 @@ Installed modules are recorded in `ckb.yaml` at the repo root:
```yaml
template: # written by ckb-init, read and updated by ckb-upgrade
repo: https://git.wierzbowa.cloud/michal/ckb.git
branch: main # main | test | experimental, or any branch of a fork
branch: main # main | test | experimental | 1.x, or any branch of a fork
kb_modules:
- name: software

View file

@ -1,6 +1,6 @@
---
name: ckb-upgrade
description: Check the canonical Cascade KB template repo for a newer version and upgrade this KB's template layer (AGENTS.md/CLAUDE.md, .agents/skills/, LICENSE, VERSION, docs, base .gitignore) in place, and — only with explicit confirmation — migrate existing wiki/ content up to the current kb_schema_version. Use for "upgrade the wiki", "check for a newer template version", "pull in the latest skills", or a named release channel (main/test/experimental).
description: Check the canonical Cascade KB template repo for a newer version and upgrade this KB's template layer (AGENTS.md/CLAUDE.md, .agents/skills/, LICENSE, VERSION, docs, base .gitignore) in place, and — only with explicit confirmation — migrate existing wiki/ content up to the current kb_schema_version. Use for "upgrade the wiki", "check for a newer template version", "pull in the latest skills", or a named release channel (main/test/experimental/1.x).
---
# Upgrade skill
@ -69,13 +69,14 @@ That block records where this KB's tooling comes from (written by
canonical repo on **`main`**, which is what every KB predating this
convention was effectively tracking.
#### The three channels
#### The channels
| Branch | What it is | Who should be on it |
|---|---|---|
| `main` | **Stable.** The released template. | Everyone, by default. |
| `test` | **Release candidate.** Validated before merging to `main`. | Anyone helping validate a release, or needing a landed-but-unshipped fix. |
| `experimental` | **Development.** Active work; may be broken or reverted. | People developing the template itself. |
| `1.x` | **Maintenance.** The 1.x line after 2.0: fixes only; the last line with PowerShell support. | KBs that need PowerShell, or can't move to 2.0 yet. |
A user switches channel by saying so: "upgrade from the test branch", "check
experimental for updates", "switch this KB to the stable channel", "I want
@ -149,6 +150,15 @@ losses, take an explicit confirmation, and treat a `kb_schema_version` that
would drop below the local wiki's as a **blocker**, not a warning: the
content would stop conforming to its own declared contract.
**When the remote's major version is higher than the local one, stop and
ask before Step 4.** A major bump (`1.28.1` → `2.0.0`) removes something a KB
may rely on. Quote the breaking part of the top `docs/CHANGELOG.md` row
upstream, then offer two answers: take the new major, or stay on the old line
by switching this KB to its maintenance branch (`1.x` for 1.x versions),
which keeps getting fixes but no new features. Staying is a channel switch
(Step 0): rerun against that branch and persist it once applied. Never cross
a major from a routine or batch run, even a `confirm: false` one.
### Step 3 — Compare the wiki content's own schema version
This is a **separate** check from Step 2, and can find something to do

View file

@ -251,9 +251,9 @@ Disambiguation, only where the table alone is ambiguous:
template" on its own, as in "upgrade the template", is the tooling layer
and stays with `ckb-upgrade`.
- `ckb-upgrade` also takes a request naming a release channel. The template repo
keeps `main` (stable), `test` (release candidate) and `experimental`
(development); which branch this KB tracks lives in `ckb.yaml`'s `template:`
block and defaults to `main`.
keeps `main` (stable), `test` (release candidate), `experimental`
(development) and `1.x` (maintenance of the 1.x line); which branch this
KB tracks lives in `ckb.yaml`'s `template:` block and defaults to `main`.
- `ckb-reset` deletes accumulated knowledge, so it always shows an inventory and
takes a typed confirmation first, and never touches the template layer or `src/`.

View file

@ -42,13 +42,14 @@ Why the template is shaped the way it is - its own design decisions - is in
### Release channels
The template repo keeps three branches. They are not interchangeable:
The template repo keeps four branches. They are not interchangeable:
| Branch | What it is | Who should track it |
|---|---|---|
| `main` | **Stable** - the released template | Everyone, by default |
| `test` | **Release candidate** - validated before merging to `main` | Anyone helping validate a release, or needing a landed-but-unshipped fix |
| `experimental` | **Development** - active work, may be broken or reverted | People developing the template itself |
| `1.x` | **Maintenance** - the 1.x line after 2.0: fixes only; the last line with PowerShell support | KBs that need PowerShell, or can't move to 2.0 yet |
Both `ckb-init` and `ckb-upgrade` default to `main`. To use another channel,
say which: *"initialize from the test branch"*, *"check experimental for

View file

@ -45,13 +45,14 @@ opisuje [docs/decisions/](docs/decisions/README.md).
### Kanały wydawnicze
Repozytorium szablonu utrzymuje trzy gałęzie. Nie są wymienne:
Repozytorium szablonu utrzymuje cztery gałęzie. Nie są wymienne:
| 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 albo potrzebuje poprawki, która weszła, ale jeszcze nie została wydana |
| `experimental` | **Rozwojowa** — bieżąca praca, może być zepsuta albo wycofana | Osoby rozwijające sam szablon |
| `1.x` | **Utrzymaniowa** — linia 1.x po wydaniu 2.0: tylko poprawki; ostatnia z obsługą PowerShella | KB, które potrzebują PowerShella albo nie mogą jeszcze przejść na 2.0 |
Zarówno `ckb-init`, jak i `ckb-upgrade` domyślnie używają `main`. Żeby użyć
innego kanału, powiedz którego: *„zainicjuj z gałęzi test"*,

View file

@ -1 +1 @@
1.28.0
1.28.1

View file

@ -4,7 +4,7 @@
# (conversations:), ckb-lint (session:, budget:) and ckb-routine (routines:).
template:
repo: https://git.wierzbowa.cloud/michal/ckb.git
branch: main # main | test | experimental
branch: main # main | test | experimental | 1.x
kb_modules: []

View file

@ -340,7 +340,8 @@ docs. Independent of the content schema above.
| Version | Date | What landed | Schema |
|---|---|---|---|
| **1.28.0** | 2026-11-11 | New opt-in `share` module (D-0018): skill `ckb-share` and `share.py` (`join`/`send`/`unshare`/`list`/`receive`/`status`, stdlib + git). A **channel** is a separate git repo per trust group with `CHANNEL.md`, `members.yaml` (kb → owner emails) and one append-only mailbox per KB, `mail/<kb>/`, cloned into `tmp/share/<channel>/`. **Send** packs a self-contained copy of an `outputs/documents/`, `outputs/answers/` or `wiki/` page (`raw/archive/` only with `--raw-ok`): `<private>` spans and `## Notes` dropped, local links as text, Sources/Crux paths marked `<kb>:`; envelope `type: share`, `kind`, `share_id`, `version`, `from`, `to`, `sent_by`, `untrusted: true`; lint's secret patterns block the send (exit 3), a dry run prints the `ABOUT.md` sensitivity section, the user confirms. Re-sending makes the next version. **Receive** copies messages addressed to the KB into `raw/inbox/` with `share_channel`, `share_ref`, `received_on`, `submitted_by` (git author) and `supersedes_source`; a message whose git author is not an owner of its mailbox is UNVERIFIED and taken only with `--accept-unverified`; a retraction becomes `raw/retractions/` requests for every held version. A `received:` ledger in the script-owned `share:` block of `ckb.yaml` keeps handled messages from returning. `dedup_inbox.py` reports `SAME SHARE`; `ckb-ingest` and `ckb-retract` know share files and requests. Smoke test covers two KBs and a bare-repo channel end to end | 1.7 |
| **1.28.1** | 2026-11-11 | Release channel `1.x`: the maintenance branch for the 1.x line once 2.0 ships, fixes only, and the last line with PowerShell support (D-0019). Listed in the channel tables of `ckb-init`, `ckb-upgrade`, `AGENTS.md`, both READMEs and both manuals, and in the `ckb.yaml` comment. `ckb-upgrade` Step 2: a higher **major** version upstream stops the run before Step 4, quotes the breaking part of the upstream changelog row, and offers the new major or a switch to the maintenance branch; never crossed from a routine or batch run | 1.7 |
| 1.28.0 | 2026-11-11 | New opt-in `share` module (D-0018): skill `ckb-share` and `share.py` (`join`/`send`/`unshare`/`list`/`receive`/`status`, stdlib + git). A **channel** is a separate git repo per trust group with `CHANNEL.md`, `members.yaml` (kb → owner emails) and one append-only mailbox per KB, `mail/<kb>/`, cloned into `tmp/share/<channel>/`. **Send** packs a self-contained copy of an `outputs/documents/`, `outputs/answers/` or `wiki/` page (`raw/archive/` only with `--raw-ok`): `<private>` spans and `## Notes` dropped, local links as text, Sources/Crux paths marked `<kb>:`; envelope `type: share`, `kind`, `share_id`, `version`, `from`, `to`, `sent_by`, `untrusted: true`; lint's secret patterns block the send (exit 3), a dry run prints the `ABOUT.md` sensitivity section, the user confirms. Re-sending makes the next version. **Receive** copies messages addressed to the KB into `raw/inbox/` with `share_channel`, `share_ref`, `received_on`, `submitted_by` (git author) and `supersedes_source`; a message whose git author is not an owner of its mailbox is UNVERIFIED and taken only with `--accept-unverified`; a retraction becomes `raw/retractions/` requests for every held version. A `received:` ledger in the script-owned `share:` block of `ckb.yaml` keeps handled messages from returning. `dedup_inbox.py` reports `SAME SHARE`; `ckb-ingest` and `ckb-retract` know share files and requests. Smoke test covers two KBs and a bare-repo channel end to end | 1.7 |
| 1.27.0 | 2026-11-02 | New core skill `ckb-feynman`, adapted from the `feynman` skill in superhero-tech-super-brain: explains one page in plain words with a concrete example and a `→ [[page]] · [Title § Heading](/wiki/…#anchor)` line under each block, then sorts every thin spot into Wiki, Sources or Mine gaps without filling any from model knowledge, asks for an explain-back and ends with numbered next moves. Candidates come from `review: draft`/`needs_update`, single-source, stale or contradicted pages; topic pages are followed to their members; Crux fingerprints are checked as in `ckb-retrieve` Step 6; `<private>` spans are never explained. Sessions go to `outputs/teaching/feynman/YYYY-MM-DD_<slug>.md` (`type: feynman-session`, fingerprinted `## Sources`, gitignored with `outputs/teaching/`, no `wiki/log.md` entry); a Sources gap reaches `wiki/query-gaps.md` only on a yes. `ckb-teach-me` skips the folder; `ckb-init`, `AGENTS.md` routing row, both READMEs and manuals updated; eval case `ckb-feynman/session` with a recorded reference run (6/6). `outputs/teaching/` added to the directory contract; `run_evals.py` matches deleted files with glob semantics (`**` was one segment) | 1.7 |
| 1.26.2 | 2026-11-10 | `ABOUT.pl.md`: the Polish pair of the `ABOUT.md` scaffold, like the other `.pl.md` docs. Agents read both when both are filled in and `ABOUT.md` wins on a conflict (`AGENTS.md`, `ckb-ingest`); `ckb-init` copies both and puts a Polish answer in the Polish file; `ckb-upgrade` creates it once for KBs below 1.26.2 and never recreates a deleted one; `ckb-reset` leaves it alone; the `mcp` server's `kb_overview` includes it and its description falls back to its `tldr`, ignoring either placeholder. `README.pl.md` and `QUICKSTART.pl.md` point to it; both manuals list it | 1.7 |
| 1.26.1 | 2026-11-02 | Docs: a one-page quickstart, `docs/QUICKSTART.md` and `docs/QUICKSTART.pl.md`, from an empty folder to the first ingest, answer, lint and sync; linked from both READMEs and both manuals | 1.7 |

View file

@ -348,7 +348,8 @@ Niezależna od schematu treści powyżej.
| Wersja | Data | Co weszło | Schemat |
|---|---|---|---|
| **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.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 |

View file

@ -639,7 +639,7 @@ Say:
### Which channel you're pulling from
The template repo keeps three branches, and by default you get the stable
The template repo keeps four branches, and by default you get the stable
one:
| Branch | What it is | Who should be on it |
@ -647,6 +647,7 @@ one:
| `main` | **Stable** - the released template | You, unless you have a reason not to be |
| `test` | **Release candidate** - validated before it reaches `main` | You're helping validate a release, or you need a fix that's landed but not shipped |
| `experimental` | **Development** - active work, may be broken or reverted | You're developing the template itself |
| `1.x` | **Maintenance** - the 1.x line after 2.0: fixes only; the last line with PowerShell support | You need PowerShell, or can't move to 2.0 yet |
To use a different one, say which:
@ -666,6 +667,12 @@ back below what your pages are written against. You'll be asked to confirm
explicitly, and it's refused outright if your content would stop conforming
to its own declared schema.
A new **major** version (1.x → 2.0) removes something a KB may rely on, so
the agent never crosses one quietly, not even from a routine. It names what
the new major removes, from the changelog, and asks: take it, or move this
KB to the `1.x` maintenance branch (*"switch this KB to the 1.x branch"*),
which keeps getting fixes but no new features.
### What gets checked
Two separate things get checked, and either, both, or neither

View file

@ -669,7 +669,7 @@ Powiedz:
### Z jakiego kanału pobierasz
Repozytorium szablonu utrzymuje trzy gałęzie i domyślnie dostajesz tę
Repozytorium szablonu utrzymuje cztery gałęzie i domyślnie dostajesz tę
stabilną:
| Gałąź | Czym jest | Kto powinien na niej być |
@ -677,6 +677,7 @@ stabilną:
| `main` | **Stabilna** — wydany szablon | Ty, o ile nie masz powodu, żeby być gdzie indziej |
| `test` | **Kandydat do wydania** — walidowany, zanim trafi do `main` | Pomagasz walidować wydanie albo potrzebujesz poprawki, która weszła, ale nie została wydana |
| `experimental` | **Rozwojowa** — bieżąca praca, może być zepsuta albo wycofana | Rozwijasz sam szablon |
| `1.x` | **Utrzymaniowa** — linia 1.x po wydaniu 2.0: tylko poprawki; ostatnia z obsługą PowerShella | Potrzebujesz PowerShella albo nie możesz jeszcze przejść na 2.0 |
Żeby użyć innej, powiedz której:
@ -695,6 +696,12 @@ nie że jesteś aktualny, bo to dwie różne sytuacje. Powrót stamtąd na `main
twoje strony. Agent poprosi o wyraźne potwierdzenie, a gdy treść
przestałaby być zgodna z własnym zadeklarowanym schematem, odmówi wprost.
Nowa wersja **główna** (1.x → 2.0) usuwa coś, na czym KB może polegać, więc
agent nigdy nie przechodzi przez nią po cichu, nawet z rutyny. Podaje, co
nowa wersja usuwa (z changeloga), i pyta: przejść, czy przełączyć tę KB na
gałąź utrzymaniową `1.x` (*„przełącz tę KB na gałąź 1.x”*), która dostaje
poprawki, ale już nie nowe funkcje.
### Co jest sprawdzane
Sprawdzane są dwie odrębne rzeczy, i każda, obie albo żadna może

View file

@ -16,6 +16,10 @@ retention: high
**Status:** Accepted · **Decided:** 2026-09-29 · **Deciders:** Michał Kopeć
> The PowerShell half (`lint_quick.ps1`, the `[version]` comparison) was
> dropped in template 2.0.0 by [D-0019](0019-two-dot-zero-drops-powershell.md).
> Everything else stands; 1.x keeps it on the `1.x` branch.
## Context
Four skills delegate their deterministic half to a Python script:

View file

@ -0,0 +1,86 @@
---
type: decision
tldr: Template 2.0.0 drops PowerShell (lint_quick.ps1 and every PowerShell snippet); scripts the template and its modules ship stay in Python; the 1.x line continues on a `1.x` maintenance branch for fixes, and ckb-upgrade never crosses a major version without asking.
status: accepted
decided_on: 2026-11-11
decided_by: Michał Kopeć
affects: .agents/skills/ckb-lint/, .agents/skills/ckb-upgrade/SKILL.md, .agents/skills/ckb-init/SKILL.md, .agents/skills/ckb-sync-changes/SKILL.md, AGENTS.md, README.md, docs/MANUAL.md, docs/CHANGELOG.md, VERSION
confidence: 0.85
quality: 0.8
last_updated: 2026-11-11
freshness_window_days: 365
retention: high
---
# D-0019 — 2.0 drops PowerShell; 1.x continues on a maintenance branch
**Status:** Accepted · **Decided:** 2026-11-11 · **Deciders:** Michał Kopeć
> Supersedes only the PowerShell half of [D-0003](0003-python-runtime-with-degraded-fallbacks.md).
> Python as the single scripting runtime, interpreter resolution, the bash
> fallback and the per-skill degraded paths stand.
## Context
[D-0003](0003-python-runtime-with-degraded-fallbacks.md) shipped two native
fallbacks for the session-start check, `lint_quick.sh` and `lint_quick.ps1`,
and said any change to checks 1, 2, 12 (later also 15) must land in both.
The smoke test diffs the bash copy against `lint_report.py --quick`; the
PowerShell copy has never run in CI and is "reviewed by hand until a Windows
runner exists". No runner exists, and an open thread to test it on a
machine with PowerShell has gone unclosed. Each lint change that touched
the fallback paid for a copy nobody could verify.
Windows users are not left without a path: Python installs in one command
(`winget`, the Store, python.org), and Git for Windows, which the KB already
needs, ships bash, so `lint_quick.sh` runs there too.
## Decision
1. **Template 2.0.0 removes PowerShell support.** `lint_quick.ps1` is
deleted; the PowerShell version comparison in `ckb-upgrade` Step 2 and
every "or the `.ps1`" mention go with it. Removing a shipped fallback is
breaking, hence the major bump. `kb_schema_version` is unaffected: the
content contract stays 1.7.
2. **Scripts stay in Python.** Every script the template runs, in skills and
in modules, is Python 3.8+ standard library. A module may need other
tools (git, Docker, `yt-dlp`), but the scripts it carries are Python.
Two non-Python files stay as named exceptions: `lint_quick.sh`, the
no-Python fallback (it exists *because* Python is missing), and the `mcp`
module's container `entrypoint.sh`, which runs inside the image, not on
the user's machine.
3. **The 1.x line continues on a `1.x` branch**, cut from 1.28.1. It gets
fixes only, no new features, and is the last line with PowerShell
support. It is a release channel like `main`/`test`/`experimental`: a KB
tracks it through `branch: 1.x` in `ckb.yaml`.
4. **`ckb-upgrade` never crosses a major version silently.** When upstream's
major is higher, it quotes the breaking part of the changelog and asks:
take the new major, or switch to the maintenance branch. Never from a
routine or batch run. This landed in 1.28.1 so that a KB upgrading from
1.28.1 onward already has the guard before it meets 2.0.
## Alternatives considered
- **Keep `lint_quick.ps1` and add a Windows CI runner.** Fixes the
verification gap, but keeps the cost of a third implementation for a
fallback that only serves people without Python, who can install it in
one command.
- **Drop the bash fallback too, making the rule "all scripts are Python"
absolute.** Considered and declined: bash is tested against the Python
reference on every smoke run, so it costs little, and it keeps the
session-start check alive on a machine with no Python.
- **No maintenance branch; tell 1.x users to pin a tag.** A tag gets no
fixes, and `ckb-upgrade` tracks branches, not tags.
## Consequences
- Windows users without Python lose the native session-start fallback
unless they run it under Git Bash; the agent falls through to the manual
checklist otherwise.
- Changes to the quick checks now land in two places (Python, bash), both
covered by the smoke test.
- A KB on 1.28.0 or older upgrading straight from `main` lacks the major
guard; its Step 5 still shows every changed file and the changelog row,
and the deleted `.ps1` is visible there.
- Fixes worth having on both lines are made on `1.x` and merged forward
into `main`, or cherry-picked when the code has diverged.

View file

@ -16,7 +16,7 @@ but they live here, in the template layer, because:
|---|---|
| [D-0001](0001-opt-in-file-based-kb-modules.md) | Optional capabilities ship as file-based modules under `.agents/modules/`, installed on request |
| [D-0002](0002-software-module-design.md) | The `software` module: gitignored `src/` clones, two OpenSpec spec levels, hybrid vendoring |
| [D-0003](0003-python-runtime-with-degraded-fallbacks.md) | Python stays the only scripting runtime; portable interpreter resolution, per-OS install guidance, a native fallback for the session-start check, degraded paths per skill |
| [D-0003](0003-python-runtime-with-degraded-fallbacks.md) | Python stays the only scripting runtime; portable interpreter resolution, per-OS install guidance, a native fallback for the session-start check, degraded paths per skill (PowerShell half dropped by D-0019) |
| [D-0004](0004-session-identity-from-git.md) | The git identity is the session's author; one workload file per person per day; `**Author:**` on log entries and saved conversations |
| [D-0005](0005-session-titles-and-routines.md) | A new session asks for its title first and waits (point 1 reversed by D-0006); routines are time-since-last actions in `ckb.yaml`, run after the user's request, with `last_run` committed |
| [D-0006](0006-title-chosen-by-agent.md) | The agent derives the session title from the first message and only announces it in one line; `announce_title` replaces `ask_title` |
@ -32,3 +32,4 @@ but they live here, in the template layer, because:
| [D-0016](0016-topic-summaries-and-consolidation.md) | Schema 1.7: agent-built topic pages in `wiki/topics/` with member-page digests as sources; a new `ckb-consolidate` skill writes proposals-only reports (topics, merges, links, stale, old log) and builds only approved topic pages |
| [D-0017](0017-capture-module-and-skill-evals.md) | Opt-in `capture` module (stdlib fetch, Wayback only over a failed/thinner page, agent tool fallback, untrusted marking, dedup at capture, `yt-dlp` with consent); structural skill evals with a prepare/check runner; multi-agent setup documented as untested |
| [D-0018](0018-share-mailbox-module.md) | Opt-in `share` module: KBs exchange documents through a git channel with one append-only mailbox per KB; received mail lands in `raw/inbox/` (untrusted) and retractions in `raw/retractions/`; the git author must own the mailbox; handled messages are kept in a ledger in `ckb.yaml` |
| [D-0019](0019-two-dot-zero-drops-powershell.md) | Template 2.0.0 drops PowerShell; every script the template and its modules ship is Python (bash fallback and the container entrypoint named as exceptions); 1.x continues on a `1.x` maintenance branch; `ckb-upgrade` never crosses a major version without asking |