ahmido
bef9020159
## Summary - codify Spec 193 as an explicit monitoring/workbench surface inventory with validator and guard coverage - refactor the Finding Exceptions Queue, Operations landing, and tenantless operation viewer into clearer context, navigation, utility, drilldown, and focused-work lanes - align Alerts, Audit Log, and Alert Deliveries with quiet origin-context handling while preserving calm reference surfaces and the explicit Tenant Diagnostics exception - add focused feature coverage, guard coverage, browser smoke coverage, and the full spec artifacts for Spec 193 ## Verification - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php tests/Feature/Guards/ActionSurfaceValidatorTest.php tests/Feature/Guards/Spec193MonitoringSurfaceHierarchyGuardTest.php tests/Feature/OpsUx/OperateHubShellTest.php tests/Feature/Operations/TenantlessOperationRunViewerTest.php tests/Feature/Monitoring/FindingExceptionsQueueHierarchyTest.php tests/Browser/Spec193MonitoringSurfaceHierarchySmokeTest.php` - `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` - integrated-browser smoke pass over queue, operations, operation detail, alerts, audit log, and tenant diagnostics ## Notes - Livewire v4 / Filament v5 stack unchanged - no provider-registration changes; Laravel 11+ provider registration remains in `bootstrap/providers.php` - no new global-search behavior was introduced - destructive and governance-changing actions keep their existing confirmation and authorization semantics - no new assets or migrations were added Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #227
245 lines
16 KiB
Markdown
245 lines
16 KiB
Markdown
# 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. |