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