SlabUploader/.planning/milestones/v0.5/M4/goals.md

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.