Add operator YOLO label QA contact sheets

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

@@ -0,0 +1,63 @@
+# YOLO Label QA Contact Sheets Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build an operator-only visual QA script that creates deterministic contact-sheet PNG artifacts from existing YOLO tile datasets.
+
+**Architecture:** Add a standalone script under `scripts/` with no backend/API/database changes. The script reads `yolo_tile_dataset_summary.json`, resolves image and label paths, selects a bounded deterministic tile subset, draws normalized YOLO labels using Pillow, and writes JSON/Markdown/PNG artifacts.
+
+**Tech Stack:** Python standard library, Pillow, pytest subprocess-based script tests.
+
+---
+
+### Task 1: Regression Test
+
+**Files:**
+- Create: `backend/tests/test_sprint167_operator_yolo_label_qa_contact_sheets.py`
+
+- [ ] Write a failing test that creates a tiny YOLO dataset with train/val images, valid labels, an invalid label row and a missing label path.
+- [ ] Run `python -m pytest backend/tests/test_sprint167_operator_yolo_label_qa_contact_sheets.py -q`.
+- [ ] Expected result: failure because `scripts/render_operator_yolo_label_qa_contact_sheets.py` does not exist.
+
+### Task 2: Script Implementation
+
+**Files:**
+- Create: `scripts/render_operator_yolo_label_qa_contact_sheets.py`
+
+- [ ] Implement CLI arguments:
+  - `--summary-path`
+  - `--output-dir`
+  - `--max-tiles`
+  - `--columns`
+  - `--thumb-size`
+- [ ] Implement summary loading and `/app/...` path resolution consistent with existing operator scripts.
+- [ ] Implement YOLO label parsing with invalid/missing counts.
+- [ ] Implement deterministic tile selection.
+- [ ] Implement Pillow rendering to PNG contact sheets.
+- [ ] Implement JSON and Markdown reports.
+- [ ] Run the targeted test and keep the implementation minimal until it passes.
+
+### Task 3: Documentation
+
+**Files:**
+- Modify: `scripts/README.md`
+- Modify: `docs/TODO.md`
+- Modify: `docs/CODEX_EXECUTION_LOG.md`
+
+- [ ] Document the command and intended usage.
+- [ ] Mark visual contact sheets as implemented in TODO.
+- [ ] Record local and Tower validation evidence.
+
+### Task 4: Verification And Deploy
+
+**Commands:**
+- `python -m pytest backend/tests/test_sprint167_operator_yolo_label_qa_contact_sheets.py -q`
+- `python -m pytest backend/tests/test_sprint146_operator_yolo_dataset_quality_audit.py backend/tests/test_sprint167_operator_yolo_label_qa_contact_sheets.py -q`
+- `bash scripts/run_readiness_check.sh`
+- `powershell -NoProfile -ExecutionPolicy Bypass -File scripts/deploy_tower.ps1`
+- Tower script run against `/app/storage/operator-data/yolo-building-aoi1024-cleanpx12vis035/yolo_tile_dataset_summary.json`
+
+- [ ] Commit and push after local readiness.
+- [ ] Redeploy Tower.
+- [ ] Generate Tower contact sheets.
+- [ ] Commit and push evidence docs.

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.