Add split promotion preflight

docs/AI_PIPELINES.md

@@ -296,6 +296,17 @@ The wrapper keeps the same safety boundary: existing dataset upload, configured
 YOLO detection and report tooling only. It does not change model configuration
 or bypass the persisted QA/QC evidence requirement.
 
+For a quick post-redeploy check before the long matrix starts, use
+`--preflight-only` with the same positive portfolio and operator manifest. This
+checks local paths, required background categories and the runtime API envelope
+without running inference:
+
+```bash
+PROMOTION_POSITIVE_PORTFOLIO_PATH=artifacts/detection-quality-matrix/multi-sample/aoi1024bg512r3e50-positive/multi_sample_quality_summary.json \
+OPERATOR_SAMPLE_MANIFEST_PATH=storage/operator-data/operator_samples_manifest.json \
+bash scripts/run_split_background_promotion_workflow.sh --preflight-only http://192.168.10.150:1202
+```
+
 The underlying single-category matrix remains available:
 
 ```bash

docs/CODEX_EXECUTION_LOG.md

@@ -6350,3 +6350,43 @@ Open:
 - Run:
   - `PROMOTION_POSITIVE_PORTFOLIO_PATH=... bash scripts/run_split_background_promotion_workflow.sh http://192.168.10.150:1202`
 - Review the generated split-aware promotion report before any retraining, recalibration or default-model decision.
+
+# Sprint 160 - Split-background promotion preflight
+
+## What changed
+
+- Added `--preflight-only` to `scripts/run_split_background_promotion_workflow.sh`.
+- Preflight now checks:
+  - `PROMOTION_POSITIVE_PORTFOLIO_PATH` exists and is readable.
+  - `OPERATOR_SAMPLE_MANIFEST_PATH` exists and is readable.
+  - the manifest contains both `pure_empty_negative` and `sparse_building_context` background categories.
+  - Python and `curl` are available.
+  - the runtime frontend API proxy returns the canonical `data` envelope from `/api/v1/projects`.
+- Updated operator docs, TODO and changelog with the quick post-redeploy preflight command.
+
+## What was tested
+
+- Red step: `python -m pytest tests/test_sprint159_split_promotion_workflow.py -q` failed because `--preflight-only` was not yet present.
+- Ran `python -m pytest tests/test_sprint159_split_promotion_workflow.py -q`: 3 passed.
+- Ran `bash -n scripts/run_split_background_promotion_workflow.sh`.
+- Ran `python -m pytest tests/test_sprint159_split_promotion_workflow.py tests/test_sprint158_promotion_report_split_background.py -q`: 4 passed.
+- Ran `curl.exe -fsS http://192.168.10.150:1202/api/v1/projects`: runtime API proxy returned a canonical `data` envelope.
+- Ran `python -m compileall backend/app`.
+- Ran `python -m pytest` in `backend`: 447 passed, 17 existing Pydantic namespace warnings.
+- Ran `cd frontend && npm run typecheck`.
+- Ran `cd frontend && npm run build`.
+- Ran `cd backend && python -m alembic heads`: `202606120900 (head)`.
+- Ran `cd backend && python -m alembic upgrade head --sql`.
+- Ran `bash -n scripts/live_migration_smoke.sh`.
+- Ran `bash scripts/run_readiness_check.sh`: passed.
+
+## Known limitations
+
+- Preflight is intentionally non-mutating and does not run inference, create datasets, retrain models, activate defaults, fetch providers, fetch weights or change API/database behavior.
+- Full split-background matrix execution still requires redeploying this commit to the Tower/Unraid runtime and running the wrapper in the runtime checkout where the positive portfolio and operator manifest artifacts exist.
+
+## Next recommended pass
+
+- Redeploy/pull on Tower, then run:
+  - `PROMOTION_POSITIVE_PORTFOLIO_PATH=... OPERATOR_SAMPLE_MANIFEST_PATH=... bash scripts/run_split_background_promotion_workflow.sh --preflight-only http://192.168.10.150:1202`
+- If preflight passes, rerun without `--preflight-only` to generate the split summary and split-aware promotion report.

docs/TODO.md

@@ -125,6 +125,7 @@ This file now starts with the current implementation status. Older preparation/b
 - [x] Add a split background-corpus matrix runner and report builder that runs pure-empty and sparse-context matrices separately.
 - [x] Teach the model promotion report to consume split background summaries so only `pure_empty_negative` blocks default promotion and `sparse_building_context` stays review-only.
 - [x] Add one-command operator workflow to run split background matrices and immediately build the split-aware promotion report.
+- [x] Add preflight-only validation for the split-background promotion workflow before long runtime matrices.
 - [ ] 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.