diff --git a/AGENTS.md b/AGENTS.md index 387ebfb..4b6c4c3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -78,8 +78,9 @@ scripts/ git/dev tooling (hooks, publish, agent-commit) 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. +- `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. --- @@ -165,7 +166,7 @@ correctness, testability and observability are. - `git log` — the authoritative change history. - `docs/CHANGELOG.md` — curated, human-readable milestones. -- `installer/doc/VM-BOOT-VERIFICATION.md` — boot evidence per iteration. +- `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 diff --git a/README.md b/README.md index 029ec82..c74ccd0 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ exact implementation/verification matrix and known limitations. ``` AGENTS.md entry point for AI/human contributors (read first) docs/ objectives, roadmap, status, architecture, process -installer/ proven Bash installer (reference / fallback) + VM harness +installer/tests/vm/ disposable UEFI VM harness (static Rust binary) installer-rs/ production Rust installer (crates/ workspace) scripts/ git/dev tooling (hooks, publish, agent-commit) .githooks/ committed git hooks @@ -62,7 +62,7 @@ the user approves; it never holds root or a shell. - `docs/DEVELOPMENT.md` — host setup, build, VM testing. - `docs/CONTRIBUTING.md` — standards and definition of done. - `docs/GIT-WORKFLOW.md` — how to commit, push and release. -- `installer/doc/VM-BOOT-VERIFICATION.md` — boot evidence. +- `docs/VM-BOOT-VERIFICATION.md` — boot evidence. ## License diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index ce2cf51..20bbf4c 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,12 +1,13 @@ # Architecture -Phoebus currently ships two installer implementations: +Phoebus ships one installer implementation: the **Rust** workspace in +`installer-rs/`. It reproduces the proven encrypted UEFI VM boot path and is the +only implementation on the install path. The retired Bash prototype is kept in +git history, tagged `v0.1.0-bash-reference`; see `docs/BASH-MIGRATION.md` for +the evidence-gated retirement. -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. +The disposable VM harness lives in `installer/tests/vm/` and drives the static +Rust binary. ## Layering diff --git a/docs/BASH-MIGRATION.md b/docs/BASH-MIGRATION.md index 47cb0da..84ebe1c 100644 --- a/docs/BASH-MIGRATION.md +++ b/docs/BASH-MIGRATION.md @@ -196,7 +196,7 @@ only proven boot path. - [ ] Run the full encrypted UEFI install with the static binary, then boot the disk with the ISO detached and unlock LUKS. - [ ] Record the serial log, boot timing, `systemctl is-system-running`, and - the failed-unit count in `installer/doc/VM-BOOT-VERIFICATION.md`. + the failed-unit count in `docs/VM-BOOT-VERIFICATION.md`. - [ ] Update `docs/STATUS.md` so the "Rust VM boot parity" row reflects the static-binary harness. @@ -329,7 +329,7 @@ exit gate has been run and recorded. | 1 | Close product gaps (opencode) | VERIFIED | `cargo test --workspace`: opencode 7 passed, `cli_coverage` 2 passed, clippy rc 0 (`4071c7d`) | | 2 | VM harness on the Rust binary | VERIFIED | static-binary install `INSTALL-RC=0` + detached boot (systemd PID1, running, 0 failed units, LUKS, login) | | 3 | Retire the tests | VERIFIED | `make test` green; `git grep "run_tests.sh\|ai-installer\|installer/lib"` outside docs/installer returns nothing (`875278b`) | -| 4 | Delete the Bash tree | TODO | | +| 4 | Delete the Bash tree | VERIFIED | no tracked file references the Bash installer (`git grep` empty); `make test` green (`TBD4`) | | 5 | Developer tooling (optional) | TODO | | ### Task ledger @@ -350,16 +350,16 @@ exit gate has been run and recorded. | 2.3 | Harness docs updated | VERIFIED | | `installer/tests/vm/README.md`, `run-vm.sh` (`f984b01`) | | 2.4 | VM install with Rust binary | VERIFIED | | serial log: `phoebus-installer 0.1.0`, `===INSTALL-RC=0===`, `NO_SECRET_LEAK`, `===POWEROFF===` (commit `54701bd`) | | 2.5 | VM detached boot | VERIFIED | | `systemd-boot` -> LUKS unlock -> login -> `running`, `0 loaded units listed`, `enp0s2 10.0.2.15/24` (commit `54701bd`) | -| 2.6 | Boot evidence recorded | VERIFIED | | `installer/doc/VM-BOOT-VERIFICATION.md` "Official harness on the static binary" (commit `54701bd`) | +| 2.6 | Boot evidence recorded | VERIFIED | | `docs/VM-BOOT-VERIFICATION.md` "Official harness on the static binary" (commit `54701bd`) | | 3.1 | Bash-test coverage mapping | VERIFIED | | map below; no Bash test lacks a Rust equivalent (`4c59a1f`) | | 3.2 | Golden plan tests; remove `parity.rs` | VERIFIED | | `cargo test -p phoebus-installer --test plan_golden` -> 3 passed; `parity.rs` deleted (`4c59a1f`) | | 3.3 | CI updated | VERIFIED | | `.forgejo/workflows/ci.yml` -> fmt + clippy + test (`875278b`) | | 3.4 | Pre-commit hook updated | VERIFIED | | Bash-suite block removed; image-size + secret scan kept (`875278b`) | | 3.5 | `Makefile` updated | VERIFIED | | `test: test-rust`; `test-bash` removed (`875278b`) | -| 4.1 | Relocate `installer/doc` | TODO | | | -| 4.2 | Delete Bash tree | TODO | | | -| 4.3 | Update all references | TODO | | | -| 4.4 | No dangling references | TODO | | | +| 4.1 | Relocate `installer/doc` | VERIFIED | | `FINDINGS.md`, `VM-BOOT-VERIFICATION.md` -> `docs/`; Bash-only `TESTING.md` deleted (`TBD4`) | +| 4.2 | Delete Bash tree | VERIFIED | | `installer/{bin,lib,tui,config,tests/*.sh,README.md}` removed; `installer/tests/vm/` kept (`TBD4`) | +| 4.3 | Update all references | VERIFIED | | `AGENTS.md`, `README.md`, `docs/{ARCHITECTURE,DEVELOPMENT,CONTRIBUTING,ROADMAP,STATUS,GIT-WORKFLOW}.md` (`TBD4`) | +| 4.4 | No dangling references | VERIFIED | | `git grep "installer/bin\|installer/lib\|ai-installer\|run_tests.sh"` -> nothing (`TBD4`) | ### Recorded gaps (from task 1.5) @@ -446,6 +446,6 @@ detail. `--bootstrap-opencode` (`4071c7d`); harness moved to the static binary (`f984b01`); full VM install `INSTALL-RC=0` + detached boot (systemd PID1, `running`, 0 failed units, LUKS, login) recorded in - `installer/doc/VM-BOOT-VERIFICATION.md`; golden plan tests replace `parity.rs` + `docs/VM-BOOT-VERIFICATION.md`; golden plan tests replace `parity.rs` (`4c59a1f`); CI/hook/Makefile/scripts now gate on Rust only and `git grep` has no dangling Bash reference (`875278b`). No blockers. Phase 4 next. diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 088f3ba..e69b9e1 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -15,6 +15,32 @@ Format: Keep a Changelog. Dates are UTC. `CHANGELOG.md`, and the top-level `AGENTS.md`. - `.gitignore` covering the ISO, build output, transcripts and secrets. +## 2026-09-20 — Retire the Bash installer (migration Phases 0–4) + +### Added +- `phoebus-executor::opencode`: pinned-manifest parsing, architecture + detection, fetch through `Exec`, SHA-256 verification, fail-closed + placeholder checks, extraction and config writer (7 unit tests). +- `--bootstrap-opencode` on the CLI; `PHOEBUS_OPENCODE_MANIFEST` overrides the + embedded manifest for fixture verification. +- `cli_coverage` and golden plan tests (`plan_golden.rs`, `tests/golden/`). +- `docs/BASH-MIGRATION.md`: the evidence-gated retirement plan and ledger. + +### Changed +- The disposable VM harness installs with the static Rust binary; full + encrypted install + detached boot re-verified (systemd PID 1, `running`, + 0 failed units, LUKS, login). +- CI, the pre-commit hook, the Makefile and the commit/publish scripts gate on + Rust only (`cargo fmt`, `clippy`, `test`). +- `installer/doc/VM-BOOT-VERIFICATION.md` and `installer/doc/FINDINGS.md` + moved to `docs/`. + +### Removed +- The Bash installer tree (entry point, libraries, TUI, configuration, shell + test suite and README), retired in favour of `installer-rs/`. The Bash + reference remains tagged `v0.1.0-bash-reference`. The disposable VM harness + under `installer/tests/vm/` is retained. + ## 2026-09-20 — Rust installer parity, desktop, and foundations ### Added diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 81dbc57..15d892e 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -24,7 +24,10 @@ - Keep unit-testable logic pure and in `phoebus-core`; keep privileged effects in `phoebus-executor` behind `ProcessRunner`. -## Bash standards (while it remains) +## Bash standards (developer tooling only) + +`scripts/`, `.githooks/` and the `Makefile` are Bash host tooling, not the +product: - `shellcheck -S warning` clean. - Never `local a="$1" b="$a"` (the dynamic-scoping bug class). Use two `local` @@ -35,10 +38,11 @@ ## Tests - Add a regression test for every meaningful bug (see the tests in - `installer/tests/` and `installer-rs/crates/*/src`). + `installer-rs/crates/*/src`; unit tests live next to the code). - 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. +- Destructive/integration testing only in a disposable qcow2 VM + (`installer/tests/vm/`). +- The Rust suite must pass before a commit. ## Commit messages diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 3c67a84..ba1a4ef 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -6,8 +6,7 @@ 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 + xorriso mtools dosfstools squashfs-tools cpio zstd python3-pexpect # Rust quality gates (names may be versioned; check `apt search rustfmt`) sudo apt install rust-clippy rustfmt @@ -23,19 +22,11 @@ inspection of VM images. `7z`/`p7zip` is useful for reading the reference ISO. 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 +The Bash prototype has been retired (see `docs/BASH-MIGRATION.md`); the Rust +workspace is the only installer. + ```sh cd installer-rs cargo fmt --all -- --check @@ -65,7 +56,8 @@ Never point the harness at a physical disk. The target is always a qcow2 file. ```sh cd /path/to/serve -tar czf installer.tar.gz -C /path/to/phoebus_os installer # or the Rust binary +cp /path/to/phoebus_os/installer-rs/target/x86_64-unknown-linux-gnu/release/phoebus-installer . +cp /path/to/phoebus_os/installer/tests/vm/install.sh . python3 -m http.server 8000 --bind 127.0.0.1 QEMU_BIN=qemu-system-x86_64 \ @@ -117,8 +109,8 @@ prerequisites, and `make test`, `make check`, `make build`, `make static`, ## Continuous integration -`.forgejo/workflows/ci.yml` mirrors the local gates (Bash suite, shellcheck, -Rust suite). It runs only once a Forgejo Actions runner is registered for the +`.forgejo/workflows/ci.yml` mirrors the local gates (`cargo fmt`, `cargo clippy`, +`cargo test`). It runs only once a Forgejo Actions runner is registered for the repository; see Forgejo's documentation for `act_runner`. Until then, run `make test` before pushing. @@ -134,9 +126,7 @@ Restore with `git clone /path/to/phoebus-.bundle phoebus_os`. ## 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`). +1. `make test` (`cd installer-rs && cargo test --workspace`) +2. `cargo fmt --all -- --check` and `cargo clippy --workspace --all-targets` +3. Update `docs/CHANGELOG.md` and `docs/STATUS.md` when behavior changes. +4. Commit (see `docs/GIT-WORKFLOW.md`). diff --git a/docs/GIT-WORKFLOW.md b/docs/GIT-WORKFLOW.md index 5b22859..ed23857 100644 --- a/docs/GIT-WORKFLOW.md +++ b/docs/GIT-WORKFLOW.md @@ -2,9 +2,9 @@ ## 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. +Tracked: source (`installer/tests/vm/`, `installer-rs/crates/`, `scripts/`, +`.githooks/`), `Cargo.toml`/`Cargo.lock`, documentation (`docs/`, `AGENTS.md`, +`README.md`, `installer-rs/README.md`) and tests (`installer-rs/**/tests/`). Ignored (see `.gitignore`): the reference ISO and other images, `installer-rs/target/`, `__pycache__`, `.agent-shell/` transcripts, and any secret material diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index 488ef9b..ef4c71c 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -3,10 +3,11 @@ Rolling note between work sessions. **Update this file before you finish**, then commit it. It should be short and current; use `git log` for detail. -- **Last updated:** commit `e680084` (2026-09-20) -- **Current focus:** repository/context setup and git workflow. -- **Last verified:** Rust installer full encrypted UEFI VM boot with the ISO - detached (`installer/doc/VM-BOOT-VERIFICATION.md`); desktop stack and Flatpak +- **Last updated:** commit `TBD4` (2026-09-20) +- **Current focus:** the Bash installer is retired (migration Phases 0–4, see + `docs/BASH-MIGRATION.md`); `installer-rs/` is the only installer. +- **Last verified:** static Rust binary, full encrypted UEFI VM install + + detached boot (`docs/VM-BOOT-VERIFICATION.md`); desktop stack and Flatpak verified headless. - **Public repo:** (remote `origin`, SSH port 2222). @@ -33,6 +34,8 @@ commit it. It should be short and current; use `git log` for detail. - Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy installed. - Reference ISO is `livegui-amd64-20260913T163055Z.iso` (gitignored). - Forgejo token for API tasks: `~/.config/phoebus/forgejo.token` (0600). +- The VM harness disks are disposable qcow2 files on `/` (not `/tmp`, which is + a small tmpfs on the dev host); never point `DISK` at `/dev/*`. ## Definition of a good stopping point diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 4c36668..d9ce327 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -5,7 +5,7 @@ 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` | +| 1 | Verify the Bash baseline | Done (retired) | tagged `v0.1.0-bash-reference`; retired with evidence in `docs/BASH-MIGRATION.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) | diff --git a/docs/STATUS.md b/docs/STATUS.md index acea019..2277b52 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -30,7 +30,7 @@ userspace = 10.730 s. The committed VM harness (`installer/tests/vm/serial-driver.py` + `install.sh`) drives the **static Rust binary**; the Bash installer is no longer on the install path (Bash migration Phase 2, see -`installer/doc/VM-BOOT-VERIFICATION.md`). +`docs/VM-BOOT-VERIFICATION.md`). ## Matrix diff --git a/scripts/context.sh b/scripts/context.sh index 333f594..8fca062 100755 --- a/scripts/context.sh +++ b/scripts/context.sh @@ -53,7 +53,7 @@ else fi line "last VM verification evidence" -git log -1 --format='%h %ad %s' --date=short -- installer/doc/VM-BOOT-VERIFICATION.md 2>/dev/null \ +git log -1 --format='%h %ad %s' --date=short -- docs/VM-BOOT-VERIFICATION.md 2>/dev/null \ || echo "(none)" line "open markers (TODO/FIXME/XXX)"