- Skills: descriptions cut to routing-hint length (1925w -> 840w), Trigger
phrases removed, Purpose collapsed, Edge cases moved to references/.
- Rule B names the decisions-log exception; "Sync the wiki" trigger dropped;
reserved sections "Four" -> "Three"; directory contract adds ckb.yaml,
docs/, tests/.
- MANUAL/CHANGELOG/OPENSPEC (EN+PL) moved to docs/; template ADRs D-0001 and
D-0002 restored from 0c06cb6 into docs/decisions/; referrers repointed.
- ckb-retrieve: rank fusion moved into scripts/retrieve_candidates.py;
Purpose states the one write it owns (query-gaps).
- tests/: fixture KB, golden JSON, smoke.sh.
- Scaffold: overview.md describes content not schema; graph/index.md names
base skills only; query-gaps.md loses its self-rotting freshness window.
- README/MANUAL/OPENSPEC/CHANGELOG ghost-writer pass in both languages.
- VERSION 1.9.0 -> 1.10.0.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
75 lines
4.4 KiB
Markdown
75 lines
4.4 KiB
Markdown
# ckb-upgrade — edge cases
|
|
|
|
Reference material for the `ckb-upgrade` skill. Read when a
|
|
run hits an unusual situation the main steps don't cover.
|
|
|
|
- **`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
|
|
template version counts as newer. Mention in the report that this KB
|
|
predates version tracking.
|
|
- **No `kb_schema_version` in local `wiki/index.md` at all** — treat as
|
|
unversioned/behind by default (Step 3), and say so plainly in the
|
|
report rather than silently treating it as "version 0.0."
|
|
- **This KB's own `origin` *is* the template repo itself** (i.e. this is
|
|
the template project's own working copy) — the checks still work
|
|
(they'll usually report "already up to date" on both fronts since
|
|
you're comparing against yourself), but note this in the report so it's
|
|
clear why an "upgrade" against your own remote looks like a no-op.
|
|
- **Network/auth failure cloning the template repo** — report the raw
|
|
error, make no changes on either track, and clean up any partial
|
|
scratch clone.
|
|
- **A "changed" template file's difference looks trivial** — still
|
|
surface it for a decision; don't invent a heuristic for "safe to
|
|
auto-take," since the cost of a wrong guess (silently discarding a real
|
|
customization) is worse than one extra question.
|
|
- **User declines every changed template file** — still add any pure-new
|
|
files (nothing lost by doing so) and bump `VERSION`, since the KB
|
|
genuinely is now aware it's on the newer template version even if it
|
|
kept its own customized copies of specific files.
|
|
- **User confirms the wiki migration but the wiki is very large** — process
|
|
it in batches with progress updates rather than promising instant
|
|
completion; it's fine for this to be the longest-running part of the
|
|
skill.
|
|
- **User declines the wiki migration** — still bump nothing under `wiki/`,
|
|
including `kb_schema_version` — leave it exactly as found, so a future
|
|
run of this skill still detects it as behind rather than silently
|
|
considering it handled.
|
|
- **A page's inferred `type` is ambiguous even after inspection** — ask
|
|
the user directly for that page rather than guessing between two
|
|
plausible types; don't let one uncertain page block backfilling the
|
|
rest.
|
|
- **Uncommitted local changes already present before running this skill**
|
|
— proceed anyway (nothing here is destructive; every change lands as an
|
|
ordinary working-tree diff, reversible with `git checkout`), but mention
|
|
in the report that there was pre-existing uncommitted work, so the user
|
|
knows the diff they're about to review isn't only from this upgrade.
|
|
- **A skill folder was renamed or removed upstream** — don't delete the
|
|
corresponding local folder automatically (it might still be in active
|
|
use, or further customized locally); mention it in the report as
|
|
"removed upstream, left in place locally" and let the user decide
|
|
separately.
|
|
|
|
---
|
|
|
|
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
|
|
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
|