docs(m3): add the prompt revision interface, seed, and auth gap
UAT requires prompt tuning, so the iteration system is M3; only the editing UI is deferred. - METADATA-105 now covers storage, append-only revisions, and recording the revision used. - METADATA-106 adds the REST revision interface (append, activate, read); no prompt UI. - METADATA-107 records the missing authentication as a later row; there is no M4 yet, so the PoR carries it. - PROMPTS.md owns the seed text as revision 0, the seed mechanism, and the interface; sections renumbered after inserting them. - DATA-MODEL.md §7 cites PROMPTS.md, adds content_hash, and states the append-only rule. - task_breakdown.md notes the S7 interface and the deferred auth. 155 requirements; both gates pass.
This commit is contained in:
@@ -17,7 +17,7 @@ the same scenario.
|
||||
| S4 | Woo client (application-password Basic) + taxonomy sync + test-woo | METADATA-5/10/15/20/30, SETTINGS-40/50/51/55/60/80, QUALITY-35 |
|
||||
| S5 | pricing, deterministic templates, server-derived ready | REVIEW-5/10/15/20/25/30/35/40/50, METADATA-70/80/85/90, QUALITY-90/95 |
|
||||
| S6 | publish (sequence, UAT draft, duplicate/stale/partial failure) | PUBLISH-5/10/15/20/25/30/31/35/36/37/38/40/45/50/55/60 |
|
||||
| S7 | inference last (Call 1 / Call 2, prompt revisions, template fallback) | METADATA-35/40/45/50/55/60/65/66/75/95/100/105/110/115, SETTINGS-45/70 |
|
||||
| S7 | inference last (Call 1 / Call 2, prompt revisions, template fallback) | METADATA-35/40/45/50/55/60/65/66/75/95/100/105/106/110/115, SETTINGS-45/70 |
|
||||
| Cross | frontend API client; Review / Settings / Publish screens | UI for the slices above |
|
||||
| Exit | inference-off suite, Woo-mock integration, Compose UI E2E, real UAT draft | QUALITY-20/35/50/105/110/120 |
|
||||
|
||||
@@ -27,6 +27,9 @@ the same scenario.
|
||||
authored when the Call 2 slice is built (`METADATA-85`): Knife blanks, Dimensional wood, Live
|
||||
edge wood, Bowl blanks, logs and caps, Pen blanks, Pepper mill blanks.
|
||||
2. `Specialty cuts` is out of M3: no title pattern, no prose template, no Call 2 prompt.
|
||||
3. S7 ships the prompt revision REST interface (`METADATA-106`) so UAT prompt tuning can be done
|
||||
against the running server. There is no prompt editing UI; tuning is an API call.
|
||||
4. Authentication for the prompt revision interface is `later` (`METADATA-107`), not M3.
|
||||
|
||||
## Frontend layout
|
||||
|
||||
|
||||
+2
-2
@@ -28,7 +28,7 @@ IDs:
|
||||
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-70, METADATA-75, METADATA-80, METADATA-85, METADATA-90, METADATA-95, METADATA-100,
|
||||
METADATA-105, METADATA-110, METADATA-115,
|
||||
METADATA-105, METADATA-106, METADATA-110, METADATA-115,
|
||||
REVIEW-5, REVIEW-10, REVIEW-15, REVIEW-20, REVIEW-25, REVIEW-30, REVIEW-35, REVIEW-40,
|
||||
REVIEW-45, REVIEW-50,
|
||||
PUBLISH-5, PUBLISH-10, PUBLISH-15, PUBLISH-20, PUBLISH-25, PUBLISH-30, PUBLISH-31, PUBLISH-35,
|
||||
@@ -45,4 +45,4 @@ QUALITY-120, QUALITY-125
|
||||
|
||||
IDs:
|
||||
|
||||
CAPTURE-15, CAPTURE-165, OPS-30, OPS-35, QUALITY-115
|
||||
CAPTURE-15, CAPTURE-165, METADATA-107, OPS-30, OPS-35, QUALITY-115
|
||||
|
||||
@@ -77,7 +77,9 @@ The listing is built in two inference calls, both optional. Call 1 (vision) read
|
||||
| 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, the revision history is retained, and the revision used is recorded with the call. | M3 | — |
|
||||
| METADATA-106 | The prompt revision interface is a REST API: append a revision, activate a revision, and read the active prompt with its revision list. There is no prompt editing UI. | M3 | — |
|
||||
| METADATA-107 | Before the prompt revision interface is exposed beyond the trusted network it requires authentication. | later | — |
|
||||
| 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 | — |
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ Status: SPEC · 2026-09-18. Store: SQLite.
|
||||
| APP-40 | derived numbers stored, never recomputed |
|
||||
| CAPTURE-25, CAPTURE-30, CAPTURE-70, CAPTURE-80, CAPTURE-85, CAPTURE-90, CAPTURE-95, CAPTURE-105, CAPTURE-115, CAPTURE-130, CAPTURE-135, CAPTURE-160 | slab and photo columns, units, PNG |
|
||||
| METADATA-5, METADATA-10, METADATA-15, METADATA-30 | taxonomy cache tables and slab taxonomy columns |
|
||||
| METADATA-35, METADATA-45, METADATA-55, METADATA-66, METADATA-105 | inference columns, prompts tables, logs |
|
||||
| METADATA-35, METADATA-45, METADATA-55, METADATA-66, METADATA-105, METADATA-106 | inference columns, prompts tables, logs, revision interface |
|
||||
| PUBLISH-25, PUBLISH-30 | purge on success, append-only log |
|
||||
| REVIEW-10, REVIEW-25, REVIEW-45, REVIEW-50 | prose, price, SKU, field limits |
|
||||
| SETTINGS-5, SETTINGS-10, SETTINGS-20, SETTINGS-25, SETTINGS-30, SETTINGS-35, SETTINGS-50, SETTINGS-51, SETTINGS-55, SETTINGS-65, SETTINGS-90 | settings, crypto, rates, taxonomy stamps |
|
||||
@@ -132,11 +132,19 @@ Rebuild is one transaction; on failure the previous cache is kept.
|
||||
|
||||
## 7. `prompts` and `prompt_revisions`
|
||||
|
||||
Prompts live in the database with all revisions; each call uses the active revision and the
|
||||
history is retained.
|
||||
`docs/contracts/PROMPTS.md` owns the prompt structure, the seed text, and the revision interface; this
|
||||
section owns the storage shape (`METADATA-105`, `METADATA-106`).
|
||||
|
||||
- `prompts`: `id`, `name` (`call1` | `call2`), `active_revision_id`, `created_at`, `updated_at`.
|
||||
- `prompt_revisions`: `id`, `prompt_id` FK, `content` text, `created_at`, `created_by`.
|
||||
- `prompts`: `id`, `name` (`call1` | `call2`), `active_revision_id` FK, `created_at`, `updated_at`.
|
||||
- `prompt_revisions`: `id`, `prompt_id` FK, `content` text, `content_hash` text, `created_at`,
|
||||
`created_by`.
|
||||
|
||||
Revisions are append-only: a save inserts a new row and moves `active_revision_id`; a row is never
|
||||
updated or deleted, so reset-to-revision and reset-to-default are pointer moves. Each prompt has a
|
||||
revision 0 seeded on first run from the seed text in `docs/contracts/PROMPTS.md` §6.
|
||||
|
||||
`inference_log.call` records which call ran, and `inference_log.prompt_revision_id` records the
|
||||
revision it used (`METADATA-66`).
|
||||
|
||||
## 8. `sync_log`
|
||||
|
||||
|
||||
+47
-13
@@ -11,22 +11,33 @@ Owns prompt storage, prompt inputs, and the two inference calls.
|
||||
| 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, inference-off path |
|
||||
| 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-105, METADATA-106, METADATA-107 | prompt storage, revision interface, auth |
|
||||
| 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. No prompt files ship with the application; the database is
|
||||
the only prompt source.
|
||||
- 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.
|
||||
- Prompts live in the database, not in text files, with all revisions retained. Storage shape is
|
||||
`docs/contracts/DATA-MODEL.md` §7 (`METADATA-105`).
|
||||
- Revisions are append-only. Editing saves a new revision and moves the active pointer; a revision
|
||||
is never updated or deleted. Reset to default and reset to revision are pointer moves.
|
||||
- Each call reads the active revision fresh, and the revision used is recorded on the call
|
||||
(`METADATA-66`).
|
||||
- The seed text in §6 is read once on first run and written as revision 0 for each call. It is the
|
||||
only prompt content that ships with the application.
|
||||
|
||||
## 2. Call 1 — vision classification
|
||||
## 2. Revision interface
|
||||
|
||||
REST, no UI (`METADATA-106`):
|
||||
|
||||
1. `POST /api/v1/prompts/{call}/revisions` appends a revision and returns it.
|
||||
2. `POST /api/v1/prompts/{call}/activate` moves the active pointer to a revision.
|
||||
3. `GET /api/v1/prompts/{call}` returns the active prompt and the revision list.
|
||||
|
||||
The interface is reachable on the trusted network only until it is authenticated (`METADATA-107`).
|
||||
|
||||
## 3. 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.
|
||||
@@ -53,7 +64,7 @@ editable; below it the field stays empty and is not shown as a low-confidence gu
|
||||
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
|
||||
## 4. 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.
|
||||
@@ -78,7 +89,7 @@ No provider thread id is used, and Call 1's raw prompt and result are not sent (
|
||||
(`METADATA-55`, `METADATA-80`). The primary wood category selects the specialized prompt
|
||||
(`METADATA-85`). The owner can edit the result (`REVIEW-40`).
|
||||
|
||||
## 4. Fallback and templates
|
||||
## 5. Fallback and templates
|
||||
|
||||
- With inference off, the server produces the long description so create never lacks prose
|
||||
(`METADATA-70`).
|
||||
@@ -88,8 +99,31 @@ No provider thread id is used, and Call 1's raw prompt and result are not sent (
|
||||
- All generated text stays within the field limits in `docs/contracts/WOO-API.md` §9
|
||||
(`REVIEW-50`).
|
||||
|
||||
## 5. Prompt management
|
||||
## 6. Seed prompt text
|
||||
|
||||
- The active Call 1 and Call 2 revisions are editable; saving creates a new revision.
|
||||
Read once on first run and written as revision 0 for each call (`METADATA-105`). Authored here with
|
||||
the rest of the prompt discussion; the seed is the only prompt content that ships with the
|
||||
application.
|
||||
|
||||
The seed is the starting point for tuning, not a final text. Both calls are revised ad hoc through
|
||||
the §2 interface when UAT surfaces a miss.
|
||||
|
||||
**`call1` seed.** Classify the slab's species, wood categories, edge type, figure, and grade from
|
||||
the supplied photos, choosing only from the supplied synced taxonomy lists, and return the result
|
||||
fields in §3 as JSON. Report a confidence for each classified field. Map free-text observations
|
||||
(character, inclusions, voids, checks) to the supplied feature-tag list only. Invent no category or
|
||||
term.
|
||||
|
||||
**`call2` seed.** Write the long product description for the slab from the supplied photos and
|
||||
listing facts. The name and short description are already built, so do not repeat them. Use the
|
||||
brand voice and geo context given. The dimensions in the fact block are exact: use those strings
|
||||
and invent no numbers. Write prose a premium lumber buyer would read.
|
||||
|
||||
## 7. Prompt management
|
||||
|
||||
- The active Call 1 and Call 2 revisions are editable through the §2 interface; saving creates a
|
||||
new revision.
|
||||
- A revision identifies its content, author, and timestamp; `inference_log` records the revision
|
||||
used for each call.
|
||||
- The revision interface requires authentication before it is exposed beyond the trusted network
|
||||
(`METADATA-107`).
|
||||
|
||||
Reference in New Issue
Block a user