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:
parent
3f5debdbe6
commit
8415004031
15 changed files with 137 additions and 17 deletions
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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/`.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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"*,
|
||||
|
|
|
|||
2
VERSION
2
VERSION
|
|
@ -1 +1 @@
|
|||
1.28.0
|
||||
1.28.1
|
||||
|
|
|
|||
2
ckb.yaml
2
ckb.yaml
|
|
@ -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: []
|
||||
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
86
docs/decisions/0019-two-dot-zero-drops-powershell.md
Normal file
86
docs/decisions/0019-two-dot-zero-drops-powershell.md
Normal 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.
|
||||
|
|
@ -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 |
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue