phoebus_os/docs/STATUS.md
Phoebus 20bfd82079 docs: add objectives, roadmap, status, architecture and agent guide
Adds the documentation a new session needs: AGENTS.md (read-first contract), docs/OBJECTIVES.md, ROADMAP.md, STATUS.md, ARCHITECTURE.md, DEVELOPMENT.md, CONTRIBUTING.md, GIT-WORKFLOW.md and CHANGELOG.md.

STATUS.md records an honest implemented/unit-tested/VM-verified matrix and known limitations.
2026-09-20 02:07:44 -07:00

4 KiB

Status

Truthful implementation/verification matrix. Vocabulary:

  • Implemented — code exists.
  • Unit tested — covered by automated tests that run on any host.
  • VM verified — exercised in the disposable QEMU/OVMF VM.
  • Hardware verified — exercised on real hardware.
  • Not verified — do not claim it works.

Proven baseline (do not regress)

A complete installation in a disposable UEFI VM, booted with the ISO detached:

QEMU + OVMF (UEFI)
30 GiB qcow2, virtio-blk (/dev/vda); live ISO at /dev/sr0
GPT: 1 GiB FAT32 ESP + LUKS2 remainder
Btrfs: @ @home @var @snapshots @swap
Gentoo systemd stage3 (default/linux/amd64/23.0/systemd)
systemd-boot + BLS entry + dracut initramfs
LUKS2 passphrase unlock at boot
systemd PID 1, login, networking
systemctl is-system-running = running; 0 failed units

Boot timing (Rust installer): 1.378 s kernel + 5.238 s initrd + 4.114 s userspace = 10.730 s.

Matrix

Area Implemented Unit tested VM verified Hardware verified
Config (TOML + legacy), validation yes yes yes n/a
Hardware/disk discovery, protection yes yes yes no
Install plan + destructive preview yes yes yes n/a
Destructive authorization (ERASE) yes yes yes n/a
GPT partitioning + ESP yes yes yes no
LUKS2 format/open/close yes yes yes no
Btrfs subvolumes + swapfile yes yes yes no
fstab / crypttab generation yes yes yes no
stage3 fetch + SHA-256 verify + extract yes yes yes n/a
Portage config + sync + getuto yes yes yes n/a
Signed Gentoo binary install yes yes yes n/a
Source package compilation yes yes yes n/a
Kernel install + dracut initramfs yes yes yes no
systemd-boot + BLS yes yes yes no
Recovery BLS entry (rescue.target) yes yes no no
Users, passwords, sudo yes yes yes n/a
Locale/timezone/keymap/services yes yes yes n/a
Rust VM boot parity yes yes yes no
Rust TUI yes yes smoke test no
Desktop profile (dwl/waybar/mako/swaybg) yes partial headless only no
PipeWire/WirePlumber yes no headless (wpctl) no
Flatpak + flathub yes no installed + remote no
XWayland / polkit agent / kitty / wofi yes no installed, not launched no
Package policy + measured history yes yes yes (326 entries) no
Background update preparation yes yes no no
Btrfs snapshots + history yes yes no no
Btrfs rollback no no no no
AI typed proposals yes yes no n/a
AI privacy boundary yes yes no n/a
AI OS sandbox no no no no
sys verbs yes yes no no
OpenCode pinned bootstrap yes yes no n/a
Release manifest/verify yes yes no n/a
NVIDIA proprietary architecture only no no no
UKI no (deferred) no no no

Known limitations

  • Desktop graphical session was verified with the headless wlroots backend because the serial-only VM has no logind seat. The DRM path and a real VT login are not yet exercised. phoebus-session is written by the installer for that purpose.
  • Flatpak apps were not installed from the remote; only the runtime and the flathub remote were verified.
  • NVIDIA is architecturally allowed but not verified on hardware.
  • UKI is deferred; the dracut UKI generator did not embed the kernel command line, so BLS is used (and verified).
  • Rollback is not implemented; snapshots and history are.
  • AI sandbox is not enforced; only typed actions and the privacy boundary.
  • Release automation stops at manifest/verify; no scheduler, smoke test, signing or atomic publish.
  • The desktop transaction compiles heavily because desktop USE does not match the signed binhost (~26 min for the desktop set on 8 vCPUs in the test VM).
  • The installer rebuilds sys-apps/systemd from source because boot/policykit/cryptsetup USE differ from the binhost.