docs: freeze Phase 3 contract - sections (25), second looks with rounds, match points + tank gauge, agent pass; UI-SPEC v3 + DESIGN/RANKING/DATA-MODEL/PLAN additions

This commit is contained in:
Alex (Hermes)
2026-11-10 22:52:51 -04:00
parent 49e284ff56
commit 40b42b1d40
5 changed files with 174 additions and 19 deletions

View File

@@ -34,20 +34,26 @@ A single-source, single-user, tailnet-only Tinder-style PWA on the Rotarran: nig
## Phase 2 — The swipe app (core)
**Status: built by Torres + verified by Alex (2026-11-10) on `dev`; awaiting Glenn's phone pass.** Contract frozen: `UI-SPEC.md` v2 + `reference/mockup-001-fidelity.html` (Variant A "Pure", approved by Glenn; 5-deep live stack, no-lock commit, dossier sheet). Image backfill + app-side mirror (`app/imgfetch.py`) done: 619/620 listings enriched, 559 local webp.
**Status: built by Torres + verified by Alex (2026-11-10) on `dev`; phone pass LIVE (swiping over the tailnet).** Contract frozen: `UI-SPEC.md` v2 + `reference/mockup-001-fidelity.html` (Variant A "Pure", approved by Glenn; 5-deep live stack, no-lock commit, dossier sheet). Image backfill + app-side mirror (`app/imgfetch.py`) done: 619/620 listings enriched, 559 local webp.
- [x] 2–3 UI mock variants → Glenn picked **Variant A "Pure"** (approved 2026-11-10 after two fix rounds)
- [x] API (deck cursor, swipe upsert/clear, list + filters, stats, media, import) + PWA frontend (faithful mockup port: stack engine, drag, Like / Nope / Maybe, dossier, empty/undo) — no match overlay (removed by Glenn's call)
- [x] Full list view with inline edit; basic filters (decision + sort + search)
- [ ] Proof: runs locally on :9453 (systemd dev unit) + tailnet `http://rotarran.tailf35a34.ts.net:9453`; phone-viewport browser pass green — **Glenn's phone pass pending**
- **Exit criteria:** Glenn can swipe a real deck on his phone and edit results in the list.
- [x] Proof: runs locally on :9453 (systemd dev unit) + tailnet `http://rotarran.tailf35a34.ts.net:9453`; phone-viewport browser pass green; **phone pass live 2026-11-10** — Glenn swiping the real deck over the tailnet (24 swipes recorded + verified from the DB; list-edit tap still unexercised by Glenn — automation-covered)
- **Exit criteria:** Glenn can swipe a real deck on his phone and edit results in the list — swiping proven; edit-tap pending.
## Phase 3 — Personalization
## Phase 3 — Personalization ("Trends")
- Swipe history → nightly retrain of explainable ranking
- Trends panel ("you lean: …"); "because you liked X" chips
- Deck ordering by learned taste with cold-start guardrails
- **Exit criteria:** after ~30 swipes, deck order visibly reflects taste; explainability shown in UI.
**Status: contract frozen 2026-11-10 (docs + brief); build started (Torres).** Glenn's approved design (2026-11-10):
- **Sections of 25:** the deck is a finite batch; the agent always runs between sections (learning segmentation + anti-doom-scroll). Modes: forge-on-demand (default) / strict (nightly read only). Fallback to the last profile if the agent fails.
- **Section lead:** on open/refresh the best suggestions lead; the 5-card live stack is unchanged.
- **Wildcards (~1-in-10):** labeled "maybe you'll like this one instead"; plausible stretches; never hard-noped families; their answers teach the model.
- **Second looks:** likes + maybes + nopes return (chosen; ≤5/section, ≤2 nopes); Round 2 weighs ×2; flips are the loudest signal; a re-nope rests the item; rounds cap at 2. Returning maybes can bring their variants.
- **Match points:** taste + agent adjustments; drive ordering, the section recipe (family caps, price mix), and returns. Explainable in the dossier; tank gauge (non-numeric) in the List.
- **Hits objective:** order = expected-like; Trends reports the hit rate (likes; likes+maybes).
- **Agent pass:** nightly/on-demand read (mock + live + fallback); **no LLM in the swipe path — ever.**
- **Exit criteria:** after ≥30 swipes the deck order visibly reflects taste; explainability visible (dossier breakdown + Trends); the section loop works end-to-end; the agent kill-switch test passes (app fully functional on the last profile with the pass disabled).
## Phase 4 — Deploy + automate