Add operator YOLO label QA contact sheets

docs/superpowers/specs/2026-07-11-yolo-label-qa-contact-sheets-design.md

@@ -0,0 +1,73 @@
+# YOLO Label QA Contact Sheets Design
+
+## Goal
+
+Add an operator-only visual QA helper that renders existing YOLO tile images with
+their YOLO bbox labels overlaid into deterministic contact-sheet PNG artifacts.
+
+## Scope
+
+This is not a product feature and does not change API contracts, database
+schema, model activation, detection inference, provider fetching or training.
+It only reads an already exported YOLO tile dataset and writes visual evidence
+artifacts for human inspection before another training run.
+
+## Inputs
+
+- `yolo_tile_dataset_summary.json` from `scripts/export_operator_yolo_tile_dataset.py`.
+- Existing tile image files referenced by the summary.
+- Existing YOLO label files referenced by the summary.
+
+## Outputs
+
+- `operator_yolo_label_qa_summary.json`
+- `operator_yolo_label_qa_contact_sheet.md`
+- One or more PNG contact sheets under the chosen output directory.
+
+Each selected tile preview shows the image, label boxes and compact metadata:
+sample slug, split, label count and background category when present.
+
+## Selection Strategy
+
+The first implementation should be deterministic and small:
+
+- include tiles with the highest label counts;
+- include tiles from low-label positive/context samples;
+- include a small number of negative tiles;
+- limit total rendered tiles with `--max-tiles`.
+
+This is enough to catch common issues such as shifted imagery, clipped labels,
+wrong class files, empty positives and mislabeled background tiles.
+
+## Rendering Strategy
+
+Use Pillow, already available in the project runtime. Draw boxes from normalized
+YOLO labels directly onto the tile image. Invalid or missing label files are
+reported in JSON/Markdown and skipped for box drawing, not silently ignored.
+
+## Error Handling
+
+- Missing summary file: fail with a clear process error.
+- Missing image files: record skipped image count and continue if other selected
+  images can be rendered.
+- Missing label files: record missing label count and render the image without
+  boxes.
+- Invalid label rows: record invalid row count and render only valid boxes.
+
+## Tests
+
+Add focused tests that create tiny fixture images and YOLO labels in a temporary
+dataset directory, run the script and assert:
+
+- JSON and Markdown reports are created;
+- contact-sheet PNG exists;
+- selected tile count is deterministic;
+- invalid labels are counted;
+- missing label files are counted;
+- rendered output is not blank.
+
+## Acceptance
+
+The helper is acceptable when local targeted tests pass, full readiness passes,
+the all-in-one Tower runtime is redeployed, and the clean AOI1024 dataset emits
+contact sheets on Tower.