SlabUploader/.audit/archive/2026-09-18-migration-todos.md

Migration TODOs — source docs

• Date: 2026-09-18
• Branch: docs/clean-main
• Purpose: edits deferred until Phase 2 step 3, when the capability and contract docs are migrated into docs/capabilities/ and docs/contracts/, made branch-neutral, and converted to cite requirement IDs.
• Rule: these docs are not edited now. REQUIREMENTS.md is the only normative text and is already correct for everything below.

CAPTURE.md

1. Line 16, "Length of the slab is aligned with the long side of the picture" — ruled dead. Remove.
2. Lines 128–129, the kind=inventory role label — discarded. The "first inventory photo is the measurement reference" half is CAPTURE-115; keep it as a citation, drop the label.
3. Line 140, editor/storefront alpha presentation — discarded.
4. The sensitivity mapping (line 69) and display/source-pixels rule (lines 58–62) are now CAPTURE-41 and CAPTURE-141; cite them instead of restating.
5. Line 82 busy mark ("more than a fraction of a second"; as-built is 300 ms) — ruled a nit, not a requirement. Leave as design prose or drop.

CREATE.md

1. Grade cardinality: change "1 or more" to 1 in all three places (attributes table, ready set, data shape). Ruling: Grade is exactly one.
2. fig-* cardinality: change "1 or more / required" to optional in the tags table and the ready set. Ruling: tags optional; the Figure attribute is at least one.
3. Ready-set images: change "at least one inventory PNG" to two (clean calibration plus its dimension-overlay copy). Ruling: REVIEW-5 is the PoR.
4. Remove "cap at 5 images" from the create sequence.
5. Remove "user typed widths/sqft/bdft wins"; the calculated fields are read-only.
6. Fix the Call 2 line so the model writes the title/description and the deterministic template is the fallback, not the assembler.

CONTENT-WOO.md

1. Em dash in the title template and example → hyphen.
2. "Templates (always on)" and "templates inject those numbers after the prose comes back" → template is the fallback only; the model writes when Call 2 runs.
3. fig-* "1+ required" and the ready set including fig-* tags → tags optional.
4. "≤5 inventory photos" → no cap; drop the "only kind=inventory" clause.
5. The empty attributes element shape is the known deferred decision; keep the placeholder.

PHOTOS.md

No changes. Overlay legibility and arrow/text drawing detail were ruled design, not requirements.

TEST-SPEC.md (→ docs/contracts/TEST-SPEC.md)

1. Migrate and cite requirement IDs; drop the pre-ID source-doc references.
2. Purge superseded cases: UI-1, UIE-9, UIE-10 (four knobs); V-3, API-8 (validation module); C2-2 (previous_response_id / thread); C1-1 (image source); C2-4 (prompt files); TV-6, TV-7, E2E-5 (80 percent / 1600 px); UIE-1, E2E-4 (computed override).
3. Add cases for the two new rows: APP-60 (keyboard, focus ring, 320 px reflow) and APP-65 (no secret material in logs).

IMPL-PLAN.md (retired)

1. Retire docs/IMPL-PLAN.md. Phases and Gates A/B/C are superseded by MILESTONES.md plus the PoR; acceptance and test obligations are QUALITY rows.
2. Superseded: four knobs; "1–5 photos"; 80 percent / 1600 px; calculated-field override; portable context and the stateful probe; prompt files.

ARCHITECTURE.md

1. §1, §2, §4 "four knobs" including Edge offset and Feather — controls are exactly Sheet and Sensitivity (CAPTURE-40).
2. §2 "1–5 photos" — one or more (CAPTURE-25).
3. §6.3 ready set requires 1+ fig-* tag and 1+ grade — tags are optional and grade is exactly one (METADATA-30, METADATA-15).
4. §8/§9 shared validation module, validation_hash, 412, stateful/stateless mode, and per-slab thread — ruled cut 2026-09-18; thread work is out of the MVP and test-inference no longer returns mode.
5. Retire docs/ARCHITECTURE.md: its testable rules are APP/CAPTURE/SETTINGS rows, and the topology is covered by those plus deploy/.
6. §3.4 Call 1 image input "all originals downscaled to 1024" → clean processed photos (METADATA-35).

UX.md (→ docs/contracts/UX.md) and UX-DESIGN.md (retired)

1. Migrate docs/UX.md to docs/contracts/UX.md: branch-neutral, cite requirement IDs, do not restate rules.
2. Retire docs/UX-DESIGN.md (non-normative). Fold the "AI" badge, first-run card, separate Title/Description screen, and error-state copy into the UX contract.
3. Superseded in UX.md: four knobs → two; "1 to 5 photos" → no cap; "no calibration photos" → the calibration photo exists; 80 percent / 1600 px → 90 percent / 800 px; calculated-field override path → read-only; grade 1+ → exactly one; fig-* 1+ → optional; "templates always run" → template fallback; "title/short/description not required to reach ready" → required (REVIEW-10); short_title → short_description.

TECH-SPEC-PIPELINE.md (retired)

