# Tasks: Unified Task Reports by Type

**Input**: Design documents from [`/specs/020-task-reports-design/`](specs/020-task-reports-design)  
**Prerequisites**: [`plan.md`](specs/020-task-reports-design/plan.md), [`spec.md`](specs/020-task-reports-design/spec.md), [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md), [`research.md`](specs/020-task-reports-design/research.md), [`data-model.md`](specs/020-task-reports-design/data-model.md), [`contracts/`](specs/020-task-reports-design/contracts)

**Tests**: Include contract/integration/UI tests for independent story validation.

**Organization**: Tasks are grouped by user story to enable independent implementation and testing.

## Format: `[ID] [P?] [Story] Description`

---

## Phase 1: Setup (Shared Infrastructure)

**Purpose**: Prepare report feature scaffolding and shared fixtures.

- [x] T001 Create reports feature folder placeholders in `backend/src/services/reports/` and `frontend/src/lib/components/reports/`
- [x] T002 [P] Add report fixture set `mixed_task_reports` and `unknown_type_partial_payload` in `backend/tests/fixtures/reports/fixtures_reports.json`
- [x] T003 [P] Add frontend mock payload fixtures for report states in `frontend/src/lib/components/reports/__tests__/fixtures/reports.fixtures.js`
- [x] T004 Register i18n key placeholders for reports UI text in `frontend/src/lib/i18n/locales/en.json` and `frontend/src/lib/i18n/locales/ru.json`

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Build core report domain and API foundations used by all stories.

- [x] T005 Implement canonical report schemas (`TaskReport`, `ReportQuery`, `ReportCollection`, `ReportDetailView`) in `backend/src/models/report.py`
- [x] T006 [P] Implement report type profile registry and unknown fallback mapping in `backend/src/services/reports/type_profiles.py`
- [x] T007 Implement report normalization service in `backend/src/services/reports/normalizer.py`
- [x] T008 Implement aggregation/query service with server-side filtering + pagination in `backend/src/services/reports/report_service.py`
- [x] T009 Add reports API route module with list/detail endpoints in `backend/src/api/routes/reports.py` (CRITICAL: PRE: authenticated/authorized request; POST: returns `{items,total,page,page_size,has_next,applied_filters}` and detail with diagnostics/next_actions; UX_STATE support via deterministic error payloads)
- [x] T010 Wire reports router into API registration in `backend/src/api/routes/__init__.py` and `backend/src/app.py`
- [x] T011 Create frontend reports API client using existing wrapper methods (no native fetch) in `frontend/src/lib/api/reports.js` (CRITICAL: PRE: valid auth context; POST: parsed payload or structured error for UI-state mapping)
- [x] T011a Verify `contracts/modules.md` alignment with `spec.md` requirements and ensure all [DEF] anchors are ready.

**Checkpoint**: Foundational layer complete; user stories can proceed.

---

## Phase 3: User Story 1 - View all task reports in one place (Priority: P1) 🎯 MVP

**Goal**: Provide one consolidated report center that lists all task types in one view.

**Independent Test**: Open reports page with mixed task fixtures and verify LLM/backup/migration/documentation reports are visible in one unified list.

### Tests for User Story 1

- [x] T012 [P] [US1] Add backend contract tests for `GET /api/reports` pagination/filter defaults in `backend/src/api/routes/__tests__/test_reports_api.py`
- [x] T013 [P] [US1] Add frontend integration test for unified mixed-type rendering in `frontend/src/lib/components/reports/__tests__/reports_page.integration.test.js`
  - frontend/src/lib/components/reports/__tests__/reports_page.integration.test.js

### Implementation for User Story 1

- [x] T014 [US1] Implement reports list endpoint handler in `backend/src/api/routes/reports.py` (CRITICAL: PRE: validated query params; POST: normalized deterministic ordering and canonical minimum fields)
- [x] T015 [P] [US1] Implement reports page route container in `frontend/src/routes/reports/+page.svelte`
- [x] T016 [P] [US1] Implement reports list component and row/card composition in `frontend/src/lib/components/reports/ReportsList.svelte` (CRITICAL: Include @UX_STATE Idle/Loading/Error and @TEST_DATA anchors)
- [x] T016a [US1] Implement grouping logic (by date/type) in `ReportsList.svelte` to satisfy FR-008.
- [x] T017 [US1] Implement loading/no-data/error UI states in reports page using UX reference in `frontend/src/routes/reports/+page.svelte` (CRITICAL: UX_STATE Loading/NoData/Error preserved)
- [x] T018 [US1] Add navigation entry to reports page in `frontend/src/lib/components/layout/Sidebar.svelte`
- [x] T019 [US1] Verify implementation matches [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md) (Happy Path & Errors)

