Specify offline recovery for the Gentoo base

docs/superpowers/plans/2026-10-13-base-recovery.md

@@ -0,0 +1,53 @@
+# Offline Base Recovery Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Recover Gentoo root, package database, kernel and owned EFI files together
+while preserving HOME and other systems, using the trusted live ISO.
+**Architecture:** Offline Btrfs read-only checkpoints and a restartable restore
+journal outside @root; matching EFI/HydraOS backups; explicit target identities.
+**Tech Stack:** Python stdlib, Btrfs tools, existing live image and QEMU acceptance.
+**Spec:** `docs/superpowers/specs/2026-10-13-base-recovery-design.md`
+
+## Global Constraints
+
+- No real host devices or existing VM disks may be modified during development.
+- Only genuine live mode, selected unmounted single-device Btrfs/ESP, explicit UUID.
+- @home, foreign EFI/BOOT, partition table and firmware state remain unchanged.
+- Runtime update and full-base checkpoint/recovery remain distinct commands/scopes.
+- Recovery requires no installed executables/network and retains previous roots.
+
+## Review Focus
+
+1. Duplicate/cloned UUIDs or changed PARTUUIDs fail before modifying either target.
+2. A nested root subvolume or read-write snapshot invalidates the checkpoint contract.
+3. Interrupted root rename/EFI copy resumes from the durable journal and actual UUIDs.
+4. Corrupt/path-traversing EFI backups never overwrite foreign files.
+5. The real VM proves coordinated kernel/package recovery and post-checkpoint HOME.
+
+## Task 1: Offline command and journal
+
+**Files:** `hydra/system_recovery.py`, `bin/hydra-system`,
+`tests/test_system_recovery.py`, `docs/system-recovery.md`.
+**Consumes:** installer storage.json schema and @root/@home/@snapshots layout.
+**Produces:** checkpoint/list/restore CLI; root-owned completed metadata and durable
+restore transaction; module has no import-time mutations and works from live ISO.
+
+- [ ] Write failing topology/ownership/path/format checks and checkpoint publication tests.
+- [ ] Implement root/ESP resolution and private mount cleanup, read-only planning.
+- [ ] Implement offline checkpoint snapshot and EFI backup with exact metadata/hashes.
+- [ ] Implement restartable restore preserving failed roots and all non-owned data.
+- [ ] Test process interruption/restart at journal transitions and malformed backups.
+- [ ] Scoped tests, self-review, commit, independent task review.
+
+## Task 2: Bootable acceptance and integration
+
+**Files:** new `dev/system-recovery-smoke.py` or extension to preserve-partition
+acceptance, associated harness tests, image wiring and release evidence.
+
+- [ ] Consume completed installer mode; seed and record fresh qcow2 only.
+- [ ] Install, checkpoint offline, upgrade real fixture package and change HOME.
+- [ ] Damage selected kernel and owned EFI, recover from live ISO and boot disk-only.
+- [ ] Verify exact old base/kernel/Portage and unchanged current HOME/foreign data.
+- [ ] Exercise interrupted restore, record hashes/states and honest limitations.
+- [ ] Integrate with laptop ISO acceptance and final review before delivery.