Purge docs/process/overnight-docs-refactor/ — leftover process docs, not SoT
This commit is contained in:
@@ -1,14 +0,0 @@
|
||||
# Overnight docs refactor (2026-09-01)
|
||||
|
||||
Process artifacts from the CoS / Grok Build / PPM / Dev Manager pass.
|
||||
Not product SoT. Live product docs are AGENTS.md and files under `docs/` (except this folder).
|
||||
|
||||
| File | What |
|
||||
|---|---|
|
||||
| morning-plan.md | Founder briefing |
|
||||
| proposal-v2.md | Execution plan after interrogate |
|
||||
| interrogate-verdict.md | Four-model review |
|
||||
| execution-status.md | Commits + DoD |
|
||||
| ppm-notes.md | Principal PM alignment |
|
||||
| dm-notes.md | Dev Manager alignment |
|
||||
| proposal-v1.md | First (blocked) proposal, if present |
|
||||
@@ -1,66 +0,0 @@
|
||||
# Morning notes for Ty — docs refactor v2 (Dev Manager)
|
||||
|
||||
Date: 2026-09-01 (before morning PT)
|
||||
Read: `/workspace/slabuploader-docs-refactor-proposal-v2.md` + `/workspace/slabuploader-docs-refactor-interrogate.md`
|
||||
Branch check: `docs/refactor-v2` tip = `main` @ `e1e087b` (PM-DESIGN unslop only). **v2 commits 1–4 are not on the branch yet** — these notes judge the *proposal*, not a landed stack.
|
||||
Constraints honored: no Gate B / host inventory; main not touched by this pass.
|
||||
|
||||
---
|
||||
|
||||
## 1. Are Gate C slice + env-agnostic deploy + OPENAPI B1/W1 enough?
|
||||
|
||||
**Short answer: almost — for architecture. Not for a green “hand to coding agents” flag.**
|
||||
|
||||
| After… | Agents stop shipping wrong *architecture*? | Still broken if they follow leftover text |
|
||||
|---|---|---|
|
||||
| **Commit 1 only** (B1/W1 + Gate C slice + kill `processing` + Phase 2 stub + Phase 6 offline strip + TV-10 + AGENTS known-stale rewrite) | **Mostly yes**, *if* AGENTS keeps the “IMPL 1+ incomplete — implement only Phase 0 + rewritten sections” guard until Phases 3–5 are cleaned | CONTENT-WOO JPEG→lose alpha; PRD FR19 category pricing / FR40 server processing if still live; Phase 3–5 top-down vision / offline flavor; `.201` hard-coding (deploy, not architecture) |
|
||||
| **+ Commit 2** (env-agnostic + `deploy/INVENTORY.md` + Caddy handle order) | Architecture same; **Gate B framing** becomes safe | Same feature landmines as above |
|
||||
| **+ Commit 3** (CONTENT-WOO / DATA-MODEL / ARCHITECTURE / IMPL 3–5) | **Yes — this is the real agent-safe checkpoint** | Nits / archive hygiene |
|
||||
| **+ Commit 4** (de-dupe, PRD archive, PM-DESIGN delete after DoD) | Hygiene / reader load; not required to unblock scaffold | — |
|
||||
|
||||
**Recommendation:** Do not unleash coding agents on Gate B scaffold until **commit 1 is on the branch and grepped**. Do not unleash feature agents (capture/Woo/inference UI) until **through commit 3**. Env-agnostic (commit 2) can land with or right after commit 1; it does not by itself stop wrong architecture.
|
||||
|
||||
Gate C slice **before** Phase 2 delete is non-negotiable (interrogate A6). v2 has that right. B1 alone without Gate C still leaves capture homeless.
|
||||
|
||||
---
|
||||
|
||||
## 2. Deploy / IMPL landmines v2 still misses or underweights
|
||||
|
||||
v2 covers the big ones (B1, processing, Phase 2/6, env-agnostic, Caddy order, RemBG/1000px, TV-10, Gate C home). Add or keep visible:
|
||||
|
||||
1. **OPENAPI dedupe language** — “SKU already **published**” should mean “SKU already **exists in Woo** (any status).” Else agents skip draft collisions.
|
||||
2. **Confidence 0.7 (FR22a)** — v2 folds into Phase 5/PROMPTS; make that an explicit commit-3 checklist line so it does not die with PRD archive.
|
||||
3. **IMPL Phase 1 remainder** — after Gate C slice, leftover “sandbox Woo / pending-era” sentences in Phase 1 body still need a one-pass scrub or they reintroduce wrong publish defaults next to the new slice.
|
||||
4. **Compose↔Caddy service names** — fragment must match compose service name (`fastapi`) *and* sit on the same Docker network; design text should say that in commit 2, not only handle order.
|
||||
5. **Partial Woo failure / orphan media** — ops note, not architecture; keep in CONTENT-WOO/IMPL Risks so agents do not invent auto-delete of Woo media.
|
||||
6. **Do not treat workspace `/workspace/*.md` as SoT** — already true; worth one AGENTS line when env-agnostic lands so agents do not read proposal files as repo authority.
|
||||
|
||||
Nothing here reopens product locks.
|
||||
|
||||
---
|
||||
|
||||
## 3. Commit staging feedback (v2 commits 1–4)
|
||||
|
||||
**Order is correct.** Wrong-code-first → env-agnostic → factual → de-dupe/archive matches how agents fail. Keep it.
|
||||
|
||||
| Commit | Staging feedback |
|
||||
|---|---|
|
||||
| **1** | Keep **atomic**: OPENAPI B1+W1 **including examples**, Gate C slice, Phase 2 stub, `processing` gone, Phase 6 offline strip, TV-10, AGENTS stale-list rewrite. Do **not** ship a HEAD where Phase 2 body is deleted without Gate C written. Prefer one commit; if split, Gate C + Phase 2 stub must move together. |
|
||||
| **2** | Fine as second. Unblocks Gate B *framing* only — still no inventory/SSH until you open Gate B. Include corrected Caddy fragment + empty `deploy/INVENTORY.md` template in the same commit DEPLOYMENT claims them. |
|
||||
| **3** | Highest ROI after 1 for “agents won’t follow stale Phase 5.” Prefer full hybrid-align of Phases 3–5 here (agree with PPM) over a long incomplete-rewrite guard. |
|
||||
| **4** | Last. PRD archive + reference rewrite same commit. PM-DESIGN delete **only** after DoD greps green + Gate table + freeze provenance in AGENTS. |
|
||||
|
||||
**Agent-safe checkpoints (for CoS/you):** after 1 (docs contract); after 3 (feature docs); after 4 (cleanup done). Do not hand implementers a mid-commit-4 tree.
|
||||
|
||||
**Branch reality check:** overnight commits 1–4 are **not** on `docs/refactor-v2` yet (tip = `e1e087b`). Morning decision is “sign v2 proposal / open execution on that branch,” not “review four landed commits.”
|
||||
|
||||
---
|
||||
|
||||
## Bottom line for Ty
|
||||
|
||||
1. **Sign v2 direction** (not v1). Product locks stay put.
|
||||
2. **Execute commit 1 first** on `docs/refactor-v2` — that is what stops the worst wrong architecture.
|
||||
3. **Coding agents:** after commit 1 for Phase 0/contract only; after commit 3 for capture/Woo/inference work. **Still no Gate B host work** until you explicitly open it.
|
||||
4. Open Qs: I align with PPM — archive PRD with superseded header; delete PM-DESIGN after DoD; hybrid-align IMPL 3–5 in commit 3.
|
||||
|
||||
Dev Manager standing by under HOLD for Gate B / unrelated main writes.
|
||||
@@ -1,115 +0,0 @@
|
||||
# SlabUploader docs refactor v2 — execution status
|
||||
|
||||
Date: 2026-09-01
|
||||
Branch: `docs/refactor-v2` @ `779fa7d`
|
||||
Remote: origin (gitea-atd `Ty_Tech/SlabUploader`)
|
||||
main: `e1e087b` (untouched; no merge)
|
||||
|
||||
Author/committer for all four commits: `grokbot_ty <grokbot_ty@gitea.local>` via env only.
|
||||
|
||||
---
|
||||
|
||||
## Commits (section 5 order)
|
||||
|
||||
| # | Full SHA | Subject | Pushed |
|
||||
|---|---|---|---|
|
||||
| 1 | `48720d83e1ae33d637c75b182110ba1b6d455483` | docs: stop wrong-code paths (OPENAPI store-only, Gate C, TV-10) | yes |
|
||||
| 2 | `369d404c29bee0e8cd67bf44fa5bf35ae7768b75` | docs: env-agnostic deploy (APP_HOSTNAME, inventory, Caddy order) | yes |
|
||||
| 3 | `3ac5e36dc3c73148d81640d7d94252db8c1dfef8` | docs: factual CONTENT-WOO/DATA-MODEL fixes + hybrid Phases 3-5 | yes |
|
||||
| 4 | `779fa7d484c325d4a3675698d7723a9dc497c3a5` | docs: archive PRD, gate map in AGENTS, drop PM-DESIGN | yes |
|
||||
|
||||
No no-op commits. All four had real diffs.
|
||||
|
||||
CoS open-question defaults applied:
|
||||
|
||||
1. PRD archived with strong superseded header
|
||||
2. PM-DESIGN deleted only after DoD green + provenance in AGENTS
|
||||
3. IMPL Phases 3–5 hybrid-aligned in commit 3 (not guard-only)
|
||||
|
||||
---
|
||||
|
||||
## DoD (proposal §6) — PASS
|
||||
|
||||
### Wrong-code absences (active docs, not archive)
|
||||
|
||||
| Check | Result |
|
||||
|---|---|
|
||||
| No `re-runs derived math` / server re-runs derived on slab PUT | PASS (OPENAPI store-only language) |
|
||||
| No IMPL acceptance requiring offline capture, airplane mode, Tesseract, OpenCV ruler for POC | PASS (Phase 2 deferred stub only; Phase 6 says no offline UAT cases) |
|
||||
| No IMPL `processing→ready` as slab status | PASS |
|
||||
| No DEPLOYMENT normative RemBG / ruler / `output_px` 1000 happy path | PASS |
|
||||
| No CONTENT-WOO “JPEG bytes” as processed listing media SoT | PASS (PNG bytes) |
|
||||
| No active AGENTS line claiming PRD FR4 still uses `/12` | PASS |
|
||||
|
||||
Note: Phase 2 stub still *names* Tesseract/OpenCV/airplane as **out of scope**. That is not acceptance. DoD greps that treat any mention as failure are false positives.
|
||||
|
||||
### Lock presences in AGENTS (verbatim)
|
||||
|
||||
| Lock | Result |
|
||||
|---|---|
|
||||
| bdft identity / no `/12` | PASS |
|
||||
| never browser secrets / AES-GCM / `SLAB_AES_KEY` | PASS |
|
||||
| `SLAB-UAT-*` force draft | PASS |
|
||||
| inference OFF until Gate C | PASS |
|
||||
| Gate A / B / C table rows | PASS (§0b) |
|
||||
| TV-1 through TV-10 | PASS |
|
||||
| hybrid client math SoT one-liner | PASS (Client owns happy path) |
|
||||
|
||||
### Structural
|
||||
|
||||
| Check | Result |
|
||||
|---|---|
|
||||
| Gate C slice in IMPL (capture + Woo draft listing exit) | PASS |
|
||||
| PRD only under `docs/archive/` with superseded header; no root PRD path | PASS |
|
||||
| README / AGENTS / ARCHITECTURE do not point at missing root PRD | PASS |
|
||||
| `deploy/INVENTORY.md` exists | PASS |
|
||||
| Freeze provenance in AGENTS | PASS (§0b) |
|
||||
| Open doc defects section | PASS (none listed) |
|
||||
| PM-DESIGN-ALIGNMENT deleted | PASS (DoD green first) |
|
||||
| CONTENT-WOO cites AGENTS for force-draft | PASS |
|
||||
|
||||
### Optional smoke
|
||||
|
||||
- `SLAB-UAT` present in AGENTS and CONTENT-WOO
|
||||
- CONTENT-WOO defers safety policy to AGENTS §5
|
||||
|
||||
---
|
||||
|
||||
## File map after tip
|
||||
|
||||
Active:
|
||||
|
||||
- `README.md`, `AGENTS.md`
|
||||
- `docs/ARCHITECTURE.md`, `TECH-SPEC-PIPELINE.md`, `DATA-MODEL.md`, `OPENAPI.md`, `CONTENT-WOO.md`, `PROMPTS.md`, `DEPLOYMENT.md`, `IMPL-PLAN.md`
|
||||
- `deploy/INVENTORY.md`
|
||||
|
||||
Archive:
|
||||
|
||||
- `docs/archive/PRD-2026-08.txt`
|
||||
|
||||
Deleted:
|
||||
|
||||
- `docs/PM-DESIGN-ALIGNMENT.md`
|
||||
|
||||
---
|
||||
|
||||
## Residual (non-DoD)
|
||||
|
||||
From DM morning notes; not required to claim cleanup done:
|
||||
|
||||
1. OPENAPI duplicate SKU language still says “already published” in places; preferred “exists in Woo (any status).”
|
||||
2. Caddy fragment could explicitly say frontend and fastapi share the compose network (handle order already fixed).
|
||||
3. Gate B host inventory still held for Ty; docs only.
|
||||
|
||||
---
|
||||
|
||||
## main safety
|
||||
|
||||
```
|
||||
main: e1e087b
|
||||
docs/refactor-v2: 779fa7d
|
||||
origin/main: e1e087b
|
||||
origin/docs/refactor-v2: 779fa7d
|
||||
```
|
||||
|
||||
No commit to main. No merge to main.
|
||||
@@ -1,288 +0,0 @@
|
||||
# SlabUploader docs refactor: interrogate verdict
|
||||
|
||||
Status: ADVERSARIAL REVIEW complete. No repo files changed.
|
||||
SoT repo: Gitea `Ty_Tech/SlabUploader` on gitea-atd (not TrueNAS/GitHub mirrors).
|
||||
Artifact reviewed: `/workspace/slabuploader-docs-refactor-proposal.md`
|
||||
Date: 2026-09-01.
|
||||
Process: pstack interrogate skill by the book (intent → one reviewer per configured model → lead judgment → no auto-apply).
|
||||
|
||||
---
|
||||
|
||||
## Intent
|
||||
|
||||
> Propose a deletion-first docs cleanup for SlabUploader so each file has one Diataxis mode and each locked product decision has one home, without changing product locks (hybrid client math, bdft formula, server secrets, Woo draft SLAB-UAT-* safety, inference off until first draft listing, gates A/B/C, env-agnostic deploy). The prior single-model pass wrote only this proposal outside the repo. We need adversarial multi-model review before Ty signs off.
|
||||
|
||||
Reviewers challenged execution against the live evidence base. They did not reopen product locks.
|
||||
|
||||
---
|
||||
|
||||
## Reviewers (configured panel; all four ran)
|
||||
|
||||
Source of model list: `~/.grok/rules/pstack-models.md` line `interrogate reviewers`.
|
||||
|
||||
| Label | Model slug (as spawned) | Status | Findings (author count) |
|
||||
|---|---|---|---|
|
||||
| Reviewer A | `composer-2.5` | completed | 6 critical, 12 warning, 2 nit |
|
||||
| Reviewer B | `DpBlu-Qwen3.6-27b` | completed | 3 critical, 5 warning, 2 nit |
|
||||
| Reviewer C | `UbuDual-Qwen3.8-27b` | completed | 3 critical, 5 warning, 2 nit |
|
||||
| Reviewer D | `grok-composer-2.5-fast` | completed | 6 critical, 8 warning, 2 nit |
|
||||
|
||||
No subagent failures. No silent single-model fallback. Panel is complete.
|
||||
|
||||
Skill references used: `interrogate/SKILL.md`, `references/reviewer-prompt.md`, `references/rubric.md`, `references/code-quality-review.md`, `references/lead-judgment.md`.
|
||||
|
||||
---
|
||||
|
||||
## Lead judgment summary
|
||||
|
||||
**Block Ty sign-off on the original proposal as written.**
|
||||
|
||||
The deletion-first direction is right. The B1–B5 factual claims largely match live docs. The failure is execution design: over-slimming AGENTS, dual Woo SoT, secrets SoT mis-home, PRD archive without reference rewrite, Phase 2 delete without a Gate C capture home, and no docs-refactor acceptance checks.
|
||||
|
||||
A revised proposal is required before execution. See `/workspace/slabuploader-docs-refactor-proposal-v2.md`.
|
||||
|
||||
Principles that drove this judgment (poteto-mode):
|
||||
|
||||
- **Subtract Before You Add / Laziness Protocol.** Keep deletion of stale IMPL bodies and PM reconciliation. Do not delete AGENTS hard-rule text that agents need in one place.
|
||||
- **Encode Lessons in Structure.** Replace “trust the migration order” with greppable docs DoD before PM-DESIGN delete.
|
||||
- **Minimize Reader Load.** AGENTS stays the single working contract with verbatim locks; specs own depth.
|
||||
- **Prove It Works.** Lead verified contested claims against live files before categorizing.
|
||||
|
||||
---
|
||||
|
||||
## Act On
|
||||
|
||||
Findings that would block a real docs PR / Ty sign-off. Address these in proposal v2 before any repo rewrite.
|
||||
|
||||
### A1. Keep AGENTS hard rules verbatim; do not slim to pointers only
|
||||
**Models:** A, B, C, D (4/4) · **Agreement: multi-model**
|
||||
**Why it matters.** Proposal §4.1 keeps only Woo-safety and inference-sequencing verbatim and turns hybrid, bdft (no `/12`), secrets never-browser, no-upscale, and status machine into pointers. AGENTS is the file agents read first. Pointers they skip are lost locks. That fights the intent to preserve product locks for implementers.
|
||||
**Lead fix.** AGENTS keeps a compact verbatim hard-rules block for every lock. Each section may add one pointer to the depth spec. Do not replace lock sentences with links.
|
||||
|
||||
### A2. Resolve Woo-safety dual-SoT (AGENTS vs CONTENT-WOO)
|
||||
**Models:** A, B, C, D (4/4) · **Agreement: multi-model**
|
||||
**Why it matters.** §3.3 makes CONTENT-WOO the sole Woo-safety SoT while §4.1 also keeps Woo-safety verbatim in AGENTS. That recreates two normative copies after the ladder is shortened. Drift becomes unarbitrated.
|
||||
**Lead fix.** Named hierarchy: AGENTS owns the agent-facing safety hard rule (normative). CONTENT-WOO owns payload/sequence detail and cites AGENTS for force-draft / `SLAB-UAT-*`. DATA-MODEL owns the `woo_create_status` key only. One policy home, one payload home.
|
||||
|
||||
### A3. Secrets policy is not DATA-MODEL’s job
|
||||
**Models:** A, D (2/4; C related via AGENTS slim) · **Agreement: multi-model**
|
||||
**Why it matters.** DATA-MODEL lists encrypted keys and blob layout. It does not state “never in browser / JS bundles.” Calling DATA-MODEL the secrets SoT is a reachable path to a Settings UI that treats secrets like prefs.
|
||||
**Lead fix.** Split SoT: AGENTS = never-browser hard rule (verbatim); ARCHITECTURE = why/flow; DATA-MODEL = ciphertext key inventory only.
|
||||
|
||||
### A4. PRD archive must rewrite live references in the same step
|
||||
**Models:** A, B, C, D (4/4) · **Agreement: multi-model**
|
||||
**Why it matters.** Live pointers: AGENTS §0 rank 6 + known-stale FR cites, README docs table, ARCHITECTURE “Companion: PRD (root)”, TECH-SPEC scope line, IMPL “PRD acceptance”, CONTENT-WOO FR cites. Moving the file without edits leaves dangling paths and mixed “read / don’t read” instructions.
|
||||
**Lead fix.** Archive commit includes path updates, AGENTS ladder rewrite (archive path or drop rank-6), and “frozen archive only” language in README/AGENTS.
|
||||
|
||||
### A5. Do not claim W6–W8 applied if PRD is archived unedited
|
||||
**Models:** A, B, D (3/4) · **Agreement: multi-model**
|
||||
**Why it matters.** W6 (tags), W7 (species+category pricing), W8 (server-side processing / NFR normalization) live in the PRD. Archive-unedited + delete PM-DESIGN removes the map that says those lines are wrong while leaving the wrong text in-tree under `docs/archive/`.
|
||||
**Lead fix.** Archive header must list superseded FR/NFR ids as non-authoritative, **or** fix those lines before freeze. Do not delete PM-DESIGN until remaining open items are relocated to AGENTS “open doc defects” or a freeze-provenance note.
|
||||
|
||||
### A6. Gate C / hybrid capture needs an IMPL home before Phase 2 body delete
|
||||
**Models:** A, D (2/4) · **Agreement: multi-model**
|
||||
**Why it matters.** Phase 2 is the only capture-UX phase body. Banner says capture moves to early Phase 1 / Gate C. Phase 1 deliverables stay API-only. Phase 4 owns real Woo. Deleting Phase 2 without writing the hybrid Gate C slice leaves first-draft-listing with no phase that owns phone capture → mask → numbers → draft listing.
|
||||
**Lead fix.** Rewrite early Phase 1 / Gate C slice first: online hybrid capture + client TECH-SPEC UX + calibrated upload + Woo draft path (inference OFF). Then stub Phase 2 as deferred offline/OCR/ruler.
|
||||
|
||||
### A7. Keep a guard for unrewritten IMPL Phases 3–5 (or rewrite them)
|
||||
**Models:** A, D (2/4; C/B support incomplete rewrite diagnosis) · **Agreement: multi-model**
|
||||
**Why it matters.** Proposal only guts Phase 1 `processing`, Phase 2 offline, Phase 6 offline UAT. Phase 3/5 still carry old-pipeline flavor (top-down-only vision vs locked all-photos@1024, offline-era assumptions). Shortening AGENTS §0 after partial cleanup makes 3–5 look implementable.
|
||||
**Lead fix.** Same pass: hybrid-align Phases 3–5 and Risks at least enough to remove wrong-code paths, **or** keep explicit AGENTS hard rule “IMPL Phases 1+ hybrid rewrite incomplete; implement only Phase 0 + explicitly rewritten sections” until done. Do not claim “no superseded text left.”
|
||||
|
||||
### A8. Schedule W2 (TV-1…TV-10) as a must-fix
|
||||
**Models:** A, B, C, D (4/4) · **Agreement: multi-model**
|
||||
**Why it matters.** TECH-SPEC already defines TV-10 Rounding. AGENTS still says “TV-10 only after TECH-SPEC defines it.” IMPL Phase 0 acceptance still TV-1…TV-9. Target design left this as a parenthetical “confirm,” not a scheduled edit. Agents can skip rounding tests after “cleanup.”
|
||||
**Lead fix.** AGENTS §3 and IMPL Phase 0 acceptance: port TV-1 through TV-10. Mandatory in first or second docs commit.
|
||||
|
||||
### A9. Migration order: contract fixes before or with body deletes; B1 first among wrong-code lines
|
||||
**Models:** A, B, C (3/4) · **Agreement: multi-model**
|
||||
**Why it matters.** Exec summary overclaims “deletion-first prevents mid-migration misreads.” Step 1 can ship while OPENAPI still says server re-runs derived math (B1). Independently shippable steps ≠ agent-safe intermediate HEADs. Steps 2–3 are additive rewrites, so “deletion-first” is partly marketing.
|
||||
**Lead fix.** Commit 1: OPENAPI B1+W1 (endpoint + examples) + IMPL stale body deletes / Gate C slice + W2. Then env-agnostic deploy. Then factual CONTENT-WOO/DATA-MODEL fixes. Then pointer/de-dupe. AGENTS slim only in the sense of adding pointers beside verbatim rules, never instead. State safe checkpoints for agent work.
|
||||
|
||||
### A10. Gate A/B/C human table must move before PM-DESIGN delete
|
||||
**Models:** A, C (2/4) · **Agreement: multi-model**
|
||||
**Why it matters.** The only clear Gate A = docs freeze / Gate B = run-host / Gate C = first draft listing table is in PM-DESIGN §9. AGENTS has a one-liner. Deleting PM-DESIGN orphans the durable gate definitions the proposal claims AGENTS owns.
|
||||
**Lead fix.** Copy the Gate A/B/C table verbatim into AGENTS (hard rules) before delete. One place only.
|
||||
|
||||
### A11. Add docs-refactor acceptance checks (DoD)
|
||||
**Models:** A, D (2/4) · **Agreement: multi-model**
|
||||
**Why it matters.** No greps, no lock-presence list, no “when is PM-DESIGN allowed to die.” Ty cannot falsify “locks preserved.”
|
||||
**Lead fix.** Add DoD: zero `re-runs derived math`; POST/examples `calibrated` where required; zero normative airplane-mode Phase 2 acceptance; AGENTS still contains bdft no `/12`, never-browser, SLAB-UAT force-draft, inference OFF until Gate C, Gate table; no active processed-output JPEG as SoT; deploy host variables not sole `.201` norm; remaining open defects listed or closed.
|
||||
|
||||
### A12. Fix the file-count claim; place `deploy/INVENTORY.md`
|
||||
**Models:** A, D (2/4; C as nit on count) · **Agreement: multi-model**
|
||||
**Why it matters.** §4.1 table is 10 active files (README, AGENTS, 8 docs under docs/), prose says 9. Env outline adds `deploy/INVENTORY.md`. “12→9” is wrong and hides an ops artifact.
|
||||
**Lead fix.** Target count: 10 active root/docs files + optional inventory worksheet owned by DEPLOYMENT (in file map). Stop using “9” as the success metric.
|
||||
|
||||
### A13. Rewrite AGENTS §0 known-stale list against live files
|
||||
**Models:** D (1/4) on the FR4-false claim; lead elevates because verified · **Agreement: lone-model finding, lead-verified → Act on**
|
||||
**Why it matters.** Live PRD FR4 already states correct `bdft = sqft * thickness_in` and rejects `/12`. AGENTS still warns as if FR4 is wrong. That is a false landmine in the first file agents read.
|
||||
**Lead fix.** Any AGENTS edit rewrites known-stale to match HEAD (drop fixed entries; add still-true ones like FR40/W8 if PRD remains readable).
|
||||
|
||||
---
|
||||
|
||||
## Consider
|
||||
|
||||
Legitimate. Worth Ty’s attention. Not automatic blockers if A1–A13 are handled.
|
||||
|
||||
### C1. Prefer trimmed PM-DESIGN until Gate C, or extract freeze provenance
|
||||
**Models:** B, C, D (3/4) · **Agreement: multi-model**
|
||||
SHA-to-lock table and B/W index have process value through Gate B/C. Delete-after-fixes is fine only if provenance and residual open items move first. Lead leans: extract freeze provenance + open defects into AGENTS; then delete reconciliation body. Keeping a trimmed tracker until Gate C is an acceptable alternate.
|
||||
|
||||
### C2. ARCHITECTURE stays normative for topology / what-runs-where
|
||||
**Models:** A, D (2/4) · **Agreement: multi-model**
|
||||
Pure “explanation” Diataxis fights AGENTS precedence (ARCHITECTURE rank 2). Keep swimlane + what-runs-where + secrets-why as normative. DATA-MODEL keeps column enums. Do not essay-ify ARCHITECTURE.
|
||||
|
||||
### C3. W1 fix must include examples, not only the endpoint line
|
||||
**Models:** A (1/4) · **Agreement: lone-model**
|
||||
OPENAPI examples still show `"status":"draft"` for calibrated create/poll. Partial edit recreates in-file contradiction. Include in B1/W1 atomic edit (ties to A9).
|
||||
|
||||
### C4. CONTENT-WOO §2.3 attributes still wrong (unlisted landmine)
|
||||
**Models:** A (1/4) · **Agreement: lone-model; lead-verified true**
|
||||
Attributes bullet still says assign “species/character/length/thickness as product attributes.” Locked model is categories + five attributes (Edge Type, Figure, Grade, Thickness, Moisture) + fig/feat tags. Add to CONTENT-WOO fix list with W4/W5/W11.
|
||||
|
||||
### C5. Ship corrected Caddy fragment in the design, not only “fix order”
|
||||
**Models:** B (1/4) · **Agreement: lone-model; lead-verified foot-gun exists**
|
||||
Live DEPLOYMENT puts bare `reverse_proxy frontend` before `handle /api/*`. Corrected `handle /api/*` then `handle` frontend should appear in env-agnostic target text so implementers do not guess.
|
||||
|
||||
### C6. Env-agnostic vs PRD FR42 conflict needs an explicit decision
|
||||
**Models:** A, D (2/4) · **Agreement: multi-model**
|
||||
Outline wants FR42 env-agnostic. Archive wants no PRD edits. Pick one: edit FR42 before freeze, or stamp archive header that FR42 host binding is superseded by DEPLOYMENT.
|
||||
|
||||
### C7. Relocate PRD-only locks before archive (e.g. Call 1 confidence 0.7)
|
||||
**Models:** D (1/4) · **Agreement: lone-model**
|
||||
FR22a / IMPL Phase 5 threshold 0.7 is not in AGENTS/ARCHITECTURE/TECH-SPEC. If PRD becomes non-source, IMPL or PROMPTS must own it deliberately.
|
||||
|
||||
### C8. Split migration step 4 (kitchen-sink de-dupe)
|
||||
**Models:** A (1/4) · **Agreement: lone-model**
|
||||
Agree with staging: contract → IMPL hybrid → CONTENT-WOO/DATA-MODEL facts → pointer pass. Matches Open Q3 staged recommendation.
|
||||
|
||||
### C9. N5 is workspace-only; do not lump into repo nit pass
|
||||
**Models:** A (1/4) · **Agreement: lone-model**
|
||||
N5 is `/workspace` review-package hygiene. Split from N1–N4, N6.
|
||||
|
||||
---
|
||||
|
||||
## Noted
|
||||
|
||||
Valid, low urgency if Act-on lands.
|
||||
|
||||
### N1. Diataxis purity on PROMPTS tuning / CONTENT-WOO short sequence is low value for POC
|
||||
**Models:** A · Leave short lists in place. Do not spend design capital on mode splits.
|
||||
|
||||
### N2. “Banners are the root cause” underplays unfinished Phase 1+ rewrite
|
||||
**Models:** A · Reframe: stale normative bodies are the disease; ladder/banners are temporary PPE. Covered by A7.
|
||||
|
||||
### N3. N3 ARCHITECTURE “Remaining sections TBD”
|
||||
**Models:** B · Already in original proposal target row. Keep in same ARCHITECTURE cleanup pass.
|
||||
|
||||
### N4. W2 mislabel “AGENTS W2”
|
||||
**Models:** C, D · Cite as PM-audit W2. Cosmetic.
|
||||
|
||||
### N5. File-count vanity metric
|
||||
**Models:** C · Covered by A12.
|
||||
|
||||
### N6. DATA-MODEL orphaned user-pref rows on deployed hosts
|
||||
**Models:** B · Docs-only POC; no evidence of deployed settings rows yet. Mention as future migration note only if schema already shipped.
|
||||
|
||||
---
|
||||
|
||||
## Dismissed
|
||||
|
||||
### D1. “Single commit only” as the only safe migration shape
|
||||
**Models:** B (partial) · Staged commits are fine if each checkpoint is monotonically safer and DoD greps gate PM delete. Forbidding stages fights reviewability (Open Q3). Rejected as absolute requirement; accepted as “no unsafe intermediate for agents without a checkpoint label.”
|
||||
|
||||
### D2. Delete PRD outright instead of archive (as mandatory)
|
||||
**Models:** C preference · Archive is fine **if** A4/A5/C6/C7 land. Deletion is optional preference, not required for correctness once references and superseded headers are fixed. Original Q1 archive recommendation stands with stronger exit criteria.
|
||||
|
||||
### D3. Suggesting product-lock changes (none serious)
|
||||
No reviewer asked to reopen hybrid, bdft, AES-GCM, SLAB-UAT, inference-off-until-Gate-C, or gate map meaning. Out of scope by intent. Nothing to dismiss on locks themselves.
|
||||
|
||||
### D4. Praise-shaped “the ladder can disappear entirely on day one”
|
||||
Implied by original proposal §3.5 · Multiple models correctly rejected full ladder removal while copies remain. Lead dismisses the original overclaim, not the reviewers.
|
||||
|
||||
---
|
||||
|
||||
## Agreement map
|
||||
|
||||
### Strong consensus (3–4 models)
|
||||
| Theme | Models | Lead bucket |
|
||||
|---|---|---|
|
||||
| Do not slim AGENTS locks to pointers | A B C D | Act on A1 |
|
||||
| Woo dual-SoT must be resolved | A B C D | Act on A2 |
|
||||
| PRD archive needs reference rewrite | A B C D | Act on A4 |
|
||||
| W2 TV-10 must be scheduled | A B C D | Act on A8 |
|
||||
| W6–W8 / unedited archive + PM delete unsafe | A B D | Act on A5 |
|
||||
| Migration order / deletion-first overclaim | A B C | Act on A9 |
|
||||
| PM-DESIGN still has process value / provenance | B C D | Consider C1 |
|
||||
| Secrets SoT ≠ DATA-MODEL alone | A D (+C via slim) | Act on A3 |
|
||||
|
||||
### Pair consensus (2 models)
|
||||
| Theme | Models | Lead bucket |
|
||||
|---|---|---|
|
||||
| Gate C capture home before Phase 2 delete | A D | Act on A6 |
|
||||
| Phases 3–5 still stale / guard required | A D | Act on A7 |
|
||||
| File count / INVENTORY wrong | A D | Act on A12 |
|
||||
| Docs refactor DoD missing | A D | Act on A11 |
|
||||
| Gate table must move before PM delete | A C | Act on A10 |
|
||||
| ARCHITECTURE must stay normative topology | A D | Consider C2 |
|
||||
| Env-agnostic vs FR42 archive tension | A D | Consider C6 |
|
||||
|
||||
### Lone-model (still read; lead filtered)
|
||||
| Theme | Model | Lead bucket |
|
||||
|---|---|---|
|
||||
| W1 examples must update with endpoint | A | Consider C3 (fold into A9) |
|
||||
| CONTENT-WOO attributes §2.3 unlisted | A | Consider C4 |
|
||||
| Full corrected Caddy fragment in design | B | Consider C5 |
|
||||
| AGENTS known-stale FR4 already false | D | Act on A13 (lead-verified) |
|
||||
| Call 1 confidence 0.7 PRD-only | D | Consider C7 |
|
||||
| Kitchen-sink step 4 | A | Consider C8 |
|
||||
| N5 workspace-only | A | Consider C9 |
|
||||
| Prefer delete PRD over archive | C | Dismissed D2 as mandatory |
|
||||
| Deployed settings migration for prefs | B | Noted N6 |
|
||||
| Single-commit-only safety | B | Dismissed D1 as absolute |
|
||||
|
||||
### Pattern
|
||||
All four models independently attacked **AGENTS over-slim** and **Woo dual-SoT**. That is the highest-confidence signal in the panel. Capture-phase hole and IMPL 3–5 incompleteness are the next structural risks. Arithmetic/file-count and W2 are cheap factual fixes the original pass should not have missed.
|
||||
|
||||
No model defended “slim AGENTS to pointers only” or “CONTENT-WOO sole Woo-safety SoT while AGENTS keeps full copy.”
|
||||
|
||||
---
|
||||
|
||||
## What the original proposal got right (lead)
|
||||
|
||||
- Deletion-first intent for stale IMPL Phase 2/6 bodies and `processing` status.
|
||||
- B1 OPENAPI PUT recompute and B5 env-agnostic deploy are real and correctly prioritized in spirit.
|
||||
- TECH-SPEC and DATA-MODEL structure should not be churned.
|
||||
- Product locks listed in §4.5 must not reopen.
|
||||
- HOLD: proposal outside repo; no commit/push. Correct.
|
||||
- PM-DESIGN as long-term reconciliation artifact should die once contradictions are gone (with provenance handled).
|
||||
- Staged commits (Open Q3) remain the right delivery shape once ordering is fixed.
|
||||
|
||||
---
|
||||
|
||||
## Sign-off recommendation
|
||||
|
||||
| Question | Answer |
|
||||
|---|---|
|
||||
| Sign off original proposal as written? | **No** |
|
||||
| Sign off direction (deletion-first, single home per decision, locks unchanged)? | **Yes, with v2 constraints** |
|
||||
| Execute repo docs rewrite now? | **No. HOLD until Ty signs v2** |
|
||||
| v2 written? | **Yes:** `/workspace/slabuploader-docs-refactor-proposal-v2.md` |
|
||||
|
||||
---
|
||||
|
||||
## Artifacts
|
||||
|
||||
| Path | Role |
|
||||
|---|---|
|
||||
| `/workspace/slabuploader-docs-refactor-proposal.md` | Original proposal (unchanged) |
|
||||
| `/workspace/slabuploader-docs-refactor-interrogate.md` | This verdict |
|
||||
| `/workspace/slabuploader-docs-refactor-proposal-v2.md` | Revised proposal incorporating Act-on |
|
||||
| `/workspace/gitea-atd/Ty_Tech/SlabUploader/` | Repo tree **untouched** |
|
||||
|
||||
---
|
||||
|
||||
## HOLD confirmation
|
||||
|
||||
No files under `/workspace/gitea-atd/Ty_Tech/SlabUploader/` were created, modified, or deleted by this interrogate pass. No git commit. No push. Verdict and v2 live only under `/workspace/`.
|
||||
@@ -1,128 +0,0 @@
|
||||
# SlabUploader morning brief — docs refactor v2
|
||||
|
||||
For: Ty
|
||||
From: overnight CoS run (grokbot_ty)
|
||||
Date: 2026-09-01
|
||||
Branch: [docs/refactor-v2](https://gitea.vps1.afterthedemo.com/Ty_Tech/SlabUploader/src/branch/docs/refactor-v2)
|
||||
SoT: gitea-atd `Ty_Tech/SlabUploader`
|
||||
**main untouched** at `e1e087b`.
|
||||
|
||||
---
|
||||
|
||||
## What happened overnight
|
||||
|
||||
Ty authorized overnight execution of proposal v2 on `docs/refactor-v2`. CoS defaults used for the three open questions:
|
||||
|
||||
1. Archive PRD with a strong superseded header
|
||||
2. Delete PM-DESIGN only after DoD green + provenance in AGENTS
|
||||
3. Hybrid-align IMPL Phases 3–5 in the same stack
|
||||
|
||||
Four docs commits landed and were pushed after each commit. Author/committer: `grokbot_ty <grokbot_ty@gitea.local>` (local env only; global git config unchanged).
|
||||
|
||||
| # | SHA | Subject |
|
||||
|---|---|---|
|
||||
| 1 | `48720d8` | docs: stop wrong-code paths (OPENAPI store-only, Gate C, TV-10) |
|
||||
| 2 | `369d404` | docs: env-agnostic deploy (APP_HOSTNAME, inventory, Caddy order) |
|
||||
| 3 | `3ac5e36` | docs: factual CONTENT-WOO/DATA-MODEL fixes + hybrid Phases 3-5 |
|
||||
| 4 | `779fa7d` | docs: archive PRD, gate map in AGENTS, drop PM-DESIGN |
|
||||
|
||||
Tip of branch: **`779fa7d`**.
|
||||
|
||||
---
|
||||
|
||||
## What changed (plain English)
|
||||
|
||||
**Coding agents can no longer rebuild the old server pipeline from leftover sentences.**
|
||||
|
||||
- **OPENAPI** now stores client math on PUT. Create returns `calibrated` (examples too). No “server re-runs derived math.”
|
||||
- **IMPL-PLAN** owns a real **Gate C** path: online phone capture → mask/axis → numbers → Woo **draft** with `SLAB-UAT-*`, inference off. Phase 2 is a short deferred stub (offline/OCR/ruler). Phases 3–5 rewritten for hybrid. Phase 6 is online UAT only.
|
||||
- **Deploy** no longer hard-codes `.201`. Fill `deploy/INVENTORY.md`, use `APP_HOSTNAME`, Caddy routes `/api/*` to fastapi before the frontend catch-all.
|
||||
- **CONTENT-WOO** uploads processed **PNG** (keeps alpha), uses fig-*/feat-* tags and the five locked attributes, and cites AGENTS for Woo force-draft safety.
|
||||
- **DATA-MODEL** drops sheet/slider prefs from server settings (localStorage on the phone).
|
||||
- **PRD** moved to `docs/archive/PRD-2026-08.txt` with a “not a source for new work” header listing non-authoritative FRs. Live docs no longer point at a root PRD path.
|
||||
- **AGENTS** keeps every product lock in full sentences, plus Gate A/B/C table, freeze SHA provenance, and an open-doc-defects slot (currently empty).
|
||||
- **PM-DESIGN-ALIGNMENT.md** deleted after DoD greps went green and provenance moved into AGENTS.
|
||||
|
||||
No product locks were reopened. No app code, no schema migration, no host inventory, no merge to main.
|
||||
|
||||
---
|
||||
|
||||
## What stays locked
|
||||
|
||||
| Lock | Status |
|
||||
|---|---|
|
||||
| Hybrid: phone owns measure/crop; server stores / Woo / inference proxy / on-demand U2Net | Locked |
|
||||
| `bdft = sqft × thickness_in` (no `/12`) | Locked |
|
||||
| Secrets never in browser; AES-GCM server; `SLAB_AES_KEY` env only | Locked |
|
||||
| Woo UAT draft + `SLAB-UAT-*` force draft; real publish after your review | Locked |
|
||||
| Inference OFF until Gate C; Call 1/2 after, still inside POC | Locked |
|
||||
| Gate A = docs freeze · Gate B = run-host · Gate C = first draft listing | Locked in AGENTS table |
|
||||
| Online-only POC; env-agnostic deploy | Locked |
|
||||
|
||||
Woo firebreak in one line: test products hit the real store as **drafts** under obvious `SLAB-UAT-*` SKUs so shoppers never see them.
|
||||
|
||||
---
|
||||
|
||||
## DoD report
|
||||
|
||||
Proposal §6 checks run before PM-DESIGN delete. Result: **green**.
|
||||
|
||||
- No active-doc “re-runs derived math”
|
||||
- No IMPL acceptance that requires airplane mode, OCR, ruler, or offline UAT for POC (Phase 2 only lists those as deferred out-of-scope)
|
||||
- No `processing→ready` status path
|
||||
- No DEPLOYMENT RemBG / `output_px` 1000 happy-path SoT
|
||||
- No CONTENT-WOO “JPEG bytes” for processed media
|
||||
- No AGENTS false FR4 `/12` landmine
|
||||
- AGENTS still has bdft lock, never-browser + AES + `SLAB_AES_KEY`, `SLAB-UAT-*` force draft, inference OFF until Gate C, Gate A/B/C table, TV-1…TV-10, hybrid one-liner
|
||||
- Gate C slice in IMPL; PRD only under archive with header; `deploy/INVENTORY.md` present; freeze provenance in AGENTS
|
||||
- CONTENT-WOO cites AGENTS.md for force-draft policy
|
||||
|
||||
Detail: `/workspace/slabuploader-docs-refactor-status.md`
|
||||
|
||||
---
|
||||
|
||||
## Still open (your calls, not docs debt)
|
||||
|
||||
1. **Sign the branch** when you want it treated as SoT for implementers (merge strategy is yours; overnight did not merge to main).
|
||||
2. **Gate B** (host inventory on a real machine) is still **not** open. Docs are ready; no SSH/inventory was run.
|
||||
3. **Coding agents:** safe for Phase 0 / contract work after commit 1; safe for capture/Woo/inference feature docs after commit 3. Prefer waiting for your explicit “open scaffold” before anyone writes app code.
|
||||
4. **DM residual nits** (not blockers; see fold-in below): OPENAPI “duplicate SKU” wording could say “exists in Woo (any status)” not only “published”; compose/Caddy same-network note is implied but could be louder.
|
||||
|
||||
---
|
||||
|
||||
## How PPM / DM morning notes fold in
|
||||
|
||||
Both files were present under `/workspace/` and were read for this brief.
|
||||
|
||||
### Principal PM (`slabuploader-morning-ppm-notes.md`)
|
||||
|
||||
- Product-lock risk of v2: **low if followed literally**. Overnight followed literally: AGENTS locks stayed verbatim, Phases 3–5 got full hybrid align (not top-down-only), PRD archive got the superseded-FR header.
|
||||
- Open Q recommendations matched CoS defaults; all three executed.
|
||||
- Bottom line they wanted: sign v2 direction, not v1. Execution is done on the branch; your sign-off is on using it.
|
||||
|
||||
### Dev Manager (`slabuploader-morning-dm-notes.md`)
|
||||
|
||||
- Notes were written **before** commits landed (tip was still `e1e087b`). Their staging advice matched what ran: wrong-code-first → env-agnostic → factual+Phases 3–5 → archive/DoD.
|
||||
- Agent-safe checkpoints they named: after 1 (contract), after 3 (feature docs), after 4 (cleanup). All three SHAs are on origin.
|
||||
- Landmines they flagged that **were** covered overnight: B1/W1, Gate C before Phase 2 stub, env-agnostic + INVENTORY + Caddy order, confidence 0.7 in Phase 5, CONTENT-WOO PNG/tags, no workspace `/workspace/*.md` as repo SoT (agents still start at AGENTS in-repo).
|
||||
- Landmines still **optional polish** (not blocking DoD): OPENAPI duplicate-SKU “any Woo status” wording; explicit same-Docker-network sentence next to Caddy fragment.
|
||||
|
||||
---
|
||||
|
||||
## Links
|
||||
|
||||
- Branch: https://gitea.vps1.afterthedemo.com/Ty_Tech/SlabUploader/src/branch/docs/refactor-v2
|
||||
- Open PR (if you want one): https://gitea.vps1.afterthedemo.com/Ty_Tech/SlabUploader/pulls/new/docs/refactor-v2
|
||||
- Proposal: `/workspace/slabuploader-docs-refactor-proposal-v2.md`
|
||||
- Interrogate verdict: `/workspace/slabuploader-docs-refactor-interrogate.md`
|
||||
- Status / DoD detail: `/workspace/slabuploader-docs-refactor-status.md`
|
||||
|
||||
---
|
||||
|
||||
## Suggested morning order
|
||||
|
||||
1. Skim this page and the four commit subjects above.
|
||||
2. Open AGENTS.md on the branch (Gate table + locks).
|
||||
3. Spot-check OPENAPI PUT/POST and IMPL Gate C if you want proof.
|
||||
4. Decide: leave branch as SoT for docs, open a PR, and/or open Gate B inventory.
|
||||
5. Do not merge to main until you mean to.
|
||||
@@ -1,53 +0,0 @@
|
||||
# Morning notes for Ty — docs refactor v2 (Principal PM)
|
||||
|
||||
Date: 2026-09-01 (before morning PT)
|
||||
Read: `/workspace/slabuploader-docs-refactor-proposal-v2.md` + `/workspace/slabuploader-docs-refactor-interrogate.md`
|
||||
Repo: untouched; branch work is CoS overnight on `docs/refactor-v2` — these notes are product alignment only.
|
||||
|
||||
---
|
||||
|
||||
## 1. Product-lock risk if we execute v2 as written
|
||||
|
||||
**Low, if they follow v2 literally.** Interrogate blocked v1 for *execution* bugs (over-slim AGENTS, dual Woo homes, deleting Phase 2 before Gate C has a home). v2 fixes those. Nothing in v2 asks to reopen hybrid client math, board-feet formula, server-only secrets, Woo draft + `SLAB-UAT-*`, inference off until the first claimable draft listing, or what Gates A/B/C mean.
|
||||
|
||||
**Watch during execution (not reasons to reject v2):**
|
||||
- Anyone “simplifying” AGENTS into pointers only would quietly drop locks. v2 forbids that — keep an eye on the PR diff.
|
||||
- Phases 3–5 rewrite must not invent a new vision contract (e.g. top-down-only again). v2 already says all photos @1024 and inference after Gate C.
|
||||
- Archiving the PRD without the superseded-FR header would leave wrong FR17/FR19/FR40 language looking live under `docs/archive/`. v2 requires the header (or fix-then-archive).
|
||||
|
||||
No product renegotiation hiding in the file list or commit order.
|
||||
|
||||
---
|
||||
|
||||
## 2. Confirm: Woo safety / gates / hybrid stay locked
|
||||
|
||||
| Lock | Still locked in v2? |
|
||||
|---|---|
|
||||
| Hybrid: phone owns happy-path measure/crop; server stores / Woo / inference proxy / on-demand harder cut | Yes (§7 + AGENTS verbatim block) |
|
||||
| `bdft = sqft × thickness` (no `/12`) | Yes |
|
||||
| Secrets never in the browser; AES on server | Yes (AGENTS owns policy) |
|
||||
| Woo UAT: create as **draft**, `SLAB-UAT-*` always draft, real live publish only after your review | Yes (AGENTS owns safety policy; CONTENT-WOO cites it for payload) |
|
||||
| Inference off for first claimable listing; Call 1/2 after that, still in POC | Yes |
|
||||
| Gate A = docs freeze · Gate B = run-host · Gate C = first draft listing on phone path | Yes (table must live in AGENTS before PM-DESIGN dies) |
|
||||
| Env-agnostic deploy (host not hard-coded to .201) | Yes (direction unchanged) |
|
||||
| Online-only POC | Yes |
|
||||
|
||||
Woo “firebreak” in plain English: test listings go to the real store but stay **draft** and use obvious `SLAB-UAT-*` SKUs so shoppers never see them; only a real SKU you approve goes live.
|
||||
|
||||
---
|
||||
|
||||
## 3. Open questions — my recommendations
|
||||
|
||||
I agree with the CoS defaults in the overnight brief:
|
||||
|
||||
1. **PRD** — **Archive** to `docs/archive/` with a strong superseded header listing non-authoritative FRs (FR17 tags, FR19 category pricing, FR40/NFR server processing, FR42 .201 host). Same commit rewrites live links. Fixing every FR in place first is extra churn for a frozen record.
|
||||
|
||||
2. **PM-DESIGN-ALIGNMENT** — **Delete after the greppable DoD is green**, with Gate table + freeze SHA provenance lifted into AGENTS. Keeping a trimmed tracker until Gate C is optional insurance; I’d rather not maintain two open-defects homes. Do not delete on hope.
|
||||
|
||||
3. **IMPL Phases 3–5** — **Hybrid-align in the same docs stack** as Phase 2/6 cleanup (v2 commit 3). Leaving a long “incomplete rewrite” guard invites agents to implement stale Phase 5. Same stack costs more editing now and less wrong code later.
|
||||
|
||||
---
|
||||
|
||||
## Bottom line for Ty
|
||||
|
||||
Sign **v2 direction** when you’re ready. Do not sign old v1. Product locks are preserved by design; the overnight work is docs hygiene so coding agents cannot rebuild the wrong app from leftover sentences. HOLD on unrelated writes until you say otherwise.
|
||||
@@ -1,217 +0,0 @@
|
||||
# SlabUploader docs refactor: proposal (design checkpoint)
|
||||
|
||||
Status: PROPOSAL, not a rewrite. No repo files were changed by this work.
|
||||
SoT for the repo is Gitea `Ty_Tech/SlabUploader` on gitea-atd. TrueNAS and GitHub are mirrors, not SoT.
|
||||
Date: 2026-09-01. Author: poteto-mode (how-critique + architect-with-checkpoint).
|
||||
|
||||
---
|
||||
|
||||
## 1. Executive summary for Ty
|
||||
|
||||
The docs set is a frozen spec pile with a contradiction ladder bolted on top of it. AGENTS.md section 0 ranks the files so an agent can pick the winner when two disagree, and PM-DESIGN-ALIGNMENT.md catalogs every disagreement (5 blockers, 11 warns, 6 nits). That ladder is the symptom. You only need a tie-breaker because the same decision lives in several places.
|
||||
|
||||
The fix is deletion-first, not reorganization. Cut the stale bodies that are already superseded (IMPL-PLAN Phases 2 and 6 offline/OCR/ruler text). Delete the two files whose job was to flag contradictions (PM-DESIGN-ALIGNMENT.md and the PRD's decisions log) once their fixes land. Give each surviving file exactly one Diataxis mode. The result is a small set where every decision has one home, so no ladder is needed.
|
||||
|
||||
Target: 12 files down to 9 in-repo (plus an archived PRD). README stays the only explanation. AGENTS.md becomes a short hard-rules reference that points at each spec instead of restating it. TECH-SPEC, ARCHITECTURE, DATA-MODEL, OPENAPI, CONTENT-WOO, PROMPTS stay as single-mode references. DEPLOYMENT becomes env-agnostic.
|
||||
|
||||
Nothing here touches the locked product decisions. Hybrid topology, `bdft = sqft * thickness_in`, AES-GCM server secrets, Woo draft + `SLAB-UAT-*` safety, and the A/B/C gate map all carry over unchanged. This is a docs-only change. It does not unblock or start run-host setup until you sign off.
|
||||
|
||||
---
|
||||
|
||||
## 2. How the current docs set works
|
||||
|
||||
Twelve files split into three jobs: lock decisions, specify behavior, and track alignment.
|
||||
|
||||
**Decision locks.** `AGENTS.md` is the working contract for coding agents. Its section 0 is a precedence ladder (TECH-SPEC, then ARCHITECTURE, then AGENTS, then DATA-MODEL/OPENAPI/CONTENT-WOO/PROMPTS/DEPLOYMENT, then IMPL-PLAN Phase 0 only, then PRD/README). Sections 1 through 9 restate the locked decisions: hybrid topology, what not to build, the deterministic core, secrets, Woo UAT safety, inference sequencing, the slab status machine, test expectations, and deploy. `Slab capture app PRD.txt` carries product intent plus a dated decisions log (2026-08-31 freeze, 2026-08-27 Ty) that overlaps AGENTS.
|
||||
|
||||
**Behavior specs.** Each of the eight `docs/` files owns one slice:
|
||||
- `TECH-SPEC-PIPELINE.md`: deterministic math and image prep (constants, algorithms, TV-1 through TV-10).
|
||||
- `ARCHITECTURE.md`: hybrid topology, swimlane, what-runs-where, secrets, status machine.
|
||||
- `DATA-MODEL.md`: SQLite schema and the slab status state machine.
|
||||
- `OPENAPI.md`: client-to-server HTTP contract (schemas, endpoints, examples).
|
||||
- `CONTENT-WOO.md`: content templates plus the WooCommerce payload and publish sequence.
|
||||
- `PROMPTS.md`: Call 1 / Call 2 prompt files and their management.
|
||||
- `DEPLOYMENT.md`: compose, Caddy, backup/restore, runbook, smoke test (currently `.201`-bound).
|
||||
- `IMPL-PLAN.md`: Phases 0 through 6 with acceptance criteria and exit gates; Phase 0 rewritten for hybrid, Phases 1+ still carry the old offline pipeline.
|
||||
|
||||
**Alignment tracking.** `PM-DESIGN-ALIGNMENT.md` is a review artifact. It lists what agrees, what conflicts (blockers/warns/nits), and what is missing, plus a recommended patch list. It exists because the other files disagree with each other.
|
||||
|
||||
The mechanism that makes this work today is the precedence ladder plus superseded banners. When IMPL-PLAN Phase 2 still says "offline PWA + OCR + ruler," a banner marks it SUPERSEDED and AGENTS section 0 tells an agent to prefer the hybrid rewrite. The system holds together only as long as every reader applies that discipline. PM-DESIGN-ALIGNMENT's own verdict is that agents skim past banners, which is why the contradictions keep costing real work.
|
||||
|
||||
---
|
||||
|
||||
## 3. Critique (how-skill, critique mode)
|
||||
|
||||
### 3.1 Per-file Diataxis mode: today vs should-be
|
||||
|
||||
Diataxis has four modes. One file, one mode. The test for each file below is what a reader comes to it to do: learn by doing (tutorial), get a task done (how-to), look up a fact (reference), or understand why (explanation).
|
||||
|
||||
| File | Mode today | Mixed? | Should-be | Why |
|
||||
|---|---|---|---|---|
|
||||
| `README.md` | explanation + reference table | yes | **explanation** | It already explains the product and points elsewhere. Keep it as the single orientation doc; drop the per-file "what" table that duplicates AGENTS. |
|
||||
| `AGENTS.md` | reference (hard rules) | no, but bloated | **reference**, slimmed | Correct mode. Problem is scope: sections 1 through 9 restate decisions that already live in TECH-SPEC/ARCHITECTURE/DATA-MODEL. It should be a short list of hard rules plus one pointer per topic, not a second copy of the specs. |
|
||||
| `Slab capture app PRD.txt` | explanation (intent) + reference (FRs) | yes | **archive** | Product intent is now fully captured in AGENTS + ARCHITECTURE + TECH-SPEC. The FR list and decisions log are stale duplicates. Keep as a frozen historical record, not an active doc. |
|
||||
| `docs/TECH-SPEC-PIPELINE.md` | reference | no | **reference** (keep) | Clean single mode. This is the math SoT. No structural change; minor status-date bump only. |
|
||||
| `docs/ARCHITECTURE.md` | explanation + reference | yes | **explanation** | The topology, swimlane, and "what runs where" are understanding material. Keep it as the one place that explains the hybrid split. Move the secrets list to point at DATA-MODEL rather than restating keys. |
|
||||
| `docs/DATA-MODEL.md` | reference | no | **reference** (keep) | Schema + status machine, lookup-shaped. Fix: drop sheet/slider prefs from server settings (W3), say "client" not "PWA" (N1). |
|
||||
| `docs/OPENAPI.md` | reference | no | **reference** (keep) | Contract-shaped. Fix the two one-liners that contradict the hybrid lock: PUT must not recompute math as SoT (B1); POST returns `calibrated`, not `draft` (W1). |
|
||||
| `docs/CONTENT-WOO.md` | reference + how-to (publish sequence) | yes | **reference** | The payload, dedupe, and logging are lookup facts. The "end-to-end publish sequence" is a numbered procedure that belongs in IMPL-PLAN or stays as a short reference list. Fix W4 (PNG not JPEG), W5 (fig-/feat-* only), W11 (no calibration photos). |
|
||||
| `docs/PROMPTS.md` | reference + how-to (tuning workflow) | yes | **reference** | The prompt files and their inputs are lookup facts. The "tuning workflow" is a short how-to; keep it as a 4-line note or move to DEPLOYMENT runbook. No structural split needed for POC. |
|
||||
| `docs/DEPLOYMENT.md` | how-to (runbook) + reference (compose/Caddy) | yes | **how-to**, env-agnostic | It is an operations playbook: inventory, deploy, backup, smoke. Make it the single how-to and make it host-agnostic (`APP_HOSTNAME`, inventory worksheet), with `.201` as a non-normative example only. Fix W9 (drop RemBG/ruler/1000px) and W10 (Caddy handle order). |
|
||||
| `docs/IMPL-PLAN.md` | how-to (phased build) + reference (acceptance) | yes, badly | **how-to**, pruned | Correct mode for a phased plan. The defect is stale bodies: Phase 2 (offline/OCR/ruler) and Phase 6 UAT still specify the killed pipeline; Phase 1 invents a `processing` status (B2). Prune to hybrid-only phases. |
|
||||
| `docs/PM-DESIGN-ALIGNMENT.md` | explanation (review artifact) | no | **delete** (after fixes land) | Its entire reason for existing is that the other files disagree. Once the blockers/warns are fixed in place, this file has nothing left to say. It is a process artifact, not product documentation. |
|
||||
|
||||
### 3.2 Mixed modes (the real reader-load problem)
|
||||
|
||||
The set fails Diataxis's "one mode per file" rule in five places:
|
||||
- `README` mixes explanation with a reference table that duplicates AGENTS.
|
||||
- `ARCHITECTURE` mixes explanation (topology) with reference (secrets, status machine).
|
||||
- `CONTENT-WOO` mixes reference (payload) with how-to (publish sequence).
|
||||
- `PROMPTS` mixes reference (prompt files) with how-to (tuning workflow).
|
||||
- `DEPLOYMENT` and `IMPL-PLAN` each mix how-to steps with reference tables.
|
||||
|
||||
None of these is fatal on its own. The cost shows up in the next section. When a file holds two modes, it also tends to hold two copies of a decision, and that is where contradictions breed.
|
||||
|
||||
### 3.3 Duplicated rules (one SoT per decision)
|
||||
|
||||
The same locked decision is written in multiple files. Each copy is a place that can go stale or drift. The high-traffic ones:
|
||||
|
||||
| Decision | Where it is repeated today | Single home it should have |
|
||||
|---|---|---|
|
||||
| `bdft = sqft * thickness_in` (no `/12`) | TECH-SPEC 4.6/TV-3, AGENTS 3, PRD FR4, IMPL Phase 0, DEPLOYMENT smoke | **TECH-SPEC** (math SoT). Everywhere else: one pointer. |
|
||||
| Hybrid topology / client is math SoT | ARCHITECTURE 1-4, TECH-SPEC 1/9, AGENTS 1, README, PRD stack, IMPL Phase 0 | **ARCHITECTURE** (explanation) + **TECH-SPEC** (math). Others: pointer. |
|
||||
| Secrets server AES-GCM, never browser | ARCHITECTURE 5, AGENTS 4, DATA-MODEL settings, OPENAPI SettingsView, PRD D15 | **DATA-MODEL** (schema) is the SoT for what's stored; **ARCHITECTURE** explains why. Others: pointer. |
|
||||
| Woo safety (`woo_create_status`, `SLAB-UAT-*` force draft) | AGENTS 5, CONTENT-WOO 2.4, DATA-MODEL settings, OPENAPI SettingsView, DEPLOYMENT smoke, README, PRD D12/FR36 | **CONTENT-WOO** (publish behavior) is the SoT; **DATA-MODEL** holds the setting key. Others: pointer. |
|
||||
| Slab status machine (`draft` to `published`) | ARCHITECTURE 6, DATA-MODEL, AGENTS 7, OPENAPI | **DATA-MODEL** (state column) is the SoT; **ARCHITECTURE** explains transitions. Others: pointer. |
|
||||
| No fake upscale / at least 1600px or retake | TECH-SPEC 5/TV-6/TV-7, AGENTS 2-3, IMPL Phase 0 | **TECH-SPEC**. Others: pointer. |
|
||||
|
||||
The pattern is the same in every row: a decision that has one natural home is also restated in three to seven files. The fix is not to edit all copies. Keep the copy in the SoT file and replace the others with a link. That is the laziness protocol applied to docs, and it removes the need for AGENTS section 0's ladder because there will be fewer things that can disagree.
|
||||
|
||||
### 3.4 Stale bodies (already superseded, still present)
|
||||
|
||||
These are not "needs a fix," they are "the body describes something we decided not to build." They should be deleted or stubbed, not patched:
|
||||
|
||||
- **IMPL-PLAN Phase 2**: full offline PWA / Workbox / IndexedDB / Tesseract OCR / OpenCV.js ruler / airplane-mode UAT. Banner says SUPERSEDED; the body still demands all of it (blocker B3).
|
||||
- **IMPL-PLAN Phase 6**: UAT suite and perf budgets that include offline capture, OCR 1 to 2s, and "server normalization" 3 to 5s (blocker B4).
|
||||
- **IMPL-PLAN Phase 1**: invents a `processing` slab status and a server job that "processes" photos toward `ready`, which is the old server pipeline under a new name (blocker B2).
|
||||
- **OPENAPI PUT**: "Server re-runs derived math when inputs change," contradicting client-is-math-SoT (blocker B1).
|
||||
- **PRD FR40 / NFR**: "server-side processing" and "server normalization" on the publish path (warn W8).
|
||||
- **DEPLOYMENT section 9 / IMPL Risks**: RemBG server path, ruler row, `output_px` drop to 1000 (warn W9).
|
||||
|
||||
### 3.5 The structural root cause
|
||||
|
||||
AGENTS.md's contradiction ladder is a symptom, not the disease. A precedence list only earns its keep when the same fact lives in several files and can disagree. Two mechanisms are doing the work that structure should do:
|
||||
1. **Superseded banners** on stale bodies (IMPL Phase 2/6) rely on readers noticing and obeying them. PM-DESIGN-ALIGNMENT's own finding is that agents skim past banners.
|
||||
2. **The precedence ladder** in AGENTS section 0 tells an agent which file wins, but it does not stop the losing copy from being read first or trusted by a reader who never opens AGENTS.
|
||||
|
||||
Per encode-lessons-in-structure, the fix is to remove the duplicated copies so there is nothing to arbitrate, and to delete the stale bodies so there is no superseded text left to skim past. The ladder can then shrink to "read README for orientation; each spec file owns one topic." PM-DESIGN-ALIGNMENT.md itself is a third instance of the same anti-pattern: a document that exists only to reconcile documents, which disappears once the copies are gone.
|
||||
|
||||
### 3.6 Lead judgment (what I would act on)
|
||||
|
||||
**Act on.**
|
||||
- Delete IMPL-PLAN Phase 2 and Phase 6 stale bodies; replace with hybrid-only stubs or fold into Gate C scope. (B3, B4)
|
||||
- Fix OPENAPI PUT to "server stores client-sent derived fields; does not recompute as SoT." (B1)
|
||||
- Remove the `processing` status from IMPL Phase 1; keep only the five-state machine. (B2)
|
||||
- Make DEPLOYMENT env-agnostic per the existing outline (`APP_HOSTNAME`, inventory worksheet, `.201` as example). (B5)
|
||||
- Delete PM-DESIGN-ALIGNMENT.md after its blockers/warns are applied in place; keep a one-line pointer to the commit that resolved them.
|
||||
- Archive `Slab capture app PRD.txt` (move to `docs/archive/` or mark frozen); it is no longer an active source.
|
||||
|
||||
**Consider.**
|
||||
- Splitting CONTENT-WOO's publish sequence and PROMPTS' tuning workflow into DEPLOYMENT runbook. Low value for POC; do only if the files feel long after the other cuts.
|
||||
- Moving ARCHITECTURE's secrets list to a pointer at DATA-MODEL. Nice-to-have; the current duplication is small.
|
||||
|
||||
**Noted.**
|
||||
- Nits (N1 through N6): "PWA" wording, status-date bumps, DEPLOYMENT banner line-break glitch. Cheap to fix in the same pass; no design impact.
|
||||
|
||||
**Dismissed.**
|
||||
- Rewriting TECH-SPEC or DATA-MODEL structure. Both are already clean single-mode references. Do not churn what is correct.
|
||||
|
||||
---
|
||||
|
||||
## 4. Target design (architect checkpoint)
|
||||
|
||||
This is the proposed end state. It stops here for your sign-off; nothing below has been written into the repo.
|
||||
|
||||
### 4.1 File list, one mode each
|
||||
|
||||
| File | Mode | Owns (single SoT) | Changes from today |
|
||||
|---|---|---|---|
|
||||
| `README.md` | explanation | Product orientation: what it is, hybrid in one paragraph, where to read next, repo remotes, POC bar. | Drop the per-file "what" table (duplicates AGENTS). Keep short. |
|
||||
| `AGENTS.md` | reference | Hard rules only: precedence (shortened), do-not-build list, test/delivery expectations, gate map A/B/C. Each topic gets one pointer to its spec file instead of a restatement. | Slim sections 1 through 9 to pointers. Keep the Woo-safety and inference-sequencing hard rules verbatim (they are agent-critical). |
|
||||
| `docs/TECH-SPEC-PIPELINE.md` | reference | Deterministic math + image prep SoT: constants, algorithms, TV-1 through TV-10, pricing rule shape. | No structural change. Bump status date; confirm TV-10 is in scope (AGENTS W2). |
|
||||
| `docs/ARCHITECTURE.md` | explanation | Hybrid topology, swimlane, what-runs-where, why secrets stay server-side, status-machine transitions explained. | Remove "Remaining sections TBD" stale line (N3). Point secrets detail at DATA-MODEL. |
|
||||
| `docs/DATA-MODEL.md` | reference | SQLite schema SoT + status state machine (the column-level truth) + settings keys. | Drop sheet/slider prefs from server settings (W3); "client" not "PWA" (N1). |
|
||||
| `docs/OPENAPI.md` | reference | HTTP contract: schemas, endpoints, examples, error envelope. | Fix PUT no-recompute (B1), POST returns `calibrated` (W1), "client" not "PWA" (N1). |
|
||||
| `docs/CONTENT-WOO.md` | reference | Content templates + Woo payload + dedupe + publish logging SoT. | PNG media (W4), fig-/feat-* only (W5), no calibration photos (W11). Keep publish sequence as a short numbered list, not prose. |
|
||||
| `docs/PROMPTS.md` | reference | Call 1 / Call 2 prompt files, inputs, management, reset-to-default. | Trim tuning workflow to a 4-line note or move to DEPLOYMENT runbook. |
|
||||
| `docs/DEPLOYMENT.md` | how-to | Operations playbook: host inventory worksheet, deploy, backup/restore, key rotation, smoke test. Env-agnostic. | Make host-agnostic (`APP_HOSTNAME`, `deploy/INVENTORY.md`); `.201` as non-normative example; fix Caddy handle order (W10); drop RemBG/ruler/1000px (W9). |
|
||||
| `docs/IMPL-PLAN.md` | how-to | Phased build plan, hybrid-only: Phase 0 (Gates A+B), Gate C first draft listing, then API/Woo/inference/deploy phases. Acceptance + exit gates per phase. | Delete Phase 2 offline body and Phase 6 offline UAT; remove `processing` status from Phase 1; keep gate map aligned to A/B/C. |
|
||||
| `docs/archive/PRD-2026-08.txt` (moved) | frozen record | Historical product intent + decisions log, as of the freeze. Not a source for new work. | Move PRD here with a header: "Frozen 2026-08-31. Superseded by AGENTS + ARCHITECTURE + TECH-SPEC." No edits to content. |
|
||||
|
||||
That is 9 active in-repo files (README, AGENTS, 7 specs) plus one archived file. Down from 12 active.
|
||||
|
||||
### 4.2 Ownership and the single-SoT map
|
||||
|
||||
Each decision has exactly one home; every other mention is a link:
|
||||
|
||||
| Decision | SoT file |
|
||||
|---|---|
|
||||
| Math (bdft, sqft, widths, crop, no-upscale) + TV vectors | TECH-SPEC |
|
||||
| Hybrid topology and what-runs-where | ARCHITECTURE |
|
||||
| Schema, status machine column, settings keys | DATA-MODEL |
|
||||
| HTTP contract | OPENAPI |
|
||||
| Content templates + Woo payload/publish behavior | CONTENT-WOO |
|
||||
| Prompt files | PROMPTS |
|
||||
| Deploy operations (env-agnostic) | DEPLOYMENT |
|
||||
| Build phases and exit gates | IMPL-PLAN |
|
||||
| Hard rules for agents + gate map A/B/C | AGENTS |
|
||||
| Product orientation | README |
|
||||
|
||||
### 4.3 Deletes and archives
|
||||
|
||||
- **Delete** `docs/PM-DESIGN-ALIGNMENT.md` once its blockers (B1 through B5) and warns are applied in place. It is a reconciliation artifact; with the copies removed it has no content left.
|
||||
- **Archive** `Slab capture app PRD.txt` to `docs/archive/PRD-2026-08.txt`, frozen, unedited, with a superseded header.
|
||||
- **Delete (in place)** IMPL-PLAN Phase 2 offline body and Phase 6 offline UAT text; replace with hybrid stubs.
|
||||
- **Delete** the `processing` status from IMPL-PLAN Phase 1.
|
||||
|
||||
### 4.4 Migration order (deletion first)
|
||||
|
||||
Order matters: remove the stale/duplicated content before adding or rewording, so the diff is mostly minus lines and no new contradiction can be introduced mid-flight.
|
||||
|
||||
1. **Delete stale bodies.** IMPL-PLAN Phase 2 offline body, Phase 6 offline UAT, Phase 1 `processing` status; PRD FR40/NFR server-processing wording (if PRD stays active one more pass) or skip since it is being archived.
|
||||
2. **Fix the two contract contradictions in place.** OPENAPI PUT no-recompute (B1); POST returns `calibrated` (W1). These are wrong-code-if-followed, so they land before anything else that an agent might read.
|
||||
3. **Make DEPLOYMENT env-agnostic** per `/workspace/slabuploader-env-agnostic-doc-outline.md`; fix Caddy handle order and drop RemBG/ruler/1000px.
|
||||
4. **De-duplicate to single SoT.** Replace restated decisions in AGENTS, README, ARCHITECTURE with pointers; apply W3/W4/W5/W6/W7/W8/W9/W11/N1 through N6 fixes where they live.
|
||||
5. **Slim AGENTS.md** sections 1 through 9 to hard-rules-plus-pointers; shorten the precedence ladder now that there are fewer copies.
|
||||
6. **Archive the PRD**, then **delete PM-DESIGN-ALIGNMENT.md**. Both go last, after their content is confirmed relocated or resolved.
|
||||
|
||||
Each step is independently reviewable and shippable as its own docs commit on gitea-atd. None of them touches code, schema migrations, or run-host setup.
|
||||
|
||||
### 4.5 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 safety; inference OFF for the first claimable publish with Call 1/2 after Gate C; the A/B/C gate map (docs freeze / run-host setup / first draft listing). This refactor reorganizes and deletes; it does not change any of these.
|
||||
|
||||
---
|
||||
|
||||
## 5. Non-goals
|
||||
|
||||
- No code changes, no schema migrations, no scaffold, no run-host inventory or deploy. Docs only.
|
||||
- No rewrite of TECH-SPEC or DATA-MODEL structure (both are already correct single-mode references).
|
||||
- No new taxonomy, no invented categories, no best-practices content beyond what the locked decisions require.
|
||||
- No reordering of Phases 0 through 6; phase names and gate map stay as delivery chapters.
|
||||
- No commit or push in this pass. The proposal is a design checkpoint only.
|
||||
- Not doing the env-agnostic deploy sign-off itself (that is Ty's call via CoS, tracked separately).
|
||||
|
||||
---
|
||||
|
||||
## 6. Open questions for Ty (max 3)
|
||||
|
||||
1. **PRD disposition.** Archive `Slab capture app PRD.txt` to `docs/archive/` as a frozen record, or delete it outright now that AGENTS + ARCHITECTURE + TECH-SPEC carry all active intent? I recommend archive (keeps the decisions log for audit).
|
||||
2. **PM-DESIGN-ALIGNMENT.md.** Delete it once its blockers/warns are applied in place, or keep a trimmed version as a living "known contradictions" tracker until Gate C is green? I recommend delete-after-fixes; a standing contradiction list recreates the anti-pattern this refactor removes.
|
||||
3. **Scope of this pass.** Do you want the full target set (sections 4.1 through 4.4) executed in one docs commit, or staged as separate commits per migration step (deletions first, then env-agnostic deploy, then de-duplication)? I recommend staged so each is reviewable and the deletion-first order is visible.
|
||||
|
||||
---
|
||||
|
||||
## 7. No repo writes confirmed
|
||||
|
||||
This pass wrote exactly one file: `/workspace/slabuploader-docs-refactor-proposal.md` (this document), which lives outside the repo at `/workspace/`. No files under `/workspace/gitea-atd/Ty_Tech/SlabUploader/` were created, modified, or deleted. Nothing was committed or pushed. The repo is untouched and remains on its current HEAD; this proposal is a design checkpoint awaiting your sign-off before any rewrite begins.
|
||||
@@ -1,283 +0,0 @@
|
||||
# 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:
|
||||
|
||||
```text
|
||||
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
Block a user