cc-update

CC Update — start from the canonical source, don't rediscover

Genesis's Claude Code update process is fully standardized. This skill exists so a session executes that process instead of re-deriving it (grep archaeology every time). If you find yourself hunting for where the pin lives or how the host updates, STOP and read the doc.

Authoritative source — read these FIRST

• docs/reference/cc-compatibility.md → §Updating Claude Code (host + container) (the exact steps) and §CC Update Evaluation Checklist (the 8-lens impact eval).
• The pin is the single source of truth: CC_VERSION (+ NODE_MAJOR) in scripts/lib/cc_version.sh.

The process in one breath — step numbers MATCH §Updating Claude Code in the doc

Deliberately the same numbering in both files: "step 4" means the same thing in each. The doc is authoritative for detail; this is the one-breath version. If a number here disagrees with the doc, the doc wins — and that disagreement is a bug worth fixing rather than working around.

Pick the target before anything else. npm view @anthropic-ai/claude-code version gives latest; use an explicit older version if you are deliberately not chasing latest. Every step below is defined over (pinned, target], so nothing can begin until target is fixed — and re-picking it later restarts the procedure (step 5).

⛔ GATE — FULL CHANGELOG READ. MANDATORY, NO EXCEPTIONS. (part of step 1, before any triage)

Read EVERY release entry in (pinned, target] IN FULL before step 1's triage. No pin bump proceeds without this.

Fetch it fresh — nothing in Genesis maintains a changelog cache: curl -fsSL https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md -o ~/tmp/cc_changelog.md (mkdir -p ~/tmp first — curl -f will not create it.) That path is a scratch copy, NOT a recon-pulled cache. Before reading, confirm the file CONTAINS a ## <target> heading (grep -c '^## <target>$') — a stale copy fails exactly that, which is how it would otherwise pass unnoticed while the whole new range goes unread. Do NOT also require the FIRST heading to equal the target: under the mid-soak rule you may deliberately finish on a target latest has already passed, and equality could never be satisfied by any re-fetch.

If the target released hours ago its heading may not be in main's CHANGELOG.md yet — the one case no re-fetch fixes. Cover the tail from the GitHub release bodies, but enumerate what is missing first: gh release view reads ONE release, so gh release view v<target> alone under-reads whenever more than one release in (pinned, target] is absent, and the gate closes over releases nobody read. gh release list --repo anthropics/claude-code --limit 60 --json tagName -q '.[].tagName', keep the tags in range with no ## <version> heading in the file, then gh release view <tag> for EACH. Say in the durable row which source covered which releases.

Scale: (2.1.218, 2.1.246] measured 25 releases / ~88KB. The load-bearing item can sit anywhere, including deep inside the newest release.

The analyzer is a TRIAGE SUMMARY, never a substitute. It prioritises; it does not discharge the gate.

Record it as a DURABLE row, not a chat line — opened BEFORE, closed AFTER. session_ledger_add always creates an open row, and its own return message says it "will re-inject into every post-compaction window until closed" (session_charter_tools.py::_impl_session_ledger_add). So a row added after declaring the gate done is a permanent false open item in charter counts, compaction injections and repo-pulse matching. Open it, do the read, then close it:

resp = session_ledger_add(session_id=<this session>,
                          text="CC changelog gate: reading (2.1.X, 2.1.Y] from <source>")
# resp is a DICT — the id is resp["id"], not resp itself.
# session_id is required, but a missing one returns {"error": …} rather than raising:
# CHECK the response, or you will proceed believing a row exists that does not.
…the read…
session_ledger_update(item_id=resp["id"], status="done",
                      evidence="read in full from <source>, <date>; <N> releases covered")

The row is session-scoped, so across a 2–3 day soak the session that opens the PR is not the one that ran the gate. What makes the gate checkable later is the carry-over: a CC-Gate-Changelog: trailer in the PR body plus the §Version History clause — see §Gate receipts in docs/reference/cc-compatibility.md for both receipts and what their absence means. The pin-receipt check blocks a pin-forward PR that is missing either — at MERGE time, where the body that actually merges is the one read. The cc-pin-receipts CI job runs the same checker advisorily and never fails a build. For rows added from 2026-08-26 onward, a Version-History row with no "changelog read" clause means the gate was not run — treat that as blocking at merge.

Delegation is allowed — with the SAME context and rigor, never a naive "summarize this." Brief the sub-agent with §Delegating the full changelog read below, then adversarially spot-check its load-bearing findings against ground truth. A delegated review is not a rubber-stamp.

Origin (2026-08-26). A session re-targeted 245→246 off the headline delta and let the changelog-reading analyzer stand in for actually reading the changelog. The cause was mechanical, not just human: on main the analyzer fetches only the newest 5 GitHub releases, keeps just the new version's body, and truncates it at 1000 chars — v2.1.246's body is ~9.3KB, so it saw the first ~8 of ~60 bullets and structurally could not surface the rest. The later full read found real Genesis-relevant 246 items the triage had missed: subagent maxTurns now returning partial output, -p --continue/--resume plan-mode resume, and a --strict-mcp-config startup-hang fix that lands directly on Guardian Diagnosis.