**Checkpoint**: US1 independently functional and demo-ready as MVP.

---

## Phase 4: User Story 2 - Recognize report type by distinct design (Priority: P2)

**Goal**: Ensure each report type has a distinct and consistent visual design + explicit label.

**Independent Test**: Render one report per type and confirm each has unique style profile and explicit task-type label.

### Tests for User Story 2

- [x] T020 [P] [US2] Add frontend visual/state tests for type profile mapping and fallback in `frontend/src/lib/components/reports/__tests__/report_type_profiles.test.js`
- [x] T021 [P] [US2] Add backend normalization tests for unknown type fallback mapping in `backend/src/services/reports/__tests__/test_report_normalizer.py`
  - backend/src/services/reports/__tests__/test_report_normalizer.py (Coverage: 100% fallback logic)

### Implementation for User Story 2

- [x] T022 [US2] Implement frontend report type profile registry in `frontend/src/lib/components/reports/reportTypeProfiles.js` (CRITICAL: PRE: known/unknown type input; POST: one fallback profile always returned)
- [x] T023 [US2] Apply type-specific badges, variants, and emphasis rules in `frontend/src/lib/components/reports/ReportCard.svelte`
- [x] T024 [US2] Add explicit textual type labels and accessibility labels in `frontend/src/lib/components/reports/ReportCard.svelte`
- [x] T025 [US2] Implement filtered-empty UX state with one-click reset action in `frontend/src/routes/reports/+page.svelte` (CRITICAL: UX_STATE FilteredEmpty preserved)
- [x] T026 [US2] Verify implementation matches [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md) (Happy Path & Errors)

**Checkpoint**: US2 independently functional with distinct visual semantics.

---

## Phase 5: User Story 3 - Understand report details and outcomes quickly (Priority: P3)

**Goal**: Add detailed report drill-down with clear outcome context and next actions.

**Independent Test**: Open success and failed reports and confirm status, summary, timing, diagnostics, and actionable guidance are immediately visible.

### Tests for User Story 3

- [x] T027 [P] [US3] Add backend contract tests for `GET /api/reports/{report_id}` in `backend/src/api/routes/__tests__/test_reports_detail_api.py`
- [x] T028 [P] [US3] Add frontend detail-panel integration test for failed report recovery guidance in `frontend/src/lib/components/reports/__tests__/report_detail.integration.test.js`
  - frontend/src/lib/components/reports/__tests__/report_detail.integration.test.js

### Implementation for User Story 3

- [x] T029 [US3] Implement report detail endpoint in `backend/src/api/routes/reports.py` (CRITICAL: PRE: auth + report_id exists; POST: normalized detail + diagnostics + next_actions)
- [x] T030 [US3] Implement report detail service assembly in `backend/src/services/reports/report_service.py` (CRITICAL: POST: failed/partial include actionable context when available)
- [x] T031 [P] [US3] Implement report detail panel/page component in `frontend/src/lib/components/reports/ReportDetailPanel.svelte`
- [x] T032 [US3] Integrate list-to-detail interaction and context-preserving navigation in `frontend/src/routes/reports/+page.svelte`
- [x] T033 [US3] Implement partial-data placeholders and failed-report action hints in `frontend/src/lib/components/reports/ReportDetailPanel.svelte` (CRITICAL: UX_RECOVERY preserved)
- [x] T034 [US3] Verify implementation matches [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md) (Happy Path & Errors)

**Checkpoint**: US3 independently functional with complete detail and recovery guidance.

---

## Phase 6: Polish & Cross-Cutting Concerns

**Purpose**: Final consistency, performance, and documentation updates across all stories.

