Add detection quality matrix

docs/AI_PIPELINES.md

@@ -182,6 +182,25 @@ Results are honest QA/QC evidence from persisted detections and persisted
 reference `vector_features`; no demo detections, live provider fetches or model
 downloads are introduced by the calibration tool.
 
+For model/tile/threshold selection, use the quality matrix wrapper:
+
+```bash
+REAL_RASTER_PATH=/mnt/user/appdata/geointel/storage/operator-data/geel_orthophoto_wms_512.tif \
+REAL_REFERENCE_VECTOR_PATH=/mnt/user/appdata/geointel/storage/operator-data/geel_grb_gbg_buildings.geojson \
+QUALITY_MODEL_ASSET_IDS="yolov8n-building-segmentation-pt yolov8n-pt" \
+QUALITY_TILE_SIZES="512 640" \
+QUALITY_TILE_OVERLAPS="64" \
+QUALITY_THRESHOLDS="0.50 0.15" \
+bash scripts/run_detection_quality_matrix.sh http://192.168.10.150:1202
+```
+
+The matrix repeats the same persisted real-data workflow for every combination
+and writes `quality_matrix_summary.json` with detection count, QA score,
+precision, recall, F1, mean IoU and false-positive/false-negative counts. The
+rankings `best_by_score`, `best_by_recall` and `best_by_precision` are operator
+decision aids only; GeoIntel still does not download models, seed fixture
+detections or treat AI detections as ground truth without QA/QC.
+
 For visual error inspection, export the persisted QA evidence from a calibration
 summary:
 

docs/CODEX_EXECUTION_LOG.md

@@ -1,3 +1,34 @@
+## Sprint 126 Detection quality matrix tooling (2026-07-07)
+
+Changed:
+- Added `scripts/run_detection_quality_matrix.sh` as an operator-facing model/tile/threshold matrix for the configured-YOLO real-data path.
+- The matrix reuses `scripts/verify_real_data_detection_qa_workflow.sh` for each row so every result is backed by persisted Project, Dataset, AnalysisRun, Detection, QualityCheck, Metric and Export records.
+- The script accepts `QUALITY_MODEL_ASSET_IDS`, `QUALITY_TILE_SIZES`, `QUALITY_TILE_OVERLAPS` and `QUALITY_THRESHOLDS`, writes per-run logs and produces `quality_matrix_summary.json`.
+- The summary reports model asset, tile size, overlap, confidence threshold, detection count, QA score, precision, recall, F1, mean IoU, matches, false positives and false negatives.
+- Added `best_by_score`, `best_by_recall` and `best_by_precision` rankings for operator model-quality decisions.
+- Added readiness syntax coverage and regression coverage in `backend/tests/test_sprint126_detection_quality_matrix.py`.
+- Updated `scripts/README.md`, `backend/README.md`, `docs/AI_PIPELINES.md`, `docs/TODO.md` and `CHANGELOG.md`.
+
+Tested:
+- RED: `python -m pytest backend\tests\test_sprint126_detection_quality_matrix.py -q` failed because `scripts/run_detection_quality_matrix.sh` did not exist.
+- `python -m pytest backend\tests\test_sprint126_detection_quality_matrix.py -q` passed.
+- `python -m pytest backend\tests\test_sprint126_detection_quality_matrix.py backend\tests\test_sprint124_detection_calibration_sweep.py backend\tests\test_sprint125_detection_calibration_evidence_bundle.py -q` passed.
+- `bash -n scripts/run_detection_quality_matrix.sh` passed.
+- `bash scripts/run_detection_quality_matrix.sh --help` passed.
+- `python scripts\smoke_docs.py` passed.
+- `git diff --check` passed.
+- `bash scripts/run_readiness_check.sh` passed: 390 backend tests, frontend typecheck/build, Alembic head `202606120900`, live smoke syntax checks and the new matrix syntax check.
+
+Open:
+- Live Tower matrix run still needed against the current Geel operator sample.
+
+Limitations:
+- This is operator benchmarking tooling only. It does not change inference behavior, add model downloads, seed fixture detections, fetch providers, change API contracts or change migrations.
+- A single Geel sample is not enough to declare a production V1 building-extraction baseline; additional orthophoto/reference samples are still needed before picking defaults.
+
+Next recommended pass:
+- Run the matrix on Tower for the current Geel operator sample, then decide whether the active building model should remain the default evaluation model or be replaced.
+
 ## Sprint 125 Detection calibration evidence bundle (2026-07-07)
 
 Changed:

docs/TODO.md

@@ -97,6 +97,7 @@ This file now starts with the current implementation status. Older preparation/b
 - [x] Persist CRS metadata in raster tile manifests so AI detections can be transformed to WGS84 GeoJSON correctly.
 - [x] Add real-data detection calibration sweep tooling for confidence-threshold and QA/QC metric comparison.
 - [x] Add calibration QA evidence export tooling for false-positive/false-negative inspection artifacts.
+- [x] Add real-data detection quality matrix tooling for model/tile/threshold comparison.
 - [ ] Calibrate confidence, IoU and model selection against persisted Geel detections and additional local orthophoto/reference samples.
 
 ## Sprint 8 status