RedBear-OS/local/docs/BUILD-SYSTEM-ASSESSMENT-2026-07-18.md

# Red Bear OS Build System — Comprehensive Assessment

**Date:** 2026-07-18
**Branch:** `0.3.1`
**Baseline:** Redox snapshot `f55acba68`
**Scope:** Makefile + `mk/*.mk` + Rust cookbook (`src/`) + `local/scripts/` + `config/*.toml` + all build-system documentation
**Method:** Five parallel explore/deep agents inventoried (1) docs, (2) user-facing messages, (3) architecture, (4) error-recovery mechanisms; plus (5) the Phase 1 remediation results (P0–P3) and the Phase 15.0 installer collision-detection work.

---

## Executive Summary

The Red Bear OS build system is **mature, well-defended, and largely self-correcting**. Of the ten error-recovery mechanisms assessed, seven are EFFECTIVE, three are PARTIAL, and none are INEFFECTIVE or MISSING. The Phase 1 remediation closed the largest gaps (.DELETE_ON_ERROR, post-build validate gate, unwrap→Result, BLAKE3 source-content cache, REDBEAR_TAG fingerprint, cache integrity check, runtime collision detection) and also surfaced and fixed a latent production bug in `collect_files_recursive` that silently broke content hashing for every non-root-level source file.

The largest remaining risks are **probabilistic, not structural**:

1. No cryptographic integrity verification of cached pkgar files (mtime + existence only).
2. No retry logic in non-prefix network operations (`download_wget`, `git clone`, binary repo download).
3. Documentation drift: ~18 of ~75 build-system docs are stale, 1 is obsolete (self-labeled), and several duplicate authoritative sources.
4. ~15 of 185 user-facing messages are stale, misleading, or unhelpful — concentrated in `build-redbear.sh` (5), `mk/disk.mk` (8 unmount warnings), and `src/bin/repo.rs` (raw Debug output).

None of these block the build; they degrade observability and operator experience. All are addressable with surgical changes that do not require architectural rework.

---

## Part 1 — Architecture & Internal Organization

### 1.1 Layered Structure

```
┌──────────────────────────────────────────────────────────────────┐
│ Operator                                                         │
│   └── ./local/scripts/build-redbear.sh <target>                  │
│         (canonical entry; .config, prefix staleness, stash, etc) │
└──────────────────────────┬───────────────────────────────────────┘
                           ▼
┌──────────────────────────────────────────────────────────────────┐
│ make all  (Makefile + mk/*.mk — 11 fragments)                    │
│   ├─ config.mk     environment, paths, sentinels                 │
│   ├─ depends.mk    rustup/cbindgen/nasm/just                     │
│   ├─ fstools.mk    cookbook repo binary, installer, redoxfs      │
│   ├─ prefix.mk     cross-compiler sysroot (binary or source)     │
│   ├─ redbear.mk    integrate-redbear.sh (fingerprint-gated)      │
│   ├─ repo.mk       repo cook — the core pipeline                 │
│   ├─ disk.mk       image creation, validation gate               │
│   ├─ qemu.mk / virtualbox.mk                                     │
│   ├─ podman.mk / ci.mk                                           │
│   └─ (validate is a prerequisite of `all`)                       │
└──────────────────────────┬───────────────────────────────────────┘
                           ▼
┌──────────────────────────────────────────────────────────────────┐
│ Cookbook Rust binary  (src/bin/repo.rs)                          │
│   ├─ fetch   src/cook/fetch.rs       source + atomic patches     │
│   ├─ cook    src/cook/cook_build.rs  3-layer cache + build       │
│   ├─ package src/cook/package.rs     PKGAR + stage.toml          │
│   └─ push    install into sysroot                                 │
└──────────────────────────┬───────────────────────────────────────┘
                           ▼
┌──────────────────────────────────────────────────────────────────┐
│ Installer  (local/sources/installer)                             │
│   4-layer install_dir():                                         │
│     1. Config pre-install  [[files]] (postinstall=false)         │
│     2. install_packages()  — package staging                     │
│     3. Config post-install [[files]] (postinstall=true)          │
│     4. User/group creation                                       │
│   CollisionTracker wired across all four layers (Phase 15.0).    │
└──────────────────────────┬───────────────────────────────────────┘
                           ▼
                 build/<arch>/<config>.iso
```

