docs: archive v1.3 and v2.0 milestones with roadmap, requirements, and retrospective

.planning/RETROSPECTIVE.md

@@ -136,6 +136,103 @@
 
 ---
 
+## Milestone: v1.3 — Research & Decision Tools
+
+**Shipped:** 2026-04-08
+**Phases:** 4 | **Plans:** 6 | **Files changed:** 52 (+3,106 / -158)
+
+### What Was Built
+- Pros/cons text annotation on candidates with visual indicator badges
+- Candidate ranking with sortOrder REAL column, drag-to-reorder via Reorder.Group, and gold/silver/bronze badges
+- Side-by-side comparison table with sticky attribute labels, weight/price delta highlighting, and winner marking
+- Setup impact preview with per-candidate weight/cost deltas, replacement detection, and "no weight data" indicator
+
+### What Worked
+- TDD for impact delta computation (Phase 13) — pure function tested in isolation before any UI work
+- Vertical slice pattern continued from v1.2 — each plan delivered end-to-end from schema to UI
+- framer-motion Reorder.Group provided drag-to-reorder with minimal code vs building from scratch
+- candidateViewMode pattern in UIStore cleanly separates grid/list/compare views without route complexity
+
+### What Was Inefficient
+- Phase 13 had a 3-week gap between research (2026-03-17) and execution (2026-04-08) — v2.0 work interleaved
+- Comparison table required careful horizontal scroll CSS that took iteration to get right
+- The 11-02 summary extraction failed (garbled output) — plan summaries should always have clean one-liners
+
+### Patterns Established
+- candidateViewMode (grid/list/compare): UIStore enum for toggling candidate presentation
+- Impact delta computation as pure function: `computeImpactDeltas(candidates, setup)` — no side effects
+- SetupImpactSelector: dropdown component for setup selection in thread context
+- ImpactDeltaBadge: reusable delta display component with replace/add/no-data states
+
+### Key Lessons
+1. Pure computation functions (no DB, no HTTP) are the fastest to TDD and most reliable to maintain
+2. Drag-to-reorder needs REAL (float) sort_order — integer ranks break on insert between existing items
+3. Comparison tables need both horizontal scroll and fixed first column — mobile-first means testing narrow viewports early
+4. Setup impact preview is most useful when it detects category-match replacement, not just addition
+
+### Cost Observations
+- Model mix: quality profile for execution
+- Sessions: Split across v2.0 work — phases 10-12 in one burst, phase 13 after v2.0 infrastructure
+- Notable: Smallest milestone (4 phases, 6 plans) but high user value per plan
+
+---
+
+## Milestone: v2.0 — Platform Foundation
+
+**Shipped:** 2026-04-08
+**Phases:** 10 | **Plans:** 32 | **Files changed:** 210 (+47,370 / -2,244)
+
+### What Was Built
+- Full PostgreSQL migration: 13 pgTable definitions, async services, PGlite test infrastructure, Docker Compose
+- External OIDC auth via Logto: three-way middleware (browser sessions, API keys, MCP OAuth)
+- Multi-user data model: userId FK on 6 entity tables, cross-user isolation, composite constraints
+- S3 object storage via MinIO: upload/delete/presigned URL abstraction, image migration script
+- Global item catalog: search, owner count, tags, 18-item bikepacking seed
+- User profiles with public setup sharing and visibility toggle
+- Reference item model with COALESCE merge pattern
+- Full catalog-driven gear flow: FAB, search overlay, add-to-collection/thread modals, manual fallback
+- Item and catalog detail pages replacing all slide-out panels
+
+### What Worked
+- Infrastructure phases (14-17) done in one concentrated push — no mixing infra with features
+- COALESCE merge pattern allowed reference items to inherit global data without duplication
+- Three-way auth middleware cleanly separated browser, API key, and MCP OAuth concerns
+- PGlite for tests eliminated external Postgres dependency while keeping real SQL execution
+- Catalog-first add flow with modal confirmation provided good UX without losing flexibility
+- Phase-per-concern kept scope manageable despite 10 phases
+
+### What Was Inefficient
+- SQLite to Postgres migration touched every service, route, and test file — massive blast radius
+- E2E tests broke and had to be disabled (backlog 999.1) — OIDC auth incompatible with test auth flow
+- Some phases (14, 18) had many plans (5-6) — could have been split into smaller milestones
+- Auth middleware complexity (OIDC + API keys + OAuth) required multiple fix commits post-merge
+- Phase 18 plan count (5) was at the upper limit — more granular phases would have been cleaner
+
+### Patterns Established
+- PGlite test infrastructure: `createTestDb()` returns async in-memory Postgres
+- Three-way auth: OIDC cookie → API key header → OAuth bearer, resolved to userId
+- COALESCE merge: `COALESCE(items.field, globalItems.field)` for transparent reference data
+- Global FAB pattern: floating action button with animated mini menu on all authenticated routes
+- Catalog search overlay: full-screen modal with debounced search, tag chip AND-filtering
+- AddToCollectionModal / AddToThreadModal: confirmation step with category picker + personal fields
+- Detail page pattern: `/items/:id` and `/global-items/:id` replacing slide-out panels
+
+### Key Lessons
+1. Database migration milestones should be their own release — touching every file means high risk of regressions
+2. PGlite is excellent for test infrastructure — real SQL without external dependencies
+3. Auth should be designed for testability from day one — bolting on OIDC broke the E2E test model
+4. COALESCE merge for reference data is elegant but requires careful propagation to all read paths
+5. Catalog-first flow works when the catalog is pre-seeded — empty catalog defeats the purpose
+6. Slide-out panels don't scale — detail pages with edit mode toggle are better for complex data
+7. Three-way auth middleware is maintainable when each method resolves to the same userId shape
+
+### Cost Observations
+- Model mix: quality profile throughout
+- Sessions: ~15 execution sessions across 22 days
+- Notable: Largest milestone by far (32 plans, 210 files) — v2.0 was effectively a rewrite of the backend
+
+---
+
 ## Cross-Milestone Trends
 
 ### Process Evolution
