docs(phase2): reconcile requirements and migrate capabilities/contracts
Surface-matrix sweep of every source doc; added nine missed behaviors (METADATA-115, REVIEW-50, APP-55/60/65, SETTINGS-45 mode, Generate-text availability, defaults-off). 153 requirements, 0 coverage gaps. Migrated capabilities to docs/capabilities/ and contracts to docs/contracts/; added WOO-API, API, DATA-MODEL, PROMPTS, UX, TEST-SPEC. Populated MILESTONES; branch-neutral trunk docs; renamed umbrella term to Woo Slab Taxonomy. Archived reconciliation working records under .audit/archive/.
This commit is contained in:
@@ -0,0 +1,183 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user