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

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