update

Carried near-verbatim from donor skills/update/ (Task 7.3) — the migration state machine's snapshot/restore/version-compare substrate. Renamed identifiers only: SF_WIKI_ROOT → REN_WIKI_ROOT, SF_SNAPSHOT_MODE → REN_SNAPSHOT_MODE, ~/.startup-framework/ → ~/.renos/.

Scripts (carried, unchanged behavior)

• scripts/snapshot.sh <from-version> — copies the wiki to ~/.claude/plugins/data/renos/wiki-snapshots/v\<from\>-pre-update-\<ISO8601\>/ (snapshot root overridable via REN_SNAPSHOT_ROOT; never derived from CLAUDE_PLUGIN_DATA — issue #34), prunes beyond CLAUDE_PLUGIN_OPTION_SNAPSHOTRETAIN (default 3), logs the snapshot to wiki/log.md.
• scripts/restore.sh {--list|--whole <snap>|--page <snap> <rel>} — lists snapshots, restores the whole wiki (stashing the pre-restore state first), or restores a single page.
• scripts/prune-snapshots.sh [<N>] [--dry-run] — retention enforcement for both normal snapshots and STASH-broken-* dirs (created by restore.sh --whole).
• scripts/version-compare.sh <A> <B> / --bump <A> <B> — strict semver comparison + bump classification (patch/minor/major/downgrade/equal/prerelease). No CC-marketplace dependency; the framework owns semver semantics since the marketplace treats version as an opaque string.

When to use this skill

• Friend invokes /ren:update to check for and apply a framework version bump
• Friend invokes /ren:update --dry-run to preview the migration plan with zero writes
• Friend invokes /ren:update --restore-snapshot to interactively restore from a prior snapshot

What this skill does NOT do

• Decide WHICH migrations exist or their chain order — that's skills/wiki-migration's registry (this skill calls into it, doesn't own it).
• Auto-rollback on new post-update doctor issues. The snapshot is retained and named; the human decides whether to restore.
• Force-push or touch the backup remote. That's skills/backup's scope entirely.

0.3 update notes

• queue-governance 2→3 (Task 10): a friend upgrading past 0.3 has queue entries left pending for the OLD reason (0.2 gated every write) rather than the new one (v2.2's instruction-plane/contradiction holds only). Run migrations/queue-governance-2-to-3/migrate.py once as a post-update step after the version bump lands — it is NOT part of the skills/wiki-migration page-type chain (it walks queue state under state_dir()/queue/, not wiki pages), so /ren:doctor's schema-drift check does not surface it; invoke it directly. --check previews what would be released with zero writes. Idempotent — safe to (re-)run even if a friend already updated once without it. See that migration's README.md for the shape-decision rationale.

0.5.1 update notes

• trust-backfill-1 (Task 10a): a friend upgrading from before 0.5.1 has pre-0.5.1 wiki pages with no ren_trust frontmatter (the trust taxonomy 0.5.1 Task 6 started stamping at the single write door). Run migrations/trust-backfill-1/migrate.py once as a post-update step after the version bump lands, gated by skills.update.lib.should_run_trust_backfill( <old-version>, <new-version>) — True when the update crosses the 0.5.1 boundary. Like queue-governance-2-to-3, this is NOT part of the skills/wiki-migration page-type chain (it walks the whole wiki tree, not a single page type keyed by schema_version) — see skills/wiki-migration/schemas.json's global_migrations note and that migration's README.md for the shape-decision rationale. --check previews what would be stamped with zero writes. Idempotent — safe to (re-)run even if a friend already updated once without it.

0.6.2 update notes

• project-knowledge-1 (issue #20): a friend upgrading from before 0.6.2 may have flat .md pages directly under projects/<slug>/ (pre-0.6.2 ingest had no sanctioned durable subtree). Run migrations/project-knowledge-1/migrate.py once as a post-update step after the version bump lands, gated by skills.update.lib.should_run_project_knowledge_1(<old-version>, <new-version>) — True when the update crosses the 0.6.2 boundary. Standalone global migration (walks whole projects/<slug>/ directories, not a schema_version-keyed page type) — see skills/wiki-migration/schemas.json's global_migrations note and that migration's README.md. Dry-run is the DEFAULT (--apply writes); show the friend the dry-run plan before applying. Idempotent — safe to (re-)run. It also reports any projects/<slug>/ missing a schema.md; relocating pages is the script's job, but organizing them into a taxonomy (nested knowledge/ subtrees, hubs, schema.md) is model-work — offer the friend a follow-up session per project (or a re-run of /ren:ingest-project, which now produces the hierarchical shape natively).

0.6.3 update notes

• foreign-remint-1 (issue #22): a friend upgrading from before 0.6.3 may have ingest-drafted knowledge pages mis-stamped ren_trust: "foreign" (pre-#22 trust_class minted "foreign" for every producer="ingest" write, which held the ingested project's L2 map out of wake-up unconditionally). Run migrations/foreign-remint-1/migrate.py once as a post-update step after the version bump lands, gated by skills.update.lib.should_run_foreign_remint_1(<old-version>, <new-version>) — True when the update crosses the 0.6.3 boundary. Standalone global migration (walks the whole wiki tree, restamps only foreign pages with a known non-human ren_writer; quarantine banners are untouched) — see skills/wiki-migration/schemas.json's global_migrations note and that migration's README.md. --check previews what would be reminted with zero writes. Idempotent — safe to (re-)run even if a friend already updated once without it.

0.7.0 update notes

• l2-map-1-to-2 (issue #53): a friend upgrading from before 0.7.0 has L2 pointer-maps still in schema 1 — arrow-form wiki pointers (- [Topic] → path (write_id)) instead of Obsidian-native markdown links (- [Topic](path) (write_id)). Unlike the standalone global migrations above, this one IS part of skills/wiki-migration's ordinary page-type chain (l2-map is a registered page type in skills/wiki-migration/schemas.json, currently at schema 2), so it's driven the same way /ren:doctor's check_schema_versions discovers pending work, not a one-off script invoked by hand. Walk it as follows, under the update flow's existing pre-migration snapshot (REN_SNAPSHOT_DIR already pointed at that run's wiki-snapshots/v<from>-pre-update-<ISO8601>/):
  1. Enumerate wiki pages via wiki_root.rglob("*.md"), skipping projects/<slug>/raw/ (write-once source material — never a migration target; lib.ren_paths.in_project_raw is the existing predicate, see skills/doctor/lib/check_schema_versions for the same walk).
  2. Read each page's frontmatter type. The master wiki/index.md is type: l2-map too — it is NOT special-cased out of this walk, per- project maps (projects/<slug>/map.md) and the master index are migrated the same way.
  3. For pages whose type is l2-map, read schema_version; an absent value means the page predates schema-stamping (issue #20) — treat it as 1, not as "skip me".
  4. Compute migration_chain("l2-map", <version>) — via importlib.import_module("skills.wiki-migration.lib"), same as /ren:doctor's check_schema_versions — for that page. A non-empty chain today is always exactly ["l2-map-1-to-2"].
  5. For each pending page, run run_migration(Path("migrations/l2-map-1-to-2"), <page_path>, wiki_root, snapshot_dir) (same skills.wiki-migration.lib import) — same primitive /ren:doctor verifies against, same SF_*/REN_* env-mapping shim. Inspect the returned MigrationRunResult: skipped=True (stdout carried SKIP) means transform.py itself declined (wrong type, no frontmatter, or already at schema 2 — see migrations/l2-map-1-to-2/README.md); a non-zero returncode with skipped=False is a genuine transform failure (page left untouched, rolled back from the snapshot like any other failed page).
  6. Verify each migrated page with verify_page( Path("migrations/l2-map-1-to-2/verify.json"), <page_path>) (same import) before counting it as applied.
  7. Show the friend the per-page diff summary, per this skill's usual diff-approval contract, before the migrated content is treated as final. Idempotent — re-running is always safe: migrate.sh (via transform.py) SKIPs any page already at schema_version: 2, scoped to the frontmatter block only (a body line that happens to read schema_version: 2 cannot false-SKIP a stale page). See migrations/l2-map-1-to-2/README.md for the full transform contract.
• Global migration: folder-note-hubs-1. Gate: should_run_folder_note_hubs_1() from skills.update.lib. If true — show the friend the pending rename list (the gate's paths), get approval (this is a MAJOR-classified structural change), then run UV_PROJECT_ENVIRONMENT="$HOME/.renos/.envs/<version>" uv run python migrations/folder-note-hubs-1/migrate.py followed by UV_PROJECT_ENVIRONMENT="$HOME/.renos/.envs/<version>" uv run python migrations/folder-note-hubs-1/verify.py — these also run from the versioned plugin cache dir, so redirect uv's project environment the same way (#40; ren_paths.envs_dir()) rather than letting a .venv land inside that immutable cache dir. On verify success, call skills.install.lib.write_default_graph_config() (the new Obsidian tier view written during the migration). On verify failure: stop, show the FAIL lines, offer whole-wiki restore via skills/update/scripts/restore.sh --whole <snapshot> (the snapshot taken at the start of this update). Never proceed to the closing summary with a failed verify.

0.8.0 update notes

• distiller-watermark seed (spec §3.5): a friend upgrading from before 0.8.0 has no distiller watermark yet. Initialize the watermark as a post-update step after the version bump lands, gated by skills.update.lib.should_run_distiller_watermark_seed(<old-version>, <new-version>) — True when the update crosses the 0.8.0 boundary. Call skills.distill.lib.write_watermark("2026-08-03T00:00:00Z") ONLY if skills.distill.lib.watermark_path() doesn't exist yet (idempotent — safe to (re-)run even if a friend already updated once without it). See docs/superpowers/specs/2026-08-18-knowledge-flows-train-design.md's §3.5 for the backlog-rescue acceptance run.

0.8.1 update notes

• frontmatter-type-1 (issues #74, #77): a friend upgrading from before 0.8.1 has wiki pages created before the write door derived a frontmatter type: from the page path, so those pages carry none — and every one of them keeps tripping wiki-health's missing-frontmatter-type rule, filing a fresh suggestion per page per sweep. Run migrations/frontmatter-type-1/migrate.py once as a post-update step after the version bump lands, gated by skills.update.lib.should_run_frontmatter_type_1(<old-version>, <new-version>) — True when the update crosses the 0.8.1 boundary. Standalone global migration (walks the whole wiki tree calling lib.memory.page_types.ensure_type, not a schema_version-keyed page type) — see skills/wiki-migration/schemas.json's global_migrations note and that migration's README.md. --check previews what would be stamped with zero writes; show the friend that preview before applying. Idempotent — safe to (re-)run even if a friend already updated once without it. It never overrides an existing type: (invariant I1) and leaves any path the derivation table doesn't recognize untouched (I2).

  Run it before the friend's next /ren:distill or /ren:wrap. Until a page is typed, a re-propose of unchanged content against it no longer normalizes equal — the proposal carries type: and the page on disk does not — so each untyped page costs one extra self-healing write and a distiller WRITE_CAP slot. Running the migration first avoids that burst entirely.

Overlap note: snapshot substrate vs. Task 1.2's per-write snapshots

lib/memory/snapshot.py (Task 1.2, G9) is a DIFFERENT snapshot mechanism: per-write-id, page-granularity snapshots for the write-safety substrate (revert a single memory write in one step). scripts/snapshot.sh here is whole-wiki, version-bump-granularity, for migration rollback. They serve genuinely different purposes at different granularities — this skill's carried snapshot logic is NOT rewritten to unify with Task 1.2's substrate; that unification (if it's ever worth doing) is a 0.3-scoped ADR decision, not something to improvise here. Noted per the task brief's explicit instruction not to rewrite working carried code.

Closing steps (after re-verify)

• Re-render project CLAUDE.md blocks — call skills.update.lib.rerender_all_project_claude_md() after migrations complete. The queue's post-apply hook and revert's post-revert hook (lib.adapter.claude_md.rerender_for_page) each re-render only the ONE project touched by a single instructions.md write; an update can change the block's FORMAT (adapter changes, doctrine index refresh) for every project at once without touching instructions.md at all — this closes that spec §3(b) gap (#64). Best-effort per slug — the returned {slug: "ok" | "error: <msg>"} dict is informational, never a gate. An Unknown return means the project registry could not be read: say so and name .reason, rather than reporting zero projects re-rendered.
• Re-render the global CLAUDE.md block — call lib.adapter.claude_md.write_global_claude_md(). The global block's doctrine index holds absolute paths pinned to the running plugin version (.../cache/ren-os/ren/<version>/doctrine/*.md), so a version bump leaves every one of them naming the PREVIOUS version — live only until that cache dir is GC'd, then dead links in a file injected into every session. The project-tier call above cannot cover this: it iterates projects with an instructions.md, and the global block belongs to no project. Same shape as #64 one tier up. Best-effort like its project-tier sibling — report the returned status (added/updated/unchanged/conflict), never gate the update on it. A conflict means torn markers in the friend's own CLAUDE.md: say so and leave the file untouched.
• Report what changed — build the "what changed in your RenOS" digest: skills.update.lib.changelog_digest(<old-version>, <new-version>, <plugin-root>/CHANGELOG.md) (plugin root = $CLAUDE_PLUGIN_ROOT, falling back to the framework root). Print it verbatim under a "What changed in your RenOS" heading. "" means the range is genuinely empty — say the update landed with no changelog entries in range. An Unknown means the digest could not be produced at all: say so, name .reason, and point at CHANGELOG.md. The digest is a courtesy, never a gate — but a courtesy that cannot run should not read as a courtesy that found nothing.
• Offer new companions — call lib.companions.pending_offers(). If non-empty, say: "This update recommends companions you haven't decided on:" and list each (title — pitch — install hint). Same rules as install Stage 6: accepted tools are installed for them and recorded (record_choice(cid, "accepted")); accepted plugins get the hint + a restart note; declines are recorded and never re-asked; no answer records nothing. Nothing installs without an explicit yes in chat.
• Re-warm the fast-path interpreter — call skills.update.lib.rewarm_interpreter(). warm_environment() runs at install and never at update, so the recorded interpreter kept naming the cache dir the update just superseded; the wake-up hook then falls through to cold uv every session, silently, because it fails safe. This also deletes the pre-0.8.3 record at state_dir()/interpreter.json — that location is inside the wiki and therefore inside /ren:backup's push, so it carried one machine's absolute paths to every machine restoring the wiki. The record now lives in ren_paths.machine_state_dir(), which is never backed up; that is what retired the platform.node() comparison guarding it (macOS returns an IP-derived node name on some networks, so the guard rejected the machine's own valid record after any network change). Best-effort, never a gate — report the returned status.
• GC stale uv envs — call skills.update.lib.gc_stale_envs(). It removes framework_root()/.envs/<v> dirs whose version is no longer in the plugin cache (#40 — the versions this same update just made stale) and returns the removed version list; report it if non-empty, silent otherwise. If it returns Unknown, say the GC did not run and name .reason — silence there would report a sweep that never happened as a clean one. Best-effort, never a gate.

References

• skills/wiki-migration/ — the migration registry + verify/apply primitive this skill drives
• migrations/queue-governance-2-to-3/ — the standalone (non-chain) queue-state migration named in the 0.3 update notes above
• migrations/trust-backfill-1/ — the standalone (non-chain) wiki-wide migration named in the 0.5.1 update notes above
• migrations/l2-map-1-to-2/ — the ordinary page-type-chain migration named in the 0.7.0 update notes above
• lib/memory/snapshot.py (Task 1.2) — the OTHER snapshot mechanism (per-write, not whole-wiki); see overlap note above
• skills/doctor/ — the post-update health check this skill's flow ends with