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
94 lines
6.3 KiB
Markdown
94 lines
6.3 KiB
Markdown
# 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. |