docs(08-01): complete candidate status tracking plan

- SUMMARY.md with task commits, decisions, and metrics
- STATE.md updated with position, decisions, session
- REQUIREMENTS.md: CAND-01, CAND-02, CAND-03 marked complete

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.planning/REQUIREMENTS.md

@@ -36,9 +36,9 @@ Requirements for this milestone. Each maps to roadmap phases.
 
 ### Candidate Status
 
-- [ ] **CAND-01**: Each candidate displays a status badge (researching, ordered, or arrived)
+- [x] **CAND-01**: Each candidate displays a status badge (researching, ordered, or arrived)
-- [ ] **CAND-02**: User can change a candidate's status via click interaction
+- [x] **CAND-02**: User can change a candidate's status via click interaction
-- [ ] **CAND-03**: New candidates default to "researching" status
+- [x] **CAND-03**: New candidates default to "researching" status
 
 ### Planning UI
 
@@ -104,9 +104,9 @@ Which phases cover which requirements. Updated during roadmap creation.
 | VIZZ-01 | Phase 9 | Pending |
 | VIZZ-02 | Phase 9 | Pending |
 | VIZZ-03 | Phase 9 | Pending |
-| CAND-01 | Phase 8 | Pending |
+| CAND-01 | Phase 8 | Complete |
-| CAND-02 | Phase 8 | Pending |
+| CAND-02 | Phase 8 | Complete |
-| CAND-03 | Phase 8 | Pending |
+| CAND-03 | Phase 8 | Complete |
 | PLAN-01 | Phase 8 | Complete |
 
 **Coverage:**

.planning/STATE.md

@@ -3,14 +3,14 @@ gsd_state_version: 1.0
 milestone: v1.2
 milestone_name: Collection Power-Ups
 status: completed
-stopped_at: Completed 08-02-PLAN.md
+stopped_at: Completed 08-01-PLAN.md
-last_updated: "2026-03-16T13:12:05.998Z"
+last_updated: "2026-03-16T13:13:36.233Z"
 last_activity: 2026-03-16 -- Completed 08-02 search/filter toolbar and category dropdown
 progress:
   total_phases: 3
-  completed_phases: 1
+  completed_phases: 2
   total_plans: 4
-  completed_plans: 3
+  completed_plans: 4
   percent: 75
 ---
 
@@ -49,6 +49,8 @@ Progress: [████████░░] 75%
 - No debounce on search input (collection under 1000 items)
 - Individual clear controls for search and category filter (no combined clear-all)
 - [Phase 08]: CategoryFilterDropdown kept separate from CategoryPicker (filter vs form concerns)
+- [Phase 08]: StatusBadge popup uses click-outside + Escape dismiss pattern matching CategoryPicker
+- [Phase 08]: Status badge uses muted gray tones (bg-gray-100 text-gray-600) per user design decision
 
 ### Pending Todos
 
@@ -60,6 +62,6 @@ None active.
 
 ## Session Continuity
 
-Last session: 2026-03-16T13:12:00.572Z
+Last session: 2026-03-16T13:13:36.231Z
-Stopped at: Completed 08-02-PLAN.md
+Stopped at: Completed 08-01-PLAN.md
 Resume file: None

.planning/phases/08-search-filter-and-candidate-status/08-01-SUMMARY.md

