feat: add normal camera atlas maintenance tooling

2026-07-03 10:22:39 +02:00
parent 36594e6449
commit 5442e4ee4c
116 changed files with 59290 additions and 94 deletions
@@ -0,0 +1,76 @@
+# 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`.