Revert "docs(m3): record create build plan and decisions"

This reverts commit 20f08bbc25.
2026-09-19 09:35:57 -07:00
parent 20f08bbc25
commit 90e862cfb0
1 changed files with 0 additions and 84 deletions
@@ -1,84 +0,0 @@
 # M3 Create — build plan (working record)
 Status: WORKING RECORD · 2026-09-19 · **not normative**.
 `docs/REQUIREMENTS.md` is the only normative text; `docs/MILESTONES.md` holds the M3 ID subset;
 behavior is in `docs/capabilities/CREATE.md` and `docs/contracts/`. This file records decisions
 made on 2026-09-19 so a new session does not re-litigate or drift from them. It **cites**
 requirement IDs; it defines none.
 ## 1. Scope
 Implement Milestone 3 only, per the M3 ID subset in `docs/MILESTONES.md` and
 `docs/capabilities/CREATE.md`. Do not implement outside that subset unless the owner expands scope
 in chat.
 ## 2. Settled contract rulings (owner, 2026-09-19)
 | # | Question | Ruling | Now lives in |
 |---|---|---|---|
 | R1 | Soft delete representation | Add `deleted_at TEXT NULL`; deleted rows excluded from all GET responses; status enum unchanged | `docs/contracts/DATA-MODEL.md` §1–2, `docs/contracts/API.md` §4 |
 | R2 | Publish completion vs the poll endpoint | The terminal poll returns `woo_product_id`; the local working slab row is then discarded; the device draft is cleared client-side; the app **never deletes from WooCommerce** | `docs/REQUIREMENTS.md` PUBLISH-25, `docs/contracts/API.md` §4 + §7, `docs/contracts/DATA-MODEL.md` §1 |
 | R3 | Prompt storage | SQLite is the point of record (`prompts` + `prompt_revisions`). File-based prompts are **superseded**; no prompt files ship and the `backend/app/prompts:ro` compose mount was removed | `docs/contracts/PROMPTS.md` (unchanged), `deploy/docker-compose.yml`, `docs/DEPLOYMENT.md` |
 | R4 | `/images` volume | Photo bytes are SQLite BLOBs (source of truth). `/images` holds only a health-probe file and short-lived staging (1024 px Call-1 JPEGs, Woo media uploads), purged after use. Health goes non-200 when the DB or `/images` is unwritable; `woo_reachable:false` stays 200 | `docs/contracts/DATA-MODEL.md` §1, APP-45 |
 ## 3. Implementation decisions
 **Stack.** FastAPI + stdlib `sqlite3` + `schema.sql` (`CREATE TABLE IF NOT EXISTS`). No SQLAlchemy,
 no Alembic. Pragmas `journal_mode=WAL`, `foreign_keys=ON`, `busy_timeout`, `synchronous=NORMAL`;
 one process-wide connection behind a lock. The app factory takes `db_path` and `image_dir` so tests
 get per-test isolation. Revisit an ORM/migrations only after real UAT data exists.
 **Async (202 + poll).** One in-process job queue with a single consumer — **not** FastAPI
 `BackgroundTasks` (Starlette background tasks make TestClient 202 tests accidentally synchronous).
 Status transitions CAS inside `BEGIN IMMEDIATE`. Tests run the queue in an inline mode so contract
 tests stay deterministic.
 **Photos.** `slab_photos.original_blob` / `processed_blob` are the source of truth; `/images` per R4.
 **Prompts.** DB-only with revisions per R3.
 **Publish.** Per R2 and `docs/contracts/API.md` §7 + `docs/contracts/CONTENT-WOO.md`. On success:
 set `woo_product_id`, purge photos, delete the working row after the terminal poll is served, clear
 the device draft. `SLAB-UAT-*` always creates a draft. `max_upload_size` is checked before media
 upload (`docs/contracts/WOO-API.md` §10).
 **Other.**
 - `ready` is server-derived from the REVIEW-5 set.
 - SKU is entered at the Measure step (UX §2.5); do not widen the Capture union.
 - The server stores client-sent derived numbers and never recomputes them as source of truth (APP-40).
 - PUT order: 404 → 409 `revision_conflict` → 409 `duplicate_sku` → 422 `stale_field` → apply → `server_rev++`.
 - Call 1 fills empty fields only; background inference writes bump `server_rev` and the client adopts the polled rev.
 - Frontend additions stay outside the Capture union: `frontend/src/api/*`, `frontend/src/create/*`.
 ## 4. Slice order
 | Slice | Delivers | M3 IDs |
 |---|---|---|
 | S0 | factory, config/startup guards, health/meta, JSON logs, Dockerfile | APP-30, APP-45, APP-55, APP-65, SETTINGS-10, SETTINGS-25, OPS-25 |
 | S1 | AES-GCM crypto + Settings (masked, write-only secrets) | SETTINGS-5/15/20/25/30/35/75/85/90, QUALITY-125 |
 | S2 | slabs CRUD, optimistic concurrency, soft delete | APP-5/15/20/35/40, REVIEW-45 |
 | S3 | photos (multipart → BLOBs, original/processed, 410 after purge) | CAPTURE-95/105/130, PUBLISH-40 |
 | S4 | Woo client (app-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, templates fallback) | METADATA-35/40/45/50/55/60/65/66/75/95/100/105/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 |
 TDD every slice: the failing test precedes its implementation; never parallelize RED and GREEN of
 the same scenario.
 ## 5. Guardrails
 - Subagents run on a single local GPU: **one at a time, never in parallel**.
 - Agents never declare a gate green; Ty owns gate exit (QUALITY-25, QUALITY-30).
 - Run `python tools/check_requirements.py` after any docs change; it must pass.
 - Ports `10880`–`10889` are this project's; never bind `:10880`. Dev-test runs on `:10881`, bound `0.0.0.0`.
 - Create must work with inference off (zero inference calls) — QUALITY-20.
 - No raw status codes, stack traces, or internal codes reach the owner — QUALITY-120.
 ## 6. Not yet validated
 - Long-horizon multi-step agentic loops (more than one or two tool round-trips).
 - M3 implementation has not started; this file is the pre-build record.