1. Retire docs/TECH-SPEC-PIPELINE.md. Its deterministic rules are CAPTURE; its ten vectors are QUALITY. Fold any wanted algorithm detail into the CAPTURE capability doc.
2. Superseded: 80 percent fill and the 1600 px floor → 90 percent and 800 px; four knobs → two; the auto-dimension overlay is no longer v1.5 (it shipped).

PROMPTS.md (→ docs/contracts/PROMPTS.md)

1. Prompts move from server text files to the database with all revisions (METADATA-105): drop the read-only mount, host-editing, and reset-to-default script.
2. Remove previous_response_id, the portable-context machinery, and the shared-validation rules from the Call 2 inputs.
3. "1–5 inventory photos" → no cap (CAPTURE-25).
4. Example title uses an em dash and a multiplication sign → hyphen separator; snap short_title to short_description.

DEPLOYMENT.md (retired)

1. Retire docs/DEPLOYMENT.md. Its testable rules are OPS/SETTINGS; its operational facts live in deploy/ (INVENTORY.md, docker-compose.yml, Caddyfile.fragment, RELEASE-PROCESS.md).
2. Fold any still-useful prose into deploy/ (the deploy README is the natural home).
3. Repoint the UAT-PRACTICE references from docs/DEPLOYMENT.md §1/§3/§5/§8 to deploy/.
4. Superseded: output_px_min 1600 → 800 px floor (CAPTURE-105); "prompt files live in git and need no backup" → prompts live in the DB with all revisions (GAP-8).

DATA-MODEL.md (→ docs/contracts/DATA-MODEL.md)

1. Grade "1+" → exactly one; fig_tag_ids "1+" → optional.
2. output_px_min 1600 and fill_target 0.80 → 800 px floor and 90 percent fill.
3. "Only inventory photos. Calibration photos do not exist." → the calibration photo exists; other batch photos are visual inventory only (CAPTURE-115).
4. "No hard deletes for slabs (audit)" → the local slab row is deleted on successful create (PUBLISH-25).
5. Remove inference_thread_id; thread work is out of the MVP.
6. Prompt files: replace the bind-mounted text files with prompts stored in the DB, all revisions (PoR row pending the PROMPTS walk).
7. short_title → short_description (Woo canonical).

OPENAPI.md (→ docs/contracts/API.md)

1. Field name short_title → short_description (Woo canonical). Applies to the schema, read model, Call 2 result, and examples.
2. fill_target 0.80 and output_px_min 1600 → 90 percent fill and an 800 px floor (CAPTURE-100, CAPTURE-105).
3. Remove the validation module endpoint, validation_hash, and the 412 path (ruled cut).
4. Remove previous_response_id, the per-slab thread, and mode from test-inference; Call 2 is a fresh full-context call.
5. Grade cardinality "1+" → exactly one; fig-* "1+" → optional.
6. The taxonomy-sync example key synced_at should be taxonomy_last_sync_at.
7. Call 1 image input for infer-taxon: original photos → clean processed photos (METADATA-35).

PRODUCT.md

1. Line 19, "One or more fig-* tags" — tags are optional per METADATA-30. Change to optional.
2. Line 23, "Measured values feed title and description templates" — template is the fallback; the model writes when Call 2 runs. Cite METADATA-60, METADATA-70, METADATA-80. Same conflict in the decision-rights table, line 37 ("Templates from listing facts").
3. Line 20, "short title" — stale wording; the field is short_description (REVIEW-10).
4. Branch-neutral: line 1 "Milestone status on m3-ds", and line 66 "behavior ... taken from main". Remove branch names.
5. Line 25, umbrella term "Woo attributes" → "Woo Slab Taxonomy" (see cross-cutting rename).

README.md

1. Branch-neutral: line 1 title "Docs map (branch m3-ds)" and line 44 "copied into docs/CREATE.md from main". Remove branch names.
2. Line 39, umbrella "Woo attributes" → "Woo Slab Taxonomy" (see cross-cutting rename).

UAT-PRACTICE.md

1. Line 100, "four knobs: Sheet, Sensitivity, Edge offset, Feather" — controls are exactly Sheet and Sensitivity; Edge offset and Feather are removed (CAPTURE-40).
2. Line 97, "1 to 5 photos" — no cap; CAPTURE-25 is one or more.
3. Line 122, "at least one figure, at least one grade" — grade is exactly one (METADATA-15).
4. Line 126, "fig-* tags. Pick at least one." — tags are optional (METADATA-30).
5. Branch-neutral: line 14 "On branch m3-ds". Stale refs to docs/DEPLOYMENT.md, docs/UX.md, docs/TECH-SPEC-PIPELINE.md, docs/IMPL-PLAN.md in the "where each rule lives" table.

Cross-cutting: "Woo Slab Taxonomy" rename

Ruling 2026-09-18: the umbrella package term is Woo Slab Taxonomy; canonical Woo attributes (the five) keep the name.

• Rename umbrella occurrences: AGENTS.md:48, PRODUCT.md:25, CREATE.md:7, CREATE.md:34, CREATE.md:50 (heading), CREATE.md:261, CREATE.md:397, README.md:39.
• Keep "Woo attributes" where it means the canonical five: CREATE.md:61, CONTENT-WOO.md:121.
• Give the term one glossary home in the step-3 contract docs; make PRODUCT/AGENTS reference it instead of redefining.