RedBear-OS/local/docs/PHASE-0-3-REASSESSMENT.md

Red Bear OS Phase 0–3 Reassessment

Purpose

This document reconciles the current public execution plan in docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md with the older hardware-oriented roadmap in local/docs/AMD-FIRST-INTEGRATION.md.

The goal is to make Phase 0 through Phase 3 readable in terms of what is built, what is boot/runtime wired, and what is actually validated.

Validation States

• builds — code or profile compiles successfully
• boots — image or service path reaches a usable boot/runtime state
• validated — behavior has been exercised with real evidence for the claimed scope
• experimental — available for bring-up but not support-promised

This repo should not treat “compiles” as equivalent to “validated”.

Why this reassessment exists

Two active documents describe the early Red Bear roadmap differently:

• docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md is the canonical public execution plan.
• local/docs/AMD-FIRST-INTEGRATION.md is the older AMD-first technical roadmap.

They are both useful, but they number phases differently:

• docs/07 uses a product-enablement framing (Phase 1 repository/profile structure, Phase 2 minimal-system baseline, Phase 3 driver/runtime substrate).
• AMD-FIRST uses a hardware-enablement framing (P0 ACPI boot, P1 driver infrastructure, P2 AMD display, P3 input + POSIX).

This document is the bridge for Phase 0–3 discussions.

Phase 0 — Bare-metal boot and ACPI baseline

Source of truth

• local/docs/AMD-FIRST-INTEGRATION.md
• Root AGENTS.md status summary

Scope

• AMD bare-metal bootability
• ACPI checksums and table handling
• shutdown/reboot/power-method support
• SMP/x2APIC-era platform readiness

Current status

• builds — yes
• boots — yes
• validated — yes, at the platform/boot level described in the AMD-first notes

Notes

Phase 0 is not part of the public docs/07 numbering, but it remains a real prerequisite in the AMD-first implementation history and should stay visible when discussing early Red Bear progress.

Phase 1 — Repository discipline and profile reproducibility

Source of truth

• docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md
• local/docs/repo-governance.md
• local/docs/PROFILE-MATRIX.md

Scope

• tracked profile definitions
• shared config fragments instead of duplicated wiring
• helper scripts aligned with tracked profiles
• support-language and validation-language rules

Current status

• builds — yes
• boots — indirectly supported by later profile builds
• validated — partially, in the sense that redbear-minimal and redbear-desktop were used as reproducibility targets during the Phase 1 cleanup

Implemented evidence

• config/redbear-*.toml shared fragment refactor
• local/docs/repo-governance.md
• local/docs/PROFILE-MATRIX.md
• local/scripts/build-redbear.sh profile coverage updates

Remaining caution

Phase 1 is structurally in good shape, but support labels still need to be used consistently in phase-level docs.

Phase 2 — Minimal-system baseline

Source of truth

• docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md
• local/docs/NETWORKING-RTL8125-NETCTL.md
• local/docs/REDBEAR-INFO-RUNTIME-REPORT.md

Scope

• bootable minimal profile
• package-management baseline
• VM networking baseline

Current status

• builds — yes
• boots — helper and validation surfaces now exist for the VM path
• validated — partially; the repo now has explicit validation helpers, but this still needs continued real runtime use to graduate from baseline bring-up to stronger support claims

Implemented evidence

• redbear-minimal enables wired-dhcp by default
• redbear-info reports VirtIO VM networking visibility
• local/scripts/validate-vm-network-baseline.sh
• local/scripts/test-vm-network-qemu.sh
• local/scripts/test-vm-network-runtime.sh

Remaining caution

Phase 2 should continue to be described as a baseline. It now has build-time, launch-time, and runtime check paths, but that is still not the same as broad hardware validation.

Phase 3 — Driver and runtime substrate

Source of truth

• docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md
• local/docs/AMD-FIRST-INTEGRATION.md

Correct framing

The public plan's wording is the correct top-level framing:

Driver and runtime substrate

The AMD-first wording remains useful as a lower-level technical breakdown:

Input + POSIX

These are not competing scopes. The second explains the concrete components that fulfill the first.

Scope

