michal/ckb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add release channels: main, test, experimental

Browse source 
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>
This commit is contained in:
Michał Kopeć 2026-09-22 08:29:45 +02:00
parent d66ebf6972
commit 6c0d70976c
12 changed files with 395 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

66
.agents/skills/ckb-init/SKILL.md
View file

@ -1,6 +1,6 @@
--- ---
name: ckb-init name: ckb-init
description: Bootstrap a brand-new Cascade Knowledge Base - the same directory structure, AGENTS.md/CLAUDE.md system prompt, full default skill set, LICENSE/VERSION, and empty wiki/ scaffold as this project - inside a target folder, sourcing the template either from this repo's own files or by pulling a fresh clone of the canonical ckb repo (or a user-supplied fork/mirror URL) into a scratch folder, so it works even when run outside an existing KB. The target folder is typically empty, or a new project that doesn't have a KB yet. Use when the user asks to "set up a new wiki like this one", "initialize a new cascade KB", "bootstrap a wiki here", "create a knowledge base with this schema", "pull the ckb repo into this folder", "clone the wiki template into <dir>", or calls it a "wiki initializer". Do not confuse with a generic `init` skill that documents an existing codebase - this one creates the Cascade KB pattern itself, empty, ready for its first ingest. Distinct from `ckb-upgrade`, which catches an *existing* populated KB up with template changes rather than bootstrapping a new one. description: Bootstrap a brand-new Cascade Knowledge Base - the same directory structure, AGENTS.md/CLAUDE.md system prompt, full default skill set, LICENSE/VERSION, and empty wiki/ scaffold as this project - inside a target folder, sourcing the template either from this repo's own files or by pulling a fresh clone of the canonical ckb repo (or a user-supplied fork/mirror URL) into a scratch folder, so it works even when run outside an existing KB. The target folder is typically empty, or a new project that doesn't have a KB yet. Use when the user asks to "set up a new wiki like this one", "initialize a new cascade KB", "bootstrap a wiki here", "create a knowledge base with this schema", "pull the ckb repo into this folder", "clone the wiki template into <dir>", or calls it a "wiki initializer". Also use when they name a release channel or branch to bootstrap from - "initialize from the test branch", "set up a dev KB from experimental", "bootstrap from <url> branch <name>" - since the template repo keeps main (stable), test (release candidate) and experimental (development) branches, and main is the default. Do not confuse with a generic `init` skill that documents an existing codebase - this one creates the Cascade KB pattern itself, empty, ready for its first ingest. Distinct from `ckb-upgrade`, which catches an *existing* populated KB up with template changes rather than bootstrapping a new one.
--- ---
# Cascade KB init skill # Cascade KB init skill
@ -80,7 +80,7 @@ scratch folder and copy out of it:
```bash ```bash
rm -rf <scratch> rm -rf <scratch>
git clone --depth 1 https://git.wierzbowa.cloud/michal/ckb.git <scratch> git clone --depth 1 --branch <branch> https://git.wierzbowa.cloud/michal/ckb.git <scratch>
``` ```
`<scratch>` is `tmp/ckb-init-src` under the *current* KB when this skill `<scratch>` is `tmp/ckb-init-src` under the *current* KB when this skill
@ -90,6 +90,34 @@ already gitignored), or a system temp path such as
Use a user-supplied URL instead if they named one ("initialize from Use a user-supplied URL instead if they named one ("initialize from
`<url>`") - a fork or an internal mirror is a legitimate template source. `<url>`") - a fork or an internal mirror is a legitimate template source.
#### Which branch (the release channel)
The canonical repo keeps three 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. |
Default to `main`. Take a different branch only when the user asks for one,
in whatever words: "initialize from the test branch", "use experimental",
"set up a dev KB", "bootstrap from `<url>` branch `<name>`", "I want the
bleeding edge". A fork's branch works the same way - `--branch` takes any
ref the source repo has.
If the user names a branch that does not exist on the source repo, the clone
fails with git's own error. Report it and list what does exist
(`git ls-remote --heads <url>`) rather than silently falling back to `main`:
a KB quietly initialized from the wrong channel is exactly the kind of thing
nobody notices until an upgrade behaves strangely.
**When initializing from `test` or `experimental`, say so plainly in the Step
12 report and explain what it means** - that this KB will keep pulling from
that channel until someone changes it, and that `experimental` in particular
carries no stability promise. Initializing onto a dev channel is a reasonable
thing to want; doing it without realizing is not.
If `git` isn't available or the clone fails (network, auth, unreachable If `git` isn't available or the clone fails (network, auth, unreachable
host), report the raw error; fall back to (b) if this skill is running host), report the raw error; fall back to (b) if this skill is running
inside a Cascade KB, otherwise stop - there is nothing to copy from. inside a Cascade KB, otherwise stop - there is nothing to copy from.
@ -224,6 +252,32 @@ actual project entity):
- `VERSION` - copy the exact current value; the new KB starts life on the - `VERSION` - copy the exact current value; the new KB starts life on the
same template version it was just cloned from. same template version it was just cloned from.
Then write `ckb.yaml` at the new KB's root, recording where its tooling came
from so its own `ckb-upgrade` knows what to check later:
```yaml
template:
repo: https://git.wierzbowa.cloud/michal/ckb.git
branch: main
```
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
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.
If the template source was this repo's own working tree (Step 3b) rather than
a clone, record the canonical repo URL and the branch this repo is currently
on (`git rev-parse --abbrev-ref HEAD`), since that is where the new KB's
upgrades will actually come from. Where that branch is `test` or
`experimental`, say so in the Step 12 report - propagating a dev channel into
a fresh KB by accident is easy, and the local working tree is exactly how it
happens.
`ckb.yaml` is also the modules manifest (`ckb-module` owns the `kb_modules:`
list). A fresh KB has no modules, so at init time the file holds the
`template:` block alone.
For `LICENSE`, copy the Apache License 2.0 text, but **ask the user first** For `LICENSE`, copy the Apache License 2.0 text, but **ask the user first**
whether to keep the copyright line as-is (appropriate if this new KB is whether to keep the copyright line as-is (appropriate if this new KB is
still effectively part of the same umbrella/organization) or update it to still effectively part of the same umbrella/organization) or update it to
@ -359,8 +413,12 @@ has a remote to point at.
Tell the user: Tell the user:
- The resolved target path. - The resolved target path.
- The template source used: the clone URL and short commit hash, or "this - The template source used: the clone URL, **branch**, and short commit hash,
repo's local working tree." or "this repo's local working tree" and the branch it was on. Name the
channel in words when it isn't `main` - "this KB tracks `experimental`,
which carries no stability promise; say 'switch to the main channel' to
change that."
- That `ckb.yaml` records the repo and branch for future upgrades.
- The directory tree created. - The directory tree created.
- Whether `AGENTS.md`/`CLAUDE.md` were written or (per Step 2) skipped/merged. - Whether `AGENTS.md`/`CLAUDE.md` were written or (per Step 2) skipped/merged.
- Which skills were copied (the full default set, plus anything explicitly - Which skills were copied (the full default set, plus anything explicitly

16
.agents/skills/ckb-module/SKILL.md
View file

@ -30,6 +30,10 @@ knowledge base, so it must travel with a clone and work for any agent that reads
Installed modules are recorded in `ckb.yaml` at the repo root: Installed modules are recorded in `ckb.yaml` at the repo root:
```yaml ```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
kb_modules: kb_modules:
- name: software - name: software
version: 1.0.0 version: 1.0.0
@ -43,7 +47,17 @@ configured with. It is **not** the wiki's content contract: `kb_schema_version`
stays in `wiki/index.md` where it has always been. Two different things, two stays in `wiki/index.md` where it has always been. Two different things, two
different homes. different homes.
If `ckb.yaml` doesn't exist, no modules are installed; create it on first install. The `template:` block records which upstream repo and **branch** this KB takes
its tooling from. It belongs to `ckb-init` (writes it) and `ckb-upgrade` (reads
it as the default source, updates it when the user switches channel). This
skill must **never** drop or rewrite it: a module install that silently reset a
KB from the `experimental` channel back to `main` would change what its next
upgrade pulls, which is not a module's business. Read `ckb.yaml`, edit the
`kb_modules:` list, write it back with everything else intact.
If `ckb.yaml` doesn't exist, no modules are installed and no template source is
recorded; create it on first install, carrying forward any `template:` block
that a later `ckb-upgrade` may add.
## Installing ## Installing

97
.agents/skills/ckb-upgrade/SKILL.md
View file

@ -1,6 +1,6 @@
--- ---
name: ckb-upgrade name: ckb-upgrade
description: Check the canonical Cascade KB template repo (https://git.wierzbowa.cloud/michal/ckb) for a newer schema/tooling version, and if one exists, upgrade this KB's template layer (AGENTS.md/CLAUDE.md, .agents/skills/, LICENSE, VERSION, README/MANUAL docs, base .gitignore rules) in place. Also checks wiki/index.md's own kb_schema_version for compatibility (including the case of an unversioned, pre-schema wiki) independently of the template layer, and — only with explicit confirmation — can migrate existing wiki/ content (backfilling missing frontmatter, adding missing scaffold files) up to the current schema while preserving every fact already collected. Use when the user asks to "upgrade the wiki", "upgrade this KB", "check for a newer template version", "update the KB schema", "pull in the latest skills", or "is there a new version of ckb". Distinct from ckb-sync-changes (reconciles this repo's OWN origin remote with its own history) and ckb-init (bootstraps a brand-new, empty KB) — this skill updates an EXISTING, populated KB's tooling layer (and, if asked, its content's schema conformance) from a separate upstream template source. description: Check the canonical Cascade KB template repo (https://git.wierzbowa.cloud/michal/ckb) for a newer schema/tooling version, and if one exists, upgrade this KB's template layer (AGENTS.md/CLAUDE.md, .agents/skills/, LICENSE, VERSION, README/MANUAL docs, base .gitignore rules) in place. Also checks wiki/index.md's own kb_schema_version for compatibility (including the case of an unversioned, pre-schema wiki) independently of the template layer, and — only with explicit confirmation — can migrate existing wiki/ content (backfilling missing frontmatter, adding missing scaffold files) up to the current schema while preserving every fact already collected. Use when the user asks to "upgrade the wiki", "upgrade this KB", "check for a newer template version", "update the KB schema", "pull in the latest skills", or "is there a new version of ckb". Also use when they name a release channel - "upgrade from the test branch", "check experimental for updates", "switch this KB to the stable channel" - since the template repo keeps main (stable), test (release candidate) and experimental (development) branches; the branch this KB tracks is recorded in ckb.yaml's template block and defaults to main. Distinct from ckb-sync-changes (reconciles this repo's OWN origin remote with its own history) and ckb-init (bootstraps a brand-new, empty KB) — this skill updates an EXISTING, populated KB's tooling layer (and, if asked, its content's schema conformance) from a separate upstream template source.
--- ---
# Upgrade skill # Upgrade skill
@ -79,19 +79,54 @@ repo's own `origin`) or for setting up a brand-new KB (that's `ckb-init`).
## How to run this skill ## How to run this skill
### Step 1 — Fetch the canonical template for comparison ### Step 0 — Resolve which repo and branch to compare against
Clone the canonical repo shallowly into a scratch location under `tmp/` — Read `ckb.yaml` at the repo root:
never touch this repo's own git remotes or history to do this comparison:
```yaml
template:
repo: https://git.wierzbowa.cloud/michal/ckb.git
branch: main
```
That block records where this KB's tooling comes from (written by
`ckb-init`). Missing file, missing block, or missing field → fall back to the
canonical repo on **`main`**, which is what every KB predating this
convention was effectively tracking.
#### The three 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. |
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
the dev version". A branch named in the request **overrides** `ckb.yaml` for
this run, and — once the upgrade is actually applied — is written back to
`ckb.yaml` so the next run stays on the channel the user chose. Do not write
it back on a run the user cancelled: they asked to *look*, not to move.
Clone shallowly into a scratch location under `tmp/` — never touch this
repo's own git remotes or history to do this comparison:
```bash ```bash
rm -rf tmp/ckb-upgrade-src rm -rf tmp/ckb-upgrade-src
git clone --depth 1 https://git.wierzbowa.cloud/michal/ckb.git tmp/ckb-upgrade-src git clone --depth 1 --branch <branch> <repo> tmp/ckb-upgrade-src
``` ```
If the clone fails (network, auth, unreachable host), report the raw If the clone fails (network, auth, unreachable host), report the raw
error and stop — this skill does not fall back to a cached or partial error and stop — this skill does not fall back to a cached or partial
check, and does not retry silently. check, and does not retry silently. If it fails specifically because the
**branch doesn't exist**, list what does (`git ls-remote --heads <repo>`)
and stop; never quietly substitute `main` for a branch the user named.
State the resolved repo and branch before doing anything else. On `test` or
`experimental`, say what that means in one line — an upgrade that pulls
unreleased or actively-broken tooling into a working KB should never be a
surprise.
### Step 2 — Compare template (tooling) versions ### Step 2 — Compare template (tooling) versions
@ -113,6 +148,24 @@ Step 3 regardless — a "no" here does **not** end the skill, because the
wiki content schema (Step 3) is checked independently and may still be wiki content schema (Step 3) is checked independently and may still be
behind. behind.
**When the local version is *higher* than the remote's, say so explicitly
rather than reporting "up to date".** The two are different facts and only
one of them is reassuring. This happens routinely once channels exist: a KB
that took tooling from `experimental` sits on a version `main` has not
released yet, so comparing it against `main` finds nothing newer — which is
true, and also not what "up to date" usually means to a reader.
Report it as what it is: "local v1.9.0 is ahead of `main`'s v1.8.0 — this KB
is carrying tooling from a pre-release channel." Then ask what they want,
because both answers are legitimate: stay ahead, or **downgrade** to the
stable branch. A downgrade is a real operation with real consequences — it
can remove skills, remove schema fields that local pages already use, and
lower `kb_schema_version` below what the content is written against — so
never perform one as a side effect of a channel switch. Name the specific
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.
### Step 3 — Compare the wiki content's own schema version ### Step 3 — Compare the wiki content's own schema version
This is a **separate** check from Step 2, and can find something to do This is a **separate** check from Step 2, and can find something to do
@ -254,6 +307,13 @@ Only if `template_upgrade_available` and at least one item was accepted:
this step — `wiki/` changes, if any, happen only in Step 7. this step — `wiki/` changes, if any, happen only in Step 7.
- Update local `VERSION` to the template's new version last, only once - Update local `VERSION` to the template's new version last, only once
every other accepted change has been applied successfully. every other accepted change has been applied successfully.
- If the user switched channel for this run (Step 0), write the new
`branch:` into `ckb.yaml`'s `template:` block now that the switch has
actually happened. Create the file with just that block if it doesn't
exist; if it does, edit only `template:` and leave `kb_modules:` exactly
as found — that list belongs to `ckb-module`. Persisting the branch is
what stops the *next* upgrade from silently pulling the KB back to
whichever channel it was on before.
### Step 7 — Rebuild wiki content to the new schema (only if confirmed in Step 5) ### Step 7 — Rebuild wiki content to the new schema (only if confirmed in Step 5)
@ -359,7 +419,9 @@ Report a summary covering whichever tracks actually ran:
```markdown ```markdown
## Upgrade report ## Upgrade report
**Template version:** v<old> → v<new> (or "already current") **Source:** <repo> on branch **<branch>** (channel: stable / release candidate / development)
**Channel changed:** <old> → <new> (or "no")
**Template version:** v<old> → v<new> (or "already current", or "local vX is ahead of this branch's vY")
**Added:** <N> file(s) — <paths, or "none"> **Added:** <N> file(s) — <paths, or "none">
**Updated:** <N> file(s) — <paths, or "none"> **Updated:** <N> file(s) — <paths, or "none">
**Kept local (declined template version):** <N> file(s) — <paths, or "none"> **Kept local (declined template version):** <N> file(s) — <paths, or "none">
@ -378,6 +440,27 @@ other than the template project itself.
## Edge cases ## Edge cases
- **`ckb.yaml` exists but has no `template:` block** — a KB created before
this convention. Treat it as canonical repo on `main`, and add the block
once an upgrade is actually applied. Don't write it on a check-only run.
- **`ckb.yaml` names a branch that no longer exists upstream** (a dev branch
that was merged and deleted) — report it with the list of branches that do
exist, and ask which to move to. Don't guess: a deleted `experimental` may
mean "its work is in `main` now" or "it was abandoned", and those lead to
different answers.
- **User asks to switch channel but declines every proposed change** — the
switch didn't happen, so don't persist the new branch. They looked at
another channel and chose not to take it; recording it would make the next
run pull from a channel they rejected.
- **Local `VERSION` is ahead of the target branch** — see Step 2. Report it
as "ahead", never as "up to date", and treat any downgrade as an explicit,
separately-confirmed operation.
- **Template repo is this very repo** (the template project upgrading
itself) — the comparison is between branches of one repo rather than
between two repos. That's valid, and the usual flow is `experimental` →
`test` → `main`; but say plainly that this is a self-upgrade, since the
"local vs upstream" framing in the report reads oddly otherwise.
- **No `VERSION` file locally** — treat local version as `0.0.0`; any real - **No `VERSION` file locally** — treat local version as `0.0.0`; any real
template version counts as newer. Mention in the report that this KB template version counts as newer. Mention in the report that this KB
predates version tracking. predates version tracking.

7
AGENTS.md
View file

@ -176,7 +176,12 @@ Short routing rules:
- For "sync changes", "sync with origin", or "push and pull my changes", - For "sync changes", "sync with origin", or "push and pull my changes",
use `ckb-sync-changes`, not ingest. use `ckb-sync-changes`, not ingest.
- For "upgrade the wiki" or "check for a newer template version", use - For "upgrade the wiki" or "check for a newer template version", use
`ckb-upgrade`. `ckb-upgrade`. The template repo keeps three branches — `main` (stable),
`test` (release candidate), `experimental` (development) — and a request
naming one ("upgrade from `test`", "switch to the stable channel") routes
here too. Which branch this KB tracks lives in `ckb.yaml`'s `template:`
block and defaults to `main`; `ckb-init` names it the same way when
bootstrapping.
- For "install/uninstall the `<name>` module", "what modules are - For "install/uninstall the `<name>` module", "what modules are
available", or a request for a capability the base KB lacks (such as available", or a request for a capability the base KB lacks (such as
handling source code), use `ckb-module`. handling source code), use `ckb-module`.

