# Implementation Plan

## Validation Checklist

- [x] All specification file paths are correct and exist
- [x] Context priming section is complete
- [x] All implementation phases are defined
- [x] Each phase follows TDD: Prime → Test → Implement → Validate
- [x] Dependencies between phases are clear (no circular dependencies)
- [x] Parallel work is properly tagged with `[parallel: true]`
- [x] Activity hints provided for specialist selection `[activity: type]`
- [x] Every phase references relevant SDD sections
- [x] Every test references PRD acceptance criteria
- [x] Integration & E2E tests defined in final phase
- [x] Project commands match actual project setup
- [x] A developer could follow this plan independently

---

## Specification Compliance Guidelines

### How to Ensure Specification Adherence

1. **Before Each Phase**: Complete the Pre-Implementation Specification Gate
2. **During Implementation**: Reference specific SDD sections in each task
3. **After Each Task**: Run Specification Compliance checks
4. **Phase Completion**: Verify all specification requirements are met

### Deviation Protocol

If implementation cannot follow specification exactly:
1. Document the deviation and reason
2. Get approval before proceeding
3. Update SDD if the deviation is an improvement
4. Never deviate without documentation

## Metadata Reference

- `[parallel: true]` - Tasks that can run concurrently
- `[component: component-name]` - For multi-component features
- `[ref: document/section; lines: 1, 2-3]` - Links to specifications, patterns, or interfaces and (if applicable) line(s)
- `[activity: type]` - Activity hint for specialist agent selection

---

## Context Priming

*GATE: You MUST fully read all files mentioned in this section before starting any implementation.*

**Specification**:

- `docs/specs/004-close-reports-frontend/product-requirements.md` - Product Requirements Document
- `docs/specs/004-close-reports-frontend/solution-design.md` - Solution Design Document
- `docs/backend-api-updates.md` - Backend API documentation for close reports endpoints

**Key Design Decisions** (from SDD ADRs):

- **ADR-1**: Reuse SchedulingApiClient - Close Reports API uses same JWT auth as scheduling; avoid duplication
- **ADR-2**: Cents-to-dollars conversion at mapper layer - Single conversion point, models match API exactly
- **ADR-3**: Family providers with Equatable parameter objects - Type-safe, proper caching
- **ADR-4**: Session-scoped state persistence - Section expansion states reset on app restart

**Implementation Context**:

- **Commands to run**:
  - `flutter analyze` - Check for code issues
  - `dart run build_runner build --delete-conflicting-outputs` - Regenerate Freezed/JSON code
  - `flutter test` - Run all tests
  - `flutter test test/data/models/close_reports/` - Run model tests
  - `flutter test test/presentation/providers/close_reports/` - Run provider tests

- **Patterns to follow**:
  - Freezed 3.x pattern: `abstract class` with `_$ClassName` mixin
  - Equatable pattern: Extend `Equatable`, override `props`
  - Riverpod 3.x: `FamilyAsyncNotifier` for family providers with parameters
  - Existing mapper pattern: Extensions on models with `toEntity()` method
  - Error handling: Use `ErrorDisplay.fromError()` widget

- **Interfaces to implement**:
  - `CloseReportsRepository` interface (SDD Section 5)
  - `CloseReportsRemoteDatasource` interface (SDD Section 7)

---

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| SchedulingApiClient base path may not work for close-reports | High | Medium | Add explicit API client wiring verification task in Phase 1 |
| Large report data causes slow load times | Medium | Low | Implement loading states, test on throttled network |
| Comparison view too complex for mobile | Medium | Medium | Design mobile-first, use vertical layout, test early |
| Phase 3 dependency on Phase 4 screens | Blocker | Certain | FIXED: Swapped Phase 3 and 4 order |

---

## Implementation Phases

### Phase 1: Data Layer Foundation

**Objective**: Create all Freezed models, Equatable entities, mappers, datasource, and repository with full test coverage following TDD.

**Success Criteria**:
- All tests written BEFORE implementation
- All Freezed models compile and generate correctly
- All entities have proper Equatable implementation
- Mappers correctly convert cents to dollars
- Repository tests pass with mocked datasource
- API client wiring verified with integration test
- `flutter analyze` reports no issues

**Files to Create**:
- `lib/data/models/close_reports/close_report_summary_model.dart`
- `lib/data/models/close_reports/close_report_detail_model.dart`
- `lib/data/models/close_reports/close_report_comparison_model.dart`
- `lib/data/models/close_reports/calendar_dates_model.dart`
- `lib/data/models/close_reports/close_report_list_response_model.dart`
- `lib/data/models/close_reports/close_report_models.dart` (barrel)
- `lib/domain/entities/close_reports/close_report_summary.dart`
- `lib/domain/entities/close_reports/close_report_detail.dart`
- `lib/domain/entities/close_reports/close_report_comparison.dart`
- `lib/domain/entities/close_reports/calendar_dates.dart`
- `lib/domain/entities/close_reports/close_report_entities.dart` (barrel)
- `lib/data/models/mappers/close_reports/close_report_mapper.dart`
- `lib/data/datasources/close_reports/close_reports_remote_datasource.dart`
- `lib/data/datasources/close_reports/close_reports_datasources.dart` (barrel)
- `lib/domain/repositories/close_reports_repository.dart`
- `lib/data/repositories/close_reports_repository_impl.dart`

**Test Files to Create**:
- `test/data/models/close_reports/close_report_models_test.dart`
- `test/data/models/mappers/close_reports/close_report_mapper_test.dart`
- `test/data/repositories/close_reports_repository_test.dart`
- `test/data/datasources/close_reports/close_reports_datasource_test.dart`

---

