docs: create milestone v1.3 roadmap (4 phases)

.planning/REQUIREMENTS.md

@@ -68,24 +68,24 @@ Which phases cover which requirements. Updated during roadmap creation.
 
 | Requirement | Phase | Status |
 |-------------|-------|--------|
-| COMP-01 | — | Pending |
+| COMP-01 | Phase 12 | Pending |
-| COMP-02 | — | Pending |
+| COMP-02 | Phase 12 | Pending |
-| COMP-03 | — | Pending |
+| COMP-03 | Phase 12 | Pending |
-| COMP-04 | — | Pending |
+| COMP-04 | Phase 12 | Pending |
-| RANK-01 | — | Pending |
+| RANK-01 | Phase 11 | Pending |
-| RANK-02 | — | Pending |
+| RANK-02 | Phase 11 | Pending |
-| RANK-03 | — | Pending |
+| RANK-03 | Phase 10 | Pending |
-| RANK-04 | — | Pending |
+| RANK-04 | Phase 11 | Pending |
-| RANK-05 | — | Pending |
+| RANK-05 | Phase 11 | Pending |
-| IMPC-01 | — | Pending |
+| IMPC-01 | Phase 13 | Pending |
-| IMPC-02 | — | Pending |
+| IMPC-02 | Phase 13 | Pending |
-| IMPC-03 | — | Pending |
+| IMPC-03 | Phase 13 | Pending |
-| IMPC-04 | — | Pending |
+| IMPC-04 | Phase 13 | Pending |
 
 **Coverage:**
 - v1.3 requirements: 13 total
-- Mapped to phases: 0
+- Mapped to phases: 13
-- Unmapped: 13
+- Unmapped: 0
 
 ---
 *Requirements defined: 2026-03-16*

.planning/ROADMAP.md

@@ -5,6 +5,7 @@
 - ✅ **v1.0 MVP** — Phases 1-3 (shipped 2026-03-15)
 - ✅ **v1.1 Fixes & Polish** — Phases 4-6 (shipped 2026-03-15)
 - ✅ **v1.2 Collection Power-Ups** — Phases 7-9 (shipped 2026-03-16)
+- 🚧 **v1.3 Research & Decision Tools** — Phases 10-13 (in progress)
 
 ## Phases
 
@@ -35,6 +36,61 @@
 
 </details>
 
+### 🚧 v1.3 Research & Decision Tools (In Progress)
+
+**Milestone Goal:** Give users the tools to actually decide between candidates — compare details side-by-side, see how a pick impacts their setup, and rank/annotate their options.
+
+- [ ] **Phase 10: Schema Foundation + Pros/Cons Fields** — Migrate schema and deliver pros/cons annotation UI
+- [ ] **Phase 11: Candidate Ranking** — Drag-to-reorder priority ranking with rank badges
+- [ ] **Phase 12: Comparison View** — Side-by-side tabular comparison with relative deltas
+- [ ] **Phase 13: Setup Impact Preview** — Per-candidate weight and cost delta against a selected setup
+
+## Phase Details
+
+### Phase 10: Schema Foundation + Pros/Cons Fields
+**Goal**: Candidates can be annotated with pros and cons, and the database is ready for ranking
+**Depends on**: Phase 9
+**Requirements**: RANK-03
+**Success Criteria** (what must be TRUE):
+  1. User can open a candidate edit form and see pros and cons text fields
+  2. User can save pros and cons text; the text persists across page refreshes
+  3. CandidateCard shows a visual indicator when a candidate has pros or cons entered
+  4. All existing tests pass after the schema migration (no column drift in test helper)
+**Plans**: TBD
+
+### Phase 11: Candidate Ranking
+**Goal**: Users can drag candidates into a priority order that persists and is visually communicated
+**Depends on**: Phase 10
+**Requirements**: RANK-01, RANK-02, RANK-04, RANK-05
+**Success Criteria** (what must be TRUE):
+  1. User can drag a candidate card to a new position within the thread's candidate list
+  2. The reordered sequence is still intact after navigating away and returning
+  3. The top three candidates display gold, silver, and bronze rank badges respectively
+  4. Drag handles and rank badges are absent on a resolved thread; candidates render in static order
+**Plans**: TBD
+
+### Phase 12: Comparison View
+**Goal**: Users can view all candidates for a thread side-by-side in a table with relative weight and price deltas
+**Depends on**: Phase 11
+**Requirements**: COMP-01, COMP-02, COMP-03, COMP-04
+**Success Criteria** (what must be TRUE):
+  1. User can toggle a "Compare" mode on a thread detail page to reveal a tabular view showing weight, price, images, notes, links, status, pros, and cons for every candidate in columns
+  2. The lightest candidate column is highlighted and all other columns show their weight difference relative to it; the cheapest candidate is highlighted similarly for price
+  3. The comparison table scrolls horizontally on a narrow viewport without breaking layout; the attribute label column stays fixed on the left
+  4. A resolved thread shows the comparison table in read-only mode with the winning candidate visually marked
+**Plans**: TBD
+
+### Phase 13: Setup Impact Preview
+**Goal**: Users can select any setup and see exactly how much weight and cost each candidate would add or subtract
+**Depends on**: Phase 12
+**Requirements**: IMPC-01, IMPC-02, IMPC-03, IMPC-04
+**Success Criteria** (what must be TRUE):
+  1. User can select a setup from a dropdown in the thread header and each candidate displays a weight delta and cost delta below its name
+  2. When the selected setup contains an item in the same category as the thread, the delta reflects replacing that item (negative delta is possible) rather than pure addition
+  3. When no category match exists in the selected setup, the delta shows a pure addition amount clearly labeled as "add"
+  4. A candidate with no weight recorded shows a "-- (no weight data)" indicator instead of a zero delta
+**Plans**: TBD
+
 ## Progress
 
 | Phase | Milestone | Plans Complete | Status | Completed |