• shared driver substrate already built in-tree
• firmware loading available as runtime infrastructure
• input/runtime prerequisites such as evdevd and udev-shim
• relibc POSIX surfaces required by downstream consumers

Current status

• builds — yes for the major in-tree Phase 3 components
• boots — partially wired via profile/service configuration
• validated — not yet at the level needed to call the substrate runtime-proven end to end

Built evidence already in tree

• local/recipes/drivers/redox-driver-sys/
• local/recipes/drivers/linux-kpi/
• local/recipes/system/firmware-loader/
• local/recipes/system/evdevd/
• local/recipes/system/udev-shim/
• local/patches/relibc/P3-*.patch

Real remaining work

The main remaining Phase 3 task is not “invent the substrate” — it already exists in-tree. The real gap is runtime and downstream-consumer validation:

• prove the relibc POSIX surfaces against actual consumers
• prove the input path from Redox input sources through evdevd and udev-shim
• keep Phase 3 distinct from later graphics/Wayland/KDE work

Current runtime-validation helpers

• ./local/scripts/test-phase3-runtime-substrate.sh — in-guest runtime check for firmware-loader, udev-shim, evdevd, and their scheme surfaces
• redbear-info --verbose — passive runtime evidence for installed/active integrations

Runtime evidence gathered during reassessment

• redbear-desktop was booted successfully in QEMU with x86_64 UEFI firmware and reached a real login prompt over the serial console.
• pcid-spawner successfully spawned virtio-netd during the guest boot sequence.
• firmware-loader registered scheme:firmware without crashing, even with an empty /usr/firmware/ directory.
• evdevd registered scheme:evdev and udev-shim registered scheme:udev during the same guest boot.
• redbear-info --json inside the guest reported virtio_net_present: true, a configured eth0 address, and live firmware/udev integration evidence.

Recommended interpretation going forward

When discussing the roadmap publicly:

• use docs/07 phase numbering as canonical
• treat AMD-FIRST phase numbering as historical hardware-roadmap context
• always attach validation language (builds, boots, validated, experimental) to claims

Summary

Phase 0 is the AMD-first bare-metal boot foundation.

Phase 1 is structurally implemented and largely cleaned up.

Phase 2 now has an actual VM-network baseline with repo, launch, and in-guest validation helpers.

One practical caveat surfaced during reassessment: the QEMU launch helper also depends on usable x86_64 UEFI firmware on the host. When that firmware is missing, the failure mode is a host-side SeaBIOS/iPXE fallback rather than a guest-side Red Bear runtime failure, so the helper now checks for that prerequisite explicitly.

Phase 3 should be understood as runtime-substrate validation and wiring, not as a brand-new infrastructure buildout from zero.

Quality Assessment

Planning quality

Strong points

• The public plan in docs/07 is clearer and more execution-oriented than the older roadmap.
• Phase 1 and Phase 2 now have concrete helper scripts and docs instead of relying on implicit operator knowledge.
• The profile matrix and governance docs substantially reduce ambiguity about what each tracked profile is supposed to represent.

Weak points

• Historical phase numbering from AMD-FIRST-INTEGRATION.md still differs from the newer public plan, which can confuse progress reporting if the bridge document is not consulted.
• Some status language across the repo still tends to overvalue “builds” relative to “validated”.

Implementation quality

Strong points

• Shared Red Bear config fragments reduced duplication in tracked profiles.
• The VM-network baseline now has layered validation surfaces: repo-level, launcher-level, and in-guest runtime checks.
• redbear-info remains aligned with real integration changes instead of becoming stale.

Weak points

• Runtime validation is still thinner than build validation across the early phases.
• Some local operating docs needed follow-up cleanup to reflect the newer scripts and profile set.

Recommendation

For Phase 0–3 work, prefer closing validation gaps and documentation drift before adding new scope. The early-phase codebase is in a much better structural state now; the main quality risk is no longer missing packages, but overstating readiness before runtime evidence exists.

Phase 4 Handoff Note

Phase 4 should begin from the existing wayland.toml profile, not by jumping straight to KWin. The current repo already contains the smallvil, cosmic-comp, qtwayland, and Mesa software rendering pieces; the highest-value next work is validating the orbital-wayland → smallvil runtime path on QEMU/VirtIO and only then widening to heavier compositor/session stacks.