- [x] T1 Phase 1: Data Layer Foundation

    - [x] T1.1 Prime Context
        - [x] T1.1.1 Read SDD Section 2 (Data Models) `[ref: SDD/Section 2; lines: 42-271]`
        - [x] T1.1.2 Read SDD Section 3 (Domain Entities) `[ref: SDD/Section 3; lines: 275-592]`
        - [x] T1.1.3 Read SDD Section 4 (Mappers) `[ref: SDD/Section 4; lines: 596-757]`
        - [x] T1.1.4 Read SDD Section 5 (Repository Interface) `[ref: SDD/Section 5; lines: 761-829]`
        - [x] T1.1.5 Read SDD Section 6 (Repository Implementation) `[ref: SDD/Section 6; lines: 833-909]`
        - [x] T1.1.6 Read SDD Section 7 (Remote Datasource) `[ref: SDD/Section 7; lines: 913-1102]`
        - [x] T1.1.7 Read SDD Section 12 (Error Handling) `[ref: SDD/Section 12; lines: 1691-1727]`
        - [x] T1.1.8 Read SDD Section 14 (API Integration Details) `[ref: SDD/Section 14; lines: 1793-1812]`
        - [x] T1.1.9 Review existing Freezed model patterns `[ref: lib/data/models/store_model.dart]`
        - [x] T1.1.10 Review existing Equatable entity patterns `[ref: lib/domain/entities/store.dart]`
        - [x] T1.1.11 Review existing SchedulingApiClient `[ref: lib/core/network/scheduling/scheduling_api_client.dart]`

    - [x] T1.2 Write Tests (TDD - Tests First) `[parallel: true]`
        - [x] T1.2.1 Write model JSON parsing tests (happy path and edge cases) `[ref: PRD/Feature 1 - monetary values in dollars]` `[activity: flutter-test]`
        - [x] T1.2.2 Write model tests for all nested models (metadata, sales, buys, returns, labor) `[activity: flutter-test]`
        - [x] T1.2.3 Write mapper cents-to-dollars conversion tests `[ref: PRD/Constraints - API returns cents]` `[activity: flutter-test]`
        - [x] T1.2.4 Write mapper date parsing tests (YYYY-MM-DD and ISO datetime) `[activity: flutter-test]`
        - [x] T1.2.5 Write mapper enum conversion tests (direction, significance) `[activity: flutter-test]`
        - [x] T1.2.6 Write repository tests with mocked datasource `[activity: flutter-test]`
        - [x] T1.2.7 Write datasource error handling tests for each error type `[ref: SDD/Section 12]` `[activity: flutter-test]`
        - [x] T1.2.8 Write API client wiring integration test `[ref: SDD/Section 14]` `[activity: flutter-test]`

    - [x] T1.3 Create Freezed Models `[parallel: true]` `[component: models]`
        - [x] T1.3.1 Create `close_report_summary_model.dart` with JSON parsing helpers `[ref: SDD/Section 2.1]` `[activity: flutter-model]`
        - [x] T1.3.2 Create `close_report_detail_model.dart` with nested models (metadata, sales, buys, returns, labor) `[ref: SDD/Section 2.2]` `[activity: flutter-model]`
        - [x] T1.3.3 Create `close_report_comparison_model.dart` with deltas and highlights models `[ref: SDD/Section 2.3]` `[activity: flutter-model]`
        - [x] T1.3.4 Create `calendar_dates_model.dart` `[ref: SDD/Section 2.4]` `[activity: flutter-model]`
        - [x] T1.3.5 Create `close_report_list_response_model.dart` with pagination model `[ref: SDD/Section 2.5]` `[activity: flutter-model]`
        - [x] T1.3.6 Create barrel export `close_report_models.dart` `[ref: SDD/Section 2.6]` `[activity: flutter-model]`
        - [x] T1.3.7 Run build_runner to generate Freezed code `[activity: build]`

    - [x] T1.4 Create Domain Entities `[parallel: true]` `[component: entities]`
        - [x] T1.4.1 Create `close_report_summary.dart` with formatted accessors `[ref: SDD/Section 3.1]` `[activity: flutter-entity]`
        - [x] T1.4.2 Create `close_report_detail.dart` with all section entities (metadata, sales, buys, returns, labor) `[ref: SDD/Section 3.2]` `[activity: flutter-entity]`
        - [x] T1.4.3 Create `close_report_comparison.dart` with enums (VarianceSignificance, VarianceDirection) `[ref: SDD/Section 3.3]` `[activity: flutter-entity]`
        - [x] T1.4.4 Create `calendar_dates.dart` with `hasReportForDate` helper `[ref: SDD/Section 3.4]` `[activity: flutter-entity]`
        - [x] T1.4.5 Create barrel export `close_report_entities.dart` `[ref: SDD/Section 3.5]` `[activity: flutter-entity]`

    - [x] T1.5 Create Mappers
        - [x] T1.5.1 Create `close_report_mapper.dart` with all extensions `[ref: SDD/Section 4.1]` `[activity: flutter-mapper]`
        - [x] T1.5.2 Implement `_centsToDollars` utility function `[activity: flutter-mapper]`
        - [x] T1.5.3 Implement `_parseDate` and `_parseDateTime` utilities `[activity: flutter-mapper]`
        - [x] T1.5.4 Create extension for each model: Summary, Detail, Metadata, Sales, Buys, Returns, Labor `[activity: flutter-mapper]`
        - [x] T1.5.5 Create comparison and highlight mappers with enum conversion `[activity: flutter-mapper]`

    - [x] T1.6 Create Datasource with Error Handling
        - [x] T1.6.1 Create `close_reports_remote_datasource.dart` with interface and implementation `[ref: SDD/Section 7.1]` `[activity: flutter-datasource]`
        - [x] T1.6.2 Verify/configure SchedulingApiClient base path for close-reports `[ref: SDD/Section 14]` `[activity: flutter-config]`
        - [x] T1.6.3 Implement `_handleError` method with all error type mappings `[ref: SDD/Section 12]` `[activity: flutter-datasource]`
        - [x] T1.6.4 Map HTTP 400 to ValidationException `[activity: flutter-datasource]`
        - [x] T1.6.5 Map HTTP 401/403 to AuthException with redirect behavior `[activity: flutter-datasource]`
        - [x] T1.6.6 Map HTTP 404 to NotFoundException `[activity: flutter-datasource]`
        - [x] T1.6.7 Map HTTP 503 to ServiceUnavailableException `[activity: flutter-datasource]`
        - [x] T1.6.8 Map timeout/connection errors to NetworkException `[activity: flutter-datasource]`
        - [x] T1.6.9 Implement all 5 endpoint methods (list, detail, latest, calendar, compare) `[activity: flutter-datasource]`
        - [x] T1.6.10 Create barrel export `close_reports_datasources.dart` `[ref: SDD/Section 7.2]` `[activity: flutter-datasource]`

    - [x] T1.7 Create Repository
        - [x] T1.7.1 Create repository interface `close_reports_repository.dart` `[ref: SDD/Section 5.1]` `[activity: flutter-repository]`
        - [x] T1.7.2 Create repository implementation `close_reports_repository_impl.dart` `[ref: SDD/Section 6.1]` `[activity: flutter-repository]`

    - [x] T1.8 Validate
        - [x] T1.8.1 Run `flutter analyze` - no errors `[activity: lint-code]`
        - [x] T1.8.2 Run `dart format .` on new files `[activity: format-code]`
        - [x] T1.8.3 Run model tests - all passing `[activity: run-tests]`
        - [x] T1.8.4 Run mapper tests - verify cents-to-dollars accuracy `[activity: run-tests]`
        - [x] T1.8.5 Run repository tests - all passing `[activity: run-tests]`
        - [x] T1.8.6 Run datasource error handling tests - all passing `[activity: run-tests]`
        - [x] T1.8.7 Run API client wiring integration test - verify base path works `[activity: run-tests]`
        - [x] T1.8.8 Verify all models follow Freezed 3.x `abstract class` pattern `[activity: review-code]`
        - [x] T1.8.9 Verify all entities extend Equatable correctly `[activity: review-code]`