@@ -48,3 +104,7 @@
 | 7. Weight Unit Selection | v1.2 | 2/2 | Complete | 2026-03-16 |
 | 8. Search, Filter, and Candidate Status | v1.2 | 2/2 | Complete | 2026-03-16 |
 | 9. Weight Classification and Visualization | v1.2 | 2/2 | Complete | 2026-03-16 |
+| 10. Schema Foundation + Pros/Cons Fields | v1.3 | 0/TBD | Not started | - |
+| 11. Candidate Ranking | v1.3 | 0/TBD | Not started | - |
+| 12. Comparison View | v1.3 | 0/TBD | Not started | - |
+| 13. Setup Impact Preview | v1.3 | 0/TBD | Not started | - |

.planning/STATE.md

@@ -2,12 +2,12 @@
 gsd_state_version: 1.0
 milestone: v1.3
 milestone_name: Research & Decision Tools
-status: requirements
+status: roadmap
-stopped_at: Defining requirements
+stopped_at: Roadmap created — ready to plan Phase 10
 last_updated: "2026-03-16T19:00:00.000Z"
-last_activity: 2026-03-16 -- Milestone v1.3 started
+last_activity: 2026-03-16 -- Roadmap created for v1.3 (4 phases, 13 requirements)
 progress:
-  total_phases: 0
+  total_phases: 4
   completed_phases: 0
   total_plans: 0
   completed_plans: 0
@@ -21,14 +21,35 @@ progress:
 See: .planning/PROJECT.md (updated 2026-03-16)
 
 **Core value:** Make it effortless to manage gear and plan new purchases -- see how a potential buy affects your total setup weight and cost before committing.
-**Current focus:** v1.3 Research & Decision Tools
+**Current focus:** v1.3 Research & Decision Tools — Phase 10 ready to plan
 
 ## Current Position
 
-Phase: Not started (defining requirements)
+Phase: 10 of 13 (Schema Foundation + Pros/Cons Fields)
 Plan: —
-Status: Defining requirements
+Status: Ready to plan
-Last activity: 2026-03-16 — Milestone v1.3 started
+Last activity: 2026-03-16 — Roadmap created for v1.3 milestone
+
+Progress: [░░░░░░░░░░] 0%
+
+## Performance Metrics
+
+**Velocity:**
+- Total plans completed: 0
+- Average duration: —
+- Total execution time: —
+
+**By Phase:**
+
+| Phase | Plans | Total | Avg/Plan |
+|-------|-------|-------|----------|
+| - | - | - | - |
+
+**Recent Trend:**
+- Last 5 plans: —
+- Trend: —
+
+*Updated after each plan completion*
 
 ## Accumulated Context
 
@@ -36,6 +57,11 @@ Last activity: 2026-03-16 — Milestone v1.3 started
 
 Cleared at milestone boundary. v1.2 decisions archived in milestones/v1.2-ROADMAP.md.
 
+Key v1.3 research findings (see research/SUMMARY.md):
+- framer-motion@12.37.0 (already installed) handles drag-to-reorder via Reorder component — no new deps
+- sort_order must use REAL (float) type, not INTEGER, to avoid bulk writes on every drag
+- Impact preview must distinguish add-mode vs replace-mode by category match — pure addition misleads
+
 ### Pending Todos
 
 None active.
@@ -47,5 +73,5 @@ None active.
 ## Session Continuity
 
 Last session: 2026-03-16
-Stopped at: Defining requirements for v1.3
+Stopped at: Roadmap created — 4 phases, 13 requirements mapped, ready to plan Phase 10
 Resume file: None