Document Phase 1 governance and profile surfaces

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
2026-04-14 11:43:37 +01:00
parent 3a0349f0d9
commit 0a6b734071
4 changed files with 219 additions and 15 deletions
@@ -247,44 +247,92 @@ Drive the graphical stack through concrete milestones.

 - Support status is explicit and reproducible.

-## Development Phases
+## Execution Phases

-### Phase A — Structure
+### Phase 1 — Repository discipline and profile reproducibility

- Repository rules
- Profile definitions
+- Establish repository rules for Red Bear-specific work.
+- Make tracked profiles explicit.
+- Reduce duplicated profile wiring through shared config fragments.
+- Keep build helpers aligned with the tracked profile set.

-### Phase B — Minimal system
+**Primary targets**
+
+- `redbear-minimal`
+- `redbear-desktop`
+
+**Acceptance**
+
+- Profile composition is easier to audit.
+- Shared Red Bear service wiring is not copy-pasted across profile files.
+- Repository governance and support-language rules are documented.
+
+### Phase 2 — Minimal system baseline

 - Boot
 - Package management
 - VM networking

-### Phase C — Driver base
+**Acceptance**
+
+- `redbear-minimal` remains the primary reproducible validation baseline.
+
+### Phase 3 — Driver and runtime substrate

 - Shared driver layer
+- Firmware loading
+- Input/runtime service prerequisites

-### Phase D — Graphics
+**Acceptance**

- Wayland
+- The driver/runtime substrate needed by graphics and desktop work is explicitly packaged and wired.
+
+### Phase 4 — Graphics and Wayland path
+
+- Wayland runtime path
 - Qt application bring-up
+- Profile-level graphics integration

-### Phase E — Networking
+**Acceptance**

- Wired networking
+- At least one profile can carry a coherent graphical session path.
+
+### Phase 5 — Wired networking and desktop integration
+
+- Wired networking on real profiles
 - KDE-visible networking path
+- Session-level compatibility surfaces

-### Phase F — Desktop
+**Acceptance**

- KDE session becomes usable
+- Wired networking works in at least one profile with documented limits.

-### Phase G — Hardware validation
+### Phase 6 — KDE session viability
+
+- KWin
+- Plasma shell
+- Session startup packaging
+
+**Acceptance**
+
+- KDE session launch is possible with documented limitations.
+
+### Phase 7 — Hardware validation and support labels

 - One fully validated profile
+- Support matrix and validation evidence

-### Phase H — Wi-Fi
+**Acceptance**

- Experimental expansion
+- Support claims are explicit, reproducible, and tied to a profile.
+
+### Phase 8 — Wi-Fi expansion
+
+- Experimental Wi-Fi support for one chipset family first
+
+**Acceptance**
+
+- Wi-Fi work remains clearly marked as experimental until validated.

 ## Task Template

@@ -325,3 +373,5 @@ Progress should be measured by working profiles, not theoretical completeness.
 - [Linux Driver Compatibility Layer](04-LINUX-DRIVER-COMPAT.md)
 - [KDE Plasma on Redox](05-KDE-PLASMA-ON-REDOX.md)
 - [`local/docs/AMD-FIRST-INTEGRATION.md`](../local/docs/AMD-FIRST-INTEGRATION.md)
+- [`local/docs/repo-governance.md`](../local/docs/repo-governance.md)
+- [`local/docs/PROFILE-MATRIX.md`](../local/docs/PROFILE-MATRIX.md)
@@ -260,9 +260,26 @@ redbear-live.toml
        NOTE: redbear-info is the canonical runtime integration report. Keep it updated when
              Red Bear adds new tools, schemes, services, or hardware integration paths.

+redbear-full.toml
+  └── desktop.toml (mainline)
+  └── redbear-legacy-base.toml     ← Neutralize broken base legacy init scripts
+  └── redbear-legacy-desktop.toml  ← Neutralize broken desktop legacy init scripts
+  └── redbear-device-services.toml ← Shared firmware-loader / evdevd / udev service wiring
+  └── redbear-netctl.toml          ← Shared Red Bear network profile files + netctl boot service
+
+redbear-kde.toml
+  └── desktop.toml (mainline)
+  └── redbear-legacy-base.toml     ← Neutralize broken base legacy init scripts
+  └── redbear-legacy-desktop.toml  ← Neutralize broken desktop legacy init scripts
+  └── redbear-device-services.toml ← Shared firmware-loader / evdevd / udev service wiring
+  └── redbear-netctl.toml          ← Shared Red Bear network profile files + netctl boot service
+
 redbear-minimal.toml
  └── minimal.toml (mainline)
        └── base.toml