**Integration Checkpoint**: After Phase 1 completion, verify datasource can connect to real API endpoint (manual test with valid JWT).

---

### Phase 2: Provider Layer

**Objective**: Create all Riverpod providers for data fetching, pagination, and UI state management following TDD.

**Dependencies**: Phase 1 must be complete (repository and entities available)

**Success Criteria**:
- All tests written BEFORE implementation
- All providers compile without errors
- Pagination works correctly in list provider
- Family providers use Equatable parameter objects
- UI state providers manage session-scoped state
- Provider tests pass

**Files to Create**:
- `lib/presentation/providers/close_reports/close_reports_providers.dart`

**Files to Modify**:
- `lib/presentation/providers/providers.dart` (add export)

**Test Files to Create**:
- `test/presentation/providers/close_reports/close_reports_providers_test.dart`

---

- [ ] T2 Phase 2: Provider Layer

    - [ ] T2.1 Prime Context
        - [ ] T2.1.1 Read SDD Section 8 (Providers) `[ref: SDD/Section 8; lines: 1105-1387]`
        - [ ] T2.1.2 Review existing provider patterns `[ref: lib/presentation/providers/dashboard_provider.dart]`
        - [ ] T2.1.3 Review FamilyAsyncNotifier pattern `[ref: lib/presentation/providers/store_detail_provider.dart]`

    - [ ] T2.2 Write Tests (TDD - Tests First)
        - [ ] T2.2.1 Write list provider tests (initial load, loadMore, refresh) `[ref: PRD/Feature 3]` `[activity: flutter-test]`
        - [ ] T2.2.2 Write pagination edge case tests (hasMore false, loading state) `[activity: flutter-test]`
        - [ ] T2.2.3 Write pagination error tests (loadMore fails, preserves state) `[ref: PRD Edge Case: List pagination inline retry]` `[activity: flutter-test]`
        - [ ] T2.2.4 Write detail provider tests `[ref: PRD/Feature 2]` `[activity: flutter-test]`
        - [ ] T2.2.5 Write latest provider tests `[ref: PRD/Feature 1]` `[activity: flutter-test]`
        - [ ] T2.2.6 Write calendar provider tests `[ref: PRD/Feature 2]` `[activity: flutter-test]`
        - [ ] T2.2.7 Write comparison provider tests `[ref: PRD/Feature 4]` `[activity: flutter-test]`
        - [ ] T2.2.8 Write comparison validation tests (same-date rejection) `[ref: PRD Edge Case: Same-date comparison]` `[activity: flutter-test]`
        - [ ] T2.2.9 Write comparison auto-swap tests (newer date becomes primary) `[ref: PRD Edge Case: Comparison date newer]` `[activity: flutter-test]`

    - [ ] T2.3 Create Base Providers
        - [ ] T2.3.1 Create `closeReportsRemoteDatasourceProvider` `[ref: SDD/Section 8.1]` `[activity: flutter-provider]`
        - [ ] T2.3.2 Create `closeReportsRepositoryProvider` `[ref: SDD/Section 8.1]` `[activity: flutter-provider]`

    - [ ] T2.4 Create List Provider with Pagination
        - [ ] T2.4.1 Create `CloseReportsListState` Equatable class `[ref: SDD/Section 8.1]` `[activity: flutter-provider]`
        - [ ] T2.4.2 Create `CloseReportsListNotifier` extending `FamilyAsyncNotifier` `[activity: flutter-provider]`
        - [ ] T2.4.3 Implement `build()` for initial load with page size 30 `[activity: flutter-provider]`
        - [ ] T2.4.4 Implement `loadMore()` with offset pagination `[ref: PRD/Feature 3 - list is paginated]` `[activity: flutter-provider]`
        - [ ] T2.4.5 Implement `refresh()` method `[ref: PRD/Feature 3 - pull-to-refresh]` `[activity: flutter-provider]`
        - [ ] T2.4.6 Add error handling for loadMore (preserve existing state, expose error for toast) `[ref: SDD/Section 8.1 comment]` `[activity: flutter-provider]`

    - [ ] T2.5 Create Detail and Latest Providers `[parallel: true]`
        - [ ] T2.5.1 Create `ReportDetailParams` Equatable class `[ref: SDD/Section 8.1]` `[activity: flutter-provider]`
        - [ ] T2.5.2 Create `CloseReportDetailNotifier` `[ref: PRD/Feature 2 - view previous days]` `[activity: flutter-provider]`
        - [ ] T2.5.3 Create `LatestCloseReportNotifier` `[ref: PRD/Feature 1 - view latest report]` `[activity: flutter-provider]`
        - [ ] T2.5.4 Create `closeReportDetailProvider` family provider `[activity: flutter-provider]`
        - [ ] T2.5.5 Create `latestCloseReportProvider` family provider `[activity: flutter-provider]`

    - [ ] T2.6 Create Calendar Provider
        - [ ] T2.6.1 Create `CalendarParams` Equatable class `[ref: SDD/Section 8.1]` `[activity: flutter-provider]`
        - [ ] T2.6.2 Create `CloseReportCalendarNotifier` `[ref: PRD/Feature 2 - calendar view]` `[activity: flutter-provider]`
        - [ ] T2.6.3 Create `closeReportCalendarProvider` family provider `[activity: flutter-provider]`

    - [ ] T2.7 Create Comparison Provider with Validation
        - [ ] T2.7.1 Create `ComparisonParams` Equatable class `[ref: SDD/Section 8.1]` `[activity: flutter-provider]`
        - [ ] T2.7.2 Add same-date validation (reject if primaryDate == comparisonDate) `[ref: PRD Edge Case: Same-date comparison]` `[activity: flutter-provider]`
        - [ ] T2.7.3 Add auto-swap logic (if comparison is newer than primary, swap them) `[ref: PRD Edge Case: Comparison date newer]` `[activity: flutter-provider]`
        - [ ] T2.7.4 Create `CloseReportComparisonNotifier` `[ref: PRD/Feature 4 - compare reports]` `[activity: flutter-provider]`
        - [ ] T2.7.5 Create `closeReportComparisonProvider` family provider `[activity: flutter-provider]`

    - [ ] T2.8 Create UI State Providers
        - [ ] T2.8.1 Create `selectedReportDateProvider` StateProvider.family `[ref: PRD/Appendix Navigation State]` `[activity: flutter-provider]`
        - [ ] T2.8.2 Create `reportSectionExpandedProvider` StateProvider.family with default map `[ref: PRD/Feature 6 - expansion persists in session]` `[activity: flutter-provider]`

    - [ ] T2.9 Update Barrel Export
        - [ ] T2.9.1 Add export to `lib/presentation/providers/providers.dart` `[ref: SDD/Section 8.2]` `[activity: flutter-provider]`

    - [ ] T2.10 Validate
        - [ ] T2.10.1 Run `flutter analyze` - no errors `[activity: lint-code]`
        - [ ] T2.10.2 Run `dart format .` on new files `[activity: format-code]`
        - [ ] T2.10.3 Run provider tests - all passing `[activity: run-tests]`
        - [ ] T2.10.4 Verify Equatable params have correct props `[activity: review-code]`
        - [ ] T2.10.5 Verify all notifiers follow AsyncNotifier pattern `[activity: review-code]`

