RedBear-OS/local/docs/PATCH-GOVERNANCE.md

# Red Bear OS Patch Governance

## Purpose

This document prevents loss of implemented work. It establishes rules that AI agents
and human contributors must follow when modifying patches, recipes, or build configs.

## Incident: 2026-04-26 Driver Code Loss

A previous agent session removed 8 patches and 9 BINS entries from
`recipes/core/base/recipe.toml` to make the build succeed, instead of fixing
patch conflicts. This deleted GPIO/I2C/UCSI driver source code that took a full
day to implement (commits `dc3f1f996`, `3054adc5d`).

The code was recovered from git history, but this must never happen again.

## Rules

### 0. MEGA-PATCH + P-PATCH DISCIPLINE (HIGHEST PRIORITY)

Each patched component (base, kernel, relibc) uses a two-layer patch model:

- **`redox.patch`** (the mega-patch) — frozen baseline of all Red Bear work. Applied first.
- **`P<N>-<desc>.patch`** (individual patches) — new work done AFTER the mega-patch. Applied after.

**The single rule that prevents the most build failures:**

> **NEVER regenerate `redox.patch` from a source tree that includes P-patch changes.**

If the source tree has P-patches applied (visible in `git status --short` or in the recipe.toml
patches list after `redox.patch`), then `git diff` from that tree will absorb the P-patches into
the mega-patch. The P-patches will then fail to apply on the next clean build because their
changes are already in the mega-patch.

**Correct operations:**

| Operation | How |
|-----------|-----|
| Add new change | Create a new P-patch, add it after `redox.patch` in `recipe.toml` |
| Consolidate P-patches into mega-patch | Generate new `redox.patch` from full source tree, then **remove all P-patches from `recipe.toml`** in the same commit |
| Fix a bug in a P-patch | Create a new P-patch that fixes it (or regenerate just that P-patch) |

**Wrong operations (causes build failures):**

| Wrong operation | What breaks |
|-----------------|-------------|
| Regenerate mega-patch from tree with P-patches, leave P-patches in recipe.toml | P-patches try to re-apply changes already in mega-patch → "Reversed or previously applied" |
| Edit mega-patch by hand | Line counts go wrong, hunks fail, impossible to debug |
| Remove P-patches from recipe.toml without folding into mega-patch | Changes are lost entirely |

**Incident log:**

| Date | What happened | Root cause | Fix |
|------|---------------|-----------|-----|
| 2026-05-29 | `validate-patches base` showed mega-patch with 100+ hunk failures, P10/P11/P12 also failing | Mega-patch was regenerated from a source tree that included P-patch changes. Individual P-patches touched same files (`init/src/main.rs`) as mega-patch, causing overlap. | P10/P11/P12 are genuinely new work on top of the mega-patch (not absorbed). The validation failure was from the mega-patch itself being stale for some hunks. Fix: regenerate mega-patch from a clean mega-patch-only tree, then re-apply P-patches. |

### 1. Never remove patches to fix build failures

When a patch fails to apply:

- **Rebase the patch** against the current cumulative state
- **Fix the context lines** so the hunk applies cleanly
- **Split the patch** if only some hunks fail (keep the working hunks)
- **Document** the failure reason in the patch file header

Do NOT remove the patch from the recipe.toml patches list without explicit
user approval. If a patch must be temporarily disabled, comment it with a TODO
explaining why and what needs to be fixed.

### 2. Never remove BINS entries to fix build failures

When a driver binary fails to compile:

- **Fix the compilation error** in the driver source
- **Add the driver to EXISTING_BINS** filter if source is incomplete
- **Document** the failure

Do NOT remove the driver from the BINS array without explicit user approval.

### 3. Patch ordering matters

Patches in `recipes/core/base/recipe.toml` must be applied in the listed order.
Some patches have interdependencies:

- `P2-acpi-i2c-resources.patch` must apply before `P2-daemon-hardening.patch`
  (workspace entries reference source files created by the former)
- `P2-boot-runtime-fixes.patch` modifies hwd/acpi.rs (must apply cleanly to upstream)
- `P2-init-acpid-wiring.patch` adds 41_acpid.service and pcid-spawner retry logic
  (acpid spawn removal is in P2-boot-runtime-fixes, do NOT duplicate)

