Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 grokbot_ty
|
abef27cf2a |
@@ -1,203 +0,0 @@
|
||||
# Requirements reconciliation — decision record
|
||||
|
||||
- Date: 2026-09-18
|
||||
- Branch: `docs/clean-main`
|
||||
- Participants: Ty + opencode
|
||||
- Status: working record. Gets distilled into `docs/REQUIREMENTS.md`, then retired.
|
||||
|
||||
This captures the decisions made while consolidating the scattered requirements, so
|
||||
context is not lost between sessions. Loose ends are collected in section 16.
|
||||
|
||||
## 1. Why this exists
|
||||
|
||||
Requirements are scattered across layers of docs (old `main` specs, current branch docs,
|
||||
`archive/`), with duplicates and contradictions. Goal: one clean `main` holding all shipped
|
||||
code plus one reconciled requirement set, with M3 scoped as a subset of it. Coding is paused
|
||||
until that exists.
|
||||
|
||||
## 2. Git state established
|
||||
|
||||
1. `pre-simplification` tag created at `13bfa792bb3ed968b333675c85bcec0c451e2635` (old main tip; retains the deleted specs: ARCHITECTURE, IMPL-PLAN, OPENAPI, DATA-MODEL, TEST-SPEC, UX, UX-DESIGN, TECH-SPEC-PIPELINE, DEPLOYMENT, PROMPTS, Build-release-standard).
|
||||
2. `main` fast-forwarded to `d754cac` (the M1>M2>M3 code line). `main` now holds all shipped code plus current docs.
|
||||
3. Local `m3-ds` created, tracking `origin/m3-ds`.
|
||||
4. Phase 1 scaffold committed as `b42e3cb` on branch `docs/clean-main`.
|
||||
5. Nothing pushed. `origin/main` still at the old tip until we decide to push.
|
||||
|
||||
## 3. Process rules adopted
|
||||
|
||||
1. Coding is paused until the requirement set is reconciled.
|
||||
2. Requirements live only in `docs/REQUIREMENTS.md`, one row per requirement, with stable IDs.
|
||||
3. Milestones are expressed as explicit subsets of requirement IDs (`docs/MILESTONES.md`).
|
||||
4. Conflict resolution rule: current/later docs plus the code that actually runs beat the tag and `archive/`. "Typically later docs prevail."
|
||||
5. The structure is enforced by `tools/check_requirements.py` (registered docs, unique IDs, traceability).
|
||||
6. Verification discipline: no "done" without raw evidence; CI is the only mechanical gate.
|
||||
|
||||
## 4. Namespaces (owner jobs, not tech layers)
|
||||
|
||||
1. `CAPTURE` — ecommerce-ready pics: intake, pick calibration photo, BG removal, crop, axis, length/width, calculations, inventory PNG, dimension overlay, lineup.
|
||||
2. `METADATA` — building the listing: attributes and tags, title, short/deep description, the two inference calls.
|
||||
3. `REVIEW` — confirm and correct: confidence display, field gating, tweaks, per-slab price suggestion and override, ready gate.
|
||||
4. `PUBLISH` — WooCommerce create, draft/live, duplicate SKU, cleanup.
|
||||
5. `SETTINGS` — configured before the session: Woo connection, inference config, species `$/bdft` rates, brand/geo.
|
||||
6. `APP` — foundation: device draft, slab status, resume, server seams, secret handling.
|
||||
7. `OPS` — foundation: deploy, hosts, release, UAT.
|
||||
8. `QUALITY` — foundation: test obligations, vectors, anti-metrics.
|
||||
|
||||
## 5. Capture decisions
|
||||
|
||||
1. Mask controls are exactly two: `Sheet` (auto/green/black) and `Sensitivity` (0–100). Edge offset and Feather are dropped. The Sheet toggle itself is a candidate for removal (auto-detect stays).
|
||||
2. Sensitivity changes are debounced 2000 ms; a Sheet change runs an immediate pass.
|
||||
3. The owner uploads all photos of the slab, then selects one as the calibration photo. That photo drives every downstream step, is duplicated with dimensions added, and becomes the first showcase image.
|
||||
4. Crop is 90% fill, shorter side at least 800 px when the source allows (shipped values beat the old 80%/1600).
|
||||
5. Length and thickness are the only user-set numbers. Widths, sqft, and bdft are computed from the approved mask and are immutable in production (no typed override).
|
||||
6. Widths are sampled every 6 inches along the approved axis, dropping the first and last 6 inches.
|
||||
7. Thickness band uses the round-up model: measured `1"` lands in the `1–1.5"` store band.
|
||||
8. Woo image order is locked: clean calibration PNG, then dimension-overlay copy, then remaining batch photos in the order added. Minimum two images per listing; cap five.
|
||||
|
||||
## 6. Ready set (submission-ready)
|
||||
|
||||
Required:
|
||||
|
||||
1. At least two images — clean first pic plus its dimension-overlay copy.
|
||||
2. `sku` matching `[A-Z0-9-]{3,24}`.
|
||||
3. `length_in` and `thickness_in`.
|
||||
4. Widths / sqft / bdft (computed, immutable).
|
||||
5. `categories` — exactly one species leaf.
|
||||
6. `categories` — at least one wood-category leaf.
|
||||
7. `attributes[Edge Type]` — one term.
|
||||
8. `attributes[Figure]` — at least one term.
|
||||
9. `attributes[Grade]` — exactly one term.
|
||||
10. `attributes[Thickness]` — one term (round-up band).
|
||||
11. `attributes[Moisture]` — one term, default kiln-dried.
|
||||
12. `regular_price`.
|
||||
13. `name`, `short_description`, `description`.
|
||||
|
||||
Optional: all Woo product tags (figure family and features family).
|
||||
|
||||
Woo schema field mapping lives in section 6 of this record and will become the `METADATA` requirements.
|
||||
|
||||
Note: title / short description / description are required on the product. Because deterministic templates are the inference-off fallback, they are guaranteed non-empty at create.
|
||||
|
||||
## 7. Taxonomy and categories
|
||||
|
||||
1. Categories sync from Woo; the product is assigned to leaf categories. Parents are never assigned but matter in context: the site shows them (breadcrumbs/filters) and Call 2 receives the parent path as context.
|
||||
2. Species is exactly one synced leaf. Wood category is one or more synced leaves.
|
||||
3. In review, the owner designates a primary wood category and any secondary ones. Default primary is the first category selected. How the owner corrects it, and how they stay aware of it, is a UX problem deferred to design.
|
||||
4. Primary drives the title. Primary plus secondary drives the description prose.
|
||||
5. The primary leaf selects a specialized Call 2 prompt. This is the "common pattern."
|
||||
6. Wood-category leaves: Knife blanks, Specialty cuts, Dimensional wood, Live edge wood, Bowl blanks, logs and caps, Pen blanks, Pepper mill blanks. All are settled prose/prompt work items except `Specialty cuts`, which is parked.
|
||||
7. All Woo product tags are optional. Tags come from the synced Woo set; no hardcoded names or prefixes. Wrinkle: one figure tag is bare `fig` (Figured), so a `fig-*` glob would drop it — the filter must be data-driven.
|
||||
8. Current tags. Features: `feat-mincr` (Crack/Check minor), `feat-resin` (Resin Ready). Figure: `fig` (Figured), `fig-brdseye`, `fig-chatoy`, `fig-crotch`, `fig-curl`, `fig-fback`, `fig-flame`, `fig-hfig`, `fig-marbled`, `fig-quilted`, `fig-splt`.
|
||||
|
||||
## 8. Locked attributes
|
||||
|
||||
1. `attributes[Edge Type]` — 1 term.
|
||||
2. `attributes[Figure]` — at least 1 term; includes `plain` for basic slabs; never left empty.
|
||||
3. `attributes[Grade]` — exactly 1 term.
|
||||
4. `attributes[Thickness]` — 1 term, round-up band.
|
||||
5. `attributes[Moisture]` — 1 term, default kiln-dried, never inferred.
|
||||
6. Missing attributes or terms are skipped, never created. v1 does not invent taxonomy.
|
||||
|
||||
## 9. Text generation (Call 2)
|
||||
|
||||
1. Call 2 produces `name`, `short_description`, and `description`.
|
||||
2. The template is a consistency/style guide in the prompt; the model has creative license. It is not assembled deterministically in code.
|
||||
3. With inference off, the deterministic template is the fallback that fills those three fields.
|
||||
4. Call 2 receives all metadata confirmed or changed in review — not the raw Call 1 suggestions.
|
||||
5. Dimensions are supplied as a literal fact block (species, figure term, length, thickness, average width, width min–max, board feet). The model uses those exact strings and invents no numbers.
|
||||
6. There is no `L × W × T` rectangle assumption; slabs are irregular and width varies.
|
||||
7. The dimension-overlay image is not sent to the model.
|
||||
8. A post-check for number drift is parked as `later`; if it is ever added it is plain deterministic comparison, not an AI call.
|
||||
9. The title separator is a hyphen: ` - `.
|
||||
|
||||
## 10. Inference transport
|
||||
|
||||
1. Calls are asynchronous: the request returns `202`, the client polls and shows phase feedback.
|
||||
2. Phases: uploading, analyzing, still working. Polling is the heartbeat that distinguishes dead connectivity from a working model.
|
||||
3. Tunable defaults: ack 15 s, upload-stall 20 s, overall inference deadline 120 s after ack, poll every 2 s backing off to 10 s.
|
||||
4. On timeout or failure, fail gracefully with a plain message and a Retry action. Retry is offered only if `test-inference` previously passed. A retry replaces any in-flight job (idempotent).
|
||||
5. Inference input is the clean processed image (masked, cropped), composited on soft white, no alpha, downscaled to at most 1024 px long edge, JPEG quality 80.
|
||||
6. Only the pixel cap is exposed in Settings. JPEG quality 80 lives in a server config file.
|
||||
7. Call 1 and Call 2 both receive the images. Call 2 additionally receives the literal fact block.
|
||||
8. Provider threads are dropped; always full resend to the provider.
|
||||
9. Inference never blocks create and never auto-publishes.
|
||||
|
||||
## 11. Prompt management
|
||||
|
||||
1. Prompts are stored in SQLite as immutable revisions, seeded from bundled repo defaults on first run.
|
||||
2. Saving appends a revision; an active pointer selects which revision is live.
|
||||
3. Reset to default re-activates the bundled default; reset to a revision re-activates that revision.
|
||||
4. Each inference call records the revision id/hash it used.
|
||||
5. A runtime debug flag gates both the Advanced settings UI and the prompt-write endpoints. Single build, not two.
|
||||
6. This is post-M3 (`later`).
|
||||
|
||||
## 12. Pricing
|
||||
|
||||
1. A flat `$/bdft` rate per species is configured in Settings, matched to a synced species leaf. No tiers in v1.
|
||||
2. The per-slab suggestion is `bdft × rate`; the owner may override and the override sticks. No rule means an empty price the owner types.
|
||||
3. The price field and its suggestion live in the review screen.
|
||||
|
||||
## 13. Publish
|
||||
|
||||
1. Create sequence is the documented one: validate the ready set, look up the SKU (stop if it exists), refresh taxonomy if older than one hour, resolve categories/tags/attributes, upload inventory PNGs, `POST /products`, then finalize.
|
||||
2. On success the local slab row is deleted. WooCommerce is the only source of truth; `sync_log` is retained; photos are purged; the device draft is cleared.
|
||||
3. `SLAB-UAT-*` always creates a Woo draft.
|
||||
4. A duplicate SKU blocks create; there is no update path.
|
||||
5. A stale value on submit is a field-level error telling the owner to pick from the current list.
|
||||
|
||||
## 14. Settings
|
||||
|
||||
1. Compose env: `WOO_BASE_URL` (https only), `SLAB_AES_KEY`.
|
||||
2. Encrypted in SQLite: `woo_wp_username`, `woo_app_password`, `inference_base_url`, `inference_api_key`.
|
||||
3. Plain settings: `inference_model`, `inference_enabled`, `content_llm_enabled`, `woo_create_status` (default draft), `brand_voice`, `geo_context`.
|
||||
4. Derived: `taxonomy_last_sync_at`, `taxonomy_anchor`.
|
||||
5. Auth is a WordPress application password for a dedicated low-privilege user; not consumer keys, not the login password.
|
||||
|
||||
## 15. Scope mapping
|
||||
|
||||
Shipped: M1 Capture, M2 Photos, capture knob prefs.
|
||||
|
||||
M3: store-connection and AI-connection settings; taxonomy sync; the five attributes; Call 1; Call 2; title/description generation; review screen with field gating; pricing; publish; local draft cleanup.
|
||||
|
||||
Later: prompt-management UI, U2Net, offline capture, OCR/ruler, batch create, number-drift check, Specialty cuts prose, primary-category correction UX.
|
||||
|
||||
## 16. Open / parked items
|
||||
|
||||
1. `attributes` element shape on `POST /products` is open — needs a live Whidbey product sample or the official Woo REST fields. Do not invent.
|
||||
2. Server persistence approach is open — full OpenAPI slab CRUD vs a thinner FastAPI path.
|
||||
3. `Specialty cuts` leaf prose is parked.
|
||||
4. Primary-category correction and awareness is a UX problem, deferred.
|
||||
5. Number-drift check is `later`.
|
||||
6. Prompt management is post-M3.
|
||||
7. The QUALITY/OPS extraction re-run is still pending (the first pass was truncated).
|
||||
8. "Later docs prevail" is the rule, but the tag/archive still hold material not yet reconciled (e.g. U2Net, browser floor, TES vectors, deploy details).
|
||||
|
||||
## 17. Work items
|
||||
|
||||
1. ~~Re-run the QUALITY/OPS extraction.~~ Done 2026-09-18 (TEST-SPEC ~110 rows; plan/deploy/release ~120 rows).
|
||||
2. Write `docs/REQUIREMENTS.md` namespace by namespace, starting with `CAPTURE`.
|
||||
3. Draft the per-leaf title/prose work once the `METADATA` section is being written.
|
||||
4. Migrate capability/contract docs into their homes, make docs branch-neutral, rebuild the structure check, wire CI.
|
||||
|
||||
## 18. Rulings deferred to a final cleanup pass
|
||||
|
||||
These surfaced during the QUALITY/OPS extraction. They do not block writing `REQUIREMENTS.md`; park them and reconcile in the cleanup pass.
|
||||
|
||||
1. Test directory layout: old TEST-SPEC mandates Vitest and `frontend/src/__tests__/`; shipped code uses the Node test runner (`node --import tsx --test`) and `frontend/tests/`. Contradiction.
|
||||
2. Test coverage target (~95% for deterministic modules) — adopt or drop.
|
||||
3. "The Test Bar" role and who authors reports versus Ty's sign-off.
|
||||
4. `docs/checks/check-structure.sh` gate timing and criteria — now replaced by `tools/check_requirements.py`.
|
||||
5. Deploy ports: proposal `18080/18443` versus UAT `:10881`, and `APP_HOSTNAME` binding.
|
||||
6. Backup retention "7 daily + 4 weekly" has no verification test.
|
||||
7. `SLAB_AES_KEY_OLD` rekey env placement (host vs compose).
|
||||
8. Smoke step 5: local `published` versus Woo `draft` mismatch — intended or not.
|
||||
9. Release process: `Build-release-standard` points at GitHub while the repo is Gitea.
|
||||
10. Taxonomy sync endpoint path divergence across docs.
|
||||
11. Ownership of `deploy/INVENTORY.md` across Gate B vs Phase 6.
|
||||
12. Scope labels: do shipped/M3/later map to phases or to release milestones.
|
||||
13. `C1`/`C2` (Call 1 / Call 2) namespace ownership ambiguity.
|
||||
14. Whether `UAT-PRACTICE.md` change control is a gate.
|
||||
15. Definition of "real fixtures" acceptance for TV-3, TV-6, TV-7, TV-10.
|
||||
16. `INF-1` ownership: SETTINGS toggle versus QUALITY suite obligation.
|
||||
17. Server-side API surface (`revision_conflict`, validation module, slab CRUD) belongs to the open server-persistence decision.
|
||||
18. `output_px_min` "never below 1600" from old DEPLOYMENT/IMPL-PLAN versus shipped 800 floor.
|
||||
@@ -1,51 +1,32 @@
|
||||
# AGENTS.md
|
||||
|
||||
## STOP — coding paused (Phase 2: requirements reconciliation)
|
||||
|
||||
Do not implement Milestone 3 or any feature right now. Trunk docs are being consolidated.
|
||||
Scope authority is `docs/REQUIREMENTS.md` + `docs/MILESTONES.md`. M3 will be re-derived as a subset of requirement IDs.
|
||||
The Milestone 3 text below is the pre-reconciliation state and is not authoritative until Phase 2 completes.
|
||||
|
||||
## Structure contract (read before creating any doc)
|
||||
|
||||
Requirements live only in `docs/REQUIREMENTS.md`; milestone scope in `docs/MILESTONES.md`.
|
||||
Before creating or moving any doc, look up its home in `docs/STRUCTURE.md` (artifact registry + namespace routing).
|
||||
If no home exists, stop and ask Ty — do not create a new artifact.
|
||||
Run `python tools/check_requirements.py` after any docs change; it must pass.
|
||||
|
||||
## Agent context
|
||||
|
||||
Read `docs/README.md` first, then this file, `docs/CAPTURE.md`, `docs/PHOTOS.md`, and `docs/CREATE.md`.
|
||||
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.
|
||||
|
||||
Implement **Milestone 3** only. Specification: `docs/CREATE.md`.
|
||||
Product overview: `docs/PRODUCT.md`.
|
||||
## Milestone 2
|
||||
|
||||
**M3 scope** (what is in vs out) comes from Ty conversations and `docs/CREATE.md`.
|
||||
**Behavior** for Woo sync, metadata, pricing, and inference is written into `docs/CREATE.md` from the technical requirements on `main`. Do not treat older milestone splits on `main` as scope authority. Do not code against `main` docs by cross-reference. Use `docs/CREATE.md` 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. Exit criteria: a Photos-ready slab is **submission-ready for WooCommerce**, proven by a `SLAB-UAT-*` Woo draft that matches the reviewed ready set. Inference-off path required.
|
||||
|
||||
## Milestone 1 and 2 (shipped inputs)
|
||||
|
||||
- Capture: `docs/CAPTURE.md`
|
||||
- Photos: `docs/PHOTOS.md` (UAT on `:10881`)
|
||||
Capture. Spec: `docs/CAPTURE.md`. Remains the calibration math and PNG contract Milestone 2 reuses.
|
||||
|
||||
## Invariants
|
||||
|
||||
- Quantity per listing is one.
|
||||
- User enters length, thickness, and SKU.
|
||||
- App may propose remaining listing fields. User reviews before create.
|
||||
- App proposes 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** means synced species and wood categories; Edge, Figure, Grade, Thickness, Moisture; `fig-*` and `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.
|
||||
|
||||
@@ -2,20 +2,12 @@
|
||||
|
||||
Lists one-of-a-kind wood slabs on Whidbey Wood Store.
|
||||
|
||||
Start at [`docs/README.md`](docs/README.md) for goals, what already shipped, and Milestone 3.
|
||||
|
||||
| Artifact | File |
|
||||
|---|---|
|
||||
| Docs map | `docs/README.md` |
|
||||
| Structure contract | `docs/STRUCTURE.md` |
|
||||
| Requirements (normative) | `docs/REQUIREMENTS.md` |
|
||||
| Milestones (ID subsets) | `docs/MILESTONES.md` |
|
||||
| Product overview | `docs/PRODUCT.md` |
|
||||
| PRD | `docs/PRODUCT.md` |
|
||||
| Invariants and agent context | `AGENTS.md` |
|
||||
| Milestone 1 Capture (shipped) | `docs/CAPTURE.md` |
|
||||
| Milestone 2 Photos (shipped) | `docs/PHOTOS.md` |
|
||||
| Milestone 3 Create (paused — requirements reconciliation) | `docs/CREATE.md` |
|
||||
| UAT practice walk | `docs/UAT-PRACTICE.md` |
|
||||
| Milestone 1 | `docs/CAPTURE.md` |
|
||||
| Milestone 2 | `docs/PHOTOS.md` |
|
||||
| Hosting | `deploy/` |
|
||||
|
||||
Owner: Ty. Store: https://www.whidbeywoodstore.com/
|
||||
|
||||
+21
-6
@@ -1,20 +1,35 @@
|
||||
# Host
|
||||
|
||||
## Overnight Milestone 2 Capture (UAT)
|
||||
## Overnight Capture UAT (primary — when Tailscale is up)
|
||||
|
||||
- Host: `ubudual5060` / Tailscale `100.64.0.9`
|
||||
- Container: `slabuploader-m2-overnight` (image `slabuploader-m2:overnight`)
|
||||
- Container: `slabuploader-m2-overnight` (image `slabuploader-m2:overnight`) — or salvage rebuild of the same role
|
||||
- Port: **10881** → 80
|
||||
- URL: `http://100.64.0.9:10881`
|
||||
- Replaces prior overnight container `slabuploader-m1-overnight` (same port).
|
||||
|
||||
## Ty local Node/SvelteKit (do not overwrite)
|
||||
## Fallback UAT — Grok Bot computer (when Tailscale to 5060 is down)
|
||||
|
||||
Use this path for salvage / Capture UAT until the box can reach `100.64.0.9` again.
|
||||
|
||||
- Host: Grok Bot computer (slab-m1 box)
|
||||
- Serve: static Capture build (`frontend` → `npm run build`, then `vite preview` or equivalent static server)
|
||||
- Port: **18181** (chosen so it never collides with Ty local on 5060)
|
||||
- Bind: `0.0.0.0:18181`
|
||||
- URL (from this box): `http://127.0.0.1:18181` — Ty reaches it via the bot computer / whatever path the app exposes; Tailscale IP of this box when mesh returns
|
||||
- Branch for salvage: `salvage-one-woo-draft` (cut from `m2-ds`)
|
||||
- Do **not** require Docker on the box for this fallback.
|
||||
|
||||
When Tailscale is restored, prefer primary overnight `:10881` again and stop advertising the fallback as the main UAT URL.
|
||||
|
||||
## Ty local Node/SvelteKit on 5060 (do not overwrite)
|
||||
|
||||
- Host: `ubudual5060` / `100.64.0.9`
|
||||
- Container: `slabuploader-m1`
|
||||
- Port: **18080** → 80 (inventory previously listed 10880; do not bind overnight there)
|
||||
- Port: **18080** → 80
|
||||
- URL: `http://100.64.0.9:18080`
|
||||
- **Never** recreate or remap this container for overnight UAT.
|
||||
- **Never** recreate or remap this container for overnight or box-fallback UAT.
|
||||
- **Never** bind overnight or fallback UAT to **10880** either (legacy Ty local).
|
||||
|
||||
Future overnight Capture deploys use a **separate** container name and an open **108XX** port other than Ty’s local port.
|
||||
Future overnight Capture deploys use a **separate** container name and an open **108XX** port other than Ty’s local ports.
|
||||
Do not put a host name in the product spec.
|
||||
|
||||
@@ -1,201 +0,0 @@
|
||||
# Listing copy and the store
|
||||
|
||||
> On branch `m3-ds`, Milestone 3 exit and scope live in `docs/CREATE.md`. This file is the listing-copy and Woo create/payload reference brought from `main` so coding does not need to open `main`. If anything conflicts with a Ty conversation lock in `CREATE.md`, `CREATE.md` wins.
|
||||
|
||||
|
||||
How titles and descriptions are built, how we talk to WooCommerce, and the exact create payload. Templates always run. Generate text is optional and never publishes on its own.
|
||||
|
||||
## 1. Titles and descriptions
|
||||
|
||||
### 1.1 Templates (always on)
|
||||
Templates live in Settings. Defaults below. Placeholders use `{field}`.
|
||||
|
||||
**title** (default):
|
||||
```
|
||||
{species} {length_ft}ft {length_in_remainder}in × {width_avg_in}in Wood Slab — {character}
|
||||
```
|
||||
Example: `Black Walnut 16ft 0in × 18.2in Wood Slab — Cathedral`
|
||||
- `length_ft` = floor(length_in / 12), `length_in_remainder` = length_in mod 12 (1 dp).
|
||||
|
||||
**short_title** (default):
|
||||
```
|
||||
{species} Slab — {character}
|
||||
```
|
||||
Example: `Black Walnut Slab — Cathedral`
|
||||
|
||||
**description** (default, multi-paragraph):
|
||||
```
|
||||
A one-of-a-one {character} {species} slab, {length_ft}ft {length_in_remainder}in long with an
|
||||
average width of {width_avg_in}in and {thickness_in}in thickness ({bdft} bdft).
|
||||
|
||||
Each slab is naturally shaped — width varies along the length at {width_min_in}in to
|
||||
{width_max_in}in. Sold by the slab; dimensions as measured. {geo_sentence}
|
||||
```
|
||||
`geo_sentence` is the geography sentence from Settings, e.g.
|
||||
`"Locally milled and shipped from the Pacific Northwest."` (default if unset: none).
|
||||
|
||||
All template math fields come from the deterministic pipeline (never from the LLM).
|
||||
|
||||
### 1.2 Generate text (optional)
|
||||
The mill owner taps Generate text on review. It never runs by itself. It is off unless `content_llm_enabled` is true.
|
||||
|
||||
The model writes prose only (character, color, grain, uses). Measured length, width, thickness, square feet, and board feet are facts in the prompt. The model does not invent numbers. Templates inject those numbers into the title and description after the prose comes back.
|
||||
|
||||
The mill owner can always edit the result. `content_source` is `llm` when this path ran.
|
||||
|
||||
If the text endpoint is missing or down, disable the button. Templates still work. Publish is never blocked because Generate text failed.
|
||||
|
||||
### 1.3 Audit
|
||||
Every content generation (template or LLM) is logged with inputs (template version,
|
||||
slab facts), the LLM request/response payload when used (inference calls logged for audit),
|
||||
and the final stored content.
|
||||
|
||||
## 2. WooCommerce
|
||||
|
||||
### 2.1 Auth & client
|
||||
- REST v3 surface unchanged: `GET/POST/PATCH/DELETE {WOO_BASE_URL}/wp-json/wc/v3/…`
|
||||
- Auth is **WordPress Application Passwords**, not WooCommerce consumer keys
|
||||
(`ck_`/`cs_`) and not the user's login password.
|
||||
- Create a **dedicated low-privilege WordPress user** (shop manager, or a custom
|
||||
role with product create/edit + media upload). A dedicated low-privilege user, not the admin account, is used.
|
||||
- Generate the application password under **Users → Profile → Application
|
||||
Passwords**. WordPress requires **HTTPS** for that UI; the store must already
|
||||
be on TLS (Caddy enforces HTTPS on the app side too).
|
||||
- Basic auth shape: `woo_wp_username:woo_app_password` (username + application
|
||||
password). Spaces in the generated password are ignored by WordPress; store
|
||||
the value as entered.
|
||||
- FastAPI is the sole Woo caller. Credentials live encrypted at rest in SQLite
|
||||
(AES-GCM, `SLAB_AES_KEY` env). The browser never holds them.
|
||||
- Rotation: revoke the application password in the WP user profile, enter a new
|
||||
one in Settings UI, then `POST /api/v1/settings/test-woo`.
|
||||
- Client: `httpx` with timeouts (connect 10s, read 60s for image-heavy create).
|
||||
- Store URL is **`WOO_BASE_URL`** from Docker Compose / host `.env` (HTTPS only).
|
||||
FastAPI refuses `http://` at startup. Not a Settings field; UI shows it read-only.
|
||||
|
||||
### 2.2 Store lists (species, tags, attributes)
|
||||
`POST /api/v1/admin/taxonomy/sync` pulls, in order:
|
||||
1. `GET /products/categories?per_page=100` (paginate) → species + wood-category leaves
|
||||
2. `GET /products/tags?per_page=100` → `fig-*` / `feat-*` only (other tags ignored)
|
||||
3. `GET /products/attributes` (+ terms) → five locked attributes
|
||||
|
||||
Rebuilds cache tables in one transaction. Failure → `502 woo_error`; previous
|
||||
cache retained (never delete-then-fail).
|
||||
|
||||
**Manufactured stamps.** Woo REST has **no** usable last-modified on categories,
|
||||
attributes, or tags. FastAPI persists `taxonomy_last_sync_at` (every successful
|
||||
pull) and `taxonomy_anchor` (bump only when stored-subset hash changes, including
|
||||
deletions). Client re-pulls the full taxonomy iff the anchor advanced. No Woo-side
|
||||
taxonomy timestamp; no per-navigation sync.
|
||||
|
||||
**Triggers:** (1) successful `test-woo` **always** resyncs; (2) publish if
|
||||
`now - taxonomy_last_sync_at > 1 hour` then reconcile (bump only on real change);
|
||||
(3) optional app launch / Settings refresh. If a picked id vanished after a refresh, show that field as no longer valid. The selection is not silently swapped.
|
||||
|
||||
**Species exclusivity.** UI pickers, pricing seeds, and Call 1 species lists are
|
||||
**exactly** the synced species-category leaves. No hardcoded, invented, or fallback
|
||||
species set. A species new in Woo is selectable only after the next sync stores it.
|
||||
|
||||
### 2.3 What goes on the listing
|
||||
|
||||
When vision is on and it is at least 0.7 sure, it fills species, wood categories,
|
||||
edge, figure, grade, and feature tags (character, inclusions, voids, checks map
|
||||
to existing `feat-*` tags only). The mill owner can change every filled value.
|
||||
Typed values always win.
|
||||
|
||||
If it is less sure, those fields stay empty. That empty-start subset is not
|
||||
the submit list. Review will not continue until the full ready set is filled:
|
||||
SKU, length, thickness, price, species, wood category, edge type, figure,
|
||||
grade, thickness band, moisture, fig-* tags, and inventory PNG(s). Species
|
||||
plus one figure is not enough. Presentation: `docs/UX.md`.
|
||||
Low-confidence guesses are not filled.
|
||||
|
||||
Names from vision or from typing match store ids case-insensitive, trimmed. No
|
||||
match leaves the field empty so they can pick from the list. The store will still
|
||||
reject a missing required field at publish.
|
||||
|
||||
|
||||
Field rules:
|
||||
- **Categories**: species leaf (1 required) plus wood-category leaf ids (1+).
|
||||
- **Tags**: `fig-*` (1+ required) and `feat-*` (0+). Only documented
|
||||
character or species product tags are used. Woo is authoritative for tag definitions.
|
||||
- **Attributes**: the five locked Woo attributes only — Edge Type, Figure, Grade,
|
||||
Thickness, Moisture — using term ids from the cache. Species,
|
||||
character, length, or free-text thickness as product attributes. Missing
|
||||
attributes are skipped, not created (v1: no attribute creation).
|
||||
|
||||
Vision only suggests. It never blocks publish. With vision off, everything is typed.
|
||||
|
||||
### 2.4 Create payload
|
||||
`POST /products` — body (only non-null fields sent):
|
||||
```jsonc
|
||||
{
|
||||
"name": "{title}",
|
||||
"type": "simple",
|
||||
"status": "{woo_create_status}", // draft | publish; default draft; SLAB-UAT-* forced draft
|
||||
"sku": "{sku}",
|
||||
"regular_price": "{price}", // 2 dp string, e.g. "2730.00"
|
||||
"description": "{description}",
|
||||
"short_description": "{short_title}",
|
||||
"categories": [ { "id": <species category id> } ],
|
||||
"tags": [ { "id": <fig-* tag id> }, { "id": <feat-* tag id> }, … ],
|
||||
"images": [
|
||||
{ "src": "<data URL or pre-uploaded attachment URL>", "alt": "{species} {character} slab" }
|
||||
],
|
||||
"attributes": [ … if present … ],
|
||||
"virtual": false,
|
||||
"downloadable": false,
|
||||
"catalog_visibility": "visible"
|
||||
}
|
||||
```
|
||||
**Image upload strategy** (Woo v3): `images[].src` accepts a URL or a data URL.
|
||||
For reliability the server:
|
||||
1. For each customer-facing inventory photo in `seq` order (processed transparent PNGs
|
||||
from the client TECH-SPEC path): `POST /media` with the **PNG bytes** → get attachment
|
||||
`source_url`. Woo accepts `image/*`; keep alpha. JPEG re-encoding drops alpha and must not happen.
|
||||
2. Reference those `source_url` values in `images` (≤5 inventory photos).
|
||||
3. Only `kind=inventory` photos. Calibration photos do not exist in this design.
|
||||
|
||||
**Status** comes from Settings `woo_create_status` (`draft` or `publish`, default
|
||||
`draft`). Practice SKUs `SLAB-UAT-*` are always created as drafts, even if Settings
|
||||
say publish. Existing SKUs are not edited in this version. After a successful create,
|
||||
the server deletes the original and processed photos. A slab marked published in the
|
||||
app means the store create succeeded. That is not the same as WooCommerce "publish."
|
||||
The force-draft rule is in `AGENTS.md`. This file only owns the payload and the steps.
|
||||
|
||||
### 2.5 Duplicate SKU
|
||||
Before create: `GET /products?sku={sku}` (any store status).
|
||||
- Found: stop. The phone shows the SKU field with Edit SKU and Open existing listing. This version does not update the other product.
|
||||
- Not found: create. Still do the check every time.
|
||||
|
||||
### 2.6 After a failed publish
|
||||
|
||||
The mill owner sees a message on the field, not a status number or a stack. The form stays on the phone. The server marks the slab failed so they can try again.
|
||||
|
||||
If the SKU already exists: under SKU, "This SKU already exists in the store (any status)." Edit SKU, or open the existing listing (admin link when we have it).
|
||||
|
||||
If a category, attribute, or price is no longer valid: under that field, "This value is no longer valid. Pick from the current list," with the current store options.
|
||||
|
||||
The server still writes `sync_log`. Success still sets `woo_product_id`, marks published locally, and deletes photos.
|
||||
|
||||
- **Partial-failure note** (risk, see IMPL-PLAN): if media uploads succeed but the
|
||||
final product POST fails, orphaned Woo attachments may exist. v1: log it; surface
|
||||
a manual cleanup note. Not auto-deleted.
|
||||
|
||||
## 3. End-to-end publish sequence (server side)
|
||||
```
|
||||
1. check the listing against the shared rules (current copy of the rules on submit)
|
||||
2. look up the SKU in the store (any status). Stop if it already exists.
|
||||
3. refresh store lists if the last successful pull is older than 1 hour. Only bump the client list-version if something actually changed.
|
||||
4. resolve categories, tags, and attributes from the synced lists (vision names or typed names)
|
||||
5. upload processed PNG inventory photos to media, keep the URLs
|
||||
6. POST /products with draft/publish per Settings, always draft for SLAB-UAT-* SKUs
|
||||
7. on success: log, mark published locally, delete originals and processed photos
|
||||
on failure: log, mark failed, keep photos, put the error on the field (§2.6)
|
||||
```
|
||||
|
||||
## 4. What the model may and may not do
|
||||
|
||||
Templates, numbers, matching names to store ids, payload, dedupe, logging: code.
|
||||
Generate text may write description prose only. It must not invent dimensions. It may only pick species and attributes that exist in the synced store lists.
|
||||
|
||||
Presentation: `docs/UX.md`. The wire uses `{ field, code, message, actions[] }`. The mill owner never sees those codes. If the phone's copy of the rules is stale, refresh the copy and retry. That is not a duplicate-SKU conflict.
|
||||
-431
@@ -1,431 +0,0 @@
|
||||
# Milestone 3 Create
|
||||
|
||||
## Purpose
|
||||
|
||||
Milestone 3 takes a Photos-ready device draft and makes the slab **submission-ready for WooCommerce**.
|
||||
|
||||
Submission-ready means the mill owner has filled the full store listing package against **live synced Woo attributes**, with price set, and can create the product in the store (practice SKUs as Woo drafts). Photos and measures from Milestones 1 and 2 are inputs. They are not enough by themselves.
|
||||
|
||||
**Exit criteria.** On the M3 UAT deploy, a Photos-ready slab reaches submission-ready and a `SLAB-UAT-*` product exists in WooCommerce as a **draft** whose categories, attributes, tags, price, and inventory images match the reviewed ready set. Create still works with inference off.
|
||||
|
||||
## How to read this file
|
||||
|
||||
This file is the Milestone 3 source of truth on branch `m3-ds`.
|
||||
|
||||
- **What is in M3** comes from Ty conversations on this branch (not from older milestone splits on `main`).
|
||||
- **How Woo sync, metadata, pricing, and inference behave** is taken from the technical requirements on `main` (`CONTENT-WOO`, `DATA-MODEL`, `UX`, `ARCHITECTURE`, `OPENAPI`, `AGENTS`, `UAT-PRACTICE`, `DEPLOYMENT`) and written here so coding does not need to open `main`.
|
||||
|
||||
Related shipped specs: `docs/CAPTURE.md`, `docs/PHOTOS.md`. Listing copy and Woo payload detail: `docs/CONTENT-WOO.md` (from `main`). Product overview: `docs/PRODUCT.md`. Folder map: `docs/README.md`.
|
||||
|
||||
## Preconditions (already shipped)
|
||||
|
||||
On this branch before M3 work:
|
||||
|
||||
- Milestone 1 Capture works in the browser (`docs/CAPTURE.md`).
|
||||
- Milestone 2 Photos works in the browser (`docs/PHOTOS.md`). UAT evidence on `:10881`.
|
||||
- Device draft holds Photos-ready inventory PNGs, calibration measures, and related state.
|
||||
- `frontend/` holds that client path. `backend/` does not yet implement the Woo client or inference proxy.
|
||||
|
||||
M3 adds the server path, Settings, taxonomy sync, review/ready fields, pricing, inference dependency, and Woo create.
|
||||
|
||||
## In scope
|
||||
|
||||
1. WooCommerce auth with WordPress application password (server-side).
|
||||
2. Sync of **Woo attributes** from the store and correct use of those lists for the listing.
|
||||
3. Review UI and rules to reach submission-ready (full ready set).
|
||||
4. Pricing proposal from species `$/bdft` rules and user override.
|
||||
5. OpenAI-compatible inference endpoint as a Settings dependency, with Call 1 / Call 2 behavior when enabled.
|
||||
6. Create product in WooCommerce (force draft for `SLAB-UAT-*`), then clear the device draft on success.
|
||||
|
||||
## Out of scope unless Ty expands M3 in chat
|
||||
|
||||
- Creating new Woo categories, attributes, terms, or tags from the app.
|
||||
- Updating an existing store SKU in place.
|
||||
- Bulk create.
|
||||
- Touching deploy port `:10880`.
|
||||
- Dumping work onto `m2-ds` or doc-simplification branches.
|
||||
|
||||
---
|
||||
|
||||
## Woo attributes
|
||||
|
||||
Locked name for the synced taxonomy package. WooCommerce is the source of truth. The app caches ids. It does not invent the lists.
|
||||
|
||||
### Categories (product categories, leaf only)
|
||||
|
||||
| Field | Cardinality | Rule |
|
||||
|---|---|---|
|
||||
| Species | exactly 1 | Synced species leaves only. No hardcoded or fallback species set. A new store species appears only after the next successful sync. |
|
||||
| Wood category | 1 or more | Leaf ids. Parents are grouping only. |
|
||||
|
||||
### Attributes (exactly five locked Woo attributes)
|
||||
|
||||
| Attribute | Cardinality | Rule |
|
||||
|---|---|---|
|
||||
| Edge Type | 1 | Term id from sync. |
|
||||
| Figure | 1 or more | Term ids from sync. |
|
||||
| Grade | 1 or more | Term ids from sync. |
|
||||
| Thickness | 1 | Measured thickness rounded **up** into the store band (example: 1" lands in the store band labeled like `1"-1 1/2"` when that is the store label). |
|
||||
| Moisture | 1 | Defaults to kiln-dried. User sets or keeps it. Never inferred. |
|
||||
|
||||
v1 does not create missing attributes or terms. If a term is missing in Woo, skip it. Do not invent it.
|
||||
|
||||
Species, character, length, and free-text thickness are **not** Woo product attributes. Only the five locked attributes go on the create payload.
|
||||
|
||||
### Tags
|
||||
|
||||
| Prefix | Cardinality | Rule |
|
||||
|---|---|---|
|
||||
| `fig-*` | 1 or more | Required. Other Woo tags are ignored at sync. |
|
||||
| `feat-*` | 0 or more | Optional. Character, inclusions, voids, and checks map onto existing `feat-*` tags only. |
|
||||
|
||||
---
|
||||
|
||||
## Auth and store URL
|
||||
|
||||
From `main` deploy and agents rules, adopted here:
|
||||
|
||||
- FastAPI is the only Woo caller. The browser never holds store credentials.
|
||||
- Auth is a WordPress **application password** for a dedicated low-privilege WP user (shop manager or custom role with product create/edit and media upload). Not WooCommerce consumer keys (`ck_` / `cs_`). Not the store admin login password.
|
||||
- Basic auth shape: `woo_wp_username` + `woo_app_password`.
|
||||
- Store URL is **`WOO_BASE_URL`** from `deploy/.env` / Docker Compose (`https://` only). Injected into the FastAPI container. Settings shows it read-only. Not a SQLite settings row. Change store means edit `.env` and recreate the FastAPI container.
|
||||
- Username and application password are entered in Settings UI, stored AES-GCM encrypted in SQLite (`SLAB_AES_KEY` env).
|
||||
- REST surface: `{WOO_BASE_URL}/wp-json/wc/v3/…`
|
||||
- Client: `httpx` with connect timeout 10s and read timeout 60s for image-heavy create.
|
||||
- Rotate: revoke the application password in WP Users → Profile, enter a new one in Settings, then run `test-woo`.
|
||||
|
||||
---
|
||||
|
||||
## Taxonomy sync
|
||||
|
||||
Endpoint and behavior from `main` OPENAPI / CONTENT-WOO / ARCHITECTURE:
|
||||
|
||||
`POST /api/v1/admin/taxonomy/sync` pulls, in order:
|
||||
|
||||
1. `GET /products/categories?per_page=100` (paginate) → species and wood-category leaves after app filter.
|
||||
2. `GET /products/tags?per_page=100` → keep only `fig-*` and `feat-*`.
|
||||
3. `GET /products/attributes` plus terms → the five locked attributes.
|
||||
|
||||
Rebuild cache tables in one transaction. On failure return `502 woo_error` and **keep** the previous cache. Never delete-then-fail.
|
||||
|
||||
**Stamps.** Woo REST has no usable last-modified for categories, attributes, or tags. FastAPI stores:
|
||||
|
||||
- `taxonomy_last_sync_at` on every successful pull
|
||||
- `taxonomy_anchor` bumped only when the stored-subset hash changes (including deletions)
|
||||
|
||||
Client re-pulls the full taxonomy only when the anchor advances.
|
||||
|
||||
**Triggers.**
|
||||
|
||||
1. Successful `POST /api/v1/settings/test-woo` always resyncs.
|
||||
2. On publish, if `now - taxonomy_last_sync_at > 1 hour`, reconcile (bump anchor only on real change).
|
||||
3. Optional app launch or Settings refresh.
|
||||
|
||||
If a picked id disappeared after refresh, show that field as no longer valid. Do not silently swap another value.
|
||||
|
||||
`GET /api/v1/admin/taxonomy` returns the cached groups plus `taxonomy_anchor` and `taxonomy_last_sync_at`.
|
||||
|
||||
---
|
||||
|
||||
## Submission-ready (ready set)
|
||||
|
||||
A slab is submission-ready only when **all** of the following are present. Species plus one figure is not enough.
|
||||
|
||||
Required:
|
||||
|
||||
- At least one inventory PNG (from Milestone 2)
|
||||
- SKU matching `[A-Z0-9-]{3,24}` (practice runs use `SLAB-UAT-*`)
|
||||
- Length and thickness (from capture, still editable on review)
|
||||
- Client-computed widths, sqft, and bdft (user typed number wins if overridden)
|
||||
- Exactly one species leaf
|
||||
- At least one wood-category leaf
|
||||
- One edge type term
|
||||
- At least one figure term
|
||||
- At least one grade term
|
||||
- Thickness band term (round-up from measured thickness)
|
||||
- One moisture term (default kiln-dried)
|
||||
- At least one `fig-*` tag
|
||||
- Price (see Pricing)
|
||||
|
||||
Optional:
|
||||
|
||||
- `feat-*` tags (zero or more)
|
||||
- Title, short title, description (may be typed, filled by templates at create, or written by Generate text when inference is on). Not required to reach ready.
|
||||
|
||||
Inline per-field nudges show empty required fields as the owner works. The slab cannot reach ready until the full set is filled.
|
||||
|
||||
Server status name for this state: `ready` (see data model below). Publish/create is blocked with `422 unpublishable` until then.
|
||||
|
||||
---
|
||||
|
||||
## Pricing
|
||||
|
||||
From `main` DATA-MODEL / UX / AGENTS:
|
||||
|
||||
- Settings (or admin API) holds `pricing_rules`: one flat `$/bdft` per species name that matches a synced species leaf. No tiers in v1.
|
||||
- Seed rule rows from synced species. The mill owner sets the rate per species.
|
||||
- Proposal: `price = bdft × price_per_bdft` for the selected species.
|
||||
- User may replace the proposal. Override sticks (`price_source` = `override` vs `recommendation`).
|
||||
- If no rule exists for the species, price starts empty and the owner types it.
|
||||
- Publish/create is allowed with a manual price.
|
||||
- `bdft = sqft × thickness_in` (deterministic).
|
||||
|
||||
Admin API surface from `main` OPENAPI:
|
||||
|
||||
- `GET /api/v1/admin/pricing`
|
||||
- `POST /api/v1/admin/pricing`
|
||||
- `PUT /api/v1/admin/pricing/{id}`
|
||||
- `DELETE /api/v1/admin/pricing/{id}`
|
||||
|
||||
---
|
||||
|
||||
## Inference
|
||||
|
||||
M3 includes the OpenAI-compatible endpoint as a real server dependency and the Call 1 / Call 2 rules below. Create must pass with inference **off**.
|
||||
|
||||
### Settings (not compose)
|
||||
|
||||
Stored encrypted in SQLite Settings (not `deploy/.env`):
|
||||
|
||||
- `inference_base_url`
|
||||
- `inference_api_key`
|
||||
- `inference_model`
|
||||
- `inference_enabled`
|
||||
- `content_llm_enabled`
|
||||
|
||||
FastAPI proxies all inference calls. The browser never holds the key.
|
||||
|
||||
`POST /api/v1/settings/test-inference` returns `{ ok, mode: stateful|stateless|fail, vision_capable, detail }`. Mode `fail` blocks Call 2 enablement only. Inference-off create still works.
|
||||
|
||||
### Call 1 (vision / taxonomy assist)
|
||||
|
||||
- Runs only when `inference_enabled` is true (auto after calibrated draft upload when on, or via `POST /api/v1/slabs/{id}/infer-taxon`).
|
||||
- Input: inventory photos downscaled to max 1024px, user metadata, synced Woo taxonomy lists.
|
||||
- Output: species, wood categories, edge, figure, grade, and feature-tag suggestions constrained to synced lists, each with confidence.
|
||||
- Default confidence threshold 0.7 (configurable). At or above threshold: pre-fill on review, still editable. Below: leave empty. Do not show low-confidence guesses as defaults.
|
||||
- Moisture is never inferred.
|
||||
- Typed values always win over model values.
|
||||
- Vision never blocks create and never auto-publishes.
|
||||
|
||||
### Call 2 (Generate text)
|
||||
|
||||
- User-triggered only (`POST /api/v1/slabs/{id}/infer-content`). Never auto.
|
||||
- Requires successful `test-inference` (`ok: true`).
|
||||
- Model writes prose only (character, color, grain, uses). It must not invent dimensions.
|
||||
- Server assembles title, short title, and description from templates with prose injected.
|
||||
- If the endpoint is down, disable the button. Templates still work. Create is never blocked by Generate text failure.
|
||||
|
||||
### Templates (always available)
|
||||
|
||||
Full defaults and Woo payload text live in `docs/CONTENT-WOO.md`. Summary here:
|
||||
|
||||
**title**
|
||||
|
||||
```
|
||||
{species} {length_ft}ft {length_in_remainder}in × {width_avg_in}in Wood Slab - {character}
|
||||
```
|
||||
|
||||
Example from CONTENT-WOO: `Black Walnut 16ft 0in × 18.2in Wood Slab - Cathedral`
|
||||
|
||||
**short_title**
|
||||
|
||||
```
|
||||
{species} Slab - {character}
|
||||
```
|
||||
|
||||
**description** (multi-paragraph)
|
||||
|
||||
```
|
||||
A one-of-a-one {character} {species} slab, {length_ft}ft {length_in_remainder}in long with an
|
||||
average width of {width_avg_in}in and {thickness_in}in thickness ({bdft} bdft).
|
||||
|
||||
Each slab is naturally shaped. Width varies along the length at {width_min_in}in to
|
||||
{width_max_in}in. Sold by the slab; dimensions as measured. {geo_sentence}
|
||||
```
|
||||
|
||||
**What `{character}` means (locked from CONTENT-WOO example + PROMPTS on `main`).**
|
||||
The word after the dash in the example is `Cathedral`, which is a **Figure** attribute term.
|
||||
Fill `{character}` with the primary (first) Figure term **name** from the ready set.
|
||||
If somehow no figure is present, leave that slot empty (ready set normally requires ≥1 figure).
|
||||
Do not confuse this with `feat-*` tags. Call 1 free-text "character / inclusions / voids / checks" map to `feat-*` tags, not to this title slot.
|
||||
|
||||
All template math fields come from the deterministic pipeline, never from the LLM.
|
||||
|
||||
---
|
||||
|
||||
## Review and create flow
|
||||
|
||||
Mill-owner path after Photos-ready:
|
||||
|
||||
1. Upload calibrated / Photos-ready draft to the server (`POST /api/v1/slabs` multipart) when the M3 client reaches that step. Status becomes `calibrated`. If inference is on, Call 1 may run.
|
||||
2. **Review.** Owner fills or overrides every ready-set field. Pickers show only synced Woo attributes.
|
||||
3. When the ready set is complete, status becomes `ready` (submission-ready).
|
||||
4. Owner taps create/publish → `POST /api/v1/slabs/{id}/publish`.
|
||||
5. Server runs the create sequence below. Client polls `GET /api/v1/slabs/{id}`.
|
||||
|
||||
### Create sequence (server)
|
||||
|
||||
1. Check the listing against the ready-set rules.
|
||||
2. Look up SKU in the store (`GET /products?sku={sku}`, any status). Stop if found.
|
||||
3. Refresh taxonomy if last successful pull is older than 1 hour.
|
||||
4. Resolve categories, tags, and attributes from the synced lists.
|
||||
5. Upload inventory PNGs via `POST /media`, keep alpha. Reference `source_url` values on the product. Cap at 5 images. **Woo image order (locked):** (1) clean calibration inventory PNG, (2) dimension-overlay copy of that calibration PNG, (3+) remaining batch inventory PNGs in the order they were added in the web app. The overlay is part of the submission. Do not upload non-inventory artifacts outside that lineup.
|
||||
6. `POST /products` with status from Settings `woo_create_status` (`draft` or `publish`, default `draft`). **`SLAB-UAT-*` always forces draft.**
|
||||
7. On success: log, set `woo_product_id`, mark published locally, delete original and processed photos, clear device draft.
|
||||
8. On failure: log, mark failed, keep photos, put a field-level error on the phone. No raw status codes for the mill owner.
|
||||
|
||||
### Create payload (shape)
|
||||
|
||||
`POST /products` sends only non-null fields. Conceptual body:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"name": "{title}",
|
||||
"type": "simple",
|
||||
"status": "{woo_create_status}",
|
||||
"sku": "{sku}",
|
||||
"regular_price": "{price}",
|
||||
"description": "{description}",
|
||||
"short_description": "{short_title}",
|
||||
"categories": [ { "id": <species leaf id> }, { "id": <wood-category leaf id> }, ... ],
|
||||
"tags": [ { "id": <fig-* and feat-* ids> } ],
|
||||
"images": [ { "src": "<media source_url>", "alt": "{species} {character} slab" } ],
|
||||
"attributes": [ /* Edge, Figure, Grade, Thickness, Moisture term ids when present */ ],
|
||||
"virtual": false,
|
||||
"downloadable": false,
|
||||
"catalog_visibility": "visible"
|
||||
}
|
||||
```
|
||||
|
||||
App "published" means the store create succeeded. That is not the same as the Woo product being live when status is draft.
|
||||
|
||||
### Duplicate SKU
|
||||
|
||||
Before create, if the SKU exists in any store status: block. Show Edit SKU and Open existing listing. This version does not update the other product. API: `409 duplicate_sku`.
|
||||
|
||||
### Stale taxonomy on submit
|
||||
|
||||
If a category, attribute, or price is no longer valid after refresh: under that field, tell the owner to pick from the current list and supply current options (`stale_field`).
|
||||
|
||||
---
|
||||
|
||||
## Settings keys (M3)
|
||||
|
||||
| Key | Where | Notes |
|
||||
|---|---|---|
|
||||
| `WOO_BASE_URL` | compose / `.env` | HTTPS store URL. Read-only in UI. |
|
||||
| `SLAB_AES_KEY` | compose / `.env` | AES master key. Never in DB or repo. |
|
||||
| `woo_wp_username` | Settings (encrypted) | Dedicated WP user. |
|
||||
| `woo_app_password` | Settings (encrypted) | Application password. |
|
||||
| `woo_create_status` | Settings | `draft` or `publish`. Default `draft`. |
|
||||
| `inference_base_url` | Settings (encrypted) | OpenAI-compatible base URL. |
|
||||
| `inference_api_key` | Settings (encrypted) | |
|
||||
| `inference_model` | Settings | |
|
||||
| `inference_enabled` | Settings | |
|
||||
| `content_llm_enabled` | Settings | Gates Generate text. |
|
||||
| `taxonomy_last_sync_at` | Settings / derived | |
|
||||
| `taxonomy_anchor` | Settings / derived | |
|
||||
| `brand_voice`, `geo_context` | Settings | Copy helpers. |
|
||||
|
||||
Relevant Settings API: `GET/PUT /api/v1/settings`, `POST /api/v1/settings/test-woo`, `POST /api/v1/settings/test-inference`.
|
||||
|
||||
---
|
||||
|
||||
## Data shape (submission-ready fields)
|
||||
|
||||
Core slab fields M3 must persist (from `main` DATA-MODEL, adopted here):
|
||||
|
||||
| Field | Rule |
|
||||
|---|---|
|
||||
| `sku` | Required. Unique. |
|
||||
| `status` | `draft` → `calibrated` → `ready` → `publishing` → `published`, or `failed` |
|
||||
| `length_in`, `thickness_in` | Required. 1/8" step. |
|
||||
| `sqft`, `bdft`, widths | From client math. |
|
||||
| `species_id` | 1 species leaf. |
|
||||
| `wood_category_ids` | 1 or more. |
|
||||
| `edge_type_term_id` | 1. |
|
||||
| `figure_term_ids` | 1 or more. |
|
||||
| `grade_term_ids` | 1 or more. |
|
||||
| `thickness_term_id` | Round-up band. |
|
||||
| `moisture_term_id` | 1. Default kiln-dried. |
|
||||
| `fig_tag_ids` | 1 or more. |
|
||||
| `feat_tag_ids` | 0 or more. |
|
||||
| `price`, `price_per_bdft`, `price_source` | See Pricing. |
|
||||
| `title`, `short_title`, `description` | Optional for ready. |
|
||||
|
||||
Cache tables: `woo_categories`, `woo_attributes`, `woo_attribute_terms`, `woo_tags`, `pricing_rules`.
|
||||
|
||||
Device draft (IndexedDB on the phone) is not a WooCommerce draft. Clear the device draft after successful create.
|
||||
|
||||
---
|
||||
|
||||
## Practice / UAT rules
|
||||
|
||||
- Every practice listing uses SKU prefix `SLAB-UAT-*`.
|
||||
- `SLAB-UAT-*` always creates a WooCommerce draft, even if Settings say publish.
|
||||
- Customers must not see practice listings on the storefront.
|
||||
- Inference is **off** for the claimable exit walk. Optional ON path only after inference Settings pass `test-inference`.
|
||||
- UAT deploy for this branch: ubudual5060 `http://100.64.0.9:10881`. Do not use `:10880`.
|
||||
|
||||
---
|
||||
|
||||
## API surface M3 must implement (summary)
|
||||
|
||||
Base path `/api/v1` (health may also be `/api/health`).
|
||||
|
||||
| Area | Methods |
|
||||
|---|---|
|
||||
| Health | `GET /api/health` |
|
||||
| Slabs | `POST/GET/PUT/DELETE /api/v1/slabs`, `GET /api/v1/slabs/{id}` |
|
||||
| Photos | original/processed GET while retained |
|
||||
| Inference | `POST .../infer-taxon`, `POST .../infer-content` |
|
||||
| Publish | `POST .../publish` → 202, poll slab |
|
||||
| Taxonomy | `GET/POST /api/v1/admin/taxonomy`, `.../sync` |
|
||||
| Pricing | CRUD `/api/v1/admin/pricing` |
|
||||
| Settings | `GET/PUT /api/v1/settings`, `test-woo`, `test-inference` |
|
||||
|
||||
Full request and response field lists on historical `main` `docs/OPENAPI.md` are the detail reference if a field is missing here. Prefer extending this file over coding from `main` directly.
|
||||
|
||||
---
|
||||
|
||||
## Done when (exit criteria)
|
||||
|
||||
**Product state induced.** Overnight UAT app on ubudual5060 `http://100.64.0.9:10881` (or the current M3 image of this branch), with `WOO_BASE_URL` and Woo application password pointed at the intended store.
|
||||
|
||||
**Evidence from that state.**
|
||||
|
||||
1. `test-woo` succeeds and taxonomy sync fills Woo attributes into the app cache. Pickers offer only synced ids.
|
||||
2. A Photos-ready slab can be filled to the **full ready set** (submission-ready) using those lists and pricing rules, with **inference off**.
|
||||
3. Create with `SLAB-UAT-*` yields a WooCommerce **draft** whose categories, attributes, tags, price, and inventory 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, and model. `test-inference` runs. Create still succeeds with inference disabled.
|
||||
|
||||
## Dishonest proxies (do not count as pass)
|
||||
|
||||
- Hardcoded or fixture taxonomy lists treated as synced.
|
||||
- Mock Woo client that never hits the real store for the exit walk.
|
||||
- Unit tests alone without a real `SLAB-UAT-*` draft in the store.
|
||||
- Consumer-key auth instead of application password.
|
||||
- Inference "wired" as dead config with no server proxy, or create that requires inference on.
|
||||
- Claiming submission-ready when required ready-set fields are still empty.
|
||||
- Touching `:10880` or parking work on `m2-ds` / doc-simplification.
|
||||
|
||||
## Open decisions (must lock before task breakdown)
|
||||
|
||||
Locked from Ty conversation or from `docs/CONTENT-WOO.md`:
|
||||
|
||||
1. **`categories` on `POST /products`.** **Locked from CONTENT-WOO field rules:** send every ready-set category id (species leaf + each wood-category leaf) as `[{"id": n}, ...]`. The single-id example in CONTENT-WOO §2.4 is incomplete relative to those field rules.
|
||||
|
||||
2. **Template `{character}`.** **Locked from CONTENT-WOO example (`… Wood Slab - Cathedral`):** use the primary Figure term **name**. `feat-*` tags are separate (Call 1 free-text character/inclusions/voids/checks map there).
|
||||
|
||||
3. **Dimension-overlay PNG.** **Locked (Ty 2026-09-16):** Woo image order is (1) clean calibration PNG, (2) dimension-overlay copy, (3+) other inventory PNGs in add order. Cap ≤5.
|
||||
|
||||
Still open (CONTENT-WOO does not fully settle these):
|
||||
|
||||
4. **`attributes` element shape on `POST /products`.** CONTENT-WOO still has `"attributes": [ … if present … ]` with no fields. Need a live Whidbey product JSON sample, or Ty pointing at the official Woo REST fields to use. Do not invent.
|
||||
|
||||
5. **Server persistence.** CONTENT-WOO describes create sequence and payload. It does not choose full OpenAPI slab CRUD vs a thinner FastAPI path on this branch. Still need a lock before coding the server store.
|
||||
|
||||
Non-blocking notes (shipped M1/M2 win on this branch): fill target 90% and 800px floor (not main's 80%/1600); Vite + Svelte SPA (not SvelteKit docs); overlay draw spacing may differ from measure spacing by design.
|
||||
|
||||
If store-specific term labels differ from examples in this file, the synced store lists win.
|
||||
@@ -1,21 +0,0 @@
|
||||
# Milestones
|
||||
|
||||
A milestone is an explicit subset of requirement IDs from `docs/REQUIREMENTS.md`. No prose scope here.
|
||||
|
||||
Populated in Phase 2. Until then every milestone is empty and coding is paused.
|
||||
|
||||
## M1 — Capture (shipped)
|
||||
|
||||
- IDs: —
|
||||
|
||||
## M2 — Photos (shipped)
|
||||
|
||||
- IDs: —
|
||||
|
||||
## M3 — Create (paused)
|
||||
|
||||
- IDs: —
|
||||
|
||||
## Later
|
||||
|
||||
- IDs: —
|
||||
+2
-2
@@ -70,6 +70,6 @@ On a phone UAT build:
|
||||
## Out of scope
|
||||
|
||||
- Complete-listing fields (SKU, species, category, edge, figure, grade, thickness band, moisture, `fig-*` / `feat-*`, title, short title, description, price)
|
||||
- WooCommerce create and submission-ready taxonomy (Milestone 3: `docs/CREATE.md`)
|
||||
- Work beyond `docs/CREATE.md` unless Ty expands M3 in chat
|
||||
- WooCommerce create (Milestone 3)
|
||||
- Inference / Assist (Milestone 4)
|
||||
- Changing Milestone 1 mask/axis/measure math except to reuse its outputs for batch apply and overlays
|
||||
|
||||
+36
-27
@@ -1,4 +1,4 @@
|
||||
# Product overview
|
||||
# Product requirements
|
||||
|
||||
SlabUploader creates one WooCommerce listing per wood slab for Whidbey Wood Store.
|
||||
|
||||
@@ -6,12 +6,8 @@ Each slab is one unit and one listing. Photos and metadata are the inventory rec
|
||||
|
||||
Photographs are taken of the slab on a green or black sheet. That is the capture starting state.
|
||||
|
||||
Owner: Ty. Store: https://www.whidbeywoodstore.com/
|
||||
|
||||
## Complete listing
|
||||
|
||||
A finished listing has:
|
||||
|
||||
- Inventory photo(s), uniform 3:4 transparent PNG
|
||||
- SKU, length, thickness, price
|
||||
- Species, wood category, edge type, figure, grade
|
||||
@@ -20,9 +16,7 @@ A finished listing has:
|
||||
- Title, short title, description
|
||||
- Zero or more `feat-*` tags
|
||||
|
||||
Store categories, attributes, and `fig-*` / `feat-*` tags are the filters shoppers use. Measured values feed title and description templates.
|
||||
|
||||
The locked name for that synced taxonomy package is **Woo attributes**. Details live in `docs/CREATE.md`.
|
||||
Store categories, attributes, and `fig-*` / `feat-*` tags are the filters. Measured values feed title and description templates.
|
||||
|
||||
## Decision rights
|
||||
|
||||
@@ -36,33 +30,48 @@ The locked name for that synced taxonomy package is **Woo attributes**. Details
|
||||
| Price | App proposal `bdft × species $/bdft`; user may replace |
|
||||
| Title, short title, description | Templates from listing facts; user may edit |
|
||||
|
||||
User-entered length, thickness, SKU, price, and taxonomy override computed or inferred values.
|
||||
|
||||
## System seams
|
||||
|
||||
Milestones 1 and 2 run in the browser. No backend and no inference URL on the shipped path.
|
||||
|
||||
Milestones 1 and 2 run in the browser. No backend and no inference URL.
|
||||
Milestone 1 handoff is the device draft: source photo, approved mask, inventory PNG, length, thickness, widths, sqft, bdft.
|
||||
|
||||
Milestone 2 extends the draft with the photo batch, calibration choice, per-photo inventory PNGs, and the dimension-overlay calibration copy.
|
||||
Milestone 3 uses FastAPI as the Woo client. Store credentials stay on the server.
|
||||
|
||||
Milestone 3 introduces FastAPI as the Woo client and inference proxy. Store credentials and inference secrets stay on the server. Spec: `docs/CREATE.md`.
|
||||
## Create
|
||||
|
||||
## Create rules (summary)
|
||||
`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.
|
||||
|
||||
Full behavior is in `docs/CREATE.md`.
|
||||
## Milestones
|
||||
|
||||
- `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.
|
||||
Work is split into four milestones. Each milestone is done when its acceptance can be demonstrated.
|
||||
|
||||
## Milestone status on `m3-ds`
|
||||
### Milestone 1 — Capture
|
||||
|
||||
| Milestone | Spec | Status |
|
||||
|---|---|---|
|
||||
| 1 Capture | `docs/CAPTURE.md` | Shipped |
|
||||
| 2 Photos | `docs/PHOTOS.md` | Shipped (UAT `:10881`) |
|
||||
| 3 Create | `docs/CREATE.md` | Current work. Exit: submission-ready for WooCommerce (`CREATE.md` Done when). Scope from Ty conversations; behavior for sync/metadata/pricing/inference taken from `main` into `CREATE.md`. |
|
||||
Spec: `docs/CAPTURE.md`. Done historically; handoff into Milestone 2.
|
||||
|
||||
Anything beyond `docs/CREATE.md` is out of M3 unless Ty expands scope in chat.
|
||||
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.
|
||||
|
||||
### 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.
|
||||
|
||||
### Milestone 3 — Create
|
||||
|
||||
WooCommerce draft for a practice SKU. Then clear the device draft.
|
||||
Acceptance: `SLAB-UAT-*` exists in the store as draft.
|
||||
|
||||
### Milestone 4 — Assist
|
||||
|
||||
Optional vision and generated copy on the manual path from Milestones 1–3.
|
||||
Acceptance: create still works with inference off.
|
||||
|
||||
@@ -1,60 +0,0 @@
|
||||
# Docs map (branch `m3-ds`)
|
||||
|
||||
Read this file first. It tells you what SlabUploader is for, what already ships, and what Milestone 3 must build.
|
||||
|
||||
**Who this is for.** Mill owner (Ty), humans reviewing scope, and agents implementing on this branch.
|
||||
|
||||
**Source of truth for Milestone 3.** `docs/CREATE.md` plus the Ty conversations that wrote it. Older milestone and task splits on `main` are obsolete for M3. Do not open `main` for scope once you are coding on `m3-ds`.
|
||||
|
||||
## High-level project goal
|
||||
|
||||
SlabUploader lists one-of-a-kind wood slabs on Whidbey Wood Store (WooCommerce).
|
||||
|
||||
One slab is one unit and one listing. Photos and metadata are the inventory record. The mill owner photographs a slab on a green or black sheet, gets store-ready transparent PNGs and measurements on the phone, fills the store's taxonomy and price, then creates a WooCommerce product.
|
||||
|
||||
Store: https://www.whidbeywoodstore.com/
|
||||
|
||||
## What is already implemented (pre-M3)
|
||||
|
||||
| Milestone | Spec | Status on this branch |
|
||||
|---|---|---|
|
||||
| 1 Capture | `docs/CAPTURE.md` | Shipped. Browser-only mask, length axis, measure, inventory PNG, device draft. |
|
||||
| 2 Photos | `docs/PHOTOS.md` | Shipped. Batch photos, pick calibration, apply mask/crop to the batch, dimension overlay, Photos-ready lineup. UAT on `:10881`. |
|
||||
|
||||
There is no Woo create yet. There is no Complete-listing taxonomy UI yet. There is no FastAPI Woo client on this branch (`backend/` is a stub). Inference is not wired.
|
||||
|
||||
## What Milestone 3 builds
|
||||
|
||||
Spec: `docs/CREATE.md`.
|
||||
|
||||
**Exit criteria.** A Photos-ready slab becomes **submission-ready for WooCommerce**, and a practice `SLAB-UAT-*` draft exists in the store that matches the reviewed ready set. Create must still work with inference off.
|
||||
|
||||
In plain terms, M3 connects the Photos-ready device draft to the real store:
|
||||
|
||||
1. Talk to WooCommerce with a WordPress application password (server-side only).
|
||||
2. Sync and use **Woo attributes** (categories, five locked attributes, `fig-*` / `feat-*` tags) per the requirements taken from `main` and written into `CREATE.md`.
|
||||
3. Pricing from species `$/bdft` rules, with user override.
|
||||
4. Inference Settings (OpenAI-compatible URL, key, model) and Call 1 / Call 2 rules when enabled.
|
||||
5. Review to the full ready set, then create the Woo product (force draft for `SLAB-UAT-*`).
|
||||
|
||||
Technical detail for Woo sync, metadata, pricing, and inference is copied into `docs/CREATE.md` from `main` so you do not need to open `main` while coding. Older milestone splits on `main` are still not the scope authority for what M3 includes.
|
||||
|
||||
## How to read the folder
|
||||
|
||||
| File | Role |
|
||||
|---|---|
|
||||
| `README.md` (this file) | Map: goals, shipped, M3. |
|
||||
| `PRODUCT.md` | Product overview: complete listing, decision rights, seams. |
|
||||
| `CAPTURE.md` | Milestone 1 Capture (shipped). |
|
||||
| `PHOTOS.md` | Milestone 2 Photos (shipped). |
|
||||
| `CREATE.md` | Milestone 3 Create (current work). Read this before task breakdown or coding. |
|
||||
| `CONTENT-WOO.md` | Listing copy templates and Woo create/payload detail (from `main`). |
|
||||
| `UAT-PRACTICE.md` | Human practice walk for a `SLAB-UAT-*` listing. Defers to `CREATE.md` on conflict. |
|
||||
| `archive/` | Historical only. Not M3 scope. |
|
||||
|
||||
## Deploy reminders for this branch
|
||||
|
||||
- UAT overnight Docker: ubudual5060 `http://100.64.0.9:10881`
|
||||
- Do not touch `:10880` (Ty Node/SvelteKit)
|
||||
- Store URL (`WOO_BASE_URL`) lives in compose / host `.env`
|
||||
- Woo application password and inference URL live in encrypted Settings, not in compose
|
||||
@@ -1,179 +0,0 @@
|
||||
# Requirements
|
||||
|
||||
Normative source of truth. One row per requirement. Enforced by `tools/check_requirements.py`.
|
||||
|
||||
A requirement is defined here and nowhere else. Capability and contract docs cite IDs; they do not restate them.
|
||||
|
||||
Format and rules: `docs/STRUCTURE.md`.
|
||||
Scope: `shipped` | `M3` | `later`.
|
||||
`Test` is a test path, a requirement ID, or `—` (traceability gap). A path given for a `shipped` requirement must exist.
|
||||
|
||||
Sources reconciled 2026-09-18 from the current branch docs plus the `pre-simplification` tag; decisions recorded in `.audit/2026-09-18-reconciliation-decisions.md`.
|
||||
|
||||
## CAPTURE — ecommerce-ready capture
|
||||
|
||||
| ID | Requirement | Scope | Test |
|
||||
|---|---|---|---|
|
||||
| CAPTURE-1 | Mask, measure, crop, and PNG output are a deterministic function of photo pixels and user inputs, with no inference, model, or network in the math. | shipped | — |
|
||||
| CAPTURE-2 | Supported clients are iOS Safari and Android Chrome, plus desktop Chrome, Edge, and Firefox; unsupported clients get a hard stop, and there are no polyfills. | shipped | — |
|
||||
| CAPTURE-3 | Capture is online only; offline capture is deferred. | later | — |
|
||||
| CAPTURE-4 | Photos are taken on a green or black sheet with the slab fully on the sheet; the first photo is top-down with the lens parallel to the broad face. | shipped | — |
|
||||
| CAPTURE-5 | A batch of one or more photos of one slab is uploaded, and the owner selects which photo is the calibration photo. | shipped | — |
|
||||
| CAPTURE-6 | The calibration photo drives mask, length axis, measure, and crop; other batch photos reuse the approved sheet, sensitivity, and crop rules. | shipped | — |
|
||||
| CAPTURE-7 | Sheet detection samples a 2 to 5 percent strip on all four borders and classifies green or black by HSV; otherwise the owner picks the sheet. | shipped | frontend/src/mask/sheetKeep.test.ts |
|
||||
| CAPTURE-8 | Mask controls are exactly Sheet (auto, green, black) and Sensitivity (0 to 100, step 1); Edge offset and Feather are removed. | shipped | — |
|
||||
| CAPTURE-9 | A Sensitivity change debounces 2000 ms; a Sheet change runs immediately; the overlay recomputes in a worker and the last good overlay stays visible. | shipped | frontend/src/capture/session.calibrate.test.ts |
|
||||
| CAPTURE-10 | The mask overlay renders on the source photo and the owner approves it; approval is blocked when the mask has no slab pixels. | shipped | — |
|
||||
| CAPTURE-11 | The mask must be a single contiguous slab contour; otherwise the resolution is a retake. | shipped | — |
|
||||
| CAPTURE-12 | The length axis is the long side of the minimum-area bounding rectangle of the mask; the owner rotates it to the prevailing length and confirms. | shipped | frontend/src/geometry/rect.test.ts |
|
||||
| CAPTURE-13 | On a nearly square slab the owner chooses which axis is length. | shipped | — |
|
||||
| CAPTURE-14 | The owner enters length and thickness in 1/8 inch steps. | shipped | frontend/src/capture/measureInputs.test.ts |
|
||||
| CAPTURE-15 | scale equals longest_axis_px divided by measured length, where longest_axis_px is the mask span end to end along the approved axis, not the rectangle edge. | shipped | — |
|
||||
| CAPTURE-16 | Widths sample every 6 inches perpendicular to the approved axis, dropping the first and last 6 inches; min, max, and average are reported; if length is 12 inches or less all three are zero. | shipped | frontend/src/measure/measure.test.ts |
|
||||
| CAPTURE-17 | sqft equals mask_pixels divided by scale squared divided by 144, rounded half-up to 2 decimals. | shipped | frontend/src/measure/measure.test.ts |
|
||||
| CAPTURE-18 | bdft equals sqft times thickness_in, rounded half-up to 2 decimals, with no divide-by-12; 1 sqft at 1 inch equals 1 bdft. | shipped | frontend/src/measure/measure.test.ts |
|
||||
| CAPTURE-19 | The inventory PNG is 8-bit RGBA with alpha preserved through encode and upload. | shipped | frontend/src/png/inventory.test.ts |
|
||||
| CAPTURE-20 | Crop is 3:4 portrait, slab centered, 90 percent fill at the widest and tallest extremes, on a transparent background. | shipped | frontend/src/png/inventory.test.ts |
|
||||
| CAPTURE-21 | After crop the shorter side is at least 800 px when the source allows; otherwise warn and require a new photo, and never upscale. | shipped | frontend/src/png/inventory.test.ts |
|
||||
| CAPTURE-22 | A non-calibration photo that yields an empty mask or fails the size floor is excluded with a per-photo error while the rest proceed. | shipped | frontend/src/capture/session.batchApply.test.ts |
|
||||
| CAPTURE-23 | Scale, widths, sqft, and bdft stay tied to the calibration photo; non-calibration photos are visual inventory only. | shipped | frontend/src/capture/session.batchApply.test.ts |
|
||||
| CAPTURE-24 | The dimension overlay is black and oriented to the approved length axis, with the length graphic beside the wood on the right in axis space. | shipped | frontend/src/png/overlay.test.ts |
|
||||
| CAPTURE-25 | Overlay width stations run every 12 inches starting 6 inches from the bottom while station is at most length minus 6; the bottom end follows the calibration photo EXIF orientation. | shipped | frontend/src/png/overlay.test.ts |
|
||||
| CAPTURE-26 | The photos-ready lineup order is clean calibration PNG, dimension-overlay copy, then remaining batch photos in capture order. | shipped | frontend/src/capture/photosReadyLineup.test.ts |
|
||||
| CAPTURE-27 | The client computes all deterministic math; the server stores the client numbers and never recomputes them as source of truth. | shipped | — |
|
||||
| CAPTURE-28 | Load-bearing client APIs are image decode, canvas or OffscreenCanvas, a worker, PNG encode, IndexedDB, and fetch; no OpenCV, ONNX, or U2Net on the shipped path. | shipped | — |
|
||||
| CAPTURE-29 | Capture knob preferences persist in localStorage until reset to default. | shipped | — |
|
||||
| CAPTURE-30 | Mask tuning has no apply step and no server round trip. | shipped | — |
|
||||
| CAPTURE-31 | Failures such as a broken mask or undersized source never silently guess; the resolution is retake. | shipped | — |
|
||||
| CAPTURE-32 | Length is stored and displayed to the nearest 1/8 inch, rounded values are what is stored, and sqin appears nowhere in the UI, tests, or copy. | shipped | — |
|
||||
| CAPTURE-33 | U2Net on-demand server matting is deferred. | later | — |
|
||||
|
||||
## METADATA — listing attributes and copy
|
||||
|
||||
| ID | Requirement | Scope | Test |
|
||||
|---|---|---|---|
|
||||
| METADATA-1 | The listing taxonomy is exactly the synced WooCommerce set; the app never hardcodes, invents, or falls back to its own lists. | M3 | — |
|
||||
| METADATA-2 | Product categories are exactly one species leaf and one or more wood-category leaves; parents group only and are never assigned. | M3 | — |
|
||||
| METADATA-3 | The five locked attributes are Edge Type (1), Figure (at least 1, includes plain), Grade (exactly 1), Thickness (1, round-up band), and Moisture (1, default kiln-dried, never inferred). | M3 | — |
|
||||
| METADATA-4 | Missing attributes or terms are skipped, never created. | M3 | — |
|
||||
| METADATA-5 | Species, character, length, and free-text thickness are not product attributes. | M3 | — |
|
||||
| METADATA-6 | Product tags come from the synced Woo set and are all optional; no hardcoded prefixes, and the bare fig tag is kept. | M3 | — |
|
||||
| METADATA-7 | Call 1 runs only when inference is enabled, automatically after a calibrated draft uploads or on demand, and sends the clean processed photos at 1024 px long edge or less plus user metadata and the synced taxonomy. | M3 | — |
|
||||
| METADATA-8 | Call 1 returns species, wood categories, edge, figure, grade, and feature-tag suggestions constrained to the synced lists, each with confidence. | M3 | — |
|
||||
| METADATA-9 | Call 1 confidence at or above the threshold (default 0.7) pre-fills review fields and below it leaves them empty; suggestions are always editable. | M3 | — |
|
||||
| METADATA-10 | Typed values always win over inferred values. | M3 | — |
|
||||
| METADATA-11 | Call 2 is user-triggered only and produces name, short_description, and description; it never runs automatically. | M3 | — |
|
||||
| METADATA-12 | Call 2 receives all metadata confirmed or changed in review plus the literal dimension fact block; the template guides style and the model has creative license. | M3 | — |
|
||||
| METADATA-13 | The model never invents or alters a dimension; every number it prints comes from the fact block. | M3 | — |
|
||||
| METADATA-14 | With inference off, deterministic templates produce name, short_description, and description so create never lacks prose. | M3 | — |
|
||||
| METADATA-15 | Inference never blocks create and never auto-publishes. | M3 | — |
|
||||
| METADATA-16 | The title uses the primary figure term name as the character, with a hyphen separator. | M3 | — |
|
||||
| METADATA-17 | The primary wood category selects a specialized Call 2 prompt. | M3 | — |
|
||||
| METADATA-18 | The dimension fact block carries exact strings for species, figure term, length, thickness, average width, width min to max, and board feet; there is no L by W by T rectangle assumption. | M3 | — |
|
||||
| METADATA-19 | The dimension-overlay image is never sent to the model. | M3 | — |
|
||||
|
||||
## REVIEW — confirm, tweak, ready
|
||||
|
||||
| ID | Requirement | Scope | Test |
|
||||
|---|---|---|---|
|
||||
| REVIEW-1 | Submission-ready requires at least two images (clean first pic plus its dimension-overlay copy), SKU, length, thickness, computed widths and sqft and bdft, exactly one species leaf, at least one wood-category leaf, one Edge Type, at least one Figure, exactly one Grade, one Thickness band, one Moisture, and a price. | M3 | — |
|
||||
| REVIEW-2 | Title, short_description, and description are required on the product and are satisfied by typed, generated, or templated text. | M3 | — |
|
||||
| REVIEW-3 | In review the owner declares one primary wood category and any secondary ones; primary drives the title and primary plus secondary drive the description; the default primary is the first category selected. | M3 | — |
|
||||
| REVIEW-4 | Every empty required field shows an inline nudge as the owner works; the slab cannot reach ready until the full set is filled, and there is no single submit-time gap list. | M3 | — |
|
||||
| REVIEW-5 | The price suggestion is bdft times the species rate from Settings; the owner may override and the override sticks; no rule leaves the price empty for manual entry. | M3 | — |
|
||||
| REVIEW-6 | Widths, sqft, and bdft are read-only in production, derived from the mask, and are not overridable. | M3 | — |
|
||||
| REVIEW-7 | A picked taxonomy id that disappeared after a refresh shows as no longer valid and is never silently swapped for another value. | M3 | — |
|
||||
| REVIEW-8 | The owner can edit any field, including generated title and description, until create. | M3 | — |
|
||||
|
||||
## PUBLISH — store submission
|
||||
|
||||
| ID | Requirement | Scope | Test |
|
||||
|---|---|---|---|
|
||||
| PUBLISH-1 | The create sequence validates the ready set, looks up the SKU and stops if it exists, refreshes taxonomy when the last sync is over one hour old, resolves categories and tags and attributes, uploads images, calls POST products, then finalizes. | M3 | — |
|
||||
| PUBLISH-2 | SKUs matching SLAB-UAT-* always create a WooCommerce draft regardless of the create-status setting. | M3 | — |
|
||||
| PUBLISH-3 | A duplicate SKU blocks create and offers edit-SKU or open-existing; this version has no update path. | M3 | — |
|
||||
| PUBLISH-4 | A stale value on submit is a field-level error that shows the current options and never a raw code. | M3 | — |
|
||||
| PUBLISH-5 | On success the server sets woo_product_id, purges photos, deletes the local slab row, and clears the device draft; WooCommerce is the source of truth. | M3 | — |
|
||||
| PUBLISH-6 | On failure the slab is marked failed, photos are retained, sync_log is written, and a plain field-level message is shown; retry works from the same screen. | M3 | — |
|
||||
| PUBLISH-7 | The owner never sees raw status codes, stack traces, or internal error codes. | M3 | — |
|
||||
| PUBLISH-8 | Images upload as processed PNGs with alpha, capped at five, and only inventory images are uploaded. | M3 | — |
|
||||
| PUBLISH-9 | The Woo image order is the photos-ready lineup: clean calibration, dimension-overlay copy, then the rest in capture order. | M3 | — |
|
||||
| PUBLISH-10 | Published means the store create succeeded, not that the product is live when status is draft. | M3 | — |
|
||||
| PUBLISH-11 | Only non-null fields are sent; the payload carries name, type simple, status, sku, regular_price, description, short_description, categories, tags, images, attributes, virtual false, downloadable false, catalog_visibility visible. | M3 | — |
|
||||
|
||||
## SETTINGS — configured once
|
||||
|
||||
| ID | Requirement | Scope | Test |
|
||||
|---|---|---|---|
|
||||
| SETTINGS-1 | WOO_BASE_URL lives in compose or .env, is https only, is injected into FastAPI, and is shown read-only in Settings; it is not a SQLite settings row. | M3 | — |
|
||||
| SETTINGS-2 | FastAPI refuses to start when WOO_BASE_URL is missing or not https. | M3 | — |
|
||||
| SETTINGS-3 | Woo auth is a WordPress application password for a dedicated low-privilege user, not consumer keys and not the admin login. | M3 | — |
|
||||
| SETTINGS-4 | Woo username and application password are entered in Settings and stored AES-GCM in SQLite; the browser never keeps them. | M3 | — |
|
||||
| SETTINGS-5 | SLAB_AES_KEY lives in compose or .env as a 32-byte base64 value, never in the DB or repo, and a missing key refuses startup. | M3 | — |
|
||||
| SETTINGS-6 | Inference base URL and API key are stored encrypted in SQLite, while inference_model, inference_enabled, content_llm_enabled, brand_voice, and geo_context are settings. | M3 | — |
|
||||
| SETTINGS-7 | Species rates are configured in Settings as one flat dollars-per-bdft value per synced species leaf, with no tiers. | M3 | — |
|
||||
| SETTINGS-8 | test-woo verifies the connection and always resyncs taxonomy on success. | M3 | — |
|
||||
| SETTINGS-9 | test-inference is a two-turn probe returning ok, mode (stateful, stateless, or fail), vision_capable, and detail; fail blocks Call 2 only. | M3 | — |
|
||||
| SETTINGS-10 | Taxonomy sync pulls categories, tags, and attributes with terms, rebuilds the cache in one transaction, and on failure returns 502 while keeping the previous cache. | M3 | — |
|
||||
| SETTINGS-11 | Every successful sync updates taxonomy_last_sync_at; taxonomy_anchor bumps only when the stored-subset hash changes, including deletions. | M3 | — |
|
||||
| SETTINGS-12 | The client re-pulls the full taxonomy only when the anchor advances, and publish refreshes when the last sync is over one hour old. | M3 | — |
|
||||
| SETTINGS-13 | woo_create_status defaults to draft. | M3 | — |
|
||||
| SETTINGS-14 | The vision pixel cap is the only user-facing vision setting; the JPEG quality lives in server config. | M3 | — |
|
||||
| SETTINGS-15 | Secrets never appear in any GET response; only a configured boolean is returned. | M3 | — |
|
||||
|
||||
## APP — device draft and state
|
||||
|
||||
| ID | Requirement | Scope | Test |
|
||||
|---|---|---|---|
|
||||
| APP-1 | Slab status runs draft, calibrated, ready, publishing, published, or failed. | shipped | — |
|
||||
| APP-2 | The device draft is separate from a WooCommerce draft and is restored on open through Resume; Continue restores the last approved state and Start fresh discards. | shipped | — |
|
||||
| APP-3 | The device draft is cleared after a successful create. | M3 | — |
|
||||
| APP-4 | Slab ids are client-generated, timestamps are UTC ISO-8601, and client_rev and server_rev support optimistic concurrency. | M3 | — |
|
||||
| APP-5 | FastAPI is the only caller of WooCommerce and of the inference endpoint; the browser holds no store or inference credentials. | shipped | — |
|
||||
| APP-6 | The API base is /api/v1 and health is at /api/health. | M3 | — |
|
||||
| APP-7 | Errors use a uniform envelope and are JSON; lists are returned in full without pagination. | M3 | — |
|
||||
| APP-8 | The server stores the client-sent derived numbers and does not recompute them as source of truth. | shipped | — |
|
||||
|
||||
## OPS — deploy and release
|
||||
|
||||
| ID | Requirement | Scope | Test |
|
||||
|---|---|---|---|
|
||||
| OPS-1 | Deploy is Docker Compose plus Caddy on an inventoried host, reachable only over LAN or Tailscale with HTTPS. | shipped | — |
|
||||
| OPS-2 | WOO_BASE_URL and SLAB_AES_KEY are supplied as compose environment and never stored in the repo. | shipped | — |
|
||||
| OPS-3 | deploy/INVENTORY.md is filled before any port bind, covering host, hostname, ports, and DNS reachability from the phone. | shipped | — |
|
||||
| OPS-4 | Services bind to localhost and Caddy is the only public surface. | shipped | — |
|
||||
| OPS-5 | Base images are pinned, not latest. | shipped | — |
|
||||
| OPS-6 | Backup is a WAL-safe SQLite backup plus a tar of the images volume, with retention of 7 daily and 4 weekly. | later | — |
|
||||
| OPS-7 | Restore is stop, restore DB and images, start, and it is tested at least once before backup is considered done. | later | — |
|
||||
| OPS-8 | The UAT environment is ubudual5060 at http://100.64.0.9:10881; port 10880 is off limits. | M3 | — |
|
||||
| OPS-9 | Inference is a remote, configurable endpoint, not part of the app host. | shipped | — |
|
||||
| OPS-10 | The repository on gitea-atd is the source of truth. | shipped | — |
|
||||
|
||||
## QUALITY — verification
|
||||
|
||||
| ID | Requirement | Scope | Test |
|
||||
|---|---|---|---|
|
||||
| QUALITY-1 | Tests are written with the code; no feature ships without a passing test and its shown output. | shipped | — |
|
||||
| QUALITY-2 | Deterministic modules are test-driven and covered before any UI consumes them. | shipped | — |
|
||||
| QUALITY-3 | Unit tests for the deterministic core cover vectors TV-1 through TV-10. | shipped | — |
|
||||
| QUALITY-4 | The full suite passes with inference disabled, asserting zero inference calls. | M3 | — |
|
||||
| QUALITY-5 | Pass or fail is only claimed with raw runner evidence; missing evidence means not run. | shipped | — |
|
||||
| QUALITY-6 | Ty reads raw results and owns gate exit; agents never declare a gate green. | shipped | — |
|
||||
| QUALITY-7 | Integration tests use a Woo mock and cover success, error, duplicate SKU, stale field, and taxonomy anchor. | M3 | — |
|
||||
| QUALITY-8 | Property checks assert bdft is monotonic in thickness and square feet. | shipped | — |
|
||||
| QUALITY-9 | The deterministic functions assert the bdft identity and the no-upscale path. | shipped | — |
|
||||
| QUALITY-10 | UI and end-to-end tests run against a Compose stack with mocked Woo. | M3 | — |
|
||||
| QUALITY-11 | Pipeline vector TV-1: an interior green patch not touching the border survives; U2Net is not invoked. | shipped | — |
|
||||
| QUALITY-12 | Pipeline vector TV-2: dark interior wood on a black sheet survives, and flood fill isolates only border-connected regions. | shipped | — |
|
||||
| QUALITY-13 | Pipeline vector TV-3: a 96 inch slab, 1.5 inch thick, 0.64 sqft mask yields 0.96 bdft. | shipped | — |
|
||||
| QUALITY-14 | Pipeline vector TV-4: width samples at 6 inch stations on a 96 inch axis report min, max, and average perpendicular to the confirmed axis. | shipped | — |
|
||||
| QUALITY-15 | Pipeline vector TV-5: one square end and one 45 degree cut, the length axis follows the prevailing length. | shipped | — |
|
||||
| QUALITY-16 | Pipeline vector TV-6: 3:4 crop, 90 percent fill at extremes, transparent PNG, shorter side at least 800 when the source allows. | shipped | — |
|
||||
| QUALITY-17 | Pipeline vector TV-7: an undersized source warns, is not upscaled, and is not publishable until retake. | shipped | — |
|
||||
| QUALITY-18 | Pipeline vector TV-8: bdft 0.96 at 12.50 per bdft gives a 12.00 recommendation, an override of 150.00 is stored, and no rule leaves the price empty for manual entry. | M3 | — |
|
||||
| QUALITY-19 | Pipeline vector TV-9: a 1 inch thickness rounds up into the synced Woo thickness band, not a hardcoded one. | M3 | — |
|
||||
| QUALITY-20 | Pipeline vector TV-10: half-up 2 decimal rounding, including 96.04 to 96, 0.641 to 0.64, 11.525 to 11.53, 12.345 to 12.35. | shipped | — |
|
||||
| QUALITY-21 | Dishonest proxies that do not count as pass: hardcoded or fixture taxonomy treated as synced, a Woo mock that never hits the real store for the exit walk, unit tests alone without a real SLAB-UAT-* draft, consumer-key auth, inference wired as dead config or required for create, claiming ready with empty fields, or parking work on the wrong branch. | M3 | — |
|
||||
| QUALITY-22 | The M3 exit evidence is a real SLAB-UAT-* Woo draft matching the reviewed ready set with inference off, plus test-woo and test-inference results. | M3 | — |
|
||||
| QUALITY-23 | Browser end-to-end capture through publish is verified on iOS Safari, Android Chrome, and desktop Chrome, Edge, and Firefox. | later | — |
|
||||
| QUALITY-24 | No raw status code, stack trace, or internal code reaches the owner in any tested path. | M3 | — |
|
||||
@@ -1,106 +0,0 @@
|
||||
# Structure contract
|
||||
|
||||
This file defines the shape of the `docs/` system and how requirements enter it.
|
||||
`tools/check_requirements.py` enforces it.
|
||||
|
||||
If the repo and this file disagree, fix one deliberately. Do not let them drift.
|
||||
|
||||
## Artifact registry
|
||||
|
||||
Every Markdown file under `docs/` is registered here. `docs/archive/**` and `docs/_templates/**` are exempt.
|
||||
|
||||
| Path | Role |
|
||||
|---|---|
|
||||
| `docs/README.md` | index |
|
||||
| `docs/PRODUCT.md` | intent |
|
||||
| `docs/STRUCTURE.md` | meta |
|
||||
| `docs/REQUIREMENTS.md` | requirements |
|
||||
| `docs/MILESTONES.md` | scope |
|
||||
| `docs/CAPTURE.md` | capability |
|
||||
| `docs/PHOTOS.md` | capability |
|
||||
| `docs/CREATE.md` | capability |
|
||||
| `docs/CONTENT-WOO.md` | contract |
|
||||
| `docs/UAT-PRACTICE.md` | practice |
|
||||
| `docs/capabilities/README.md` | index |
|
||||
| `docs/contracts/README.md` | index |
|
||||
|
||||
Roles:
|
||||
|
||||
- **index** — navigation only.
|
||||
- **intent** — why and what; not testable requirements.
|
||||
- **meta** — this contract.
|
||||
- **requirements** — the only normative text.
|
||||
- **scope** — milestone-to-ID mapping.
|
||||
- **capability** — behavior and acceptance for one capability; cites IDs, does not define them.
|
||||
- **contract** — cross-cutting interface detail; cites IDs, does not define them.
|
||||
- **practice** — human walkthrough.
|
||||
|
||||
## ID namespaces
|
||||
|
||||
Namespaces are **owner jobs, not technology layers**. A requirement belongs to the job it serves, and each namespace owns that job's screen, rules, server behavior, and data. There is no separate API, data, or UX layer to fight over.
|
||||
|
||||
All requirement text lives only in `docs/REQUIREMENTS.md`. This table assigns the home and prefix.
|
||||
|
||||
| Prefix | The owner is... | Covers |
|
||||
|---|---|---|
|
||||
| `CAPTURE` | capturing ecommerce-ready pics | photo intake, pick calibration/dimension photo, BG removal, crop, axis, length/width, calculations, inventory PNG, dimension overlay, lineup |
|
||||
| `METADATA` | building the listing | wood attributes and tags, title, short/deep description, via up to 2 inference calls |
|
||||
| `REVIEW` | reviewing and correcting | confidence display, field gating, tweaks, per-slab price suggestion and override, ready gate |
|
||||
| `PUBLISH` | submitting to the store | WooCommerce create, draft/live, duplicate SKU, cleanup |
|
||||
| `SETTINGS` | configuring before the session | Woo connection, inference config, species `$/bdft` rates, brand/geo |
|
||||
| `APP` | (foundation, not a job) | device draft, slab status, resume, server seams, secret handling |
|
||||
| `OPS` | (foundation, not a job) | deploy, hosts, release, UAT |
|
||||
| `QUALITY` | (foundation, not a job) | test obligations, vectors, anti-metrics |
|
||||
|
||||
Price has two homes by design: the species `$/bdft` rates are configured in `SETTINGS`; the per-slab suggestion and override live in `REVIEW`.
|
||||
|
||||
## Requirement format
|
||||
|
||||
Defined only in `docs/REQUIREMENTS.md`, as table rows:
|
||||
|
||||
```
|
||||
| ID | Requirement | Scope | Test |
|
||||
| CAPTURE-1 | Statement of one testable requirement | shipped | frontend/src/measure/measure.test.ts |
|
||||
```
|
||||
|
||||
- `Scope` is `shipped`, `M3`, or `later`.
|
||||
- `Test` is a repo-relative test path, a requirement ID, or `—`. A path given for a `shipped` requirement must exist; a given ID must resolve to a defined requirement.
|
||||
|
||||
## How to change a requirement
|
||||
|
||||
- **Modify:** edit the single row in `REQUIREMENTS.md`; update `Test`; if scope changed, update `MILESTONES.md`. Do not create a doc.
|
||||
- **Add:** pick the prefix and home from the namespace table; append a row; add the test. Do not create a doc.
|
||||
- **New domain:** that is a structure change. Add a namespace row and a home here first, deliberately. Do not create a drive-by artifact.
|
||||
|
||||
Nothing outside `REQUIREMENTS.md` may define a requirement. Capability and contract docs cite IDs only.
|
||||
|
||||
## Enforced by `tools/check_requirements.py`
|
||||
|
||||
1. Every `docs/` Markdown file (except `archive/**` and `_templates/**`) is registered above.
|
||||
2. Every registered file exists on disk.
|
||||
3. Requirement IDs match `^[A-Z]+-\d+$`, are unique, and use a registered prefix.
|
||||
4. Scope is one of `shipped | M3 | later`.
|
||||
5. `Test` references resolve: a path given for a `shipped` requirement exists; an ID given resolves to a defined requirement; `—` is allowed.
|
||||
6. Requirement rows appear only in `REQUIREMENTS.md`.
|
||||
7. Every ID listed in `MILESTONES.md` exists in `REQUIREMENTS.md`.
|
||||
|
||||
## Planned (Phase 2)
|
||||
|
||||
- Migrate capability docs to `docs/capabilities/` and contracts to `docs/contracts/`.
|
||||
- Populate `REQUIREMENTS.md` from the `pre-simplification` tag and the current docs.
|
||||
- Enforce branch-neutral language in trunk docs.
|
||||
- Wire this check into CI.
|
||||
|
||||
## Migration plan (Phase 2)
|
||||
|
||||
| Current | Canonical home |
|
||||
|---|---|
|
||||
| `docs/CAPTURE.md` | `docs/capabilities/CAPTURE.md` |
|
||||
| `docs/PHOTOS.md` | `docs/capabilities/PHOTOS.md` |
|
||||
| `docs/CREATE.md` | `docs/capabilities/CREATE.md` |
|
||||
| `docs/CONTENT-WOO.md` | `docs/contracts/CONTENT-WOO.md` |
|
||||
| tag `OPENAPI.md` | `docs/contracts/API.md` |
|
||||
| tag `DATA-MODEL.md` | `docs/contracts/DATA-MODEL.md` |
|
||||
| tag `UX.md` | `docs/contracts/UX.md` |
|
||||
| tag `PROMPTS.md` | `docs/contracts/PROMPTS.md` |
|
||||
| tag `TEST-SPEC.md` | `docs/contracts/TEST-SPEC.md` |
|
||||
@@ -1,230 +0,0 @@
|
||||
# UAT Practice Walk: one `SLAB-UAT-*` listing
|
||||
|
||||
Status: WALK · for Ty to run · SlabUploader
|
||||
|
||||
This is the walkable practice plan. It proves one listing end to end without touching a live product.
|
||||
Follow the sections in order. Each one names what you do, what you should see, and where the rule
|
||||
lives.
|
||||
|
||||
**Inference is OFF for this walk.** The optional ON path is only valid after Gate C is green and
|
||||
the inference endpoint is already configured. Inference stays off here.
|
||||
|
||||
---
|
||||
|
||||
> On branch `m3-ds`, Milestone 3 exit criteria and field rules live in `docs/CREATE.md`. This walk is the human practice path for a `SLAB-UAT-*` listing. Prefer `CREATE.md` if anything conflicts.
|
||||
|
||||
|
||||
## 1. Host and deploy preconditions
|
||||
|
||||
Before this walk, the app must already be on the inventoried host. This section only checks that.
|
||||
Host IPs and hostnames come from `deploy/INVENTORY.md`.
|
||||
|
||||
1. **Inventory is filled.** `deploy/INVENTORY.md` has `APP_HOST`, `APP_HOSTNAME`, ports, Caddy
|
||||
location, and the smoke results. It is the only source for what runs where on this host.
|
||||
See `docs/DEPLOYMENT.md` §1 for the worksheet rules.
|
||||
2. **Reachable over LAN/Tailscale.** Your phone reaches `https://${APP_HOSTNAME}` on the same
|
||||
network (LAN or Tailscale). No public exposure. Verify with a browser, not `curl`.
|
||||
3. **HTTPS only.** The URL is `https://`. The browser shows a valid certificate. If the phone
|
||||
warns, the Caddy TLS trust is not set up yet. That is a deploy problem, not a listing problem.
|
||||
4. **Health passes.** In a browser on the phone, open `https://${APP_HOSTNAME}/api/health`.
|
||||
You should see an ok response. This is the same check in `docs/DEPLOYMENT.md` §8 step 1.
|
||||
5. **Store URL is set.** `WOO_BASE_URL` is in the host `.env` and points at the store over
|
||||
`https://`. It is not something you type in the app. See `docs/DEPLOYMENT.md` §3 and §5.
|
||||
|
||||
If any of these fail, fix the deploy before continuing. This walk does not cover Gate B host work.
|
||||
It assumes the app is up and reachable.
|
||||
|
||||
---
|
||||
|
||||
## 2. WordPress Application Password setup
|
||||
|
||||
You do this once per store, in the store's WordPress admin. Do it before you open the app's
|
||||
Settings.
|
||||
|
||||
1. **Store is on HTTPS.** WordPress only offers Application Passwords over HTTPS. The store must
|
||||
already be on TLS. If it is not, stop and fix the store first.
|
||||
2. **Dedicated low-privilege user.** Create or use a WordPress user that can create and edit
|
||||
products and upload media. The store admin login is not reused. A shop manager role or a custom
|
||||
role with product create/edit plus media upload is enough.
|
||||
3. **Generate the password.** Sign in as that user. Go to **Users → Profile → Application
|
||||
Passwords**. Generate a password and label it "SlabUploader". Copy the password. WordPress
|
||||
shows it once.
|
||||
4. **Enter it in the app.** Open the app's Settings on the phone. Enter the WordPress username and
|
||||
the application password. The server stores them encrypted. The browser does not keep them.
|
||||
5. **Run `test-woo`.** In Settings, tap the test. It should report ok. This also resyncs the
|
||||
store's species, categories, tags, and attributes into the app. If it fails, the username or
|
||||
password is wrong, or the store is unreachable.
|
||||
|
||||
Rules: this is a WordPress Application Password, not WooCommerce consumer keys (`ck_`/`cs_`).
|
||||
The app never calls the store from the browser. FastAPI is the only caller. Rotate by revoking
|
||||
the old password in the WP profile and entering a new one in Settings, then re-running
|
||||
`test-woo`. Full lock: `AGENTS.md` §4 and §5, `docs/DEPLOYMENT.md` §5.
|
||||
|
||||
---
|
||||
|
||||
## 3. Practice build rules
|
||||
|
||||
These rules keep practice runs invisible to customers. They are locked. Changes are not made for
|
||||
the walk.
|
||||
|
||||
- **SKU prefix `SLAB-UAT-*`.** Every practice listing uses a SKU that starts with `SLAB-UAT-`.
|
||||
Pick a unique one each time, for example `SLAB-UAT-001`.
|
||||
- **Always a Woo draft.** A `SLAB-UAT-*` SKU creates a WooCommerce draft even if Settings say
|
||||
publish. Customers cannot open it. This is hard rule in `AGENTS.md` §5.
|
||||
- **`woo_create_status` defaults to draft.** The Settings field that controls create status
|
||||
defaults to `draft`. Practice uses the default. If it is `publish`, the
|
||||
`SLAB-UAT-*` rule still forces a draft.
|
||||
- **Customers never see practice listings.** A Woo draft is hidden from the storefront. If you
|
||||
can see the product on the live store, something is wrong.
|
||||
|
||||
If a practice SKU is not `SLAB-UAT-*`, it is not a practice run. Real SKUs are not published in
|
||||
this walk.
|
||||
|
||||
---
|
||||
|
||||
## 4. Prove one listing end to end
|
||||
|
||||
This is the main walk. Run it on a phone browser first, then repeat on a PC browser. Both are in
|
||||
the signed compatibility matrix (`docs/UX.md`, signed 2026-09-06).
|
||||
|
||||
Supported browsers: iOS Safari, Android Chrome on phones; desktop Chrome, Edge, Firefox on PC.
|
||||
Exact version pins are tracked under issue #4. If the browser is not supported, the app shows a
|
||||
hard stop. Switch to a supported browser.
|
||||
|
||||
### 4.1 Capture
|
||||
|
||||
1. Open the app on the phone. Start a new slab.
|
||||
2. Take 1 to 5 photos of the slab. The first should be top-down, lens parallel to the broad
|
||||
face. A tilted shot makes the numbers wrong. Retake if it is tilted.
|
||||
3. **Mask overlay and four knobs.** The app draws a mask over the photo. You see which pixels are
|
||||
slab and which are not. Tune the four knobs: **Sheet** (auto/green/black), **Sensitivity**,
|
||||
**Edge offset**, **Feather**. Each change re-runs the mask immediately. Look at the edge
|
||||
against the real wood. If it is still off, retake the photo.
|
||||
4. **Confirm the mask.** Tap confirm.
|
||||
5. **Length axis.** The app draws the bounding rectangle and the length axis. Confirm it follows
|
||||
the slab's long direction. Rotate if it is skewed. On a nearly square slab, you say which way
|
||||
is length.
|
||||
6. **Enter numbers by hand.** Length in 1/8" steps. Thickness as a 1/8" pick. SKU: type
|
||||
`SLAB-UAT-001` (or your chosen practice SKU).
|
||||
7. **Check the computed numbers.** The browser shows square feet, board feet, and width samples.
|
||||
Board feet = square feet × thickness in inches. No divide-by-12. If the numbers look wrong,
|
||||
go back and fix the mask or the length.
|
||||
8. **Continue.** This uploads the originals, the processed PNGs, and the numbers to the server.
|
||||
The slab status becomes `calibrated`.
|
||||
|
||||
### 4.2 Review
|
||||
|
||||
1. You are on the review screen. Fill every required field. Inference is OFF, so everything starts
|
||||
empty.
|
||||
2. **Species.** Pick exactly one from the synced store list. The list came from `test-woo`.
|
||||
Only species in the list may be typed.
|
||||
3. **Wood categories.** Pick at least one from the synced list.
|
||||
4. **Edge type, figure, grade.** Pick from the synced lists. At least one figure, at least one
|
||||
grade.
|
||||
5. **Thickness band.** Pick the Woo band that the measured thickness rounds up into.
|
||||
6. **Moisture.** Keep the default (kiln-dried) or change it.
|
||||
7. **fig-* tags.** Pick at least one.
|
||||
8. **feat-* tags.** Zero or more. Only pick existing `feat-*` tags.
|
||||
9. **Price.** A recommendation fills from the species $/bdft rule times board feet. You can
|
||||
override it. If there is no rule for the species, the price starts empty. Type it. Publish
|
||||
is still allowed with a manual price.
|
||||
10. **Title and description.** You can type them, or leave them for templates at publish.
|
||||
Templates inject the deterministic numbers. Generate text is OFF for this walk.
|
||||
|
||||
Every empty required field shows an inline nudge where it sits. The slab cannot reach `ready`
|
||||
until the full set is filled.
|
||||
|
||||
### 4.3 Publish
|
||||
|
||||
1. Tap **Publish**.
|
||||
2. The server checks the SKU against the store. If `SLAB-UAT-001` is new, it creates the
|
||||
product.
|
||||
3. **What you should see:** a success message on the screen. The local draft and its photos are
|
||||
gone from the app. The slab status in the app is `published`.
|
||||
4. **What that does NOT mean:** the product is not live in the store. It is a WooCommerce draft.
|
||||
The app's "published" means the store create succeeded and the local row was cleaned up.
|
||||
|
||||
### 4.4 Confirm in the store
|
||||
|
||||
1. Open the store's WooCommerce admin.
|
||||
2. Find the product by SKU `SLAB-UAT-001`.
|
||||
3. **It must be a draft.** Status is draft, not published.
|
||||
4. **Check the fields:** SKU, price, category (species), tags (fig-*, feat-*), attributes
|
||||
(Edge Type, Figure, Grade, Thickness, Moisture), and images (the processed transparent PNGs).
|
||||
5. **Open the live storefront.** The product must not appear. A draft is invisible to customers.
|
||||
|
||||
### 4.5 Repeat on a PC browser
|
||||
|
||||
Repeat 4.1 through 4.4 on a desktop browser (Chrome, Edge, or Firefox). Use a different
|
||||
practice SKU, for example `SLAB-UAT-002`. The flow must work the same way. This is the signed
|
||||
PC-browser compatibility check.
|
||||
|
||||
---
|
||||
|
||||
## 5. Pass and fail checks
|
||||
|
||||
You can see all of these without reading code.
|
||||
|
||||
| Check | Where | Pass looks like |
|
||||
|---|---|---|
|
||||
| Health endpoint | Phone browser, `https://${APP_HOSTNAME}/api/health` | ok response |
|
||||
| `test-woo` ok | App Settings | ok; species list is populated |
|
||||
| `woo_create_status` is draft | App Settings | shows `draft` (or `publish`, but `SLAB-UAT-*` forces draft anyway) |
|
||||
| Slab reaches `calibrated` | App, after capture | status is `calibrated` |
|
||||
| Slab reaches `ready` | App, after review | no empty required fields; inline nudges gone |
|
||||
| Publish succeeds | App, after Publish | success message; local draft is gone |
|
||||
| Woo product exists as draft | Store admin, products | SKU `SLAB-UAT-*`, status draft |
|
||||
| SKU prefix correct | Store admin | starts with `SLAB-UAT-` |
|
||||
| Store not live | Live storefront URL | product does not appear |
|
||||
| Board feet identity | App review screen, or a fixture | bdft = sqft × thickness in inches; no divide-by-12 |
|
||||
| Images are processed PNGs | Store admin, product images | transparent PNGs, not the original JPEGs |
|
||||
|
||||
### Duplicate SKU recovery
|
||||
|
||||
If you publish the same SKU twice, the second time the app stops before creating a second product.
|
||||
Under the SKU field you see: "This SKU already exists in the store (any status)." Two paths:
|
||||
edit the SKU to a new value, or open the existing listing. The draft stays in the app. Nothing is
|
||||
lost. This is the expected behavior, not a bug. See `docs/CONTENT-WOO.md` §2.5.
|
||||
|
||||
### What a fail looks like
|
||||
|
||||
- **No success message after Publish.** The app shows a plain message that the listing could not
|
||||
be created. No status number, no stack trace. The server kept a log. You can retry from the
|
||||
same screen without re-photographing.
|
||||
- **A value is no longer valid.** If a category, attribute, or price was removed from the store
|
||||
between sync and publish, that field shows "This value is no longer valid. Pick from the
|
||||
current list." Re-pick and retry.
|
||||
- **Store unreachable.** A plain message says the store could not be reached. Check the network
|
||||
and retry.
|
||||
|
||||
---
|
||||
|
||||
## 6. Cleanup
|
||||
|
||||
After the walk, decide what to do with the Woo draft UAT product.
|
||||
|
||||
- **Leave it or delete it.** Both are fine. It is a draft. Customers cannot see it. If you delete
|
||||
it, the store admin is the place to do it. The app does not delete store products.
|
||||
- **Never customer-visible.** If the product is visible on the live storefront, it is not a
|
||||
draft. That is a bug. Stop and report it.
|
||||
|
||||
**Real live publish is a separate step.** It is not part of this walk. A real product uses a
|
||||
non-UAT SKU (no `SLAB-UAT-` prefix) and is published only after you review it. That is a
|
||||
different decision. That step is not run here. The name of that step is **final POC publish**, and it
|
||||
is gated on your review of one real listing.
|
||||
|
||||
---
|
||||
|
||||
## Where each rule lives
|
||||
|
||||
| Rule | Source |
|
||||
|---|---|
|
||||
| Practice SKU forces draft | `AGENTS.md` §5 |
|
||||
| `woo_create_status` default draft | `AGENTS.md` §5, `docs/CONTENT-WOO.md` §2.4 |
|
||||
| App Password setup, not consumer keys | `AGENTS.md` §4, `docs/DEPLOYMENT.md` §5 |
|
||||
| Host inventory before deploy | `docs/DEPLOYMENT.md` §1, `deploy/INVENTORY.md` |
|
||||
| Capture → review → publish flow | `docs/UX.md` (SIGNED 2026-09-06) |
|
||||
| Board feet identity | `docs/TECH-SPEC-PIPELINE.md` |
|
||||
| Duplicate SKU recovery | `docs/CONTENT-WOO.md` §2.5, `docs/UX.md` Publish |
|
||||
| PC browser compatibility | `docs/UX.md` Browser compatibility |
|
||||
| Gate C = early Phase 1 | `docs/IMPL-PLAN.md` Gates map and Phase 1 |
|
||||
Vendored
-20
@@ -1,20 +0,0 @@
|
||||
<!--
|
||||
Template: decision record. One file per decision.
|
||||
Record why a choice was made when the reason is not obvious from the code or requirements.
|
||||
-->
|
||||
# ADR-<n>: <title>
|
||||
|
||||
- Date: <yyyy-mm-dd>
|
||||
- Status: `<proposed | accepted | superseded>`
|
||||
|
||||
## Context
|
||||
|
||||
<the situation and forces>
|
||||
|
||||
## Decision
|
||||
|
||||
<what was decided>
|
||||
|
||||
## Consequences
|
||||
|
||||
<what this makes easier, harder, or impossible>
|
||||
Vendored
-17
@@ -1,17 +0,0 @@
|
||||
<!--
|
||||
Template: capability doc. Home: docs/capabilities/<NAME>.md
|
||||
Behavior and acceptance only. Cite requirement IDs; never define them.
|
||||
-->
|
||||
# <Capability>
|
||||
|
||||
Status: `<shipped | in progress | planned>`
|
||||
|
||||
Cites: `<IDs from docs/REQUIREMENTS.md>`
|
||||
|
||||
## Behavior
|
||||
|
||||
<what the capability does, in plain terms>
|
||||
|
||||
## Acceptance
|
||||
|
||||
<what must be observed for this capability to be considered done, and where the evidence lives>
|
||||
Vendored
-11
@@ -1,11 +0,0 @@
|
||||
<!--
|
||||
Template: contract doc. Home: docs/contracts/<NAME>.md
|
||||
Cross-cutting interface detail. Cite requirement IDs; never define them.
|
||||
-->
|
||||
# <Contract>
|
||||
|
||||
Cites: `<IDs from docs/REQUIREMENTS.md>`
|
||||
|
||||
## <Interface detail>
|
||||
|
||||
<schemas, endpoints, prompts, screen rules — non-normative detail that supports the cited requirements>
|
||||
Vendored
-6
@@ -1,6 +0,0 @@
|
||||
<!--
|
||||
Template: one requirement row.
|
||||
Append to the correct namespace section of docs/REQUIREMENTS.md.
|
||||
Do not define this requirement anywhere else.
|
||||
-->
|
||||
| `<PREFIX>-<n>` | <one testable statement> | `<shipped|M3|later>` | `<repo-relative test path>` or `—` |
|
||||
@@ -15,11 +15,3 @@ 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.
|
||||
|
||||
## M3 note (updated 2026-09-16)
|
||||
|
||||
M3 exit on `m3-ds` is submission-ready for WooCommerce (`docs/CREATE.md`). Technical requirements for Woo sync, metadata, pricing, and inference were taken from historical `main` docs and written into `CREATE.md`. Do not use `main` milestone splits as M3 scope.
|
||||
|
||||
@@ -1,13 +0,0 @@
|
||||
# Capability docs
|
||||
|
||||
One file per capability. Behavior and acceptance only.
|
||||
|
||||
Rules (`docs/STRUCTURE.md`): a capability doc **cites** requirement IDs from `docs/REQUIREMENTS.md`; it never defines or restates them.
|
||||
|
||||
Expected files (Phase 2 migration):
|
||||
|
||||
- `CAPTURE.md` — Milestone 1 Capture
|
||||
- `PHOTOS.md` — Milestone 2 Photos
|
||||
- `CREATE.md` — Milestone 3 Create
|
||||
|
||||
Template: `docs/_templates/capability.md`.
|
||||
@@ -1,16 +0,0 @@
|
||||
# Contract docs
|
||||
|
||||
Cross-cutting interface detail shared by capabilities.
|
||||
|
||||
Rules (`docs/STRUCTURE.md`): a contract doc **cites** requirement IDs from `docs/REQUIREMENTS.md`; it never defines or restates them.
|
||||
|
||||
Expected files (Phase 2 migration):
|
||||
|
||||
- `API.md` — FastAPI HTTP contract (from tag `OPENAPI.md`)
|
||||
- `DATA-MODEL.md` — SQLite schema and status machine (from tag `DATA-MODEL.md`)
|
||||
- `UX.md` — screens, field recovery, outcomes (from tag `UX.md`)
|
||||
- `PROMPTS.md` — Call 1 / Call 2 prompt text (from tag `PROMPTS.md`)
|
||||
- `TEST-SPEC.md` — test pyramid, vectors, dishonest proxies (from tag `TEST-SPEC.md`)
|
||||
- `CONTENT-WOO.md` — listing copy and Woo payload detail (migrated from `docs/CONTENT-WOO.md`)
|
||||
|
||||
Template: `docs/_templates/contract.md`.
|
||||
@@ -1,9 +0,0 @@
|
||||
# tools
|
||||
|
||||
Structure and verification gates. These are the only sanctioned way to claim the docs are clean or a slice is "done".
|
||||
|
||||
| Script | Purpose | Run |
|
||||
|---|---|---|
|
||||
| `check_requirements.py` | Enforce `docs/STRUCTURE.md`: registered docs, requirement IDs, traceability. | `python tools/check_requirements.py` |
|
||||
|
||||
Run from the repo root. Exit 0 = pass, exit 1 = fail.
|
||||
@@ -1,159 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Enforce docs/STRUCTURE.md.
|
||||
|
||||
Run from the repo root:
|
||||
|
||||
python tools/check_requirements.py
|
||||
|
||||
Exit 0 = the docs structure is consistent. Exit 1 = it is not.
|
||||
Checks are listed in docs/STRUCTURE.md.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
ROOT = Path(__file__).resolve().parent.parent
|
||||
DOCS = ROOT / "docs"
|
||||
STRUCTURE = DOCS / "STRUCTURE.md"
|
||||
REQUIREMENTS = DOCS / "REQUIREMENTS.md"
|
||||
MILESTONES = DOCS / "MILESTONES.md"
|
||||
|
||||
EXEMPT_PREFIXES = (("docs", "archive"), ("docs", "_templates"))
|
||||
|
||||
ROLES = "index|intent|meta|requirements|scope|capability|contract|practice"
|
||||
REGISTRY_ROW = re.compile(rf"^\|\s*`(docs/[^`]+\.md)`\s*\|\s*({ROLES})\s*\|")
|
||||
NAMESPACE_ROW = re.compile(r"^\|\s*`([A-Z]+)`\s*\|")
|
||||
REQUIREMENT_ROW = re.compile(
|
||||
r"^\|\s*([A-Z]+)-(\d+)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|\s*$"
|
||||
)
|
||||
MILESTONE_IDS = re.compile(r"^-\s*IDs:\s*(.*)$")
|
||||
ID_TOKEN = re.compile(r"^[A-Z]+-\d+$")
|
||||
|
||||
SCOPES = {"shipped", "M3", "later"}
|
||||
PLACEHOLDER = {"", "—", "-", "*(none yet)*"}
|
||||
|
||||
|
||||
def main() -> int:
|
||||
errors: list[str] = []
|
||||
|
||||
if not STRUCTURE.exists():
|
||||
print("FAIL check_requirements: docs/STRUCTURE.md is missing")
|
||||
return 1
|
||||
|
||||
structure = STRUCTURE.read_text(encoding="utf-8")
|
||||
|
||||
registered: dict[str, str] = {}
|
||||
for line in structure.splitlines():
|
||||
match = REGISTRY_ROW.match(line)
|
||||
if match:
|
||||
registered[match.group(1)] = match.group(2)
|
||||
|
||||
namespaces = {
|
||||
match.group(1)
|
||||
for line in structure.splitlines()
|
||||
if (match := NAMESPACE_ROW.match(line))
|
||||
}
|
||||
if not namespaces:
|
||||
errors.append("STRUCTURE.md declares no ID namespaces")
|
||||
|
||||
# 1. every non-exempt doc is registered
|
||||
for path in sorted(DOCS.rglob("*.md")):
|
||||
rel = path.relative_to(ROOT).as_posix()
|
||||
if path.relative_to(ROOT).parts[:2] in EXEMPT_PREFIXES:
|
||||
continue
|
||||
if rel not in registered:
|
||||
errors.append(f"unregistered doc: {rel}")
|
||||
|
||||
# 2. every registered doc exists
|
||||
for rel in registered:
|
||||
if not (ROOT / rel).exists():
|
||||
errors.append(f"registered doc missing on disk: {rel}")
|
||||
|
||||
# 3-5. requirement rows
|
||||
ids: dict[str, str] = {}
|
||||
test_refs: list[tuple[str, str, str, str]] = []
|
||||
if not REQUIREMENTS.exists():
|
||||
errors.append("docs/REQUIREMENTS.md is missing")
|
||||
else:
|
||||
for number, line in enumerate(
|
||||
REQUIREMENTS.read_text(encoding="utf-8").splitlines(), 1
|
||||
):
|
||||
match = REQUIREMENT_ROW.match(line)
|
||||
if not match:
|
||||
continue
|
||||
prefix, digit, _statement, scope, test = match.groups()
|
||||
rid = f"{prefix}-{digit}"
|
||||
loc = f"docs/REQUIREMENTS.md:{number}"
|
||||
if prefix not in namespaces:
|
||||
errors.append(f"{loc} unknown namespace '{prefix}'")
|
||||
if rid in ids:
|
||||
errors.append(f"{loc} duplicate id {rid} (first seen at {ids[rid]})")
|
||||
else:
|
||||
ids[rid] = loc
|
||||
if scope not in SCOPES:
|
||||
errors.append(f"{loc} {rid} invalid scope '{scope}'")
|
||||
test_ref = test.strip()
|
||||
if test_ref not in PLACEHOLDER:
|
||||
test_refs.append((loc, rid, test_ref, scope))
|
||||
|
||||
# 5. resolve test references: an existing path, a requirement ID, or —
|
||||
for loc, rid, ref, scope in test_refs:
|
||||
if ID_TOKEN.match(ref):
|
||||
if ref not in ids:
|
||||
errors.append(f"{loc} {rid} test ref {ref} is not a defined requirement")
|
||||
elif "/" in ref or "\\" in ref or "." in ref:
|
||||
if scope == "shipped" and not (ROOT / ref).exists():
|
||||
errors.append(f"{loc} {rid} shipped test path not found: {ref}")
|
||||
else:
|
||||
errors.append(f"{loc} {rid} invalid Test ref '{ref}' (use a path, an ID, or —)")
|
||||
|
||||
# 6. requirement rows appear only in REQUIREMENTS.md
|
||||
for path in sorted(DOCS.rglob("*.md")):
|
||||
if path.relative_to(ROOT).parts[:2] in EXEMPT_PREFIXES or path in {
|
||||
REQUIREMENTS,
|
||||
STRUCTURE,
|
||||
}:
|
||||
continue
|
||||
rel = path.relative_to(ROOT).as_posix()
|
||||
for number, line in enumerate(
|
||||
path.read_text(encoding="utf-8").splitlines(), 1
|
||||
):
|
||||
if REQUIREMENT_ROW.match(line):
|
||||
errors.append(f"{rel}:{number} requirement row outside REQUIREMENTS.md")
|
||||
|
||||
# 7. milestone IDs resolve
|
||||
if not MILESTONES.exists():
|
||||
errors.append("docs/MILESTONES.md is missing")
|
||||
else:
|
||||
for number, line in enumerate(
|
||||
MILESTONES.read_text(encoding="utf-8").splitlines(), 1
|
||||
):
|
||||
match = MILESTONE_IDS.match(line)
|
||||
if not match:
|
||||
continue
|
||||
for token in match.group(1).split(","):
|
||||
token = token.strip().strip("`").strip()
|
||||
if token in PLACEHOLDER:
|
||||
continue
|
||||
if not ID_TOKEN.match(token):
|
||||
errors.append(f"MILESTONES.md:{number} not an ID: '{token}'")
|
||||
elif token not in ids:
|
||||
errors.append(f"MILESTONES.md:{number} unknown ID {token}")
|
||||
|
||||
if errors:
|
||||
print(f"FAIL check_requirements: {len(errors)} problem(s)")
|
||||
for error in errors:
|
||||
print(f" - {error}")
|
||||
return 1
|
||||
|
||||
print(
|
||||
f"PASS check_requirements: {len(registered)} docs, "
|
||||
f"{len(namespaces)} namespaces, {len(ids)} requirements"
|
||||
)
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
Reference in New Issue
Block a user