From f0f891f80e0e4994107dc6f8cd06f99dba3a161f Mon Sep 17 00:00:00 2001 From: Ty Balascio Date: Sat, 19 Sep 2026 12:29:08 -0700 Subject: [PATCH] docs(m3): add the prompt revision interface, seed, and auth gap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .../milestones/v0.5/M3/task_breakdown.md | 5 +- docs/MILESTONES.md | 4 +- docs/REQUIREMENTS.md | 4 +- docs/contracts/DATA-MODEL.md | 18 ++++-- docs/contracts/PROMPTS.md | 60 +++++++++++++++---- 5 files changed, 69 insertions(+), 22 deletions(-) diff --git a/.planning/milestones/v0.5/M3/task_breakdown.md b/.planning/milestones/v0.5/M3/task_breakdown.md index fcb5d59..6a9fd8c 100644 --- a/.planning/milestones/v0.5/M3/task_breakdown.md +++ b/.planning/milestones/v0.5/M3/task_breakdown.md @@ -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 diff --git a/docs/MILESTONES.md b/docs/MILESTONES.md index 707f91d..029a121 100644 --- a/docs/MILESTONES.md +++ b/docs/MILESTONES.md @@ -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 diff --git a/docs/REQUIREMENTS.md b/docs/REQUIREMENTS.md index 61a757b..5dc141f 100644 --- a/docs/REQUIREMENTS.md +++ b/docs/REQUIREMENTS.md @@ -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 | — | diff --git a/docs/contracts/DATA-MODEL.md b/docs/contracts/DATA-MODEL.md index df7c27c..cbbe405 100644 --- a/docs/contracts/DATA-MODEL.md +++ b/docs/contracts/DATA-MODEL.md @@ -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` diff --git a/docs/contracts/PROMPTS.md b/docs/contracts/PROMPTS.md index 8a37044..daa16b9 100644 --- a/docs/contracts/PROMPTS.md +++ b/docs/contracts/PROMPTS.md @@ -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`).