From 6442a60ecc21991a4be6cb46936610cddd093b55 Mon Sep 17 00:00:00 2001 From: grokbot_ty Date: Mon, 7 Sep 2026 01:40:00 +0000 Subject: [PATCH] docs: drop AGENTS conflict-ladder precedence slop Docs should agree. Replace ranked disagreement order with a plain ownership map and keep only real archive mistakes plus open #4 pins. --- AGENTS.md | 52 +++++++++++++++++++++++++++++----------------------- 1 file changed, 29 insertions(+), 23 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2d92109..e4b3040 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,37 +2,43 @@ Working contract for coding agents. Read before writing code. -Status: **Gate A freeze** · signed 2026-08-31 PT · docs refactor 2026-09-01 · SoT: Gitea `Ty_Tech/SlabUploader` on **gitea-atd** (not mirrors). +Status: **Gate A freeze** · signed 2026-08-31 PT · docs cut to `main` 2026-09-06 · SoT: Gitea `Ty_Tech/SlabUploader` on **gitea-atd** (not mirrors). --- -## 0. Doc precedence (hard) +## 0. Where each doc lives -When docs disagree, use this order: +The live docs agree. Do not keep a conflict ladder in your head. If two live files disagree, that is a docs bug: fix the files, then continue. Do not pick a winner from a ranked list. -1. **`docs/TECH-SPEC-PIPELINE.md`** — deterministic math, image prep, constants, test vectors -2. **`docs/ARCHITECTURE.md`** — hybrid topology, what-runs-where, secrets why, status machine -3. This **`AGENTS.md`** — hard rules for agents (verbatim locks below) -4. **`docs/DATA-MODEL.md`**, **`docs/OPENAPI.md`**, **`docs/CONTENT-WOO.md`**, **`docs/PROMPTS.md`**, **`docs/DEPLOYMENT.md`**. Presentation: `docs/UX.md` (full rewrite landed 2026-09-02, same day as the deletion). Functional gates stay in this file. -5. **`docs/IMPL-PLAN.md`** — hybrid-aligned Phases 0–6. Phase 2 is a deferred stub only (offline PWA / OCR / ruler). Do not implement deferred stubs or any server happy-path measure/crop as SoT. -6. **`README.md`** — orientation only -7. **`docs/archive/PRD-2026-08.txt`** — frozen archive only. Not a source for new work. +| Doc | Owns | +|---|---| +| `docs/TECH-SPEC-PIPELINE.md` | Deterministic math, image prep, constants, test vectors | +| `docs/ARCHITECTURE.md` | Hybrid topology, what-runs-where, secrets why, status machine | +| `AGENTS.md` | Hard rules for coding agents (locks below) | +| `docs/DATA-MODEL.md` | Store row / schema facts | +| `docs/OPENAPI.md` | Wire / HTTP contracts | +| `docs/CONTENT-WOO.md` | Listing copy and Woo payload | +| `docs/PROMPTS.md` | Call 1 / Call 2 prompt files | +| `docs/DEPLOYMENT.md` | Compose, Caddy, secrets placement, ops | +| `docs/UX.md` | Presentation: what the mill owner sees and does | +| `docs/UAT-PRACTICE.md` | Walkable practice UAT for `SLAB-UAT-*` | +| `docs/IMPL-PLAN.md` | Phases 0–6. Phase 2 is a deferred stub only (offline PWA / OCR / ruler). Do not implement deferred stubs or server happy-path measure/crop as SoT. | +| `README.md` | Orientation only | +| `docs/archive/PRD-2026-08.txt` | Frozen archive. Not a source for new work. | -Archived PRD lines that conflict with the files above are non-authoritative (see archive header and known-stale list). +### Archive mistakes (do not reintroduce) -### Known stale (archive / historical only) +- PRD FR17 “Tags: fig-* only” is wrong. Locked model is `fig-*` (1+) + `feat-*` (0+). +- PRD FR19 category-weighted pricing is wrong. Species `$/bdft` only (category-weighted deferred v1.5). +- PRD FR40 / NFR server-normalization as SoT is wrong. Client owns happy-path measure/crop. +- PRD FR42 hard-coded `.201` is wrong. Env-agnostic DEPLOYMENT + inventory. +- Client-side store secrets are wrong. Server AES-GCM only. +- Offline-first PWA / OCR / ruler are deferred, not MVP. +- Woo create default is draft + `SLAB-UAT-*` for UAT, not the old “pending” wording. -- Archived PRD FR17 “Tags: fig-* only” → **wrong**. Locked model is `fig-*` (1+) + `feat-*` (0+). See DATA-MODEL. -- Archived PRD FR19 / overview “species and wood category” pricing → **wrong**. Species `$/bdft` only. Category-weighted pricing is deferred (v1.5). -- Archived PRD FR40 “server-side processing” and NFR “server normalization” → **wrong**. Client owns happy-path measure/crop; server stores drafts and runs U2Net on demand only. -- Archived PRD FR42 / deploy bullets hard-coding `.201` → superseded by env-agnostic DEPLOYMENT (inventory + `APP_HOSTNAME`). -- Older “creds client-side” decision → **wrong**. Server AES-GCM only; never browser storage for secrets. -- Offline-first PWA / OCR / ruler product text → superseded by hybrid + online-only MVP. -- Older “pending” Woo create default → superseded: UAT uses **Woo draft** + `SLAB-UAT-*`. +### Still open (real gaps only) -### Open doc defects - -Landed on `docs/refactor-v2`: #5 Application Passwords, #8 Call 1 prefill, #9 confidence gate, #11 `WOO_BASE_URL`, #12 synced-species-only, #15 inline mask knobs (U2Net deferred), #14 taxonomy manufactured last-modified, #2 portable Call1→Call2, #17 shared validation module, #18 409/422 field recovery. **#10 UX spec:** rewritten 2026-09-02; Ty signed the walk 2026-09-06 PT with one amendment (PC browsers in the compatibility matrix). Presentation: `docs/UX.md`. The pre-deletion file is history, not a source. **#4** browser floor: phone + PC families locked; exact minimum version pins and API inventory depth still open. OPENAPI #3 wording already landed if the body still looks open. +- Issue #4: exact minimum browser version pins and deeper load-bearing API inventory. Phone + PC families are already locked in `docs/UX.md` / TECH-SPEC. --- @@ -55,7 +61,7 @@ Phase map: **Phase 0 = Gates A+B.** **Gate C = early Phase 1** claimable publish | `4ec478f` | Contradiction patches (README/PRD/Woo/DEPLOYMENT) | | `4d9f307` / `4e97770` | Inference review + hybrid capture pipeline (pre-freeze baseline) | -Docs refactor stack on `docs/refactor-v2` (2026-09-01) applies OPENAPI store-only, env-agnostic deploy, CONTENT-WOO/DATA-MODEL facts, hybrid Phases 1–6, PRD archive. Product locks above are unchanged. +Docs refactor is on `main` (cut 2026-09-06). Product locks above are unchanged. ---