Updates the doc to reflect the 2 follow-on improvements to
collision detection:
- Phase 5.1 added 'recipe files' source (handles the 39 recipes
with [[package]].files dict). Out-of-scope #1 in this doc
marked as DONE.
- Phase 5.4 added --selftest mode with 8 regression cases wired
into the pre-push hook. Future-work item #4 added for property-
based fuzzing (e.g. hypothesis).
Per AGENTS.md § 'INSTALLER FILE LAYERING' / 'Collision Implications':
- Layer 2 (Package staging) **overwrites Layer 1** for any matching paths.
- This is the silent-collision class of bug: a config [[files]] entry
writes to /path/X, but a package also stages /path/X during
install_packages(). Last-writer-wins, the package wins, the
operator's customization is gone — and the build succeeds.
Phase 0 audit confirmed that AGENTS.md's promise of a CollisionTracker
in src/cook/collision.rs was false (the file doesn't exist). Phase 4.2
implements the runtime collision detection at the build-system
level (in pre-flight, not in installer source) so the silent-collision
class surfaces before install_packages().
New file: local/scripts/verify-collision-detection.py
- Parses every recipes/<cat>/<pkg>/recipe.toml's [[package]].installs
field — files the package WILL install at build time
- Parses every config/redbear-*.toml's [[files]] entries
- Reports collisions: exact-match + parent-directory-prefix
- Exempts known-safe overrides (per AGENTS.md 'Init Service File
Ownership'): /etc/init.d/*, /etc/environment.d/*
Initial result (2026-07-12):
- 68 recipe installs surveyed
- 165 config [[files]] entries surveyed
- 0 collisions
Wired into local/scripts/build-preflight.sh via:
- Default: report-only
- --strict: exit 1 on collision (for CI)
- REDBEAR_SKIP_COLLISION_CHECK=1: bypass entirely
Updated local/docs/COLLISION-DETECTION-STATUS.md with:
- Phase 4.2 implementation summary
- How the algorithm works
- What it does NOT cover (runtime conflicts, patch-induced, dynamic
generation)
- Recovery options
Honest documentation of the actual state of collision detection:
- Init-service path collisions: WORKING via lint-config
- Package-vs-config runtime collision detection: NOT implemented
(no code anywhere emits the [COLLISION-ERROR] markers
that validate-collision-log.sh looks for)
- Recipe installs manifest: limited utility because no recipe
currently declares installs
Phase 1 follow-up: implement runtime collision detection in
local/sources/installer/src/ to match the broken AGENTS.md
promise (already updated in the prior commit).
vasilito