### 1.2 Configuration Hierarchy

```
redbear-full.toml ─┐
                   │ includes
redbear-grub.toml ─┼─► redbear-mini.toml ─► minimal.toml ─► base.toml
                   │      │
                   │      ├─ redbear-legacy-base.toml
                   │      ├─ redbear-netctl.toml
                   │      ├─ redbear-device-services.toml
                   │      └─ redbear-boot-stages.toml
                   │
                   └─ [package_groups] GPU, Wayland, Qt6, KF6, KWin, greeter, SDDM
```

`Config::from_file()` resolves `include = [...]` and expands `[package_groups.<name>]` references recursively (cycle-detected). Explicit `[packages]` entries override group membership. The cookbook `repo` binary sees only the fully-expanded package list.

### 1.3 Build Pipeline (repo cook)

For each recipe in topological order:

1. **Workspace pollution cleanup** — remove orphaned `Cargo.toml`/`Cargo.lock` from `recipes/` root.
2. **Fetch** — git clone / tarball / path source / same_as; protected recipes gated.
3. **Atomic patch application** — `cp -al` staging dir; full success promotes, any failure rolls back.
4. **Three-layer cache check**:
   - Layer A: `SourceContentHash` (BLAKE3 of every source file + recipe.toml + patches).
   - Layer B: `DepHashes` (BLAKE3 of every build dep's PKGAR).
   - Layer C: `--force-rebuild` bypass.
5. **Binary store restore** — if `target/` is missing but `repo/<arch>/` has the pkgar, extract it.
6. **Build** — dispatch to cargo/cmake/meson/configure/make/custom/remote/none template.
7. **ELF auto-dep discovery** — scan DT_NEEDED, map to pkgar providers.
8. **Package** — PKGAR + stage.toml + dep_hashes.toml + source_hash.txt, all atomic.

### 1.4 Canonical Source of Truth

| Layer | Authority |
|-------|-----------|
| Build policy | `local/AGENTS.md` (96KB, 1827 lines) — supersedes all other docs |
| Public-facing policy | `AGENTS.md` (root, 53KB) — subset of `local/AGENTS.md` |
| Build invariants | `local/docs/BUILD-SYSTEM-INVARIANTS.md` |
| Cache design | `local/docs/BUILD-CACHE-PLAN.md` |
| Hardening history | `local/docs/BUILD-SYSTEM-HARDENING-PLAN.md` |
| Collision detection | `local/docs/COLLISION-DETECTION-STATUS.md` (most recently updated) |
| Tool reference | `local/scripts/TOOLS.md` (15 tools) |
| Desktop plan | `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v5.8, 2076 lines) |

---

## Part 2 — Quality & Correctness

### 2.1 Strengths

| Property | Evidence |
|----------|----------|
| Atomic operations | `.partial` + rename pattern across prefix, cook_build, patch staging, hash files. Interrupted operations leave no partial artifacts. |
| Conservative-on-uncertainty | Hash compute failure → rebuild. Corrupt TOML → mtime fallback. Missing dep_hashes → rebuild. The system never silently trusts corrupt state. |
| Defense in depth | Source integrity is protected by 6 layers: atomic patches, local-overlay immutability, source fingerprints, BLAKE3 content hashing, offline-first defaults, git self-heal. |
| Three-layer cache | Content hash + dep hashes + force flag. Catches both source changes and dependency changes that mtime alone would miss. |
| Local-overlay immutability | `is_local_overlay()` is unconditional and un-overridable. The previous `REDBEAR_ALLOW_LOCAL_UNFETCH` escape hatch was removed (commit `cb8b093564`). |
| Protected recipes | ~90 recipes carrying Red Bear patches are gated; only `REDBEAR_ALLOW_PROTECTED_FETCH=1` permits online re-fetch. |
| Phase 15.0 collision detection | `CollisionTracker` in installer catches the D-Bus regression class (Layer 2 overwriting Layer 1) at both build time (Python scan) and runtime (installer). |

### 2.2 Latent Bug Fixed During Phase 1

**`collect_files_recursive` in `cook_build.rs`** computed relative paths from the *current* subdirectory instead of the *root*. Every non-root-level file was hashed as `<unreadable>` because `fs::read` failed on the truncated path. **Impact:** the `SourceContentHash` cache never actually hashed file contents for any file below the root of a source tree — meaning content changes in subdirectories were silently invisible. **Fix:** thread `root` parameter through recursion; also ensure parent dir creation in `DepHashes::write()`.

### 2.3 Correctness Verifications Run During Phase 1

- `cargo check` ✅ clean
- `cargo test --lib cook::cook_build::tests` ✅ 21/22 (1 pre-existing failure in `file_system_loop`, unrelated)
- `cargo clippy --lib` ✅ 0 new warnings (195 pre-existing)
- `make -n` dry-runs ✅ for `all`, `validate`, `redbear`, `cache-restore`, plus all escape hatches

### 2.4 Correctness Gaps (Pre-existing, Not Introduced)

1. **ELF auto-dep loss after binary store restore** — when a recipe is restored from `repo/<arch>/`, the reconstructed `auto_deps.toml` comes from the manifest's declared `depends`, not from DT_NEEDED discovery. Dynamic deps discovered at the original build are lost. Downstream consumers may miss re-build triggers.
2. **Corrupt dep_hashes.toml → silent mtime fallback** — if `dep_hashes.toml` parses as invalid TOML, `DepHashes::read()` returns `None` and the system falls back to mtime. Documented in the test suite but not corrected.
3. **Cached pkgar has no integrity check** — restoration trusts file existence + mtime. A truncated or corrupt pkgar is not caught until extraction (or later).
4. **Layer 3 (postinstall) collisions are suppressed** — by design (intentional overrides), but this means a malicious or accidental config postinstall entry that damages package-provided files would not raise a warning.

---

## Part 3 — Robustness & Error Recovery

### 3.1 Mechanism Scorecard

| # | Mechanism | Detection | Auto-Correction | User Guidance | Workspace State | Rating |
|---|-----------|-----------|-----------------|---------------|-----------------|--------|
| 1 | Stale prefix detection | Effective | Effective (auto `make prefix`, abort on fail) | Clear (shows fork dates) | Clean (`.partial` pattern) | **EFFECTIVE** |
| 2 | Cache restoration | Partial (mtime only) | Partial (warn-only on bad pkgar) | Adequate | Unverified after restore | **PARTIAL** |
| 3 | Patch application | Effective | Effective (atomic rollback) | Excellent (`[ATOMIC]` markers, `.rej` paths) | Immutable | **EFFECTIVE** |
| 4 | Workspace pollution | Effective | Effective (silent cleanup) | Silent (debug log only) | Clean | **EFFECTIVE** |
| 5 | Source tree recovery | Effective | Partial (git self-heal; manual for forks) | Clear | Protected (local-overlay guard) | **EFFECTIVE** |
| 6 | Network failure | Partial | Partial (wget has retry for prefix only) | Adequate | Recoverable | **PARTIAL** |
| 7 | Content-hash cache | Effective | Effective (rebuild on mismatch) | Debug-level only | Clean | **EFFECTIVE** |
| 8 | Binary store restore | Partial | Partial (warn-only, fall through to rebuild) | Warn-only | Partially corruptible | **PARTIAL** |
| 9 | Interrupted build | Effective (.DELETE_ON_ERROR + `.partial`) | Effective | Silent (auto-recovered) | Auto-recovered | **EFFECTIVE** |
| 10 | Protected recipe guard | Effective (~90 recipes) | N/A (prevents damage) | Clear (flag + env var) | Protected | **EFFECTIVE** |

### 3.2 Recovery Paths (Operator-Facing)

```bash
# Light — most auto-correction happens here
./local/scripts/build-redbear.sh redbear-mini

# Medium — wipe target caches, keep sources
./local/scripts/build-redbear.sh --no-cache redbear-mini

# Heavy — distclean + rebuild (preserves local/)
make distclean && ./local/scripts/build-redbear.sh redbear-mini

# Nuclear — wipe everything except local/ sources
make distclean && rm -rf build/ repo/ prefix/ && ./local/scripts/build-redbear.sh redbear-mini
```

### 3.3 Robustness Gaps Requiring Future Work

1. **Cache integrity verification** — `restore-cache.sh --verify` only checks pkgar existence, not BLAKE3. A corrupt cached pkgar propagates silently until extraction. *Recommended fix: store per-pkgar BLAKE3 in the snapshot manifest and verify post-restore.*
2. **Non-prefix network retry** — `download_wget()` in `src/cook/fs.rs` and `git clone` in `fetch.rs` have no retry. A transient blip aborts the build. *Recommended fix: wrap fetch operations with `--tries=3 --timeout=30 --waitretry=5`.*
3. **Binary store post-restore validation** — no check that extracted files match the pkgar's recorded file list. pkgar's signature check at extraction time partially mitigates this; a separate content pass would close the gap.
4. **Auto_deps preservation across binary store restores** — currently lossy. *Recommended fix: copy `auto_deps.toml` from `repo/<arch>/` alongside `dep_hashes.toml`.*

---

## Part 4 — Documentation Quality

### 4.1 Inventory Summary

| Category | Total | CURRENT | STALE | OBSOLETE | ARCHIVED |
|----------|-------|---------|-------|----------|----------|
| Root-level | 5 | 3 | 2 | 0 | 0 |
| `docs/` directory | 7 | 2 | 5 | 0 | 0 |
| `local/AGENTS.md` | 1 | 1 | 0 | 0 | 0 |
| Build-system docs (`local/docs/`) | 16 | 11 | 4 | 1 | 0 |
| Recipe `AGENTS.md` files | 4 | 1 | 3 | 0 | 0 |
| `local/` support docs | 5 | 4 | 1 | 0 | 0 |
| Subsystem plans | 19 | ~16 | ~3 | 0 | 0 |
| Archived + internal | ~18 | — | — | — | 18 |
| **TOTAL** | **~75** | **~38** | **~18** | **1** | **~18** |

### 4.2 Canonical Doc Authority

```
1. local/AGENTS.md                          (96KB — absolute policy authority)
2. AGENTS.md (root)                         (53KB — public-facing subset)
3. local/docs/BUILD-SYSTEM-INVARIANTS.md    (invariants any change must preserve)
4. Feature docs:
   - BUILD-CACHE-PLAN.md
   - BUILD-SYSTEM-HARDENING-PLAN.md
   - COLLISION-DETECTION-STATUS.md
   - RELEASE-BUMP-WORKFLOW.md
5. local/scripts/TOOLS.md                   (15-tool operator reference)
6. README.md                                (project overview, status)
```

### 4.3 Stale / Obsolete / Duplicate Findings

#### A. Should be ARCHIVED (self-labeled or unambiguously superseded)
- `local/docs/BUILD-SYSTEM-IMPROVEMENTS.md` — self-labeled "HISTORICAL POST-MORTEM". Content is tracked elsewhere or abandoned.
- `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` — uses old P0–P6 phase numbering; superseded by `CONSOLE-TO-KDE-DESKTOP-PLAN.md`.
- `local/docs/SLEEP-IMPLEMENTATION-PLAN.md` — references 0.2.4 branch; pre-0.3.1.

#### B. Should be MERGED into authoritative source
- `local/docs/PATCH-GOVERNANCE.md` → fold into `local/AGENTS.md` § "Patch Governance" (already mostly there; only adds 2026-04-26 incident context).
- `docs/06-BUILD-SYSTEM-SETUP.md` → merge mechanics into `AGENTS.md` § "Build Commands"; distro setup into `README.md`.
- `docs/05-KDE-PLASMA-ON-REDOX.md` → mark as historical supplement to `CONSOLE-TO-KDE-DESKTOP-PLAN.md`.

#### C. Should be REDIRECTED (replace content with pointer)
- `recipes/AGENTS.md` → replace with short note pointing to `local/recipes/AGENTS.md` + `local/AGENTS.md`.
- `recipes/core/AGENTS.md` → same; current content describes upstream-Redox pattern, not the local fork reality.

#### D. Need FRESHNESS UPDATES
- `docs/README.md` — date "2026-05-01" → current; v4.0 → v5.8 plan reference; remove per-component GitLab URLs.
- `CONTRIBUTING.md` — rewrite for local fork workflow, `build-redbear.sh`, patch governance.
- `HARDWARE.md` — remove reference to nonexistent `PROFILE-MATRIX.md`.
- `local/docs/LOCAL-FORK-SUPREMACY-POLICY.md` — fix "currently 0.1.0" → "currently 0.3.1".
- `local/docs/GRUB-INTEGRATION-PLAN.md` — update `make all CONFIG_NAME=redbear-grub` → `./local/scripts/build-redbear.sh redbear-grub`.

#### E. Definite duplicates (primary should win)
| Duplicate | Primary |
|-----------|---------|
| `recipes/AGENTS.md` | `local/recipes/AGENTS.md` |
| `recipes/core/AGENTS.md` | `local/AGENTS.md` § "LOCAL FORK MODEL" |
| `docs/05-KDE-PLASMA-ON-REDOX.md` | `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` |
| `AGENTS.md` (root) | `local/AGENTS.md` (intentional subset — keep both) |

### 4.4 Recommended Doc Hygiene Policy

Adopt project-wide: every build-system doc should carry
```markdown
> **Last verified:** YYYY-MM-DD against branch `<branch>`
> **Authority:** Primary | Supplement | Historical
```
The collision-detection, release-bump, and hooks docs already follow this pattern. Standardize it.

---

## Part 5 — User-Facing Messages

### 5.1 Inventory Summary

**Total:** 185 messages across 16 source files.

| Source | Count |
|--------|-------|
| `Makefile` (root) | 11 |
| `mk/config.mk` | 4 |
| `mk/depends.mk` | 4 |
| `mk/disk.mk` | 12 |
| `mk/podman.mk` | 8 |
| `mk/prefix.mk` | 13 |
| `mk/repo.mk` | 5 |
| `mk/qemu.mk` | 2 |
| `mk/redbear.mk` | 3 |
| `mk/virtualbox.mk` | 8 |
| **`local/scripts/build-redbear.sh`** | **50** (largest surface) |
| `src/cook/status.rs` | 4 |
| `src/cook/cook_build.rs` | 18 |
| `src/cook/fetch.rs` | 27 |
| `src/bin/repo.rs` | 9 |
| `src/bin/repo_builder.rs` | 7 |

### 5.2 Overall Quality

| Rating | Count | % |
|--------|-------|---|
| Current + helpful | ~158 | 85% |
| Stale or misleading | 9 | 5% |
| Unhelpful (noise or vague) | 12 | 6% |
| Debug-level (acceptable) | ~10 | 5% |

### 5.3 Stale / Misleading Messages (Action Required)

| ID | File:Line | Current Text | Issue | Fix |
|----|-----------|--------------|-------|-----|
| M18 | `build-redbear.sh:523` | `"Patches are applied by 'repo fetch' via recipe.toml (atomic mechanism)"` | Implies overlay-patch model is primary; local forks are primary now. | Reword: `"Local fork sources are already committed. Recipe patches (for non-fork recipes) are applied atomically by repo fetch."` |
| M19 | `build-redbear.sh:524` | `"Skipping direct patch application (was bypassing cookbook atomicity)"` | References historical behavior. | Integrate into M18 fix or remove. |
| M26 | `build-redbear.sh:569` | `"This may take 30-60 minutes on first build..."` | Stale for redbear-full with 100+ recipes. | `"varies by config (45-120 minutes for redbear-full, less for redbear-mini)"` |
| M46 | `build-redbear.sh:923` | `"Release mode: building from immutable archives (offline)"` | Implies archive-extraction model; actual build uses local forks. | `"Release mode: building from local forks (offline)"` |
| I2 | `mk/redbear.mk:41` | `"Archiving fully-patched source packages..."` | Misleading for fork-based model — forks already have patches committed. | `"Archiving source packages..."` |
| E1 | `mk/podman.mk:47` | `"please set it to 1 in mk/config.mk"` | Wrong location — it's set in `.config`. | `"please set it to 1 in .config"` |
| F10 | `mk/prefix.mk:346` | `"Incomplete build stages. Please re-run the build"` | Vague directive. | `"Incomplete build stages detected. Run 'make prefix' to rebuild the toolchain."` |
| J2 | `mk/virtualbox.mk:10` | `"RedBearOS directory exists, deleting..."` | Branding inconsistency. | `"Red Bear OS directory exists, deleting..."` (or keep as VBox-internal identifier with a comment). |
| Q1 | `src/bin/repo.rs:207,294,297` | `eprintln!("{:?}", e)` | Raw Rust Debug output, no operator context. | Replace with human-readable messages. |

### 5.4 Noisy / Unhelpful Messages

| ID | File:Line | Issue | Fix |
|----|-----------|-------|-----|
| D1, D2, D6, D7 | `mk/disk.mk:8, 9, 107, 109` | Repeated "Warning: failed to unmount" fires every build even when nothing was mounted. | Suppress when error is just "not mounted" (expected); only warn on real failures. |
| A6, A8 | `Makefile:162, 189` | "container is not built" — doesn't tell operator how to build it first. | Add: `"Run 'make container' first to build the Podman image."` |
| B3 | `mk/config.mk:90` | "sccache not found" — no install hint. | Add: `"Install with 'cargo install sccache' or from your package manager."` |
| H2 | `mk/qemu.mk:140` | "Unsupported ARCH" — doesn't list supported arches. | Add the list: x86_64, aarch64, i686, i586, riscv64gc. |

### 5.5 Strongest Messages (Models to Emulate)

The structured error blocks in `build-redbear.sh` (M1, M2, M14, M15, M17, M49) are exemplary:
- State the problem in one line.
- List affected items (forks, recipes, files).
- Provide the exact override or fix command.
- Reference documentation where applicable.

**Example** (M2):
```
REFUSING TO BUILD — FORKS NOT ON CANONICAL BRANCHES
The following forks are on unexpected branches:
  - local/sources/relibc: on 'main' (expected 'submodule/relibc')
  ...
Fix: checkout the correct branch in each fork, or set
     REDBEAR_ALLOW_BRANCH_DRIFT=1 to override.
```

This pattern should be the standard for all error-class messages.

---

## Part 6 — Gaps, Blockers, Improvement Opportunities

### 6.1 No Current Blockers

The build system is fully functional on the canonical path: `./local/scripts/build-redbear.sh redbear-mini` (or `redbear-full`, `redbear-grub`) produces a bootable ISO from a clean checkout. Phase 1 remediation closed the structural gaps; Phase 15.0 closed the runtime collision-detection gap.

### 6.2 Quality Improvement Opportunities (Ordered by Impact)

| # | Opportunity | Effort | Impact | Status |
|---|-------------|--------|--------|--------|
| Q1 | Add per-pkgar BLAKE3 to cache manifest; verify post-restore. | Medium | Closes the largest robustness gap (Mechanism #2). | ✅ Resolved — `BinaryStoreManifest` + `compute_file_blake3_hex` in `cook_build.rs`/`fs.rs`/`repo_builder.rs` |
| Q2 | Wrap `download_wget()` and `git clone` with retry logic matching prefix.mk's wget pattern. | Small | Eliminates the most common transient-failure abort. | ✅ Resolved — `run_command_with_retry()` in `fs.rs`, used by `download_wget` + git clone |
| Q3 | Preserve `auto_deps.toml` in binary store; copy alongside `dep_hashes.toml`. | Small | Closes correctness gap in restored recipes. | ✅ Resolved — publish in `repo_builder.rs`, restore-with-fallback in `cook_build.rs` |
| Q4 | Validate `dep_hashes.toml` parse strictly; on corrupt, log loud + rebuild instead of silent mtime fallback. | Small | Eliminates a silent correctness gap. | ✅ Resolved — `DepHashes::read` returns `Result<Option<Self>, String>` |
| Q5 | Adopt the "Last verified / Authority" header policy for all build-system docs. | Small | Prevents future drift. | ✅ Resolved — doc consolidation commit |
| Q6 | Standardize error-message template across `repo.rs` (replace `{:?}` with human-readable). | Small | Improves operator experience for CLI errors. | ✅ Resolved — `{:?}` → `{:#}` in `repo.rs` |
| Q7 | Suppress `mk/disk.mk` unmount noise for the "not mounted" case. | Trivial | Removes 8 spurious warnings per build. | ✅ Resolved (Tier 1) |
| Q8 | Fix the 9 stale user-facing messages identified in Part 5.3. | Trivial | Removes misleading language. | ✅ Resolved (Tier 1) |
| Q9 | Archive/merge the 3+3+2 stale/obsolete/duplicate docs identified in Part 4.3. | Small | Consolidates doc surface; no behavior change. | ✅ Resolved (Tier 2) |
| Q10 | Replace `recipes/AGENTS.md` and `recipes/core/AGENTS.md` with redirects to `local/AGENTS.md`. | Trivial | Eliminates misleading upstream-Redox-pattern docs. | ✅ Resolved (Tier 2) |

### 6.3 Auto-Correction Capability Summary

The build system auto-corrects the following without operator intervention:

| Failure | Auto-Correction |
|---------|-----------------|
| Stale prefix (fork newer than libc.a) | Auto-runs `make prefix`; aborts on failure. |
| Workspace pollution (orphan Cargo.toml) | Silently removed before every fetch and build. |
| Partially-applied patches | Atomic rollback; source tree never partially patched. |
| Interrupted build (Ctrl-C, OOM) | `.DELETE_ON_ERROR` removes partial targets; `.partial` directories cleaned next run. |
| Damaged git source (no .git) | Auto re-clones from recipe URL. |
| Missing target/ with pkgar in repo/ | Restores from binary store. |
| Source changed without mtime change | BLAKE3 content hash catches it; rebuilds. |
| Dependency pkgar changed | DepHashes catches it; rebuilds. |
| Local-overlay unfetch attempted | Refused; sources are immutable. |
| Protected recipe online fetch attempted | Refused; falls through to offline source. |
| Transient network failure on non-prefix fetch (Q2) | `run_command_with_retry()` retries 3× with exponential backoff (1s/2s/4s). |
| Corrupt cached pkgar that passed mtime check (Q1) | BLAKE3 manifest verification detects mismatch; logs WARN, marks not-restored, forces rebuild. |

The build system does NOT auto-correct:

| Failure | Operator Action Required |
|---------|--------------------------|
| Config-vs-package collision (warn mode) | Read the warning; fix the config or accept it. |
| Fork on wrong branch | Checkout correct branch or set override. |
| Dirty fork working tree at build start | Commit or stash; the script stashes automatically but may need manual unstash on failure. |

---

## Part 7 — Recommended Action Plan

### Tier 1 — Safe, surgical fixes (no behavior change, low risk)

All Tier 1 items are resolved:

1. ✅ **Fix 9 stale messages** (Part 5.3): M18/M19/M26/M46 (`build-redbear.sh`), I2 (`mk/redbear.mk`), E1 (`mk/podman.mk`), F10 (`mk/prefix.mk`), J2 (`mk/virtualbox.mk`), Q1 (`src/bin/repo.rs` as Q6).
2. ✅ **Suppress mk/disk.mk unmount noise** (Part 5.4): D1/D2/D6/D7 gated behind `2>/dev/null || true`; A6/A8 (Makefile), B3 (`mk/config.mk`), H2 (`mk/qemu.mk`) — all enhanced with actionable guidance.
3. ✅ **Archive `local/docs/BUILD-SYSTEM-IMPROVEMENTS.md`** to `local/docs/archived/`.
4. ✅ **Update `LOCAL-FORK-SUPREMACY-POLICY.md`** version reference 0.1.0 → 0.3.1.
5. ✅ **Update `GRUB-INTEGRATION-PLAN.md`** build commands to `build-redbear.sh`.
6. ✅ **Update `docs/README.md`** date stamp and version references (2026-07-18, v6.0 plan).

### Tier 2 — Doc consolidation (content rewrite, requires judgment)

All Tier 2 items are resolved:

7. ✅ **Replace `recipes/AGENTS.md`** with redirect to `local/recipes/AGENTS.md` and `local/AGENTS.md`.
8. ✅ **Replace `recipes/core/AGENTS.md`** with redirect to `local/AGENTS.md` § "LOCAL FORK MODEL".
9. ✅ **Mark `docs/05-KDE-PLASMA-ON-REDOX.md`** as historical supplement; header points to `CONSOLE-TO-KDE-DESKTOP-PLAN.md`.
10. ✅ **Mark `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md`** with authority header pointing to current plan.
11. ✅ **Mark `docs/06-BUILD-SYSTEM-SETUP.md`** as non-canonical; header points to `AGENTS.md` and `README.md`.
12. ✅ **Rewrite `CONTRIBUTING.md`** to reflect local fork workflow, `build-redbear.sh`, patch governance.
13. ✅ **Fix `HARDWARE.md`** — removed reference to nonexistent `PROFILE-MATRIX.md`.

Additional doc hygiene completed:
- ✅ Archived `local/docs/SLEEP-IMPLEMENTATION-PLAN.md` (referenced 0.2.4 branch; pre-0.3.1).

### Tier 3 — Code improvements (gaps from Part 6.2)

All Tier 3 items are resolved:

14. ✅ Q1 — Cache manifest with per-pkgar BLAKE3 + post-restore verify. (`BinaryStoreManifest` in `cook_build.rs`, `compute_file_blake3_hex` in `fs.rs`, manifest write in `repo_builder.rs`)
15. ✅ Q2 — Retry logic for non-prefix fetches. (`run_command_with_retry()` in `fs.rs`)
16. ✅ Q3 — Preserve `auto_deps.toml` in binary store. (publish in `repo_builder.rs`, restore+fallback in `cook_build.rs`)
17. ✅ Q4 — Strict `dep_hashes.toml` parse handling. (`DepHashes::read` returns `Result<Option<Self>, String>`)
18. ✅ Q6 — Standardize error messages in `repo.rs`. (`{:?}` → `{:#}`)

Verification: `cargo check` ✅, `cargo test --lib` ✅ 38/38 (35 existing + 3 new BinaryStoreManifest tests), `cargo clippy --lib` ✅ 0 new warnings, `make -n` dry-runs ✅.

---

## Appendix A — Phase 1 Remediation Status (for reference)

| Item | Status | Files |
|------|--------|-------|
| P0.1 — `.DELETE_ON_ERROR` in root Makefile | ✅ Done | `Makefile` |
| P0.2 — Test harness for cook_build | ✅ Done (21 tests + latent bug fix) | `src/cook/cook_build.rs` |
| P1.3 — Installer runtime collision detection | ✅ Done (Phase 15.0) | `local/sources/installer/{src/collision.rs,src/lib.rs,src/installer.rs,tests/collision.rs}` |
| P1.4 — unwrap→Result in fetch_repo/cook_build | ✅ Done | `src/cook/{fetch_repo.rs,cook_build.rs,fetch.rs}` |
| P2.5 — REDBEAR_TAG fingerprint | ✅ Done | `mk/redbear.mk` |
| P2.6 — Cache integrity check | ✅ Done | `Makefile` |
| P3.7 — Post-build validate gate | ✅ Done | `Makefile`, `mk/disk.mk` |

All changes verified: `cargo check` ✅, `cargo test --lib cook::cook_build::tests` ✅ 21/22 (1 pre-existing), `cargo clippy --lib` ✅ 0 new warnings, `make -n` dry-runs ✅. Nothing has been committed (per project policy — agents do not commit without explicit request).

## Appendix B — Source Files Consulted

**Make layer:** `Makefile`, `mk/config.mk`, `mk/depends.mk`, `mk/disk.mk`, `mk/fstools.mk`, `mk/podman.mk`, `mk/prefix.mk`, `mk/qemu.mk`, `mk/repo.mk`, `mk/redbear.mk`, `mk/virtualbox.mk`, `mk/ci.mk`.

**Cookbook Rust:** `Cargo.toml`, `src/lib.rs`, `src/config.rs`, `src/recipe.rs`, `src/staged_pkg.rs`, `src/bin/repo.rs`, `src/bin/repo_builder.rs`, `src/cook/{fetch.rs, cook_build.rs, package.rs, tree.rs, ident.rs, fs.rs, status.rs}`.

**Scripts:** `local/scripts/build-redbear.sh`, `local/scripts/integrate-redbear.sh`, plus the cache/sync/restore scripts.

**Installer:** `local/sources/installer/{src/lib.rs, src/installer.rs, src/collision.rs, tests/collision.rs}`.

**Docs:** All 75 docs inventoried (Part 4).