---

### Phase 3: UI Layer (Screens and Widgets)

**Objective**: Create all reusable widgets and screens with analytics instrumentation.

**Dependencies**: Phases 1 and 2 must be complete (providers and entities available)

**Success Criteria**:
- All tests written BEFORE implementation
- All 8 widgets render correctly
- CloseReportsScreen has tabs (Latest, History)
- CloseReportDetailScreen shows expandable sections
- CloseReportComparisonScreen shows side-by-side comparison
- DateSelectorModal has all specified behaviors
- Analytics events fire on screen views
- Widget and screen tests pass

**Files to Create**:
- `lib/presentation/widgets/close_reports/close_report_list_tile.dart`
- `lib/presentation/widgets/close_reports/metric_row.dart`
- `lib/presentation/widgets/close_reports/expandable_section.dart`
- `lib/presentation/widgets/close_reports/discrepancy_badge.dart`
- `lib/presentation/widgets/close_reports/date_selector_modal.dart`
- `lib/presentation/widgets/close_reports/quick_compare_buttons.dart`
- `lib/presentation/widgets/close_reports/comparison_metric_row.dart`
- `lib/presentation/widgets/close_reports/variance_chip.dart`
- `lib/presentation/widgets/close_reports/close_reports_widgets.dart` (barrel)
- `lib/presentation/screens/close_reports/close_reports_screen.dart`
- `lib/presentation/screens/close_reports/close_report_detail_screen.dart`
- `lib/presentation/screens/close_reports/close_report_comparison_screen.dart`
- `lib/presentation/screens/close_reports/close_reports_screens.dart` (barrel)

**Files to Modify**:
- `lib/presentation/screens/store_detail/store_detail_screen.dart` (add Quick Action)

**Test Files to Create**:
- `test/presentation/widgets/close_reports/close_report_widgets_test.dart`
- `test/presentation/screens/close_reports/close_reports_screen_test.dart`
- `test/presentation/screens/close_reports/close_report_detail_screen_test.dart`
- `test/presentation/screens/close_reports/close_report_comparison_screen_test.dart`

---

