From df40c4269f7ac488a7f2231bea2ea853e8f13eb2 Mon Sep 17 00:00:00 2001 From: grokbot_ty Date: Wed, 16 Sep 2026 20:32:03 +0000 Subject: [PATCH] docs(m3): lock Create requirements on m3-ds Add docs/CREATE.md as M3 SoT from Ty conversation (Woo attributes sync, ready-set use, create, OpenAI Settings dependency). Point AGENTS/PRODUCT here; mark main milestone splits obsolete for this branch. --- AGENTS.md | 28 +++++++---- docs/CREATE.md | 112 +++++++++++++++++++++++++++++++++++++++++ docs/PRODUCT.md | 29 ++++------- docs/archive/README.md | 4 ++ 4 files changed, 144 insertions(+), 29 deletions(-) create mode 100644 docs/CREATE.md diff --git a/AGENTS.md b/AGENTS.md index 545e555..c2c893e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,31 +2,37 @@ ## Agent context -Read this file, `docs/CAPTURE.md`, and `docs/PHOTOS.md`. -Implement Milestone 2 only. Specification: `docs/PHOTOS.md`. -PRD: `docs/PRODUCT.md` for destination and field names. Do not implement Milestone 3 or 4. -Do not widen Milestone 2 into Complete-listing taxonomy, SKU, price, copy, or Woo create. +Read this file, `docs/CAPTURE.md`, `docs/PHOTOS.md`, and `docs/CREATE.md`. +Implement **Milestone 3** only. Specification: `docs/CREATE.md`. +PRD overview: `docs/PRODUCT.md` for destination and field names. -## Milestone 2 +**M3 scope SoT is `docs/CREATE.md` and the Ty conversations that produced it.** +Milestone / task breakdowns on `main` are obsolete for M3. Do not cross-reference `main` for scope once coding on this branch. -Photos. -Acceptance: on a phone, batch of 1–N photos, user-picked calibration photo through Milestone 1 mask/axis/measure, every successful shot as a 3:4 transparent inventory PNG lined up, Milestone 1 numbers on screen, dimension-overlay copy of the calibration PNG present. +Do not implement work outside `docs/CREATE.md` unless Ty expands scope in chat. +Do not touch deploy port `:10880`. UAT redeploy target is overnight Docker on ubudual5060 `:10881`. -Milestone 2 is inference-free. Batch mask/crop reuse and dimension overlays run in the browser as ordinary code. There is no inference URL and no model call in this milestone. +## Milestone 3 -## Milestone 1 (historical) +Create — Woo attributes sync (WordPress application password), proper use of the synced taxonomy for the ready set and product create, plus OpenAI-compatible inference endpoint dependency in Settings. +Acceptance: see Done when in `docs/CREATE.md`. Practice SKU `SLAB-UAT-*` exists in the store as draft; create works with inference off. -Capture. Spec: `docs/CAPTURE.md`. Remains the calibration math and PNG contract Milestone 2 reuses. +## Milestone 1–2 (shipped inputs) + +- Capture: `docs/CAPTURE.md` — calibration math and PNG contract. +- Photos: `docs/PHOTOS.md` — batch inventory PNGs + dimension overlay. Base tip for this branch: shipped M2 on `:10881`. ## Invariants - Quantity per listing is one. - User enters length, thickness, and SKU. -- App proposes remaining listing fields. User reviews before create. +- App may propose remaining listing fields. User reviews before create. - Non-math fields remain editable until create. - `bdft = sqft × thickness_in` - Price proposal is `bdft × species $/bdft`. User may replace it. Missing rate leaves price empty. - User-entered length, thickness, SKU, price, and taxonomy override computed or inferred values. +- **Woo attributes** = synced species + wood categories; Edge / Figure / Grade / Thickness / Moisture; `fig-*` / `feat-*`. Store is source of truth. +- Woo auth is WordPress application password (server-side). `WOO_BASE_URL` is compose/env; inference URL is Settings. - SKUs matching `SLAB-UAT-*` create as Woo draft. - Create works with inference off. - Source below the PNG size floor requires a new photo. diff --git a/docs/CREATE.md b/docs/CREATE.md new file mode 100644 index 0000000..5508c94 --- /dev/null +++ b/docs/CREATE.md @@ -0,0 +1,112 @@ +# Milestone 3 — Create + +Builds on Milestones 1–2 (`docs/CAPTURE.md`, `docs/PHOTOS.md`). +Destination and field names also live in `docs/PRODUCT.md`. + +**Scope source of truth:** this file and the Ty conversations that wrote it. +Task and milestone breakdowns on `main` (including older PRODUCT / IMPL-PLAN / CONTENT-WOO splits) are **obsolete for M3**. Do not cross-reference `main` for what M3 includes once this branch is the working set. + +## Goal + +Phone path from Photos-ready device draft → store-synced **Woo attributes** filled and reviewed → WooCommerce product create (practice SKUs as draft) → clear device draft. + +M3 also wires the **OpenAI-compatible inference endpoint** as a server dependency so inference ops can run when enabled. Create must still work with inference off. + +## Woo attributes + +Locked name for the synced taxonomy package. WooCommerce is the source of truth; the app caches ids and never invents the lists. + +### Categories (product categories, leaf-only) + +| Field | Cardinality | Notes | +|---|---|---| +| Species | exactly 1 required | Synced species leaves only; no hardcoded / fallback set | +| Wood category | 1+ required | Parents are grouping only; picks are leaves | + +### Attributes (exactly five locked Woo attributes) + +| Attribute | Cardinality | Notes | +|---|---|---| +| Edge Type | 1 required | Term id from sync | +| Figure | 1+ required | Term ids from sync | +| Grade | 1+ required | Term ids from sync | +| Thickness | 1 required | Measured thickness rounded **up** into the store band | +| Moisture | 1 required | Default kiln-dried; user sets/keeps; **never inferred** | + +v1: missing attributes are skipped, not created. Species, character, length, and free-text thickness are **not** product attributes. + +### Tags + +| Tag prefix | Cardinality | Notes | +|---|---|---| +| `fig-*` | 1+ required | Other Woo tags ignored | +| `feat-*` | 0+ optional | Character / inclusions / voids / checks map onto existing feat tags only | + +### Listing facts beside taxonomy + +- User: SKU, length, thickness (and app-computed widths / sqft / bdft from M1/M2) +- Price: propose `bdft × species $/bdft` from pricing rules; user may override; missing rate → empty price +- Copy: title / short title / description from templates (optional Generate text when inference is on; not required for ready) + +## Sync (Woo) + +- FastAPI is the sole Woo client. Credentials never in the browser. +- Auth: WordPress **application password** for a dedicated low-privilege WP user (not Woo `ck_`/`cs_` consumer keys). +- Store URL: `WOO_BASE_URL` from `deploy/.env` / compose (`https://` only). Settings shows it read-only. Not a SQLite settings row. +- Woo username + application password: Settings UI → AES-GCM in SQLite (`SLAB_AES_KEY` env). +- Taxonomy sync pulls, in order: categories → tags (`fig-*` / `feat-*` only) → attributes + terms (five locked). +- Sync failure keeps the previous cache (never delete-then-fail). Stale picks show “no longer valid”; never silently swap. + +## Inference dependency + +- OpenAI-compatible endpoint: `inference_base_url`, API key, model in **Settings** (encrypted), not compose env. +- Server proxies all inference calls. +- Feature-flagged. **Create / ready path must pass with inference off** (manual taxonomy + deterministic numbers + Woo draft). +- Vision may prefill taxonomy at ≥0.7 confidence when on; typed values always win; below threshold → leave empty. + +## Ready set (submission ready) + +Review does not continue until the full ready set is filled. Species + one figure is not enough. + +Required: + +- ≥1 inventory PNG (from M2) +- SKU, length, thickness; widths / sqft / bdft present +- Species, ≥1 wood category, edge type, ≥1 figure, ≥1 grade, thickness band, moisture, ≥1 `fig-*`, price +- `feat-*` optional (0+) + +## Create + +- `POST` product to Woo with categories, attributes, tags, price, copy, inventory PNG images. +- Duplicate SKU (any store status) blocks create; no update path in this version. +- `SLAB-UAT-*` always creates as Woo **draft**, even if Settings say publish. +- Device draft ≠ Woo draft. After successful create, clear the device draft. +- Default create status from Settings `woo_create_status` (`draft` \| `publish`, default `draft`), subject to the UAT force-draft rule. + +## Acceptance (done when) + +Product state induced: overnight UAT app on ubudual5060 `http://100.64.0.9:10881` (or the current M3 deploy of this branch), with Woo credentials and `WOO_BASE_URL` pointed at the intended store. + +Evidence from that state: + +1. Taxonomy sync via application password retrieves Woo attributes into the app cache; pickers offer only synced ids. +2. A Photos-ready slab can be filled to the full ready set using those synced lists (inference off is a required path). +3. Create with `SLAB-UAT-*` yields a WooCommerce **draft** product whose categories / attributes / tags / price / images match the reviewed ready set. +4. Duplicate SKU is blocked; device draft clears after success. +5. Inference Settings accept an OpenAI-compatible base URL / key / model; create still succeeds with inference disabled. + +## Dishonest proxies (do not count as pass) + +- Hardcoded or fixture taxonomy lists treated as “synced” +- Mock Woo client or in-process fake that never hit the real store +- Claiming ready / create green from unit tests alone without a real draft in the store +- Consumer-key auth instead of application password +- Inference “wired” only as dead config with no server proxy path, or create that requires inference on +- Touching `:10880` (Ty Node/SvelteKit) or dumping work onto `m2-ds` / doc-simplification branches + +## Out of scope (unless Ty expands M3 in chat) + +- Full Assist UX beyond the OpenAI endpoint dependency and optional prefill rules above +- Creating new Woo attributes / terms / tags from the app +- Update-in-place of an existing store SKU +- Bulk create diff --git a/docs/PRODUCT.md b/docs/PRODUCT.md index 0c7ada7..e87e580 100644 --- a/docs/PRODUCT.md +++ b/docs/PRODUCT.md @@ -39,39 +39,32 @@ Milestone 3 uses FastAPI as the Woo client. Store credentials stay on the server ## Create +Spec: `docs/CREATE.md` (Milestone 3 SoT on this branch). + `SLAB-UAT-*` creates as a WooCommerce draft (store status). Duplicate SKU blocks create. A listing can be created with inference off. A device draft in the app is separate from a WooCommerce draft. +Woo attributes (synced taxonomy) and the OpenAI-compatible inference Settings dependency are defined in `docs/CREATE.md`. ## Milestones -Work is split into four milestones. Each milestone is done when its acceptance can be demonstrated. +M1 and M2 are shipped inputs. **M3 scope is defined in `docs/CREATE.md` and Ty conversations — not by older splits on `main`.** ### Milestone 1 — Capture -Spec: `docs/CAPTURE.md`. Done historically; handoff into Milestone 2. - -User stories: -- Photograph a slab on a green or black sheet and remove the background. -- Set length from the bounding rectangle and get widths, sqft, and bdft. -- Leave and later Continue or Start fresh. - -Acceptance: inventory PNG and measurements visible on a phone. No Woo create. +Spec: `docs/CAPTURE.md`. Shipped; handoff into Milestone 2. ### Milestone 2 — Photos -Spec: `docs/PHOTOS.md`. Current work. - -Batch photos of one slab, pick calibration, run Milestone 1 on that reference, apply the same mask params and crop to the rest, preview all inventory PNGs lined up, plus a dimension-overlay copy of the calibration PNG. -Acceptance: on a phone, 1–N store-ready inventory PNGs for the slab (including dimension overlay on the calibration copy) with Milestone 1 measures visible. No Woo create. No Complete-listing taxonomy in this milestone. +Spec: `docs/PHOTOS.md`. Shipped on UAT `:10881`. No Woo create. No Complete-listing taxonomy in this milestone. ### Milestone 3 — Create -WooCommerce draft for a practice SKU. Then clear the device draft. -Acceptance: `SLAB-UAT-*` exists in the store as draft. +Spec: `docs/CREATE.md`. Current work on branch `m3-ds`. +Woo attributes sync via application password, ready-set use of that taxonomy, product create, inference endpoint dependency. +Acceptance: see Done when in `docs/CREATE.md`. -### Milestone 4 — Assist +### Later work -Optional vision and generated copy on the manual path from Milestones 1–3. -Acceptance: create still works with inference off. +Anything beyond `docs/CREATE.md` (including fuller Assist UX) is out of M3 unless Ty expands scope in chat. diff --git a/docs/archive/README.md b/docs/archive/README.md index 6cd3296..298473a 100644 --- a/docs/archive/README.md +++ b/docs/archive/README.md @@ -15,3 +15,7 @@ Live spec on this branch: - `docs/PRODUCT.md` - `docs/CAPTURE.md` - `deploy/` for hosting only + +## M3 note (2026-09-16) + +For Milestone 3 on branch `m3-ds`, do **not** treat docs frozen on `main` as scope SoT. Use `docs/CREATE.md` on `m3-ds` (conversation-locked). Archive / `main` files remain historical reference only.