1. Evaluate — intake, the ⛔ GATE above, then triage. Intake, never from scratch: memory_recall + docs/reference/cc-compatibility.md §Known Issues / §Version History + npm view @anthropic-ai/claude-code@<target> engines.node + a quick community sweep (Reddit/forums) for regressions the changelog omits. Triage: recon_cc_update_check(old, new) MCP (backed by src/genesis/recon/cc_update_analyzer.py). Know its real coverage: today it fetches only the newest 5 GitHub releases, matches the target version's tag, and truncates that body at 1000 chars — so on a multi-release jump it sees a fraction of ONE release, or NOTHING at all once the TARGET's own tag ages out of the newest 5. That is likely mid-soak: step 5 holds a candidate for 2-3 days while CC ships ~daily. When that happens the LLM is never called at all — _fetch_changelog returns "", and analyze gates the LLM path on if self._router and changelog, so it falls through to a hand-built dict with details="Changelog not available". The confident-looking informational verdict in that case is a deterministic fallback, not a judgement — do not read it as "the analyzer looked and found nothing". Two traps in reading that verdict. (a) _fetch_changelog returns "" from five distinct paths — a non-zero gh exit, a timeout, a bare except, a non-list payload, and the tag-not-in-newest-5 case. An expired gh auth produces a byte-identical details="Changelog not available", so confirm gh auth status before concluding the tag aged out. (b) There is a SECOND non-judgement path: when the LLM was called and failed, the keyword heuristic also returns informational with real changelog text. Tell them apart by the " (LLM analysis unavailable)" suffix on summary — without that suffix and with a non-empty details, the verdict is a genuine LLM read. (A whole-(old, new] map-reduce rewrite exists on an unmerged branch — unmerged as of 2026-08-26; grep the file before relying on it. It would still omit the oldest chunks on a very large range, so the GATE does not retire either way.) Triage every hooks / MCP / CLI-flag / subagent / permissions delta. Rule: a changelog claim that "we depend on X" only gates the bump if verified against LIVE usage — the TodoWrite lesson: a removed feature Genesis measured 0 uses of is hygiene, not a blocker.
   • Take the PRE-align model-alias sample HERE, in step 1. It belongs to the first never skippable step, not to step 2 — step 2 has a legitimate skip condition, and a sample nested under it silently disappears exactly when that skip fires, leaving the step-4 "after" reading with nothing to compare against. It cannot move later either: step 3 replaces the CLI, so this is the last point at which the old binary is still installed. See §Model-alias drift below for the invocation; the post-align half is step 4.
2. Deploy current main FIRST — scripts/update.sh as a background task, BEFORE aligning the candidate, so the soak runs on current code. Otherwise step 8 lands accumulated Genesis change AND the CC bump together and you cannot attribute a regression to either. Checkable skip condition — three parts, all required: git fetch origin first (an unfetched origin/main is stale and produces a false "already current"); take the newest update_history_recent row whose status == "success" — the tool deliberately returns every attempt including failure and rolled_back (update_history.py:98-113), and a failed attempt's later timestamp otherwise reads as evidence of a deployment that never happened; then confirm that row's new_commit is an ancestor-or-equal of the fetched origin/main head — mechanically, git merge-base --is-ancestor "$(git rev-parse origin/main)" <new_commit> exits 0. Skip only if all three hold.
3. Align the CONTAINER ONLY to the candidate.

   source scripts/lib/cc_version.sh   # NOTE: this sets CC_VERSION to the repo PIN
   CC_VERSION=<candidate>             # standalone assignment, AFTER the source
   cc_ensure_local
   cc_shadow_scan
   

   ⚠️ Never write CC_VERSION=<candidate> cc_ensure_local and then a bare cc_shadow_scan. An assignment prefix on a function call does not persist past that call, so the scan would run on the OLD pin while the container is on the candidate — and if any copy sits at the old pin it crowns that one canonical and deletes the freshly-installed candidate (cc_version.sh:251). Full rationale: doc §Updating step 3. claude --version is NOT sufficient here: it spawns a fresh child, which reads the new on-disk binary and truthfully reports the candidate while the session asking the question is still executing the old one. Run scripts/check_cc_running_versions.sh instead — it compares each live process's actual mapped binary against the one on disk. Check the Node floor first — npm view @anthropic-ai/claude-code@<candidate> engines.node vs node -v. If it rises above the container's Node, STOP: no container-side Node transition tool exists today (install.sh:473-477 hardcodes >= 20 and never reads NODE_MAJOR), and a failed align is not a clean no-op — npm install -g has already replaced the working CC before the verify runs.
4. Validate the CANDIDATE against candidate-shaped expectations, not step 9's. During the soak the correct state is container == candidate, host == old pin — step 9 requires BOTH to equal the pin, which cannot hold yet. Run the critical paths, the doc's §Known Issues, and each behavior the impact eval flagged; any Guardian-path check exercises the host's old binary, so candidate-specific Guardian behavior needs a container-side exercise.
   • Run scripts/check_cc_running_versions.sh BEFORE validating, not just before the soak. Same trap as step 3 and step 5: validation performed inside a session still mapped to the replaced binary is evidence about the OLD release, and it is the evidence the whole changelog gate feeds into. The check belongs at every point that produces evidence about the candidate — steps 3, 4, 5 and 9 — not only at the soak boundary.
   • Take the POST-align model-alias sample here and compare it against the pre-align one from step 2 — nothing else in the system will catch an alias remap. See §Model-alias drift below for the invocation and for which modelUsage entry to read (it is not the first one).
5. Soak 2–3 days under real use — but the clock does not start until every interactive session is actually ON the candidate. A long-running CC process keeps its original binary mapping until it restarts; npm replaces the package underneath it. So relaunch the foreground sessions, then prove it rather than assuming it:

   scripts/check_cc_running_versions.sh    # exit 0 required before the clock starts
   

   Re-run it at soak END too — sessions started mid-soak are fine, but one that predates the align and was never relaunched has been contributing evidence about the OLD release the whole time. Origin (measured on a live install): a soak was declared started and ran its full length with a majority of live CC processes — and most interactive sessions — still executing the replaced predecessor. cc_shadow_scan was clean throughout (it scans on-disk copies, not running processes) and claude --version reported the candidate the whole time, because it spawns a fresh child. Nothing in the procedure would have caught it.