- [ ] T3 Phase 3: UI Layer

    - [ ] T3.1 Prime Context
        - [ ] T3.1.1 Read SDD Section 10 (Screens) `[ref: SDD/Section 10; lines: 1510-1643]`
        - [ ] T3.1.2 Read SDD Section 11 (Widgets) `[ref: SDD/Section 11; lines: 1647-1687]`
        - [ ] T3.1.3 Read SDD Section 11.2 (DateSelectorModal Behavior) `[ref: SDD/Section 11.2]`
        - [ ] T3.1.4 Read SDD Section 12 (Error Handling) `[ref: SDD/Section 12; lines: 1691-1727]`
        - [ ] T3.1.5 Read PRD Feature acceptance criteria `[ref: PRD/Feature Requirements; lines: 104-196]`
        - [ ] T3.1.6 Read PRD Edge Cases `[ref: PRD/Detailed Feature Specifications; lines: 236-244]`
        - [ ] T3.1.7 Read PRD Tracking Requirements `[ref: PRD/Success Metrics; lines: 257-269]`
        - [ ] T3.1.8 Review app theme and colors `[ref: lib/core/theme/app_theme.dart]`
        - [ ] T3.1.9 Review existing widget patterns `[ref: lib/presentation/widgets/common/]`

    - [ ] T3.2 Write Widget Tests (TDD - Tests First)
        - [ ] T3.2.1 Write CloseReportListTile tests (renders metrics, discrepancy indicator) `[activity: flutter-test]`
        - [ ] T3.2.2 Write ExpandableSection tests (animation, state callback) `[activity: flutter-test]`
        - [ ] T3.2.3 Write DiscrepancyBadge tests (warning styling, "Cash Discrepancy" label) `[activity: flutter-test]`
        - [ ] T3.2.4 Write DateSelectorModal tests - disabled dates (greyed, not tappable) `[ref: SDD/Section 11.2]` `[activity: flutter-test]`
        - [ ] T3.2.5 Write DateSelectorModal tests - highlight dots on available dates `[ref: SDD/Section 11.2]` `[activity: flutter-test]`
        - [ ] T3.2.6 Write DateSelectorModal tests - month navigation arrows `[ref: SDD/Section 11.2]` `[activity: flutter-test]`
        - [ ] T3.2.7 Write DateSelectorModal tests - loading state while fetching `[ref: SDD/Section 11.2]` `[activity: flutter-test]`
        - [ ] T3.2.8 Write QuickCompareButtons tests (callbacks, disabled states) `[activity: flutter-test]`
        - [ ] T3.2.9 Write ComparisonMetricRow tests with variance colors `[activity: flutter-test]`
        - [ ] T3.2.10 Write VarianceChip tests (significance levels, direction) `[activity: flutter-test]`

    - [ ] T3.3 Write Screen Tests (TDD - Tests First)
        - [ ] T3.3.1 Write CloseReportsScreen tests - tab switching `[activity: flutter-test]`
        - [ ] T3.3.2 Write CloseReportsScreen tests - loading state `[activity: flutter-test]`
        - [ ] T3.3.3 Write CloseReportsScreen tests - error state with retry `[activity: flutter-test]`
        - [ ] T3.3.4 Write CloseReportsScreen tests - empty state `[ref: SDD/Section 10.1]` `[activity: flutter-test]`
        - [ ] T3.3.5 Write CloseReportsScreen tests - infinite scroll `[activity: flutter-test]`
        - [ ] T3.3.6 Write CloseReportDetailScreen tests - section expansion `[activity: flutter-test]`
        - [ ] T3.3.7 Write CloseReportDetailScreen tests - compare navigation `[activity: flutter-test]`
        - [ ] T3.3.8 Write CloseReportDetailScreen tests - discrepancy display `[activity: flutter-test]`
        - [ ] T3.3.9 Write CloseReportComparisonScreen tests - swap functionality `[activity: flutter-test]`
        - [ ] T3.3.10 Write CloseReportComparisonScreen tests - variance highlighting `[activity: flutter-test]`
        - [ ] T3.3.11 Write CloseReportComparisonScreen tests - "No comparison available" state `[ref: PRD Edge Case]` `[activity: flutter-test]`
        - [ ] T3.3.12 Write toast notification tests for error scenarios `[ref: SDD/Section 12.2]` `[activity: flutter-test]`

    - [ ] T3.4 Create Reusable Widgets `[parallel: true]` `[component: widgets]`
        - [ ] T3.4.1 Create `CloseReportListTile` with discrepancy indicator `[ref: SDD/Section 11.1; PRD/Feature 3]` `[activity: flutter-widget]`
        - [ ] T3.4.2 Create `MetricRow` for label/value display `[ref: SDD/Section 11.1]` `[activity: flutter-widget]`
        - [ ] T3.4.3 Create `ExpandableSection` with 200-300ms animation `[ref: SDD/Section 10.2; PRD/Feature 6]` `[activity: flutter-widget]`
        - [ ] T3.4.4 Create `DiscrepancyBadge` with warning styling and "Cash Discrepancy" label `[ref: SDD/Section 11.1; PRD/Feature 7]` `[activity: flutter-widget]`
        - [ ] T3.4.5 Create `DateSelectorModal` - base structure `[ref: SDD/Section 11.2; PRD/Feature 2]` `[activity: flutter-widget]`
        - [ ] T3.4.6 Implement DateSelectorModal - disabled dates (greyed, not tappable) `[ref: SDD/Section 11.2]` `[activity: flutter-widget]`
        - [ ] T3.4.7 Implement DateSelectorModal - highlight dots on available dates `[ref: SDD/Section 11.2]` `[activity: flutter-widget]`
        - [ ] T3.4.8 Implement DateSelectorModal - month navigation arrows `[ref: SDD/Section 11.2]` `[activity: flutter-widget]`
        - [ ] T3.4.9 Implement DateSelectorModal - loading state while fetching `[ref: SDD/Section 11.2]` `[activity: flutter-widget]`
        - [ ] T3.4.10 Create `QuickCompareButtons` (vs Yesterday, vs Last Week) `[ref: SDD/Section 10.2; PRD/Feature 4]` `[activity: flutter-widget]`
        - [ ] T3.4.11 Create `ComparisonMetricRow` with 3-column layout `[ref: SDD/Section 11.1]` `[activity: flutter-widget]`
        - [ ] T3.4.12 Create `VarianceChip` with significance colors `[ref: SDD/Section 11.1; PRD/Feature 4]` `[activity: flutter-widget]`
        - [ ] T3.4.13 Create barrel export `close_reports_widgets.dart` `[ref: SDD/Section 11.3]` `[activity: flutter-widget]`

    - [ ] T3.5 Create CloseReportsScreen with Analytics
        - [ ] T3.5.1 Create screen with TabBar (Latest, History) `[ref: SDD/Section 10.1; PRD/Feature 1, 3]` `[activity: flutter-screen]`
        - [ ] T3.5.2 Implement AppBar with calendar button and refresh button `[ref: SDD/Section 10.1]` `[activity: flutter-screen]`
        - [ ] T3.5.3 Implement Latest tab using `latestCloseReportProvider` `[ref: PRD/Feature 1]` `[activity: flutter-screen]`
        - [ ] T3.5.4 Implement History tab with `closeReportsListProvider` and infinite scroll `[ref: PRD/Feature 3]` `[activity: flutter-screen]`
        - [ ] T3.5.5 Implement pull-to-refresh on both tabs `[ref: PRD/Feature 3]` `[activity: flutter-screen]`
        - [ ] T3.5.6 Implement loading state `[ref: SDD/Section 10.1]` `[activity: flutter-screen]`
        - [ ] T3.5.7 Implement error state with `ErrorDisplay.fromError()` and retry `[ref: SDD/Section 12]` `[activity: flutter-screen]`
        - [ ] T3.5.8 Implement empty state for no reports `[ref: SDD/Section 10.1]` `[activity: flutter-screen]`
        - [ ] T3.5.9 Handle calendar date selection navigation `[ref: PRD/Feature 2]` `[activity: flutter-screen]`
        - [ ] T3.5.10 Add inline retry for pagination failures (toast + "Tap to retry") `[ref: PRD Edge Case: List pagination]` `[activity: flutter-screen]`
        - [ ] T3.5.11 Wire up `close_reports_viewed` analytics event `[ref: PRD/Tracking Requirements]` `[activity: flutter-analytics]`
        - [ ] T3.5.12 Wire up `close_report_calendar_opened` analytics event `[ref: PRD/Tracking Requirements]` `[activity: flutter-analytics]`

    - [ ] T3.6 Create CloseReportDetailScreen with Analytics
        - [ ] T3.6.1 Create screen with expandable sections layout `[ref: SDD/Section 10.2; PRD/Feature 1, 6]` `[activity: flutter-screen]`
        - [ ] T3.6.2 Implement AppBar with Compare and Refresh buttons `[ref: SDD/Section 10.2]` `[activity: flutter-screen]`
        - [ ] T3.6.3 Implement ReportHeader with discrepancy badge and key metrics `[ref: SDD/Section 10.2]` `[activity: flutter-screen]`
        - [ ] T3.6.4 Display store timezone in header `[ref: PRD Edge Case: timezone display]` `[activity: flutter-screen]`
        - [ ] T3.6.5 Implement SalesSummarySection with all fields `[ref: PRD/Feature 1]` `[activity: flutter-screen]`
        - [ ] T3.6.6 Implement BuysSection with all fields `[ref: PRD/Feature 1]` `[activity: flutter-screen]`
        - [ ] T3.6.7 Implement ReturnsSection with all fields `[ref: PRD/Feature 1]` `[activity: flutter-screen]`
        - [ ] T3.6.8 Implement LaborSection with all fields `[ref: PRD/Feature 1]` `[activity: flutter-screen]`
        - [ ] T3.6.9 Wire up section expansion to `reportSectionExpandedProvider` `[ref: PRD/Feature 6]` `[activity: flutter-screen]`
        - [ ] T3.6.10 Implement Compare flow with QuickCompareButtons and date selection `[ref: PRD/Feature 4]` `[activity: flutter-screen]`
        - [ ] T3.6.11 Wire up `close_report_detail_viewed` analytics event `[ref: PRD/Tracking Requirements]` `[activity: flutter-analytics]`
        - [ ] T3.6.12 Wire up `close_report_date_changed` analytics event `[ref: PRD/Tracking Requirements]` `[activity: flutter-analytics]`
        - [ ] T3.6.13 Wire up `close_report_section_toggled` analytics event `[ref: PRD/Tracking Requirements]` `[activity: flutter-analytics]`
        - [ ] T3.6.14 Wire up `close_report_comparison_started` analytics event `[ref: PRD/Tracking Requirements]` `[activity: flutter-analytics]`

    - [ ] T3.7 Create CloseReportComparisonScreen with Analytics
        - [ ] T3.7.1 Create screen with comparison layout `[ref: SDD/Section 10.3; PRD/Feature 4]` `[activity: flutter-screen]`
        - [ ] T3.7.2 Implement AppBar with Swap and Change Date buttons `[ref: SDD/Section 10.3]` `[activity: flutter-screen]`
        - [ ] T3.7.3 Implement ComparisonHeader with date labels `[ref: SDD/Section 10.3]` `[activity: flutter-screen]`
        - [ ] T3.7.4 Implement "No comparison available" state when comparison report missing `[ref: PRD Edge Case]` `[activity: flutter-screen]`
        - [ ] T3.7.5 Implement HighlightsBanner for significant variances `[ref: SDD/Section 10.3; PRD/Feature 4]` `[activity: flutter-screen]`
        - [ ] T3.7.6 Implement ComparisonTable with all metric rows `[ref: PRD/Feature 4]` `[activity: flutter-screen]`
        - [ ] T3.7.7 Apply variance coloring (>10% warning, >25% critical) `[ref: PRD/Feature 4]` `[activity: flutter-screen]`
        - [ ] T3.7.8 Apply inverted coloring for Labor % (lower is better) `[ref: PRD/Feature 4 business rules]` `[activity: flutter-screen]`
        - [ ] T3.7.9 Implement Swap button functionality `[ref: PRD/Feature 4]` `[activity: flutter-screen]`
        - [ ] T3.7.10 Implement Change Date functionality `[ref: PRD/Feature 4]` `[activity: flutter-screen]`
        - [ ] T3.7.11 Wire up `close_report_comparison_completed` analytics event `[ref: PRD/Tracking Requirements]` `[activity: flutter-analytics]`

    - [ ] T3.8 Create Error Toast Notifications
        - [ ] T3.8.1 Implement toast for "Failed to load report for [date]" `[ref: SDD/Section 12.2]` `[activity: flutter-screen]`
        - [ ] T3.8.2 Implement toast for "Failed to load calendar" `[ref: SDD/Section 12.2]` `[activity: flutter-screen]`
        - [ ] T3.8.3 Implement toast for "No report available for [date]" `[ref: SDD/Section 12.2]` `[activity: flutter-screen]`
        - [ ] T3.8.4 Implement toast for "Failed to load more reports. Tap to retry." `[ref: SDD/Section 8.1]` `[activity: flutter-screen]`
        - [ ] T3.8.5 Wire up `close_report_error` analytics event for all error scenarios `[ref: PRD/Tracking Requirements]` `[activity: flutter-analytics]`

    - [ ] T3.9 Handle Auth Redirect for 401
        - [ ] T3.9.1 Implement auth redirect behavior on 401/403 errors `[ref: SDD/Section 12]` `[activity: flutter-screen]`

    - [ ] T3.10 Create Barrel Export
        - [ ] T3.10.1 Create `close_reports_screens.dart` barrel export `[ref: SDD/Section 10.4]` `[activity: flutter-screen]`

    - [ ] T3.11 Validate
        - [ ] T3.11.1 Run `flutter analyze` - no errors `[activity: lint-code]`
        - [ ] T3.11.2 Run `dart format .` on new files `[activity: format-code]`
        - [ ] T3.11.3 Run widget tests - all passing `[activity: run-tests]`
        - [ ] T3.11.4 Run screen tests - all passing `[activity: run-tests]`
        - [ ] T3.11.5 Verify UI matches SDD component hierarchies `[activity: review-code]`
        - [ ] T3.11.6 Verify error handling uses `ErrorDisplay.fromError()` pattern `[activity: review-code]`
        - [ ] T3.11.7 Verify accessibility (semantic labels, 48dp touch targets) `[ref: SDD/Section 17.2]` `[activity: review-code]`
        - [ ] T3.11.8 Verify all analytics events fire correctly `[activity: review-code]`

