ahmido
7d4d607475
## Summary - add baseline compare evidence gap detail modeling and a dedicated Livewire table surface - extend baseline compare landing and operation run detail surfaces to expose evidence gap details and stats - add spec artifacts for feature 162 and expand feature coverage with focused Filament and baseline tests ## Notes - branch: `162-baseline-gap-details` - commit: `a92dd812` - working tree was clean after push ## Validation - tests were not run in this step Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #192
209 lines
14 KiB
Markdown
209 lines
14 KiB
Markdown
# 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.
|