# Tasks: Enterprise Evidence Gap Details for Baseline Compare

**Input**: Design documents from `/specs/162-baseline-gap-details/`
**Prerequisites**: `plan.md`, `spec.md`, `research.md`, `data-model.md`, `contracts/baseline-gap-details.openapi.yaml`, `quickstart.md`

**Tests**: Runtime behavior changes in this repo require Pest coverage. Each user story below includes the minimum focused tests needed to prove the slice works independently.
**Organization**: Tasks are grouped by user story so each story can be implemented and validated independently.

## Phase 1: Setup (Shared Infrastructure)

**Purpose**: Confirm the feature slice, target files, and verification entrypoints before implementation changes start.

- [X] T001 Confirm the feature scope, affected files, and verification commands in `specs/162-baseline-gap-details/plan.md`, `specs/162-baseline-gap-details/quickstart.md`, and `specs/162-baseline-gap-details/contracts/baseline-gap-details.openapi.yaml`
- [X] T002 Map the current baseline compare detail flow in `app/Jobs/CompareBaselineToTenantJob.php`, `app/Services/Baselines/BaselineContentCapturePhase.php`, `app/Filament/Resources/OperationRunResource.php`, and `app/Filament/Pages/BaselineCompareLanding.php`

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Establish the shared evidence-gap read model and rendering helpers required by all user stories.

**⚠️ CRITICAL**: No user story work should start until this phase is complete.

- [X] T003 Define the shared evidence-gap read-model contract and state mapping in `app/Filament/Resources/OperationRunResource.php` to match `specs/162-baseline-gap-details/data-model.md`
- [X] T004 [P] Normalize canonical run-detail reason-bucket extraction helpers for `baseline_compare.evidence_gaps.subjects` in `app/Filament/Resources/OperationRunResource.php`
- [X] T005 [P] Normalize tenant-landing evidence-gap summary/detail extraction in `app/Support/Baselines/BaselineCompareStats.php`
- [X] T006 Establish the tenant-landing integration points for evidence-gap summary, detail, and diagnostics sections in `app/Filament/Pages/BaselineCompareLanding.php` and `resources/views/filament/pages/baseline-compare-landing.blade.php`

**Checkpoint**: Shared read model and page integration points are clear; user-story implementation can proceed.

---

## Phase 3: User Story 1 - Inspect concrete evidence gaps quickly (Priority: P1) 🎯 MVP

**Goal**: Persist and render grouped concrete evidence-gap subjects so an operator can inspect affected policies without opening raw JSON.

**Independent Test**: Create a baseline compare run with evidence gaps and verify the canonical run detail shows grouped concrete subjects aligned with the aggregate reason buckets.

### Tests for User Story 1

- [X] T007 [P] [US1] Extend compare persistence coverage for reason-grouped subject details in `tests/Feature/Baselines/BaselineCompareAmbiguousMatchGapTest.php`
- [X] T008 [P] [US1] Extend capture-phase subject persistence coverage in `tests/Feature/Baselines/BaselineCompareResumeTokenTest.php`
- [X] T009 [P] [US1] Add or update canonical run-detail rendering coverage for grouped evidence-gap rows in `tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php`
- [X] T010 [P] [US1] Add canonical run-detail render-safety coverage with `bindFailHardGraphClient()` in `tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php`

### Implementation for User Story 1

- [X] T011 [US1] Persist bounded subject-level evidence-gap buckets for new compare runs in `app/Jobs/CompareBaselineToTenantJob.php`
- [X] T012 [US1] Persist capture-phase `gap_subjects` alongside aggregate gaps in `app/Services/Baselines/BaselineContentCapturePhase.php`
- [X] T013 [US1] Render grouped evidence-gap detail sections from the shared read model in `app/Filament/Resources/OperationRunResource.php`
- [X] T014 [US1] Create or refine the grouped read-only evidence-gap detail view in `resources/views/filament/infolists/entries/evidence-gap-subjects.blade.php`
- [X] T015 [US1] Keep raw JSON diagnostics secondary and aligned with the new evidence-gap detail contract in `app/Filament/Resources/OperationRunResource.php`

**Checkpoint**: Operators can inspect concrete evidence-gap subjects on the canonical run detail page without using raw JSON.

---

## Phase 4: User Story 2 - Filter large gap sets without scanning raw diagnostics (Priority: P2)

**Goal**: Let operators narrow evidence-gap detail by reason, policy type, or subject key directly on the page.

**Independent Test**: Open a run with multiple gap reasons and many subject rows, enter a partial search token, and confirm only the relevant grouped rows remain visible.