**Integration Checkpoint**: After Phase 3 completion, verify screens render with mocked data and analytics events are captured.

---

### Phase 4: Navigation & Permissions

**Objective**: Add Close Reports to app navigation with proper permission enforcement.

**Dependencies**: Phase 3 must be complete (screens exist for router imports)

**Success Criteria**:
- All tests written BEFORE implementation
- AppPage.closeReports enum value exists
- Permission default set to ShiftLead
- All routes resolve correctly
- Navigation helpers work
- Permission check blocks unauthorized access
- Store name propagates correctly through navigation

**Files to Modify**:
- `lib/core/constants/permission_constants.dart`
- `lib/router/app_router.dart`
- `lib/presentation/screens/store_detail/store_detail_screen.dart` (add Quick Action)

**Test Files to Create**:
- `test/router/close_reports_routes_test.dart`

---

- [x] T4 Phase 4: Navigation & Permissions **COMPLETED**

    - [x] T4.1 Prime Context
        - [x] T4.1.1 Read SDD Section 9 (Navigation & Permissions) `[ref: SDD/Section 9; lines: 1390-1506]`
        - [x] T4.1.2 Read PRD Constraints - permission level requirement `[ref: PRD/Constraints; lines: 278-279]`
        - [x] T4.1.3 Review existing permission constants `[ref: lib/core/constants/permission_constants.dart]`
        - [x] T4.1.4 Review existing router patterns `[ref: lib/router/app_router.dart]`

    - [x] T4.2 Write Tests (TDD - Tests First)
        - [x] T4.2.1 Write route resolution tests (all 3 close report routes) `[activity: flutter-test]`
        - [x] T4.2.2 Write permission redirect tests (unauthorized user blocked) `[activity: flutter-test]`
        - [x] T4.2.3 Write navigation helper tests (goToCloseReports, goToCloseReportDetail, goToCloseReportComparison) `[activity: flutter-test]`
        - [x] T4.2.4 Write store name propagation tests `[activity: flutter-test]`

    - [x] T4.3 Update Permission Constants
        - [x] T4.3.1 Add `closeReports` to `AppPage` enum `[ref: SDD/Section 9.1]` `[activity: flutter-config]`
        - [x] T4.3.2 Add `AppPage.closeReports: AccessLevel.shiftLead` to `DefaultPermissions.defaults` `[ref: SDD/Section 9.1]` `[activity: flutter-config]`

    - [x] T4.4 Update Router
        - [x] T4.4.1 Import close reports screens `[activity: flutter-router]`
        - [x] T4.4.2 Add `close-reports` GoRoute under store detail `[ref: SDD/Section 9.2]` `[activity: flutter-router]`
        - [x] T4.4.3 Add nested `:date` route for detail screen `[ref: SDD/Section 9.2]` `[activity: flutter-router]`
        - [x] T4.4.4 Add nested `compare` route with query parameters `[ref: SDD/Section 9.2]` `[activity: flutter-router]`
        - [x] T4.4.5 Add close reports check to `_getAppPageFromLocation` `[ref: SDD/Section 9.2]` `[activity: flutter-router]`
        - [x] T4.4.6 Ensure storeName query parameter propagates through all routes `[activity: flutter-router]`

    - [x] T4.5 Add Navigation Helpers
        - [x] T4.5.1 Add `goToCloseReports` extension method `[ref: SDD/Section 9.2]` `[activity: flutter-router]`
        - [x] T4.5.2 Add `goToCloseReportDetail` extension method `[ref: SDD/Section 9.2]` `[activity: flutter-router]`
        - [x] T4.5.3 Add `goToCloseReportComparison` extension method `[ref: SDD/Section 9.2]` `[activity: flutter-router]`

    - [x] T4.6 Integrate with Store Detail
        - [x] T4.6.1 Add Close Reports button to Quick Actions section `[ref: PRD/Feature 5]` `[activity: flutter-screen]`
        - [x] T4.6.2 Use `Icons.assessment_rounded` or `Icons.summarize_rounded` icon `[ref: PRD/Open Questions resolved]` `[activity: flutter-screen]`
        - [x] T4.6.3 Implement permission check for button visibility `[ref: PRD/Constraints]` `[activity: flutter-screen]`

    - [x] T4.7 Validate
        - [x] T4.7.1 Run `flutter analyze` - no errors `[activity: lint-code]`
        - [x] T4.7.2 Run route tests - all passing `[activity: run-tests]`
        - [x] T4.7.3 Verify route paths match SDD specification `[activity: review-code]`
        - [x] T4.7.4 Verify permission redirect works for unauthorized users `[activity: manual-test]`
        - [x] T4.7.5 Verify store name appears in Close Reports screens `[activity: manual-test]`

