# Normal Camera Atlas Maintenance Phases 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:** Add phased maintenance tooling around the no-generation normal-camera atlas: a dedicated validator, review index, richer per-image annotations, folder alias metadata, needs-samples acquisition output, schema checks, and docs/smoke handoff.

**Architecture:** Keep `normal_camera_atlas_prep.py` as the artifact builder and add `tools/normal_camera_atlas_validate.py` as the strict validation CLI. `tools/prompt_smoke.py` should delegate normal-camera artifact invariants to the validator instead of carrying every detail inline. Generated artifacts remain under `ab_batches/normal_camera/`.

**Tech Stack:** Python standard library, JSON catalogs, generated Markdown/HTML review artifacts, existing `tools/prompt_smoke.py` smoke runner.

---

### Task 1: Dedicated Validator

**Files:**
- Create: `tools/normal_camera_atlas_validate.py`
- Modify: `tools/prompt_smoke.py`

- [x] Add a validator module that imports `normal_camera_atlas_prep`, reads `categories/normal_camera_variants.json`, verifies catalog schema/counts, folder coverage, no-generation invariants, artifact existence, review manifests/contact sheets, selected-reference consistency, folder alias metadata, and optional JSON schema-style structural checks.
- [x] Expose `validate_normal_camera_atlas(...) -> list[str]` and a CLI that exits `1` with one error per line when validation fails.
- [x] Add a narrow prompt-smoke check that calls the validator instead of duplicating all normal-camera artifact details.
- [x] Verify with `python tools/normal_camera_atlas_validate.py --artifacts-dir ab_batches/normal_camera`.

### Task 2: Review Index

**Files:**
- Modify: `normal_camera_atlas_prep.py`
- Generated: `ab_batches/normal_camera/review/index.html`
- Generated: `ab_batches/normal_camera/review/index.md`

- [x] Add `build_review_index(...)` helpers that list every default review folder with source folder, canonical alias, image count, selected subvariant count, status summary, manifest path, and contact-sheet path.
- [x] Write both HTML and Markdown indexes from `write_artifacts(...)`.
- [x] Include no-generation language and local artifact links only.

### Task 3: Per-Image Review Annotations

**Files:**
- Modify: `normal_camera_atlas_prep.py`

- [x] Add `review_items` to every review manifest.
- [x] For selected references, mark `review_decision: selected_reference`, preserve `review_bucket`, `variant_key`, and include selection notes.
- [x] For residual images, mark `review_decision: residual_unassigned`, `review_bucket: unassigned`, and include a conservative reason such as `outside_selected_subvariants_or_pending_manual_bucket`.
- [x] Reflect these decisions in contact-sheet figure attributes/captions.

### Task 4: Folder Alias Metadata

**Files:**
- Modify: `normal_camera_atlas_prep.py`
- Modify: `tools/normal_camera_atlas_validate.py`

- [x] Add explicit alias metadata for typo/spacing variants while preserving exact source folder names.
- [x] Include alias metadata in review manifests, unused-pool backlog rows, and review indexes.
- [x] Validate that every known typo/spacing source folder keeps an alias record.

### Task 5: Needs-Samples Acquisition List

**Files:**
- Modify: `normal_camera_atlas_prep.py`
- Generated: `ab_batches/normal_camera/normal_camera_needs_samples_acquisition.json`
- Generated: `ab_batches/normal_camera/normal_camera_needs_samples_acquisition.md`

- [x] Build a needs-samples acquisition list from `categories/normal_camera_variants.json`.
- [x] Sort by missing sample count, then action family, then variant key.
- [x] Keep it separate from the pre-A/B priority plan.

### Task 6: Docs And Verification

**Files:**
- Modify: `docs/normal-camera-atlas.md`
- Modify: `tools/prompt_smoke.py`

- [x] Document the validator, review index, alias metadata, per-image annotations, and acquisition list.
- [x] Run `python normal_camera_atlas_prep.py --write-artifacts --output-dir ab_batches/normal_camera`.
- [x] Run `python tools/normal_camera_atlas_validate.py --artifacts-dir ab_batches/normal_camera`.
- [x] Run `python tools/prompt_smoke.py --case normal_camera_atlas_catalog --case normal_camera_atlas_prep_artifacts --case normal_camera_unused_pool_review_artifacts --quiet`.
- [x] Run `python -m py_compile normal_camera_atlas_prep.py tools/normal_camera_atlas_validate.py tools/prompt_smoke.py`.