diff --git a/AGENTS.md b/AGENTS.md index 0efcfcfe37..072ccc6f48 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -615,6 +615,52 @@ For quirks and driver support specifically: - if duplication is temporarily unavoidable, treat it as convergence work to remove, not as a permanent design. +### Orphan-Patch Supersession Decision Tree + +When `local/scripts/verify-patch-content.sh` reports that a patch in +`local/patches//` is no longer present in the fork HEAD +(orphan), the default action is **NOT** to reapply the patch. Follow +this decision tree instead (per `local/docs/PATCH-PRESERVATION-AUDIT-2026-07-12.md`): + +``` +1. Run 'git -C local/sources/ log --all --oneline -i --grep ' + where is extracted from the orphan's filename. + +2. ALSO check the target file's git log: + 'git -C local/sources/ log --oneline -- ' + +3. Classify the orphan into one of three buckets: + (a) SUPERSEDED upstream + = Red Bear itself rewrote the function and superseded it + (e.g. acpid/mcfg migration). + Action: MOVE patch to local/patches/legacy-superseded-// + ALSO: if the fork's content covers the same need, no other action. + + (b) INTEGRATED via different commit + = Fork already has commits touching the same file/topic, just + under different commit subjects (typical of mega-absorption + patterns). + Action: MOVE patch to local/patches/legacy-superseded-// + Verification: confirm fork's grep shows new equivalent code. + + (c) MISSING-UPSTREAM (genuine gap) + = Fork has no commits touching the topic AND no upstream alternative. + Action: try `patch -p1 --fuzz=5` (file structure may have drifted). + If still fails: requires fork rebase via upgrade-forks.sh. + Mark patch as 'Phase 2.4+ work' and leave in local/patches//. + +Special cases (always SUPERSEDED regardless of fork state): +- 'bump' patches naming 'redox-scheme', 'syscall', or 'rb': managed + automatically by 'sync-versions.sh' (Cat 2 fork version +rb suffix). +- 'ecosystem-pins' patches: managed by Local Fork Supremacy Policy + + AGENTS.md 'Latest-upstream-before-freeze rule'. + +This decision tree is wired into the operator workflow by Phase 2.1 +audit + Phase 2.2 manual review + SUPERSEDED.md audit log entries. +Future fork-upstream sync operators should run 'verify-patch-content.sh' +on every fork upgrade and apply this decision tree before any attempt to +reapply orphan patches. + ### Structure ```