From f5ea6edf098745d5836b9f5a263a27ea79b67af0 Mon Sep 17 00:00:00 2001 From: Phoebus Date: Sun, 20 Sep 2026 02:57:13 -0700 Subject: [PATCH] chore(docs): add evidence-gated Bash migration plan --- .opencode/command/migrate-bash.md | 23 ++ .opencode/opencode.json | 2 +- docs/BASH-MIGRATION.md | 411 ++++++++++++++++++++++++++++++ 3 files changed, 435 insertions(+), 1 deletion(-) create mode 100644 .opencode/command/migrate-bash.md create mode 100644 docs/BASH-MIGRATION.md diff --git a/.opencode/command/migrate-bash.md b/.opencode/command/migrate-bash.md new file mode 100644 index 0000000..efe2690 --- /dev/null +++ b/.opencode/command/migrate-bash.md @@ -0,0 +1,23 @@ +--- +description: Continue the persistent, evidence-gated migration away from the Bash installer. +agent: build +--- + +Execute the next step of the Bash migration defined in +`docs/BASH-MIGRATION.md`. That file is authoritative: read it first, then +follow its rules exactly. + +1. Read `docs/BASH-MIGRATION.md` and `docs/HANDOFF.md`. +2. Find the lowest-numbered phase whose exit gate is not `VERIFIED`. +3. Run that phase's Verification commands first, to capture a baseline. +4. Do the phase's tasks. After each task, run its Verification and paste the + exact command and observed result into the ledger's Evidence column. +5. Do not mark any task `VERIFIED` unless its test actually ran and passed. If + it cannot run here, mark it `BLOCKED` with the blocker recorded. +6. Do not delete anything from `installer/` until Phase 2's exit gate is + `VERIFIED`. +7. Update `docs/HANDOFF.md` and the ledger's Session log, then commit with + `scripts/agent-commit.sh` and push with `scripts/publish.sh`. + +Report the phase and tasks advanced, the exact verification that passed, and +the commit hash. If nothing could be verified, say so plainly. diff --git a/.opencode/opencode.json b/.opencode/opencode.json index 45f745b..68dd6f7 100644 --- a/.opencode/opencode.json +++ b/.opencode/opencode.json @@ -1,6 +1,6 @@ { "$schema": "https://opencode.ai/config.json", - "instructions": ["docs/OBJECTIVES.md", "docs/ROADMAP.md", "docs/HANDOFF.md"], + "instructions": ["docs/OBJECTIVES.md", "docs/ROADMAP.md", "docs/HANDOFF.md", "docs/BASH-MIGRATION.md"], "permission": { "edit": "allow", "external_directory": { diff --git a/docs/BASH-MIGRATION.md b/docs/BASH-MIGRATION.md new file mode 100644 index 0000000..d7f45a6 --- /dev/null +++ b/docs/BASH-MIGRATION.md @@ -0,0 +1,411 @@ +# Bash migration — persistent execution prompt and evidence ledger + +This file is both the prompt and the progress record for removing the Bash +installer from Phoebus OS. It is authoritative: read it at the start of every +session that touches the migration, and update it before you stop. + +Do not treat this as a design document. Do the work, prove it, record it. + +--- + +## 0. How to use this file + +1. Read `AGENTS.md`, then this file, then `docs/ROADMAP.md` and + `docs/HANDOFF.md`. +2. Run `make context` and `git log --oneline -10`. +3. Find the lowest-numbered phase whose exit gate is not yet `VERIFIED`. +4. Execute only that phase's tasks. Do not start a later phase. +5. After each task, run its **Verification** command and paste the observed + result into the **Evidence** column. Then commit. +6. Before you stop, update `docs/HANDOFF.md` and the **Session log** at the + bottom of this file. + +An agent that skips the verification step has not done the task. There is no +partial credit and no "looks correct". + +--- + +## 1. Mission + +The production installer is the Rust workspace in `installer-rs/`. It has +already reproduced the proven encrypted UEFI VM boot, so the Bash tree in +`installer/` is now a reference/fallback that must be retired. + +Goal: **zero Bash in the shipping installer and its test/verification path**, +with every deletion backed by a passing automated check or recorded VM +evidence. + +Out of scope unless Phase 5 is explicitly requested: developer tooling under +`scripts/`, `.githooks/` and the `Makefile`. Those are host tooling, not the +product, and may remain Bash. + +--- + +## 2. Hard rules (the evidence gate) + +These rules override any instruction to move fast. + +1. **No task advances to `VERIFIED` without executed evidence.** The Evidence + column must contain: the exact command, the observed result (the key output + lines, not a summary), and the commit hash it was run at. "Unit tests pass" + is not evidence; the command and its output are. +2. **Code inspection, compilation, or reasoning never count as verification.** + A task whose Verification is a test must have that test actually run. +3. **A test that cannot run in this environment is `BLOCKED`, never + `VERIFIED`.** Name the blocker and the exact command that would unblock it. +4. **VM tasks require the disposable qcow2 VM.** Never point `DISK` at a + `/dev/*` device. If the host cannot run the VM, the task stays `BLOCKED`. +5. **Do not weaken, delete, or skip a check to make a task pass.** If a + verification fails, fix the cause or mark the task `BLOCKED` with the + failure recorded. +6. **Do not delete anything from `installer/` until Phase 2's exit gate is + `VERIFIED`.** Preserve the proven boot path (AGENTS.md rule 9). +7. **One logical change per commit**, conventional-commit message, via + `scripts/agent-commit.sh`. Never commit the ISO, build output, transcripts + or secrets. +8. **Never send or log secrets.** Use the existing redactor and 0600 secret + files; the VM evidence must include the `NO_SECRET_LEAK` check. + +### Status vocabulary + +| Status | Meaning | +| ------ | ------- | +| `TODO` | Not started. | +| `DOING` | Started, not finished. A blocker must be written next to it. | +| `BLOCKED` | Cannot proceed. The blocker and the unblock command are recorded. | +| `VERIFIED` | The Verification command was run and its raw result is in Evidence. | + +There is deliberately no `DONE`. `VERIFIED` is the only terminal state. + +--- + +## 3. Preconditions + +Record these once under Phase 0 before any migration work. + +- `make doctor` reports the host prerequisites. +- `make test` passes (Bash suite + `cargo test --workspace`). +- `cd installer-rs && cargo fmt --all -- --check` and + `cargo clippy --workspace --all-targets` are clean. +- The reference ISO path and the VM harness variables are known (see + `installer/tests/vm/README.md`). + +--- + +## 4. Phase 0 — Preserve and instrument + +**Tasks** + +- [ ] Tag the current tree as the Bash reference: + `git tag -a v0.1.0-bash-reference -m "Proven Bash installer reference"`. +- [ ] Confirm `installer-rs/crates/phoebus-installer/tests/parity.rs` passes + today, so the Rust plan is known to match the Bash plan before anything + is removed. +- [ ] Write a CLI-coverage test (Rust) that asserts every mode in + `installer/bin/ai-installer:53-73` maps to a Rust CLI path. It should + fail today for `--bootstrap-opencode`. +- [ ] Copy `installer/config/opencode.manifest` into the Rust crate's + resources (e.g. `installer-rs/crates/phoebus-installer/resources/`) and + reference it from the new coverage test. + +**Verification** + +```sh +git tag --list 'v0.1.0-bash-reference' +cd installer-rs && cargo test --workspace --test parity +cargo test --workspace cli_coverage +``` + +**Evidence** + +| Task | Command | Result | Commit | +| ---- | ------- | ------ | ------ | +| tag | | | | +| parity baseline | | | | +| CLI coverage test (expected fail on opencode) | | | | +| manifest relocated | | | | + +**Exit gate:** the reference tag exists, the parity test passes, and the new +coverage test fails *only* on `--bootstrap-opencode`. + +--- + +## 5. Phase 1 — Close the product gaps + +**Tasks** + +- [ ] Add `phoebus-executor/src/opencode.rs` implementing the behavior of + `installer/lib/opencode.sh`: architecture detection, manifest parsing, + fetch through `Exec`, SHA-256 verification, fail-closed on a missing or + placeholder (`^0+$`) checksum, extraction, symlink, and the config + writer. No `sh -c`; every command through `Exec`. +- [ ] Unit-test it with a fixture manifest and the recording/never runner: + (a) good checksum extracts, (b) placeholder checksum is refused, + (c) mismatch is refused and the download is discarded, (d) unsupported + arch is refused. +- [ ] Add `--bootstrap-opencode` to `installer-rs/crates/phoebus-installer/src/main.rs` + so the CLI-coverage test from Phase 0 passes. +- [ ] Port any remaining Bash-only CLI surface (`--backend`, `--ui` if still + meaningful) or record why it is intentionally dropped. +- [ ] Confirm the `sys` binary covers the Bash `ai.sh` action set, or record + the gap as a separate task. + +**Verification** + +```sh +cd installer-rs && cargo test --workspace +cargo test --workspace cli_coverage +cargo clippy --workspace --all-targets +``` + +Plus a manual smoke test of the new flag against a local fixture with a known +SHA-256: + +```sh +phoebus-installer --bootstrap-opencode # with the manifest pointed at the fixture +``` + +**Evidence** + +| Task | Command | Result | Commit | +| ---- | ------- | ------ | ------ | +| opencode executor + tests | | | | +| CLI flag + coverage green | | | | +| dropped-surface rationale | | | | +| sys coverage vs ai.sh | | | | + +**Exit gate:** `cargo test --workspace` passes and `cli_coverage` is green. + +--- + +## 6. Phase 2 — Move the VM harness to the Rust binary (the critical gate) + +The harness currently installs with Bash (`installer/tests/vm/install.sh:41`). +Until it installs with the static Rust binary, deleting Bash would regress the +only proven boot path. + +**Tasks** + +- [ ] Build the static binary: + `RUSTFLAGS="-C target-feature=+crt-static" cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu`. +- [ ] Rewrite the guest-side script to fetch and run the static + `phoebus-installer` binary instead of the Bash installer, keeping the + secret-file handling and the `NO_SECRET_LEAK` scan. +- [ ] Point `installer/tests/vm/README.md` and the serial driver's serve + instructions at the Rust binary. +- [ ] 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`. +- [ ] Update `docs/STATUS.md` so the "Rust VM boot parity" row reflects the + static-binary harness. + +**Verification** + +```sh +# Build: +cd installer-rs && RUSTFLAGS="-C target-feature=+crt-static" \ + cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu + +# Install in the disposable VM (install mode), then boot it detached: +python3 installer/tests/vm/serial-driver.py install +python3 installer/tests/vm/serial-driver.py boot +``` + +The boot evidence must show: LUKS unlock, login, networking, +`systemctl is-system-running = running`, `0 failed units`, and +`NO_SECRET_LEAK`. + +**Evidence** + +| Task | Command | Result | Commit | +| ---- | ------- | ------ | ------ | +| static build | | | | +| guest script uses Rust binary | | | | +| VM install (serial log path) | | | | +| VM detached boot | | | | +| docs updated | | | | + +**Exit gate:** the detached boot evidence above exists and is recorded. Only +then may Phase 3 begin. + +--- + +## 7. Phase 3 — Retire the tests + +**Tasks** + +- [ ] Map each file in `installer/tests/*.sh` to existing Rust coverage. For + each, either cite the Rust test that covers the same behavior or add one. +- [ ] Replace `installer-rs/crates/phoebus-installer/tests/parity.rs` with + golden-file tests that pin the Rust plan output; then delete + `parity.rs`. +- [ ] Remove the Bash suite and `shellcheck` step from + `.forgejo/workflows/ci.yml`. +- [ ] Remove the Bash-suite invocation from `.githooks/pre-commit` (keep the + secret scan and image-size checks). +- [ ] Remove `test-bash` from the `Makefile` and make `test` run the Rust + suite. + +**Verification** + +```sh +cd installer-rs && cargo test --workspace +make test +git grep -n "run_tests.sh\|ai-installer\|installer/lib" -- . ':!docs' ':!installer' +``` + +The `git grep` must return nothing outside `docs/` and the not-yet-deleted +`installer/` tree. + +**Evidence** + +| Task | Command | Result | Commit | +| ---- | ------- | ------ | ------ | +| Bash-test coverage mapping | | | | +| golden plan tests | | | | +| parity.rs removed | | | | +| CI + hook updated | | | | + +**Exit gate:** `make test` is green and `git grep` shows no code reference to +the Bash installer. + +--- + +## 8. Phase 4 — Delete the Bash tree + +**Tasks** + +- [ ] Move `installer/doc/FINDINGS.md` and + `installer/doc/VM-BOOT-VERIFICATION.md` under `docs/` and fix links. +- [ ] Delete `installer/bin/`, `installer/lib/`, `installer/tui/`, + `installer/config/`, `installer/tests/*.sh`, and `installer/README.md`. +- [ ] Update `AGENTS.md`, `README.md`, `docs/ARCHITECTURE.md`, + `docs/DEVELOPMENT.md`, `docs/ROADMAP.md` and `docs/CONTRIBUTING.md` to + remove Bash-installer instructions and shellcheck gates. +- [ ] Update `docs/CHANGELOG.md` and `docs/STATUS.md`. + +**Verification** + +```sh +git grep -n "installer/bin\|installer/lib\|ai-installer\|run_tests.sh" -- . ':!docs/BASH-MIGRATION.md' ':!.git' +make test +``` + +The `git grep` must return nothing. `make test` must pass. + +**Evidence** + +| Task | Command | Result | Commit | +| ---- | ------- | ------ | ------ | +| docs relocated | | | | +| Bash tree deleted | | | | +| references updated | | | | +| no dangling references | | | | + +**Exit gate:** no tracked file references the Bash installer and `make test` is +green. + +--- + +## 9. Phase 5 — Developer tooling (optional, only if requested) + +`scripts/*.sh`, `.githooks/*` and the `Makefile` recipes are host tooling. +Port them to a `cargo xtask` only if the goal is literally zero Bash in the +repository. If done, apply the same evidence gate: the replacement command's +output is the evidence, and the old script may only be deleted once the +replacement is `VERIFIED`. + +--- + +## 10. Ledger + +Phase status is the minimum of its tasks. A phase is `VERIFIED` only when its +exit gate has been run and recorded. + +| Phase | Scope | Status | Exit-gate evidence | +| ----- | ----- | ------ | ------------------ | +| 0 | Preserve and instrument | TODO | | +| 1 | Close product gaps (opencode) | TODO | | +| 2 | VM harness on the Rust binary | TODO | | +| 3 | Retire the tests | TODO | | +| 4 | Delete the Bash tree | TODO | | +| 5 | Developer tooling (optional) | TODO | | + +### Task ledger + +| ID | Task | Status | Blocker (if any) | Evidence | +| -- | ---- | ------ | ---------------- | -------- | +| 0.1 | Tag `v0.1.0-bash-reference` | TODO | | | +| 0.2 | Parity test baseline | TODO | | | +| 0.3 | Rust CLI-coverage test | TODO | | | +| 0.4 | Relocate `opencode.manifest` | TODO | | | +| 1.1 | `phoebus-executor::opencode` | TODO | | | +| 1.2 | Opencode unit tests | TODO | | | +| 1.3 | `--bootstrap-opencode` flag | TODO | | | +| 1.4 | Port/justify remaining CLI surface | TODO | | | +| 1.5 | Confirm `sys` covers `ai.sh` | TODO | | | +| 2.1 | Static binary build | TODO | | | +| 2.2 | Guest script uses Rust binary | TODO | | | +| 2.3 | Harness docs updated | TODO | | | +| 2.4 | VM install with Rust binary | TODO | | | +| 2.5 | VM detached boot | TODO | | | +| 2.6 | Boot evidence recorded | TODO | | | +| 3.1 | Bash-test coverage mapping | TODO | | | +| 3.2 | Golden plan tests; remove `parity.rs` | TODO | | | +| 3.3 | CI updated | TODO | | | +| 3.4 | Pre-commit hook updated | TODO | | | +| 3.5 | `Makefile` updated | TODO | | | +| 4.1 | Relocate `installer/doc` | TODO | | | +| 4.2 | Delete Bash tree | TODO | | | +| 4.3 | Update all references | TODO | | | +| 4.4 | No dangling references | TODO | | | + +--- + +## 11. Session protocol + +**Start:** read this file, confirm the ledger is current, pick the lowest +incomplete phase, run its Verification before changing anything so you have a +baseline. + +**Stop:** run `make test`; update this ledger's rows and the Session log; +update `docs/HANDOFF.md`, `docs/CHANGELOG.md` and `docs/STATUS.md` if behavior +or verification changed; commit with `scripts/agent-commit.sh`; push with +`scripts/publish.sh`. + +Never edit a row to `VERIFIED` in the same commit that changes the code unless +that commit also contains the executed evidence. + +--- + +## 12. Verification command reference + +```sh +# Full quality gate +make test +cd installer-rs && cargo fmt --all -- --check +cd installer-rs && cargo clippy --workspace --all-targets +cd installer-rs && cargo test --workspace + +# Static binary for the live installer environment +cd installer-rs && RUSTFLAGS="-C target-feature=+crt-static" \ + cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu + +# VM harness (never point DISK at /dev/*) +python3 installer/tests/vm/serial-driver.py install +python3 installer/tests/vm/serial-driver.py boot + +# Reference check (should shrink to zero by Phase 4) +git grep -n "installer/bin\|installer/lib\|ai-installer\|run_tests.sh" +``` + +--- + +## 13. Session log + +Append one entry per session, newest last. Keep it short; `git log` has the +detail. + +- `YYYY-MM-DD` — (agent/session) phase worked, tasks moved, verification run, + blocker, commit hash.