#### Phase 4 Review Summary

**Date of Completion**: 2026-01-26

**Codex Review Findings**:

| Finding | Category | Action Taken |
|---------|----------|--------------|
| Missing validation/redirect for empty comparison params | Critical | FIXED - Added redirect guard in compare route |
| Tests duplicate router logic (can drift from real implementation) | Important | DEFERRED - Current approach is acceptable; can be improved in future |
| Route-level permission tests are indirect | Important | DEFERRED - Current tests provide adequate coverage |
| No test for route order (compare vs :date) | Important | FIXED - Added route order tests |
| No test for missing query params on /compare | Important | FIXED - Added compare redirect validation tests |
| Documentation of comparison params | Nice-to-have | DEFERRED - Code is self-documenting |
| Store detail screen uses raw route string | Nice-to-have | NOT APPLICABLE - Consistent with existing patterns |

**Changes Made Based on Review**:
1. Added redirect guard in `compare` route to validate required `primary` and `comparison` query parameters (lines 716-739 in app_router.dart)
2. Changed builder to use non-null assertions (safe due to redirect guard)
3. Added 6 new tests for compare route validation (missing/empty params)
4. Added 2 new tests for route order verification (compare vs :date pattern)
5. Total tests increased from 25 to 33

**Rejected Suggestions with Rationale**:
1. **Extract `_getAppPageFromLocation` to shared utility**: Low priority - test duplication is acceptable since the test helpers are simple and the risk of drift is low. The real router is tested via integration tests in Phase 5.
2. **Widget tests for GoRouter redirect logic**: High effort - current unit tests adequately cover permission logic. Full router integration will be tested in Phase 5.
3. **Documentation of comparison params**: The redirect guard makes the requirements explicit in code, and the navigation helper signature documents the expected params.

**Items Deferred to Future Phases**:
- Full widget/integration tests of router redirect behavior (Phase 5)
- Potential refactoring to share path builders between production and test code

---

### Phase 5: Integration & Polish

**Objective**: Complete integration testing, perform manual testing, and fix any bugs.

**Dependencies**: Phases 1-4 must be complete

**Success Criteria**:
- Integration tests pass for complete user flows
- Manual testing on iOS and Android passes
- All PRD acceptance criteria verified
- Performance meets requirements (<2s load times)
- All edge cases handled correctly

**Files to Create**:
- `test/integration/close_reports_flow_test.dart`

---

