docs(phase2): reconcile requirements and migrate capabilities/contracts
Surface-matrix sweep of every source doc; added nine missed behaviors (METADATA-115, REVIEW-50, APP-55/60/65, SETTINGS-45 mode, Generate-text availability, defaults-off). 153 requirements, 0 coverage gaps. Migrated capabilities to docs/capabilities/ and contracts to docs/contracts/; added WOO-API, API, DATA-MODEL, PROMPTS, UX, TEST-SPEC. Populated MILESTONES; branch-neutral trunk docs; renamed umbrella term to Woo Slab Taxonomy. Archived reconciliation working records under .audit/archive/.
This commit is contained in:
@@ -0,0 +1,91 @@
|
||||
# Prompts contract
|
||||
|
||||
Status: SPEC · 2026-09-18.
|
||||
Owns prompt storage, prompt inputs, and the two inference calls.
|
||||
|
||||
## Requirements impact
|
||||
|
||||
| Requirement | Impact on this design |
|
||||
|---|---|
|
||||
| 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-55, METADATA-60, METADATA-65, METADATA-70 | Call 2 trigger, context, constraints, fallback |
|
||||
| METADATA-75, METADATA-80, METADATA-85, METADATA-90, METADATA-95 | non-blocking, fallback title, prompt selection, fact block, overlay exclusion |
|
||||
| METADATA-100, METADATA-105, METADATA-110, METADATA-115 | feat mapping, prompt storage, button, failure |
|
||||
| METADATA-66 | generation logging |
|
||||
| SETTINGS-30 | brand voice and geo context |
|
||||
| REVIEW-40, REVIEW-50 | editability and field limits |
|
||||
|
||||
## 1. Storage and revisions
|
||||
|
||||
- Prompts live in the database, not in text files, with all revisions retained. Tables are in
|
||||
`docs/contracts/DATA-MODEL.md` §7.
|
||||
- Each call reads the active revision fresh.
|
||||
- Editing a prompt creates a new revision; history is never overwritten.
|
||||
- Every generation is logged with its inputs, the request/response when a model was used, and the
|
||||
final stored content.
|
||||
|
||||
## 2. Call 1 — vision classification
|
||||
|
||||
**When.** Runs automatically after a calibrated draft uploads only when `inference_enabled` is
|
||||
true; also on demand or retry. With inference off it is skipped and the fields are filled by hand.
|
||||
|
||||
**Inputs.**
|
||||
- The clean processed photos at 1024 px long edge or less.
|
||||
- The synced taxonomy: species leaves, Edge Type, Figure, Grade, Thickness, Moisture terms, each
|
||||
with its Woo id. These are the only legal choices.
|
||||
- User metadata: SKU, length, thickness.
|
||||
|
||||
**Constraints.**
|
||||
- The model may only choose values from the supplied synced lists; it never invents categories or
|
||||
terms.
|
||||
- Free-text observations (character, inclusions, voids, checks) are mapped to existing synced
|
||||
`feat-*` tags only; Woo is authoritative for those tags.
|
||||
|
||||
**Result fields.** `species_id` + `species_confidence`; `wood_category_ids`;
|
||||
`edge_type_term_id`; `figure_term_ids` + `figure_confidence`; `grade_term_id` +
|
||||
`grade_confidence`; `character`, `inclusions`, `voids`, `checks`. Grade, edge, thickness, and
|
||||
moisture are singular.
|
||||
|
||||
**Pre-fill.** At or above the threshold (default 0.7) the field is pre-filled and remains
|
||||
editable; below it the field stays empty and is not shown as a low-confidence guess. Typed values
|
||||
always win. Call 1 is assist-only and never gates publish. A runtime failure is classified
|
||||
recoverable or unrecoverable for the owner.
|
||||
|
||||
## 3. Call 2 — content prose
|
||||
|
||||
**When.** User-triggered only, via the Generate text control; never automatic. The control appears
|
||||
only when content generation is enabled and the endpoint is reachable.
|
||||
|
||||
**Inputs.**
|
||||
- A fresh, full Call 1 context: prompt, Call 1 photos, and the Call 1 result. No provider thread
|
||||
id is used.
|
||||
- The confirmed or changed metadata from review.
|
||||
- The literal dimension fact block, exact strings for species, figure term, length, thickness,
|
||||
average width, width min–max, and board feet; no length-by-width-by-thickness rectangle
|
||||
assumption.
|
||||
- Brand voice and geo context.
|
||||
|
||||
**Constraints.**
|
||||
- The model writes prose only and never invents or alters a dimension; every number comes from the
|
||||
fact block.
|
||||
- The dimension-overlay image is never sent.
|
||||
|
||||
**Output.** `title`, `short_description`, `description`. The owner can edit the result.
|
||||
|
||||
## 4. Fallback and templates
|
||||
|
||||
- With inference off, deterministic templates produce name, short_description, and description so
|
||||
create never lacks prose.
|
||||
- The template is the fallback only; when Call 2 runs, the model writes and the template guides
|
||||
style.
|
||||
- The fallback title uses the primary figure term name as the character, with the hyphen
|
||||
separator.
|
||||
- The primary wood category selects a specialized Call 2 prompt.
|
||||
- All generated text stays within the field limits in `docs/contracts/WOO-API.md` §9.
|
||||
|
||||
## 5. Prompt management
|
||||
|
||||
- The active Call 1 and Call 2 revisions are editable; saving creates a new revision.
|
||||
- A revision identifies its content, author, and timestamp; `inference_log` records the revision
|
||||
used for each call.
|
||||
Reference in New Issue
Block a user