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.
This commit is contained in:
parent
38214ea9e7
commit
20bfd82079
9 changed files with 889 additions and 0 deletions
189
AGENTS.md
Normal file
189
AGENTS.md
Normal file
|
|
@ -0,0 +1,189 @@
|
|||
# AGENTS.md — operating instructions for AI sessions
|
||||
|
||||
This file is the entry point for any AI/LLM session (or human) working on
|
||||
Phoebus OS. **Read this file first, then follow the reading order below.**
|
||||
It is deliberately concrete: follow it rather than rediscovering the project.
|
||||
|
||||
---
|
||||
|
||||
## 1. What Phoebus is
|
||||
|
||||
Phoebus OS is a **modern, stable, Gentoo-based workstation operating system**:
|
||||
systemd, Wayland-first, PipeWire, UEFI/GPT, LUKS2, Btrfs with snapshots, a fast
|
||||
dwl-style desktop, Flatpak, and an optional AI administration assistant. It is
|
||||
**AI-first but never AI-dependent**: the system must be fully usable without an
|
||||
LLM, and the LLM never holds privilege.
|
||||
|
||||
Read next, in order:
|
||||
|
||||
1. `docs/OBJECTIVES.md` — vision, philosophy, non-goals.
|
||||
2. `docs/ROADMAP.md` — priorities and what is done/next/later.
|
||||
3. `docs/STATUS.md` — what is implemented vs unit-tested vs VM-verified.
|
||||
4. `docs/ARCHITECTURE.md` — components and how they fit together.
|
||||
5. `docs/DEVELOPMENT.md` — host setup, build, test, VM workflow.
|
||||
6. `docs/CONTRIBUTING.md` — code standards and definition of done.
|
||||
7. `docs/GIT-WORKFLOW.md` — how changes are committed and published.
|
||||
8. `git log --oneline -30` and the top of `docs/CHANGELOG.md` — recent history.
|
||||
|
||||
---
|
||||
|
||||
## 2. Non-negotiable rules
|
||||
|
||||
These are not preferences. Do not violate them, even to make a test pass.
|
||||
|
||||
1. **Never touch a physical host disk.** All destructive testing happens on a
|
||||
disposable qcow2 image. If a test needs a real disk, stop and say so.
|
||||
2. **Never send secrets to an LLM.** No passwords, passphrases, API keys or
|
||||
tokens in prompts, logs, config files, command lines or commits.
|
||||
3. **Never log secrets.** Register every secret with the redactor; pass
|
||||
passphrases only over stdin.
|
||||
4. **Never give the LLM a shell or root.** AI can only emit typed, validated
|
||||
actions; a privileged, human-approved broker executes them.
|
||||
5. **Never globally enable Gentoo `~amd64`.** Scoped `accept_keywords` for
|
||||
hardware/desktop enablement are allowed and must be explicit.
|
||||
6. **Never disable package signature verification** to make an install pass.
|
||||
7. **Never weaken** LUKS2, Btrfs, systemd, UEFI or disk protection for
|
||||
convenience. Fix the real problem.
|
||||
8. **Stability beats novelty.** No release-candidate kernels, no experimental
|
||||
filesystem defaults, no unstable snapshots. Prefer stable/LTS and mature
|
||||
implementations.
|
||||
9. **Do not regress the proven boot path.** See `docs/STATUS.md` for the exact
|
||||
configuration that is known to boot.
|
||||
10. **Do not commit the ISO, build output, session transcripts or secrets.**
|
||||
`.gitignore` handles this; do not override it.
|
||||
|
||||
---
|
||||
|
||||
## 3. Repository map
|
||||
|
||||
```
|
||||
AGENTS.md this file (read first)
|
||||
README.md short project overview
|
||||
docs/ objectives, roadmap, status, architecture, process
|
||||
installer/ proven Bash installer (reference / fallback)
|
||||
bin/ai-installer entry point
|
||||
lib/ deterministic backend modules
|
||||
tui/ dialog/whiptail UI
|
||||
config/ defaults, example config, OpenCode manifest
|
||||
tests/ unit suite + tests/vm/ disposable-VM harness
|
||||
doc/ environment findings and VM boot verification
|
||||
installer-rs/ production Rust installer
|
||||
crates/phoebus-core types, validation, plan, policy, target-root safety
|
||||
crates/phoebus-executor command layer, storage, Portage, boot, snapshots, ...
|
||||
crates/phoebus-ai typed proposals + enforced privacy boundary
|
||||
crates/phoebus-tui ratatui TUI
|
||||
crates/phoebus-installer CLI, `sys`, `phoebus-release`, orchestration
|
||||
scripts/ git/dev tooling (hooks, publish, agent-commit)
|
||||
.githooks/ committed git hooks
|
||||
```
|
||||
|
||||
Authoritative design records:
|
||||
|
||||
- `installer/doc/FINDINGS.md` — what the reference live environment contains.
|
||||
- `installer/doc/VM-BOOT-VERIFICATION.md` — the proven VM install/boot path.
|
||||
- `installer-rs/README.md` — Rust workspace details.
|
||||
|
||||
---
|
||||
|
||||
## 4. How to work (loop)
|
||||
|
||||
1. Read this file and the reading order in §1.
|
||||
2. Inspect `docs/ROADMAP.md` for the highest-priority unfinished item.
|
||||
3. Inspect `git log --oneline -20` and `docs/CHANGELOG.md` for context.
|
||||
4. Inspect the relevant code and existing tests **before editing**.
|
||||
5. Implement the smallest correct change. Prefer upstream tools over new code.
|
||||
6. Run the quality gates and relevant tests (§5).
|
||||
7. If you did destructive work, run it in the disposable VM (§6) and record
|
||||
the evidence.
|
||||
8. Update `docs/CHANGELOG.md` and `docs/STATUS.md` if behavior/verification
|
||||
changed.
|
||||
9. Commit with a conventional commit message (see `docs/GIT-WORKFLOW.md`) and
|
||||
push when the user's remote is configured.
|
||||
|
||||
Do the actual work; do not stop at a design document. Do not ask for guidance
|
||||
when the next engineering step is clear.
|
||||
|
||||
---
|
||||
|
||||
## 5. Build and test gates
|
||||
|
||||
Bash installer (reference):
|
||||
|
||||
```sh
|
||||
installer/tests/run_tests.sh # unit/regression assertions
|
||||
shellcheck -S warning installer/bin/ai-installer installer/lib/*.sh installer/tui/*.sh
|
||||
```
|
||||
|
||||
Rust installer (production):
|
||||
|
||||
```sh
|
||||
cd installer-rs
|
||||
cargo fmt --all -- --check
|
||||
cargo clippy --workspace --all-targets
|
||||
cargo test --workspace
|
||||
cargo build --release -p phoebus-installer
|
||||
```
|
||||
|
||||
Static binary for the live installer environment:
|
||||
|
||||
```sh
|
||||
cd installer-rs
|
||||
RUSTFLAGS="-C target-feature=+crt-static" \
|
||||
cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu
|
||||
```
|
||||
|
||||
Both test suites must pass before a commit. The pre-commit hook runs the fast
|
||||
Bash suite and a secret scan; see `docs/GIT-WORKFLOW.md`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Disposable VM testing
|
||||
|
||||
`installer/tests/vm/` contains a repeatable harness:
|
||||
|
||||
- `serial-driver.py` — host-side pexpect driver (`install` and `boot` modes).
|
||||
- `install.sh` — guest-side non-interactive install.
|
||||
- `test.conf.example` — configuration.
|
||||
- `run-vm.sh` — interactive QEMU launcher.
|
||||
|
||||
Never point `DISK` at a `/dev/*` device. See `docs/DEVELOPMENT.md` for the full
|
||||
procedure and required host packages.
|
||||
|
||||
---
|
||||
|
||||
## 7. Code conventions (short form)
|
||||
|
||||
Rust: no `unsafe` (if truly needed, keep it tiny, document invariants, test
|
||||
it); no `unwrap`/`expect` in privileged paths; structured `thiserror` errors;
|
||||
never `sh -c`; every command goes through `phoebus-executor::Exec`; every
|
||||
target write goes through `TargetRoot`; destructive functions require a
|
||||
`DestructiveAuthorization` token.
|
||||
|
||||
Bash (while it exists): `shellcheck` clean; no `local a="$1" b="$a"` (dynamic
|
||||
scoping bug class); no writes to host paths without the target root; quote
|
||||
everything.
|
||||
|
||||
Use `just`-style readability, not cleverness. Fewer lines is not the goal;
|
||||
correctness, testability and observability are.
|
||||
|
||||
---
|
||||
|
||||
## 8. Where history lives
|
||||
|
||||
- `git log` — the authoritative change history.
|
||||
- `docs/CHANGELOG.md` — curated, human-readable milestones.
|
||||
- `installer/doc/VM-BOOT-VERIFICATION.md` — boot evidence per iteration.
|
||||
- `docs/STATUS.md` — current implementation/verification matrix.
|
||||
|
||||
When you finish work, update the changelog and status, then commit. A future
|
||||
session should be able to reconstruct what happened from these alone.
|
||||
|
||||
---
|
||||
|
||||
## 9. Known limitations (keep this current)
|
||||
|
||||
See `docs/STATUS.md` for the full list. Highlights: UKI is deferred (BLS is
|
||||
used); Btrfs rollback is not implemented; the AI OS sandbox is designed but not
|
||||
enforced; Full Disk Encryption boot, desktop and Flatpak are verified only in
|
||||
a disposable VM (graphical session via the headless wlroots backend, no
|
||||
physical seat); NVIDIA is not verified.
|
||||
121
docs/ARCHITECTURE.md
Normal file
121
docs/ARCHITECTURE.md
Normal file
|
|
@ -0,0 +1,121 @@
|
|||
# Architecture
|
||||
|
||||
Phoebus currently ships two installer implementations:
|
||||
|
||||
1. **Bash** (`installer/`) — the proven prototype and executable reference.
|
||||
2. **Rust** (`installer-rs/`) — the production installer. It reproduces the
|
||||
proven VM boot path and is the intended long-term backend.
|
||||
|
||||
The Bash implementation stays until hardware-level desktop verification exists.
|
||||
|
||||
## Layering
|
||||
|
||||
```
|
||||
TUI / CLI / sys front-ends (phoebus-tui, phoebus-installer)
|
||||
|
|
||||
v
|
||||
Orchestration + plan staged execution, single source of truth
|
||||
|
|
||||
v
|
||||
Executor commands, storage, Portage, boot, services
|
||||
|
|
||||
v
|
||||
Core typed config, models, policy, validation
|
||||
```
|
||||
|
||||
### phoebus-core
|
||||
|
||||
Pure, non-privileged logic with no external commands except reading `/proc`,
|
||||
`/sys` and small system files:
|
||||
|
||||
- `config` — `InstallConfig` (nested sections, enums for closed sets); TOML and
|
||||
legacy flat-format loading (format is detected structurally).
|
||||
- `validate` — hostname/username/locale/timezone/keymap/password checks.
|
||||
- `disk` / `hardware` — models and protection classification (pure).
|
||||
- `plan` — `InstallPlan` with the canonical step order and human rendering.
|
||||
- `policy` — deterministic source/binary decisions + policy context.
|
||||
- `emergelog` — parses Portage `emerge.log` into measured compile times.
|
||||
- `target` — `TargetRoot`, which rejects absolute paths and `..` traversal.
|
||||
- `secret` — `SecretString` (redacted `Debug`, zeroized on drop) + `Redactor`.
|
||||
- `snapshot` — deterministic snapshot names + TOML transaction history.
|
||||
- `action` — closed `SystemAction` schema and a small deterministic parser.
|
||||
- `update` — preparation policy and real Portage argument builders.
|
||||
|
||||
### phoebus-executor
|
||||
|
||||
The only crate that runs privileged commands.
|
||||
|
||||
- `command` — `CommandSpec`, `ProcessRunner` (real / recording / never) with
|
||||
arguments always separate; there is no `sh -c`.
|
||||
- `exec` — `Exec` centralises logging, redaction, dry-run, chroot mounts and
|
||||
target writes.
|
||||
- `log` — file + optional stderr logging; every line is redacted.
|
||||
- `auth` — `DestructiveAuthorization`, issued only after ERASE + final
|
||||
confirmation.
|
||||
- `storage`, `encryption`, `portage`, `kernel`, `boot`, `users`, `services`,
|
||||
`desktop` — the install backend, mirroring the proven order.
|
||||
- `probe` — read-only hardware and disk discovery.
|
||||
- `snapshot`, `update`, `admin`, `actions` — post-install foundations.
|
||||
|
||||
### phoebus-ai
|
||||
|
||||
- Typed `AiProposal` / `SystemAction` (unknown actions fail closed; no shell).
|
||||
- `privacy` — `PrivacyPolicy` + `ContextBundle`; forbidden-path checks. The
|
||||
collector in `phoebus-executor::admin` only reads system sources.
|
||||
|
||||
### phoebus-installer
|
||||
|
||||
- `orchestrate` — `Installer` runs the plan stages and stops on first failure.
|
||||
- `release` — `ReleaseManifest` create/verify, assemble command.
|
||||
- Binaries: `phoebus-installer`, `sys`, `phoebus-release`.
|
||||
|
||||
## Safety model
|
||||
|
||||
- Every command goes through `Exec`, which logs a redacted command line, exit
|
||||
status and duration, and honours dry-run centrally.
|
||||
- Destructive functions take `&DestructiveAuthorization`; the token is created
|
||||
only after the destructive preview and confirmations.
|
||||
- All target writes go through `TargetRoot`; host-versus-target mistakes are
|
||||
caught by construction and covered by tests.
|
||||
- Secrets travel over stdin only and are registered with the redactor before
|
||||
any logging. They never enter the config.
|
||||
- The AI cannot execute; it can only propose typed changes that the backend
|
||||
validates and the user approves.
|
||||
|
||||
## Installation order (do not regress)
|
||||
|
||||
```
|
||||
storage_prepare -> stage_install -> fstab_generate -> portage_configure
|
||||
-> packages_base -> kernel_install -> boot_install -> users_configure
|
||||
-> services_configure -> desktop_install -> finalize
|
||||
```
|
||||
|
||||
Storage order: partition GPT, create ESP, LUKS format/open, `mkfs.btrfs`, mount
|
||||
top-level, create subvolumes, unmount, mount the subvolume layout. `fstab` and
|
||||
`crypttab` are generated **after** stage3 extraction (stage3 ships its own
|
||||
`/etc/fstab`).
|
||||
|
||||
## Configuration and plan
|
||||
|
||||
`InstallConfig` is canonical data; the plan and all rendering derive from it.
|
||||
The same plan drives the review screen, the destructive preview, dry-run and
|
||||
the actual execution, so the UI cannot diverge from the backend.
|
||||
|
||||
## Post-install foundations
|
||||
|
||||
- **Snapshots**: read-only Btrfs snapshots under `/.snapshots`, recorded in a
|
||||
TOML history. `/home` is intentionally not snapshotted by default.
|
||||
- **Background updates**: `emerge --fetchonly` then `--buildpkgonly` stage
|
||||
distfiles and reusable local binary packages without installing; activation
|
||||
stays explicit.
|
||||
- **Kernel/boot**: `sys-kernel/gentoo-kernel-bin` (safe) or `gentoo-kernel`
|
||||
(optimized), dracut initramfs, systemd-boot BLS entries, plus a recovery
|
||||
entry booting `rescue.target`.
|
||||
|
||||
## Extension points
|
||||
|
||||
- `ProcessRunner` — swap the real runner for a recording/never runner in tests,
|
||||
or for a different execution backend.
|
||||
- `InstallStep` — add stages in `plan.rs` and handle them in `orchestrate.rs`.
|
||||
- `SystemAction` — add closed verbs; the policy engine classifies and previews
|
||||
them, and the broker executes them after approval.
|
||||
79
docs/CHANGELOG.md
Normal file
79
docs/CHANGELOG.md
Normal file
|
|
@ -0,0 +1,79 @@
|
|||
# Changelog
|
||||
|
||||
All notable changes are recorded here. The authoritative history is `git log`;
|
||||
this file is the curated, human-readable summary.
|
||||
|
||||
Format: Keep a Changelog. Dates are UTC.
|
||||
|
||||
## Unreleased
|
||||
|
||||
### Added
|
||||
- Git workflow: committed hooks (`.githooks/`), `scripts/check-secrets.sh`,
|
||||
`scripts/agent-commit.sh`, `scripts/publish.sh`, `scripts/setup-hooks.sh`.
|
||||
- Documentation set: `docs/OBJECTIVES.md`, `ROADMAP.md`, `STATUS.md`,
|
||||
`ARCHITECTURE.md`, `DEVELOPMENT.md`, `CONTRIBUTING.md`, `GIT-WORKFLOW.md`,
|
||||
`CHANGELOG.md`, and the top-level `AGENTS.md`.
|
||||
- `.gitignore` covering the ISO, build output, transcripts and secrets.
|
||||
|
||||
## 2026-09-20 — Rust installer parity, desktop, and foundations
|
||||
|
||||
### Added
|
||||
- Rust workspace (`installer-rs/`): `phoebus-core`, `phoebus-executor`,
|
||||
`phoebus-ai`, `phoebus-tui`, `phoebus-installer` (~9.4k LOC, 45 files).
|
||||
- Typed `InstallConfig` supporting TOML and the legacy flat format.
|
||||
- `TargetRoot` (host/target path safety), `SecretString`/`Redactor`,
|
||||
`DestructiveAuthorization`, central `Exec` command layer with dry-run.
|
||||
- Storage backend: GPT, ESP, LUKS2, Btrfs layout, fstab/crypttab, swapfile.
|
||||
- Stage3 fetch with pinned SHA-256 (or signed DIGESTS), Portage configuration,
|
||||
signed binary use, source builds, kernel, dracut, systemd-boot BLS.
|
||||
- Desktop/Flatpak: selects `default/linux/amd64/23.0/desktop/systemd`, writes
|
||||
`/usr/local/bin/phoebus-session`; flathub remote configured.
|
||||
- Package policy instrumentation: measured compile times parsed from
|
||||
`emerge.log` (326 entries recorded in the desktop run), persisted to
|
||||
`/var/lib/phoebus/compile-times.tsv`.
|
||||
- Snapshots: read-only Btrfs snapshots + TOML transaction history.
|
||||
- Background update preparation (`--fetchonly` + `--buildpkgonly`).
|
||||
- Typed `SystemAction` schema, privileged broker, and the `sys` command.
|
||||
- AI privacy boundary (`PrivacyPolicy`, `ContextBundle`, forbidden paths).
|
||||
- Release tooling: `phoebus-release` manifest/verify/sha256/assemble.
|
||||
- ratatui TUI with plan review and ERASE confirmation.
|
||||
- Recovery BLS entry booting `rescue.target`.
|
||||
|
||||
### Fixed
|
||||
- Subvolumes mounted before creation.
|
||||
- fstab/crypttab overwritten by stage3 extraction (moved to `fstab_generate`).
|
||||
- Missing `/var/tmp` breaking `kernel-install`.
|
||||
- `installkernel` requiring `uki_generator` even for BLS.
|
||||
- dracut `crypt` module and `systemd-cryptsetup` missing.
|
||||
- LUKS cmdline using `rd.luks.uuid` instead of `rd.luks.name`.
|
||||
- dracut UKI missing the kernel command line (BLS adopted).
|
||||
- `@swap` not mounted, breaking swap activation.
|
||||
- Portage GPG verify user unable to read the getuto keyring.
|
||||
- Transient rsync mirror quarantine (sync retries).
|
||||
- Pillow/HarfBuzz documentation circular dependency.
|
||||
- Legacy config silently parsed as TOML with defaults.
|
||||
|
||||
### Verified
|
||||
- Full encrypted UEFI install and boot with the ISO detached: `systemd` PID 1,
|
||||
`is-system-running = running`, 0 failed units, 10.73 s boot.
|
||||
- Desktop stack headless: dwl, waybar, mako, swaybg, `grim` screenshot,
|
||||
`wl-copy`/`wl-paste`, `wpctl`, `flatpak 1.18.1` + flathub.
|
||||
- No secret leakage in the installer log.
|
||||
|
||||
## 2026-09-19 — Bash installer prototype and first VM boot
|
||||
|
||||
### Added
|
||||
- Bash + `dialog` installer (`installer/`) with deterministic backend, TUI,
|
||||
plan/review, dry-run, logging, and destructive confirmation.
|
||||
- Read-only hardware/disk discovery with live-medium protection.
|
||||
- GPT/LUKS2/Btrfs backend, systemd stage3, Portage, kernel, systemd-boot,
|
||||
users/services/desktop modules.
|
||||
- Unit/regression suite and a disposable VM harness.
|
||||
|
||||
### Verified
|
||||
- First complete encrypted UEFI VM install and boot with the Bash installer.
|
||||
|
||||
### Fixed
|
||||
- The subvolume-ordering, fstab-timing, `/var/tmp`, `rd.luks.name`,
|
||||
`uki_generator`, cryptsetup, `@swap`, and `local root="$1" dir=...` bugs
|
||||
(these are the class of bug the Rust port is designed to prevent).
|
||||
84
docs/CONTRIBUTING.md
Normal file
84
docs/CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,84 @@
|
|||
# Contributing
|
||||
|
||||
## Golden rules
|
||||
|
||||
1. Read `AGENTS.md` and the reading order in it before changing anything.
|
||||
2. Prefer upstream tools and Gentoo conventions over new code.
|
||||
3. Keep the proven boot path working. If a change could regress it, verify in
|
||||
the disposable VM before committing.
|
||||
4. Never commit secrets, the ISO, build output or session transcripts.
|
||||
5. Update `docs/CHANGELOG.md` and `docs/STATUS.md` when behavior or
|
||||
verification changes.
|
||||
|
||||
## Rust standards
|
||||
|
||||
- No `unsafe`. If it is genuinely required, keep it tiny, document the
|
||||
invariants, and test it. (The TUI uses `std::io::IsTerminal` rather than a
|
||||
foreign `isatty`.)
|
||||
- No `unwrap`/`expect` in privileged paths. Return structured `thiserror`
|
||||
errors that carry stage, operation and exit status.
|
||||
- Never `sh -c`. Every command goes through `phoebus-executor::Exec` with
|
||||
separate arguments; secrets go over stdin.
|
||||
- Every target write goes through `TargetRoot`.
|
||||
- Destructive functions require `&DestructiveAuthorization`.
|
||||
- Keep unit-testable logic pure and in `phoebus-core`; keep privileged effects
|
||||
in `phoebus-executor` behind `ProcessRunner`.
|
||||
|
||||
## Bash standards (while it remains)
|
||||
|
||||
- `shellcheck -S warning` clean.
|
||||
- Never `local a="$1" b="$a"` (the dynamic-scoping bug class). Use two `local`
|
||||
statements.
|
||||
- Never write to a host path without the target root.
|
||||
- Quote all expansions.
|
||||
|
||||
## Tests
|
||||
|
||||
- Add a regression test for every meaningful bug (see the tests in
|
||||
`installer/tests/` and `installer-rs/crates/*/src`).
|
||||
- Prefer a fake `ProcessRunner` + `TempDir` over root or real disks.
|
||||
- Destructive/integration testing only in a disposable qcow2 VM.
|
||||
- Both suites must pass before a commit.
|
||||
|
||||
## Commit messages
|
||||
|
||||
Conventional Commits, imperative mood:
|
||||
|
||||
```
|
||||
<type>(<scope>): <summary>
|
||||
|
||||
<body: what changed and why, and how it was verified>
|
||||
```
|
||||
|
||||
Types: `feat`, `fix`, `refactor`, `test`, `docs`, `build`, `ci`, `chore`.
|
||||
Scopes: `installer`, `rust`, `core`, `executor`, `ai`, `tui`, `vm`, `docs`,
|
||||
`git`, `release`.
|
||||
|
||||
Examples:
|
||||
|
||||
```
|
||||
feat(rust): add typed SystemAction broker for sys
|
||||
fix(executor): make getuto keyring readable by the verify user
|
||||
docs(git): add migration plan and agent workflow
|
||||
```
|
||||
|
||||
## Definition of done
|
||||
|
||||
- [ ] The change is implemented, not merely described.
|
||||
- [ ] Tests added or updated; both suites pass.
|
||||
- [ ] `cargo fmt`/`clippy` clean (when the components are installed).
|
||||
- [ ] `docs/CHANGELOG.md` updated; `docs/STATUS.md` updated if verification
|
||||
changed.
|
||||
- [ ] No secrets, ISO, build output or transcripts staged.
|
||||
- [ ] Committed with a conventional message and pushed when a remote exists.
|
||||
|
||||
## Review checklist
|
||||
|
||||
- Does it weaken encryption, signing, boot protection or disk safety? If so,
|
||||
stop.
|
||||
- Does it globally enable `~amd64` or disable signature verification? If so,
|
||||
stop.
|
||||
- Does it give the LLM a shell, root, secrets or home-directory access? If so,
|
||||
stop.
|
||||
- Does it preserve the proven boot path and the fstab/subvolume ordering?
|
||||
- Is the change observable in the log and covered by a test?
|
||||
117
docs/DEVELOPMENT.md
Normal file
117
docs/DEVELOPMENT.md
Normal file
|
|
@ -0,0 +1,117 @@
|
|||
# Development
|
||||
|
||||
## Host requirements
|
||||
|
||||
Ubuntu/Debian host names (the development machine is Ubuntu 26.04):
|
||||
|
||||
```sh
|
||||
sudo apt install qemu-system-x86 qemu-utils ovmf-generic seabios ipxe-qemu \
|
||||
dialog xorriso mtools dosfstools squashfs-tools cpio zstd \
|
||||
shellcheck python3-pexpect
|
||||
|
||||
# Rust quality gates (names may be versioned; check `apt search rustfmt`)
|
||||
sudo apt install rust-clippy rustfmt
|
||||
# or, if cargo is rustup-managed:
|
||||
# rustup component add rustfmt clippy
|
||||
```
|
||||
|
||||
Optional: `expect`, `cryptsetup`, `btrfs-progs`, `parted`, `kpartx` for offline
|
||||
inspection of VM images. `7z`/`p7zip` is useful for reading the reference ISO.
|
||||
|
||||
## Reference media
|
||||
|
||||
The Gentoo LiveGUI ISO is a **reference artifact**, not source. It is ignored by
|
||||
`.gitignore`. Keep it outside git; point the VM harness at it by path.
|
||||
|
||||
## Bash installer
|
||||
|
||||
```sh
|
||||
installer/tests/run_tests.sh
|
||||
shellcheck -S warning installer/bin/ai-installer installer/lib/*.sh installer/tui/*.sh
|
||||
|
||||
# Non-interactive, non-destructive:
|
||||
installer/bin/ai-installer --config installer/config/example.conf --plan
|
||||
installer/bin/ai-installer --dry-run --config installer/config/example.conf
|
||||
```
|
||||
|
||||
## Rust installer
|
||||
|
||||
```sh
|
||||
cd installer-rs
|
||||
cargo fmt --all -- --check
|
||||
cargo clippy --workspace --all-targets
|
||||
cargo test --workspace
|
||||
cargo build --release -p phoebus-installer
|
||||
|
||||
# Static binary for the live environment:
|
||||
RUSTFLAGS="-C target-feature=+crt-static" \
|
||||
cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu
|
||||
```
|
||||
|
||||
Useful CLI invocations:
|
||||
|
||||
```sh
|
||||
target/release/phoebus-installer --config FILE --plan
|
||||
target/release/phoebus-installer --config FILE --dry-run --install
|
||||
target/release/phoebus-installer --config FILE --install --yes \
|
||||
--luks-passphrase-file /secure/luks.pw --user-password-file /secure/user.pw
|
||||
```
|
||||
|
||||
## Disposable VM testing
|
||||
|
||||
Never point the harness at a physical disk. The target is always a qcow2 file.
|
||||
|
||||
`installer/tests/vm/serial-driver.py` drives QEMU over the serial console:
|
||||
|
||||
```sh
|
||||
cd /path/to/serve
|
||||
tar czf installer.tar.gz -C /path/to/phoebus_os installer # or the Rust binary
|
||||
python3 -m http.server 8000 --bind 127.0.0.1
|
||||
|
||||
QEMU_BIN=qemu-system-x86_64 \
|
||||
OVMF_CODE=/usr/share/OVMF/OVMF_CODE_4M.fd \
|
||||
OVMF_VARS=/usr/share/OVMF/OVMF_VARS_4M.fd \
|
||||
DISK=/tmp/phoebus/target.qcow2 \
|
||||
ISO=/path/to/livegui-*.iso \
|
||||
KERNEL=/tmp/live/boot/gentoo INITRD=/tmp/live/boot/gentoo.igz \
|
||||
INSTALL_URL=http://10.0.2.2:8000/install.sh \
|
||||
python3 installer/tests/vm/serial-driver.py install
|
||||
|
||||
# Then boot the disk alone (ISO detached):
|
||||
DISK=/tmp/phoebus/target.qcow2 OVMF_CODE=... OVMF_VARS=... \
|
||||
python3 installer/tests/vm/serial-driver.py boot
|
||||
```
|
||||
|
||||
`installer/tests/vm/run-vm.sh` launches an interactive VM instead.
|
||||
|
||||
### Verifying the graphical stack
|
||||
|
||||
The serial-only VM has no logind seat, so wlroots' DRM backend cannot start
|
||||
there. For headless verification use:
|
||||
|
||||
```sh
|
||||
export WLR_BACKENDS=headless WLR_RENDERER=pixman WLR_RENDERER_ALLOW_SOFTWARE=1
|
||||
dwl & # creates wayland-0
|
||||
grim /tmp/shot.png # proves the compositor renders
|
||||
```
|
||||
|
||||
On a real machine the installer writes `/usr/local/bin/phoebus-session`
|
||||
(waybar + mako + swaybg + dwl).
|
||||
|
||||
## Inspecting the reference ISO without booting
|
||||
|
||||
```sh
|
||||
7z l livegui-*.iso
|
||||
7z x livegui-*.iso image.squashfs boot/gentoo boot/gentoo.igz
|
||||
unsquashfs -l image.squashfs # file listing
|
||||
unsquashfs -d /tmp/root image.squashfs etc/portage/make.conf
|
||||
```
|
||||
|
||||
## Quality gates before commit
|
||||
|
||||
1. `installer/tests/run_tests.sh`
|
||||
2. `cd installer-rs && cargo test --workspace`
|
||||
3. `cargo fmt --all -- --check` and `cargo clippy --workspace --all-targets`
|
||||
4. `shellcheck` on the Bash tree (while it exists)
|
||||
5. Update `docs/CHANGELOG.md` and `docs/STATUS.md` when behavior changes.
|
||||
6. Commit (see `docs/GIT-WORKFLOW.md`).
|
||||
101
docs/GIT-WORKFLOW.md
Normal file
101
docs/GIT-WORKFLOW.md
Normal file
|
|
@ -0,0 +1,101 @@
|
|||
# Git workflow and public-repository migration
|
||||
|
||||
## What is tracked
|
||||
|
||||
Tracked: source (`installer/`, `installer-rs/crates/`, `scripts/`, `.githooks/`),
|
||||
`Cargo.toml`/`Cargo.lock`, documentation (`docs/`, `AGENTS.md`, `README.md`,
|
||||
`installer/doc/`, `installer-rs/README.md`), installer configs and tests.
|
||||
|
||||
Ignored (see `.gitignore`): the reference ISO and other images, `installer-rs/target/`,
|
||||
`__pycache__`, `.agent-shell/` transcripts, and any secret material
|
||||
(`*.pw`, `*.key`, `*.pem`, `credentials`).
|
||||
|
||||
## One-time migration (already performed)
|
||||
|
||||
```sh
|
||||
cd /path/to/phoebus_os
|
||||
git init -b main
|
||||
git add -A
|
||||
git commit -m "chore: import Phoebus OS installer and Rust migration"
|
||||
# ... further commits for docs and tooling ...
|
||||
git config core.hooksPath .githooks # enable the committed hooks
|
||||
```
|
||||
|
||||
Then connect the public remote and push:
|
||||
|
||||
```sh
|
||||
git remote add origin <PUBLIC_REPO_URL>
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
`scripts/publish.sh` performs the push after re-running the checks. It takes the
|
||||
remote and branch as arguments:
|
||||
|
||||
```sh
|
||||
scripts/publish.sh origin main
|
||||
```
|
||||
|
||||
> The remote URL is intentionally not hard-coded. Add it once with
|
||||
> `git remote add origin <URL>` and every later `scripts/publish.sh` uses it.
|
||||
|
||||
## Ongoing loop for a work session
|
||||
|
||||
```
|
||||
read AGENTS.md
|
||||
-> inspect docs/ROADMAP.md and git log
|
||||
-> implement the smallest correct change
|
||||
-> run the quality gates
|
||||
-> update docs/CHANGELOG.md and docs/STATUS.md
|
||||
-> commit (conventional message)
|
||||
-> push
|
||||
```
|
||||
|
||||
An AI session **must commit the work it does**. The one-line helper:
|
||||
|
||||
```sh
|
||||
scripts/agent-commit.sh "feat(rust): add typed SystemAction broker
|
||||
|
||||
Adds a closed action schema and a privileged broker. Verified with
|
||||
cargo test --workspace."
|
||||
```
|
||||
|
||||
`agent-commit.sh` refuses to commit if the secret scan finds a credential or if
|
||||
a staged file is too large, then runs the fast tests.
|
||||
|
||||
## Hooks
|
||||
|
||||
`.githooks/pre-commit` (enabled with `git config core.hooksPath .githooks`):
|
||||
|
||||
1. scans staged files for secrets (`scripts/check-secrets.sh`);
|
||||
2. blocks staged `*.iso`, `*.qcow2` and files larger than 5 MiB;
|
||||
3. runs the fast Bash test suite.
|
||||
|
||||
Bypass for a genuine emergency with `git commit --no-verify`, or set
|
||||
`SKIP_PHOEBUS_HOOKS=1`. Set `PHOEBUS_PRECOMMIT_RUST=1` to also run
|
||||
`cargo test --workspace` in the hook.
|
||||
|
||||
## Branching and releases
|
||||
|
||||
- Trunk-based: `main` is always green. Short-lived branches are fine for risky
|
||||
work; merge with a conventional merge/squash.
|
||||
- Releases are annotated tags `vX.Y.Z` with the manifest produced by
|
||||
`phoebus-release`. Never replace `latest.iso` until `phoebus-release verify`
|
||||
passes.
|
||||
- Never rewrite published history (`push --force` to `main` is forbidden). Fix
|
||||
mistakes with a new `fix:` commit.
|
||||
|
||||
## Secret policy
|
||||
|
||||
- Never commit passwords, LUKS passphrases, API keys or tokens.
|
||||
- Secrets are supplied at runtime through 0600 files or stdin and registered
|
||||
with the redactor.
|
||||
- The pre-commit scan is a safety net, not a licence to be careless.
|
||||
|
||||
## What a future session should do
|
||||
|
||||
1. `git log --oneline -20` and `head docs/CHANGELOG.md` for context.
|
||||
2. Work as described in `AGENTS.md`.
|
||||
3. Before committing: `scripts/check-secrets.sh` and the test gates.
|
||||
4. Commit with `scripts/agent-commit.sh` (or `git commit`), then
|
||||
`scripts/publish.sh`.
|
||||
5. Confirm `git status` is clean and the push succeeded.
|
||||
66
docs/OBJECTIVES.md
Normal file
66
docs/OBJECTIVES.md
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
# Objectives
|
||||
|
||||
## Vision
|
||||
|
||||
Phoebus OS is a modern, stable, Gentoo-based workstation operating system that
|
||||
provides Gentoo-level flexibility, performance and control **without requiring
|
||||
the user to act as a full-time Gentoo administrator**.
|
||||
|
||||
It combines a mature modern architecture with a conservative update policy and
|
||||
real recovery:
|
||||
|
||||
```
|
||||
Modern architecture + mature implementations
|
||||
+ conservative updates + snapshots/rollback
|
||||
```
|
||||
|
||||
## Pillars
|
||||
|
||||
- **Gentoo + Portage** remain the package foundation. Phoebus is an integration
|
||||
layer, not a parallel Linux ecosystem.
|
||||
- **systemd** is the init and service architecture; OpenRC is out of scope.
|
||||
- **Wayland-first**, with XWayland only for compatibility.
|
||||
- **PipeWire + WirePlumber** are the audio stack. PulseAudio is not the target.
|
||||
- **UEFI/GPT-first.** Legacy BIOS is not a v0.1 priority.
|
||||
- **LUKS2** whole-root encryption with a passphrase (TPM2 later, never
|
||||
mandatory).
|
||||
- **Btrfs** with subvolumes, snapshots and (eventually) rollback.
|
||||
- **Stability over novelty.** Stable/LTS kernels, mature filesystems, no
|
||||
release candidates, no globally unmasked testing tree.
|
||||
- **Pragmatic builds.** Compile when it is cheap or genuinely beneficial; use
|
||||
signed Gentoo binaries when compilation is expensive and the benefit is
|
||||
negligible.
|
||||
- **Friendly to proprietary software** (drivers, firmware, codecs, Steam,
|
||||
browsers) where legally distributable. No moralising warnings; respect
|
||||
licences.
|
||||
- **AI-first, never AI-dependent.** The system is fully usable without an LLM.
|
||||
|
||||
## The AI contract
|
||||
|
||||
The LLM is an interface, explainer, planner and reasoning assistant. It is
|
||||
**not** the source of truth, the root shell, or the privilege boundary.
|
||||
|
||||
```
|
||||
user request -> LLM -> typed structured action -> policy engine
|
||||
-> human-readable preview -> explicit approval -> authentication
|
||||
-> privileged deterministic broker -> verification -> history
|
||||
```
|
||||
|
||||
The model never receives the user's sudo password (authentication happens
|
||||
through sudo/polkit/PAM outside model context), and it has no code path to
|
||||
read private files: system access is not home-directory access.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- A custom init system, package manager, audio stack or compositor.
|
||||
- A giant kernel fork or a large downstream patch set.
|
||||
- Bleeding-edge/experimental defaults.
|
||||
- Making the LLM required for installation or normal operation.
|
||||
- Rebuilding the world on a small release VPS.
|
||||
|
||||
## Definition of a successful distribution
|
||||
|
||||
Phoebus installs a **bootable, encrypted, systemd** system in a disposable UEFI
|
||||
VM, boots with the installer media removed, unlocks LUKS, reaches a login and
|
||||
a functional Wayland desktop, and can be maintained without the user becoming
|
||||
a Gentoo expert. This is verified per `docs/STATUS.md`.
|
||||
44
docs/ROADMAP.md
Normal file
44
docs/ROADMAP.md
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
# Roadmap
|
||||
|
||||
Priority order is deliberate. Do not skip a higher item because a later one is
|
||||
more interesting. Status vocabulary: **Done**, **Partial**, **Next**, **Later**.
|
||||
|
||||
| # | Item | Status | Evidence / notes |
|
||||
|---|------|--------|------------------|
|
||||
| 1 | Verify the Bash baseline | Done | `installer/tests/run_tests.sh`, `installer/doc/VM-BOOT-VERIFICATION.md` |
|
||||
| 2 | Build the Rust architecture | Done | `installer-rs/` workspace, 5 crates |
|
||||
| 3 | Port the deterministic core | Done | `phoebus-core` (config, plan, policy, validation, models) |
|
||||
| 4 | Port the destructive backend | Done | `phoebus-executor` (storage, LUKS2, Btrfs, Portage, boot, users, services) |
|
||||
| 5 | **Rust VM boot parity** | Done | Full encrypted UEFI install + boot, zero failed units, 10.7 s |
|
||||
| 6 | Finish the desktop | Partial | dwl/waybar/mako/swaybg/pipewire verified headless; physical seat + interactive login pending |
|
||||
| 7 | Finish Flatpak | Partial | `flatpak 1.18.1` installed, flathub configured; no app installed yet |
|
||||
| 8 | Instrument source/binary policy | Done | measured compile times harvested from `emerge.log` (326 entries) |
|
||||
| 9 | Background update preparation | Partial | `--fetchonly` + `--buildpkgonly` implemented and unit-tested; not VM-tested |
|
||||
| 10 | Snapshots / rollback | Partial | snapshot create + history done; rollback not implemented |
|
||||
| 11 | AI privilege and privacy architecture | Partial | typed actions + enforced privacy boundary; OS sandbox not implemented |
|
||||
| 12 | `sys` operations | Partial | history, enable/disable service, inspect, install, prepare-updates |
|
||||
| 13 | Kernel optimization policy | Later | conservative fragments only; SAFE/OPTIMIZED/AGGRESSIVE selection exists |
|
||||
| 14 | ISO / release pipeline | Partial | manifest/verify/assemble-plan tooling; no scheduling/publish/smoke test |
|
||||
| 15 | Recovery environment | Later | recovery BLS entry generated; full recovery image not built |
|
||||
| — | Rust TUI | Partial | ratatui UI with plan/ERASE; not yet the default on all paths |
|
||||
| — | Git workflow + agent guide | Done | this `docs/` set, `.githooks/`, `scripts/` |
|
||||
|
||||
## Immediate next steps
|
||||
|
||||
1. **Physical-seat desktop**: run `phoebus-session`/dwl on a real VT (or a
|
||||
`seatd`-backed session) and verify kitty, wofi, XWayland, the polkit agent,
|
||||
logout and reboot interactively.
|
||||
2. **Desktop binary strategy**: match the desktop USE set to a signed binhost
|
||||
(or publish one) so desktop installs stop compiling ~26 minutes of packages.
|
||||
3. **Snapshots and safe updates end-to-end**: prove `sys` snapshot +
|
||||
`prepare-updates` on an installed system, then implement and test rollback
|
||||
before wiring `sys undo`.
|
||||
|
||||
## Later
|
||||
|
||||
- Full recovery environment (network, LUKS, Btrfs, Portage/kernel repair).
|
||||
- Automated biweekly ISO candidate build with tiered tests and atomic publish.
|
||||
- AI OS sandbox (systemd sandboxing / namespaces / bubblewrap / Landlock).
|
||||
- Local model support; richer provider onboarding.
|
||||
- Optimised kernel profiles with real hardware detection.
|
||||
- Risk-class update policy (CORE / PROVEN / EDGE) and update preflight.
|
||||
88
docs/STATUS.md
Normal file
88
docs/STATUS.md
Normal file
|
|
@ -0,0 +1,88 @@
|
|||
# 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.
|
||||
Loading…
Add table
Reference in a new issue