TenantAtlas/specs/193-monitoring-action-hierarchy/tasks.md

Tasks: Monitoring Surface Action Hierarchy and Workbench Semantics

Input: Design documents from /specs/193-monitoring-action-hierarchy/
Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/monitoring-action-hierarchy.logical.openapi.yaml, quickstart.md

Tests: Required. This feature changes runtime behavior on existing Filament v5 / Livewire v4 monitoring surfaces, so Pest guard, feature, RBAC, and browser smoke coverage must be added or extended.

Organization: Tasks are grouped by user story so each slice stays independently testable. Recommended delivery order is US1 -> US2 -> US3 -> US4, with US1 as the MVP cut after the shared guard foundation is in place.

Phase 1: Setup (Shared Infrastructure)

Purpose: Prepare dedicated test entry points for the monitoring-surface hierarchy slice.

• T001 Create the Spec 193 guard test scaffold in apps/platform/tests/Feature/Guards/Spec193MonitoringSurfaceHierarchyGuardTest.php
• T002 [P] Create focused monitoring hierarchy test scaffolds in apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueHierarchyTest.php and apps/platform/tests/Feature/Monitoring/OperationsHeaderHierarchyTest.php
• T003 [P] Create the browser smoke scaffold in apps/platform/tests/Browser/Spec193MonitoringSurfaceHierarchySmokeTest.php

Checkpoint: Dedicated Spec 193 test entry points exist and the implementation can proceed without mixing this slice into unrelated suites.

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Codify the shared monitoring-surface inventory and validation rules that every user story depends on.

⚠️ CRITICAL: No user story work should start before this phase is complete.

• T004 [P] Add Spec 193 inventory contract expectations in apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php
• T005 [P] Add Spec 193 validation-rule expectations in apps/platform/tests/Feature/Guards/ActionSurfaceValidatorTest.php
• T006 [P] Add completeness and exception-reason coverage in apps/platform/tests/Feature/Guards/Spec193MonitoringSurfaceHierarchyGuardTest.php
• T007 Implement the Spec 193 monitoring-surface inventory and retire the blanket Alerts exemption in apps/platform/app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php
• T008 Implement Spec 193 classification and exception validation in apps/platform/app/Support/Ui/ActionSurface/ActionSurfaceValidator.php

Checkpoint: The repo can enumerate, classify, and fail CI on undocumented monitoring-surface hierarchy regressions before any page-level refactor starts.

---

Phase 3: User Story 1 - Review a Queue Without Header Ambiguity (Priority: P1) 🎯 MVP

Goal: Make Finding Exceptions Queue read as a quiet monitoring surface when nothing is selected and as a focused review workbench only when a decision-ready exception is active.

Independent Test: Open the queue with and without a selected exception and confirm that scope, utility, drilldown, and decision actions no longer render as one flat peer strip.

Tests for User Story 1

Note

: Write these tests first and confirm they fail before implementation.

• T009 [P] [US1] Add no-selection vs selected-workbench hierarchy coverage in apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueHierarchyTest.php
• T010 [P] [US1] Extend approval and rejection authorization continuity coverage in apps/platform/tests/Feature/Rbac/ActionSurfaceRbacSemanticsTest.php

Implementation for User Story 1

• T011 [US1] Refactor layered header actions and selected-state visibility in apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php
• T012 [US1] Align queue detail, utility, and related-drilldown rendering in apps/platform/resources/views/filament/pages/monitoring/finding-exceptions-queue.blade.php

Checkpoint: Finding Exceptions Queue is independently functional with a calm no-selection state and a distinct selected-exception work lane.

---

Phase 4: User Story 2 - Read One Operation Run Without Mixed Context Signals (Priority: P1)

Goal: Make Operations and the tenantless operation run viewer separate scope, navigation, utility, related links, and follow-up actions so the monitoring flow reads clearly from list to detail.

Independent Test: Open Operations and drill into the tenantless viewer from multiple origin contexts, then verify that return navigation stays quieter than refresh or run follow-up actions and that related links do not compete with the main work lane.

Tests for User Story 2

Note

: Write these tests first and confirm they fail before implementation.

• T013 [P] [US2] Extend viewer hierarchy and calm-no-action coverage in apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php
• T014 [P] [US2] Add operations landing header hierarchy coverage in apps/platform/tests/Feature/Monitoring/OperationsHeaderHierarchyTest.php
• T015 [P] [US2] Extend canonical navigation and related-link assertions in apps/platform/tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php and apps/platform/tests/Feature/Monitoring/OperationsRelatedNavigationTest.php
• T016 [P] [US2] Extend shared scope-label and return-affordance coverage in apps/platform/tests/Feature/OpsUx/OperateHubShellTest.php

Implementation for User Story 2