- [ ] T5 Phase 5: Integration & Polish

    - [ ] T5.1 Prime Context
        - [ ] T5.1.1 Read SDD Section 15 (Testing Strategy) `[ref: SDD/Section 15; lines: 1815-1838]`
        - [ ] T5.1.2 Read SDD Section 17 (Quality Requirements) `[ref: SDD/Section 17; lines: 1908-1933]`
        - [ ] T5.1.3 Read PRD Success Metrics `[ref: PRD/Success Metrics; lines: 246-256]`
        - [ ] T5.1.4 Read PRD Edge Cases `[ref: PRD/Detailed Feature Specifications; lines: 236-244]`

    - [ ] T5.2 Write Integration Tests
        - [ ] T5.2.1 Test full flow: dashboard -> store detail -> close reports -> detail `[ref: PRD User Journey: Daily Report Review]` `[activity: flutter-test]`
        - [ ] T5.2.2 Test calendar navigation flow `[ref: PRD User Journey: Historical Analysis]` `[activity: flutter-test]`
        - [ ] T5.2.3 Test comparison flow end-to-end `[ref: PRD/Feature 4]` `[activity: flutter-test]`
        - [ ] T5.2.4 Test permission denial for unauthorized users `[activity: flutter-test]`
        - [ ] T5.2.5 Test error recovery flows (network error -> retry) `[activity: flutter-test]`
        - [ ] T5.2.6 Test same-date comparison rejection `[ref: PRD Edge Case]` `[activity: flutter-test]`
        - [ ] T5.2.7 Test auto-swap when comparison date is newer `[ref: PRD Edge Case]` `[activity: flutter-test]`
        - [ ] T5.2.8 Test "No comparison available" display `[ref: PRD Edge Case]` `[activity: flutter-test]`
        - [ ] T5.2.9 Test list pagination inline retry `[ref: PRD Edge Case]` `[activity: flutter-test]`

    - [ ] T5.3 Manual Testing
        - [ ] T5.3.1 Test on iOS device/simulator `[activity: manual-test]`
        - [ ] T5.3.2 Test on Android device/emulator `[activity: manual-test]`
        - [ ] T5.3.3 Verify load times meet performance requirements (<2s) `[ref: SDD/Section 17.1]` `[activity: manual-test]`
        - [ ] T5.3.4 Test offline/network error scenarios `[activity: manual-test]`
        - [ ] T5.3.5 Test with stores that have no reports (empty state) `[activity: manual-test]`
        - [ ] T5.3.6 Test with stores that have discrepancies `[activity: manual-test]`
        - [ ] T5.3.7 Test comparison with missing comparison date `[activity: manual-test]`
        - [ ] T5.3.8 Test date picker with gaps in available dates `[ref: PRD/Edge Cases]` `[activity: manual-test]`
        - [ ] T5.3.9 Verify analytics events fire correctly in real app `[activity: manual-test]`

    - [ ] T5.4 Bug Fixes
        - [ ] T5.4.1 Address any issues found in integration tests `[activity: flutter-bug-fix]`
        - [ ] T5.4.2 Address any issues found in manual testing `[activity: flutter-bug-fix]`
        - [ ] T5.4.3 Fix any accessibility issues `[activity: flutter-bug-fix]`

    - [ ] T5.5 Final Validation
        - [ ] T5.5.1 All unit tests passing `[activity: run-tests]`
        - [ ] T5.5.2 All widget tests passing `[activity: run-tests]`
        - [ ] T5.5.3 All screen tests passing `[activity: run-tests]`
        - [ ] T5.5.4 All integration tests passing `[activity: run-tests]`
        - [ ] T5.5.5 `flutter analyze` - no errors or warnings `[activity: lint-code]`
        - [ ] T5.5.6 Code formatted with `dart format .` `[activity: format-code]`
        - [ ] T5.5.7 Test coverage meets standards `[activity: run-tests]`

    - [ ] T5.6 PRD Acceptance Criteria Verification
        - [ ] T5.6.1 Feature 1: View Latest Close Report - all criteria met `[ref: PRD/Feature 1]` `[activity: business-acceptance]`
        - [ ] T5.6.2 Feature 2: Navigate by Date - all criteria met `[ref: PRD/Feature 2]` `[activity: business-acceptance]`
        - [ ] T5.6.3 Feature 3: List Recent Reports - all criteria met `[ref: PRD/Feature 3]` `[activity: business-acceptance]`
        - [ ] T5.6.4 Feature 4: Compare Two Reports - all criteria met `[ref: PRD/Feature 4]` `[activity: business-acceptance]`
        - [ ] T5.6.5 Feature 5: Navigation Integration - all criteria met `[ref: PRD/Feature 5]` `[activity: business-acceptance]`
        - [ ] T5.6.6 Feature 6: Section Expansion - all criteria met `[ref: PRD/Feature 6]` `[activity: business-acceptance]`
        - [ ] T5.6.7 Feature 7: Discrepancy Highlighting - all criteria met `[ref: PRD/Feature 7]` `[activity: business-acceptance]`

    - [ ] T5.7 SDD Compliance Verification
        - [ ] T5.7.1 Data models match SDD Section 2 exactly `[ref: SDD/Section 2]` `[activity: review-code]`
        - [ ] T5.7.2 Entities match SDD Section 3 exactly `[ref: SDD/Section 3]` `[activity: review-code]`
        - [ ] T5.7.3 Mappers match SDD Section 4 exactly `[ref: SDD/Section 4]` `[activity: review-code]`
        - [ ] T5.7.4 Repository matches SDD Sections 5-6 exactly `[ref: SDD/Section 5, 6]` `[activity: review-code]`
        - [ ] T5.7.5 Datasource matches SDD Section 7 exactly `[ref: SDD/Section 7]` `[activity: review-code]`
        - [ ] T5.7.6 Providers match SDD Section 8 exactly `[ref: SDD/Section 8]` `[activity: review-code]`
        - [ ] T5.7.7 File structure matches SDD Section 13 `[ref: SDD/Section 13]` `[activity: review-code]`

---

## Summary

| Phase | Description | Task Count | Dependencies |
|-------|-------------|------------|--------------|
| Phase 1 | Data Layer Foundation | 44 tasks | None |
| Phase 2 | Provider Layer | 30 tasks | Phase 1 |
| Phase 3 | UI Layer (Screens & Widgets) | 58 tasks | Phases 1, 2 |
| Phase 4 | Navigation & Permissions | 22 tasks | Phases 1, 2, 3 |
| Phase 5 | Integration & Polish | 35 tasks | Phases 1-4 |
| **Total** | | **189 tasks** | |

**Key Changes from v1.0.0**:
1. **Phase 3/4 Swap**: UI Layer (screens) now Phase 3, Navigation now Phase 4 (fixes compilation dependency)
2. **TDD Enforced**: Tests written BEFORE implementation in every phase
3. **API Client Wiring**: Explicit tasks for SchedulingApiClient configuration and integration test
4. **Error Handling Complete**: All error types mapped, toast notifications, auth redirect tasks
5. **PRD Edge Cases Covered**: Same-date validation, auto-swap, "No comparison available", pagination retry
6. **DateSelectorModal Detailed**: Subtasks for disabled dates, highlight dots, month navigation, loading state
7. **Analytics with Screens**: Instrumentation tasks in Phase 3 alongside screen implementation
8. **Integration Checkpoints**: After Phase 1 and Phase 3 for early verification
9. **Risk Section Added**: Documents key risks and mitigations
10. **Store Name Propagation**: Explicit tasks to ensure store name flows through navigation

**Parallel Opportunities**:
- T1.3 (Models) and T1.4 (Entities) can run in parallel after T1.2 tests written
- T2.5 (Detail/Latest providers) tasks are parallel
- T3.4 (Widgets) tasks can run in parallel

---

*Implementation Plan Version: 2.0.0*
*Created: 2026-01-26*
*Updated: 2026-01-26 (Codex review fixes)*
*Spec ID: 004-close-reports-frontend*