40
CHANGELOG.md
View file

@ -284,7 +284,8 @@ docs. Independent of the content schema above.
| Version | Date | What landed | Schema | | Version | Date | What landed | Schema |
|---|---|---|---| |---|---|---|---|
| **1.8.0** | 2026-09-21 | Seven ideas adopted from Graft: crux/notes/fingerprints, `--quick` lint mode, in-degree ranking, ingest blast radius, completed edge vocabulary | → 1.5 | | **1.9.0** | 2026-09-22 | Release channels: `main`/`test`/`experimental` branches, branch-aware `ckb-init` and `ckb-upgrade`, `template:` block in `ckb.yaml` | 1.5 |
| 1.8.0 | 2026-09-21 | Seven ideas adopted from Graft: crux/notes/fingerprints, `--quick` lint mode, in-degree ranking, ingest blast radius, completed edge vocabulary | → 1.5 |
| 1.7.0 | 2026-09-20 | Opt-in modules (`.agents/modules/`, `ckb-module`, `ckb.yaml`); the `software` module with `ckb-code-map` and `ckb-spec`; `ckb-reset`; OpenSpec docs | 1.4 | | 1.7.0 | 2026-09-20 | Opt-in modules (`.agents/modules/`, `ckb-module`, `ckb.yaml`); the `software` module with `ckb-code-map` and `ckb-spec`; `ckb-reset`; OpenSpec docs | 1.4 |
| 1.6.1 | 2026-09-01 | Fixed false-positive broken-edge findings in the lint graph check | 1.4 | | 1.6.1 | 2026-09-01 | Fixed false-positive broken-edge findings in the lint graph check | 1.4 |
| 1.6.0 | 2026-09-01 | `ckb-decide`; detection half of lint moved into `lint_report.py`; OKF export moved into `export_okf.py` | → 1.4 | | 1.6.0 | 2026-09-01 | `ckb-decide`; detection half of lint moved into `lint_report.py`; OKF export moved into `export_okf.py` | → 1.4 |
@ -306,9 +307,44 @@ Versions 1.4.0 and 1.5.0 were never published — the template jumped from
--- ---
## Release channels
The template repo keeps three branches, and the version histories above track
`main` only:
| 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 |
| `experimental` | **Development** — active work, may be broken or reverted | People developing the template itself |
The branch a KB tracks lives in `ckb.yaml`:
```yaml
template:
repo: https://git.wierzbowa.cloud/michal/ckb.git
branch: main
```
`ckb-init` writes it, `ckb-upgrade` reads it as the default and updates it when
you switch. No `ckb.yaml` and no `template:` block both mean `main`.
One consequence worth knowing: a KB that took tooling from `test` or
`experimental` can sit on a `VERSION` that `main` has not released yet.
Comparing it against `main` then finds nothing newer — which is true, but is
**not** the same as "up to date", and `ckb-upgrade` reports it as "ahead"
rather than as current. Moving such a KB back to `main` is a *downgrade*: it
can remove skills and lower `kb_schema_version` below what local pages are
written against. It requires an explicit confirmation, and is blocked outright
where the schema would drop below the content's own declared contract.
---
## Migrating between versions ## Migrating between versions
Say **"upgrade the wiki"** or **"check for a newer template version"**. The Say **"upgrade the wiki"** or **"check for a newer template version"**. To use
a different channel, name it: *"upgrade from the test branch"*, *"check
experimental"*, *"switch back to stable"*. The
`ckb-upgrade` skill checks the canonical template repo, updates the tooling `ckb-upgrade` skill checks the canonical template repo, updates the tooling
layer in place, and — separately, and only after you explicitly confirm — layer in place, and — separately, and only after you explicitly confirm —
migrates existing `wiki/` content up to the current schema while preserving migrates existing `wiki/` content up to the current schema while preserving