• T017 [US2] Refactor viewer context, navigation, utility, and follow-up action layering in apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
• T018 [US2] Align the tenantless operation viewer header rendering in apps/platform/resources/views/filament/pages/operations/tenantless-operation-run-viewer.blade.php
• T019 [US2] Refactor operations landing scope-reset and header hierarchy in apps/platform/app/Filament/Pages/Monitoring/Operations.php
• T020 [US2] Align operations landing context-bar and header rendering in apps/platform/resources/views/filament/pages/monitoring/operations.blade.php

Checkpoint: Operations and the tenantless run viewer are independently functional and clearly separate context, navigation, utility, and follow-up actions.

---

Phase 5: User Story 3 - Preserve Calm Monitoring Pages Without Forced Churn (Priority: P2)

Goal: Explicitly classify shared-pattern monitoring pages and bounded-scope reference pages so only genuinely ambiguous surfaces change while calm pages remain calm.

Independent Test: Review Alerts, Audit Log, alert deliveries, Evidence Overview, Review Register, Baseline Compare Landing, and Baseline Compare Matrix and confirm they either remain calm or receive only documented minor alignment.

Tests for User Story 3

Note

: Write these tests first and confirm they fail before implementation.

• T021 [P] [US3] Add minor-alignment coverage for the Alerts overview in apps/platform/tests/Feature/Monitoring/AlertsHierarchyTest.php and alert-delivery calm/deep-link behavior in apps/platform/tests/Feature/Filament/Alerts/AlertDeliveryViewerTest.php and apps/platform/tests/Feature/Alerts/AlertDeliveryDeepLinkFiltersTest.php
• T022 [P] [US3] Extend Audit Log minor-alignment coverage in apps/platform/tests/Feature/Monitoring/AuditLogInspectFlowTest.php and apps/platform/tests/Feature/Filament/AuditLogPageTest.php
• T023 [P] [US3] Add calm-reference no-regression coverage for Evidence Overview and Review Register in apps/platform/tests/Feature/Evidence/EvidenceOverviewPageTest.php and apps/platform/tests/Feature/TenantReview/TenantReviewRegisterTest.php
• T024 [P] [US3] Add calm-reference no-regression coverage for Baseline Compare Landing and Baseline Compare Matrix in apps/platform/tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php and apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php

Implementation for User Story 3

• T025 [US3] Add explicit monitoring-surface declaration and origin-context alignment in apps/platform/app/Filament/Pages/Monitoring/Alerts.php
• T026 [US3] Tighten shared-pattern hierarchy only where needed in apps/platform/app/Filament/Pages/Monitoring/AuditLog.php and apps/platform/app/Filament/Resources/AlertDeliveryResource/Pages/ListAlertDeliveries.php

Checkpoint: Minor-alignment pages are explicit and bounded, while calm reference pages stay independently testable without cosmetic rebuilds.

---

Phase 6: User Story 4 - Keep Special Diagnostic Surfaces Explicit (Priority: P3)

Goal: Preserve Tenant Diagnostics as the single documented diagnostic exception, with repair actions visible only when a real defect exists.

Independent Test: Open Tenant Diagnostics with and without repair-needed conditions and confirm that repair actions only appear when justified and remain protected by explicit exception coverage and existing access semantics.

Tests for User Story 4

Note

: Write these tests first and confirm they fail before implementation.

• T027 [P] [US4] Extend explicit exception-reason coverage in apps/platform/tests/Feature/Guards/Spec193MonitoringSurfaceHierarchyGuardTest.php
• T028 [P] [US4] Extend tenant diagnostics repair-state coverage in apps/platform/tests/Feature/Filament/TenantDiagnosticsRepairsTest.php
• T029 [P] [US4] Extend tenant diagnostics access semantics in apps/platform/tests/Feature/TenantRBAC/TenantDiagnosticsAccessTest.php

Implementation for User Story 4

• T030 [US4] Update repair-action visibility and explicit special-type declaration handling in apps/platform/app/Filament/Pages/TenantDiagnostics.php

Checkpoint: Tenant Diagnostics remains independently functional as an explicit exception surface without weakening the general monitoring hierarchy rule.

---

Phase 7: Polish & Cross-Cutting Concerns

Purpose: Lock the slice down with browser proof, copy review, and focused verification.

• T031 [P] Add remediated, exception, and calm-reference browser smoke coverage in apps/platform/tests/Browser/Spec193MonitoringSurfaceHierarchySmokeTest.php
• T032 Review operator-facing labels, modal titles, notifications, and audit prose in apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php, apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php, apps/platform/app/Filament/Pages/Monitoring/Operations.php, apps/platform/app/Filament/Pages/Monitoring/Alerts.php, apps/platform/app/Filament/Pages/Monitoring/AuditLog.php, apps/platform/app/Filament/Resources/AlertDeliveryResource/Pages/ListAlertDeliveries.php, and apps/platform/app/Filament/Pages/TenantDiagnostics.php
• T033 [P] Add explicit non-regression assertions for confirmation depth, reason capture, provider-dispatch semantics, and record-page header leakage in apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php and apps/platform/tests/Feature/Guards/Spec193MonitoringSurfaceHierarchyGuardTest.php
• T034 [P] Run the focused Sail verification and formatting workflow from specs/193-monitoring-action-hierarchy/quickstart.md against the changed guard, feature, browser, and page files

