Hydra-OS/docs/superpowers/plans/2026-10-13-laptop-ready.md

Hydra OS Laptop Preparation 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: Deliver a tested ISO supporting preserved-partition installation, signed runtime updates/recovery, and live laptop diagnostics without modifying the host.

Architecture: Extend the validated installer with an explicit partition mode; use a separately installed trusted updater for signed passive release payloads; retain independent guest VM state. Validate each subsystem then exercise them in new disposable UEFI/KVM VMs before integrating and delivering release artifacts.

Tech Stack: Python stdlib, Gentoo, OpenSSL Ed25519, Btrfs tools, GRUB/efibootmgr, QEMU/KVM, existing dedicated rootless Podman builder.

Spec: docs/superpowers/specs/2026-10-13-laptop-ready-design.md

Global Constraints

• No physical block, firmware, host-service, original-container or existing-VM writes.
• Install tests exclusively use fresh private qcow2 disks; no target selected for laptop.
• Preserve partition boundaries, foreign EFI/fallback files and firmware BootOrder.
• Runtime payloads never contain HOME, VM data/config, credentials or networking.
• Check release signature using a separately installed key before trusting contents.
• Keep physical functional claims separate from read-only diagnostics and VM results.
• Existing whole-disk and runtime behavior must retain their regression coverage.

Review Focus

1. Partition aliases, topology changes and mounted siblings: reject actual targets in use and identity changes, preserve eligible unrelated siblings (Task 1).
2. Existing EFI loaders, lack of ESP space and partial installation: fail before destructive root formatting when possible and preserve foreign bytes (Task 1).
3. A signed but malformed/replayed archive or unsafe redirect: no mutation (Task 2).
4. Power loss during apply/rollback and a broken CLI: standalone fresh-process recovery restores exact originals and retains monotonic replay state (Task 2).
5. Missing hardware/tools, privacy and a release that passed only mocks: bounded honest diagnostics and real disposable-disk acceptance evidence (Tasks 3, 4, 5).

Task 1: Preserve-partition installer

Files: hydra/installer.py, optional focused hydra/install_storage.py, tests/test_installer.py, image/packages, image/dracut.conf, docs/install.md. Interfaces: extend Request compatibly with root_partition, esp_partition, confirm_format, root_fs and register_boot_entry. Existing install stays the entry.

• Add failing tests for mode parsing, identity/bounds/protection, mounted siblings, Btrfs member enumeration, ESP collision/space, only-root formatting and EFI policy.
• Implement shared validated target plan and distinct storage/boot branches.
• Add ext4 and Btrfs layouts plus explicit dependencies; test failure cleanup.
• Run installer suite, self-review, commit only task-owned files.
• Independent task review and scoped fixes.

Task 2: Signed update and recovery

Files: new hydra/update*.py as needed, stable bin/hydra-update*, hydra/cli.py, dev/release.py, tests/test_update*.py, tests/test_cli.py, image install wiring, docs/updates.md. Coordinate shared image files with Task 1; do not race edits. Interfaces: the CLI actions from the spec; stable recover entrypoint runnable without importing hydra runtime; passive artifact manifest with version/sequence.

• Add failing tests for real crypto, transport bounds, manifest/payload validation, no-write failures, replay rules, locking and destination/backup path ownership.
• Implement passive package builder, trusted verification and transactional apply.
• Implement explicit rollback and independent crash recovery with durable journal.
• Prove SIGKILL recovery in a fresh process, unchanged guest data and blocked corrupt backups; verify status/check work unprivileged.
• Document release creation, local key ownership, bootstrap and runtime scope.
• Run scoped suites, commit, independent review and scoped fixes.

Task 3: Read-only laptop doctor

Files: hydra/doctor.py, tests/test_doctor.py, docs/hardware/asus-fx517zc.md. Interfaces: doctor_report() returns serializable bounded observations; doctor_main(argv) serves text/JSON. CLI wiring coordinated after Task 2.

• Test fake proc/sys/tools with absent devices, timeouts and redaction.
• Implement independent read-only probes and manual functional checks.
• Run unit suite and safe host smoke, commit, independent review.

Task 4: Integration and disposable acceptance harnesses

Files: dev/iso-smoke.py, tests/test_iso_smoke.py, new dev/update-smoke.py or helper as needed, CLI wiring and docs; do not edit these while other tasks do.

• Preserve whole-disk mode; add existing-partitions acceptance using seeded fresh disk only, no existing-disk argument. Capture partition/EFI/BootOrder identities.
• Add signed update/tamper/apply/rollback/crash-recover installed-guest checks.
• Confirm brand asset and doctor availability, compile standalone guest scripts.
• Run full source suite once integrations settle; independent review.

Task 5: Build, run acceptance and deliver

Files: source release records under docs/releases; build artifacts remain ignored.

• Prepare isolated build checkout and preserve old ISO/firmware hashes.
• Build needed packages/rootfs/ISO, retaining explicit signature trust material.
• Run whole-disk and preserve-partitions real UEFI acceptance plus updater recovery.
• Run focused fixes only for observed failures, rerun affected acceptance.
• Verify exact release files, checksums, source revisions and absence of secrets.
• Final independent branch review, integrate and publish authorized source/artifacts using available authenticated transport; report any unavailable publishing action.
• Report physical checks still requiring live laptop boot, not unsupported success.