ckb/.agents/skills/ckb-upgrade/SKILL.md
Michał Kopeć da2833abfe Sync: local changes as of 2026-11-01T20:31:36Z
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 21:31:36 +01:00

441 lines
22 KiB
Markdown

---
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).
---
# Upgrade skill
## Purpose
A KB has two layers, checked independently; it can be behind on either,
both, or neither:
- **Template layer** — `AGENTS.md`/`CLAUDE.md`, `.agents/skills/*`,
`LICENSE`, `VERSION`, `README*`, `docs/`, the base `.gitignore` rules
(`tests/` stays in the template repo). Compared via `VERSION`; freely
upgradable, it holds no project-specific content.
- **Content layer** — `wiki/`, `raw/`, `outputs/`, `workload/`. Compared
via `wiki/index.md`'s `kb_schema_version` (absent counts as unversioned
and behind). Never touched automatically: a migration runs only after
explicit confirmation (Steps 3 and 7) and only adds or backfills
structure, never rewrites what a page says.
## Schema versioning policy
`wiki/index.md` is the only wiki file that carries `kb_schema_version`.
Treat it as the version of the wiki content contract, not as a per-page
field.
Use schema versions as `MAJOR.MINOR`:
- Bump the **minor** version for backward-compatible additions: optional
frontmatter fields, optional reserved wiki scaffolds, new optional
subdirectories such as `wiki/projects/`, or additional optional
index/log conventions.
- Bump the **major** version for breaking changes: removing or renaming a
required field, changing the meaning of an existing required field,
removing an existing reserved filename convention, or changing cascade
lookup semantics in a way older tooling cannot safely interpret.
The root `VERSION` file tracks the template/tooling release, not just the
wiki schema. When a schema convention changes in the template repo, update
the relevant docs/skills and `VERSION` in the same template-layer change.
When migrating an existing KB's content layer, bump `wiki/index.md`'s
`kb_schema_version` only after the confirmed migration has actually
completed.
This is different from `ckb-sync-changes` (reconciles *this* repo's own
commit history with *its own* `origin` remote — same content, no template
comparison) and from `ckb-init` (bootstraps a brand-new, empty KB from the
template — nothing to preserve because there's no content yet). This skill
assumes you already have a populated KB and want to catch it up with
template improvements made elsewhere, without disturbing anything you've
collected unless you specifically ask it to reshape that content's
structure too.
## How to run this skill
### Step 0 — Resolve which repo and branch to compare against
Read `ckb.yaml` at the repo root:
```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
rm -rf 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
error and stop — this skill does not fall back to a cached or partial
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
Read `VERSION` at the repo root (treat a missing file as `0.0.0` — an
older KB that predates this convention) and
`tmp/ckb-upgrade-src/VERSION`. Compare as dotted-integer tuples
(`1.2.0` > `1.1.9`), not as plain strings — e.g.:
```bash
# bash — `sort -V` orders dotted versions numerically
local_v=$(cat VERSION 2>/dev/null || echo 0.0.0); remote_v=$(cat tmp/ckb-upgrade-src/VERSION)
[[ "$local_v" != "$remote_v" && "$(printf '%s\n' "$local_v" "$remote_v" | sort -V | tail -n1)" == "$remote_v" ]] && echo newer || echo same-or-older
```
```powershell
# PowerShell — [version] compares component-wise
$l = [version](Get-Content VERSION -ErrorAction SilentlyContinue | Select-Object -First 1); if (-not $l) { $l = [version]"0.0.0" }
$r = [version](Get-Content tmp/ckb-upgrade-src/VERSION | Select-Object -First 1)
if ($r -gt $l) { "newer" } else { "same-or-older" }
```
No Python needed for this step; with only two numbers to compare, doing it
by eye is acceptable too.
Record the result (`template_upgrade_available`: yes/no) and continue to
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
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
This is a **separate** check from Step 2, and can find something to do
even when Step 2 didn't. Read the `kb_schema_version` frontmatter field
from local `wiki/index.md`, and from
`tmp/ckb-upgrade-src/wiki/index.md` (the version new KBs are created with
today). Compare as `(major, minor)` tuples, e.g. `"1.2"` > `"1.1"`.
- **Local `wiki/index.md` has no `kb_schema_version` at all** — this is an
**unversioned** wiki: either it predates the convention entirely, or it
was hand-built without the standard frontmatter. Treat it as behind by
default, same as version `"0.0"`.
- **Local version is older than the template's** — behind.
- **Local version is the same or newer** — not behind; nothing to do for
content.
Record the result (`wiki_schema_upgrade_available`: yes/no, plus the two
version strings for reporting).
**If both `template_upgrade_available` and `wiki_schema_upgrade_available`
are "no"** → report "already up to date — template v`X`, wiki schema
v`Y`," clean up the scratch clone (Step 8), and stop.
### Step 4 — Diff the template layer only (if `template_upgrade_available`)
Skip this step entirely if Step 2 found no template upgrade — go straight
to Step 5 with just the wiki-schema finding to present, if any.
The template layer is exactly these paths — never `ABOUT.md`, and never
anything under `wiki/`, `raw/`, `outputs/`, `templates/`, `workload/`,
`tmp/`, `libs/`, or `linked/`:
- `AGENTS.md` (and the `CLAUDE.md` symlink — recreate it if it's missing
or isn't a symlink to `AGENTS.md`; don't diff its content, it's just a
symlink)
- `LICENSE`
- `VERSION`
- `README.md`, `README.pl.md`, and everything under `docs/` (`MANUAL*`,
`CHANGELOG*`, `OPENSPEC*`, `decisions/`) — whichever exist upstream. A KB
older than template 1.10 keeps these at the repo root; move them into
`docs/` as part of the upgrade and say so.
- Take the changelogs from upstream wholesale rather than merging: they
record the template's history, which the upstream copy is authoritative
about.
- `tests/` is **not** part of the upgrade. If this KB has a `tests/` folder
left over from a template before 1.15.0, say so once and offer to delete
it; leave it alone unless the user agrees.
- `.agents/skills/<name>/**` for every skill folder present in
`tmp/ckb-upgrade-src/.agents/skills/`
- `.agents/modules/<name>/**` for every optional module present upstream
(see `ckb-module`). Upgrade the module *payload* freely — it is inert
template content. But **never delete a skill under `.agents/skills/`
just because it is absent upstream**: it may be a module-installed copy
that this KB deliberately enabled. Check `ckb.yaml` before treating any
skill as removed upstream. When an installed module's payload changes,
say so and suggest reinstalling it — the installed copies are now stale.
- The base ignore rules in `.gitignore` (`libs/`, `linked/`, `tmp/`,
regenerated `outputs/` subfolders, `.env`, etc.) — merged, never
replaced wholesale (see Step 6)
For every path in that list, diff the local copy against the scratch
clone's copy:
- **Doesn't exist locally, exists upstream** (e.g. a skill or doc added
since this KB was created) — no local content at risk; stage it as an
addition.
- **Identical** — nothing to do.
- **Differs** — this needs care. The difference might be a template
improvement worth taking, or it might be a deliberate local
customization — nothing here can tell those apart automatically,
especially for `AGENTS.md`, which the [manual](../../../docs/MANUAL.md)
explicitly tells users they're free to edit. Never silently overwrite;
queue it for Step 5.
### Step 5 — Present findings and get decisions
Present whichever of the two findings apply (one or both):
```markdown
## Upgrade available
### Template: v<local> → v<remote> (only if template_upgrade_available)
**New files** (nothing local to lose, will be added):
- <path>
- ...
**Changed files** (local content differs from the template):
- <path> — <one-line summary of the change, e.g. "Step 7 reworded" or
"trigger phrases extended">
- ...
### Wiki content schema: v<local-or-"unversioned"> → v<remote> (only if wiki_schema_upgrade_available)
Your `wiki/` content was built against an older (or no) schema version.
This doesn't stop anything from working, but some pages may be missing
frontmatter fields the current schema expects (`tldr`, `confidence`,
`quality`, `retention`, etc.), or missing structural pieces (e.g. no
`wiki/graph/` folder yet). Nothing factual would be rewritten — only
structure and metadata would be backfilled.
```
For each **changed template file**, ask via `AskUserQuestion` — batched
into one question if the user wants to move fast, or one at a time if
they'd rather review each — with options **"Take the template version"**,
**"Keep my local version"**, or **"Show me the full diff first."**
Default recommendation for template files:
- Skill files (`.agents/skills/**`), `LICENSE`, `VERSION` — lean toward
"take the template version." These are rarely hand-edited and are
exactly the kind of thing that should stay in sync.
- `AGENTS.md`, `README*`, `MANUAL*` — don't default silently. Say plainly
that local customization is common in these files and ask explicitly
rather than nudging toward either choice.
If `wiki_schema_upgrade_available`, ask a **separate**, explicit question
— don't fold it into the template-file batch, since it's a different kind
of decision with different risk (it touches `wiki/`, which this skill
otherwise never does):
> "Would you like me to also upgrade all wiki-related folders and data to
> the new standard? I'll review every page under `wiki/`, add any missing
> scaffold files, and backfill missing frontmatter fields — without
> rewriting any of the actual knowledge you've collected. For a large
> wiki this can take a while. Options: **Yes, rebuild to the new
> standard** / **No, just the template files** / **Show me what's
> missing first, then decide.**"
These two decisions are independent — a user can accept the template
upgrade and decline the wiki migration, or vice versa.
### Step 6 — Apply the accepted template-layer changes
Only if `template_upgrade_available` and at least one item was accepted:
- Copy accepted **new** and **changed** files from `tmp/ckb-upgrade-src/`
over their local counterparts.
- For `.gitignore`, don't overwrite it — append any upstream base rules
not already present locally (line-by-line comparison), preserving every
existing local line, including custom ones the user added for their own
project.
- If `CLAUDE.md` isn't a symlink to `AGENTS.md` (or is missing), recreate
it as one.
- Create any `raw/` folder the new directory contract lists but the KB lacks,
such as `raw/retractions/` (template 1.17.0), with an empty `.gitadd`. This
is scaffold, not content: never move or touch files already in `raw/`.
- If the KB has no `templates/` folder at all, create it with upstream's
`templates/README.md` and `templates/status-report.md` (template 1.18.0).
If the folder exists, leave every file in it alone, those two included:
document templates are the user's content, not the template layer.
- If the KB has no `ABOUT.md`, create it from upstream's scaffold with
`last_updated` set to today (template 1.21.0), and tell the user it is
theirs to fill in. An existing `ABOUT.md` is never diffed or touched.
- Leave every path outside the template layer completely untouched at
this step — `wiki/` changes, if any, happen only in Step 7.
- Update local `VERSION` to the template's new version last, only once
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:`,
`conversations:` and `routines:` exactly as found — those belong to
`ckb-module`, `ckb-add-conversation` and `ckb-routine`. 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)
This is the one part of this skill that writes under `wiki/` — it only
ever runs after the explicit confirmation from Step 5, never
automatically, and never partially without saying so. Warn the user
before starting if `wiki/entities/` has many pages, since this is a
per-page pass, not instant.
**a. Fill structural gaps first.** Check for the standard `wiki/` scaffold
pieces and create any that are missing, using the same empty-template
shape `ckb-init` writes for a fresh KB (never overwrite one that already
exists, even if it looks sparse):
- `wiki/entities/index.md`, `wiki/graph/index.md`, `wiki/graph/edges.json`
- `wiki/error-book.md`, `wiki/overview.md`
- Any subdirectory under `wiki/entities/`-style groupings that's missing
its own `index.md` per the Recursive Index & Log Convention.
**b. Backfill frontmatter on every existing page**, per the schema in
`AGENTS.md` page schema. For each `.md` file under `wiki/` (excluding the reserved
`index.md`/`log.md`/`error-book.md`), check its frontmatter against the
schema and fix only what's missing — never touch a field that's already
present, and never alter the page's body text:
- **Missing `type`** — infer conservatively from the page's own content
and location (e.g. a page under `wiki/entities/` describing a person,
project, library, or concept). Don't silently guess: batch every
inferred `type` into one list and confirm it with the user before
writing, since `type` is the field lint treats as most load-bearing.
- **Missing `tldr`** — synthesize a one-sentence summary from the page's
actual content. Low-risk, mechanical — no need to ask per-page.
- **Missing `confidence` / `quality`** — don't invent a placeholder
number. Re-read the page fresh and score it the same way `ckb-ingest`
would score a newly-synthesized page (source corroboration for
confidence, structure/citations/consistency for quality).
- **Missing `last_updated`** — set to today, and note in the log entry
(Step 7d) that the date reflects this migration, not original
authorship.
- **Missing `freshness_window_days` / `retention`** — set a reasonable
default appropriate to the page's apparent topic, the same judgment call
`ckb-ingest` makes for newly-written pages.
- **Missing dual-linking** on an existing cross-reference (only a
`[[wikilink]]` where a `[markdown](path.md)` link should also exist, or
vice versa) — add the missing form. Don't invent new cross-references
that weren't already there in some form.
**b2. Schema 1.4 → 1.5: evidence sections.** Schema 1.5 added the reserved
body sections (`## Sources`, `## Crux`, `## Notes`), the
`source_fingerprint`/`source_checked` frontmatter fields, and the completed
edge vocabulary in `wiki/graph/index.md`. Migrating a 1.4 wiki:
- **`wiki/graph/index.md`** — replace its vocabulary section with the
template's table verbatim. Existing edges stay valid; 1.5 only added
verbs (`part_of`, `produces`, `configures`, `validates`, `implements`),
it removed none.
- **`## Sources` without fingerprints** — backfill a digest for every cited
file that still exists (`sha256sum <file> | cut -c1-8`), with
`source_checked` set to today. Where the cited file is **gone**, do not
quietly drop the bullet: leave it and flag the page, because a page whose
evidence has vanished is a finding the migration surfaced, not one it
should bury.
- **`## Crux`** — do **not** manufacture one. A Crux is verbatim source
text, and inventing quotes during a migration is precisely the failure
the section exists to make impossible. Pages gain a Crux when they are
next ingested or deliberately re-grounded, and a 1.5 page with no Crux is
fully conformant.
- **`## Notes`** — add an empty one to generated pages under
`libs/<name>/` so the protected affordance exists. Elsewhere, leave it
absent.
These are additive: a 1.4 page with none of them is valid 1.5, so this step
never blocks the version bump. Backfilling fingerprints is worth doing in
the same pass anyway, since it is mechanical and it is what makes `ckb-lint`
check 12 meaningful from that point on.
**c. Bump `wiki/index.md`'s `kb_schema_version`** to the template's
current value, once every page has been checked.
**d. Log every touched page** in `wiki/log.md`, per Rule B's format — this
is the one legitimate exception to this skill's normal "never writes to
`wiki/log.md`" behavior. Use the action `UPDATE (schema migration)`, the
description "Backfilled missing `tldr`, `confidence`, `retention` during
schema migration to v<new>. No content changes." and the source
`ckb-upgrade schema migration`, so each entry says clearly that it was a
backfill, not new knowledge.
**e. Suggest running "Lint" afterward** as an independent verification
pass, rather than re-implementing lint's own conformance checks here —
the two skills should agree on what "conformant" means.
### Step 8 — Clean up and report
```bash
rm -rf tmp/ckb-upgrade-src
```
Report a summary covering whichever tracks actually ran:
```markdown
## Upgrade report
**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">
**Updated:** <N> file(s) — <paths, or "none">
**Kept local (declined template version):** <N> file(s) — <paths, or "none">
**Wiki content schema:** v<old-or-"unversioned"> → v<new> (or "already current" / "declined")
**Scaffold files added:** <paths, or "none">
**Pages backfilled:** <N> — <paths, or "none">
**Types inferred and confirmed:** <list, or "none">
```
If anything actually changed, close with the same reminder pattern as
`ckb-ingest`/`ckb-lint`: review the diff, then say "sync changes" to
commit and push it to *this KB's own* `origin` — not the template repo
just checked against, which is typically a different remote for any KB
other than the template project itself.
## Edge cases
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
run hits something the steps above don't cover; don't load it otherwise.