- [x] T035 [P] Add API contract conformance checks against `specs/020-task-reports-design/contracts/reports-api.openapi.yaml` in `backend/src/api/routes/__tests__/test_reports_openapi_conformance.py` (CRITICAL: Verify @UX_STATE and @TEST_DATA metadata compliance)
- [x] T036 [P] Add frontend performance guard test for filter responsiveness in `frontend/src/lib/components/reports/__tests__/reports_filter_performance.test.js`
- [x] T036a [P] Implement virtualization or pagination optimization for large lists (>1000 items) in `ReportsList.svelte` to satisfy FR-011.
- [x] T037 Update operational docs for reports usage and troubleshooting in `docs/settings.md` and `docs/design/resource_centric_layout.md`
- [x] T038 Run end-to-end quickstart validation and capture results in `specs/020-task-reports-design/quickstart.md`
- [x] T039 Run semantic compliance protocol (`python3 generate_semantic_map.py`) and resolve critical parsing errors from latest report
- [x] T040 Remove deprecated tasks page route and redirect UI navigation entry points to reports (`frontend/src/routes/tasks/+page.svelte`, `frontend/src/lib/components/layout/TaskDrawer.svelte`, `frontend/src/components/Navbar.svelte`)
- [x] T041 Fix reports list sorting/filtering for mixed offset-naive and offset-aware datetimes to prevent `GET /api/reports` 500 during active migration (`backend/src/services/reports/report_service.py`, `backend/src/api/routes/__tests__/test_reports_api.py`)
- [x] T042 Add frontend submit-guard for dashboard migration/backup modal actions to prevent duplicate task creation on repeated clicks (`frontend/src/routes/dashboards/+page.svelte`)
- [x] T043 Update semantic map generator to ignore few-shot examples under `.ai/shots/` (`generate_semantic_map.py`)

---

## Dependencies & Execution Order

### Phase Dependencies

- Phase 1 → no dependencies.
- Phase 2 depends on Phase 1 and blocks all user stories.
- Phase 3 (US1) depends on Phase 2.
- Phase 4 (US2) depends on Phase 2; can proceed after US1 baseline route/list exists.
- Phase 5 (US3) depends on Phase 2 and uses US1 list interaction.
- Phase 6 depends on completion of selected user stories.

### User Story Dependency Graph

- **US1 (P1)**: first deliverable (MVP).
- **US2 (P2)**: extends US1 presentation semantics.
- **US3 (P3)**: extends US1 with detail drill-down and diagnostics.

Graph: `US1 -> {US2, US3}`

### Parallel Opportunities

- Setup fixture/i18n tasks: T002, T003, T004.
- Foundational tasks: T006 and T011 parallel with model scaffolding once T005 is done.
- US1 tests T012/T013 in parallel.
- US2 tests T020/T021 in parallel.
- US3 tests T027/T028 and UI detail task T031 in parallel after endpoint contract is stable.
- Cross-cutting checks T035/T036 parallel in Phase 6.

---

## Parallel Example: User Story 1

```bash
Task: "T012 [US1] Add backend contract tests in backend/src/api/routes/__tests__/test_reports_api.py"
Task: "T013 [US1] Add frontend integration test in frontend/src/lib/components/reports/__tests__/reports_page.integration.test.js"

Task: "T015 [US1] Implement reports route in frontend/src/routes/reports/+page.svelte"
Task: "T016 [US1] Implement list component in frontend/src/lib/components/reports/ReportsList.svelte"
```

## Parallel Example: User Story 3

```bash
Task: "T027 [US3] Add backend detail contract tests in backend/src/api/routes/__tests__/test_reports_detail_api.py"
Task: "T028 [US3] Add frontend detail integration test in frontend/src/lib/components/reports/__tests__/report_detail.integration.test.js"

Task: "T030 [US3] Implement detail service assembly in backend/src/services/reports/report_service.py"
Task: "T031 [US3] Implement report detail panel in frontend/src/lib/components/reports/ReportDetailPanel.svelte"
```

---

## Implementation Strategy

### MVP First (Recommended)

1. Complete Phase 1 + Phase 2.
2. Complete Phase 3 (US1) and validate independent test.
3. Demo/deploy MVP unified report list.

### Incremental Delivery

1. Add US2 for visual differentiation after MVP list stability.
2. Add US3 for diagnostics/detail depth.
3. Finish Phase 6 polish and conformance.

### UX Preservation Rule

No task in this plan intentionally degrades the UX defined in [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md).  
Each user story contains a mandatory UX verification task: T019, T026, T034.