ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
7d4d607475
TenantAtlas/specs/162-baseline-gap-details/tasks.md
ahmido 7d4d607475 feat: add baseline gap details surfaces (#192) 
## 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
2026-03-24 19:05:23 +00:00

14 KiB
Raw Blame History

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.

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

  • 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
  • T004 [P] Normalize canonical run-detail reason-bucket extraction helpers for baseline_compare.evidence_gaps.subjects in app/Filament/Resources/OperationRunResource.php
  • T005 [P] Normalize tenant-landing evidence-gap summary/detail extraction in app/Support/Baselines/BaselineCompareStats.php
  • 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

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

Implementation for User Story 1

  • T011 [US1] Persist bounded subject-level evidence-gap buckets for new compare runs in app/Jobs/CompareBaselineToTenantJob.php
  • T012 [US1] Persist capture-phase gap_subjects alongside aggregate gaps in app/Services/Baselines/BaselineContentCapturePhase.php
  • T013 [US1] Render grouped evidence-gap detail sections from the shared read model in app/Filament/Resources/OperationRunResource.php
  • T014 [US1] Create or refine the grouped read-only evidence-gap detail view in resources/views/filament/infolists/entries/evidence-gap-subjects.blade.php
  • 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

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

Implementation for User Story 2

  • T021 [US2] Implement local filtering across reason, policy type, and subject key in resources/views/filament/infolists/entries/evidence-gap-subjects.blade.php
  • 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
  • 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
  • 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

  • T025 [P] [US3] Add legacy-run fallback coverage to tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php
  • T026 [P] [US3] Add tenant-landing fallback coverage for missing-detail versus no-gap states in tests/Feature/Filament/BaselineCompareLandingWhyNoFindingsTest.php
  • 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

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

  • 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
  • T032 Run focused formatting on touched PHP files with vendor/bin/sail bin pint --dirty --format agent
  • 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
  • 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
  • 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

# 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

# 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

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