Add background split matrix runner

docs/AI_PIPELINES.md

@@ -245,6 +245,23 @@ detections or treat AI detections as ground truth without QA/QC. The same
 candidate should also pass the background false-positive matrix before it is
 considered as a default:
 
+```bash
+OPERATOR_SAMPLE_MANIFEST_PATH=storage/operator-data/operator_samples_manifest.json \
+OPERATOR_BACKGROUND_SAMPLE_SLUGS="postel_bos lommel_heide kasterlee_bos" \
+QUALITY_MODEL_ASSET_IDS="geointel-building-yolov8s-aoi1024bg512r3e50-pt" \
+QUALITY_TILE_SIZES="512" \
+QUALITY_TILE_OVERLAPS="64" \
+QUALITY_THRESHOLDS="0.35 0.15" \
+BACKGROUND_SPLIT_OUTPUT_DIR=artifacts/detection-hard-negatives/aoi1024bg512r3e50-split \
+bash scripts/run_background_corpus_split_matrix.sh http://192.168.10.150:1202
+```
+
+The split runner writes `background_corpus_split_summary.json` and Markdown
+handoff output with a strict `pure_empty_negative` gate and a separate
+review-only `sparse_building_context` block.
+
+The underlying single-category matrix remains available:
+
 ```bash
 OPERATOR_SAMPLE_MANIFEST_PATH=storage/operator-data/operator_samples_manifest.json \
 OPERATOR_BACKGROUND_CATEGORIES="pure_empty_negative" \

docs/CODEX_EXECUTION_LOG.md

@@ -6235,3 +6235,43 @@ Open:
   - `OPERATOR_BACKGROUND_CATEGORIES="pure_empty_negative"` for the strict default-promotion false-positive gate.
   - `OPERATOR_BACKGROUND_CATEGORIES="sparse_building_context"` for contextual review evidence.
 - Retrain or recalibrate the inactive AOI1024 local model candidate only after those two matrices are available.
+
+# Sprint 157 - Background split matrix runner
+
+## What changed
+
+- Added `scripts/run_background_corpus_split_matrix.sh` as the operator wrapper for the next Tower run.
+- The wrapper runs `scripts/run_operator_hard_negative_detection_matrix.sh` twice:
+  - `OPERATOR_BACKGROUND_CATEGORIES="pure_empty_negative"` for the strict default-promotion false-positive gate.
+  - `OPERATOR_BACKGROUND_CATEGORIES="sparse_building_context"` for review-only contextual evidence.
+- Added `scripts/build_background_corpus_split_report.py` to combine both summaries into:
+  - `background_corpus_split_summary.json`
+  - `background_corpus_split_summary.md`
+- The combined report records `strict_default_gate`, `context_review`, `passes_zero_detection_gate`, max detection counts and the recommended next step.
+- Added readiness coverage for the new Python and Bash scripts.
+- Updated operator pipeline docs, TODO and changelog.
+
+## What was tested
+
+- Added regression coverage in `backend/tests/test_sprint157_background_split_matrix_runner.py`.
+- Ran `python -m pytest tests/test_sprint157_background_split_matrix_runner.py -q`.
+- Ran `python -m pytest tests/test_sprint157_background_split_matrix_runner.py tests/test_sprint156_background_corpus_classification.py tests/test_sprint132_operator_hard_negative_matrix.py -q`: 9 passed.
+- Ran `python -m py_compile scripts/build_background_corpus_split_report.py`.
+- Ran `bash -n scripts/run_background_corpus_split_matrix.sh`.
+- Ran `python -m compileall backend/app`.
+- Ran `python -m pytest` in `backend`: 443 passed.
+- Ran `cd frontend && npm run typecheck`.
+- Ran `cd frontend && npm run build`.
+- Ran `bash scripts/run_readiness_check.sh`.
+- Ran `cd backend && python -m alembic heads` and `cd backend && python -m alembic upgrade head --sql`.
+- Ran `bash -n scripts/live_migration_smoke.sh` and `bash -n scripts/run_background_corpus_split_matrix.sh`.
+
+## Known limitations
+
+- This pass adds orchestration/report tooling only. It does not run live inference on Tower, retrain YOLO, rerun the split matrices or change any model default.
+- No backend API contract, database migration, provider fetching, fake detection output or model download behavior changed.
+
+## Next recommended pass
+
+- Rebuild/redeploy the runtime, regenerate the operator manifest if needed, then run `scripts/run_background_corpus_split_matrix.sh` against `http://192.168.10.150:1202`.
+- Use the emitted split report to decide whether to retrain, recalibrate thresholds or keep the AOI1024 candidate operator-only.

docs/TODO.md

@@ -122,7 +122,8 @@ This file now starts with the current implementation status. Older preparation/b
 - [x] Train and gate background-aware `geointel-building-yolov8s-aoi1024bg512r3e50-pt`; it is the strongest positive-AOI candidate so far but remains inactive because full background-candidate false-positive pressure still blocks default promotion.
 - [x] Add explicit operator detection profiles for local model assets: balanced review around threshold `0.15` and conservative high-precision review around threshold `0.35`, both clearly marked as non-default-approved until promotion gates pass.
 - [x] Add pure-empty versus sparse-building contextual background corpus classification to operator manifests, hard-negative matrix filters and YOLO tile provenance.
-- [ ] Retrain or recalibrate against the cleaner pure-empty gate plus separate sparse-context inspection matrix.
+- [x] Add a split background-corpus matrix runner and report builder that runs pure-empty and sparse-context matrices separately.
+- [ ] Rerun split background matrices on Tower after rebuild, then retrain or recalibrate against the cleaner pure-empty gate plus separate sparse-context inspection matrix.
 - [ ] Promote a V1 default building detector only after it passes seven positive AOIs, clean hard-negative/background gates and persisted QA/QC evidence without fake detections or model downloads.
 
 ## Sprint 8 status