# 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.