From 779fa7d484c325d4a3675698d7723a9dc497c3a5 Mon Sep 17 00:00:00 2001 From: grokbot_ty Date: Tue, 1 Sep 2026 05:30:27 +0000 Subject: [PATCH] docs: archive PRD, gate map in AGENTS, drop PM-DESIGN Move PRD to docs/archive/PRD-2026-08.txt with superseded header. Rewrite live references. AGENTS gains Gate A/B/C table, freeze provenance, open-doc-defects slot, and archive rank. README/TECH-SPEC /ARCHITECTURE de-dupe. DoD green: delete PM-DESIGN-ALIGNMENT. --- AGENTS.md | 77 +++- README.md | 27 +- docs/ARCHITECTURE.md | 2 +- docs/CONTENT-WOO.md | 2 +- docs/IMPL-PLAN.md | 3 +- docs/PM-DESIGN-ALIGNMENT.md | 365 ------------------ docs/TECH-SPEC-PIPELINE.md | 6 +- .../archive/PRD-2026-08.txt | 18 + 8 files changed, 103 insertions(+), 397 deletions(-) delete mode 100644 docs/PM-DESIGN-ALIGNMENT.md rename Slab capture app PRD.txt => docs/archive/PRD-2026-08.txt (95%) diff --git a/AGENTS.md b/AGENTS.md index 3d33fb6..9851a6f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,30 +2,60 @@ Working contract for coding agents. Read before writing code. -Status: **Gate A freeze** · signed 2026-08-31 PT · SoT: Gitea `Ty_Tech/SlabUploader` on **gitea-atd** (not mirrors). +Status: **Gate A freeze** · signed 2026-08-31 PT · docs refactor 2026-09-01 · SoT: Gitea `Ty_Tech/SlabUploader` on **gitea-atd** (not mirrors). --- ## 0. Doc precedence (hard) -When docs disagree, use this order until stale docs are rewritten: +When docs disagree, use this order: 1. **`docs/TECH-SPEC-PIPELINE.md`** — deterministic math, image prep, constants, test vectors -2. **`docs/ARCHITECTURE.md`** — hybrid topology, what-runs-where, secrets, status machine -3. This **`AGENTS.md`** — hard rules for agents +2. **`docs/ARCHITECTURE.md`** — hybrid topology, what-runs-where, secrets why, status machine +3. This **`AGENTS.md`** — hard rules for agents (verbatim locks below) 4. **`docs/DATA-MODEL.md`**, **`docs/OPENAPI.md`**, **`docs/CONTENT-WOO.md`**, **`docs/PROMPTS.md`**, **`docs/DEPLOYMENT.md`** -5. **`docs/IMPL-PLAN.md`** — Hybrid-aligned Phases 0–6 are authoritative. Phase 2 is a deferred stub only (offline PWA / OCR / ruler). Do not implement deferred stubs or any server happy-path measure/crop as SoT. -6. **PRD / README** — product intent only; do **not** implement lines that contradict TECH-SPEC, ARCHITECTURE, or this file +5. **`docs/IMPL-PLAN.md`** — hybrid-aligned Phases 0–6. Phase 2 is a deferred stub only (offline PWA / OCR / ruler). Do not implement deferred stubs or any server happy-path measure/crop as SoT. +6. **`README.md`** — orientation only +7. **`docs/archive/PRD-2026-08.txt`** — frozen archive only. Not a source for new work. -Known stale / do-not-implement without rewrite: +Archived PRD lines that conflict with the files above are non-authoritative (see archive header and known-stale list). -- PRD FR17 “Tags: fig-* only” → **wrong**. Locked model is `fig-*` (1+) + `feat-*` (0+). See DATA-MODEL. -- PRD FR19 / overview “species and wood category” pricing → **wrong**. Species `$/bdft` only. Category-weighted pricing is deferred (v1.5). -- PRD FR40 “server-side processing” and NFR “server normalization” → **wrong**. Client owns happy-path measure/crop; server stores drafts and runs U2Net on demand only. -- PRD FR42 / deploy bullets hard-coding `.201` → superseded by env-agnostic DEPLOYMENT (inventory + `APP_HOSTNAME`). -- Older “creds client-side” decision → **wrong**. Server AES-GCM only; never browser storage for secrets (PRD D15 already corrected; keep this lock). -- PRD / README offline-first PWA / OCR / ruler → superseded by hybrid + online-only MVP. -- CONTENT-WOO / DEPLOYMENT older “pending” create default → superseded: UAT uses **Woo draft** + `SLAB-UAT-*`. +### Known stale (archive / historical only) + +- Archived PRD FR17 “Tags: fig-* only” → **wrong**. Locked model is `fig-*` (1+) + `feat-*` (0+). See DATA-MODEL. +- Archived PRD FR19 / overview “species and wood category” pricing → **wrong**. Species `$/bdft` only. Category-weighted pricing is deferred (v1.5). +- Archived PRD FR40 “server-side processing” and NFR “server normalization” → **wrong**. Client owns happy-path measure/crop; server stores drafts and runs U2Net on demand only. +- Archived PRD FR42 / deploy bullets hard-coding `.201` → superseded by env-agnostic DEPLOYMENT (inventory + `APP_HOSTNAME`). +- Older “creds client-side” decision → **wrong**. Server AES-GCM only; never browser storage for secrets. +- Offline-first PWA / OCR / ruler product text → superseded by hybrid + online-only MVP. +- Older “pending” Woo create default → superseded: UAT uses **Woo draft** + `SLAB-UAT-*`. + +### Open doc defects + +None known after the 2026-09-01 docs refactor on `docs/refactor-v2`. If a greppable DoD item fails, list it here before deleting reconciliation notes. + +--- + +## 0b. Gates (human map) + +| Label | Human name | What it means | +|---|---|---| +| Gate A | Docs freeze | Product locks written into the repo | +| Gate B | Run-host setup | Inventory the real host, deploy skeleton | +| Gate C | First draft listing | One Woo draft listing with inference OFF | + +Phase map: **Phase 0 = Gates A+B.** **Gate C = early Phase 1** claimable publish slice. Call 1/2 after Gate C, still inside POC. Depth: `docs/IMPL-PLAN.md`. + +### Freeze provenance (Gate A) + +| SHA | What locked | +|---|---| +| `a94d81d` | gitea-atd `Ty_Tech/SlabUploader` as remotes SoT | +| `457711b` | AGENTS.md + hybrid IMPL Phase 0 | +| `4ec478f` | Contradiction patches (README/PRD/Woo/DEPLOYMENT) | +| `4d9f307` / `4e97770` | Inference review + hybrid capture pipeline (pre-freeze baseline) | + +Docs refactor stack on `docs/refactor-v2` (2026-09-01) applies OPENAPI store-only, env-agnostic deploy, CONTENT-WOO/DATA-MODEL facts, hybrid Phases 1–6, PRD archive. Product locks above are unchanged. --- @@ -51,6 +81,8 @@ Known stale / do-not-implement without rewrite: Happy path never leaves the phone until the user continues after confirmed mask + numbers. +Depth: `docs/ARCHITECTURE.md`. + --- ## 2. What NOT to build (early phases / MVP) @@ -79,11 +111,13 @@ Encode TECH-SPEC exactly: - Image prep: sheet/sliders → mask confirm → length axis confirm → 3:4 PNG / 80% fill / ≥1600px when source allows. - **No inventing pixels. No fake upscale.** Undersized source → warn + retake; photo not publishable until retake. - Pricing: species `$/bdft` from Settings, seeded by Woo species sync; `rec = bdft × price_per_bdft`; user override sticks; missing rule → empty rec, manual allowed. -- Port TECH-SPEC **TV-1 through TV-10** (including TV-10 Rounding). Client (or shared pure modules the client uses) is authoritative for math; server **stores** client-sent numbers — does not recompute as SoT. Depth: `docs/TECH-SPEC-PIPELINE.md`. +- Port TECH-SPEC **TV-1 through TV-10** (including TV-10 Rounding). Client (or shared pure modules the client uses) is authoritative for math; server **stores** client-sent numbers — does not recompute as SoT. + +Depth: `docs/TECH-SPEC-PIPELINE.md`. --- -## 4. Secrets & settings +## 4. Secrets and settings **Never in browser storage / JS bundles:** @@ -95,9 +129,11 @@ Encode TECH-SPEC exactly: **Browser may persist (non-secret):** sheet mode, sensitivity, edge offset, feather (localStorage OK; reset-to-default required). +Why/flow: `docs/ARCHITECTURE.md` §5. Ciphertext key inventory: `docs/DATA-MODEL.md` settings table. + --- -## 5. Woo UAT & create status (Ty locked 2026-08-31) +## 5. Woo UAT and create status (Ty locked 2026-08-31) - Store: **PROD** `www.whidbeywoodstore.com` - Mid-phase UAT creates: Woo status **draft**, SKU prefix **`SLAB-UAT-*`** @@ -108,6 +144,8 @@ Encode TECH-SPEC exactly: - After successful publish: purge originals + processed images on server - Do **not** conflate with slab lifecycle status (below) +Payload and publish sequence depth: `docs/CONTENT-WOO.md` (cites this section for safety policy). Key only: DATA-MODEL `woo_create_status`. + --- ## 6. Inference (inside POC, sequenced) @@ -116,8 +154,11 @@ Encode TECH-SPEC exactly: - **Gate C** claimable path: inference **OFF**; manual taxonomy + deterministic numbers + Woo draft path. - **Call 1 (vision) / Call 2 (text) only after Gate C is green, still inside overall POC** before “done” — not post-POC. - Call 1 auto only if `inference_enabled`; Call 2 never auto-fires (user taps Generate text). +- Call 1 body: all inventory photos @1024 (not top-down-only). Confidence threshold 0.7 (configurable) lives in IMPL Phase 5 / PROMPTS. - LoRA deferred. No numeric/dimension invention by LLM; templates inject deterministic numbers. +Prompt file mechanics: `docs/PROMPTS.md`. + --- ## 7. Slab status machine (app-internal only) @@ -131,7 +172,7 @@ Encode TECH-SPEC exactly: --- -## 8. Test & delivery expectations +## 8. Test and delivery expectations - No feature without a passing test and shown execution output (PR/commit message). - Deterministic core unit-tested before UI consumes it. diff --git a/README.md b/README.md index 3ead516..0771213 100644 --- a/README.md +++ b/README.md @@ -6,41 +6,52 @@ Phone capture (online) → hybrid measure/crop on device → review → WooComme Owner: Ty (Whidbey). Store: www.whidbeywoodstore.com. Deploy: Docker Compose + Caddy on an inventoried host (`APP_HOSTNAME`). ## Status -**POC requirements freeze in progress (Gate A, 2026-08-31).** Read `AGENTS.md` before -any implementation. TECH-SPEC + ARCHITECTURE beat stale PRD/README lines. Do **not** -treat older “planning complete / ready for implementation” wording as a green light -to code the obsolete server-pipeline Phase 0. + +**Gate A freeze signed 2026-08-31.** Docs refactor on branch `docs/refactor-v2` (2026-09-01). +Read `AGENTS.md` before any implementation. TECH-SPEC + ARCHITECTURE + AGENTS beat archived PRD lines. POC bar: phone → customer-ready listing on the real store; UAT creates as **Woo draft** with `SLAB-UAT-*` SKUs; one real SKU **Woo publish** after Ty review. Online-only for POC -(offline deferred). Build plan: `docs/IMPL-PLAN.md` (Phase 0 = hybrid Gates A+B). +(offline deferred). Build plan: `docs/IMPL-PLAN.md` (Phase 0 = hybrid Gates A+B; Gate C = +early Phase 1 first draft listing). ## Documentation + | File | What | |---|---| | `AGENTS.md` | Working contract + hard rules (read first) | -| `Slab capture app PRD.txt` | Requirements + decisions (intent; superseded lines called out in AGENTS) | | `docs/ARCHITECTURE.md` | Hybrid client/server split, data flow | | `docs/TECH-SPEC-PIPELINE.md` | Deterministic math + image pipeline, constants, test vectors | | `docs/DATA-MODEL.md` | SQLite schema + slab status state machine | | `docs/OPENAPI.md` | Client↔server API contract | | `docs/CONTENT-WOO.md` | Content templates + WooCommerce payload/integration | | `docs/PROMPTS.md` | Vision + content prompts (server files) | -| `docs/DEPLOYMENT.md` | Compose, Caddy, backup/restore, key rotation | +| `docs/DEPLOYMENT.md` | Env-agnostic compose, Caddy, backup/restore | +| `deploy/INVENTORY.md` | Host inventory worksheet (Gate B) | | `docs/IMPL-PLAN.md` | Phased build plan with acceptance criteria + exit gates | +| `docs/archive/PRD-2026-08.txt` | Frozen historical PRD only (not a source for new work) | ## Quick orientation + +Hard locks live in `AGENTS.md`. Short map: + - **Hybrid:** phone owns mask/sliders/sqft/bdft/3:4 PNG; server stores, Woo, inference proxy, on-demand U2Net. -- **Deterministic core** is unit-tested and network-free. Inference is toggleable; app works with it off. +- **bdft** = sqft × thickness_in (no `/12`). TV-1 through TV-10 on the client. +- **Secrets** never in browser; AES-GCM on server; `SLAB_AES_KEY` env only. +- **Woo UAT:** draft default; `SLAB-UAT-*` force draft (AGENTS §5). +- **Inference OFF** until Gate C; Call 1/2 after, still inside POC. - **Online-only for POC** (offline PWA deferred). - **Two containers** (`frontend`, `fastapi`) + Caddy. Single SQLite + image volumes. - **v1 non-goals:** no versioning, no staff/roles, no bulk publish, no analytics, no SKU update path. ## Repo remotes + - Canonical SoT: Gitea `Ty_Tech/SlabUploader` on **gitea-atd** (`https://gitea.vps1.afterthedemo.com/Ty_Tech/SlabUploader`) - Optional later mirrors: `gitea-truenas`, GitHub — not SoT for this workstream ## Getting started (implementer) + 1. Read `AGENTS.md` (hard rules) and Phase 0 in `docs/IMPL-PLAN.md`. 2. Start at Phase 0 — hybrid client TECH-SPEC modules + thin FastAPI health/settings (not a server happy-path pipeline). 3. Do not skip exit gates; Ty signs each phase via the delivery process. +4. Do not implement from `docs/archive/PRD-2026-08.txt`. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index cdd4582..9a86fc0 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -6,7 +6,7 @@ Normative for hybrid split, swimlane, what-runs-where, secrets **why**, and stat transitions. Ops depth lives in DEPLOYMENT. Schema enums live in DATA-MODEL. Agent-facing hard rules live in AGENTS.md (verbatim locks stay there). -Companion: TECH-SPEC-PIPELINE.md. PRD is historical intent only (see AGENTS precedence). +Companion: `docs/TECH-SPEC-PIPELINE.md`. Historical PRD: `docs/archive/PRD-2026-08.txt` (frozen; not a source for new work). Agent locks: `AGENTS.md`. ## 1. Topology (hybrid) diff --git a/docs/CONTENT-WOO.md b/docs/CONTENT-WOO.md index 593722a..dc19b8a 100644 --- a/docs/CONTENT-WOO.md +++ b/docs/CONTENT-WOO.md @@ -54,7 +54,7 @@ All template math fields come from the deterministic pipeline (never from the LL ### 1.3 Audit Every content generation (template or LLM) is logged with inputs (template version, -slab facts), the LLM request/response payload when used (PRD "inference calls logged"), +slab facts), the LLM request/response payload when used (inference calls logged for audit), and the final stored content. ## 2. WooCommerce integration (FR24–28) diff --git a/docs/IMPL-PLAN.md b/docs/IMPL-PLAN.md index cf4da36..103a995 100644 --- a/docs/IMPL-PLAN.md +++ b/docs/IMPL-PLAN.md @@ -292,7 +292,8 @@ authoritative for POC. Do not treat ruler confidence as a POC risk row. ## Definition of Done (v1, project-level) - All 6 phases exit-gated by Ty (Phase 2 remains deferred stub unless product reopens it). -- Hybrid online acceptance met (measured in Phase 6 UAT). +- Hybrid online acceptance met (measured in Phase 6 UAT). Gates A/B/C meanings match AGENTS §0b. - `pytest` + integration + UAT green; inference-off path green. - Deployed on the inventoried host (`APP_HOSTNAME` from `deploy/INVENTORY.md`), HTTPS, backed up, restore tested, runbook + key-rotation verified. - Repo on gitea-atd (`Ty_Tech/SlabUploader`) is source of truth; docs current. +- Do not treat `docs/archive/PRD-2026-08.txt` as implementation SoT. diff --git a/docs/PM-DESIGN-ALIGNMENT.md b/docs/PM-DESIGN-ALIGNMENT.md deleted file mode 100644 index 35eae5b..0000000 --- a/docs/PM-DESIGN-ALIGNMENT.md +++ /dev/null @@ -1,365 +0,0 @@ -# SlabUploader: PM vs design alignment - -**Status:** On gitea-atd for Ty review. 2026-08-31 PT. Human rewrite (unslop). Other doc patches still on HOLD. -**Authors:** Principal PM (product alignment). Dev Manager (technical landmines). -**Baseline on gitea-atd `main`:** `457711b` (AGENTS + Phase 0). `4ec478f` (PRD/README/Woo/DEPLOYMENT patches). -**Also compared:** `/workspace/slabuploader-poc-review-package.md` sections 1-2. Env-agnostic section 3 draft is not on gitea. - ---- - -## How to read this - -| Label | Meaning | -|---|---| -| **Agreed** | Review package, AGENTS, and the design specs say the same thing | -| **Conflict** | Live docs disagree. A coding agent can pick the wrong one. | -| **Missing** | Clarity is absent, or it only lives in a `/workspace` draft not on gitea | - ---- - -## 1. POC outcome and Woo safety - -**Agreed.** End goal: phone photo becomes a customer-ready listing on www.whidbeywoodstore.com. - -Woo safety works like this. Test products are created as drafts with SKU prefix `SLAB-UAT-*`, so customers never see them until Ty intentionally publishes a real SKU. Settings field `woo_create_status` is `draft` or `publish`, default `draft`. Final POC is one real SKU published after Ty review. - -This is locked in AGENTS section 5, PRD decisions 12/FR36 (`4ec478f`), CONTENT-WOO, DATA-MODEL, OPENAPI, DEPLOYMENT smoke, and review package section 1. - -**Conflict.** None material on Woo safety after `4ec478f`. - -**Missing.** Env-agnostic deploy wording still only in `/workspace` package section 3, not on gitea (HOLD). Does not block Woo alignment. - ---- - -## 2. Phone does the math, server stores it - -**Agreed.** The phone (client) owns mask, sliders, axis, sqft, bdft, and the 3:4 PNG. The server stores those numbers, runs U2Net on demand, talks to Woo, and proxies inference. The server must not recompute happy-path math as the source of truth. - -Locked in ARCHITECTURE, TECH-SPEC, AGENTS section 1, IMPL-PLAN Phase 0 (`457711b`), README, and the PRD stack rewrite (`4ec478f`). - -**Conflict.** IMPL-PLAN Phases 1+ still carry stale offline/OCR/ruler and `processing` to `ready` language. Banners say ignore those sections, but agents skim past banners. OPENAPI PUT still says the server re-runs derived math (see blocker B1 below). - -**Missing.** Full rewrite of IMPL-PLAN Phases 1 to 6 for hybrid plus Woo draft UAT. - ---- - -## 3. Board-foot formula - -**Agreed.** `bdft = sqft x thickness_in` (TECH-SPEC TV-3). Same in AGENTS, IMPL-PLAN Phase 0, PRD FR4, DEPLOYMENT smoke. - -**Conflict.** None after `4ec478f`. CONTENT-WOO `length_ft = floor(length_in / 12)` is display conversion only, not bdft math. - -**Missing.** None. - ---- - -## 4. Image prep (3:4, 1600, sliders) - -**Agreed.** Sheet and sliders, mask confirm, 3:4 PNG, 80% fill, at least 1600px or retake, no fake upscale. TECH-SPEC sections 3 to 5, AGENTS, ARCHITECTURE, and review package section 2 match. - -**Conflict (narrow).** PRD FR19 still prices by "species and wood category." TECH-SPEC and DATA-MODEL price by species only ($/bdft). CONTENT-WOO still says media upload is JPEG. TECH-SPEC wants transparent PNG (warn W4). - -**Missing.** Explicit line in PRD when writes reopen: wood category is for taxonomy, not for $/bdft in the POC. - ---- - -## 5. Where secrets live - -**Agreed.** Woo and inference secrets sit on the server under AES-GCM. `SLAB_AES_KEY` is env only. Never in the browser. ARCHITECTURE, AGENTS section 4, PRD D15, DATA-MODEL. - -**Conflict (soft).** DATA-MODEL and OPENAPI still list sheet/slider prefs in server settings. ARCHITECTURE and AGENTS say localStorage (warn W3). - -**Missing.** None. - ---- - -## 6. Inference stays OFF until first draft listing works - -**Agreed.** The test suite must pass with inference OFF. First draft listing (Gate C) means inference OFF, manual path, and Woo draft. Call 1 and Call 2 come after that, still inside the POC. Call 2 is user-triggered. LoRA is deferred. No LLM dimensions. - -Review package, AGENTS section 6, ARCHITECTURE, PROMPTS, Phase 0 out-of-scope. - -**Conflict.** None on sequencing intent. - -**Missing.** Phase 5 rewrite later if any "top-down only" flavor remains versus "all photos @1024." - ---- - -## 7. Slab status vs Woo create status - -**Agreed.** Slab lifecycle: `draft` to `calibrated` to `ready` to `publishing` to `published` or `failed`. Woo create status: `draft` or `publish`. Do not conflate them. A slab can show `published` while the storefront still only has a Woo draft. AGENTS and CONTENT-WOO say this explicitly. - -**Conflict (soft).** The word "published" is overloaded. OPENAPI POST creates a "calibrated draft" but returns `status: draft` (warn W1). - -**Missing.** Optional glossary row when writes reopen. - ---- - -## 8. Online only - -**Agreed.** No offline PWA in the POC. Review package, AGENTS, README (`4ec478f`), PRD decision 18, TECH-SPEC, Phase 0. - -**Conflict.** IMPL-PLAN Phase 2 and Phase 6 still specify offline capture. Superseded banners exist. Agents may skim past them. - -**Missing.** Phase 2/6 body rewrite when writes reopen. - ---- - -## 9. Phase and gate map - -Human names for the gates: - -| Label | Human name | What it means | -|---|---|---| -| Gate A | Docs freeze | Product locks written into the repo | -| Gate B | Run-host setup | Inventory the real host, deploy skeleton | -| Gate C | First draft listing | One Woo draft listing with inference OFF | - -**Agreed.** Phases 0 to 6 stay. Phase 0 covers docs freeze and run-host setup. First draft listing is early Phase 1. Inference starts after first draft listing. - -**Conflict.** Docs freeze raced onto gitea while Ty HOLDed further writes and asked for env-agnostic deploy plus this alignment. Deploy docs still hard-code `.201` in AGENTS section 9, DEPLOYMENT, and PRD FR42 (blockers B2/B5). - -**Missing.** Ty sign-off via CoS on the env-agnostic deploy amend before run-host setup. Coding agents and inventory are held. - ---- - -## Matrix - -| Topic | Status | -|---|---| -| POC outcome and Woo safety | Agreed (on gitea) | -| Phone math vs server store | Agreed core. Conflict in Phase 1+ / OPENAPI PUT. | -| bdft formula | Agreed | -| Image prep | Agreed. Narrow pricing/PNG conflicts. | -| Secrets location | Agreed. Soft prefs storage drift. | -| Inference OFF then Call 1/2 | Agreed | -| Slab lifecycle vs woo_create_status | Agreed. Wording overload residual. | -| Online only | Agreed. Phase 2/6 text stale. | -| Phase / gate sequencing | Map agreed. Missing env-agnostic sign before run-host setup. | - ---- - -## PM take - -Core product intent and the design source of truth (TECH-SPEC, ARCHITECTURE, AGENTS, Phase 0, Woo safety) align after `457711b` and `4ec478f`. What is left is implementer landmines, not a PM vs architecture fight. OPENAPI still tells the server to recompute math. Deploy docs hard-code a host. IMPL-PLAN bodies still describe the old offline pipeline. - -**Recommend via CoS:** when HOLD lifts, authorize one small docs commit for env-agnostic deploy plus OPENAPI "no server recompute" before any coding agents or run-host setup. Optional IMPL-PLAN 1+/2/6 and PRD FR19 cleanup in the same or a follow-on commit. - ---- - -## Technical consistency audit - -**Status:** Workspace-only. No gitea commit, push, or SSH. -**Authors:** Dev Manager, for CoS / Principal PM. -**Repo HEAD:** `4ec478f` on `main` (`Ty_Tech/SlabUploader` @ gitea-atd). -**Audit date:** 2026-08-31 PT. -**HOLD:** Do not write to gitea until CoS lifts HOLD. Fixes below are recommended drafts only. Env-agnostic deploy amend remains unsigned. See `/workspace/slabuploader-poc-review-package.md` section 3 and `/workspace/slabuploader-env-agnostic-doc-outline.md`. - ---- - -### What the docs freeze locked in (SHAs + files) - -``` -git log -5 --oneline -4ec478f docs: finish Gate A contradiction patches -457711b docs: Gate A freeze - AGENTS.md + hybrid Phase 0 -a94d81d docs: set gitea-atd Ty_Tech/SlabUploader as remotes SoT -4d9f307 docs: lock inference review - prompts, Call 1/2, feat tags -4e97770 docs: lock revised capture pipeline and hybrid architecture -``` - -| SHA | Commit | Files locked | -|---|---|---| -| `457711b` | Docs freeze: AGENTS.md + hybrid Phase 0 | `AGENTS.md` (new, 148 lines). `docs/IMPL-PLAN.md` Phase 0 rewrite, plus banner that Phases 1+ are still stale. | -| `4ec478f` | Finish docs-freeze contradiction patches | `README.md`, `Slab capture app PRD.txt`, `docs/CONTENT-WOO.md`, `docs/DATA-MODEL.md`, `docs/DEPLOYMENT.md`, `docs/OPENAPI.md` | - -Already consistent before the freeze (not rewritten in those SHAs, but source of truth per AGENTS precedence): - -- `docs/TECH-SPEC-PIPELINE.md`: client-authoritative math, `bdft = sqft x thickness_in`, TV-1 through TV-10, no `/12` -- `docs/ARCHITECTURE.md`: hybrid topology, AES-GCM secrets, slab status machine -- `docs/PROMPTS.md`: Call 1/2 (no freeze delta) - -Product locks now in-repo via AGENTS + patches: - -- Hybrid: client is happy-path measure/crop source of truth. Server stores, runs on-demand U2Net, talks to Woo, proxies inference. -- `bdft = sqft x thickness_in` (no `/12`) -- Secrets: server AES-GCM only. Never browser. -- Online-only POC. Offline, OCR, and ruler are deferred. -- `woo_create_status` is `draft` or `publish`, default `draft`. `SLAB-UAT-*` forces Woo draft on PROD so customers never see test products. -- Health: `GET /api/health` -- Phase 0 covers docs freeze and run-host setup. First draft listing is early Phase 1 claimable Woo draft with inference OFF. - ---- - -### What already agrees (safe if agents follow AGENTS) - -Agents that follow AGENTS.md section 0 precedence and ignore flagged-stale text will get these right: - -| Topic | Where it agrees | -|---|---| -| Doc precedence | AGENTS section 0: TECH-SPEC, then ARCHITECTURE, then AGENTS, then DATA/OPENAPI/CONTENT/PROMPTS/DEPLOY, then IMPL Phase 0 only, then PRD/README intent | -| Who runs what | AGENTS section 1, ARCHITECTURE sections 1 to 4, TECH-SPEC section 1.5 / 9.8, README, PRD Architecture rewrite (post-`4ec478f`), DEPLOYMENT layout note | -| bdft + TV-3 | TECH-SPEC section 4.6 + TV-3. AGENTS section 3. PRD FR4. IMPL Phase 0. DEPLOYMENT smoke section 8.4. | -| No fake upscale / at least 1600 | TECH-SPEC section 5 + TV-6/7. AGENTS sections 2 to 3. IMPL Phase 0. | -| Secrets AES-GCM server | ARCHITECTURE section 5. AGENTS section 4. DATA-MODEL `settings`. OPENAPI SettingsView. PRD D15. | -| Woo safety | AGENTS section 5. CONTENT-WOO section 2.4. DATA-MODEL `woo_create_status`. OPENAPI SettingsView. DEPLOYMENT smoke section 8. README. PRD D12/FR36. | -| Slab vs Woo status | AGENTS section 7. ARCHITECTURE section 6. DATA-MODEL. CONTENT-WOO section 2.4. | -| Inference sequenced | AGENTS section 6. ARCHITECTURE clarifications 4 to 5. OPENAPI infer endpoints. First draft listing keeps inference OFF. | -| Phase 0 hybrid scope | IMPL-PLAN Phase 0 (post-`457711b`) matches AGENTS. Phase 2 banner says SUPERSEDED. | -| Health path | AGENTS section 9. DEPLOYMENT sections 7 to 8. OPENAPI Health. IMPL Phase 0. | - -If agents start at AGENTS + TECH-SPEC + ARCHITECTURE + IMPL Phase 0 only, the run-host skeleton is coherent. The landmines sit in Phases 1+/risks/PRD leftovers/OPENAPI one-liners and the hard-coded `.201` deploy story. - ---- - -### Remaining contradictions - -Severity: - -- **Blocker**: wrong code if followed -- **Warn**: likely wrong path or wasted work -- **Nit**: wording drift, low blast radius - -#### Blockers - -**B1. OPENAPI says server re-runs derived math when inputs change.** -Where: `docs/OPENAPI.md`, `PUT /api/v1/slabs/{id}` (around L154). -Wrong path: Implement server-side recompute of sqft/bdft/widths as source of truth on PUT. Violates AGENTS section 3 and TECH-SPEC sections 1.5 / 9.8. -Fix: Server stores client-sent derived fields. May validate shape/ranges. Must not recompute mask/sqft/bdft as authoritative. Client re-runs TECH-SPEC math and PUTs new numbers. - -**B2. IMPL-PLAN Phase 1 invents a `processing` to `ready` status.** -Where: `docs/IMPL-PLAN.md` Phase 1 (around L75). -Wrong path: Add a `processing` slab status and a server job that "processes" photos toward `ready`. Reintroduces the old server pipeline under a new name. -Fix: Rewrite Phase 1 to hybrid. CRUD + upload stores client-calibrated payloads. Status machine is only `draft` to `calibrated` to `ready` to `publishing` to `published` or `failed`. Queue only for publish, inference, and U2Net-on-demand. Never for measure/crop. - -**B3. IMPL-PLAN Phase 2 body still specifies offline, OCR, and ruler.** -Where: `docs/IMPL-PLAN.md` Phase 2 (around L86 to L106). Banner says SUPERSEDED, but Goal/Deliverables/Acceptance/Exit still demand Tesseract OCR, OpenCV.js ruler, Workbox, IndexedDB, airplane-mode UAT. -Wrong path: Implement the body. Builds the exact "do not build" list in AGENTS section 2. -Fix: Replace Phase 2 body with a short stub: "Deferred post-POC. Capture UX lives in early Phase 1 / first draft listing (online hybrid). See AGENTS section 2." Delete OCR/ruler/offline acceptance lines. - -**B4. IMPL-PLAN Phase 6 UAT still requires offline capture, OCR, and "server normalization".** -Where: `docs/IMPL-PLAN.md` Phase 6 (around L181 to L183, L175 to L179). -Wrong path: Write UAT scripts and perf budgets for OCR 1 to 2s and server normalization 3 to 5s. Gate exit on offline capture. -Fix: UAT suite is the hybrid online path. Drop offline capture. Perf is client measure/crop budgets plus U2Net-on-demand only. Inventory host via `APP_*` (see env-agnostic section). - -**B5. Deploy docs still hard-code `.201` / `slab.tyubumini.local`.** -Where: `AGENTS.md` section 9. `docs/DEPLOYMENT.md` title/target/sections 1, 4, 6, 7. `README.md` L6. `docs/IMPL-PLAN.md` Phase 0 Gate B (.201 inventory), Phase 6, Risks, DoD. PRD FR42 / deploy bullets. -Wrong path: Bake `192.168.1.201` / `slab.tyubumini.local` into compose, Caddy, health URLs, runbooks. Treat TyUBUMini as mandatory. Skip inventory worksheet. -Fix: Apply `/workspace/slabuploader-env-agnostic-doc-outline.md`. Use `APP_HOST` / `APP_HOSTNAME` / ports and `deploy/INVENTORY.md`. Historical lab as non-normative callout only. Do not push until CoS lifts HOLD. - -#### Warns - -**W1. OPENAPI create returns `status: draft` for a "calibrated draft".** -Where: `docs/OPENAPI.md` `POST /api/v1/slabs` (around L146 to L147). -Wrong path: Skip `calibrated` entirely. Conflate "photos taken" draft with "mask+numbers uploaded" calibrated. Break first-draft-listing poll/UI assumptions. -Fix: POST after client confirm returns `201` with `status: calibrated` (align ARCHITECTURE section 6, DATA-MODEL, AGENTS section 7). - -**W2. AGENTS says "TV-10 only after TECH-SPEC defines it," but TECH-SPEC already has TV-10.** -Where: `AGENTS.md` section 3 (around L80) vs `docs/TECH-SPEC-PIPELINE.md` section 8 TV-10 Rounding (around L192 to L196). -Wrong path: Skip rounding unit tests thinking TV-10 is undefined. -Fix: AGENTS should say "Port TV-1 through TV-10." IMPL Phase 0 acceptance should include TV-10. - -**W3. DATA-MODEL / OPENAPI put sheet prefs in server `settings`. ARCHITECTURE/AGENTS say localStorage.** -Where: DATA-MODEL settings keys `user_sensitivity|edge_offset|feather|sheet_mode` (around L184). OPENAPI SettingsView (around L132 to L133). Versus AGENTS section 4 / ARCHITECTURE section 5. -Wrong path: Dual-write prefs to SQLite AES settings table, or encrypt non-secrets, or fight over which wins on load. -Fix: Remove sheet/slider prefs from server settings schema, or mark optional sync later. Keep localStorage as source of truth for POC. - -**W4. CONTENT-WOO media upload says "JPEG bytes". TECH-SPEC output is transparent PNG.** -Where: `docs/CONTENT-WOO.md` section 2.4 (around L114) vs TECH-SPEC section 5 / PRD FR31. -Wrong path: Re-encode processed PNGs to JPEG and lose alpha before Woo media upload. -Fix: Say "PNG bytes (processed inventory images)." Mention Woo accepts image/*. Keep alpha. - -**W5. CONTENT-WOO tag auto-assign still says `[character]` / optional `[species]` tags.** -Where: `docs/CONTENT-WOO.md` section 2.3 (around L81 to L83) vs DATA-MODEL / PRD D8: `fig-*` + `feat-*` only. -Wrong path: Create non-fig/feat Woo tags named after character strings. Ignore feat-* mapping. -Fix: Rewrite section 2.3 to match DATA-MODEL: fig-* (1+) + feat-* (0+ from Call 1). No generic character/species tag invent. - -**W6. PRD FR17 vs D8 / DATA-MODEL on tags.** -Where: PRD FR17 "Tags: fig-* only, 1+ required" vs Decisions log #8 + DATA-MODEL `fig_tag_ids` + `feat_tag_ids`. -Wrong path: Drop feat-* from schema/UI/publish payload. -Fix: FR17 should say fig-* (1+) and feat-* (0+). Cite DATA-MODEL. - -**W7. PRD FR19 + pricing schema still "species and wood category".** -Where: PRD FR19 (around L134). PRD pricing schema `wood_category: string` (around L241). Versus TECH-SPEC section 6 / DATA-MODEL `pricing_rules` = species only. -Wrong path: Build wood-category pricing tiers or composite keys. -Fix: FR19 + schema become species-only. Wood-category pricing is deferred. - -**W8. PRD FR40 + NFR still say "server-side processing" / "server normalization".** -Where: PRD FR40 (around L190). NFR Performance (around L200 to L201). -Wrong path: Put measure/crop on the publish path server-side. Budget 3 to 5s server normalization as a feature. -Fix: FR40 is Woo sync + status/log only (client already did processing). NFR is client local processing plus optional U2Net latency. Drop "server normalization." - -**W9. DEPLOYMENT section 9 / Risks still mention RemBG, ruler, `output_px` drop to 1000.** -Where: `docs/DEPLOYMENT.md` section 9 (around L161). `docs/IMPL-PLAN.md` Risks (around L201 to L202). -Wrong path: Add RemBG server path. Lower OUTPUT_PX_MIN below 1600 (violates TECH-SPEC TV-7; undersized means retake, not a lower min). -Fix: Delete ruler row for POC or mark deferred. U2Net-on-demand only. Never drop below 1600. - -**W10. Caddy fragment shape is foot-gunny.** -Where: `docs/DEPLOYMENT.md` section 4. Site-level `reverse_proxy frontend:80` plus `handle /api/* { reverse_proxy fastapi:8000 }`. -Wrong path: Ship as-written. `/api/*` may never reach fastapi depending on Caddy directive order. Health smoke fails. -Fix: Explicit `handle /api/*` to fastapi and `handle { reverse_proxy frontend }` (or `handle_path`) so API wins. Keep service name `fastapi` consistent with compose. - -**W11. Calibration-photo language leftovers in CONTENT-WOO.** -Where: CONTENT-WOO section 2.4 (around L116 to L117) "Calibration photos are excluded (FR2)". PRD D1 says no calibration photos exist. -Wrong path: Invent `kind=calibration` in upload meta / schema. OPENAPI/DATA-MODEL correctly only allow `inventory`. -Fix: Delete the sentence. Say "only inventory photos (kind=inventory)." - -#### Nits - -**N1.** DATA-MODEL / OPENAPI still say "PWA" (DATA-MODEL L7; OPENAPI Versioning L301). Risk: agents scaffold Workbox. Fix: "client" / "SvelteKit app". Offline PWA deferred. - -**N2.** PRD Architecture header still "Client (mobile web / PWA)" (around L210). Body correctly says offline deferred. Fix: "Client (mobile web / SvelteKit)". - -**N3.** ARCHITECTURE status line "Remaining sections TBD" (L4). Topology is locked. Stale TBD undercuts confidence. Fix: "Hybrid topology locked at docs freeze. Remaining ops sections TBD." - -**N4.** TECH-SPEC status date still 2026-08-27. AGENTS docs freeze 2026-08-31. Content matches. Optional status bump. - -**N5.** Review package Appendix C checklist items 1 to 7 largely done in-repo. Item 0 (env-agnostic) not done. Package preamble still reads pre-freeze in places ("AGENTS referenced, file missing"). Mark items 1 to 7 done. Keep item 0 open. - -**N6.** DEPLOYMENT docs-freeze banner line-break glitch (L4 to L8). "LAN/Tailscale" sentence split across the callout. Fix when env-agnostic rewrite lands. - ---- - -### Env-agnostic gap - -| Artifact | Role | Normative host? | -|---|---|---| -| Repo: `AGENTS.md` section 9, `docs/DEPLOYMENT.md`, `README.md`, `IMPL-PLAN.md` Gate B / Phase 6 / DoD, PRD FR42 | Current source of truth agents will read | Yes. Hard-codes `.201` / TyUBUMini / `slab.tyubumini.local` / `192.168.1.201`. | -| Workspace: `/workspace/slabuploader-poc-review-package.md` section 3 | Proposed deploy source of truth. Not in repo. | No. Uses `APP_HOST` / `APP_HOSTNAME` / inventory worksheet. Lab example is non-normative. | -| Workspace: `/workspace/slabuploader-env-agnostic-doc-outline.md` | Patch outline for CoS-signed amend | Same | - -These two workspace markdown files are drafts, not source of truth yet. Agents must not treat `/workspace/*.md` as repo authority. Until the env-agnostic amend lands under CoS HOLD lift, run-host inventory is blocked if agents assume `.201` is mandatory, and equally blocked if they invent a different host without inventory. - -Product locks (hybrid, bdft, Woo safety) are independent of this gap and already in-repo. - ---- - -### Recommended next doc patches when CoS lifts HOLD - -Docs only. No scaffold or code. Do not reopen hybrid, Woo, or bdft locks. - -1. **Env-agnostic deploy cut (run-host unblocker).** Per `/workspace/slabuploader-env-agnostic-doc-outline.md`: - - `AGENTS.md` section 9 becomes inventory-first + `https://${APP_HOSTNAME}/api/health`. Lab example is a callout only. - - `docs/DEPLOYMENT.md` title/target/section 1 point at `deploy/INVENTORY.md` worksheet. Caddy uses `${APP_HOSTNAME}`. Fix handle order (W10). Drop RemBG SoT smell (W9). - - `README.md` deploy line. PRD FR42 / deploy bullets. `IMPL-PLAN` Gate B / Phase 6 / Risks / DoD host wording. -2. **OPENAPI one-liners (B1, W1).** PUT does not recompute source of truth. POST returns `calibrated`. -3. **AGENTS TV-10 (W2).** Require TV-1 through TV-10. -4. **IMPL-PLAN Phase 1 (B2).** Kill `processing` to `ready`. Hybrid CRUD/store language. -5. **IMPL-PLAN Phase 2 (B3).** Replace body with deferred stub. -6. **IMPL-PLAN Phase 6 + Risks (B4, W9).** Online UAT only. No OCR/offline/server-normalization budgets. No `output_px` to 1000. -7. **CONTENT-WOO (W4, W5, W11).** PNG media. fig-*/feat-* assign. No calibration photos. -8. **DATA-MODEL / OPENAPI settings (W3, N1).** Drop server sheet prefs (or defer). Say "client" not "PWA". -9. **PRD leftovers (W6 to W8, N2).** FR17 feat-*. FR19 species-only. FR40/NFR hybrid wording. Pricing schema. -10. **Refresh workspace review package.** Mark Appendix C items 1 to 7 done. Keep item 0 plus sign-off for env-agnostic only. - -After patches: one docs commit on gitea-atd, report SHA to CoS, then run-host inventory on the designated host. Still no silent `.201` assumption. - ---- - -### Audit verdict - -The docs freeze did land the critical product locks: hybrid, bdft, AES, Woo draft/`SLAB-UAT-*`, Phase 0 rewrite, AGENTS precedence. Scaffolding run-host math/AES/health is safe if agents obey AGENTS + TECH-SPEC + Phase 0. - -Run-host deploy, and any agent that reads IMPL Phase 1/2/6, OPENAPI PUT, or PRD FR40/NFR without the precedence discipline, will still ship the wrong architecture: server recompute, `processing` status, offline/OCR/ruler, JPEG without alpha, hard-coded `.201`. - -Highest-ROI doc fixes when HOLD lifts: (1) env-agnostic deploy, (2) OPENAPI "re-runs derived math", (3) gut IMPL Phase 2/6 stale bodies, (4) Phase 1 status machine. diff --git a/docs/TECH-SPEC-PIPELINE.md b/docs/TECH-SPEC-PIPELINE.md index 322da72..62bbcd1 100644 --- a/docs/TECH-SPEC-PIPELINE.md +++ b/docs/TECH-SPEC-PIPELINE.md @@ -1,7 +1,7 @@ # Technical Spec: Deterministic Image Pipeline & Area → Bdft -Status: SPEC · 2026-08-27 · TyTech / SlabUploader -Scope: PRD deliverable #1 — algorithms and test vectors for the deterministic core. +Status: SPEC · 2026-08-27 · Gate A freeze 2026-08-31 · TyTech / SlabUploader +Scope: algorithms and test vectors for the deterministic core (client-authoritative). No inference, no LLM. Everything here is a pure function of (pixels, user inputs) → outputs. Inference, Woo payload, API, and schema live in other docs. @@ -216,4 +216,4 @@ Price 12.345 → **12.35**. | HTTP contract | OpenAPI | | Client vs server topology | Architecture | | Auto-dimension overlay, figure-weighted price | Impl plan (v1.5) | -| Offline capture | PRD non-goal | +| Offline capture | non-goal (online-only POC; see AGENTS) | diff --git a/Slab capture app PRD.txt b/docs/archive/PRD-2026-08.txt similarity index 95% rename from Slab capture app PRD.txt rename to docs/archive/PRD-2026-08.txt index 4d85944..5083f8e 100644 --- a/Slab capture app PRD.txt +++ b/docs/archive/PRD-2026-08.txt @@ -1,3 +1,21 @@ +# ARCHIVED — not a source for new work + +Frozen 2026-08-31. Historical product requirements only. +Superseded by AGENTS.md + docs/ARCHITECTURE.md + docs/TECH-SPEC-PIPELINE.md + +docs/DATA-MODEL.md + docs/CONTENT-WOO.md + docs/IMPL-PLAN.md (+ OPENAPI, PROMPTS, DEPLOYMENT). + +Non-authoritative if they conflict with the files above: +- FR17 tag wording (locked model is fig-* 1+ and feat-* 0+) +- FR19 / overview category-weighted pricing (species $/bdft only in POC) +- FR40 server-side processing +- NFR server normalization timing +- FR42 host .201 binding (env-agnostic DEPLOYMENT + deploy/INVENTORY.md) +- Any line listed under AGENTS.md "Known stale" + +Do not implement from this file. Agents: start at AGENTS.md. + +--- + # Slab Capture & WooCommerce Publishing App — PRD ## Overview