[P1] State Sync Audit: Components with phase-awareness gaps

[frankbria]

Background

The TaskStats bug fix (PR #234, fixes #233) exposed a broader architectural pattern: components that use useAgentState() hook without considering project phase may show incorrect data during non-development phases.

This is the "late-joining user" scenario - when a user opens the Dashboard after certain actions have occurred, they may see stale or incorrect data because the component is looking at the wrong data source.

Root Cause

The application has two parallel data systems:

Data Source	Phase	Update Mechanism
REST API (issues endpoint)	Planning	HTTP polling/SWR
WebSocket (agent state)	Development/Review	Real-time push

Components that rely solely on one data source without phase awareness are vulnerable to showing incorrect data.

At-Risk Components (Audit Needed)

High Priority

Component	Risk	Current Behavior
AgentPanel	HIGH	May show "no agents" during planning when agents are planned but not yet active
ProgressIndicator	HIGH	May calculate 0% progress during planning phase
TaskTreeView	MEDIUM	May show empty tree if only reading agent state

Medium Priority

Component	Risk	Current Behavior
MetricsCharts / CostDashboard	LOW	Should show "Metrics available during development" during planning
QualityGates	LOW	Should show configured gates during planning (pending execution)

Pattern to Apply

Each affected component should follow the pattern established in PR #234:

interface ComponentProps {
  phase?: string;          // Current project phase
  issuesData?: IssuesResponse;  // REST API data for planning phase
}

function Component({ phase, issuesData }: ComponentProps) {
  const agentState = useAgentState();  // Always call (hooks rules)
  
  const data = useMemo(() => {
    if (phase === 'planning') {
      return calculateFromIssuesData(issuesData);
    }
    return agentState;  // development/review phases
  }, [phase, issuesData, agentState]);
}

Testing Strategy

Each component should have "late-joining user" tests that verify:

• Correct display during planning phase
• Correct display during development phase
• Smooth data source switching during phase transitions
• Graceful degradation when data is loading

Acceptance Criteria

• Audit all components using useAgentState() for phase-awareness
• Apply phase-aware pattern to high-priority components
• Add unit tests for phase-aware behavior
• Add E2E "late-joining user" tests for each fixed component
• Document pattern in architecture docs

Related

• Fixes: PR fix(ui): make TaskStats phase-aware to fix late-joining user bug #234 (TaskStats phase-aware fix - establishes the pattern)
• Parent Bug: [P0] Tasks do not display on the Task tab on project page #233 (Tasks do not display - now fixed by PR fix(ui): make TaskStats phase-aware to fix late-joining user bug #234)
• Related Testing: [P1] E2E Test cases with existing state issues #231 (E2E Test cases with existing state issues)
• Related Testing: [P0] Add State Reconciliation E2E Tests for All Features #227 (State Reconciliation E2E Tests - closed)

References

• Beads issue: codeframe-7pya
• Code review: docs/code-review/2026-01-08-taskstats-phase-awareness-review.md

[traycerai]

Plan

Observations

After auditing the codebase, the phase-awareness issue is more nuanced than initially described. Most "at-risk" components don't directly use useAgentState() but receive data as props from parent components (primarily file:web-ui/src/components/Dashboard.tsx). The core issue is that these components need phase-aware data sources, not necessarily phase-aware logic themselves. file:web-ui/src/components/tasks/TaskStats.tsx (PR #234) established the pattern: components should accept both phase and issuesData props to switch between REST API data (planning) and WebSocket data (development/review).

Approach

Apply a prop-based phase-awareness pattern rather than direct useAgentState() modifications. The Dashboard component will pass phase and issuesData props to child components, allowing them to select the appropriate data source. This maintains separation of concerns and follows the established TaskStats pattern. Given the P1 priority, high-priority components will be updated in parallel with comprehensive unit tests following the test patterns in file:web-ui/__tests__/components/tasks/TaskStats.test.tsx. The implementation will be split into two phases: immediate critical fixes (AgentPanel, ProgressIndicator, TaskTreeView) and follow-up enhancements (MetricsCharts, QualityGates).

Implementation Plan

1. Immediate Critical Fixes (Parallel Track)

Objective: Fix the three high-priority components identified in the ticket that directly impact user experience during late-join scenarios.

1.1 AgentPanel Phase-Awareness (CRITICAL)

File: file:web-ui/src/components/AgentList.tsx

Current State: Uses REST API getAgentsForProject(), may show "No agents assigned" during planning when agents are planned but not yet created.

Changes Required:

• Add phase?: string and issuesData?: IssuesResponse to AgentListProps
• During planning phase, show informational message instead of "No agents assigned":
  • "Agents will be created automatically when development begins"
  • Show count of planned tasks: "X tasks ready for agent assignment"
• Add conditional rendering:

  if (phase === 'planning' && (!assignments || assignments.length === 0)) {
    return <PlanningPhaseAgentMessage issuesData={issuesData} />;
  }

• Create PlanningPhaseAgentMessage component to display task count and phase-appropriate messaging

Testing:

• Add test file file:web-ui/__tests__/components/AgentList.test.tsx
• Test cases:
  • Planning phase shows planning message with task count
  • Development phase shows agent cards
  • Empty state during development shows "No agents assigned"
  • Phase transition updates messaging
• Add E2E test: "Late-joining user during planning sees agent assignment message"

Estimated Effort: 3 hours (code + unit tests + E2E test)

1.2 ProgressIndicator Phase-Awareness (CRITICAL)

File: file:web-ui/src/components/ProgressIndicator.tsx

Current State: Receives currentStep and totalSteps as props, may show 0% during planning if parent calculates from agent state.

Changes Required:

• Add phase?: string and issuesData?: IssuesResponse to ProgressIndicatorProps
• Add helper function calculateProgressFromIssuesData(issuesData) to compute completion percentage from issues/tasks
• Add useMemo to calculate progress:

  const { currentStep, totalSteps } = useMemo(() => {
    if (phase === 'planning' && issuesData) {
      return calculateProgressFromIssuesData(issuesData);
    }
    return { currentStep: currentStepProp, totalSteps: totalStepsProp };
  }, [phase, issuesData, currentStepProp, totalStepsProp]);

• Update Dashboard to pass phase-aware progress data

Testing:

• Add test file file:web-ui/__tests__/components/ProgressIndicator.test.tsx
• Test cases:
  • Planning phase calculates from issuesData
  • Development phase uses props from agent state
  • Zero-division protection when no tasks exist
  • Percentage clamped to 0-100 range
• Add E2E test: "Late-joining user during planning sees correct progress percentage"

Estimated Effort: 3 hours (code + unit tests + E2E test)

1.3 TaskTreeView Phase-Awareness (CRITICAL)

File: file:web-ui/src/components/TaskTreeView.tsx

Current State: May show empty tree if only reading agent state during planning phase.

Changes Required:

• Add explicit phase?: string and issuesData?: IssuesResponse props
• Add useMemo to select data source:

  const displayIssues = useMemo(() => {
    if (phase === 'planning' && issuesData?.issues) {
      return issuesData.issues;
    }
    return issuesProp || [];
  }, [phase, issuesData, issuesProp]);

• Update Dashboard to pass both props
• Ensure tree renders correctly with REST API data during planning

Testing:

• Review existing tests in file:web-ui/__tests__/components/TaskTreeView.test.tsx
• Add test cases:
  • Planning phase displays issues from issuesData
  • Development phase displays issues from props
  • Empty state handled gracefully in both phases
• Add E2E test: "Late-joining user during planning sees full task tree"

Estimated Effort: 2 hours (code + unit tests + E2E test)

2. Audit and Document Current State

Objective: Create a comprehensive audit document listing all components and their phase-awareness status.

• Review file:web-ui/src/components/Dashboard.tsx to identify all components that display task/agent/progress data
• Document which components use useAgentState() directly vs. receive props
• Create audit matrix in docs/architecture/phase-awareness-audit.md with columns:
  • Component name and file path
  • Data source (useAgentState, REST API, props)
  • Phase-awareness status (aware, not-aware, n/a)
  • Risk level (high, medium, low)
  • Action required (update, test-only, none)
• Identify any additional components beyond the three critical ones

Estimated Effort: 2 hours

3. Update Medium-Priority Components (Follow-up)

3.1 QualityGatesPanel Phase-Awareness

File: file:web-ui/src/components/quality-gates/QualityGatesPanel.tsx

Current State: Receives tasks prop from Dashboard's useAgentState(), showing empty during planning phase.

Changes Required:

• Add phase?: string and issuesData?: IssuesResponse to QualityGatesPanelProps interface
• Add helper function extractTasksFromIssuesData(issuesData) to flatten issues into task array matching Task[] from agentState
• Add useMemo to select data source:

  const tasks = useMemo(() => {
    if (phase === 'planning' && issuesData) {
      return extractTasksFromIssuesData(issuesData);
    }
    return tasksProp; // from useAgentState
  }, [phase, issuesData, tasksProp]);

• Update Dashboard to pass phase={normalizedPhase} and issuesData={issuesData} props
• During planning phase, show message: "Quality gates will be evaluated during development phase"

Testing:

• Add test file file:web-ui/__tests__/components/quality-gates/QualityGatesPanel.test.tsx
• Test cases:
  • Planning phase shows appropriate message
  • Development phase shows task selector with agent state tasks
  • Phase transition switches data sources correctly
  • Empty issuesData handled gracefully

Estimated Effort: 2 hours

3.2 CostDashboard Phase-Awareness

File: file:web-ui/src/components/metrics/CostDashboard.tsx

Current State: Uses REST API for metrics, only relevant during development phase.

Changes Required:

• Add phase?: string to CostDashboardProps
• During planning phase, show informational message:
  • "Cost metrics will be available during development phase"
  • "Metrics track LLM API usage and token consumption"
• Add conditional rendering at component start:

  if (phase === 'planning') {
    return <PlanningPhaseMetricsMessage />;
  }

Testing:

• Review existing tests in file:web-ui/__tests__/components/CostDashboard.test.tsx
• Add test cases:
  • Planning phase shows informational message
  • Development phase shows metrics dashboard
  • No API calls made during planning phase

Estimated Effort: 1.5 hours

4. Update Dashboard Component

File: file:web-ui/src/components/Dashboard.tsx

Changes Required:

• Pass phase={normalizedPhase} prop to all updated components:
  • <AgentList phase={normalizedPhase} issuesData={issuesData} projectId={projectId} />
  • <ProgressIndicator phase={normalizedPhase} issuesData={issuesData} ... />
  • <TaskTreeView phase={normalizedPhase} issuesData={issuesData} issues={issuesData?.issues || []} />
  • <TaskStats phase={normalizedPhase} issuesData={issuesData} />
  • <QualityGatesPanel phase={normalizedPhase} issuesData={issuesData} tasks={tasks} />
  • <CostDashboard phase={normalizedPhase} projectId={projectId} />
• Ensure issuesData from SWR is available to all child components
• Add comment documenting phase-aware prop passing pattern

Estimated Effort: 1 hour

5. Create Shared Utilities

File: file:web-ui/src/utils/phaseAwareData.ts (new file)

Purpose: Centralize phase-aware data transformation logic.

Functions to create:

• extractTasksFromIssuesData(issuesData: IssuesResponse): Task[] - Flatten issues into task array
• calculateProgressFromIssuesData(issuesData: IssuesResponse): { currentStep: number, totalSteps: number } - Calculate progress metrics
• isPhaseAwareComponent(phase: string): boolean - Check if phase requires special handling
• getPlanningPhaseMessage(componentType: string): string - Get appropriate planning phase message

Testing:

• Create test file file:web-ui/__tests__/utils/phaseAwareData.test.ts
• Test all utility functions with various data scenarios

Estimated Effort: 2 hours

6. Update Type Definitions

File: file:web-ui/src/types/api.ts

Changes Required:

• Ensure ProjectPhase type includes all phases: 'discovery' | 'planning' | 'development' | 'review' | 'complete' | 'shipped'
• Add JSDoc comments documenting phase-aware component pattern
• Consider adding PhaseAwareComponentProps interface:

  export interface PhaseAwareComponentProps {
    phase?: ProjectPhase;
    issuesData?: IssuesResponse;
  }

Estimated Effort: 0.5 hours

7. Documentation Updates

7.1 Architecture Documentation

File: docs/architecture/phase-awareness-pattern.md (new file)

Content:

• Overview of two-data-system architecture (REST API vs WebSocket)
• Phase-aware component pattern explanation
• Code examples from TaskStats implementation
• When to apply the pattern (decision tree)
• Testing strategy for phase-aware components
• Common pitfalls and solutions

7.2 Code Review Document Update

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

Changes:

• Add "Related Components" section listing all components that need similar updates
• Add reference to new architecture documentation
• Update "Future Considerations" section with links to this implementation plan

Estimated Effort: 1.5 hours

8. Testing Strategy

8.1 Unit Tests (Parallel with Component Updates)

For each updated component, add test suite following file:web-ui/__tests__/components/tasks/TaskStats.test.tsx pattern:

Test Categories:

• Planning Phase Tests:
  • Component uses issuesData when phase='planning'
  • Correct display with populated issuesData
  • Graceful handling of undefined issuesData
  • Appropriate messaging for planning phase
• Development Phase Tests:
  • Component uses agent state when phase='development'
  • Correct display with agent state data
  • Ignores issuesData during development
• Phase Transition Tests:
  • Data source switches correctly during phase change
  • No memory leaks or stale data
  • Smooth UI transition
• Backward Compatibility Tests:
  • Component works without phase prop (defaults to agent state)
  • Existing usages continue to function

Estimated Effort: Included in component updates (1-2 hours per component)

8.2 E2E "Late-Joining User" Tests

File: file:tests/e2e/test_phase_awareness.spec.ts (new file)

Test Scenarios (Critical):

• Late-joining user during planning phase sees correct agent assignment message
• Late-joining user during planning phase sees correct progress percentage
• Late-joining user during planning phase sees full task tree
• Late-joining user during development phase sees agent state data
• Phase transition from planning to development updates all components correctly

Estimated Effort: 3 hours

8.3 E2E Test Updates

File: file:tests/e2e/test_state_reconciliation.spec.ts

Changes:

• Add phase-awareness checks to existing state reconciliation tests
• Verify components show correct data source based on phase
• Test late-joining user scenario across all phases

Estimated Effort: 1 hour

9. Implementation Sequence (P1 Priority)

Phase 1: Critical Fixes (Days 1-2)

Parallel Tracks:
├── 1.1 AgentPanel (3 hours)
├── 1.2 ProgressIndicator (3 hours)
└── 1.3 TaskTreeView (2 hours)

Phase 2: Infrastructure (Day 2-3)

Sequential:
├── 2. Audit & Document (2 hours)
├── 5. Create Shared Utilities (2 hours)
└── 6. Update Type Definitions (0.5 hours)

Phase 3: Dashboard & Medium-Priority (Day 3)

Sequential:
├── 4. Update Dashboard Component (1 hour)
├── 3.1 QualityGatesPanel (2 hours)
└── 3.2 CostDashboard (1.5 hours)

Phase 4: Testing & Documentation (Day 4)

Parallel:
├── 8.2 E2E Late-Joining Tests (3 hours)
├── 8.3 E2E Test Updates (1 hour)
└── 7. Documentation Updates (1.5 hours)

Total Estimated Effort: 22-24 hours (compressed timeline for P1 priority)

10. Acceptance Criteria Verification

• CRITICAL: AgentPanel shows correct message during planning phase (late-join scenario)
• CRITICAL: ProgressIndicator shows correct percentage during planning phase (late-join scenario)
• CRITICAL: TaskTreeView displays full task tree during planning phase (late-join scenario)
• All components using useAgentState() audited and documented
• Dashboard passes phase and issuesData props to all relevant components
• Shared utility functions created and tested
• Unit tests added for each updated component (8+ tests per component)
• E2E "late-joining user" tests added for critical components
• Medium-priority components (QualityGatesPanel, CostDashboard) updated with phase-aware messaging
• Architecture documentation created explaining the pattern
• All existing tests continue to pass (backward compatibility maintained)
• Code review completed referencing file:docs/code-review/2026-01-08-taskstats-phase-awareness-review.md as pattern guide

Import In IDE

🤖 Prompt for AI Agents

## Observations

After auditing the codebase, the phase-awareness issue is more nuanced than initially described. Most "at-risk" components don't directly use `useAgentState()` but receive data as props from parent components (primarily `file:web-ui/src/components/Dashboard.tsx`). The core issue is that these components need phase-aware data sources, not necessarily phase-aware logic themselves. `file:web-ui/src/components/tasks/TaskStats.tsx` (PR #234) established the pattern: components should accept both `phase` and `issuesData` props to switch between REST API data (planning) and WebSocket data (development/review).

## Approach

Apply a **prop-based phase-awareness pattern** rather than direct `useAgentState()` modifications. The Dashboard component will pass `phase` and `issuesData` props to child components, allowing them to select the appropriate data source. This maintains separation of concerns and follows the established TaskStats pattern. Given the P1 priority, high-priority components will be updated in parallel with comprehensive unit tests following the test patterns in `file:web-ui/__tests__/components/tasks/TaskStats.test.tsx`. The implementation will be split into two phases: immediate critical fixes (AgentPanel, ProgressIndicator, TaskTreeView) and follow-up enhancements (MetricsCharts, QualityGates).

## Implementation Plan

### 1. Immediate Critical Fixes (Parallel Track)

**Objective:** Fix the three high-priority components identified in the ticket that directly impact user experience during late-join scenarios.

#### 1.1 AgentPanel Phase-Awareness (CRITICAL)

**File:** `file:web-ui/src/components/AgentList.tsx`

**Current State:** Uses REST API `getAgentsForProject()`, may show "No agents assigned" during planning when agents are planned but not yet created.

**Changes Required:**
- Add `phase?: string` and `issuesData?: IssuesResponse` to `AgentListProps`
- During planning phase, show informational message instead of "No agents assigned":
  - "Agents will be created automatically when development begins"
  - Show count of planned tasks: "X tasks ready for agent assignment"
- Add conditional rendering:
  ```typescript
  if (phase === 'planning' && (!assignments || assignments.length === 0)) {
    return <PlanningPhaseAgentMessage issuesData={issuesData} />;
  }
  ```
- Create `PlanningPhaseAgentMessage` component to display task count and phase-appropriate messaging

**Testing:**
- Add test file `file:web-ui/__tests__/components/AgentList.test.tsx`
- Test cases:
  - Planning phase shows planning message with task count
  - Development phase shows agent cards
  - Empty state during development shows "No agents assigned"
  - Phase transition updates messaging
- Add E2E test: "Late-joining user during planning sees agent assignment message"

**Estimated Effort:** 3 hours (code + unit tests + E2E test)

#### 1.2 ProgressIndicator Phase-Awareness (CRITICAL)

**File:** `file:web-ui/src/components/ProgressIndicator.tsx`

**Current State:** Receives `currentStep` and `totalSteps` as props, may show 0% during planning if parent calculates from agent state.

**Changes Required:**
- Add `phase?: string` and `issuesData?: IssuesResponse` to `ProgressIndicatorProps`
- Add helper function `calculateProgressFromIssuesData(issuesData)` to compute completion percentage from issues/tasks
- Add `useMemo` to calculate progress:
  ```typescript
  const { currentStep, totalSteps } = useMemo(() => {
    if (phase === 'planning' && issuesData) {
      return calculateProgressFromIssuesData(issuesData);
    }
    return { currentStep: currentStepProp, totalSteps: totalStepsProp };
  }, [phase, issuesData, currentStepProp, totalStepsProp]);
  ```
- Update Dashboard to pass phase-aware progress data

**Testing:**
- Add test file `file:web-ui/__tests__/components/ProgressIndicator.test.tsx`
- Test cases:
  - Planning phase calculates from issuesData
  - Development phase uses props from agent state
  - Zero-division protection when no tasks exist
  - Percentage clamped to 0-100 range
- Add E2E test: "Late-joining user during planning sees correct progress percentage"

**Estimated Effort:** 3 hours (code + unit tests + E2E test)

#### 1.3 TaskTreeView Phase-Awareness (CRITICAL)

**File:** `file:web-ui/src/components/TaskTreeView.tsx`

**Current State:** May show empty tree if only reading agent state during planning phase.

**Changes Required:**
- Add explicit `phase?: string` and `issuesData?: IssuesResponse` props
- Add `useMemo` to select data source:
  ```typescript
  const displayIssues = useMemo(() => {
    if (phase === 'planning' && issuesData?.issues) {
      return issuesData.issues;
    }
    return issuesProp || [];
  }, [phase, issuesData, issuesProp]);
  ```
- Update Dashboard to pass both props
- Ensure tree renders correctly with REST API data during planning

**Testing:**
- Review existing tests in `file:web-ui/__tests__/components/TaskTreeView.test.tsx`
- Add test cases:
  - Planning phase displays issues from issuesData
  - Development phase displays issues from props
  - Empty state handled gracefully in both phases
- Add E2E test: "Late-joining user during planning sees full task tree"

**Estimated Effort:** 2 hours (code + unit tests + E2E test)

### 2. Audit and Document Current State

**Objective:** Create a comprehensive audit document listing all components and their phase-awareness status.

- Review `file:web-ui/src/components/Dashboard.tsx` to identify all components that display task/agent/progress data
- Document which components use `useAgentState()` directly vs. receive props
- Create audit matrix in `docs/architecture/phase-awareness-audit.md` with columns:
  - Component name and file path
  - Data source (useAgentState, REST API, props)
  - Phase-awareness status (aware, not-aware, n/a)
  - Risk level (high, medium, low)
  - Action required (update, test-only, none)
- Identify any additional components beyond the three critical ones

**Estimated Effort:** 2 hours

### 3. Update Medium-Priority Components (Follow-up)

#### 3.1 QualityGatesPanel Phase-Awareness

**File:** `file:web-ui/src/components/quality-gates/QualityGatesPanel.tsx`

**Current State:** Receives `tasks` prop from Dashboard's `useAgentState()`, showing empty during planning phase.

**Changes Required:**
- Add `phase?: string` and `issuesData?: IssuesResponse` to `QualityGatesPanelProps` interface
- Add helper function `extractTasksFromIssuesData(issuesData)` to flatten issues into task array matching `Task[]` from agentState
- Add `useMemo` to select data source:
  ```typescript
  const tasks = useMemo(() => {
    if (phase === 'planning' && issuesData) {
      return extractTasksFromIssuesData(issuesData);
    }
    return tasksProp; // from useAgentState
  }, [phase, issuesData, tasksProp]);
  ```
- Update Dashboard to pass `phase={normalizedPhase}` and `issuesData={issuesData}` props
- During planning phase, show message: "Quality gates will be evaluated during development phase"

**Testing:**
- Add test file `file:web-ui/__tests__/components/quality-gates/QualityGatesPanel.test.tsx`
- Test cases:
  - Planning phase shows appropriate message
  - Development phase shows task selector with agent state tasks
  - Phase transition switches data sources correctly
  - Empty issuesData handled gracefully

**Estimated Effort:** 2 hours

#### 3.2 CostDashboard Phase-Awareness

**File:** `file:web-ui/src/components/metrics/CostDashboard.tsx`

**Current State:** Uses REST API for metrics, only relevant during development phase.

**Changes Required:**
- Add `phase?: string` to `CostDashboardProps`
- During planning phase, show informational message:
  - "Cost metrics will be available during development phase"
  - "Metrics track LLM API usage and token consumption"
- Add conditional rendering at component start:
  ```typescript
  if (phase === 'planning') {
    return <PlanningPhaseMetricsMessage />;
  }
  ```

**Testing:**
- Review existing tests in `file:web-ui/__tests__/components/CostDashboard.test.tsx`
- Add test cases:
  - Planning phase shows informational message
  - Development phase shows metrics dashboard
  - No API calls made during planning phase

**Estimated Effort:** 1.5 hours

### 4. Update Dashboard Component

**File:** `file:web-ui/src/components/Dashboard.tsx`

**Changes Required:**
- Pass `phase={normalizedPhase}` prop to all updated components:
  - `<AgentList phase={normalizedPhase} issuesData={issuesData} projectId={projectId} />`
  - `<ProgressIndicator phase={normalizedPhase} issuesData={issuesData} ... />`
  - `<TaskTreeView phase={normalizedPhase} issuesData={issuesData} issues={issuesData?.issues || []} />`
  - `<TaskStats phase={normalizedPhase} issuesData={issuesData} />`
  - `<QualityGatesPanel phase={normalizedPhase} issuesData={issuesData} tasks={tasks} />`
  - `<CostDashboard phase={normalizedPhase} projectId={projectId} />`
- Ensure `issuesData` from SWR is available to all child components
- Add comment documenting phase-aware prop passing pattern

**Estimated Effort:** 1 hour

### 5. Create Shared Utilities

**File:** `file:web-ui/src/utils/phaseAwareData.ts` (new file)

**Purpose:** Centralize phase-aware data transformation logic.

**Functions to create:**
- `extractTasksFromIssuesData(issuesData: IssuesResponse): Task[]` - Flatten issues into task array
- `calculateProgressFromIssuesData(issuesData: IssuesResponse): { currentStep: number, totalSteps: number }` - Calculate progress metrics
- `isPhaseAwareComponent(phase: string): boolean` - Check if phase requires special handling
- `getPlanningPhaseMessage(componentType: string): string` - Get appropriate planning phase message

**Testing:**
- Create test file `file:web-ui/__tests__/utils/phaseAwareData.test.ts`
- Test all utility functions with various data scenarios

**Estimated Effort:** 2 hours

### 6. Update Type Definitions

**File:** `file:web-ui/src/types/api.ts`

**Changes Required:**
- Ensure `ProjectPhase` type includes all phases: `'discovery' | 'planning' | 'development' | 'review' | 'complete' | 'shipped'`
- Add JSDoc comments documenting phase-aware component pattern
- Consider adding `PhaseAwareComponentProps` interface:
  ```typescript
  export interface PhaseAwareComponentProps {
    phase?: ProjectPhase;
    issuesData?: IssuesResponse;
  }
  ```

**Estimated Effort:** 0.5 hours

### 7. Documentation Updates

#### 7.1 Architecture Documentation

**File:** `docs/architecture/phase-awareness-pattern.md` (new file)

**Content:**
- Overview of two-data-system architecture (REST API vs WebSocket)
- Phase-aware component pattern explanation
- Code examples from TaskStats implementation
- When to apply the pattern (decision tree)
- Testing strategy for phase-aware components
- Common pitfalls and solutions

#### 7.2 Code Review Document Update

**File:** `file:docs/code-review/2026-01-08-taskstats-phase-awareness-review.md`

**Changes:**
- Add "Related Components" section listing all components that need similar updates
- Add reference to new architecture documentation
- Update "Future Considerations" section with links to this implementation plan

**Estimated Effort:** 1.5 hours

### 8. Testing Strategy

#### 8.1 Unit Tests (Parallel with Component Updates)

For each updated component, add test suite following `file:web-ui/__tests__/components/tasks/TaskStats.test.tsx` pattern:

**Test Categories:**
- **Planning Phase Tests:**
  - Component uses issuesData when phase='planning'
  - Correct display with populated issuesData
  - Graceful handling of undefined issuesData
  - Appropriate messaging for planning phase
- **Development Phase Tests:**
  - Component uses agent state when phase='development'
  - Correct display with agent state data
  - Ignores issuesData during development
- **Phase Transition Tests:**
  - Data source switches correctly during phase change
  - No memory leaks or stale data
  - Smooth UI transition
- **Backward Compatibility Tests:**
  - Component works without phase prop (defaults to agent state)
  - Existing usages continue to function

**Estimated Effort:** Included in component updates (1-2 hours per component)

#### 8.2 E2E "Late-Joining User" Tests

**File:** `file:tests/e2e/test_phase_awareness.spec.ts` (new file)

**Test Scenarios (Critical):**
- Late-joining user during planning phase sees correct agent assignment message
- Late-joining user during planning phase sees correct progress percentage
- Late-joining user during planning phase sees full task tree
- Late-joining user during development phase sees agent state data
- Phase transition from planning to development updates all components correctly

**Estimated Effort:** 3 hours

#### 8.3 E2E Test Updates

**File:** `file:tests/e2e/test_state_reconciliation.spec.ts`

**Changes:**
- Add phase-awareness checks to existing state reconciliation tests
- Verify components show correct data source based on phase
- Test late-joining user scenario across all phases

**Estimated Effort:** 1 hour

### 9. Implementation Sequence (P1 Priority)

**Phase 1: Critical Fixes (Days 1-2)**
```
Parallel Tracks:
├── 1.1 AgentPanel (3 hours)
├── 1.2 ProgressIndicator (3 hours)
└── 1.3 TaskTreeView (2 hours)
```

**Phase 2: Infrastructure (Day 2-3)**
```
Sequential:
├── 2. Audit & Document (2 hours)
├── 5. Create Shared Utilities (2 hours)
└── 6. Update Type Definitions (0.5 hours)
```

**Phase 3: Dashboard & Medium-Priority (Day 3)**
```
Sequential:
├── 4. Update Dashboard Component (1 hour)
├── 3.1 QualityGatesPanel (2 hours)
└── 3.2 CostDashboard (1.5 hours)
```

**Phase 4: Testing & Documentation (Day 4)**
```
Parallel:
├── 8.2 E2E Late-Joining Tests (3 hours)
├── 8.3 E2E Test Updates (1 hour)
└── 7. Documentation Updates (1.5 hours)
```

**Total Estimated Effort:** 22-24 hours (compressed timeline for P1 priority)

### 10. Acceptance Criteria Verification

- [ ] **CRITICAL:** AgentPanel shows correct message during planning phase (late-join scenario)
- [ ] **CRITICAL:** ProgressIndicator shows correct percentage during planning phase (late-join scenario)
- [ ] **CRITICAL:** TaskTreeView displays full task tree during planning phase (late-join scenario)
- [ ] All components using `useAgentState()` audited and documented
- [ ] Dashboard passes `phase` and `issuesData` props to all relevant components
- [ ] Shared utility functions created and tested
- [ ] Unit tests added for each updated component (8+ tests per component)
- [ ] E2E "late-joining user" tests added for critical components
- [ ] Medium-priority components (QualityGatesPanel, CostDashboard) updated with phase-aware messaging
- [ ] Architecture documentation created explaining the pattern
- [ ] All existing tests continue to pass (backward compatibility maintained)
- [ ] Code review completed referencing `file:docs/code-review/2026-01-08-taskstats-phase-awareness-review.md` as pattern guide

---

Execution Information

Branch: main
Commit: 1edac57

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#10 - feat(frontend): Multi-Agent State Management with React Context [merged]
#211 - feat(dashboard): Add PhaseProgress component for phase visualization [merged]
#215 - feat(dashboard): Add phase-aware task view integration (#16-6) [merged]
#229 - feat(e2e): add state reconciliation tests for late-joining users [closed]
#234 - fix(ui): make TaskStats phase-aware to fix late-joining user bug [closed]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

Previous Plan

Observations

After auditing the codebase, the phase-awareness issue is more nuanced than initially described. Most "at-risk" components don't directly use useAgentState() but receive data as props from parent components (primarily file:web-ui/src/components/Dashboard.tsx). The core issue is that these components need phase-aware data sources, not necessarily phase-aware logic themselves. file:web-ui/src/components/tasks/TaskStats.tsx (PR #234) established the pattern: components should accept both phase and issuesData props to switch between REST API data (planning) and WebSocket data (development/review).

Approach

Apply a prop-based phase-awareness pattern rather than direct useAgentState() modifications. The Dashboard component will pass phase and issuesData props to child components, allowing them to select the appropriate data source. This maintains separation of concerns and follows the established TaskStats pattern. High-priority components will be updated first, with comprehensive unit tests following the test patterns in file:web-ui/__tests__/components/tasks/TaskStats.test.tsx.

Implementation Plan

1. Audit and Document Current State

Objective: Create a comprehensive audit document listing all components and their phase-awareness status.

• Review file:web-ui/src/components/Dashboard.tsx to identify all components that display task/agent/progress data
• Document which components use useAgentState() directly vs. receive props
• Create audit matrix in docs/architecture/phase-awareness-audit.md with columns:
  • Component name and file path
  • Data source (useAgentState, REST API, props)
  • Phase-awareness status (aware, not-aware, n/a)
  • Risk level (high, medium, low)
  • Action required (update, test-only, none)

2. Update High-Priority Components

2.1 QualityGatesPanel Phase-Awareness

File: file:web-ui/src/components/quality-gates/QualityGatesPanel.tsx

Current State: Receives tasks prop from Dashboard's useAgentState(), showing empty during planning phase.

Changes Required:

• Add phase?: string and issuesData?: IssuesResponse to QualityGatesPanelProps interface
• Add helper function extractTasksFromIssuesData(issuesData) to flatten issues into task array matching Task[] from agentState
• Add useMemo to select data source:

  const tasks = useMemo(() => {
    if (phase === 'planning' && issuesData) {
      return extractTasksFromIssuesData(issuesData);
    }
    return tasksProp; // from useAgentState
  }, [phase, issuesData, tasksProp]);

• Update Dashboard to pass phase={normalizedPhase} and issuesData={issuesData} props
• During planning phase, show message: "Quality gates will be evaluated during development phase"

Testing:

• Add test file file:web-ui/__tests__/components/quality-gates/QualityGatesPanel.test.tsx
• Test cases:
  • Planning phase shows appropriate message
  • Development phase shows task selector with agent state tasks
  • Phase transition switches data sources correctly
  • Empty issuesData handled gracefully

2.2 PhaseProgress Component Enhancement

File: file:web-ui/src/components/PhaseProgress.tsx

Current State: Receives currentStep and totalSteps as props, may show 0% during planning if parent calculates from agent state.

Changes Required:

• Add phase?: string and issuesData?: IssuesResponse to PhaseProgressProps
• Add helper function calculateProgressFromIssuesData(issuesData) to compute completion percentage from issues/tasks
• Add useMemo to calculate progress:

  const { currentStep, totalSteps } = useMemo(() => {
    if (phase === 'planning' && issuesData) {
      return calculateProgressFromIssuesData(issuesData);
    }
    return { currentStep: currentStepProp, totalSteps: totalStepsProp };
  }, [phase, issuesData, currentStepProp, totalStepsProp]);

• Update Dashboard to pass phase-aware progress data

Testing:

• Add test file file:web-ui/__tests__/components/PhaseProgress.test.tsx
• Test cases:
  • Planning phase calculates from issuesData
  • Development phase uses props from agent state
  • Zero-division protection when no tasks exist
  • Percentage clamped to 0-100 range

2.3 AgentList Component (AgentPanel)

File: file:web-ui/src/components/AgentList.tsx

Current State: Uses REST API getAgentsForProject(), may show "No agents assigned" during planning when agents are planned but not yet created.

Changes Required:

• Add phase?: string and issuesData?: IssuesResponse to AgentListProps
• During planning phase, show informational message instead of "No agents assigned":
  • "Agents will be created automatically when development begins"
  • Show count of planned tasks: "X tasks ready for agent assignment"
• Add conditional rendering:

  if (phase === 'planning' && (!assignments || assignments.length === 0)) {
    return <PlanningPhaseAgentMessage issuesData={issuesData} />;
  }

• Create PlanningPhaseAgentMessage component to display task count and phase-appropriate messaging

Testing:

• Add test file file:web-ui/__tests__/components/AgentList.test.tsx
• Test cases:
  • Planning phase shows planning message with task count
  • Development phase shows agent cards
  • Empty state during development shows "No agents assigned"
  • Phase transition updates messaging

3. Update Medium-Priority Components

3.1 TaskTreeView Phase-Awareness

File: file:web-ui/src/components/TaskTreeView.tsx

Current State: Already receives issues prop from REST API, inherently phase-aware.

Changes Required:

• Add explicit phase?: string prop for clarity
• Add JSDoc comment documenting phase-awareness
• No logic changes needed (already uses REST API data)

Testing:

• Review existing tests in file:web-ui/__tests__/components/TaskTreeView.test.tsx
• Add test case verifying component works in both planning and development phases

3.2 CostDashboard Phase-Awareness

File: file:web-ui/src/components/metrics/CostDashboard.tsx

Current State: Uses REST API for metrics, only relevant during development phase.

Changes Required:

• Add phase?: string to CostDashboardProps
• During planning phase, show informational message:
  • "Cost metrics will be available during development phase"
  • "Metrics track LLM API usage and token consumption"
• Add conditional rendering at component start:

  if (phase === 'planning') {
    return <PlanningPhaseMetricsMessage />;
  }

Testing:

• Review existing tests in file:web-ui/__tests__/components/CostDashboard.test.tsx
• Add test cases:
  • Planning phase shows informational message
  • Development phase shows metrics dashboard
  • No API calls made during planning phase

4. Update Dashboard Component

File: file:web-ui/src/components/Dashboard.tsx

Changes Required:

• Pass phase={normalizedPhase} prop to all updated components:
  • <TaskStats phase={normalizedPhase} issuesData={issuesData} />
  • <QualityGatesPanel phase={normalizedPhase} issuesData={issuesData} tasks={tasks} />
  • <PhaseProgress phase={normalizedPhase} issuesData={issuesData} ... />
  • <AgentList phase={normalizedPhase} issuesData={issuesData} projectId={projectId} />
  • <CostDashboard phase={normalizedPhase} projectId={projectId} />
  • <TaskTreeView phase={normalizedPhase} issues={issuesData?.issues || []} />
• Ensure issuesData from SWR is available to all child components
• Add comment documenting phase-aware prop passing pattern

5. Create Shared Utilities

File: file:web-ui/src/utils/phaseAwareData.ts (new file)

Purpose: Centralize phase-aware data transformation logic.

Functions to create:

• extractTasksFromIssuesData(issuesData: IssuesResponse): Task[] - Flatten issues into task array
• calculateProgressFromIssuesData(issuesData: IssuesResponse): { currentStep: number, totalSteps: number } - Calculate progress metrics
• isPhaseAwareComponent(phase: string): boolean - Check if phase requires special handling
• getPlanningPhaseMessage(componentType: string): string - Get appropriate planning phase message

Testing:

• Create test file file:web-ui/__tests__/utils/phaseAwareData.test.ts
• Test all utility functions with various data scenarios

6. Update Type Definitions

File: file:web-ui/src/types/api.ts

Changes Required:

• Ensure ProjectPhase type includes all phases: 'discovery' | 'planning' | 'development' | 'review' | 'complete' | 'shipped'
• Add JSDoc comments documenting phase-aware component pattern
• Consider adding PhaseAwareComponentProps interface:

  export interface PhaseAwareComponentProps {
    phase?: ProjectPhase;
    issuesData?: IssuesResponse;
  }

7. Documentation Updates

7.1 Architecture Documentation

File: docs/architecture/phase-awareness-pattern.md (new file)

Content:

• Overview of two-data-system architecture (REST API vs WebSocket)
• Phase-aware component pattern explanation
• Code examples from TaskStats implementation
• When to apply the pattern (decision tree)
• Testing strategy for phase-aware components
• Common pitfalls and solutions

7.2 Code Review Document Update

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

Changes:

• Add "Related Components" section listing all components that need similar updates
• Add reference to new architecture documentation
• Update "Future Considerations" section with links to this implementation plan

8. Testing Strategy

8.1 Unit Tests

For each updated component, add test suite following file:web-ui/__tests__/components/tasks/TaskStats.test.tsx pattern:

Test Categories:

• Planning Phase Tests:
  • Component uses issuesData when phase='planning'
  • Correct display with populated issuesData
  • Graceful handling of undefined issuesData
  • Appropriate messaging for planning phase
• Development Phase Tests:
  • Component uses agent state when phase='development'
  • Correct display with agent state data
  • Ignores issuesData during development
• Phase Transition Tests:
  • Data source switches correctly during phase change
  • No memory leaks or stale data
  • Smooth UI transition
• Backward Compatibility Tests:
  • Component works without phase prop (defaults to agent state)
  • Existing usages continue to function

8.2 Integration Tests

File: file:tests/e2e/test_phase_awareness.spec.ts (new file)

Test Scenarios:

• Late-joining user during planning phase sees correct task counts
• Late-joining user during development phase sees agent state
• Phase transition from planning to development updates all components
• Dashboard tabs show correct data in each phase
• Quality gates show appropriate message during planning

8.3 E2E Test Updates

File: file:tests/e2e/test_state_reconciliation.spec.ts

Changes:

• Add phase-awareness checks to existing state reconciliation tests
• Verify components show correct data source based on phase
• Test late-joining user scenario across all phases

9. Implementation Sequence

graph TD
    A[1. Audit & Document] --> B[2. Create Shared Utilities]
    B --> C[3. Update Type Definitions]
    C --> D[4. Update High-Priority Components]
    D --> E[5. Update Dashboard Props]
    E --> F[6. Add Unit Tests]
    F --> G[7. Update Medium-Priority Components]
    G --> H[8. Add Integration Tests]
    H --> I[9. Update Documentation]
    I --> J[10. Code Review & Merge]

Loading

Estimated Effort per Component:

• High-priority components: 2-3 hours each (code + tests)
• Medium-priority components: 1-2 hours each (code + tests)
• Shared utilities: 2 hours
• Documentation: 2 hours
• Integration tests: 3 hours

Total Estimated Effort: 15-20 hours

10. Acceptance Criteria Verification

• All components using useAgentState() audited and documented
• High-priority components (QualityGatesPanel, PhaseProgress, AgentList) updated with phase-aware pattern
• Medium-priority components (TaskTreeView, CostDashboard) updated with phase-aware messaging
• Dashboard passes phase and issuesData props to all relevant components
• Shared utility functions created and tested
• Unit tests added for each updated component (8+ tests per component)
• Integration tests added for late-joining user scenarios
• Architecture documentation created explaining the pattern
• All existing tests continue to pass (backward compatibility maintained)
• Code review completed referencing file:docs/code-review/2026-01-08-taskstats-phase-awareness-review.md as pattern guide

Import In IDE

🤖 Prompt for AI Agents

## Observations

After auditing the codebase, the phase-awareness issue is more nuanced than initially described. Most "at-risk" components don't directly use `useAgentState()` but receive data as props from parent components (primarily `file:web-ui/src/components/Dashboard.tsx`). The core issue is that these components need phase-aware data sources, not necessarily phase-aware logic themselves. `file:web-ui/src/components/tasks/TaskStats.tsx` (PR #234) established the pattern: components should accept both `phase` and `issuesData` props to switch between REST API data (planning) and WebSocket data (development/review).

## Approach

Apply a **prop-based phase-awareness pattern** rather than direct `useAgentState()` modifications. The Dashboard component will pass `phase` and `issuesData` props to child components, allowing them to select the appropriate data source. This maintains separation of concerns and follows the established TaskStats pattern. High-priority components will be updated first, with comprehensive unit tests following the test patterns in `file:web-ui/__tests__/components/tasks/TaskStats.test.tsx`.

## Implementation Plan

### 1. Audit and Document Current State

**Objective:** Create a comprehensive audit document listing all components and their phase-awareness status.

- Review `file:web-ui/src/components/Dashboard.tsx` to identify all components that display task/agent/progress data
- Document which components use `useAgentState()` directly vs. receive props
- Create audit matrix in `docs/architecture/phase-awareness-audit.md` with columns:
  - Component name and file path
  - Data source (useAgentState, REST API, props)
  - Phase-awareness status (aware, not-aware, n/a)
  - Risk level (high, medium, low)
  - Action required (update, test-only, none)

### 2. Update High-Priority Components

#### 2.1 QualityGatesPanel Phase-Awareness

**File:** `file:web-ui/src/components/quality-gates/QualityGatesPanel.tsx`

**Current State:** Receives `tasks` prop from Dashboard's `useAgentState()`, showing empty during planning phase.

**Changes Required:**
- Add `phase?: string` and `issuesData?: IssuesResponse` to `QualityGatesPanelProps` interface
- Add helper function `extractTasksFromIssuesData(issuesData)` to flatten issues into task array matching `Task[]` from agentState
- Add `useMemo` to select data source:
  ```typescript
  const tasks = useMemo(() => {
    if (phase === 'planning' && issuesData) {
      return extractTasksFromIssuesData(issuesData);
    }
    return tasksProp; // from useAgentState
  }, [phase, issuesData, tasksProp]);
  ```
- Update Dashboard to pass `phase={normalizedPhase}` and `issuesData={issuesData}` props
- During planning phase, show message: "Quality gates will be evaluated during development phase"

**Testing:**
- Add test file `file:web-ui/__tests__/components/quality-gates/QualityGatesPanel.test.tsx`
- Test cases:
  - Planning phase shows appropriate message
  - Development phase shows task selector with agent state tasks
  - Phase transition switches data sources correctly
  - Empty issuesData handled gracefully

#### 2.2 PhaseProgress Component Enhancement

**File:** `file:web-ui/src/components/PhaseProgress.tsx`

**Current State:** Receives `currentStep` and `totalSteps` as props, may show 0% during planning if parent calculates from agent state.

**Changes Required:**
- Add `phase?: string` and `issuesData?: IssuesResponse` to `PhaseProgressProps`
- Add helper function `calculateProgressFromIssuesData(issuesData)` to compute completion percentage from issues/tasks
- Add `useMemo` to calculate progress:
  ```typescript
  const { currentStep, totalSteps } = useMemo(() => {
    if (phase === 'planning' && issuesData) {
      return calculateProgressFromIssuesData(issuesData);
    }
    return { currentStep: currentStepProp, totalSteps: totalStepsProp };
  }, [phase, issuesData, currentStepProp, totalStepsProp]);
  ```
- Update Dashboard to pass phase-aware progress data

**Testing:**
- Add test file `file:web-ui/__tests__/components/PhaseProgress.test.tsx`
- Test cases:
  - Planning phase calculates from issuesData
  - Development phase uses props from agent state
  - Zero-division protection when no tasks exist
  - Percentage clamped to 0-100 range

#### 2.3 AgentList Component (AgentPanel)

**File:** `file:web-ui/src/components/AgentList.tsx`

**Current State:** Uses REST API `getAgentsForProject()`, may show "No agents assigned" during planning when agents are planned but not yet created.

**Changes Required:**
- Add `phase?: string` and `issuesData?: IssuesResponse` to `AgentListProps`
- During planning phase, show informational message instead of "No agents assigned":
  - "Agents will be created automatically when development begins"
  - Show count of planned tasks: "X tasks ready for agent assignment"
- Add conditional rendering:
  ```typescript
  if (phase === 'planning' && (!assignments || assignments.length === 0)) {
    return <PlanningPhaseAgentMessage issuesData={issuesData} />;
  }
  ```
- Create `PlanningPhaseAgentMessage` component to display task count and phase-appropriate messaging

**Testing:**
- Add test file `file:web-ui/__tests__/components/AgentList.test.tsx`
- Test cases:
  - Planning phase shows planning message with task count
  - Development phase shows agent cards
  - Empty state during development shows "No agents assigned"
  - Phase transition updates messaging

### 3. Update Medium-Priority Components

#### 3.1 TaskTreeView Phase-Awareness

**File:** `file:web-ui/src/components/TaskTreeView.tsx`

**Current State:** Already receives `issues` prop from REST API, inherently phase-aware.

**Changes Required:**
- Add explicit `phase?: string` prop for clarity
- Add JSDoc comment documenting phase-awareness
- No logic changes needed (already uses REST API data)

**Testing:**
- Review existing tests in `file:web-ui/__tests__/components/TaskTreeView.test.tsx`
- Add test case verifying component works in both planning and development phases

#### 3.2 CostDashboard Phase-Awareness

**File:** `file:web-ui/src/components/metrics/CostDashboard.tsx`

**Current State:** Uses REST API for metrics, only relevant during development phase.

**Changes Required:**
- Add `phase?: string` to `CostDashboardProps`
- During planning phase, show informational message:
  - "Cost metrics will be available during development phase"
  - "Metrics track LLM API usage and token consumption"
- Add conditional rendering at component start:
  ```typescript
  if (phase === 'planning') {
    return <PlanningPhaseMetricsMessage />;
  }
  ```

**Testing:**
- Review existing tests in `file:web-ui/__tests__/components/CostDashboard.test.tsx`
- Add test cases:
  - Planning phase shows informational message
  - Development phase shows metrics dashboard
  - No API calls made during planning phase

### 4. Update Dashboard Component

**File:** `file:web-ui/src/components/Dashboard.tsx`

**Changes Required:**
- Pass `phase={normalizedPhase}` prop to all updated components:
  - `<TaskStats phase={normalizedPhase} issuesData={issuesData} />`
  - `<QualityGatesPanel phase={normalizedPhase} issuesData={issuesData} tasks={tasks} />`
  - `<PhaseProgress phase={normalizedPhase} issuesData={issuesData} ... />`
  - `<AgentList phase={normalizedPhase} issuesData={issuesData} projectId={projectId} />`
  - `<CostDashboard phase={normalizedPhase} projectId={projectId} />`
  - `<TaskTreeView phase={normalizedPhase} issues={issuesData?.issues || []} />`
- Ensure `issuesData` from SWR is available to all child components
- Add comment documenting phase-aware prop passing pattern

### 5. Create Shared Utilities

**File:** `file:web-ui/src/utils/phaseAwareData.ts` (new file)

**Purpose:** Centralize phase-aware data transformation logic.

**Functions to create:**
- `extractTasksFromIssuesData(issuesData: IssuesResponse): Task[]` - Flatten issues into task array
- `calculateProgressFromIssuesData(issuesData: IssuesResponse): { currentStep: number, totalSteps: number }` - Calculate progress metrics
- `isPhaseAwareComponent(phase: string): boolean` - Check if phase requires special handling
- `getPlanningPhaseMessage(componentType: string): string` - Get appropriate planning phase message

**Testing:**
- Create test file `file:web-ui/__tests__/utils/phaseAwareData.test.ts`
- Test all utility functions with various data scenarios

### 6. Update Type Definitions

**File:** `file:web-ui/src/types/api.ts`

**Changes Required:**
- Ensure `ProjectPhase` type includes all phases: `'discovery' | 'planning' | 'development' | 'review' | 'complete' | 'shipped'`
- Add JSDoc comments documenting phase-aware component pattern
- Consider adding `PhaseAwareComponentProps` interface:
  ```typescript
  export interface PhaseAwareComponentProps {
    phase?: ProjectPhase;
    issuesData?: IssuesResponse;
  }
  ```

### 7. Documentation Updates

#### 7.1 Architecture Documentation

**File:** `docs/architecture/phase-awareness-pattern.md` (new file)

**Content:**
- Overview of two-data-system architecture (REST API vs WebSocket)
- Phase-aware component pattern explanation
- Code examples from TaskStats implementation
- When to apply the pattern (decision tree)
- Testing strategy for phase-aware components
- Common pitfalls and solutions

#### 7.2 Code Review Document Update

**File:** `file:docs/code-review/2026-01-08-taskstats-phase-awareness-review.md`

**Changes:**
- Add "Related Components" section listing all components that need similar updates
- Add reference to new architecture documentation
- Update "Future Considerations" section with links to this implementation plan

### 8. Testing Strategy

#### 8.1 Unit Tests

For each updated component, add test suite following `file:web-ui/__tests__/components/tasks/TaskStats.test.tsx` pattern:

**Test Categories:**
- **Planning Phase Tests:**
  - Component uses issuesData when phase='planning'
  - Correct display with populated issuesData
  - Graceful handling of undefined issuesData
  - Appropriate messaging for planning phase
- **Development Phase Tests:**
  - Component uses agent state when phase='development'
  - Correct display with agent state data
  - Ignores issuesData during development
- **Phase Transition Tests:**
  - Data source switches correctly during phase change
  - No memory leaks or stale data
  - Smooth UI transition
- **Backward Compatibility Tests:**
  - Component works without phase prop (defaults to agent state)
  - Existing usages continue to function

#### 8.2 Integration Tests

**File:** `file:tests/e2e/test_phase_awareness.spec.ts` (new file)

**Test Scenarios:**
- Late-joining user during planning phase sees correct task counts
- Late-joining user during development phase sees agent state
- Phase transition from planning to development updates all components
- Dashboard tabs show correct data in each phase
- Quality gates show appropriate message during planning

#### 8.3 E2E Test Updates

**File:** `file:tests/e2e/test_state_reconciliation.spec.ts`

**Changes:**
- Add phase-awareness checks to existing state reconciliation tests
- Verify components show correct data source based on phase
- Test late-joining user scenario across all phases

### 9. Implementation Sequence

```mermaid
graph TD
    A[1. Audit & Document] --> B[2. Create Shared Utilities]
    B --> C[3. Update Type Definitions]
    C --> D[4. Update High-Priority Components]
    D --> E[5. Update Dashboard Props]
    E --> F[6. Add Unit Tests]
    F --> G[7. Update Medium-Priority Components]
    G --> H[8. Add Integration Tests]
    H --> I[9. Update Documentation]
    I --> J[10. Code Review & Merge]
```

**Estimated Effort per Component:**
- High-priority components: 2-3 hours each (code + tests)
- Medium-priority components: 1-2 hours each (code + tests)
- Shared utilities: 2 hours
- Documentation: 2 hours
- Integration tests: 3 hours

**Total Estimated Effort:** 15-20 hours

### 10. Acceptance Criteria Verification

- [ ] All components using `useAgentState()` audited and documented
- [ ] High-priority components (QualityGatesPanel, PhaseProgress, AgentList) updated with phase-aware pattern
- [ ] Medium-priority components (TaskTreeView, CostDashboard) updated with phase-aware messaging
- [ ] Dashboard passes `phase` and `issuesData` props to all relevant components
- [ ] Shared utility functions created and tested
- [ ] Unit tests added for each updated component (8+ tests per component)
- [ ] Integration tests added for late-joining user scenarios
- [ ] Architecture documentation created explaining the pattern
- [ ] All existing tests continue to pass (backward compatibility maintained)
- [ ] Code review completed referencing `file:docs/code-review/2026-01-08-taskstats-phase-awareness-review.md` as pattern guide

---

Execution Information

Branch: main
Commit: 1edac57

New Plan

Observations

After auditing the codebase, the phase-awareness issue is more nuanced than initially described. Most "at-risk" components don't directly use useAgentState() but receive data as props from parent components (primarily file:web-ui/src/components/Dashboard.tsx). The core issue is that these components need phase-aware data sources, not necessarily phase-aware logic themselves. file:web-ui/src/components/tasks/TaskStats.tsx (PR #234) established the pattern: components should accept both phase and issuesData props to switch between REST API data (planning) and WebSocket data (development/review).

Approach

Apply a prop-based phase-awareness pattern rather than direct useAgentState() modifications. The Dashboard component will pass phase and issuesData props to child components, allowing them to select the appropriate data source. This maintains separation of concerns and follows the established TaskStats pattern. Given the P1 priority, high-priority components will be updated in parallel with comprehensive unit tests following the test patterns in file:web-ui/__tests__/components/tasks/TaskStats.test.tsx. The implementation will be split into two phases: immediate critical fixes (AgentPanel, ProgressIndicator, TaskTreeView) and follow-up enhancements (MetricsCharts, QualityGates).

Implementation Plan

1. Immediate Critical Fixes (Parallel Track)

Objective: Fix the three high-priority components identified in the ticket that directly impact user experience during late-join scenarios.

1.1 AgentPanel Phase-Awareness (CRITICAL)

File: file:web-ui/src/components/AgentList.tsx

Current State: Uses REST API getAgentsForProject(), may show "No agents assigned" during planning when agents are planned but not yet created.

Changes Required:

• Add phase?: string and issuesData?: IssuesResponse to AgentListProps
• During planning phase, show informational message instead of "No agents assigned":
  • "Agents will be created automatically when development begins"
  • Show count of planned tasks: "X tasks ready for agent assignment"
• Add conditional rendering:

  if (phase === 'planning' && (!assignments || assignments.length === 0)) {
    return <PlanningPhaseAgentMessage issuesData={issuesData} />;
  }

• Create PlanningPhaseAgentMessage component to display task count and phase-appropriate messaging

Testing:

• Add test file file:web-ui/__tests__/components/AgentList.test.tsx
• Test cases:
  • Planning phase shows planning message with task count
  • Development phase shows agent cards
  • Empty state during development shows "No agents assigned"
  • Phase transition updates messaging
• Add E2E test: "Late-joining user during planning sees agent assignment message"

Estimated Effort: 3 hours (code + unit tests + E2E test)

1.2 ProgressIndicator Phase-Awareness (CRITICAL)

File: file:web-ui/src/components/ProgressIndicator.tsx

Current State: Receives currentStep and totalSteps as props, may show 0% during planning if parent calculates from agent state.

Changes Required:

• Add phase?: string and issuesData?: IssuesResponse to ProgressIndicatorProps
• Add helper function calculateProgressFromIssuesData(issuesData) to compute completion percentage from issues/tasks
• Add useMemo to calculate progress:

  const { currentStep, totalSteps } = useMemo(() => {
    if (phase === 'planning' && issuesData) {
      return calculateProgressFromIssuesData(issuesData);
    }
    return { currentStep: currentStepProp, totalSteps: totalStepsProp };
  }, [phase, issuesData, currentStepProp, totalStepsProp]);

• Update Dashboard to pass phase-aware progress data

Testing:

• Add test file file:web-ui/__tests__/components/ProgressIndicator.test.tsx
• Test cases:
  • Planning phase calculates from issuesData
  • Development phase uses props from agent state
  • Zero-division protection when no tasks exist
  • Percentage clamped to 0-100 range
• Add E2E test: "Late-joining user during planning sees correct progress percentage"

Estimated Effort: 3 hours (code + unit tests + E2E test)

1.3 TaskTreeView Phase-Awareness (CRITICAL)

File: file:web-ui/src/components/TaskTreeView.tsx

Current State: May show empty tree if only reading agent state during planning phase.

Changes Required:

• Add explicit phase?: string and issuesData?: IssuesResponse props
• Add useMemo to select data source:

  const displayIssues = useMemo(() => {
    if (phase === 'planning' && issuesData?.issues) {
      return issuesData.issues;
    }
    return issuesProp || [];
  }, [phase, issuesData, issuesProp]);

• Update Dashboard to pass both props
• Ensure tree renders correctly with REST API data during planning

Testing:

• Review existing tests in file:web-ui/__tests__/components/TaskTreeView.test.tsx
• Add test cases:
  • Planning phase displays issues from issuesData
  • Development phase displays issues from props
  • Empty state handled gracefully in both phases
• Add E2E test: "Late-joining user during planning sees full task tree"

Estimated Effort: 2 hours (code + unit tests + E2E test)

2. Audit and Document Current State

Objective: Create a comprehensive audit document listing all components and their phase-awareness status.

• Review file:web-ui/src/components/Dashboard.tsx to identify all components that display task/agent/progress data
• Document which components use useAgentState() directly vs. receive props
• Create audit matrix in docs/architecture/phase-awareness-audit.md with columns:
  • Component name and file path
  • Data source (useAgentState, REST API, props)
  • Phase-awareness status (aware, not-aware, n/a)
  • Risk level (high, medium, low)
  • Action required (update, test-only, none)
• Identify any additional components beyond the three critical ones

Estimated Effort: 2 hours

3. Update Medium-Priority Components (Follow-up)

3.1 QualityGatesPanel Phase-Awareness

File: file:web-ui/src/components/quality-gates/QualityGatesPanel.tsx

Current State: Receives tasks prop from Dashboard's useAgentState(), showing empty during planning phase.

Changes Required:

• Add phase?: string and issuesData?: IssuesResponse to QualityGatesPanelProps interface
• Add helper function extractTasksFromIssuesData(issuesData) to flatten issues into task array matching Task[] from agentState
• Add useMemo to select data source:

  const tasks = useMemo(() => {
    if (phase === 'planning' && issuesData) {
      return extractTasksFromIssuesData(issuesData);
    }
    return tasksProp; // from useAgentState
  }, [phase, issuesData, tasksProp]);

• Update Dashboard to pass phase={normalizedPhase} and issuesData={issuesData} props
• During planning phase, show message: "Quality gates will be evaluated during development phase"

Testing:

• Add test file file:web-ui/__tests__/components/quality-gates/QualityGatesPanel.test.tsx
• Test cases:
  • Planning phase shows appropriate message
  • Development phase shows task selector with agent state tasks
  • Phase transition switches data sources correctly
  • Empty issuesData handled gracefully

Estimated Effort: 2 hours

3.2 CostDashboard Phase-Awareness

File: file:web-ui/src/components/metrics/CostDashboard.tsx

Current State: Uses REST API for metrics, only relevant during development phase.

Changes Required:

• Add phase?: string to CostDashboardProps
• During planning phase, show informational message:
  • "Cost metrics will be available during development phase"
  • "Metrics track LLM API usage and token consumption"
• Add conditional rendering at component start:

  if (phase === 'planning') {
    return <PlanningPhaseMetricsMessage />;
  }

Testing:

• Review existing tests in file:web-ui/__tests__/components/CostDashboard.test.tsx
• Add test cases:
  • Planning phase shows informational message
  • Development phase shows metrics dashboard
  • No API calls made during planning phase

Estimated Effort: 1.5 hours

4. Update Dashboard Component

File: file:web-ui/src/components/Dashboard.tsx

Changes Required:

• Pass phase={normalizedPhase} prop to all updated components:
  • <AgentList phase={normalizedPhase} issuesData={issuesData} projectId={projectId} />
  • <ProgressIndicator phase={normalizedPhase} issuesData={issuesData} ... />
  • <TaskTreeView phase={normalizedPhase} issuesData={issuesData} issues={issuesData?.issues || []} />
  • <TaskStats phase={normalizedPhase} issuesData={issuesData} />
  • <QualityGatesPanel phase={normalizedPhase} issuesData={issuesData} tasks={tasks} />
  • <CostDashboard phase={normalizedPhase} projectId={projectId} />
• Ensure issuesData from SWR is available to all child components
• Add comment documenting phase-aware prop passing pattern

Estimated Effort: 1 hour

5. Create Shared Utilities

File: file:web-ui/src/utils/phaseAwareData.ts (new file)

Purpose: Centralize phase-aware data transformation logic.

Functions to create:

• extractTasksFromIssuesData(issuesData: IssuesResponse): Task[] - Flatten issues into task array
• calculateProgressFromIssuesData(issuesData: IssuesResponse): { currentStep: number, totalSteps: number } - Calculate progress metrics
• isPhaseAwareComponent(phase: string): boolean - Check if phase requires special handling
• getPlanningPhaseMessage(componentType: string): string - Get appropriate planning phase message

Testing:

• Create test file file:web-ui/__tests__/utils/phaseAwareData.test.ts
• Test all utility functions with various data scenarios

Estimated Effort: 2 hours

6. Update Type Definitions

File: file:web-ui/src/types/api.ts

Changes Required:

• Ensure ProjectPhase type includes all phases: 'discovery' | 'planning' | 'development' | 'review' | 'complete' | 'shipped'
• Add JSDoc comments documenting phase-aware component pattern
• Consider adding PhaseAwareComponentProps interface:

  export interface PhaseAwareComponentProps {
    phase?: ProjectPhase;
    issuesData?: IssuesResponse;
  }

Estimated Effort: 0.5 hours

7. Documentation Updates

7.1 Architecture Documentation

File: docs/architecture/phase-awareness-pattern.md (new file)

Content:

• Overview of two-data-system architecture (REST API vs WebSocket)
• Phase-aware component pattern explanation
• Code examples from TaskStats implementation
• When to apply the pattern (decision tree)
• Testing strategy for phase-aware components
• Common pitfalls and solutions

7.2 Code Review Document Update

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

Changes:

• Add "Related Components" section listing all components that need similar updates
• Add reference to new architecture documentation
• Update "Future Considerations" section with links to this implementation plan

Estimated Effort: 1.5 hours

8. Testing Strategy

8.1 Unit Tests (Parallel with Component Updates)

For each updated component, add test suite following file:web-ui/__tests__/components/tasks/TaskStats.test.tsx pattern:

Test Categories:

• Planning Phase Tests:
  • Component uses issuesData when phase='planning'
  • Correct display with populated issuesData
  • Graceful handling of undefined issuesData
  • Appropriate messaging for planning phase
• Development Phase Tests:
  • Component uses agent state when phase='development'
  • Correct display with agent state data
  • Ignores issuesData during development
• Phase Transition Tests:
  • Data source switches correctly during phase change
  • No memory leaks or stale data
  • Smooth UI transition
• Backward Compatibility Tests:
  • Component works without phase prop (defaults to agent state)
  • Existing usages continue to function

Estimated Effort: Included in component updates (1-2 hours per component)

8.2 E2E "Late-Joining User" Tests

File: file:tests/e2e/test_phase_awareness.spec.ts (new file)

Test Scenarios (Critical):

• Late-joining user during planning phase sees correct agent assignment message
• Late-joining user during planning phase sees correct progress percentage
• Late-joining user during planning phase sees full task tree
• Late-joining user during development phase sees agent state data
• Phase transition from planning to development updates all components correctly

Estimated Effort: 3 hours

8.3 E2E Test Updates

File: file:tests/e2e/test_state_reconciliation.spec.ts

Changes:

• Add phase-awareness checks to existing state reconciliation tests
• Verify components show correct data source based on phase
• Test late-joining user scenario across all phases

Estimated Effort: 1 hour

9. Implementation Sequence (P1 Priority)

Phase 1: Critical Fixes (Days 1-2)

Parallel Tracks:
├── 1.1 AgentPanel (3 hours)
├── 1.2 ProgressIndicator (3 hours)
└── 1.3 TaskTreeView (2 hours)

Phase 2: Infrastructure (Day 2-3)

Sequential:
├── 2. Audit & Document (2 hours)
├── 5. Create Shared Utilities (2 hours)
└── 6. Update Type Definitions (0.5 hours)

Phase 3: Dashboard & Medium-Priority (Day 3)

Sequential:
├── 4. Update Dashboard Component (1 hour)
├── 3.1 QualityGatesPanel (2 hours)
└── 3.2 CostDashboard (1.5 hours)

Phase 4: Testing & Documentation (Day 4)

Parallel:
├── 8.2 E2E Late-Joining Tests (3 hours)
├── 8.3 E2E Test Updates (1 hour)
└── 7. Documentation Updates (1.5 hours)

Total Estimated Effort: 22-24 hours (compressed timeline for P1 priority)

10. Acceptance Criteria Verification

• CRITICAL: AgentPanel shows correct message during planning phase (late-join scenario)
• CRITICAL: ProgressIndicator shows correct percentage during planning phase (late-join scenario)
• CRITICAL: TaskTreeView displays full task tree during planning phase (late-join scenario)
• All components using useAgentState() audited and documented
• Dashboard passes phase and issuesData props to all relevant components
• Shared utility functions created and tested
• Unit tests added for each updated component (8+ tests per component)
• E2E "late-joining user" tests added for critical components
• Medium-priority components (QualityGatesPanel, CostDashboard) updated with phase-aware messaging
• Architecture documentation created explaining the pattern
• All existing tests continue to pass (backward compatibility maintained)
• Code review completed referencing file:docs/code-review/2026-01-08-taskstats-phase-awareness-review.md as pattern guide

Import In IDE

🤖 Prompt for AI Agents

## Observations

After auditing the codebase, the phase-awareness issue is more nuanced than initially described. Most "at-risk" components don't directly use `useAgentState()` but receive data as props from parent components (primarily `file:web-ui/src/components/Dashboard.tsx`). The core issue is that these components need phase-aware data sources, not necessarily phase-aware logic themselves. `file:web-ui/src/components/tasks/TaskStats.tsx` (PR #234) established the pattern: components should accept both `phase` and `issuesData` props to switch between REST API data (planning) and WebSocket data (development/review).

## Approach

Apply a **prop-based phase-awareness pattern** rather than direct `useAgentState()` modifications. The Dashboard component will pass `phase` and `issuesData` props to child components, allowing them to select the appropriate data source. This maintains separation of concerns and follows the established TaskStats pattern. Given the P1 priority, high-priority components will be updated in parallel with comprehensive unit tests following the test patterns in `file:web-ui/__tests__/components/tasks/TaskStats.test.tsx`. The implementation will be split into two phases: immediate critical fixes (AgentPanel, ProgressIndicator, TaskTreeView) and follow-up enhancements (MetricsCharts, QualityGates).

## Implementation Plan

### 1. Immediate Critical Fixes (Parallel Track)

**Objective:** Fix the three high-priority components identified in the ticket that directly impact user experience during late-join scenarios.

#### 1.1 AgentPanel Phase-Awareness (CRITICAL)

**File:** `file:web-ui/src/components/AgentList.tsx`

**Current State:** Uses REST API `getAgentsForProject()`, may show "No agents assigned" during planning when agents are planned but not yet created.

**Changes Required:**
- Add `phase?: string` and `issuesData?: IssuesResponse` to `AgentListProps`
- During planning phase, show informational message instead of "No agents assigned":
  - "Agents will be created automatically when development begins"
  - Show count of planned tasks: "X tasks ready for agent assignment"
- Add conditional rendering:
  ```typescript
  if (phase === 'planning' && (!assignments || assignments.length === 0)) {
    return <PlanningPhaseAgentMessage issuesData={issuesData} />;
  }
  ```
- Create `PlanningPhaseAgentMessage` component to display task count and phase-appropriate messaging

**Testing:**
- Add test file `file:web-ui/__tests__/components/AgentList.test.tsx`
- Test cases:
  - Planning phase shows planning message with task count
  - Development phase shows agent cards
  - Empty state during development shows "No agents assigned"
  - Phase transition updates messaging
- Add E2E test: "Late-joining user during planning sees agent assignment message"

**Estimated Effort:** 3 hours (code + unit tests + E2E test)

#### 1.2 ProgressIndicator Phase-Awareness (CRITICAL)

**File:** `file:web-ui/src/components/ProgressIndicator.tsx`

**Current State:** Receives `currentStep` and `totalSteps` as props, may show 0% during planning if parent calculates from agent state.

**Changes Required:**
- Add `phase?: string` and `issuesData?: IssuesResponse` to `ProgressIndicatorProps`
- Add helper function `calculateProgressFromIssuesData(issuesData)` to compute completion percentage from issues/tasks
- Add `useMemo` to calculate progress:
  ```typescript
  const { currentStep, totalSteps } = useMemo(() => {
    if (phase === 'planning' && issuesData) {
      return calculateProgressFromIssuesData(issuesData);
    }
    return { currentStep: currentStepProp, totalSteps: totalStepsProp };
  }, [phase, issuesData, currentStepProp, totalStepsProp]);
  ```
- Update Dashboard to pass phase-aware progress data

**Testing:**
- Add test file `file:web-ui/__tests__/components/ProgressIndicator.test.tsx`
- Test cases:
  - Planning phase calculates from issuesData
  - Development phase uses props from agent state
  - Zero-division protection when no tasks exist
  - Percentage clamped to 0-100 range
- Add E2E test: "Late-joining user during planning sees correct progress percentage"

**Estimated Effort:** 3 hours (code + unit tests + E2E test)

#### 1.3 TaskTreeView Phase-Awareness (CRITICAL)

**File:** `file:web-ui/src/components/TaskTreeView.tsx`

**Current State:** May show empty tree if only reading agent state during planning phase.

**Changes Required:**
- Add explicit `phase?: string` and `issuesData?: IssuesResponse` props
- Add `useMemo` to select data source:
  ```typescript
  const displayIssues = useMemo(() => {
    if (phase === 'planning' && issuesData?.issues) {
      return issuesData.issues;
    }
    return issuesProp || [];
  }, [phase, issuesData, issuesProp]);
  ```
- Update Dashboard to pass both props
- Ensure tree renders correctly with REST API data during planning

**Testing:**
- Review existing tests in `file:web-ui/__tests__/components/TaskTreeView.test.tsx`
- Add test cases:
  - Planning phase displays issues from issuesData
  - Development phase displays issues from props
  - Empty state handled gracefully in both phases
- Add E2E test: "Late-joining user during planning sees full task tree"

**Estimated Effort:** 2 hours (code + unit tests + E2E test)

### 2. Audit and Document Current State

**Objective:** Create a comprehensive audit document listing all components and their phase-awareness status.

- Review `file:web-ui/src/components/Dashboard.tsx` to identify all components that display task/agent/progress data
- Document which components use `useAgentState()` directly vs. receive props
- Create audit matrix in `docs/architecture/phase-awareness-audit.md` with columns:
  - Component name and file path
  - Data source (useAgentState, REST API, props)
  - Phase-awareness status (aware, not-aware, n/a)
  - Risk level (high, medium, low)
  - Action required (update, test-only, none)
- Identify any additional components beyond the three critical ones

**Estimated Effort:** 2 hours

### 3. Update Medium-Priority Components (Follow-up)

#### 3.1 QualityGatesPanel Phase-Awareness

**File:** `file:web-ui/src/components/quality-gates/QualityGatesPanel.tsx`

**Current State:** Receives `tasks` prop from Dashboard's `useAgentState()`, showing empty during planning phase.

**Changes Required:**
- Add `phase?: string` and `issuesData?: IssuesResponse` to `QualityGatesPanelProps` interface
- Add helper function `extractTasksFromIssuesData(issuesData)` to flatten issues into task array matching `Task[]` from agentState
- Add `useMemo` to select data source:
  ```typescript
  const tasks = useMemo(() => {
    if (phase === 'planning' && issuesData) {
      return extractTasksFromIssuesData(issuesData);
    }
    return tasksProp; // from useAgentState
  }, [phase, issuesData, tasksProp]);
  ```
- Update Dashboard to pass `phase={normalizedPhase}` and `issuesData={issuesData}` props
- During planning phase, show message: "Quality gates will be evaluated during development phase"

**Testing:**
- Add test file `file:web-ui/__tests__/components/quality-gates/QualityGatesPanel.test.tsx`
- Test cases:
  - Planning phase shows appropriate message
  - Development phase shows task selector with agent state tasks
  - Phase transition switches data sources correctly
  - Empty issuesData handled gracefully

**Estimated Effort:** 2 hours

#### 3.2 CostDashboard Phase-Awareness

**File:** `file:web-ui/src/components/metrics/CostDashboard.tsx`

**Current State:** Uses REST API for metrics, only relevant during development phase.

**Changes Required:**
- Add `phase?: string` to `CostDashboardProps`
- During planning phase, show informational message:
  - "Cost metrics will be available during development phase"
  - "Metrics track LLM API usage and token consumption"
- Add conditional rendering at component start:
  ```typescript
  if (phase === 'planning') {
    return <PlanningPhaseMetricsMessage />;
  }
  ```

**Testing:**
- Review existing tests in `file:web-ui/__tests__/components/CostDashboard.test.tsx`
- Add test cases:
  - Planning phase shows informational message
  - Development phase shows metrics dashboard
  - No API calls made during planning phase

**Estimated Effort:** 1.5 hours

### 4. Update Dashboard Component

**File:** `file:web-ui/src/components/Dashboard.tsx`

**Changes Required:**
- Pass `phase={normalizedPhase}` prop to all updated components:
  - `<AgentList phase={normalizedPhase} issuesData={issuesData} projectId={projectId} />`
  - `<ProgressIndicator phase={normalizedPhase} issuesData={issuesData} ... />`
  - `<TaskTreeView phase={normalizedPhase} issuesData={issuesData} issues={issuesData?.issues || []} />`
  - `<TaskStats phase={normalizedPhase} issuesData={issuesData} />`
  - `<QualityGatesPanel phase={normalizedPhase} issuesData={issuesData} tasks={tasks} />`
  - `<CostDashboard phase={normalizedPhase} projectId={projectId} />`
- Ensure `issuesData` from SWR is available to all child components
- Add comment documenting phase-aware prop passing pattern

**Estimated Effort:** 1 hour

### 5. Create Shared Utilities

**File:** `file:web-ui/src/utils/phaseAwareData.ts` (new file)

**Purpose:** Centralize phase-aware data transformation logic.

**Functions to create:**
- `extractTasksFromIssuesData(issuesData: IssuesResponse): Task[]` - Flatten issues into task array
- `calculateProgressFromIssuesData(issuesData: IssuesResponse): { currentStep: number, totalSteps: number }` - Calculate progress metrics
- `isPhaseAwareComponent(phase: string): boolean` - Check if phase requires special handling
- `getPlanningPhaseMessage(componentType: string): string` - Get appropriate planning phase message

**Testing:**
- Create test file `file:web-ui/__tests__/utils/phaseAwareData.test.ts`
- Test all utility functions with various data scenarios

**Estimated Effort:** 2 hours

### 6. Update Type Definitions

**File:** `file:web-ui/src/types/api.ts`

**Changes Required:**
- Ensure `ProjectPhase` type includes all phases: `'discovery' | 'planning' | 'development' | 'review' | 'complete' | 'shipped'`
- Add JSDoc comments documenting phase-aware component pattern
- Consider adding `PhaseAwareComponentProps` interface:
  ```typescript
  export interface PhaseAwareComponentProps {
    phase?: ProjectPhase;
    issuesData?: IssuesResponse;
  }
  ```

**Estimated Effort:** 0.5 hours

### 7. Documentation Updates

#### 7.1 Architecture Documentation

**File:** `docs/architecture/phase-awareness-pattern.md` (new file)

**Content:**
- Overview of two-data-system architecture (REST API vs WebSocket)
- Phase-aware component pattern explanation
- Code examples from TaskStats implementation
- When to apply the pattern (decision tree)
- Testing strategy for phase-aware components
- Common pitfalls and solutions

#### 7.2 Code Review Document Update

**File:** `file:docs/code-review/2026-01-08-taskstats-phase-awareness-review.md`

**Changes:**
- Add "Related Components" section listing all components that need similar updates
- Add reference to new architecture documentation
- Update "Future Considerations" section with links to this implementation plan

**Estimated Effort:** 1.5 hours

### 8. Testing Strategy

#### 8.1 Unit Tests (Parallel with Component Updates)

For each updated component, add test suite following `file:web-ui/__tests__/components/tasks/TaskStats.test.tsx` pattern:

**Test Categories:**
- **Planning Phase Tests:**
  - Component uses issuesData when phase='planning'
  - Correct display with populated issuesData
  - Graceful handling of undefined issuesData
  - Appropriate messaging for planning phase
- **Development Phase Tests:**
  - Component uses agent state when phase='development'
  - Correct display with agent state data
  - Ignores issuesData during development
- **Phase Transition Tests:**
  - Data source switches correctly during phase change
  - No memory leaks or stale data
  - Smooth UI transition
- **Backward Compatibility Tests:**
  - Component works without phase prop (defaults to agent state)
  - Existing usages continue to function

**Estimated Effort:** Included in component updates (1-2 hours per component)

#### 8.2 E2E "Late-Joining User" Tests

**File:** `file:tests/e2e/test_phase_awareness.spec.ts` (new file)

**Test Scenarios (Critical):**
- Late-joining user during planning phase sees correct agent assignment message
- Late-joining user during planning phase sees correct progress percentage
- Late-joining user during planning phase sees full task tree
- Late-joining user during development phase sees agent state data
- Phase transition from planning to development updates all components correctly

**Estimated Effort:** 3 hours

#### 8.3 E2E Test Updates

**File:** `file:tests/e2e/test_state_reconciliation.spec.ts`

**Changes:**
- Add phase-awareness checks to existing state reconciliation tests
- Verify components show correct data source based on phase
- Test late-joining user scenario across all phases

**Estimated Effort:** 1 hour

### 9. Implementation Sequence (P1 Priority)

**Phase 1: Critical Fixes (Days 1-2)**
```
Parallel Tracks:
├── 1.1 AgentPanel (3 hours)
├── 1.2 ProgressIndicator (3 hours)
└── 1.3 TaskTreeView (2 hours)
```

**Phase 2: Infrastructure (Day 2-3)**
```
Sequential:
├── 2. Audit & Document (2 hours)
├── 5. Create Shared Utilities (2 hours)
└── 6. Update Type Definitions (0.5 hours)
```

**Phase 3: Dashboard & Medium-Priority (Day 3)**
```
Sequential:
├── 4. Update Dashboard Component (1 hour)
├── 3.1 QualityGatesPanel (2 hours)
└── 3.2 CostDashboard (1.5 hours)
```

**Phase 4: Testing & Documentation (Day 4)**
```
Parallel:
├── 8.2 E2E Late-Joining Tests (3 hours)
├── 8.3 E2E Test Updates (1 hour)
└── 7. Documentation Updates (1.5 hours)
```

**Total Estimated Effort:** 22-24 hours (compressed timeline for P1 priority)

### 10. Acceptance Criteria Verification

- [ ] **CRITICAL:** AgentPanel shows correct message during planning phase (late-join scenario)
- [ ] **CRITICAL:** ProgressIndicator shows correct percentage during planning phase (late-join scenario)
- [ ] **CRITICAL:** TaskTreeView displays full task tree during planning phase (late-join scenario)
- [ ] All components using `useAgentState()` audited and documented
- [ ] Dashboard passes `phase` and `issuesData` props to all relevant components
- [ ] Shared utility functions created and tested
- [ ] Unit tests added for each updated component (8+ tests per component)
- [ ] E2E "late-joining user" tests added for critical components
- [ ] Medium-priority components (QualityGatesPanel, CostDashboard) updated with phase-aware messaging
- [ ] Architecture documentation created explaining the pattern
- [ ] All existing tests continue to pass (backward compatibility maintained)
- [ ] Code review completed referencing `file:docs/code-review/2026-01-08-taskstats-phase-awareness-review.md` as pattern guide

---

Execution Information

Branch: main
Commit: 1edac57