# 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. - [X] T001 [P] Create the cross-surface contract test scaffold in `apps/platform/tests/Feature/Monitoring/MonitoringPageStateContractTest.php` - [X] T002 [P] Create the Spec 198 browser smoke scaffold in `apps/platform/tests/Browser/Spec198MonitoringPageStateSmokeTest.php` - [X] 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. - [X] 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` - [X] T005 [P] Add explicit page-state contract declarations to `apps/platform/app/Filament/Pages/BaselineCompareLanding.php` and `apps/platform/app/Filament/Pages/BaselineCompareMatrix.php` - [X] 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` - [X] T007 Update cross-surface state-class, query-role, invalid-fallback, and shared inspect-vocabulary assertions in `apps/platform/tests/Feature/Monitoring/MonitoringPageStateContractTest.php` - [X] 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. - [X] 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` - [X] T010 [P] [US1] Extend Operations restorable tab/filter coverage in `apps/platform/tests/Feature/Filament/TableStatePersistenceTest.php` ### Implementation for User Story 1 - [X] T011 [US1] Align requested tenant, requested dashboard prefilter, and `activeTab` precedence in `apps/platform/app/Filament/Pages/Monitoring/Operations.php` - [X] 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 ⚠️ - [X] 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` - [X] 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 - [X] T015 [US2] Make `selectedAuditLogId` the single inspect source in `apps/platform/app/Filament/Pages/Monitoring/AuditLog.php` - [X] 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 ⚠️ - [X] 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` - [X] T018 [P] [US3] Extend calm-queue vs decision-ready state coverage in `apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueTest.php` ### Implementation for User Story 3 - [X] T019 [US3] Make `selectedFindingExceptionId` the sole inspect/review state in `apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php` - [X] 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 ⚠️ - [X] T021 [P] [US4] Extend launch-context hydration and focus handoff coverage in `apps/platform/tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php` - [X] T022 [P] [US4] Extend draft/apply, focus restoration, and draft discard coverage in `apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php` - [X] T023 [P] [US4] Extend invalid and unauthorized compare-context fallback coverage in `apps/platform/tests/Feature/Rbac/BaselineCompareMatrixAuthorizationTest.php` ### Implementation for User Story 4 - [X] 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` - [X] T025 [US4] Separate draft, applied, focus, and shareable slices in `apps/platform/app/Filament/Pages/BaselineCompareMatrix.php` - [X] 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 ⚠️ - [X] 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 - [X] T028 [US5] Align query hydration, session persistence, and simple-monitoring filter semantics in `apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php` - [X] 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. - [X] T030 [P] Add cross-surface deeplink, refresh, back, and share smoke coverage in `apps/platform/tests/Browser/Spec198MonitoringPageStateSmokeTest.php` - [X] T031 [P] Extend no-regression browser flows in `apps/platform/tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php` and `apps/platform/tests/Browser/Spec194GovernanceFrictionSmokeTest.php` - [X] 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` - [X] 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 - [X] 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 - [X] 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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.