38
CHANGELOG.pl.md
View file

@ -291,7 +291,8 @@ Niezależna od schematu treści powyżej.
| Wersja | Data | Co weszło | Schemat | | Wersja | Data | Co weszło | Schemat |
|---|---|---|---| |---|---|---|---|
| **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.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.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.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.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 |
@ -312,9 +313,44 @@ Wersje 1.4.0 i 1.5.0 nigdy nie zostały opublikowane — szablon przeskoczył z
--- ---
## 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 ## Migracja między wersjami
Powiedz **„upgrade the wiki"** albo **„check for a newer template version"**. 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 Skill `ckb-upgrade` sprawdza kanoniczne repozytorium szablonu, aktualizuje
warstwę narzędziową w miejscu i — osobno, i wyłącznie po twoim wyraźnym warstwę narzędziową w miejscu i — osobno, i wyłącznie po twoim wyraźnym
potwierdzeniu — migruje istniejącą treść `wiki/` do bieżącego schematu, potwierdzeniu — migruje istniejącą treść `wiki/` do bieżącego schematu,

31
MANUAL.md
View file

@ -435,6 +435,37 @@ Say:
> "Upgrade the wiki." / "Check for a newer template version." > "Upgrade the wiki." / "Check for a newer template version."
### Which channel you're pulling from
The template repo keeps three branches, and by default you get the stable
one:
| Branch | What it is | Who should be on it |
|---|---|---|
| `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 |
To use a different one, just say which:
> "Upgrade from the test branch." / "Check experimental for updates." /
> "Switch this KB back to the stable channel."
Whichever you pick sticks — it's recorded in `ckb.yaml`, so the next upgrade
stays on the same channel rather than quietly pulling you back to `main`. The
same goes at creation time: *"initialize from the experimental branch"*.
One thing to watch. If you're tracking `test` or `experimental`, your KB can
sit on a version `main` hasn't released yet. Checking against `main` then
finds nothing newer — the agent will tell you you're **ahead**, not that
you're up to date, because those are different situations. Going back to
`main` from there is a *downgrade*: it can remove skills and roll the schema
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.
### What gets checked
Two entirely separate things get checked, and either, both, or neither Two entirely separate things get checked, and either, both, or neither
might turn something up: might turn something up:

29
MANUAL.pl.md
View file

@ -456,6 +456,35 @@ Powiedz:
> „Upgrade the wiki.” / „Check for a newer template version.” > „Upgrade the wiki.” / „Check for a newer template version.”
### Z jakiego kanału pobierasz
Repozytorium szablonu utrzymuje trzy gałęzie i domyślnie dostajesz tę
stabilną:
| Gałąź | Czym jest | Kto powinien na niej być |
|---|---|---|
| `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 |
Żeby użyć innej, po prostu powiedz której:
> „Upgrade from the test branch.” / „Check experimental for updates.” /
> „Switch this KB back to the stable channel.”
To, co wybierzesz, zostaje — jest zapisane w `ckb.yaml`, więc kolejny upgrade
zostanie na tym samym kanale, zamiast po cichu ściągnąć cię z powrotem na
`main`. Tak samo przy tworzeniu: *„zainicjuj z gałęzi experimental”*.
Na jedno warto uważać. Jeśli śledzisz `test` albo `experimental`, twoja KB
może mieć wersję, której `main` jeszcze nie wydało. Sprawdzenie względem
`main` nie znajdzie wtedy nic nowszego — agent powie ci, że **wyprzedzasz**, a
nie że jesteś aktualny, bo to dwie różne sytuacje. Powrót stamtąd na `main` to
*downgrade*: może usunąć skille i cofnąć schemat poniżej tego, pod co napisano
twoje strony. Zostaniesz poproszony o wyraźne potwierdzenie, a gdy treść
przestałaby być zgodna z własnym zadeklarowanym schematem — operacja zostanie
odmówiona.
Sprawdzane są dwie zupełnie odrębne rzeczy, i każda, obie albo żadna może Sprawdzane są dwie zupełnie odrębne rzeczy, i każda, obie albo żadna może
coś wykazać: coś wykazać:

