Hydra-OS/docs/superpowers/plans/2026-10-13-gentoo-image.md

HydraOS Gentoo Image Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans. Checkboxes track implementation.

Goal: Produce and boot-test an installable Gentoo-based HydraOS ISO.

Architecture: Verified stage3 and pinned Portage feed an isolated builder. A prepared rootfs provides both live image and installer payload. Dracut/SquashFS/GRUB make the ISO; a guarded installer applies it only to explicitly selected disks.

Tech Stack: Gentoo systemd amd64 stage3, Portage/binhost, Podman rootless, dracut, GRUB EFI, SquashFS, Python3, shell.

Spec: ../specs/2026-10-13-gentoo-image-design.md

Global Constraints

• First target ASUS FX517ZC, UEFI, SecureBoot disabled.
• No changes to current hostconfig, existing Ubuntu or userVM disks.
• Dedicated builder store under ignored build/, no global prune.
• Stage3 signature primaryfingerprint 13EBBDBEDE7A12775DFDB1BABB572E0E2D182910.
• Sources pinned; preserve Portage, package inventory and normal update hooks.
• Build jobs4, emerge jobs1 initially; do not stop userVMs for resources.
• Installer defaults to dry-run; no default disk or universal installed password.
• Physical installation not part of autonomous test execution.

Review Focus

• Cache corruption or wrong signingkey: Task1 verification must reject before import.
• Builder retries must preserve unrelated stores/data: Task1 exact scoped paths/names.
• Installer target is parent of live/root/mountedpartition: Task3 topology rejection.
• Partial format/copy failure: Task3 fail-fast, no subsequent bootloader stage.
• Hardware-only behavior: Task4 records unverified physical checks explicitly.

Task 1: Reproducible build inputs and isolated builder

Files: image/sources.json, image/packages, image/portage/, scripts/hydra-build, hydra/build.py, tests/test_build.py. Interfaces: hydra-build fetch|prepare|packages|rootfs|iso|status, --work PATH, --cache PATH, optional --podman PATH. Each step resumable and validates prerequisite manifests. Outputs WORK/rootfs payload or dedicated builder container, WORK/artifacts/, build manifest. No host root required.

• Test pinned download hash mismatch, required signaturefingerprint, safe workpath/refusal of root, resume state vs missingactualartifact, scoped Podman argv.
• Observe RED; implement verifiedfetch and isolatedimport/container naming. Use stage3 20261011T170049Z SHA256 50634e8cb87384b94a6dbf78cd2707766c45a5a98f3823e7287d114ee998970b and Portage4696089e782c20b5f0c04952f6698d6a8cc1acb4 archiveSHA256 d24b2056f7ae26506193374b0d9f25c82d4bf547e0ee17279940169418bd3bca.
• Configure officialbinhost signaturechecking, selective ~amd64 for labwc/wlroots, QEMU x86_64 only, required SPICE/GL/USB flags. Preserve licenses and installed packageDB.
• Run actual dependency resolution and package install; record exact versions/USE and any selective sourcebuild decisions. No claim of bit-identical build.
• Run tests and commit builder inputs/scripts.

Task 2: Host rootfs and bootable image

Files: image/rootfs/, image/grub.cfg, image/dracut.conf, image/configure-rootfs.sh, tests/test_image.py. Interfaces: Consumes builder and tested CLI/session from graphics plan. Produces labelled HYDRA_OS ISO with boot/vmlinuz, boot/initramfs-live.img, LiveOS/squashfs.img and package/buildmanifest.

• Test service/config generation, live-only overrides separation, exact kernelversion used for dracut, image label/cmdline agreement, networksubnet conflict handling.
• Implement rootfs overlay: greetd/minimalsession, recovery, localliveadministration, installedauth baseline, audio, NetworkManager, hydrabr0/DHCP/NAT and narrowlyscoped bridgehelper. Include laptopfirmware/bootdrivers and OVMF.
• Build genericliveinitramfs with dmsquash-live and OverlayFS; squashfspayload retains kernel/packageDB. Assemble UEFIISO with GRUB; save SHA256 and manifest.
• Run image checks and disposable OVMF/KVM liveboot; verify rootfilesystem ready and expected tools. Commit rootfs/imageconfig.

Task 3: Explicit guarded installer

Files: bin/hydra-install, hydra/installer.py, tests/test_installer.py. Interfaces: hydra-install --disk DEVICE --user USER [--execute --confirm-erase DEVICE]; without execute prints exactplan. Environment/default rootfs path points to live squashfs, never running root. Password via getpass/TTY, never CLI/log. Separate nonsecret dryrun from execution.

• Test missing/mismatched confirmation, disk mounted directly or through children/ancestors, root/live source backingdisk, invaliddevice, symlink resolution, invalidusername, failedcommands abort subsequentsteps.
• Observe RED; implement sysfs/lsblk topology validation, GPT1GiBESP/ext4, payload extraction, fstabUUIDs, user/password setup and liveoverridesremoval. Explicit target, no automaticdiscoveryselection.
• Install regularinitramfs and GRUBfallback --removable --no-nvram. Checked subprocessargv; handle failure diagnostics and mounts cleanup without deletingtargetdata.
• Test fakecommandfailure paths then complete actualinstallation inside fresh VM using disposable qcow2. Rootprivilege exists only in testguest.
• Commit installer and negative tests.

Task 4: Installed-system validation and publication

Files: dev/iso-smoke.py, docs/install.md, docs/verification.md, README.md. Interfaces: Consumes ISO and installer. Produces evidence from boot/install/reboot and releaseartifact checksum, plus pendinghardwarechecklist.

• Boot ISO under OVMF/KVM with fresh disk; install only there; write persistence sentinel.
• Remove ISO and boot installeddisk; verify sentinel, services, QEMUtools, network and shell/recovery. Check no liveoverlay/autologinadminoverride remains.
• Test nested guest VM if KVM nesting available; distinguish virtualgraphics from real laptopresults.
• Run full test suite and independent review. Correct material defects; document remaining physicalchecks without claiming them passed.
• Save ISO locally with checksum, push source/patches/manifests to suppliedrepo. BinaryISO only uploaded when suitable repository release/storage path exists; never commit ISO to Git.