docs: Add script maintenance requirements after hierarchy changes

Added new section "Script Maintenance After Hierarchy Changes" to
CONTRIBUTING.md documenting the requirement to review and update
scripts in scripts/ directory after any major source reorganization.

Key points:
- Lists when script review is required (file moves, renames, etc.)
- Identifies scripts that commonly need updates (check_all.sh,
  gen_coverage_report.sh, build_win.sh, gen_assets.sh)
- Provides verification steps to ensure scripts remain functional
- Includes recent example (platform.cc → platform/platform.cc)
- References automated verification via check_all.sh

This prevents issues like the coverage script failing on moved files
or verification scripts missing compilation failures in tools.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

1 files changed, 33 insertions, 0 deletions

diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md
index f41d90e..ae8c35a 100644
--- a/doc/CONTRIBUTING.md
+++ b/doc/CONTRIBUTING.md
@@ -340,3 +340,36 @@ For tests that only need synth or tracker (not both), you can still call `synth_
 
 These are performance-critical APIs and should be called directly, not wrapped by AudioEngine.
 
+### Script Maintenance After Hierarchy Changes
+
+After any major source hierarchy change (moving, renaming, or reorganizing files), you **must** review and update all scripts in the `scripts/` directory to ensure they remain functional.
+
+**When to perform this review:**
+- Moving source files to new directories (e.g., `src/platform.cc` → `src/platform/platform.cc`)
+- Renaming source files or directories
+- Reorganizing the build system (CMake changes, new subdirectories)
+- Changing asset locations or formats
+
+**Scripts that commonly require updates:**
+- `scripts/check_all.sh` - Build verification and testing
+- `scripts/gen_coverage_report.sh` - Code coverage analysis
+- `scripts/build_win.sh` - Windows cross-compilation
+- `scripts/gen_assets.sh` - Asset generation pipeline
+- Any scripts with hardcoded paths or assumptions about file locations
+
+**Verification steps:**
+1. Run `./scripts/check_all.sh` to verify builds and tests still work
+2. Run `./scripts/gen_coverage_report.sh` to ensure coverage tracking handles new paths
+3. Test platform-specific scripts if applicable (`build_win.sh`, `run_win.sh`)
+4. Check for error messages about missing files or incorrect paths
+5. Update documentation if script behavior has changed
+
+**Recent example:**
+When `src/platform.cc` was moved to `src/platform/platform.cc`, the coverage script (`gen_coverage_report.sh`) initially failed with "unable to open /Users/skal/demo/src/platform.cc" due to stale coverage data. The fix required:
+- Adding 'source' to `LCOV_OPTS` ignore list to handle missing source files
+- Enabling automatic cleanup of the `build_coverage/` directory before each run
+- Testing the script to verify it handles the new file structure
+
+**Automation:**
+The `./scripts/check_all.sh` script is designed to catch most issues automatically. Always run it before committing hierarchy changes to ensure no regressions in build or test infrastructure.
+