fix(ui): make TaskStats phase-aware to fix late-joining user bug

.beads/issues.jsonl

@@ -96,6 +96,7 @@
 {"id":"codeframe-791","title":"Phase 6: US4 - Dashboard Integration (codeframe-8jr)","description":"Migrate Dashboard component from local state to Context-based state management.\n\nDeliverables:\n- Dashboard wrapped with AgentStateProvider\n- Replace useState with useAgentState hook\n- Remove local WebSocket handlers\n- React.memo optimization for AgentCard\n- Connection status indicator\n- 6 integration tests\n\nTasks: T096-T114 (19 tasks total)\nDependencies: Phase 5 complete\nEstimated: 1 day","status":"closed","priority":0,"issue_type":"task","created_at":"2025-11-06T22:47:13.539863401-07:00","updated_at":"2025-11-14T10:48:57.43931324-07:00","closed_at":"2025-11-14T10:48:57.43931324-07:00","close_reason":"Sprint 6 phases complete - PR #18","labels":["frontend","integration","sprint-4","ui","us4"]}
 {"id":"codeframe-7i9","title":"T010: WebSocket broadcast helpers","description":"Add WebSocket broadcast helpers to codeframe/ui/websocket_broadcasts.py (broadcast_blocker_created, broadcast_blocker_resolved, broadcast_agent_resumed)","status":"closed","priority":0,"issue_type":"task","created_at":"2025-11-08T19:20:34.168863455-07:00","updated_at":"2025-11-14T10:48:48.466244084-07:00","closed_at":"2025-11-14T10:48:48.466244084-07:00","close_reason":"Sprint 6 (049-human-in-loop) complete - merged in PR #18","dependencies":[{"issue_id":"codeframe-7i9","depends_on_id":"codeframe-2yh","type":"blocks","created_at":"2025-11-08T19:22:46.737355169-07:00","created_by":"frankbria"}]}
 {"id":"codeframe-7pl","title":"T106: Replace projectProgress useState with useAgentState hook","description":"Replace projectProgress useState with useAgentState hook in Dashboard.tsx","design":"Remove local projectProgress state and replace with projectProgress from useAgentState context hook","acceptance_criteria":"- [ ] Local projectProgress useState removed\n- [ ] projectProgress value comes from context\n- [ ] Component works correctly","status":"closed","priority":0,"issue_type":"task","created_at":"2025-11-07T13:34:38.182191318-07:00","updated_at":"2025-11-07T13:54:35.670983014-07:00","closed_at":"2025-11-07T13:54:35.670983014-07:00"}
+{"id":"codeframe-7pya","title":"State Sync Audit: Identify components with phase-awareness gaps","description":"\n## Background\nThe TaskStats component fix (this branch) exposed a broader pattern: components that use `useAgentState()` hook without considering project phase may show incorrect data during planning or other non-development phases.\n\n## Root Cause\nThe application has two parallel data systems:\n1. **REST API (issues endpoint)** - Source of truth during planning phase\n2. **WebSocket (agent state)** - Real-time state during development\n\nComponents that rely solely on one data source without phase awareness are vulnerable to 'late-joining user' scenarios.\n\n## At-Risk Components (Audit Needed)\n\n### High Priority\n1. **AgentPanel** - May show 'no agents' during planning when agents are planned but not yet active\n2. **ProgressIndicator** - May calculate 0% progress during planning phase\n3. **TaskTreeView** - May show empty tree during planning if only reading agent state\n\n### Medium Priority\n4. **MetricsCharts (CostDashboard)** - Should show 'Metrics available during development' during planning\n5. **QualityGates** - Should show configured gates during planning (pending execution)\n\n### Pattern to Apply\nEach component should:\n1. Accept `phase` prop\n2. Accept phase-specific data prop (e.g., `issuesData`)\n3. Select appropriate data source based on phase\n4. Handle phase transitions gracefully\n\n## Testing Strategy\nEach component should have 'late-joining user' E2E tests that verify:\n- Correct display during each phase\n- Smooth data source switching during phase transitions\n- Graceful degradation when data is loading\n\n## Related Work\n- TaskStats fix: this branch\n- Late-joining user E2E tests: commits cb408ed, e1539b8\n","status":"open","priority":2,"issue_type":"task","created_at":"2026-01-08T23:05:26.460792556-07:00","updated_at":"2026-01-08T23:05:26.460792556-07:00","labels":["frontend","tech-debt"]}
 {"id":"codeframe-7yn","title":"T117: Performance test for 10 concurrent agents without lag","description":"Performance test for 10 concurrent agents without lag in web-ui/__tests__/performance/ten-agents-load.test.ts","design":"Create load test that renders Dashboard with 10 agents and verifies no performance degradation","acceptance_criteria":"- [ ] Test file created\n- [ ] Test simulates 10 concurrent agents\n- [ ] Test verifies no lag or slowdown\n- [ ] Test passes","status":"closed","priority":0,"issue_type":"task","created_at":"2025-11-07T14:03:46.049389607-07:00","updated_at":"2025-11-18T07:57:37.6037886-07:00","closed_at":"2025-11-14T23:06:25.844551951-07:00"}
 {"id":"codeframe-8","title":"Connect Status Server to actual Database","description":"","status":"closed","priority":0,"issue_type":"task","assignee":"self","created_at":"2025-10-15T20:38:25.204464267-07:00","updated_at":"2025-10-16T13:54:27.101733546-07:00","closed_at":"2025-10-16T13:54:27.101733546-07:00"}
 {"id":"codeframe-8at","title":"Phase 5 Complete: Agent Resume After Blocker Resolution (T028-T034)","description":"Completed implementation of User Story 3 for 049-human-in-loop feature.\n\n✅ Completed Tasks:\n- T028-T030: wait_for_blocker_resolution() in all 3 worker agents\n- T032: WebSocket broadcast_agent_resumed() \n- T033-T034: Dashboard WebSocket handler and activity feed\n\n✅ Test Results: 7/7 passing (100% pass rate)\n\n📋 Implementation Details:\n- Agents poll database every 5s (configurable)\n- 600s timeout (configurable)\n- Returns user's answer when resolved\n- Broadcasts agent_resumed WebSocket event\n- Dashboard shows ▶️ icon in activity feed\n\n⏸️ Deferred:\n- T031: Answer injection logic (design decision needed)\n\n✅ Status: Phase 5 MVP complete, ready for end-to-end testing","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-08T21:22:41.73374674-07:00","updated_at":"2025-11-08T21:24:29.588113773-07:00","closed_at":"2025-11-08T21:24:29.588113773-07:00"}