+  └── redbear-legacy-base.toml     ← Neutralize broken base legacy init scripts
+  └── redbear-device-services.toml ← Shared firmware-loader / evdevd / udev service wiring
+  └── redbear-netctl.toml          ← Shared Red Bear network profile files + netctl boot service
  └── [packages] redbear-release, redbear-hwutils, redbear-netctl,
                 redox-driver-sys, firmware-loader, evdevd, udev-shim
 ```
@@ -0,0 +1,50 @@
+# Red Bear OS Profile Matrix
+
+## Purpose
+
+This matrix makes the tracked Red Bear profiles explicit so support claims map to a concrete build
+target instead of a vague feature list.
+
+## Validation Labels
+
+- **builds** — configuration and packages are expected to compile
+- **boots** — image is expected to reach a usable boot state
+- **validated** — behavior has been tested on the claimed profile
+- **experimental** — available for bring-up, but not support-promised
+
+## Tracked Profiles
+
+| Profile | Intent | Key Fragments | Current support language |
+|---|---|---|---|
+| `redbear-minimal` | Console + storage + wired-network baseline | `minimal.toml`, `redbear-legacy-base.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / primary validation baseline |
+| `redbear-desktop` | Main Red Bear desktop integration profile without KDE-specific session wiring | `desktop.toml`, `redbear-netctl.toml` | builds |
+| `redbear-full` | Expanded graphics/input/Qt integration target | `desktop.toml`, `redbear-legacy-base.toml`, `redbear-legacy-desktop.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / experimental runtime path |
+| `redbear-kde` | KDE Plasma bring-up profile | `desktop.toml`, `redbear-legacy-base.toml`, `redbear-legacy-desktop.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / experimental desktop path |
+| `redbear-live` | Live and recovery image layered on desktop | `redbear-desktop.toml` | builds |
+
+## Profile Notes
+
+### `redbear-minimal`
+
+- First place to validate repository discipline and profile reproducibility.
+- Should stay smaller and less assumption-heavy than the graphics profiles.
+
+### `redbear-desktop`
+
+- Carries the standard Red Bear desktop-facing package additions.
+- Inherits desktop behavior but avoids the heavier KDE session-specific wiring.
+
+### `redbear-full`
+
+- Used for broader integration work that combines graphics, input, and Qt runtime pieces.
+- Should not be described as fully supported until runtime validation is evidence-backed.
+
+### `redbear-kde`
+
+- Dedicated profile for Plasma/KWin session bring-up.
+- Keep KDE-specific service wiring here instead of leaking it into the generic desktop profile.
+
+### `redbear-live`
+
+- Intended for install, demo, and recovery workflows.
+- Should inherit only stable desktop-profile assumptions unless explicitly documented.
@@ -0,0 +1,87 @@
+# Red Bear OS Repository Governance
+
+## Purpose
+
+This document defines the repository-discipline rules for Red Bear OS so profile work stays
+reproducible, reviewable, and upstream-friendly.
+
+## Core Rules
+
+### 1. Keep Red Bear work isolated
+
+- Put Red Bear-specific source, recipes, scripts, and docs under `local/` whenever possible.
+- Prefer patch files and symlinks over direct edits to upstream-managed source trees.
+- Treat mainline Redox areas as upstream surfaces first, not as the default place for Red Bear
+  customization.
+
+### 2. Profiles are the support surface
+
+Tracked Red Bear profiles are:
+
+- `redbear-minimal`
+- `redbear-desktop`
+- `redbear-full`
+- `redbear-kde`
+- `redbear-live`
+
+Every user-visible feature should name which profile(s) it belongs to.
+
+### 3. Validation claims must be explicit
+
+- `builds` means the package or profile compiles.
+- `boots` means the image reaches a real bootable system state.
+- `validated` means behavior has been tested on the claimed profile.
+- `experimental` means present for bring-up but not support-promised.
+
+Do not describe compile-only work as supported hardware or a working desktop path.
+
+### 4. Prefer shared fragments over duplicated profile logic
+
+- Shared profile file wiring belongs in reusable `config/redbear-*.toml` fragments.
+- Avoid copy-pasting identical service definitions or file payloads across multiple Red Bear
+  profiles.
+- Keep profile-specific behavior in the profile file only when the runtime behavior is actually
+  different.
+
+### 5. Build helpers must match tracked profiles
+
+If a profile is tracked in git, helper scripts and docs should either support it directly or state
+why it is intentionally excluded.
+
+## Profile Intent
+
+### `redbear-minimal`
+
+Primary validation baseline: console, storage, package flow, and wired networking.
+
+### `redbear-desktop`
+
+Main integration profile for desktop-oriented Red Bear services without making KDE the default.
+
+### `redbear-full`
+
+Expanded desktop/integration target that includes more runtime pieces and graphics-path bring-up.
+
+### `redbear-kde`
+
+Dedicated KDE/Plasma bring-up profile.
+
+### `redbear-live`
+
+Live and recovery variant layered on top of the Red Bear desktop path.
+
+## Change Checklist
+
+For any substantial Red Bear change, record:
+
+- objective
+- profile impact
+- files touched
+- validation level (`builds`, `boots`, `validated`, `experimental`)
+- known limitations
+
+## Upstream Sync Discipline
+
+- Rebase/sync through `local/scripts/sync-upstream.sh`.
+- Keep Red Bear-specific diffs easy to audit.
+- Update profile docs when config inheritance or package composition changes.