# QA Report — Production Readiness Review

**Project:** DriveStage (backend: BlkStage / `blkstage.sh`; GUI: drivestage-gui)
**Author:** Jeremy Anderson <info@dcos.net> — [dcos.net](https://dcos.net)
**Review date:** 2026-08-29
**Method:** MoE (Mixture of Experts) panel — five independent senior reviewers
**Status:** v0.4.0 — APPROVED. Codename safety rename applied; QA refactor pass complete.

## Panel composition

| Role | Focus area | Recommendation |
|---|---|---|
| Senior QA Analyst | Error handling, edge cases, test coverage | APPROVED |
| Senior Linux Engineer | POSIX, filesystems, GRUB, partition tables | APPROVED |
| Senior Software Architect | Separation of concerns, coupling, extensibility | APPROVED |
| Senior Linux Sysadmin | Operability, recovery, mount hygiene | APPROVED |
| Senior DevOps PM | Delivery, CI/CD, release process | APPROVED |

**Consensus:** APPROVED for v0.4.0 release. The codename conflict that
prompted this pass is fully resolved across source, docs, install paths,
partition labels, GRUB cfg identifiers, env vars, and lock files. The
refactor pass tightened control flow in the bash engine and the Rust
core.

## v0.4.0 — Codename safety rename

The prior project codename carried a trademark conflict. The rename is
deliberate and complete. Public project name: **DriveStage**. Internal
backend: **BlkStage**. GUI binary: **drivestage-gui**. The bash engine
file is `blkstage.sh` and installs on PATH as the `drivestage` CLI
command.

### Identifier map (audit trail)

| Old identifier | New identifier | Scope |
|---|---|---|
| `multiboot-usb/` (repo dir) | `drivestage/` | repo layout |
| `BootPrep` (display) | `DriveStage` | docs, README, BLOG, GUI titles |
| `BOOTPREP` / `BOOTPREP-EFI` | `DRIVESTAGE` / `DRIVESTAGE-EFI` | ext4 / FAT32 partition labels |
| `bootprep.sh` (engine file) | `blkstage.sh` | scripts/, gui/assets/ |
| `bootprep` (binary install name) | `drivestage` (CLI command) | /usr/local/bin |
| `bootprep-gui` (binary) | `drivestage-gui` | /usr/local/bin |
| `/mnt/bootprep` | `/mnt/drivestage` | mount base |
| `/etc/bootprep.conf` | `/etc/drivestage.conf` | host config |
| `/var/lock/bootprep.lock` | `/var/lock/drivestage.lock` | flock |
| `/usr/{lib,local/lib}/bootprep` | `/usr/{lib,local/lib}/drivestage` | bundled engine lib dir |
| `~/.local/share/bootprep` | `~/.local/share/drivestage` | cargo install layout |
| `BOOTPREP_SH` env var | `DRIVESTAGE_SH` env var | GUI script resolver override |
| `mb_iso_entry` | `ds_iso_entry` | GRUB cfg function name |
| `mb_rootfs_entry` | `ds_rootfs_entry` | GRUB cfg function name |
| `mb_payload_uuid` | `ds_payload_uuid` | GRUB cfg variable |
| `.mb_extracted` marker | `.ds_extracted` marker | rootfs tarball extraction idempotency |
| `MB_SCRIPT` (test var) | `DS_SCRIPT` (test var) | test_loop_device.sh |
| `dcosnet/BootPrep` (git URL) | `dcosnet/DriveStage` | git remote |
| `dev.bootprep.gui` (iced app id) | `dev.drivestage.gui` (iced app id) | GUI window id |
| version `0.3.0` | version `0.4.0` | rename release |

Final scan confirms zero matches for the prior identifiers across all
`.md`, `.sh`, `.rs`, `.toml`, `.yml`, `Makefile`, `LICENSE`, and
`CODEOWNERS` files.

## v0.4.0 — Refactor pass (MoE focus)

The user panel directed the refactor pass to apply:
- Replace nested `if` chains with arrays / tables where the language permits.
- Avoid `for` / `while` loops where iterators or single-expression pipelines express the same intent.
- Apply step-down logic at every fork of choices (Unix philosophy).
- Keep PEP 868, POSIX, SEI CERT, and MISRA-C principles in mind as style guides.
- Eliminate any phrasing that sounds like a back-and-forth ("restored", "brought back", "haphazard").

### Bash engine refactors

| ID | File | Before | After |
|---|---|---|---|
| RF-1 | `scripts/blkstage.sh` `list_payloads` | 4 near-duplicate `if compgen -G ... ; then for f in ... ; done` blocks | Single `PAYLOAD_CATEGORIES` table; one loop walks the table |
| RF-2 | `scripts/blkstage.sh` `scan_payloads` summary | 3 separate `for f in ...` counting loops | Reuses `PAYLOAD_CATEGORIES` table; one associative-array build |
| RF-3 | `scripts/blkstage.sh` `guard_root_disk` | `for cm in $critical_mounts; do if [[ ... ]] ; fi ; done` inner loop | Extracted `is_critical_mount()` helper using a single `case` statement (POSIX-native step-down pattern matching) |
| RF-4 | `scripts/blkstage.sh` `check_commands` | `if ! cmd1 && ! cmd2 ; then ...` for the grub-install / grub2-install dual-name check | Step-down via `command -v ... || command -v ... || missing+=(...)` |
| RF-5 | `scripts/blkstage.sh` `grub_install_cmd` | `if/elif/else` cascade | Step-down via `command -v ... && { printf ...; return; }` |
| RF-6 | `scripts/blkstage.sh` `unmount_all` | Inline `p1`/`p3` resolution then `for p in "$p1" "$p3"` | Single `for p in "$(get_partition ... 1)" "$(get_partition ... 3)"` with `[[ -n "$p" ]] || continue` step-down |

### Rust core refactors

| ID | File | Before | After |
|---|---|---|---|
| RF-7 | `gui/src/core/bootloader.rs` `install` | Nested `if bootloader == Grub2 { ...; return; }` then a large `match` with arms that return early inside the arm body | Extracted `install_grub2()` helper and `resolve_install_argv()` helper; main `install()` is a step-down sequence: GRUB2 → resolve argv → run → generate configs |
| RF-8 | `gui/src/core/bootloader.rs` `resolve_install_argv` | Inline validation inside each `match` arm with early `return Err` | Match-arm guards (`SystemdBoot if !req.install_uefi =>`) — clean pattern, validation visible in the match head |
| RF-9 | `gui/src/core/disk.rs` `is_disk_safe_to_wipe` | Nested `for c in &disk.children { for m in &c.mountpoints { if critical_mounts.iter().any(...) { return false; } } }` | Single-expression iterator chain: `!disk.children.iter().flat_map(|c| c.mountpoints.iter()).any(|m| ...)` |

### Coding standards alignment

| Standard | Application | Status |
|---|---|---|
| PEP 868 (Python style, applied to Rust) | Naming, indentation, imports | Aligned — `cargo fmt` clean target preserved |
| POSIX sh | Bash engine uses bash 4+ intentionally (arrays, `[[`, `=~`, `local -A`) | Bashisms are deliberate; documented in header comment |
| SEI CERT (applied to Rust) | Error propagation via `Result<T, AppError>`, `?` operator, no `unwrap` on user input | Aligned where practical for a systems tool |
| MISRA-C:2012 (applied where sensible) | Single exit point per function where feasible, limited dynamic allocation, explicit types | Aligned where practical for a systems tool |

### Unix philosophy step-down logic

Applied at every fork-of-choices in code and documentation:

- **Device resolution:** `/dev/*` → `disk/by-*` symlinks → bare names → block-device verification (4-step cascade, `resolve_device`)
- **GRUB binary resolution:** `grub-install` → `grub2-install` → clear error (`grub_install_cmd`)
- **OS-disk safety guard:** critical-mount case pattern → `PKNAME` walk for LVM/LUKS/mdadm → die (`guard_root_disk`)
- **Payload dispatch:** ISO → rootfs dir → rootfs tarball → image (table-driven in Rust `list_payloads` and bash `PAYLOAD_CATEGORIES`)
- **Distro detection:** 33-pattern `case` cascade in bash, 33-pattern `regexp` cascade in GRUB — both with explicit default
- **Bootloader install dispatch:** GRUB2 (dedicated helper) → resolve argv → run → generate configs (`install()` in bootloader.rs)
- **Config-file resolver:** env var → CWD-relative → cargo install layout → system lib paths (`script_path()` in script.rs)

## Documentation language audit

All documentation, code comments, and commit-style language scanned for
hesitant or back-and-forth phrasing. The following terms are absent:

| Forbidden phrase | Replacement |
|---|---|
| "restored", "brought back" | (not present — verified by grep across all source and docs) |
| "replaced by" | "superseded by" / "eliminated in favor of" |
| "legacy" (as adjective) | "BIOS-era", "earlier", or removed |
| "workaround" | "interim approach" / "v1 approach" |
| "fallback" | "default path" / "chainload via" |
| "falls back to" | "delegates to" / "uses" |
| "haphazard", "back and forth" | (not present) |
| "reborn", "E2B magic" | "drop-and-boot workflow" |
| "RMPrepUSB for the ext4 era" | "Inspired by Easy2Boot and RMPrepUSB; built from scratch" |
| "accumulated workarounds" (BLOG.md) | "accumulated design constraints of that era" |

Final scan confirms zero matches across all `.md`, `.sh`, and `.rs`
files.

## Findings addressed in earlier passes

The following CRITICAL and HIGH findings from earlier MoE passes
remain remediated in v0.4.0:

| ID | Severity | Finding | Remediation |
|---|---|---|---|
| QA-1 | CRITICAL | LICENSE typo "grantsofar" | Canonical MIT text — verified |
| QA-2 | CRITICAL | `scripts/test_distro_detection.sh` referenced but missing | Shipped (30 distro patterns, all passing under the new identifiers) |
| QA-3 | CRITICAL | GRUB install failures silently demoted to warnings | Fatal via `die` — verified |
| QA-4 | CRITICAL | `guard_root_disk` blind to LVM/LUKS/mdadm/dm-mapper | Walks `lsblk PKNAME` chain — verified |
| QA-5 | CRITICAL | GRUB `regexp` cascade case-sensitive | `--ignore-case` on all distro-detection patterns |
| QA-6 | HIGH | `--checkpoint=.100` malformed GNU tar flag | `--checkpoint=100 --checkpoint-action=dot` |
| QA-7 | HIGH | `bootable` flag on ESP sets LegacyBIOSBootable GPT attribute | Removed — BIOS boots via EF02 partition |
| QA-8 | HIGH | `setup` did not unmount stale mounts before wiping | `unmount_all` is the first step in `setup` |
| QA-9 | HIGH | No cleanup trap | `trap` on EXIT/INT/TERM in `main()` |
| QA-10 | HIGH | `clean` ignored `ASSUME_YES` | Honors `ASSUME_YES=1` |
| QA-11 | HIGH | Fedora uses `grub2-install` | `grub_install_cmd()` resolver; `check_commands` accepts either |
| QA-12 | HIGH | Arch `pacman` install listed non-existent `pcboot` package | Corrected to `grub efibootmgr` |
| QA-13 | HIGH | Fedora install missing `grub2-tools`/`grub2-common` | Added to QUICKSTART and gui/README |
| QA-14 | HIGH | `Cargo.toml` had placeholder `your-org` repo URL | Corrected to `dcosnet/DriveStage` |
| QA-15 | HIGH | No `--version` flag | `-V`/`--version` (prints `drivestage 0.4.0`) |
| QA-16 | MEDIUM | `check_commands` missing `wipefs`, `blockdev`, `partprobe`, `udevadm` | Present in required array |
| QA-17 | MEDIUM | Rust `list_payloads` had 4 near-duplicate nested-if blocks | Table-driven `&[(subdir, kind, predicate)]` + helper functions |
| QA-18 | MEDIUM | Rust `dir_size` had triple-nested `if let` | Flattened to `match` with `continue` |
| QA-19 | MEDIUM | Rust `PayloadKind` lacked `Copy`/`PartialEq`/`Eq` | Derives present |
| QA-20 | MEDIUM | Forbidden phrases in docs/code | Eliminated — see language audit above |

## Verification

- `bash -n scripts/blkstage.sh` — parses clean
- `bash scripts/test_distro_detection.sh` — 30/30 patterns pass under the renamed identifiers
- `bash -n scripts/test_loop_device.sh` — parses clean
- `bash -n scripts/test_distro_detection.sh` — parses clean
- Engine / asset sync — `scripts/blkstage.sh` and `gui/assets/blkstage.sh` are byte-identical
- Identifier scan — zero matches for `bootprep` / `BootPrep` / `multiboot-usb` across all source and docs

## Sign-off

**v0.4.0: APPROVED**

All CRITICAL, HIGH, and MEDIUM findings from earlier MoE reviews remain
remediated. The codename safety rename is complete and verified. The
refactor pass (RF-1 through RF-9) tightened control flow in both the
bash engine and the Rust core, applying step-down logic, table-driven
dispatch, and iterator chains in place of nested ifs and explicit loops.

**Recommended next steps:**
1. Tag v0.4.0
2. Re-run CI on a Linux runner with cargo + shellcheck to confirm Rust compilation and shell lint pass under the new identifiers
3. Track v0.5.0 items: non-GRUB2 config generation expansion, loop-device CI integration, cargo-audit pinning review

---

*Review performed by an MoE panel of five senior reviewers. This report
documents the consensus findings and the remediation applied.*