@@ -0,0 +1,112 @@
+---
+phase: 08-search-filter-and-candidate-status
+plan: 01
+subsystem: database, api, ui
+tags: [drizzle, sqlite, zod, react, tailwind, status-tracking]
+
+requires:
+  - phase: 05-thread-candidates
+    provides: threadCandidates table and CRUD service
+provides:
+  - status column on thread_candidates (researching/ordered/arrived)
+  - candidateStatusSchema Zod enum for validation
+  - StatusBadge clickable component with popup menu
+  - Status field in candidate CRUD operations
+affects: [08-search-filter-and-candidate-status]
+
+tech-stack:
+  added: []
+  patterns: [click-outside-dismiss-popup, status-badge-pill-with-menu]
+
+key-files:
+  created:
+    - src/client/components/StatusBadge.tsx
+    - drizzle/0002_broken_roughhouse.sql
+  modified:
+    - src/db/schema.ts
+    - src/shared/schemas.ts
+    - src/server/services/thread.service.ts
+    - src/client/hooks/useThreads.ts
+    - src/client/hooks/useCandidates.ts
+    - src/client/components/CandidateCard.tsx
+    - src/client/routes/threads/$threadId.tsx
+    - tests/helpers/db.ts
+    - tests/services/thread.service.test.ts
+
+key-decisions:
+  - "StatusBadge popup uses click-outside + Escape dismiss pattern matching CategoryPicker"
+  - "Status badge uses muted gray tones (bg-gray-100 text-gray-600) per user design decision"
+
+patterns-established:
+  - "StatusBadge popup: absolute positioned dropdown with click-outside dismiss via containerRef + useEffect mousedown listener"
+
+requirements-completed: [CAND-01, CAND-02, CAND-03]
+
+duration: 5min
+completed: 2026-03-16
+---
+
+# Phase 8 Plan 1: Candidate Status Tracking Summary
+
+**Candidate status tracking (researching/ordered/arrived) with schema migration, service/Zod updates, 5 TDD tests, and clickable StatusBadge popup on CandidateCard**
+
+## Performance
+
+- **Duration:** 5 min
+- **Started:** 2026-03-16T13:06:48Z
+- **Completed:** 2026-03-16T13:12:08Z
+- **Tasks:** 2
+- **Files modified:** 12
+
+## Accomplishments
+- Added `status` column to `thread_candidates` table with default "researching" and full Drizzle migration
+- Wired status through entire stack: schema, Zod validation, service CRUD, client type interfaces
+- Created StatusBadge component with clickable pill badge and popup menu (3 status options with icons)
+- Integrated StatusBadge into CandidateCard pill row with API mutation on status change
+- 5 new TDD tests covering all status CRUD operations (24 total thread service tests passing)
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Add status column and update backend + tests (TDD RED)** - `9342085` (test)
+2. **Task 1: Add status column and update backend + tests (TDD GREEN)** - `ca1c2a2` (feat)
+3. **Task 2: Create StatusBadge component and wire into CandidateCard** - `25956ed` (feat)
+
+_Note: Task 1 used TDD with separate RED and GREEN commits_
+
+## Files Created/Modified
+- `src/db/schema.ts` - Added status column to threadCandidates table
+- `src/shared/schemas.ts` - Added candidateStatusSchema Zod enum and status to createCandidateSchema
+- `src/server/services/thread.service.ts` - Status in getThreadWithCandidates select, createCandidate values, updateCandidate type
+- `src/client/hooks/useThreads.ts` - Added status to CandidateWithCategory interface
+- `src/client/hooks/useCandidates.ts` - Added status to CandidateResponse interface
+- `src/client/components/StatusBadge.tsx` - New clickable status badge with popup menu
+- `src/client/components/CandidateCard.tsx` - Added status and onStatusChange props, renders StatusBadge
+- `src/client/routes/threads/$threadId.tsx` - Passes status and useUpdateCandidate to CandidateCard
+- `tests/helpers/db.ts` - Added status column to test helper CREATE TABLE
+- `tests/services/thread.service.test.ts` - 5 new candidate status tests
+- `drizzle/0002_broken_roughhouse.sql` - Migration adding status column
+
+## Decisions Made
+- StatusBadge popup uses click-outside + Escape dismiss pattern matching CategoryPicker
+- Status badge uses muted gray tones (bg-gray-100 text-gray-600) per user design decision -- not semantic colors
+- Active status in popup menu highlighted with bg-gray-50 and checkmark icon
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Candidate status tracking fully operational
+- Ready for Plan 02 (search/filter functionality)
+
+---
+*Phase: 08-search-filter-and-candidate-status*
+*Completed: 2026-03-16*