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

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.