### Tests for User Story 2

- [X] T016 [P] [US2] Add filtering-affordance assertions for the canonical run detail in `tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php`
- [X] T017 [P] [US2] Add tenant-landing parity and filtering visibility coverage in `tests/Feature/Filament/BaselineCompareLandingAdminTenantParityTest.php`
- [X] T018 [P] [US2] Add tenant-landing render-safety coverage with `bindFailHardGraphClient()` in `tests/Feature/Filament/BaselineCompareLandingAdminTenantParityTest.php`
- [X] T019 [P] [US2] Add unchanged compare-start surface and mutation-scope messaging coverage in `tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php`
- [X] T020 [P] [US2] Add unchanged baseline-compare audit semantics coverage in `tests/Feature/Baselines/BaselineCompareAuditEventsTest.php`

### Implementation for User Story 2

- [X] T021 [US2] Implement local filtering across reason, policy type, and subject key in `resources/views/filament/infolists/entries/evidence-gap-subjects.blade.php`
- [X] T022 [US2] Render the tenant-landing evidence-gap detail block and search affordances in `app/Filament/Pages/BaselineCompareLanding.php` and `resources/views/filament/pages/baseline-compare-landing.blade.php`
- [X] T023 [US2] Align `BaselineCompareStats` reason-group payloads with the canonical run-detail bucket contract in `app/Support/Baselines/BaselineCompareStats.php`, `app/Filament/Pages/BaselineCompareLanding.php`, and `app/Filament/Resources/OperationRunResource.php`
- [X] T024 [US2] Keep tenant-landing raw diagnostics explicitly secondary to summary and evidence-gap detail in `app/Filament/Pages/BaselineCompareLanding.php` and `resources/views/filament/pages/baseline-compare-landing.blade.php`

**Checkpoint**: Operators can isolate relevant evidence-gap rows on both affected surfaces without leaving the page.

---

## Phase 5: User Story 3 - Distinguish missing detail from no gaps (Priority: P3)

**Goal**: Preserve operator trust by clearly distinguishing legacy or partially recorded runs from runs that truly have no evidence gaps.

**Independent Test**: Open one run with aggregate evidence-gap counts but no recorded subject details and another run with no evidence gaps, then verify the UI communicates the difference clearly.

### Tests for User Story 3

- [X] T025 [P] [US3] Add legacy-run fallback coverage to `tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php`
- [X] T026 [P] [US3] Add tenant-landing fallback coverage for missing-detail versus no-gap states in `tests/Feature/Filament/BaselineCompareLandingWhyNoFindingsTest.php`
- [X] T027 [P] [US3] Add explicit tenant-safety regression coverage for canonical and tenant surfaces in `tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php` and `tests/Feature/Filament/BaselineCompareLandingAdminTenantParityTest.php`

### Implementation for User Story 3

- [X] T028 [US3] Implement canonical run-detail fallback messaging for `details_not_recorded` versus `no_gaps` in `app/Filament/Resources/OperationRunResource.php` and `resources/views/filament/infolists/entries/evidence-gap-subjects.blade.php`
- [X] T029 [US3] Implement tenant-landing fallback messaging for legacy and partial-detail compare runs in `app/Filament/Pages/BaselineCompareLanding.php` and `resources/views/filament/pages/baseline-compare-landing.blade.php`
- [X] T030 [US3] Ensure partial reason coverage does not imply zero affected subjects for missing buckets in `app/Filament/Resources/OperationRunResource.php` and `app/Support/Baselines/BaselineCompareStats.php`

**Checkpoint**: Legacy and partial-detail runs remain readable and trustworthy without being mistaken for healthy no-gap runs.

---

## Phase 6: Polish & Cross-Cutting Concerns

**Purpose**: Final consistency, regression validation, and release readiness across all user stories.

- [X] T031 [P] Update feature artifacts for any final contract or wording changes in `specs/162-baseline-gap-details/spec.md`, `specs/162-baseline-gap-details/plan.md`, `specs/162-baseline-gap-details/quickstart.md`, and `specs/162-baseline-gap-details/contracts/baseline-gap-details.openapi.yaml`
- [X] T032 Run focused formatting on touched PHP files with `vendor/bin/sail bin pint --dirty --format agent`
- [X] T033 Run the focused canonical verification pack from `specs/162-baseline-gap-details/quickstart.md` with `vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareAmbiguousMatchGapTest.php tests/Feature/Baselines/BaselineCompareResumeTokenTest.php tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php`
- [X] T034 [P] Run the tenant-landing evidence-gap verification tests with `vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareLandingAdminTenantParityTest.php tests/Feature/Filament/BaselineCompareLandingWhyNoFindingsTest.php tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php tests/Feature/Baselines/BaselineCompareAuditEventsTest.php`
- [X] T035 Execute the manual run-review checks in `specs/162-baseline-gap-details/quickstart.md` against `/admin/operations/{run}` and `/admin/t/{tenant}/baseline-compare-landing`