---

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 Story 1 (Phase 3): Depends on Foundational completion; recommended MVP cut.
• User Story 2 (Phase 4): Depends on Foundational completion; can run in parallel with US1 if capacity allows, but is easier to review after US1 establishes the pattern.
• User Story 3 (Phase 5): Depends on Foundational completion; can proceed in parallel with US1 or US2 because it focuses on classification preservation and minor alignment.
• User Story 4 (Phase 6): Depends on Foundational completion; can proceed in parallel with US3 once the exception contract exists.
• Polish (Phase 7): Depends on all desired user stories being complete.

User Story Dependencies

• US1: No dependencies beyond Foundational.
• US2: No dependencies beyond Foundational, but it reuses the hierarchy and context patterns proven in US1.
• US3: No dependencies beyond Foundational; it validates that shared-pattern and bounded-scope pages stay intentionally calm.
• US4: No dependencies beyond Foundational; it specializes the exception path after the inventory and validator rules exist.

Within Each User Story

• Write the story tests first and confirm they fail before implementation.
• Update page classes before finalizing any matching Blade view adjustments.
• Keep each story independently shippable before moving to the next priority.

Parallel Opportunities

• T002 and T003 can run in parallel after T001.
• T004, T005, and T006 can run in parallel before implementing T007 and T008.
• Within US1, T009 and T010 can run in parallel.
• Within US2, T013, T014, T015, and T016 can run in parallel.
• Within US3, T021, T022, T023, and T024 can run in parallel.
• Within US4, T027, T028, and T029 can run in parallel.
• T031 and T033 can run in parallel once all page-level changes are complete.

---

Parallel Example: User Story 1

# Parallel test pass for US1
T009 Add no-selection vs selected-workbench hierarchy coverage in apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueHierarchyTest.php
T010 Extend approval and rejection authorization continuity coverage in apps/platform/tests/Feature/Rbac/ActionSurfaceRbacSemanticsTest.php

Parallel Example: User Story 2

# Parallel test pass for US2
T013 Extend viewer hierarchy coverage in apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php
T014 Add operations landing header hierarchy coverage in apps/platform/tests/Feature/Monitoring/OperationsHeaderHierarchyTest.php
T015 Extend canonical navigation and related-link assertions in apps/platform/tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php and apps/platform/tests/Feature/Monitoring/OperationsRelatedNavigationTest.php
T016 Extend shared scope-label and return-affordance coverage in apps/platform/tests/Feature/OpsUx/OperateHubShellTest.php

Parallel Example: User Story 3

# Parallel test pass for US3
T021 Add Alerts overview and alert-delivery minor-alignment coverage
T022 Extend Audit Log minor-alignment coverage
T023 Add Evidence Overview and Review Register no-regression coverage
T024 Add Baseline Compare Landing and Matrix no-regression coverage

Parallel Example: User Story 4

# Parallel test pass for US4
T027 Extend explicit exception-reason coverage in apps/platform/tests/Feature/Guards/Spec193MonitoringSurfaceHierarchyGuardTest.php
T028 Extend tenant diagnostics repair-state coverage in apps/platform/tests/Feature/Filament/TenantDiagnosticsRepairsTest.php
T029 Extend tenant diagnostics access semantics in apps/platform/tests/Feature/TenantRBAC/TenantDiagnosticsAccessTest.php

---

Implementation Strategy

MVP First (User Story 1 Only)

1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational guard and inventory work.
3. Complete Phase 3: User Story 1.
4. Validate the queue hierarchy through the focused US1 tests.
5. Stop and review the remediated workbench pattern before widening the slice.

Incremental Delivery

1. Ship US1 to establish the first remediated monitoring workbench pattern.
2. Add US2 to carry the same action hierarchy into Operations and the canonical run viewer.
3. Add US3 to classify shared-pattern surfaces and preserve calm references without churn.
4. Add US4 to formalize the Tenant Diagnostics exception path.
5. Finish with explicit FR-193-019 non-regression assertions, browser smoke, and focused Sail verification from Phase 7.

Parallel Team Strategy

1. One contributor completes Setup and Foundational tasks.
2. After Foundation is green:
   • Contributor A takes US1.
   • Contributor B takes US2.
   • Contributor C takes US3.
   • Contributor D takes US4.
3. Merge back for Phase 7 browser smoke and focused verification.