@@ -145,6 +242,8 @@
 | v1.0 | 53 | 3 | Initial build, coarse granularity, TDD backend |
 | v1.1 | ~30 | 3 | Auto-advance pipeline, parallel wave execution, auto-fix deviations |
 | v1.2 | 25 | 3 | Zero-deviation execution, vertical slice pattern, join table metadata |
+| v1.3 | ~15 | 4 | Pure function TDD, interleaved with v2.0, drag-to-reorder |
+| v2.0 | ~350 | 10 | Full platform rewrite, Postgres + OIDC + multi-user + catalog |
 
 ### Cumulative Quality
 
@@ -153,6 +252,8 @@
 | v1.0 | 5,742 | 114 | Service + route integration |
 | v1.1 | 6,134 | ~130 | Service + route integration (updated for icon schema) |
 | v1.2 | 7,310 | ~150 | 121 tests (service + route + classification) |
+| v1.3 | ~8,300 | ~160 | +impact delta tests |
+| v2.0 | 23,970 | 210+ | 161+ tests (PGlite, multi-user isolation, MCP) |
 
 ### Top Lessons (Verified Across Milestones)
 
@@ -162,3 +263,7 @@
 4. Auto-advance pipeline (discuss → plan → execute) works well for clear-scope phases
 5. Vertical slice delivery (schema → service → test → API → UI) is optimal for feature additions
 6. Join table metadata (not entity table) when same entity plays different roles in different contexts
+7. Database migrations are high-risk — isolate them from feature work
+8. Auth testability must be designed upfront — retrofitting breaks E2E tests
+9. COALESCE merge is powerful for reference data but must be propagated to all read paths
+10. Catalog-first flows need pre-seeded data to provide value on day one