74 lines
6.2 KiB
Markdown
74 lines
6.2 KiB
Markdown
# 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.
|