When reordering patches, test the FULL chain: remove source, rebuild, verify.

### 4. Recipe.toml is tracked, source trees are not

`recipes/core/base/recipe.toml` is git-tracked. Changes to it are durable.
`recipes/core/base/source/` is a fetched working copy — destroyed by `make clean`,
`make distclean`, source immutable archived, and provision-release.

Any change to source/ MUST be preserved as a patch in `local/patches/base/`.

### 5. Before removing anything, check git history

```bash
git log --oneline --all -- <file>
```

If a previous commit added substantial work (driver implementations, features),
the removal MUST be approved by the user. Agent sessions MUST NOT delete
implemented work to bypass build failures.

### 6. Build validation after patch changes

After ANY change to the patches list or patch files:

1. Remove the source tree: `rm -rf recipes/core/base/source`
2. Full rebuild: `REDBEAR_ALLOW_PROTECTED_FETCH=1 CI=1 make r.base`
3. Verify NO "FAILED" or "rejects" in output
4. Verify all expected binaries in stage: `ls stage/usr/bin/ stage/usr/lib/drivers/`
5. Full image build: `CI=1 make all CONFIG_NAME=redbear-full`

## Known Issues

| Patch | Status | Notes |
|-------|--------|-------|
| P2-acpid-core-refactor.patch | Needs rebasing | 13/15 hunks fail on acpid/scheme.rs; removed from recipe.toml with TODO |
| P2-acpi-i2c-resources.patch | Recovered & rebased → P2-i2c-gpio-ucsi-drivers.patch | Original couldn't apply to current source revision; extracted driver sources, fixed PCI API calls (try_mem→map_bar, try_map_bar→map_bar), regenerated as P2-i2c-gpio-ucsi-drivers.patch (5938 lines, 32 files) |
| P2-boot-runtime-fixes.patch | Needs rebasing | Context lines from monolith split are stale; hwd/acpi.rs hunk fails on clean upstream |
| P2-init-acpid-wiring.patch | Deduplicated | Removed acpi.rs hunk that duplicated P2-boot-runtime-fixes |

## Recipe.toml Fix Log

| Date | Change | Why |
|------|--------|-----|
| 2026-04-30 | Recovered I2C/GPIO/UCSI drivers | P2-acpi-i2c-resources.patch couldn't apply; regenerated as P2-i2c-gpio-ucsi-drivers.patch (5938 lines, 12 drivers: gpiod, i2cd, amd-mp2-i2cd, dw-acpi-i2cd, intel-lpss-i2cd, i2c-interface, intel-gpiod, i2c-gpio-expanderd, i2c-hidd, intel-thc-hidd, ucsid, acpi-resource) |
| 2026-04-30 | Fixed amd-mp2-i2cd PCI API | .try_mem() removed from PciBar; replaced with PciFunctionHandle::map_bar(0) |
| 2026-04-30 | Fixed intel-thc-hidd PCI API | .try_map_bar() removed from PciFunctionHandle; replaced with .map_bar(0) |
| 2026-04-30 | Added P0-bootstrap-workspace-fix.patch | [workspace] in bootstrap Cargo.toml prevents parent workspace auto-detection; fixes base-initfs from-scratch build |
| 2026-04-30 | Added symlinks to integrate-redbear.sh | P0-bootstrap-workspace-fix.patch and P2-i2c-gpio-ucsi-drivers.patch symlinks now auto-created |
| 2026-04-26 | Restored 8 removed patches | Agent deleted them to bypass conflicts; restored all from git HEAD |
| 2026-04-26 | Restored 9 BINS entries | Agent deleted i2cd, gpiod, ucsid, etc. to bypass missing sources |
| 2026-04-26 | Added EXISTING_BINS grep loop | Gracefully handles missing driver source instead of build failure |
| 2026-05-29 | Added P12-init-fix-init-debug-import.patch | P11 introduced `init_debug` calls but forgot to import `init_debug` — `use crate::color::{init_error, init_warn, ...}` missing `init_debug`. Build error: `cannot find function init_debug in this scope`. |
| 2026-05-29 | Documented mega-patch discipline (Rule 0) | Recurring patch corruption caused by regenerating mega-patch from trees that include P-patches. Created Rule 0 in PATCH-GOVERNANCE.md and updated AGENTS.md. |