Ty_Tech/SlabUploader
6
0
Fork 0
Code Issues 15 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f3117c790566bfa76126a1632f29e39ee903432a
SlabUploader/docs/process/overnight-docs-refactor/proposal-v2.md
T

16 KiB
Raw Blame History

SlabUploader docs refactor: proposal v2 (post-interrogate)

Status: PROPOSAL v2. Not a rewrite. No repo files changed by this document. SoT: Gitea Ty_Tech/SlabUploader on gitea-atd. Date: 2026-09-01. Basis: /workspace/slabuploader-docs-refactor-proposal.md revised for Act-on findings in /workspace/slabuploader-docs-refactor-interrogate.md. Panel that forced the revision: composer-2.5, DpBlu-Qwen3.6-27b, UbuDual-Qwen3.8-27b, grok-composer-2.5-fast (all four completed).

1. Executive summary for Ty

Direction from v1 stands: deletion-first cleanup, one Diataxis mode per file, one home per locked decision, product locks unchanged.

v1 is not sign-off ready. Four-model interrogate blocked it for structural execution bugs, not for wrong product intent.

v2 changes the execution rules:

  1. AGENTS.md stays the agent working contract. Hard locks stay verbatim. Pointers add depth; they do not replace lock text.
  2. Named SoT hierarchy for Woo safety and secrets (agent-facing policy vs schema vs payload).
  3. Gate C hybrid capture slice is written before Phase 2 body delete.
  4. IMPL Phases 3–5 + Risks get hybrid alignment or an explicit “do not implement” guard. No claim that superseded text is gone after Phase 2/6 only.
  5. PRD archive is allowed only with reference rewrite + superseded FR header (or fix W6–W8 first).
  6. Contract wrong-code lines (OPENAPI B1/W1, AGENTS/IMPL W2) land in commit 1 with greppable DoD before PM-DESIGN dies.
  7. File count and inventory worksheet are honest. Target is 10 active docs files + DEPLOYMENT-owned inventory worksheet, not “9.”

Nothing here reopens: hybrid client math, bdft = sqft × thickness_in, AES-GCM server secrets, Woo draft + SLAB-UAT-*, inference OFF until first draft listing, gates A/B/C meaning, env-agnostic deploy.

2. What v1 got right (kept)

  • Stale IMPL Phase 2 offline/OCR/ruler body and Phase 6 offline UAT must go.
  • Phase 1 must not invent processing → ready.
  • OPENAPI PUT must not recompute client math as SoT; POST calibrated wording must match status machine.
  • DEPLOYMENT must become env-agnostic per /workspace/slabuploader-env-agnostic-doc-outline.md.
  • TECH-SPEC and DATA-MODEL structure stay; no churn for purity.
  • PM-DESIGN-ALIGNMENT is a reconciliation artifact and should not live forever.
  • Docs only. No code, schema migration, run-host work, commit, or push in the design pass.

3. v1 defects fixed in v2 (Act-on map)

ID Defect v2 rule
A1 Slim AGENTS to pointers drops locks Verbatim hard-rules block retained
A2 Woo dual-SoT AGENTS = policy; CONTENT-WOO = payload cites AGENTS
A3 Secrets SoT = DATA-MODEL AGENTS policy; ARCHITECTURE why; DATA-MODEL keys only
A4 PRD archive orphans references Same-commit reference rewrite
A5 W6–W8 “applied” by silence Superseded header or fix-before-archive; PM delete gated
A6 Phase 2 delete leaves Gate C homeless Write Gate C slice first
A7 Phases 3–5 still stale Hybrid-align or keep AGENTS guard
A8 W2 TV-10 unscheduled Mandatory AGENTS + IMPL Phase 0 edit
A9 Deletion-first overclaim / B1 late Commit 1 = B1/W1/W2 + IMPL wrong-code deletes
A10 Gate table only in PM-DESIGN Copy into AGENTS before PM delete
A11 No docs DoD Greppable acceptance section
A12 “9 files” false; INVENTORY missing Recount; map inventory under DEPLOYMENT
A13 AGENTS known-stale FR4 false Rewrite known-stale against HEAD

4. Target design

4.1 File list and modes

