193 lines
12 KiB
Markdown
193 lines
12 KiB
Markdown
# 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.
|