# 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.