docs/code-review/2026-01-08-taskstats-phase-awareness-review.md

@@ -0,0 +1,243 @@
+# Code Review Report: TaskStats Phase-Aware Data Source
+
+**Date:** 2026-01-08
+**Reviewer:** Code Review Agent
+**Component:** TaskStats Component - Phase-Aware Bug Fix
+**Files Reviewed:**
+- `web-ui/src/components/tasks/TaskStats.tsx`
+- `web-ui/src/components/Dashboard.tsx`
+- `web-ui/__tests__/components/tasks/TaskStats.test.tsx`
+
+**Ready for Production:** Yes
+
+## Executive Summary
+
+This PR fixes the "late-joining user" bug where TaskStats displayed 0 tasks during the planning phase despite tasks existing in the issues data. The implementation adds phase-aware data source selection while maintaining backward compatibility. The code follows React best practices, includes comprehensive tests, and properly handles edge cases.
+
+**Critical Issues:** 0
+**Major Issues:** 0
+**Minor Issues:** 2
+**Positive Findings:** 6
+
+---
+
+## Review Context
+
+**Code Type:** Frontend React Component (UI Display)
+**Risk Level:** Low
+**Business Constraints:** Bug fix with backward compatibility requirement
+
+### Review Focus Areas
+
+Based on context analysis, the review focused on:
+- ✅ Reliability - Error handling, edge cases, defensive programming
+- ✅ Maintainability - Type safety, documentation, code organization
+- ✅ Performance - Memoization correctness, unnecessary re-renders
+- ✅ Testing - Coverage, edge case validation
+- ❌ Security (OWASP Top 10) - Not applicable (no user input, authentication, or data mutations)
+
+---
+
+## Priority 1 Issues - Critical
+
+**None identified**
+
+---
+
+## Priority 2 Issues - Major
+
+**None identified**
+
+---
+
+## Priority 3 Issues - Minor
+
+### 1. Multiple Array Iterations in calculateStatsFromIssues
+
+**Location:** `web-ui/src/components/tasks/TaskStats.tsx:62-71`
+**Severity:** Minor
+**Category:** Performance Optimization
+
+**Problem:**
+The `calculateStatsFromIssues` function filters the array 3 times (completed, blocked, in_progress). For large task lists, a single-pass approach would be more efficient.
+
+**Current Code:**
+```typescript
+return {
+  total: allTasks.length,
+  completed: allTasks.filter((t) => t.status === 'completed').length,
+  blocked: allTasks.filter((t) => t.status === 'blocked').length,
+  inProgress: allTasks.filter((t) => t.status === 'in_progress').length,
+};
+```
+
+**Suggested Fix:**
+```typescript
+const counts = { total: allTasks.length, completed: 0, blocked: 0, inProgress: 0 };
+for (const task of allTasks) {
+  if (task.status === 'completed') counts.completed++;
+  else if (task.status === 'blocked') counts.blocked++;
+  else if (task.status === 'in_progress') counts.inProgress++;
+}
+return counts;
+```
+
+**Assessment:** Low priority - current implementation is readable and typical planning phase task counts are small (<100 tasks). The memoization ensures this runs infrequently. **Acceptable as-is for this PR.**
+
+---
+
+### 2. Phase Type Could Be More Specific
+
+**Location:** `web-ui/src/components/tasks/TaskStats.tsx:37`
+**Severity:** Minor
+**Category:** Type Safety
+
+**Problem:**
+The `phase` prop uses `string` type rather than a union type matching the actual phases.
+
+**Current Code:**
+```typescript
+phase?: string;
+```
+
+**Suggested Fix:**
+```typescript
+phase?: 'discovery' | 'planning' | 'development' | 'review' | 'complete' | 'shipped';
+```
+
+**Assessment:** Low priority - the component only checks for `'planning'` equality, so the string comparison works correctly. The broader type allows flexibility if phase names change. **Acceptable as-is for this PR.**
+
+---
+
+## Positive Findings
+
+### Excellent Practices
+
+1. **Backward Compatibility:** Optional props ensure existing usages continue to work without modification. The component defaults to agent state if no phase/issuesData is provided.
+
+2. **React Hooks Rules Compliance:** The hook is always called unconditionally, with conditional data usage - following React's rules of hooks correctly.
+
+3. **Defensive Programming:** Optional chaining (`issuesData?.issues`) and fallback to empty arrays (`issue.tasks || []`) prevent runtime errors.
+
+4. **Comprehensive Memoization:** The `useMemo` hook includes all relevant dependencies, ensuring correct cache invalidation on data source changes.
+
+### Good Architectural Decisions
+
+5. **Single Responsibility:** The `calculateStatsFromIssues` helper function is extracted separately, making the component logic clearer and the helper testable in isolation.
+
+6. **Phase-Aware Pattern:** This establishes a reusable pattern for other components facing the same dual-data-source issue (documented in issue codeframe-7pya).
+
+### Test Coverage
+
+7. **Edge Case Coverage:** Tests cover:
+   - Planning phase with data
+   - Development/review phases
+   - Missing issuesData
+   - Issues without tasks array
+   - Phase transitions
+   - Backward compatibility
+   - API consistency verification
+
+---
+
+## Team Collaboration Needed
+
+### Handoffs to Other Agents
+
+**Architecture Agent:**
+- The pattern established here (phase-aware data source selection) should be documented as a recommended approach for other at-risk components listed in issue codeframe-7pya.
+
+**UX Designer Agent:**
+- Consider whether a loading state indicator would improve UX when issuesData is undefined during planning phase (currently shows 0s).
+
+---
+
+## Testing Recommendations
+
+### Unit Tests - Covered
+
+- [x] Planning phase uses issuesData
+- [x] Development phase uses agent state
+- [x] Review phase uses agent state
+- [x] Missing issuesData handled gracefully
+- [x] Issues without tasks handled gracefully
+- [x] Backward compatibility without props
+- [x] Phase transition data source switching
+- [x] Consistency with API total_tasks field
+
+### Integration Tests - Existing Coverage
+
+- [x] Dashboard test suite passes (44 tests)
+- [x] Full test suite passes (1498 tests)
+
+### E2E Tests - Future Consideration
+
+- [ ] Late-joining user sees correct task count during planning phase (would validate full stack)
+
+---
+
+## Future Considerations
+
+### Patterns for Project Evolution
+
+- The phase-aware component pattern should be applied to other components identified in issue codeframe-7pya (AgentPanel, ProgressIndicator, TaskTreeView).
+- Consider creating a custom hook like `usePhaseAwareData()` to centralize the pattern if multiple components need it.
+
+### Technical Debt Items
+
+- Issue codeframe-7pya tracks the broader audit of components needing phase awareness.
+
+---
+
+## Compliance & Best Practices
+
+### React Best Practices Met
+
+- ✅ Hooks rules followed (unconditional hook calls)
+- ✅ Proper memoization with complete dependency arrays
+- ✅ TypeScript interfaces for props
+- ✅ JSDoc documentation on component and helpers
+- ✅ React.memo export for performance optimization
+
+### Testing Best Practices
+
+- ✅ Descriptive test names
+- ✅ AAA pattern (Arrange-Act-Assert)
+- ✅ Edge case coverage
+- ✅ Mock isolation
+
+---
+
+## Action Items Summary
+
+### Immediate (Before Production)
+
+*No critical or major issues - ready for production*
+
+### Short-term (Next Sprint)
+
+1. Apply phase-aware pattern to other at-risk components (issue codeframe-7pya)
+
+### Long-term (Backlog)
+
+1. Consider adding loading state indicator for undefined issuesData
+2. Consider single-pass optimization if task lists grow large
+
+---
+
+## Conclusion
+
+This PR implements a well-designed fix for the TaskStats planning phase bug. The code demonstrates solid React practices including proper hooks usage, memoization, and type safety. The comprehensive test suite (8 new tests) covers all relevant scenarios including edge cases and phase transitions. The minor issues identified are acceptable for this PR and represent optimization opportunities rather than functional concerns.
+
+**Recommendation:** ✅ Ready for Production - Approve and Merge
+
+---
+
+## Appendix
+
+### Metrics
+
+- **Lines of Code Changed:** +453 (86 component, 365 tests)
+- **Functions/Methods Reviewed:** 3 (TaskStats, calculateStatsFromIssues, test suites)
+- **Test Cases Added:** 8 new tests for phase-aware behavior
+- **Test Coverage:** All 1498 tests passing