Some checks are pending
ci / test (push) Waiting to run
Replace the fixed category routing (ADR 0006) with a shared, inspectable,
hardware- and preference-aware selection policy over resolved candidates from
Portage (source/binary/vendor), Nix, Flatpak, Snap, AppImage and the Phoebus
overlay. The policy keeps base components under Portage, separates hard
constraints from preferences, honours and persists explicit choices, errors
instead of silently switching lanes, and reuses an already-installed lane.
- phoebus-core::selection: the pure policy (16 tests: base-system, low-memory
vs high-core, sandbox requirement, GPU/arch/storage rejection, explicit
preference, unavailable backend, reproducibility, render).
- phoebus-executor::chooser: resolves real metadata and hardware facts.
- phoebus-executor::{snap,appimage,ebuild}: new lanes. Snap detects daemon and
confinement and installs app-containers/snapd through Portage; AppImage
adopts images with a pinned SHA-256, checks the ELF architecture without
executing, integrates a desktop entry and preserves user data on removal; the
custom ebuild overlay binds approval to the ebuild content digest and builds
through Portage's sandbox.
- Typed actions choose_package / set_package_preference / snap_* / appimage_* /
custom_ebuild_* with strict validators; the assistant prompt and schema are
reconciled (no category routing; custom ebuilds are untrusted).
- Installed sys: the installer locates the trusted static binary, copies it to
/usr/local/bin/sys and proves it runs in the target chroot before the
recovery snapshot, failing closed if absent; the VM harness fetches sys.
- docs/SYS.md: command/action reference and acceptance matrix; ADR 0006 revised.
Host gates pass: fmt, clippy (no new warnings), workspace tests, make test,
release and static sys builds. VM lane journeys remain pending (see HANDOFF).
190 lines
7.8 KiB
Markdown
190 lines
7.8 KiB
Markdown
# 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 a built-in AI administration assistant. The AI
|
|
assistant and Nix are **defining, always-present subsystems**: installing
|
|
Phoebus **requires a connected model** (a remote provider or a downloaded local
|
|
model; none is shipped), the installed system is AI-first and uses a connected
|
|
model proactively, and Nix is a second package lane shipped and updated through
|
|
Portage. Installation requires the network; the installed system must boot, run
|
|
and recover without it, with the Phoebus deterministic CLI (`sys`) — the same
|
|
typed actions the assistant uses — as the no-model fallback. The
|
|
LLM never holds privilege (see §2.4).
|
|
|
|
Fastest start: run `make context` (prints repository state, the roadmap's
|
|
immediate next steps, the rolling handoff and open markers).
|
|
|
|
Then read, in order:
|
|
|
|
1. `docs/OBJECTIVES.md` — vision, philosophy, non-goals.
|
|
2. `docs/ROADMAP.md` — priorities and what is done/next/later.
|
|
3. `docs/HANDOFF.md` — where the last session stopped and the next actions.
|
|
4. `docs/STATUS.md` — what is implemented vs unit-tested vs VM-verified.
|
|
5. `docs/ARCHITECTURE.md` — components and how they fit together.
|
|
6. `docs/SYS.md` — the `sys` command/action reference and acceptance matrix.
|
|
7. `docs/adr/` — why significant decisions were made (BLS, profile, ...).
|
|
8. `docs/DEVELOPMENT.md` — host setup, build, test, VM workflow.
|
|
9. `docs/CONTRIBUTING.md` — code standards and definition of done.
|
|
10. `docs/GIT-WORKFLOW.md` — how changes are committed and published.
|
|
11. `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/tests/vm/ disposable UEFI VM harness (static Rust binary)
|
|
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:
|
|
|
|
- `docs/FINDINGS.md` — what the reference live environment contains.
|
|
- `docs/VM-BOOT-VERIFICATION.md` — the proven VM install/boot path.
|
|
- `docs/BASH-MIGRATION.md` — the evidence-gated retirement of the Bash installer.
|
|
- `installer-rs/README.md` — Rust workspace details.
|
|
|
|
---
|
|
|
|
## 4. How to work (loop)
|
|
|
|
1. Read this file and the reading order in §1; run `make context`.
|
|
2. Run `make doctor` before VM work, and inspect `docs/ROADMAP.md` for the
|
|
highest-priority unfinished item.
|
|
3. Inspect `git log --oneline -20`, `docs/CHANGELOG.md` and `docs/HANDOFF.md`.
|
|
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`, `docs/STATUS.md` and `docs/HANDOFF.md` if
|
|
behavior/verification changed.
|
|
9. Commit with a conventional commit message (see `docs/GIT-WORKFLOW.md`) and
|
|
push (`scripts/publish.sh` or `make publish`).
|
|
|
|
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
|
|
|
|
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
|
|
```
|
|
|
|
The Rust suite must pass before a commit. The pre-commit hook runs a secret scan
|
|
and an optional Rust suite; 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 (developer tooling only): `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.
|
|
- `docs/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.
|