---

## Dependencies & Execution Order

### Phase Dependencies

- **Phase 1: Setup**: No dependencies.
- **Phase 2: Foundational**: Depends on Phase 1 and blocks all user stories.
- **Phase 3: US1**: Starts after Phase 2 and delivers the MVP.
- **Phase 4: US2**: Starts after Phase 2; depends functionally on the US1 detail structure being present.
- **Phase 5: US3**: Starts after Phase 2; depends functionally on the shared read model and both surface integrations.
- **Phase 6: Polish**: Starts after the desired user stories are complete.

### User Story Dependencies

- **US1 (P1)**: No dependency on other user stories once the foundational phase is complete.
- **US2 (P2)**: Depends on US1 detail rendering because filtering operates on the rendered evidence-gap rows.
- **US3 (P3)**: Depends on US1 read-model/rendering and should also align with US2 surface semantics where filtering is visible.

### Within Each User Story

- Tests should be written or updated before implementation and fail for the missing behavior.
- Persistence work precedes rendering work.
- Rendering work precedes parity and fallback polish.
- Each story should be independently runnable through the focused tests listed above.

## Parallel Opportunities

- `T004` and `T005` can run in parallel after `T003`.
- `T007`, `T008`, `T009`, and `T010` can run in parallel within US1.
- `T016`, `T017`, `T018`, `T019`, and `T020` can run in parallel within US2.
- `T025`, `T026`, and `T027` can run in parallel within US3.
- `T031` and `T034` can run in parallel during Polish.

## Parallel Example: User Story 1

```bash
# Parallelize the US1 regression updates first
Task: T007 tests/Feature/Baselines/BaselineCompareAmbiguousMatchGapTest.php
Task: T008 tests/Feature/Baselines/BaselineCompareResumeTokenTest.php
Task: T009 tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php
Task: T010 tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php

# Then implement the persistence and render paths
Task: T011 app/Jobs/CompareBaselineToTenantJob.php
Task: T012 app/Services/Baselines/BaselineContentCapturePhase.php
Task: T013 app/Filament/Resources/OperationRunResource.php
Task: T014 resources/views/filament/infolists/entries/evidence-gap-subjects.blade.php
```

## Parallel Example: User Story 2

```bash
# Parallelize test scaffolding for both surfaces
Task: T016 tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php
Task: T017 tests/Feature/Filament/BaselineCompareLandingAdminTenantParityTest.php
Task: T018 tests/Feature/Filament/BaselineCompareLandingAdminTenantParityTest.php
Task: T019 tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php
Task: T020 tests/Feature/Baselines/BaselineCompareAuditEventsTest.php

# Then implement filtering and surface parity
Task: T021 resources/views/filament/infolists/entries/evidence-gap-subjects.blade.php
Task: T022 app/Filament/Pages/BaselineCompareLanding.php
Task: T023 app/Support/Baselines/BaselineCompareStats.php
Task: T024 resources/views/filament/pages/baseline-compare-landing.blade.php
```

## Parallel Example: User Story 3

```bash
# Parallelize legacy-state tests
Task: T025 tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php
Task: T026 tests/Feature/Filament/BaselineCompareLandingWhyNoFindingsTest.php
Task: T027 tests/Feature/Filament/BaselineCompareLandingAdminTenantParityTest.php

# Then implement fallback states on both surfaces
Task: T028 app/Filament/Resources/OperationRunResource.php
Task: T029 resources/views/filament/pages/baseline-compare-landing.blade.php
Task: T030 app/Support/Baselines/BaselineCompareStats.php
```

## Implementation Strategy

### MVP First

Deliver Phase 3 first. That yields the core value: subject-level persistence plus canonical run-detail visibility for evidence-gap details.

### Incremental Delivery

1. Complete Setup and Foundational phases.
2. Deliver US1 as the MVP for operator visibility.
3. Add US2 for enterprise-scale filtering and landing-page parity.
4. Add US3 for legacy-run trust and fallback clarity.
5. Finish with formatting, focused regression runs, and manual validation.
