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

Quickstart: Monitoring Surface Action Hierarchy and Workbench Semantics

Goal

Bring the in-scope monitoring, queue, operations, and workbench surfaces under one bounded hierarchy: scope reads as context, navigation reads as navigation, utilities stay utility-level, selected-object or focused actions become prominent only in active work states, calm bounded-scope pages remain calm, and TenantDiagnostics remains the only explicit exception.

Implementation Sequence

1. Confirm the in-scope inventory in code.

   • Add the Spec 193 inventory to the existing ActionSurfaceExemptions layer.
   • Validate which surfaces are remediation-required, minor-alignment only, compliant or no-op, or special-type acceptable.
   • Retire the blanket Alerts baseline exemption and replace it with explicit declaration plus inventory coverage.

2. Remediate the core workbench pages first.

   • Refactor FindingExceptionsQueue so queue scope, utilities, drilldowns, and selected-exception decisions no longer render as flat peers.
   • Refactor TenantlessOperationRunViewer so scope, return navigation, refresh, related links, and resumable actions render as distinct layers.
   • Refactor Operations so scope and show-all context stay visible but quieter than the list’s actual work controls.

3. Tighten shared monitoring patterns and classify the rest.

   • Add an explicit declaration and audit pass to Alerts.
   • Review AuditLog and ListAlertDeliveries for minor alignment only.
   • Confirm EvidenceOverview, BaselineCompareLanding, BaselineCompareMatrix, and ReviewRegister remain calm references.
   • Keep TenantDiagnostics as the explicit special-type exception and verify its exception reason in code.

4. Add regression protection.

   • Extend the existing action-surface validator with Spec 193 inventory validation.
   • Add a dedicated guard test for Spec 193 inventory and exception semantics.
   • Add focused feature tests for the remediated pages and the diagnostic exception.
   • Add one browser smoke suite covering remediated, exception, and reference surfaces.

5. Run focused verification.

   • Run the guard tests, focused feature tests, browser smoke suite, and formatting through Sail.

Suggested Source Files

• 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
• apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php
• apps/platform/app/Filament/Pages/BaselineCompareLanding.php
• apps/platform/app/Filament/Pages/BaselineCompareMatrix.php
• apps/platform/app/Filament/Pages/Reviews/ReviewRegister.php
• apps/platform/app/Filament/Pages/TenantDiagnostics.php
• apps/platform/app/Support/OperateHub/OperateHubShell.php
• apps/platform/app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php
• apps/platform/app/Support/Ui/ActionSurface/ActionSurfaceValidator.php

Suggested Test Files

• apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php
• apps/platform/tests/Feature/Guards/ActionSurfaceValidatorTest.php
• apps/platform/tests/Feature/Guards/Spec193MonitoringSurfaceHierarchyGuardTest.php
• apps/platform/tests/Feature/OpsUx/OperateHubShellTest.php
• apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php
• apps/platform/tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php
• apps/platform/tests/Feature/Monitoring/OperationsRelatedNavigationTest.php
• apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php
• apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueHierarchyTest.php
• apps/platform/tests/Feature/Monitoring/OperationsHeaderHierarchyTest.php
• apps/platform/tests/Browser/Spec193MonitoringSurfaceHierarchySmokeTest.php

Minimum Verification Commands

Run all commands through Sail from apps/platform.

cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceValidatorTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/Spec193MonitoringSurfaceHierarchyGuardTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/OpsUx/OperateHubShellTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Operations/TenantlessOperationRunViewerTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Monitoring/FindingExceptionsQueueHierarchyTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec193MonitoringSurfaceHierarchySmokeTest.php
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

Manual Acceptance Checklist

1. Open FindingExceptionsQueue with and without a selected exception and confirm the page visibly changes from quiet monitoring mode to focused workbench mode.
2. Open TenantlessOperationRunViewer from Operations and confirm scope, return, refresh, related links, and follow-up actions no longer read as one flat header strip.
3. Open Operations and confirm scope reset is visible but quieter than tabs, filters, and row drilldown.
4. Open Alerts, AuditLog, and ListAlertDeliveries and confirm they remain calm or only receive documented minor alignment.
5. Open EvidenceOverview, BaselineCompareLanding, BaselineCompareMatrix, and ReviewRegister and confirm they remain calm bounded-scope references.
6. Open TenantDiagnostics with and without an active defect state and confirm repair actions appear only when justified and remain confirmed.
7. Confirm browser smoke checks show no JavaScript errors on remediated, exception, and reference surfaces.

Deployment Notes

• No migration is expected.
• No new provider registration is expected; Laravel 11+ provider registration remains in bootstrap/providers.php.
• No new asset registration is expected. Existing deploy handling of cd apps/platform && php artisan filament:assets remains sufficient.