File Mode Owns v2 change vs today
README.md explanation Orientation, remotes, POC bar, where to read next Drop duplicate “what” table bloat; deploy line env-agnostic; PRD row → archive path when moved
AGENTS.md reference (agent contract) Verbatim hard rules + Gate A/B/C table + test/delivery + short precedence while copies remain Add pointers beside locks; never replace locks; rewrite known-stale; absorb gate table + open-doc-defects until clear
docs/TECH-SPEC-PIPELINE.md reference Math + image prep + TV-1…TV-10 Status bump only; no structural rewrite
docs/ARCHITECTURE.md explanation and normative topology reference Hybrid split, swimlane, what-runs-where, secrets why, status transitions explained Keep tables; fix “Remaining sections TBD” (N3); secrets detail points to DATA-MODEL keys, policy stays here + AGENTS
docs/DATA-MODEL.md reference Schema, status enum, settings keys Drop server sheet/slider prefs (W3); “client” not “PWA” (N1); not the never-browser policy home
docs/OPENAPI.md reference HTTP contract B1 PUT store-only; W1 POST calibrated and examples; N1 PWA wording
docs/CONTENT-WOO.md reference Templates, Woo payload, dedupe, publish logging W4 PNG; W5 fig-/feat-*; W11 no calibration photos; attributes = five locked attrs not species/character/length as attrs; cite AGENTS for SLAB-UAT force-draft
docs/PROMPTS.md reference Call 1/2 files, inputs, reset-to-default Keep short tuning note in-file (no split for POC)
docs/DEPLOYMENT.md how-to Env-agnostic playbook APP_HOSTNAME / inventory; corrected Caddy handle /api/* then frontend handle; drop RemBG/ruler/1000px SoT (W9); W10
docs/IMPL-PLAN.md how-to Phases + exit gates, hybrid-only Gate C slice with capture+draft listing; stub Phase 2 deferred; kill processing; hybrid-align 3–5 + Risks; Phase 6 online UAT only; TV-1…TV-10 in Phase 0
deploy/INVENTORY.md how-to worksheet Host inventory filled at Gate B Created empty/template when DEPLOYMENT goes env-agnostic; owned by DEPLOYMENT, not a second product spec
docs/archive/PRD-2026-08.txt frozen record Historical PRD Move + superseded header listing non-authoritative FRs; or fix W6–W8 before freeze

Active count: 10 docs surfaces (README, AGENTS, 8 under docs/ excluding archive) + inventory worksheet. Plus archived PRD. Not “9.”

Delete after DoD green: docs/PM-DESIGN-ALIGNMENT.md (reconciliation body). Preserve freeze provenance by lifting SHA-to-lock summary into AGENTS or a one-screen freeze note inside AGENTS.

4.2 Ownership hierarchy (single home, typed)

Decision Normative home Depth / implementation home Others
Math, crop, no-upscale, TV vectors TECH-SPEC — AGENTS verbatim summary + pointer
Hybrid what-runs-where ARCHITECTURE — AGENTS verbatim summary + pointer
Schema columns, status enum, settings keys DATA-MODEL OPENAPI shapes Pointers only
HTTP behavior OPENAPI — Pointers
Woo payload / templates / publish sequence CONTENT-WOO — —
Woo safety policy (SLAB-UAT-* force draft, UAT draft default, no edit-same-SKU, purge-after-publish) AGENTS CONTENT-WOO cites AGENTS; DATA-MODEL has woo_create_status key README one-liner OK
Secrets never-browser / AES / SLAB_AES_KEY env AGENTS ARCHITECTURE why/flow; DATA-MODEL key list —
Inference sequencing (OFF until Gate C; Call 2 manual) AGENTS PROMPTS file mechanics; ARCHITECTURE call placement —
Gate A/B/C human map AGENTS IMPL-PLAN phase mapping —
Build phases / acceptance IMPL-PLAN — AGENTS gate map + “incomplete rewrite” guard until 1+ clean
Deploy ops DEPLOYMENT (+ inventory worksheet) — AGENTS deploy sketch points here
Product orientation README — —

4.3 AGENTS verbatim hard-rules block (non-negotiable list)

Keep short full sentences in AGENTS for all of:

  • Hybrid: client owns happy-path math/mask/PNG; server stores, Woo, inference proxy, on-demand U2Net
  • bdft = sqft × thickness_in (no /12)
  • No fake upscale; <1600 after crop → warn + retake
  • Do-not-build table (offline PWA, OCR, ruler, server happy-path pipeline, etc.)
  • Secrets never in browser storage or JS bundles; AES-GCM server; SLAB_AES_KEY env only
  • Woo UAT: draft default; SLAB-UAT-* force draft; real publish only after Ty review; duplicate SKU stops
  • Inference OFF for full suite and Gate C; Call 1/2 after Gate C still inside POC; Call 2 never auto
  • Status machine names: draft → calibrated → ready → publishing → published | failed (not Woo draft)
  • Gate table A/B/C
  • Test/delivery: no feature without passing test + shown output; deterministic core unit-tested first
  • TV-1 through TV-10 required
  • While IMPL 1+ rewrite incomplete: implement only Phase 0 + sections explicitly marked rewritten

Pointers after each block are encouraged. Replacing any bullet with only a link is forbidden.

4.4 IMPL-PLAN hybrid shape (Gate C home)

Phase 0 (unchanged intent): Gates A+B; client TECH-SPEC modules; thin FastAPI health/settings; TV-1…TV-10.

Early Phase 1 / Gate C slice (must exist as real deliverables before Phase 2 stub):

  • Online capture 1–5 photos (no OCR/ruler/offline)
  • Client sheet/sliders, mask confirm, length axis confirm
  • Client sqft/bdft/widths; calibrated draft upload (server stores client numbers)
  • Manual SKU/length/thickness/taxonomy as needed for one listing
  • Woo draft create with SLAB-UAT-* on configured store; inference OFF
  • Exit: one draft listing Ty can open in Woo admin

Phase 1 remainder: broader API/settings/taxonomy cache as needed; no processing status; no server happy-path math SoT.

Phase 2: deferred stub only (offline PWA / OCR / ruler). No airplane-mode acceptance.

Phases 3–5: rewrite enough to match hybrid + all-photos@1024 Call 1 + inference after Gate C. Remove top-down-only vision SoT and offline-era assumptions. Confidence threshold 0.7 (from PRD FR22a / current Phase 5) moves here or PROMPTS deliberately.

Phase 6: online UAT only; env-agnostic host; no OCR/offline/server-normalization budgets; no output_px→1000; no ruler risk row as SoT.

4.5 PRD disposition (v2)

Recommend archive to docs/archive/PRD-2026-08.txt with:

Frozen 2026-08-31. Not a source for new work.
Superseded by AGENTS + ARCHITECTURE + TECH-SPEC + DATA-MODEL + CONTENT-WOO + IMPL-PLAN.
Non-authoritative if they conflict: FR17 tag wording, FR19 category-weighted pricing,
FR40 server-side processing, NFR server normalization timing, FR42 host .201 binding,
and any line AGENTS known-stale still lists.

Same commit must update AGENTS, README, ARCHITECTURE companion, TECH-SPEC scope, IMPL DoD language, CONTENT-WOO FR cites.

Alternate: fix W6–W8/FR42 in PRD then archive with a shorter header. Do not archive unedited without the non-authoritative list.

4.6 PM-DESIGN-ALIGNMENT deletion gate

Delete only when all are true:

  1. Docs DoD greps green (section 6).
  2. Gate A/B/C table lives in AGENTS.
  3. Freeze SHA-to-lock one-liner or small table lifted into AGENTS.
  4. Residual open items (if any) listed under AGENTS “open doc defects,” not only in chat.
  5. PRD archive/reference step done or PRD fixed in place.

Until then keep the file or a trimmed “open defects” section. Do not delete on hope.

5. Migration order (v2)

Honest label: wrong-code-first, then deletes, then env-agnostic add, then de-dupe. Not pure deletion-first.

Commit 1 — Stop wrong code if followed

  1. OPENAPI: PUT stores client-sent derived fields (no recompute as SoT). POST returns calibrated. Update examples too (W1).
  2. AGENTS + IMPL Phase 0: TV-1 through TV-10 (W2).
  3. IMPL: remove processing; write Gate C hybrid capture+draft-listing slice; stub Phase 2 deferred; strip Phase 6 offline/OCR/server-normalization UAT; start Risks cleanup (W9).
  4. AGENTS: fix known-stale list vs HEAD (drop false FR4 /12 warning).

Checkpoint: safe for agents on contract + Phase 0/Gate C docs. Still may have duplicate prose elsewhere.

Commit 2 — Env-agnostic deploy

  1. DEPLOYMENT + AGENTS §9 + README + IMPL host wording per env outline.
  2. Add deploy/INVENTORY.md template.
  3. Corrected Caddy fragment (handle /api/* then frontend handle).
  4. Drop RemBG/ruler/1000px as deploy SoT.

Commit 3 — Factual fixes in place

  1. CONTENT-WOO: W4, W5, W11, attributes bullet (C4), cite AGENTS for safety policy.
  2. DATA-MODEL / OPENAPI: W3 sheet prefs out of server settings; N1 client not PWA.
  3. ARCHITECTURE: N3 status line; keep topology tables.
  4. IMPL Phases 3–5 hybrid alignment (or AGENTS guard left on if partial).

Commit 4 — De-dupe and archive

  1. README/ARCHITECTURE/CONTENT-WOO: replace long restatements with pointers where AGENTS/TECH-SPEC already state the lock (locks remain in AGENTS).
  2. Archive PRD with header + rewrite all live references.
  3. Copy Gate table + freeze provenance into AGENTS if not already.
  4. Run DoD (section 6). Delete PM-DESIGN only if green.

Each commit is reviewable. Agent-safe checkpoints: after commit 1, after commit 3, after commit 4. Do not hand a half-finished commit 4 tree to implementers.

6. Docs refactor definition of done

Run from repo root after the last commit. All must pass before Ty treats the cleanup as done.

Wrong-code absences (active docs, not archive):

  • No re-runs derived math / “server re-runs derived” on slab PUT.
  • No IMPL acceptance requiring offline capture, airplane mode, Tesseract OCR, or OpenCV ruler for POC.
  • No IMPL processing→ready as a slab status.
  • No DEPLOYMENT normative SoT that RemBG/ruler/output_px 1000 define the happy path.
  • No CONTENT-WOO “JPEG bytes” as processed listing media SoT (PNG).
  • No active AGENTS line claiming PRD FR4 still uses /12 if PRD FR4 is already correct.

Lock presences in AGENTS (verbatim):

  • bdft identity / no /12
  • never browser secrets / AES-GCM / SLAB_AES_KEY
  • SLAB-UAT-* force draft
  • inference OFF until Gate C
  • Gate A / Gate B / Gate C table rows
  • TV-1 through TV-10
  • hybrid client math SoT one-liner

Structural:

  • Gate C slice exists in IMPL with capture + Woo draft listing exit.
  • PRD either absent from active paths or only under docs/archive/ with superseded header; README/AGENTS/ARCHITECTURE do not point at a missing root PRD path.
  • deploy/INVENTORY.md exists when DEPLOYMENT claims it.
  • PM-DESIGN-ALIGNMENT deleted only with DoD green + provenance relocated.

Optional smoke: rg for SLAB-UAT in AGENTS and CONTENT-WOO; CONTENT-WOO must cite AGENTS for force-draft policy rather than diverging.

7. What stays locked (do not reopen)

Hybrid topology; bdft = sqft × thickness_in; AES-GCM server secrets never in browser; Woo draft + SLAB-UAT-* force-draft; inference OFF for first claimable publish; Call 1/2 after Gate C still inside POC; Gate A docs freeze / Gate B run-host / Gate C first draft listing; env-agnostic deploy direction; online-only POC.

8. Non-goals

  • No code, schema migrations, scaffold, or run-host inventory execution in this design pass.
  • No TECH-SPEC or DATA-MODEL structural rewrite.
  • No Diataxis split of PROMPTS tuning or CONTENT-WOO short publish list for POC.
  • No product lock renegotiation.
  • No commit/push until Ty signs this v2 (or a successor).
  • N5 workspace review-package hygiene stays out of repo commits.

9. Open questions for Ty (max 3)

  1. PRD: Archive with strong superseded header (recommended), or fix W6–W8/FR42 in place then archive?
  2. PM-DESIGN: Delete after DoD green with provenance in AGENTS (recommended), or keep a trimmed open-defects file until Gate C is green?
  3. IMPL 3–5: Full hybrid rewrite in the same docs stack as Phase 2/6 cleanup (recommended for less guard complexity), or minimal wrong-path deletes + AGENTS “incomplete rewrite” guard until a later commit?

10. Consider-class items folded or deferred

Item v2 handling
W1 examples Folded into commit 1
CONTENT-WOO attributes Folded into commit 3
Corrected Caddy fragment Folded into commit 2 target text
ARCHITECTURE normative topology Folded into §4.1
FR42 vs archive Open Q1
Confidence 0.7 relocate Folded into Phase 5 / PROMPTS note in §4.4
Step-4 split Folded into commits 3–4
N5 workspace Non-goal

11. No repo writes confirmed

This v2 document lives at /workspace/slabuploader-docs-refactor-proposal-v2.md only. Interrogate verdict at /workspace/slabuploader-docs-refactor-interrogate.md. Original v1 left in place for audit. No changes under /workspace/gitea-atd/Ty_Tech/SlabUploader/. No git commit. No push.

Reference in New Issue View Git Blame Copy Permalink