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

- [X] T001 Create the Spec 193 guard test scaffold in `apps/platform/tests/Feature/Guards/Spec193MonitoringSurfaceHierarchyGuardTest.php`
- [X] T002 [P] Create focused monitoring hierarchy test scaffolds in `apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueHierarchyTest.php` and `apps/platform/tests/Feature/Monitoring/OperationsHeaderHierarchyTest.php`
- [X] 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.

- [X] T004 [P] Add Spec 193 inventory contract expectations in `apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php`
- [X] T005 [P] Add Spec 193 validation-rule expectations in `apps/platform/tests/Feature/Guards/ActionSurfaceValidatorTest.php`
- [X] T006 [P] Add completeness and exception-reason coverage in `apps/platform/tests/Feature/Guards/Spec193MonitoringSurfaceHierarchyGuardTest.php`
- [X] T007 Implement the Spec 193 monitoring-surface inventory and retire the blanket Alerts exemption in `apps/platform/app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php`
- [X] 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.

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

### Implementation for User Story 1

- [X] T011 [US1] Refactor layered header actions and selected-state visibility in `apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php`
- [X] 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.

- [X] T013 [P] [US2] Extend viewer hierarchy and calm-no-action coverage in `apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php`
- [X] T014 [P] [US2] Add operations landing header hierarchy coverage in `apps/platform/tests/Feature/Monitoring/OperationsHeaderHierarchyTest.php`
- [X] 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`
- [X] T016 [P] [US2] Extend shared scope-label and return-affordance coverage in `apps/platform/tests/Feature/OpsUx/OperateHubShellTest.php`

### Implementation for User Story 2

- [X] T017 [US2] Refactor viewer context, navigation, utility, and follow-up action layering in `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`
- [X] T018 [US2] Align the tenantless operation viewer header rendering in `apps/platform/resources/views/filament/pages/operations/tenantless-operation-run-viewer.blade.php`
- [X] T019 [US2] Refactor operations landing scope-reset and header hierarchy in `apps/platform/app/Filament/Pages/Monitoring/Operations.php`
- [X] 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.

- [X] 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`
- [X] 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`
- [X] 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`
- [X] 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

- [X] T025 [US3] Add explicit monitoring-surface declaration and origin-context alignment in `apps/platform/app/Filament/Pages/Monitoring/Alerts.php`
- [X] 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.

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

### Implementation for User Story 4

- [X] 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.

- [X] T031 [P] Add remediated, exception, and calm-reference browser smoke coverage in `apps/platform/tests/Browser/Spec193MonitoringSurfaceHierarchySmokeTest.php`
- [X] 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`
- [X] 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`
- [X] 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

```bash
# 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

```bash
# 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

```bash
# 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

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