441 lines
22 KiB
Markdown
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.
|