Ty_Tech/SlabUploader
6
0
Fork 0
Code Issues 15 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(m3): regroup METADATA and remove the false fallback framing

Browse Source 
METADATA was ordered as it was written, not by topic, and used Call 1 /
Call 2 without defining them.

- Add a short METADATA preamble stating the inference flow: Call 1 vision
  proposes taxonomy, the name and short description are deterministic, Call 2
  writes the long description.
- Regroup the rows: taxonomy, then Call 1, then deterministic copy, then
  Call 2, then cross-cutting.
- METADATA-70 said the deterministic name and short description were an
  inference-off fallback; they are unconditional. It now covers only the
  inference-off description.
- METADATA-81 folded into METADATA-80 (same rule, two strings).
- METADATA-45 now names the below-threshold outcome.
- METADATA-90 now states what the fact block drives.

153 requirements; check_requirements and check_coverage both pass.
This commit is contained in:
Ty Balascio
2026-09-19 12:10:11 -07:00
parent 120e0be871
commit d6aa79b593
5 changed files with 27 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/MILESTONES.md
+1 -1
View File
@@ -27,7 +27,7 @@ IDs:
METADATA-5, METADATA-10, METADATA-15, METADATA-20, METADATA-25, METADATA-30, METADATA-35, METADATA-5, METADATA-10, METADATA-15, METADATA-20, METADATA-25, METADATA-30, METADATA-35,
METADATA-40, METADATA-45, METADATA-50, METADATA-55, METADATA-60, METADATA-65, METADATA-66, METADATA-40, METADATA-45, METADATA-50, METADATA-55, METADATA-60, METADATA-65, METADATA-66,
METADATA-70, METADATA-75, METADATA-80, METADATA-81, METADATA-85, METADATA-90, METADATA-95, METADATA-100, METADATA-70, METADATA-75, METADATA-80, METADATA-85, METADATA-90, METADATA-95, METADATA-100,
METADATA-105, METADATA-110, METADATA-115, METADATA-105, METADATA-110, METADATA-115,
REVIEW-5, REVIEW-10, REVIEW-15, REVIEW-20, REVIEW-25, REVIEW-30, REVIEW-35, REVIEW-40, REVIEW-5, REVIEW-10, REVIEW-15, REVIEW-20, REVIEW-25, REVIEW-30, REVIEW-35, REVIEW-40,
REVIEW-45, REVIEW-50, REVIEW-45, REVIEW-50,
docs/REQUIREMENTS.md
+11 -10
View File
@@ -52,6 +52,8 @@ Sources reconciled 2026-09-18 from the current branch docs plus the `pre-simplif
## METADATA — listing attributes and copy ## METADATA — listing attributes and copy
The listing is built in two inference calls, both optional. Call 1 (vision) reads the photos and proposes taxonomy; Call 2 (text) writes the long description. The product name and short description are assembled deterministically from the listing facts and never come from a model. With inference off, the owner fills the taxonomy by hand and the server produces the description.
| ID | Requirement | Scope | Test | | ID | Requirement | Scope | Test |
|---|---|---|---| |---|---|---|---|
| METADATA-5 | The listing taxonomy is exactly the synced WooCommerce set; the app never hardcodes, invents, or falls back to its own lists. | M3 | — | | METADATA-5 | The listing taxonomy is exactly the synced WooCommerce set; the app never hardcodes, invents, or falls back to its own lists. | M3 | — |
@@ -60,22 +62,21 @@ Sources reconciled 2026-09-18 from the current branch docs plus the `pre-simplif
| METADATA-20 | Missing attributes or terms are skipped, never created. | M3 | — | | METADATA-20 | Missing attributes or terms are skipped, never created. | M3 | — |
| METADATA-25 | Species, character, length, and free-text thickness are not product attributes. | M3 | — | | METADATA-25 | Species, character, length, and free-text thickness are not product attributes. | M3 | — |
| METADATA-30 | Product tags come from the synced Woo set and are all optional; no hardcoded prefixes, and the bare fig tag is kept. | M3 | — | | METADATA-30 | Product tags come from the synced Woo set and are all optional; no hardcoded prefixes, and the bare fig tag is kept. | M3 | — |
| METADATA-100 | Call 1 free-text observations (character, inclusions, voids, checks) are mapped to existing synced feat-* tags only; WooCommerce is the authority for feat-* definitions. | M3 | — |
| METADATA-35 | 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-35 | 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-40 | Call 1 returns species, wood categories, edge, figure, grade, and feature-tag suggestions constrained to the synced lists, each with confidence. | M3 | — | | METADATA-40 | Call 1 returns species, wood categories, edge, figure, grade, and feature-tag suggestions constrained to the synced lists, each with confidence. | M3 | — |
| METADATA-45 | 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-45 | Call 1 confidence at or above the threshold (default 0.7) pre-fills review fields; below it the field stays empty for the owner to fill by hand or re-run Call 1; suggestions are always editable. | M3 | — |
| METADATA-50 | Typed values always win over inferred values. | M3 | — | | METADATA-50 | Typed values always win over inferred values. | M3 | — |
| METADATA-55 | Call 2 runs on demand and produces the product description. | M3 | — | | METADATA-85 | The primary wood category selects the Call 2 prompt and the title and short-description patterns. | M3 | — |
| METADATA-80 | The server assembles the name and short description deterministically from the primary wood category's patterns and the dimension fact block. The patterns use only synced taxonomy terms and capture facts. | M3 | — |
| METADATA-90 | The dimension fact block supplies the exact strings the patterns interpolate and the only numbers Call 2 may print; there is no L by W by T rectangle assumption. | M3 | — |
| METADATA-55 | Call 2 runs on demand and produces the long description. | M3 | — |
| METADATA-60 | Call 2 receives the processed photos, the metadata confirmed or changed in review, the primary and secondary wood categories, the parent-category path, the dimension fact block, and brand/geo context. | M3 | — | | METADATA-60 | Call 2 receives the processed photos, the metadata confirmed or changed in review, the primary and secondary wood categories, the parent-category path, the dimension fact block, and brand/geo context. | M3 | — |
| METADATA-65 | The model never invents or alters a dimension; every number it prints comes from the fact block. | M3 | — | | METADATA-65 | The model never invents or alters a dimension; every number it prints comes from the fact block. | M3 | — |
| METADATA-66 | Every content generation, from a deterministic template or from the model, is logged with its inputs, the model request and response when a model was used, and the final stored content. | M3 | — |
| METADATA-70 | With inference off, the server assembles the name and short description and produces the description. | M3 | — |
| METADATA-75 | Inference never blocks create and never auto-publishes. | M3 | — |
| METADATA-80 | The server assembles the product name deterministically from the primary wood category's title pattern and the dimension fact block. Title patterns use only synced taxonomy terms and capture facts. | M3 | — |
| METADATA-81 | The server assembles the short description deterministically as a spec line from the primary wood category's short-description pattern. Short-description patterns use only synced taxonomy terms and capture facts. | M3 | — |
| METADATA-85 | The primary wood category selects the Call 2 prompt and the title and short-description patterns. | M3 | — |
| METADATA-90 | 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-95 | The dimension-overlay image is never sent to the model. | M3 | — | | METADATA-95 | The dimension-overlay image is never sent to the model. | M3 | — |
| METADATA-100 | Call 1 free-text observations (character, inclusions, voids, checks) are mapped to existing synced feat-* tags only; WooCommerce is the authority for feat-* definitions. | M3 | — | | METADATA-70 | With inference off, the server produces the long description. | M3 | — |
| METADATA-66 | Every content generation, from a deterministic pattern or from the model, is logged with its inputs, the model request and response when a model was used, and the final stored content. | M3 | — |
| METADATA-75 | Inference never blocks create and never auto-publishes. | M3 | — |
| METADATA-105 | Inference prompts are stored in the database with all revisions; each call uses the active revision and the revision history is retained. | M3 | — | | METADATA-105 | Inference prompts are stored in the database with all revisions; each call uses the active revision and the revision history is retained. | M3 | — |
| METADATA-110 | The Generate text control appears only when content generation is enabled and the inference endpoint is reachable, and is disabled when the text service is down. | M3 | — | | METADATA-110 | The Generate text control appears only when content generation is enabled and the inference endpoint is reachable, and is disabled when the text service is down. | M3 | — |
| METADATA-115 | A runtime inference failure is classified recoverable or unrecoverable for the owner: recoverable offers Retry, unrecoverable gives a plain message explaining it. | M3 | — | | METADATA-115 | A runtime inference failure is classified recoverable or unrecoverable for the owner: recoverable offers Retry, unrecoverable gives a plain message explaining it. | M3 | — |
docs/capabilities/CREATE.md
+4 -4
View File
@@ -15,7 +15,7 @@ lives in `docs/contracts/` (`API.md`, `WOO-API.md`, `DATA-MODEL.md`, `PROMPTS.md
| METADATA-5, METADATA-10, METADATA-15, METADATA-20, METADATA-25, METADATA-30 | synced taxonomy, cardinality, no term creation | | METADATA-5, METADATA-10, METADATA-15, METADATA-20, METADATA-25, METADATA-30 | synced taxonomy, cardinality, no term creation |
| METADATA-35, METADATA-40, METADATA-45, METADATA-50 | Call 1 inputs, results, confidence gate, precedence | | METADATA-35, METADATA-40, METADATA-45, METADATA-50 | Call 1 inputs, results, confidence gate, precedence |
| METADATA-55, METADATA-60, METADATA-65, METADATA-66 | Call 2, context, dimension safety, logging | | METADATA-55, METADATA-60, METADATA-65, METADATA-66 | Call 2, context, dimension safety, logging |
| METADATA-70, METADATA-75, METADATA-80, METADATA-81, METADATA-85, METADATA-90, METADATA-95 | deterministic copy, non-blocking, pattern selection, fact block | | METADATA-70, METADATA-75, METADATA-80, METADATA-85, METADATA-90, METADATA-95 | deterministic copy, inference-off path, pattern selection, fact block |
| METADATA-100, METADATA-105, METADATA-110, METADATA-115 | feat mapping, prompt storage, Generate text control, failure triage | | METADATA-100, METADATA-105, METADATA-110, METADATA-115 | feat mapping, prompt storage, Generate text control, failure triage |
| PUBLISH-5, PUBLISH-10, PUBLISH-15, PUBLISH-20 | create sequence, draft rule, duplicate, stale | | PUBLISH-5, PUBLISH-10, PUBLISH-15, PUBLISH-20 | create sequence, draft rule, duplicate, stale |
| PUBLISH-25, PUBLISH-30, PUBLISH-31, PUBLISH-35, PUBLISH-36, PUBLISH-37, PUBLISH-38 | success, failure, partial failure, triage | | PUBLISH-25, PUBLISH-30, PUBLISH-31, PUBLISH-35, PUBLISH-36, PUBLISH-37, PUBLISH-38 | success, failure, partial failure, triage |
@@ -58,9 +58,9 @@ dimension (`METADATA-60`, `METADATA-65`, `METADATA-90`). The Generate text contr
when content generation is enabled and the endpoint is reachable (`METADATA-110`). All generation when content generation is enabled and the endpoint is reachable (`METADATA-110`). All generation
is logged (`METADATA-66`). is logged (`METADATA-66`).
With inference off, the server assembles the name and short description and produces the With inference off, the server produces the long description (`METADATA-70`). The name and short
description (`METADATA-70`). The name and short description are assembled from the primary wood description are assembled from the primary wood category's patterns (`METADATA-80`,
category's patterns (`METADATA-80`, `METADATA-81`, `METADATA-85`). Prompts live in the database with `METADATA-85`). Prompts live in the database with
all revisions (`METADATA-105`). Inference never blocks create and never auto-publishes all revisions (`METADATA-105`). Inference never blocks create and never auto-publishes
(`METADATA-75`); a runtime failure offers Retry when recoverable or explains when it is not (`METADATA-75`); a runtime failure offers Retry when recoverable or explains when it is not
(`METADATA-115`). (`METADATA-115`).
docs/contracts/CONTENT-WOO.md
+4 -4
View File
@@ -11,7 +11,7 @@ Owns how listing copy is produced and the intent of the create payload. The wire
|---|---| |---|---|
| REVIEW-10, REVIEW-15, REVIEW-40, REVIEW-50 | required prose, primary category, editability, limits | | REVIEW-10, REVIEW-15, REVIEW-40, REVIEW-50 | required prose, primary category, editability, limits |
| METADATA-55, METADATA-60, METADATA-65, METADATA-66 | Call 2, inputs, dimension safety, logging | | METADATA-55, METADATA-60, METADATA-65, METADATA-66 | Call 2, inputs, dimension safety, logging |
| METADATA-70, METADATA-75, METADATA-80, METADATA-81, METADATA-85, METADATA-90, METADATA-95, METADATA-110 | deterministic copy, fallback, pattern selection, fact block, overlay exclusion, control | | METADATA-70, METADATA-75, METADATA-80, METADATA-85, METADATA-90, METADATA-95, METADATA-110 | deterministic copy, inference-off path, pattern selection, fact block, overlay exclusion, control |
| PUBLISH-5, PUBLISH-10, PUBLISH-15, PUBLISH-20, PUBLISH-25, PUBLISH-30, PUBLISH-31, PUBLISH-40, PUBLISH-45, PUBLISH-50, PUBLISH-55, PUBLISH-60 | payload and create outcomes | | PUBLISH-5, PUBLISH-10, PUBLISH-15, PUBLISH-20, PUBLISH-25, PUBLISH-30, PUBLISH-31, PUBLISH-40, PUBLISH-45, PUBLISH-50, PUBLISH-55, PUBLISH-60 | payload and create outcomes |
| SETTINGS-30, SETTINGS-65 | brand voice and geo context; create status | | SETTINGS-30, SETTINGS-65 | brand voice and geo context; create status |
| METADATA-10, METADATA-15, METADATA-30 | categories, attributes, tags on the payload | | METADATA-10, METADATA-15, METADATA-30 | categories, attributes, tags on the payload |
@@ -23,7 +23,7 @@ Three fields, three sources (`REVIEW-10`):
1. **name** — assembled deterministically by the server from the primary wood category's title 1. **name** — assembled deterministically by the server from the primary wood category's title
pattern and the dimension fact block (`METADATA-80`). The model does not write it. pattern and the dimension fact block (`METADATA-80`). The model does not write it.
2. **short_description** — assembled deterministically as a spec line from the primary wood 2. **short_description** — assembled deterministically as a spec line from the primary wood
category's short-description pattern (`METADATA-81`). The model does not write it. category's short-description pattern (`METADATA-80`). The model does not write it.
3. **description** — written by Call 2 when it runs (`METADATA-55`), from the inputs in 3. **description** — written by Call 2 when it runs (`METADATA-55`), from the inputs in
`METADATA-60`; with inference off the server produces it (`METADATA-70`). `METADATA-60`; with inference off the server produces it (`METADATA-70`).
@@ -40,8 +40,8 @@ generation is logged (`METADATA-66`).
## 2. Deterministic title and short description ## 2. Deterministic title and short description
Both patterns are assembled by the server and use only synced taxonomy terms and capture facts Both patterns are assembled by the server and use only synced taxonomy terms and capture facts
(`METADATA-80`, `METADATA-81`). Placeholders use `{field}`; every number comes from the (`METADATA-80`). Placeholders use `{field}`; every number comes from the deterministic pipeline,
deterministic pipeline, never the model (`METADATA-90`). never the model (`METADATA-90`).
The shape follows the convention a working mill store uses: descriptor-led, dimension-light titles, The shape follows the convention a working mill store uses: descriptor-led, dimension-light titles,
with the measurements carried separately. See "Provenance" below. with the measurements carried separately. See "Provenance" below.
docs/contracts/PROMPTS.md
+7 -7
View File
@@ -9,8 +9,8 @@ Owns prompt storage, prompt inputs, and the two inference calls.
|---|---| |---|---|
| METADATA-5, METADATA-10, METADATA-15, METADATA-30 | taxonomy choices and cardinality | | METADATA-5, METADATA-10, METADATA-15, METADATA-30 | taxonomy choices and cardinality |
| METADATA-35, METADATA-40, METADATA-45, METADATA-50 | Call 1 inputs, constraints, pre-fill, precedence | | METADATA-35, METADATA-40, METADATA-45, METADATA-50 | Call 1 inputs, constraints, pre-fill, precedence |
| METADATA-55, METADATA-60, METADATA-65, METADATA-70 | Call 2 output, inputs, dimension safety, fallback | | METADATA-55, METADATA-60, METADATA-65, METADATA-70 | Call 2 output, inputs, dimension safety, inference-off path |
| METADATA-75, METADATA-80, METADATA-81, METADATA-85, METADATA-90, METADATA-95 | non-blocking, deterministic copy, pattern selection, fact block, overlay exclusion | | METADATA-75, METADATA-80, METADATA-85, METADATA-90, METADATA-95 | non-blocking, deterministic copy, pattern selection, fact block, overlay exclusion |
| METADATA-100, METADATA-105, METADATA-110, METADATA-115 | feat mapping, prompt storage, button, failure | | METADATA-100, METADATA-105, METADATA-110, METADATA-115 | feat mapping, prompt storage, button, failure |
| METADATA-66 | generation logging | | METADATA-66 | generation logging |
| SETTINGS-30 | brand voice and geo context | | SETTINGS-30 | brand voice and geo context |
@@ -75,15 +75,15 @@ No provider thread id is used, and Call 1's raw prompt and result are not sent (
- The dimension-overlay image is never sent (`METADATA-95`). - The dimension-overlay image is never sent (`METADATA-95`).
**Output.** The long `description` prose. The server assembles `name` and `short_description` **Output.** The long `description` prose. The server assembles `name` and `short_description`
(`METADATA-55`, `METADATA-80`, `METADATA-81`). The primary wood category selects the specialized (`METADATA-55`, `METADATA-80`). The primary wood category selects the specialized prompt
prompt (`METADATA-85`). The owner can edit the result (`REVIEW-40`). (`METADATA-85`). The owner can edit the result (`REVIEW-40`).
## 4. Fallback and templates ## 4. Fallback and templates
- With inference off, the server assembles the name and short description and produces the - With inference off, the server produces the long description so create never lacks prose
description so create never lacks prose (`METADATA-70`). (`METADATA-70`).
- The deterministic title and short-description patterns live in `docs/contracts/CONTENT-WOO.md` - The deterministic title and short-description patterns live in `docs/contracts/CONTENT-WOO.md`
(`METADATA-80`, `METADATA-81`). (`METADATA-80`).
- The primary wood category selects the specialized Call 2 prompt (`METADATA-85`). - The primary wood category selects the specialized Call 2 prompt (`METADATA-85`).
- All generated text stays within the field limits in `docs/contracts/WOO-API.md` §9 - All generated text stays within the field limits in `docs/contracts/WOO-API.md` §9
(`REVIEW-50`). (`REVIEW-50`).