ComfyUI-Ethanfel-Prompt-Builder/docs/superpowers/plans/2026-07-02-normal-camera-atlas-maintenance-phases.md

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

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

• Expose validate_normal_camera_atlas(...) -> list[str] and a CLI that exits 1 with one error per line when validation fails.

• Add a narrow prompt-smoke check that calls the validator instead of duplicating all normal-camera artifact details.

• 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

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

• Write both HTML and Markdown indexes from write_artifacts(...).

• Include no-generation language and local artifact links only.

Task 3: Per-Image Review Annotations

Files:

• Modify: normal_camera_atlas_prep.py

• Add review_items to every review manifest.

• For selected references, mark review_decision: selected_reference, preserve review_bucket, variant_key, and include selection notes.

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

• 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

• Add explicit alias metadata for typo/spacing variants while preserving exact source folder names.

• Include alias metadata in review manifests, unused-pool backlog rows, and review indexes.

• 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

• Build a needs-samples acquisition list from categories/normal_camera_variants.json.

• Sort by missing sample count, then action family, then variant key.

• 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

• Document the validator, review index, alias metadata, per-image annotations, and acquisition list.

• Run python normal_camera_atlas_prep.py --write-artifacts --output-dir ab_batches/normal_camera.

• Run python tools/normal_camera_atlas_validate.py --artifacts-dir ab_batches/normal_camera.

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

• Run python -m py_compile normal_camera_atlas_prep.py tools/normal_camera_atlas_validate.py tools/prompt_smoke.py.