24
README.md
View file

@ -21,6 +21,30 @@ adds `src/` repositories and spec-driven development — see
For the page schema in full, and for how both version numbers got where they For the page schema in full, and for how both version numbers got where they
are, see [CHANGELOG.md](CHANGELOG.md) ([Polski](CHANGELOG.pl.md)). are, see [CHANGELOG.md](CHANGELOG.md) ([Polski](CHANGELOG.pl.md)).
### Release channels
The template repo keeps three 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 |
Both `ckb-init` and `ckb-upgrade` default to `main`. To use another channel,
just say which: *"initialize from the test branch"*, *"check experimental for
updates"*, *"switch this KB back to the stable channel"*. The branch a KB
tracks is recorded in `ckb.yaml`:
```yaml
template:
repo: https://git.wierzbowa.cloud/michal/ckb.git
branch: main
```
A KB with no `ckb.yaml` (or no `template:` block) is treated as tracking
`main`, which is what every KB predating this convention was doing anyway.
--- ---
## Directory Structure ## Directory Structure

24
README.pl.md
View file

@ -22,6 +22,30 @@ Jeśli ta baza dokumentuje tworzone przez Ciebie oprogramowanie, opcjonalny modu
Pełny schemat strony oraz historię obu numerów wersji znajdziesz w Pełny schemat strony oraz historię obu numerów wersji znajdziesz w
[CHANGELOG.pl.md](CHANGELOG.pl.md) ([English](CHANGELOG.md)). [CHANGELOG.pl.md](CHANGELOG.pl.md) ([English](CHANGELOG.md)).
### Kanały wydawnicze
Repozytorium szablonu utrzymuje trzy 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 |
Zarówno `ckb-init`, jak i `ckb-upgrade` domyślnie używają `main`. Żeby użyć
innego kanału, po prostu powiedz którego: *„zainicjuj z gałęzi test"*,
*„sprawdź experimental pod kątem aktualizacji"*, *„przełącz tę KB z powrotem
na kanał stabilny"*. Śledzona gałąź jest zapisana w `ckb.yaml`:
```yaml
template:
repo: https://git.wierzbowa.cloud/michal/ckb.git
branch: main
```
KB bez `ckb.yaml` (albo bez bloku `template:`) jest traktowana jako śledząca
`main` — czyli dokładnie to, co i tak robiła każda KB sprzed tej konwencji.
--- ---
## Struktura katalogów ## Struktura katalogów

