ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
e02799b383
TenantAtlas/specs/198-monitoring-page-state/tasks.md
ahmido e02799b383 feat: implement spec 198 monitoring page state contract (#238) 
## Summary
- implement Spec 198 monitoring page-state contracts across Operations, Audit Log, Finding Exceptions Queue, Evidence Overview, Baseline Compare Landing, and Baseline Compare Matrix
- align selected-record and draft/apply behavior with query/session restoration semantics, including canonical navigation and tenant-filter normalization helpers
- add Spec 198 feature and browser coverage, update closure/spec artifacts, and refresh affected regression tests that asserted pre-contract behavior

## Verification
- focused Spec 198 feature pack passed through Sail
- Spec 198 browser smoke passed through Sail
- existing Spec 190 and Spec 194 browser smokes passed through Sail
- targeted fallout tests were updated and rerun during full-suite triage

## Notes
- Livewire v4 / Filament v5 compliant only; no legacy API reintroduction
- no provider registration changes; Laravel 11+ provider registration remains in `bootstrap/providers.php`
- no global-search behavior changed for any resource
- destructive queue decision actions remain confirmation-gated and authorization-backed
- no new Filament assets were added; existing deploy step for `php artisan filament:assets` remains unchanged

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #238
2026-04-15 21:59:42 +00:00

18 KiB
Raw Blame History

Tasks: Monitoring Page-State Contract

Input: Design documents from /specs/198-monitoring-page-state/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/

Tests: For runtime behavior changes in this repo, tests are REQUIRED (Pest). Operations: This feature does not create or reuse a new OperationRun; existing Monitoring and governance writes keep their current run, audit, and confirmation behavior. RBAC: Authorization semantics remain unchanged, but tasks include negative-path coverage where requested query or selected-record state becomes unauthorized or invalid. UI Naming: Operator-facing labels and helper copy must stay aligned with the spec's canonical vocabulary (Operations, Audit log, Finding exceptions queue, Evidence overview, Baseline compare matrix, Inspect event, Approve exception, Reject exception, Apply filters, Reset filters). Operator Surfaces: Each changed page keeps the spec's declared surface role and single inspect/open model. Filament UI Action Surfaces: All changed pages must preserve one primary inspect model, keep destructive-like actions confirmation-gated, and avoid introducing new page-local status or action frameworks. Proportionality / Anti-Bloat: Keep the implementation surface-first and page-local; do not introduce a global page-state engine or new persistence.

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

Phase 1: Setup (Shared Infrastructure)

Purpose: Prepare shared verification scaffolding for Spec 198 without changing runtime behavior yet.

  • T001 [P] Create the cross-surface contract test scaffold in apps/platform/tests/Feature/Monitoring/MonitoringPageStateContractTest.php
  • T002 [P] Create the Spec 198 browser smoke scaffold in apps/platform/tests/Browser/Spec198MonitoringPageStateSmokeTest.php
  • T003 [P] Extend the shared state-persistence harness in apps/platform/tests/Feature/Filament/TableStatePersistenceTest.php

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Establish the shared page-state contract structure and helper touchpoints before any surface-specific work begins.

⚠️ CRITICAL: No user story work can begin until this phase is complete.

  • T004 [P] Add explicit page-state contract declarations to apps/platform/app/Filament/Pages/Monitoring/Operations.php, apps/platform/app/Filament/Pages/Monitoring/AuditLog.php, apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php, and apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php
  • T005 [P] Add explicit page-state contract declarations to apps/platform/app/Filament/Pages/BaselineCompareLanding.php and apps/platform/app/Filament/Pages/BaselineCompareMatrix.php
  • T006 [P] Align shared query/session/navigation normalization touchpoints in apps/platform/app/Support/Filament/CanonicalAdminTenantFilterState.php and apps/platform/app/Support/Navigation/CanonicalNavigationContext.php
  • T007 Update cross-surface state-class, query-role, invalid-fallback, and shared inspect-vocabulary assertions in apps/platform/tests/Feature/Monitoring/MonitoringPageStateContractTest.php
  • T008 Update tenant-sensitive persistence and restore-boundary assertions in apps/platform/tests/Feature/Filament/TableStatePersistenceTest.php

Checkpoint: Foundation ready. All user stories can now proceed independently.

Phase 3: User Story 1 - Enter Operations Without Tab Drift (Priority: P1) 🎯 MVP

Goal: Make Operations use one deterministic contract for requested dashboard state, tenant prefilter, tabs, and persisted table state.

Independent Test: Open Operations directly and from KPI/drillthrough context, change tabs and filters, and confirm refresh or reopen behavior restores only the documented shareable state.

Tests for User Story 1 ⚠️

Note

: Write these tests first, ensure they fail before implementation.

  • T009 [P] [US1] Extend deeplink, dashboard-prefilter, and unauthorized requested-tenant fallback coverage in apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php and apps/platform/tests/Feature/Rbac/ActionSurfaceRbacSemanticsTest.php
  • T010 [P] [US1] Extend Operations restorable tab/filter coverage in apps/platform/tests/Feature/Filament/TableStatePersistenceTest.php

Implementation for User Story 1

  • T011 [US1] Align requested tenant, requested dashboard prefilter, and activeTab precedence in apps/platform/app/Filament/Pages/Monitoring/Operations.php
  • T012 [US1] Update explicit shareable/restorable tab and filter cues in apps/platform/resources/views/filament/pages/monitoring/operations.blade.php

Checkpoint: Operations behaves as a predictable simple monitoring surface and is testable independently.

Phase 4: User Story 2 - Inspect Audit Events Through One Model (Priority: P1)

Goal: Make Audit Log use one selected-event inspect contract for action-based inspect, deeplink entry, close detail, and refresh.

Independent Test: Open Audit Log with and without a selected event, inspect an event, then refresh and back-navigate to confirm there is only one selected-event model.

Tests for User Story 2 ⚠️

  • T013 [P] [US2] Extend selected-event hydration, invalid or unauthorized event fallback, and close-detail restoration coverage in apps/platform/tests/Feature/Monitoring/AuditLogInspectFlowTest.php and apps/platform/tests/Feature/Rbac/ActionSurfaceRbacSemanticsTest.php
  • T014 [P] [US2] Extend persisted filter and selected-event clear-state coverage in apps/platform/tests/Feature/Filament/TableStatePersistenceTest.php

Implementation for User Story 2

  • T015 [US2] Make selectedAuditLogId the single inspect source in apps/platform/app/Filament/Pages/Monitoring/AuditLog.php
  • T016 [US2] Align inline event-detail rendering and close-detail controls in apps/platform/resources/views/filament/pages/monitoring/audit-log.blade.php and apps/platform/resources/views/filament/pages/monitoring/partials/audit-log-inspect-event.blade.php

Checkpoint: Audit Log is independently testable with one selected-event inspect model.

Phase 5: User Story 3 - Review Finding Exceptions Through One Workbench State (Priority: P1)

Goal: Make Finding Exceptions Queue use one selected-exception workbench model for inspect, summary, decision actions, and refresh.

Independent Test: Open the queue with and without a selected exception and verify that summary, decision actions, and refresh behavior all derive from the same selected-exception state.

Tests for User Story 3 ⚠️

  • T017 [P] [US3] Extend selected-exception hydration, invalid or unauthorized fallback, and selection-clearing coverage in apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueHierarchyTest.php and apps/platform/tests/Feature/Rbac/ActionSurfaceRbacSemanticsTest.php
  • T018 [P] [US3] Extend calm-queue vs decision-ready state coverage in apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueTest.php

Implementation for User Story 3

  • T019 [US3] Make selectedFindingExceptionId the sole inspect/review state in apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php
  • T020 [US3] Align selected-exception summary and decision-lane rendering in apps/platform/resources/views/filament/pages/monitoring/finding-exceptions-queue.blade.php

Checkpoint: Finding Exceptions Queue is independently testable as one selected-exception workbench flow.

Phase 6: User Story 4 - Keep Compare Matrix Explicitly Special (Priority: P1)

Goal: Preserve Baseline Compare Matrix as an explicit draft/apply special case while making launch-context, applied state, and focus state predictable.

Independent Test: Launch the matrix from the landing page, change draft filters without applying them, apply the new state, focus a subject, and verify what refresh, back, and a shared link restore.

Tests for User Story 4 ⚠️

  • T021 [P] [US4] Extend launch-context hydration and focus handoff coverage in apps/platform/tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php
  • T022 [P] [US4] Extend draft/apply, focus restoration, and draft discard coverage in apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php
  • T023 [P] [US4] Extend invalid and unauthorized compare-context fallback coverage in apps/platform/tests/Feature/Rbac/BaselineCompareMatrixAuthorizationTest.php

Implementation for User Story 4

  • T024 [US4] Treat compare landing context as initialization-only state in apps/platform/app/Filament/Pages/BaselineCompareLanding.php and apps/platform/resources/views/filament/pages/baseline-compare-landing.blade.php
  • T025 [US4] Separate draft, applied, focus, and shareable slices in apps/platform/app/Filament/Pages/BaselineCompareMatrix.php
  • T026 [US4] Surface draft/apply/focus semantics in apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php

Checkpoint: Compare Matrix remains powerful but independently testable with explicit launch, draft/apply, and focus semantics.

Phase 7: User Story 5 - Preserve Simple Monitoring Pages Without One-Off Protocols (Priority: P2)

Goal: Align Evidence Overview with the shared simple monitoring contract for query hydration, clear filters, and restorable filter behavior.

Independent Test: Enter Evidence Overview with prefilter state, clear filters, reopen or refresh the page, and confirm the page behaves like a simple monitoring surface without hidden local exceptions.

Tests for User Story 5 ⚠️

  • T027 [P] [US5] Extend tenant/search hydration, clear-filter, and refresh coverage in apps/platform/tests/Feature/Evidence/EvidenceOverviewPageTest.php

Implementation for User Story 5

  • T028 [US5] Align query hydration, session persistence, and simple-monitoring filter semantics in apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php
  • T029 [US5] Update empty-state and clear-filter rendering for the simple monitoring contract in apps/platform/resources/views/filament/pages/monitoring/evidence-overview.blade.php

Checkpoint: Evidence Overview is independently testable as a simple monitoring surface.

Phase 8: Polish & Cross-Cutting Concerns

Purpose: Final verification, browser coverage, closure documentation, and formatting across all stories.

  • T030 [P] Add cross-surface deeplink, refresh, back, and share smoke coverage in apps/platform/tests/Browser/Spec198MonitoringPageStateSmokeTest.php
  • T031 [P] Extend no-regression browser flows in apps/platform/tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php and apps/platform/tests/Browser/Spec194GovernanceFrictionSmokeTest.php
  • T032 Run the focused Sail feature-test pack for apps/platform/tests/Feature/Monitoring/MonitoringPageStateContractTest.php, apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php, apps/platform/tests/Feature/Monitoring/AuditLogInspectFlowTest.php, apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueHierarchyTest.php, apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueTest.php, apps/platform/tests/Feature/Evidence/EvidenceOverviewPageTest.php, apps/platform/tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php, apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php, apps/platform/tests/Feature/Filament/TableStatePersistenceTest.php, apps/platform/tests/Feature/Rbac/ActionSurfaceRbacSemanticsTest.php, and apps/platform/tests/Feature/Rbac/BaselineCompareMatrixAuthorizationTest.php
  • T033 Execute the manual smoke checklist in specs/198-monitoring-page-state/quickstart.md against /admin/operations, /admin/audit-log, /admin/finding-exceptions/queue, /admin/evidence/overview, and the Baseline Compare routes
  • T034 [P] Update closure documentation in specs/198-monitoring-page-state/spec.md and specs/198-monitoring-page-state/quickstart.md with the final shareable/restorable-state mapping and any Spec 199 handoff notes
  • T035 Run cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent over touched files under apps/platform/app/Filament/Pages/, apps/platform/app/Support/, apps/platform/resources/views/filament/pages/, and apps/platform/tests/

Dependencies & Execution Order

Phase Dependencies

  • Setup (Phase 1): No dependencies. Can start immediately.
  • Foundational (Phase 2): Depends on Setup completion. Blocks all user stories.
  • User Stories (Phases 3-7): All depend on Foundational completion.
    • User Stories 1-4 are all Priority P1 and can proceed in parallel after Phase 2.
    • User Story 5 is Priority P2 and can also proceed after Phase 2, but it is lower delivery priority.
  • Polish (Phase 8): Depends on all desired user stories being complete.

User Story Dependencies

  • User Story 1 (P1): Can start after Foundational. No dependency on other stories.
  • User Story 2 (P1): Can start after Foundational. No dependency on other stories.
  • User Story 3 (P1): Can start after Foundational. No dependency on other stories.
  • User Story 4 (P1): Can start after Foundational. No dependency on other stories; landing and matrix work stay inside the same story.
  • User Story 5 (P2): Can start after Foundational. No dependency on other stories.

Within Each User Story

  • Tests MUST be written and fail before implementation.
  • Page class state logic before Blade rendering updates.
  • Query/session precedence before browser smoke validation.
  • Story-specific verification before moving on to another story.

Parallel Opportunities

  • All Setup tasks marked [P] can run in parallel.
  • Foundational tasks T004, T005, and T006 can run in parallel.
  • Once Foundational is complete, the test tasks for US1-US5 can run in parallel.
  • User Stories 1-4 can be implemented in parallel by different developers after Phase 2.
  • Browser smoke additions T030 and T031 can run in parallel once story behavior is stable.

Parallel Example: User Story 1

# Launch both Operations test tracks together:
Task T009 - Extend deeplink and dashboard-prefilter hydration coverage in apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php
Task T010 - Extend Operations restorable tab/filter coverage in apps/platform/tests/Feature/Filament/TableStatePersistenceTest.php

Parallel Example: User Story 2

# Launch both Audit Log test tracks together:
Task T013 - Extend selected-event hydration, invalid event fallback, and close-detail restoration coverage in apps/platform/tests/Feature/Monitoring/AuditLogInspectFlowTest.php
Task T014 - Extend persisted filter and selected-event clear-state coverage in apps/platform/tests/Feature/Filament/TableStatePersistenceTest.php

Parallel Example: User Story 3

# Launch both Finding Exceptions Queue test tracks together:
Task T017 - Extend selected-exception hydration, invalid fallback, and selection-clearing coverage in apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueHierarchyTest.php
Task T018 - Extend calm-queue vs decision-ready state coverage in apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueTest.php

Parallel Example: User Story 4

# Launch all Compare Matrix verification tasks together:
Task T021 - Extend launch-context hydration and focus handoff coverage in apps/platform/tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php
Task T022 - Extend draft/apply, focus restoration, and draft discard coverage in apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php
Task T023 - Extend invalid and unauthorized compare-context fallback coverage in apps/platform/tests/Feature/Rbac/BaselineCompareMatrixAuthorizationTest.php

Parallel Example: User Story 5

# Evidence Overview can start alongside any P1 story once Phase 2 is complete:
Task T027 - Extend tenant/search hydration, clear-filter, and refresh coverage in apps/platform/tests/Feature/Evidence/EvidenceOverviewPageTest.php

Implementation Strategy

MVP First (User Story 1 Only)

  1. Complete Phase 1: Setup.
  2. Complete Phase 2: Foundational.
  3. Complete Phase 3: User Story 1.
  4. STOP and VALIDATE: Test User Story 1 independently.
  5. Demo or ship the Operations state contract before moving to additional surfaces.

Incremental Delivery

  1. Complete Setup + Foundational → foundation ready.
  2. Add User Story 1 → test independently → deploy/demo.
  3. Add User Story 2 → test independently → deploy/demo.
  4. Add User Story 3 → test independently → deploy/demo.
  5. Add User Story 4 → test independently → deploy/demo.
  6. Add User Story 5 → test independently → deploy/demo.

Parallel Team Strategy

With multiple developers:

  1. Team completes Setup + Foundational together.
  2. Once Foundational is done:
    • Developer A: User Story 1
    • Developer B: User Story 2
    • Developer C: User Story 3
    • Developer D: User Story 4
    • Developer E: User Story 5
  3. Finish with the shared browser, documentation, and verification tasks in Phase 8.

Notes

  • [P] tasks touch different files and have no direct dependency on incomplete tasks.
  • [US#] labels map tasks back to the five user stories in spec.md.
  • Every story remains independently completable and testable after Phase 2.
  • Verify tests fail before implementing each story.
  • Avoid adding a new global page-state framework, shell-level context layer, or new persistence while implementing these tasks.