# M4 — Goals

Role: goals for Milestone 4. Cites requirement IDs and Gitea issue numbers; defines none
new until accepted. Source of truth for scope will be `docs/MILESTONES.md` (M4 ID subset)
and `docs/REQUIREMENTS.md` (rows) after acceptance.

**Base:** builds on branch `m4` (commit `818874e`, `feat(m4): crop_fill setting + tape-line
prototype (#99)`), which is 1 ahead of `origin/main`. #99 is in scope.

**Objective:** Ship a polished, stable M3 experience with the tape-line calibration model,
a **human-driven taxonomy review** (Call 1 deferred; owner picks everything on a thumb-first
UI), **refined Call 2 long descriptions**, and a verified real WooCommerce draft submission.

**Exit criterion:** A real `SLAB-UAT-*` Woo **draft** matching the reviewed ready set exists
in the store, created end-to-end through the M4 UI (tape-line calibration → human taxonomy
review → Call 2 long description → publish), with **no Call 1** in the path (inference
settings need not be vision-enabled). Call 2 is exercised on a live call at least once.
Raw runner evidence recorded; Ty owns gate exit (QUALITY-25/30).

## Goals (accepted direction)

1. **Stabilize + polish the M3 experience (A) — includes the #99 tape-line calibration (B).**
   - **Tape-line calibration (#99) — SHIPPED (as-built 2026-09-25, UAT signed off):** the
     axis-rectangle calibration is replaced by a **fixed** black centre line with two end
     ticks. The line is a stage fixture and is **never an owner input** (not draggable, not
     focusable, not keyboard-nudgeable). The **source photo/slab is the only thing that
     moves** — pan/zoom/tilt it until it lines up with the fixed line at the place the tape
     measurement was taken. Declared Length = the real inches read off the tape, and the
     fixed line represents that same length; scale = fixed-line pixel span / declared
     Length, no `maskSpanAlong` check. The crop slider alone sets the line ends
     (`crop_fill=90` ⇒ each end 5% from its edge). The earlier `?tape-prototype` sandbox,
     `TapePrototype.svelte`, `frontend/src/png/crop.ts` and the `sveltedrag` dependency are
     all superseded/removed. Requirement rows CAPTURE-170/175/75 carry the as-built; see
     `tasks.md` T2 for detail.
   - **UX polish:** photo-picker look/feel (#91), photo filenames on submit (#92), capture
     gated on a tested Woo connection (#93), review UI is always the human-pick flow (#94),
     debug mode (#95), required-photo lock glyph (#100). (#96 Call 1/2 prompt viewer drops
     with Call 1.)
   - Post-launch issue work + the tape-line feature; no other new feature surface.

2. **Human-driven taxonomy review + thumb-first UI (Call 1 deferred; Call 2 kept).**
   - **Call 1 (vision) → deferred to future work.** Not in the MVP: no "Suggest with AI"
     button, no auto-pre-fill, no confidence pre-fill, no AI markers on fields. The
     inference settings need not be vision-enabled.
   - **Owner picks everything Call 1 used to propose**, via a thumb-first, on-phone usable
     UI: species (1 leaf), wood categories (primary + optional secondaries), Edge, Figure
     (multi), Grade (owner judgment), Thickness band (derived, no pick), Moisture, and
     `feat-*` / `fig-*` tags. All from the synced Woo taxonomy (METADATA-5/10/15/30).
   - **Call 2 (text) stays** — writes the long description from the human-picked values +
     dimension fact block; brand/geo context, primary + secondary categories. (Refining its
     output quality is its own goal, #3 below.)
   - **Title + short description remain deterministic** from the primary wood category +
     dimension fact block (METADATA-80/85) — they depend only on the human's primary pick
     + fact block, not on Call 1.
   - **All METADATA requirements remain in scope** — the human collects the same data
     Call 1 previously suggested, just by hand.
   - **Wireframe first (a sprint task in this milestone):** before any review-UI coding,
     produce a wireframe (2-3 HTML variants) to align on the overall flow — how the
     thumb-first taxonomy collection, primary/secondary selection, and Call 2 generate
     control compose on a phone. This is the design gate for the review work.
     **Starting point (saved, recent):** `docs/design/issue-99-tape-line-overlay.html`
     (approved #99 tape-line overlay wireframe, committed 2026-09-24 on
     `issue-99-tape-line-overlay`). Do **not** build on the older `pre-simplification`
     wireframes or the 2026-09-18 `ux-design.md` coverage matrix — those are stale.
   - *To be scoped:* the exact thumb-first interaction model (wizard vs single-scroll,
     chips vs pickers) — settled by the wireframe.

3. **Refine Call 2 so it delivers better long descriptions.**
   - Call 2 (text) stays in the MVP and is the inference work of this milestone: improve
     how it turns the human-picked taxonomy + dimension fact block + brand/geo context into
     a long description that reads well for the store.
   - Levers (task-level, settled during the sprint): prompt revision (METADATA-105/106),
     the dimension fact block as the only numbers it may print (METADATA-65/90/95),
     primary + secondary category weighting, brand voice / geo context settings
     (SETTINGS-30), and recoverable/unrecoverable failure (METADATA-115).
   - Success is judged on the exit-walk description quality (Ty reads it), not on a proxy
     metric. Raw evidence recorded.

4. **Exit: real Woo draft submission.**
   - PUBLISH-5 sequence, PUBLISH-10 (`SLAB-UAT-*` force draft), PUBLISH-25 (woo_product_id,
     purge photos, discard local row, clear device draft). QUALITY-110 exit evidence.

## Non-goals (excluded from M4)

- **Call 1 (vision) inference** — deferred to future work. No auto-suggest, no confidence
  pre-fill, no AI markers. METADATA-35/40/45/100 rows are out of the M4 active set.
- TLS on LAN transports (#78) — production-readiness, deferred.
- Backup/restore (OPS-30/35) — deferred ("Later").
- Instrumentation: Prometheus metrics, alerting, log retention (#7/#16) — deferred.
- Store-admin species-leaf creation (#13), shared validation module (#17), 409/422
  field-level recovery (#18) — post-launch designs, deferred.
- Offline capture (CAPTURE-15), U2Net server matting (CAPTURE-165) — "Later".
- Browser e2e on all five clients (QUALITY-115) — "Later".
- Prompt-revision auth beyond trusted network (METADATA-107) — "Later".
- App login (relies on trusted LAN/Tailscale + HTTPS, OPS-55) — out of scope.

## Assumptions

- M4 does **not** add an app-level login; the trusted-network model (OPS-55) holds.
- The `m4` branch is the working base; `main` is the merge target once M4 is accepted and green.
- Inference endpoint is a remote, configurable endpoint (OPS-45); M4 refines prompts/calls,
  not the endpoint transport.
- Real Woo for the exit walk; Woo mock is a dishonest proxy (QUALITY-105/110).
- Existing M3 requirement rows that the tape-line model supersedes (CAPTURE-60, CAPTURE-75)
  are updated in place; new rows are added for the tape-line behavior. No row is deleted.

## Requirements delta (draft — rows written at execution, after acceptance)

- **New rows:** tape-line calibration behavior (overlay, draggable ticks,
  owner-declared length, tick-distance scale). ~1–3 rows under CAPTURE.
- **New rows (draft):** the **manual taxonomy selection UI** — owner picks species / wood
  categories (primary + secondary) / edge / figure / grade / moisture / tags by hand,
  thumb-first, with no inference pre-fill. ~1 row under METADATA or REVIEW.
- **Superseded/updated rows (draft):** CAPTURE-60 (length axis), CAPTURE-75 (scale model) —
  rewritten to the tape-line model.
- **Deferred rows (out of M4 active set):** METADATA-35/40/45/100 (Call 1 vision
  suggestions + confidence gate) — moved to "Later"/future work. The rows stay in
  REQUIREMENTS.md; only their M4 scope drops.
- **Refined rows (draft):** METADATA-55/60/65 (Call 2) — if the human-picked flow changes
  normative Call 2 inputs (it shouldn't materially; Call 2 already receives the metadata
  confirmed in review).
- **Refined rows (draft):** REVIEW-15/20/25/40 (review-workflow usability) — field layout,
  nudge behavior, primary/secondary category interaction, generate-text control placement,
  if the usability changes alter normative review behavior. #94 (conditional review UI)
  now means: the review screen is **always** the human-pick flow (no inference on/off
  branch for Call 1).
- **Unchanged (in M4 ID subset):** all PUBLISH, REVIEW, SETTINGS, APP, OPS-40, QUALITY rows
  that M3 already shipped and M4 re-uses for the exit; METADATA-5/10/15/30/85 (the data the
  human collects + the deterministic title/short-desc).

## Acceptance criteria (draft)

1. **Tape-line calibration + M3 polish ship together (Goal 1):** the tape-line calibration
   ships as a **fixed** centre line the owner pans/zooms/tilts the slab onto (line is never
   an owner input; crop slider sets its ends; declared length = the real tape inches, and
   the fixed line represents that same length; no `maskSpanAlong` check), and the
   M3 polish issues (#91–#100, excluding #96 which drops with Call 1) are closed with
   passing tests and raw runner evidence.
2. **The review flow is human-driven, thumb-first, and Call 1-free:** the owner can pick
   species, wood categories (primary + secondary), edge, figure, grade, moisture, and tags
   by hand on a phone, with no "Suggest with AI" surface and no AI pre-fill. The wireframe
   was accepted before coding (design gate).
3. **Call 2 (text) is exercised on a live call** during the exit walk and delivers a
   description that reads well (Ty judges it); content-gen control visibility (METADATA-110),
   recoverable/unrecoverable classification (METADATA-115), and prompt-revision API
   (METADATA-105/106) all pass their tests.
4. **A real `SLAB-UAT-*` Woo draft** exists in the store matching the reviewed ready set
   (QUALITY-110), with `woo_product_id` set, photos purged, local row discarded, device
   draft cleared (PUBLISH-25).
5. **Gates pass:** `python tools/check_requirements.py` and `python tools/check_coverage.py`
   exit 0; full suite passes with inference **and** off (QUALITY-20) — now including the
   human-pick flow with Call 1 removed; raw evidence recorded.

## Verification strategy (smallest that proves the claim)

- **Deterministic core:** unit tests for tape-line geometry + `crop_fill` (existing
  `frontend/src/png/*` test surface).
- **Integration:** Woo mock for the PUBLISH-5 sequence (success, duplicate SKU, stale field,
  taxonomy anchor) — QUALITY-35/50.
- **Exit walk:** `deploy/uat_walk.sh` on the real store for the `SLAB-UAT-*` draft
  (QUALITY-105/110) — the only proof that counts for the submission claim.
- **Ty owns gate exit** (QUALITY-30); agents record raw evidence, never declare green.

## Task-level decisions (settled during the sprint, not at planning)

The only plan-level open item is the exact thumb-first interaction model
(wizard vs single-scroll, chips vs pickers) — settled by the wireframe.
Settled at kickoff (not reopened here): full #91–#100 polish wave (only #96 drops
with Call 1); #99 confined to the calibration step (CAPTURE-130 lineup untouched);
exit walk is a single slab carrying multiple photos.

## Task breakdown detail bar

The task breakdown is not a list of goal names. Every task carries, at minimum:

- **Goal it serves** (G1–G4) and the requirement IDs / issue numbers it touches.
- **Skills to load** for that task — named and ordered (e.g. UI task: `sketch` +
  `wireframe-review-iteration` → `omh-frontend` + `omh-design-quality-gate` →
  `omh-visual-qa` + `omh-accessibility-audit`).
- **Starting point / references** — the specific saved artifact, file, or branch the task
  builds from (e.g. `docs/design/issue-99-tape-line-overlay.html`, the live
  `Review.svelte`, the M3 `MultiSelect.svelte`).
- **Verification** — the smallest check that proves the task's claim (unit test paths,
  `tsc --noEmit`, Woo mock, `deploy/uat_walk.sh`, 375/768/1280 visual captures, keyboard /
  contrast audit). Ty owns gate exit.
- **Sequence / dependencies** — what must land first (wireframe accepted before review-UI
  coding; requirements rows before the code that implements them; Call 2 refinement after
  the human-pick flow feeds it real data).
- **Stop condition** — when the task is done (e.g. "wireframe accepted by Ty," "gates
  green + raw evidence recorded," "real `SLAB-UAT-*` draft matches the ready set").
- **Evidence boundary** — what is prepared vs observed; no task claims done without the
  raw runner / capture / store evidence named above.