2
VERSION
View file

@ -1 +1 @@
1.8.0 1.9.0

38
workload/2026-09-22_summary.md
View file

@ -56,3 +56,41 @@ emptied defeats the purpose, so the record lives here instead — the same
reasoning `ckb-reset` applies to its Rule D exception. The migration this reasoning `ckb-reset` applies to its Rule D exception. The migration this
removed from the log remains documented in `CHANGELOG.md` and in commits removed from the log remains documented in `CHANGELOG.md` and in commits
`474630e`/`2c4d57a`, published on both remotes. `474630e`/`2c4d57a`, published on both remotes.
## [2026-09-22] Release channels — three branches, branch-aware init and upgrade
Added `test` and `experimental` branches alongside `main`, and taught
`ckb-init`/`ckb-upgrade` to source from any of them.
**Channel semantics:** `main` = stable/released, `test` = release candidate,
`experimental` = development. Default everywhere is `main`.
**Selection is per-invocation and sticky.** The user names a branch in words
("initialize from the test branch", "check experimental for updates", "switch
back to stable"); the choice is then persisted to `ckb.yaml`:
```yaml
template:
repo: https://git.wierzbowa.cloud/michal/ckb.git
branch: main
```
Persistence was a judgment call, not an explicit ask. Without it, a KB
bootstrapped from `experimental` would be silently pulled back to `main` by its
next upgrade — mixing channels without anyone noticing. Absent file or absent
block both mean `main`, so every pre-existing KB behaves exactly as before.
**The non-obvious consequence, handled explicitly:** a KB tracking `test` or
`experimental` can sit on a VERSION `main` has not released. Comparing against
`main` finds nothing newer, which the old code would have reported as "up to
date" — true but misleading. `ckb-upgrade` Step 2 now reports "ahead" instead,
and treats a move back to `main` as a downgrade requiring explicit
confirmation, blocked outright when `kb_schema_version` would drop below what
local content is written against.
**Files touched:** `ckb-init` (Step 3 channel table, Step 7 writes `ckb.yaml`,
Step 12 reports the channel), `ckb-upgrade` (new Step 0, Step 2 ahead-case,
Step 6 persists, Step 8 reports, 5 new edge cases), `ckb-module` (must not
clobber the `template:` block), `AGENTS.md` routing, both READMEs, both
MANUALs, both CHANGELOGs. VERSION 1.8.0 -> 1.9.0. Schema unchanged at 1.5 —
this is tooling, not a content contract.