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

Implementation Plan: Monitoring Surface Action Hierarchy and Workbench Semantics

Branch: 193-monitoring-action-hierarchy | Date: 2026-04-11 | Spec: /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/193-monitoring-action-hierarchy/spec.md Input: Feature specification from /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/193-monitoring-action-hierarchy/spec.md

Note: This plan keeps the work inside the existing Filament v5 / Livewire v4 page layer, existing OperateHubShell and CanonicalNavigationContext scope helpers, and the current action-surface guard infrastructure. It explicitly avoids adding a new monitoring-action framework.

Summary

Codify one bounded action-layer contract for monitoring, queue, operations, and workbench surfaces in the admin panel. Reuse existing Filament header actions, ActionGroup, UiEnforcement, OperateHubShell, CanonicalAdminTenantFilterState, and the existing ActionSurfaceValidator extension path to inventory all in-scope surfaces, remediate the three clearly problematic workbench pages, convert the alerts overview into an explicitly declared in-scope monitoring surface, preserve calm bounded-scope pages as references, document TenantDiagnostics as the only special-type exception, and extend guard plus browser regression layers so mixed monitoring headers do not return.

Technical Context

Language/Version: PHP 8.4.15
Primary Dependencies: Laravel 12, Filament v5, Livewire v4, Pest v4, Tailwind CSS v4, existing OperateHubShell, CanonicalNavigationContext, CanonicalAdminTenantFilterState, UiEnforcement, ActionSurfaceValidator, and Filament page or resource action builders
Storage: PostgreSQL through existing workspace-owned and tenant-owned models; no schema change planned
Testing: Pest feature tests, existing guard tests, and Pest browser smoke tests run through Laravel Sail
Target Platform: Laravel monolith web application under apps/platform, with canonical workspace-context monitoring routes under /admin, tenant-context routes under /admin/t/{tenant}/..., and cluster-backed monitoring routes under /admin/alerts
Project Type: web application
Performance Goals: Preserve the 5-second scan rule for monitoring surfaces, keep monitoring renders DB-only with no outbound HTTP or queued jobs at render time, avoid adding new polling beyond existing run-detail behavior, and avoid query churn when separating action layers
Constraints: No new action framework, no new persistence, no route or panel changes, no authorization-plane changes, no new badge taxonomy, no silent surface exemptions, no record-page header rules copied directly onto workbench pages, and no expansion of confirmation depth, reason capture, or run semantics beyond existing actions
Scale/Scope: 11 in-scope surfaces, 3 remediation-required core pages, 3 minor-alignment audits, 4 compliant or no-op bounded-scope references, 1 special-type exception, existing Blade views for monitoring pages, and focused guard plus feature plus browser regression coverage

Constitution Check

GATE: Passed before Phase 0 research. Re-checked after Phase 1 design and still passing.

Principle	Pre-Research	Post-Design	Notes
Inventory-first / snapshots-second	PASS	PASS	The feature does not alter inventory, snapshots, or backup truth. It only reorganizes monitoring surfaces.
Read/write separation	PASS	PASS	Existing write actions such as approve, reject, and tenant repair keep their current confirmation, audit, and test behavior. No new writes are introduced.
Graph contract path	N/A	N/A	No new Microsoft Graph call path or contract-registry change is planned.
Deterministic capabilities	PASS	PASS	Capability checks remain in the canonical registries plus UiEnforcement; regrouping actions does not change entitlement logic.
Workspace + tenant isolation	PASS	PASS	Existing route scopes, OperateHubShell resolution, and tenant-safe drilldown rules remain authoritative.
RBAC-UX authorization semantics	PASS	PASS	Non-members remain 404, member-without-capability remains 403, and server-side checks remain unchanged.
Run observability / Ops-UX	PASS	PASS	Existing OperationRun-backed actions keep their current queued-toast, monitoring-detail, and terminal-status semantics.
Data minimization	PASS	PASS	No new persistence, caches, or cross-surface helper artifacts are introduced.
Proportionality / anti-bloat	PASS	PASS	The work extends the existing inventory and validation layers rather than introducing a new monitoring-action engine.
UI semantics / few layers	PASS	PASS	The feature uses direct action placement and explicit classification, not a new presenter or interpretation layer.
Filament-native UI	PASS	PASS	Native Filament actions, action groups, pages, tables, and shared context bars remain the implementation path.
Surface taxonomy / monitoring-specific hierarchy	PASS	PASS	The plan explicitly distinguishes monitoring/workbench surfaces from Spec 192 record pages and documents the allowed exception.
Filament v5 / Livewire v4 compliance	PASS	PASS	All touched surfaces stay inside the existing Filament v5 + Livewire v4 stack.
Provider registration location	PASS	PASS	No provider change is needed; Laravel 11+ provider registration remains in bootstrap/providers.php.
Global search hard rule	PASS	PASS	No new globally searchable resource is introduced and no resource search settings are changed. Existing searchable resources already have View/Edit pages where needed.
Destructive action safety	PASS	PASS	Existing confirmed actions such as exception approval or rejection and tenant repair actions keep ->requiresConfirmation() plus current authorization.
Asset strategy	PASS	PASS	No new global or on-demand asset registration is needed. Existing deployment handling of cd apps/platform && php artisan filament:assets remains unchanged.

Filament-Specific Compliance Notes

• Livewire v4.0+ compliance: The plan remains on Filament v5 + Livewire v4 and introduces no legacy or mixed-version API usage.
• Provider registration location: No panel or provider changes are required; Laravel 11+ panel providers remain registered in bootstrap/providers.php.
• Global search: The feature does not add a new globally searchable resource and does not alter global-search visibility for existing resources. Touched monitoring pages remain page-level surfaces or reuse existing resource detail pages.
• Destructive actions: Approve exception, Reject exception, Bootstrap owner, and Merge duplicate memberships remain routed through Action::make(...)->action(...) with ->requiresConfirmation() plus existing authorization and audit semantics.
• Asset strategy: No new global or lazy-loaded assets are planned. Existing deployment handling of cd apps/platform && php artisan filament:assets remains sufficient.
• Testing plan: Extend the existing action-surface guard layer, add focused Pest tests for the remediated and exception surfaces, and add a browser smoke suite that proves visible monitoring hierarchy on the remediated pages and no-regression behavior on reference pages.

Phase 0 Research

Research outcomes are captured in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/193-monitoring-action-hierarchy/research.md.

Key decisions:

• Reuse the existing ActionSurfaceExemptions plus ActionSurfaceValidator inventory pattern from Spec 192 instead of creating a new monitoring-action framework.
• Keep OperateHubShell and CanonicalNavigationContext as the single scope and return-context sources for canonical /admin monitoring pages.
• Express hierarchy through native Filament actions, ActionGroup, existing context bars, and targeted Blade adjustments rather than custom header components.
• Retire the blanket baseline exemption for Alerts and bring it into explicit Spec 193 declaration plus inventory coverage.
• Build regression protection on top of the existing guard tests, OperateHubShellTest, focused page tests, and one dedicated browser smoke suite.

Phase 1 Design

Design artifacts are created under /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/193-monitoring-action-hierarchy/:

• research.md: decisions and rejected alternatives for monitoring/workbench hierarchy
• data-model.md: derived surface inventory, action-layer, and regression expectation models
• contracts/monitoring-action-hierarchy.logical.openapi.yaml: internal logical contract for monitoring-surface action layers and exception handling
• quickstart.md: implementation and verification sequence for the feature

Design highlights:

• Keep all classification and action-layer rules derived, not persisted.
• Represent each in-scope surface through one explicit inventory entry and one explicit regression expectation.
• Extend the existing action-surface validation layer with a second bounded inventory for monitoring/workbench surfaces.
• Keep selection-state logic local to the affected pages instead of moving it into a shared runtime resolver.
• Treat TenantDiagnostics as the only explicit special-type exception and require an exception reason in the guard layer.

Phase 1 — Agent Context Update

Planned command:

• .specify/scripts/bash/update-agent-context.sh copilot

This feature does not introduce a new technology stack, but the required agent-context refresh still runs after the technical context and design artifacts are complete.

Project Structure

Documentation (this feature)

specs/193-monitoring-action-hierarchy/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── spec.md
├── contracts/
│   └── monitoring-action-hierarchy.logical.openapi.yaml
└── checklists/
    └── requirements.md

Source Code (repository root)

apps/platform/
├── app/
│   ├── Filament/
│   │   ├── Pages/
│   │   │   ├── Monitoring/
│   │   │   │   ├── FindingExceptionsQueue.php                     # MODIFY
│   │   │   │   ├── Operations.php                                 # MODIFY
│   │   │   │   ├── Alerts.php                                     # MODIFY (add declaration + minor alignment)
│   │   │   │   ├── AuditLog.php                                   # AUDIT / possible minor alignment
│   │   │   │   └── EvidenceOverview.php                           # REFERENCE only
│   │   │   ├── Operations/
│   │   │   │   └── TenantlessOperationRunViewer.php               # MODIFY
│   │   │   ├── Reviews/
│   │   │   │   └── ReviewRegister.php                             # REFERENCE only
│   │   │   ├── BaselineCompareLanding.php                         # REFERENCE only
│   │   │   ├── BaselineCompareMatrix.php                          # REFERENCE only
│   │   │   └── TenantDiagnostics.php                              # AUDIT / special-type exception
│   │   └── Resources/
│   │       ├── AlertDeliveryResource.php                          # REUSE / possible declaration notes
│   │       └── AlertDeliveryResource/
│   │           └── Pages/
│   │               └── ListAlertDeliveries.php                    # AUDIT / possible minor alignment
│   ├── Support/
│   │   ├── OperateHub/
│   │   │   └── OperateHubShell.php                                # REUSE
│   │   ├── Navigation/
│   │   │   └── CanonicalNavigationContext.php                     # REUSE
│   │   ├── Filament/
│   │   │   └── CanonicalAdminTenantFilterState.php                # REUSE
│   │   ├── Rbac/
│   │   │   └── UiEnforcement.php                                  # REUSE
│   │   └── Ui/
│   │       └── ActionSurface/
│   │           ├── ActionSurfaceExemptions.php                    # MODIFY
│   │           ├── ActionSurfaceValidator.php                     # MODIFY
│   │           └── ActionSurfaceProfileDefinition.php             # POSSIBLE MODIFY
├── resources/
│   └── views/
│       └── filament/
│           ├── partials/
│           │   └── context-bar.blade.php                          # REUSE / possible minor alignment
│           └── pages/
│               ├── monitoring/
│               │   ├── finding-exceptions-queue.blade.php         # MODIFY
│               │   ├── operations.blade.php                       # POSSIBLE MODIFY
│               │   ├── alerts.blade.php                           # POSSIBLE MODIFY
│               │   └── audit-log.blade.php                        # POSSIBLE MODIFY
│               ├── operations/
│               │   └── tenantless-operation-run-viewer.blade.php  # MODIFY
│               ├── reviews/
│               │   └── review-register.blade.php                  # REFERENCE only
│               ├── baseline-compare-landing.blade.php             # REFERENCE only
│               ├── baseline-compare-matrix.blade.php              # REFERENCE only
│               └── tenant-diagnostics.blade.php                   # REFERENCE / special-type audit
└── tests/
    ├── Feature/
    │   ├── Guards/
    │   │   ├── ActionSurfaceContractTest.php                      # MODIFY
    │   │   ├── ActionSurfaceValidatorTest.php                     # MODIFY
    │   │   └── Spec193MonitoringSurfaceHierarchyGuardTest.php     # NEW
    │   ├── Monitoring/
    │   │   ├── AuditLogInspectFlowTest.php                        # REUSE / possible extend
    │   │   ├── OperationsCanonicalUrlsTest.php                    # MODIFY or REUSE
    │   │   ├── OperationsDashboardDrillthroughTest.php            # MODIFY or REUSE
    │   │   ├── OperationsRelatedNavigationTest.php                # MODIFY or REUSE
    │   │   ├── FindingExceptionsQueueHierarchyTest.php            # NEW
    │   │   └── OperationsHeaderHierarchyTest.php                  # NEW
    │   ├── Operations/
    │   │   └── TenantlessOperationRunViewerTest.php               # MODIFY
    │   ├── OpsUx/
    │   │   └── OperateHubShellTest.php                            # MODIFY
    │   └── Rbac/
    │       ├── ActionSurfaceRbacSemanticsTest.php                 # REUSE / possible extend
    │       └── TenantActionSurfaceConsistencyTest.php             # REUSE / possible extend
    └── Browser/
        ├── Spec192RecordPageHeaderDisciplineSmokeTest.php         # REUSE for patterns
        └── Spec193MonitoringSurfaceHierarchySmokeTest.php         # NEW

Structure Decision: Keep the work entirely inside the existing Laravel/Filament monolith under apps/platform. Modify only the affected page classes, a small set of monitoring Blade views, the existing action-surface validation layer, and focused tests. Do not create a new runtime resolver or header-framework layer.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
Cross-page monitoring/workbench taxonomy and explicit exception catalog (BLOAT-001 trigger)	The feature must distinguish remediation-required workbench pages, shared-pattern audit pages, calm bounded-scope references, and the single acceptable diagnostic exception in a way CI can validate.	Pure local cleanup would reduce visible clutter but would not prevent future drift or explain why some monitoring surfaces are preserved while others are remediated.

Proportionality Review

• Current operator problem: Monitoring and workbench pages still mix scope, navigation, utility, and active work actions in one header lane, slowing queue review and making next-step semantics ambiguous.
• Existing structure is insufficient because: The constitution and Spec 192 now govern other action-surface classes, but the repo lacks a bounded implementation inventory and regression hook for this monitoring/workbench surface class.
• Narrowest correct implementation: Extend the existing action-surface inventory and validation layer with one additional monitoring/workbench inventory, remediate only the three clearly problematic pages, explicitly classify the others, and add focused feature plus browser regression coverage.
• Ownership cost created: A small extension to the validator and exemption inventory, one new guard test, several focused page tests, one browser smoke suite, and ongoing review discipline for future monitoring surfaces.
• Alternative intentionally rejected: A new monitoring action-placement engine or registry was rejected because the current repo already has sufficient primitives through Filament actions, OperateHubShell, and the existing action-surface validator.
• Release truth: current-release operator clarity and action-surface discipline

Implementation Strategy

Phase A — Codify the monitoring inventory and guard contract

Goal: turn the spec inventory into an enforceable project-level contract without introducing a new framework.

Changes:

• Extend ActionSurfaceExemptions with a spec193MonitoringSurfaceInventory() and per-surface lookup helper.
• Extend ActionSurfaceValidator with explicit validation of the Spec 193 inventory and its allowed classifications.
• Add Spec193MonitoringSurfaceHierarchyGuardTest.php to assert completeness, explicit exception reasoning, and bounded reference preservation.
• Remove the blanket baseline exemption for Alerts and replace it with explicit monitoring-surface coverage.

Tests:

• Extend ActionSurfaceContractTest.php and ActionSurfaceValidatorTest.php with Spec 193 expectations.
• Add Spec193MonitoringSurfaceHierarchyGuardTest.php.

Phase B — Remediate the highest-noise workbench surfaces

Goal: implement the core hierarchy wins first on the pages with the clearest mixed-header problem.

Changes:

• Refactor FindingExceptionsQueue so scope, return, filters, drilldowns, and selected-exception decisions no longer render as flat peers.
• Refactor TenantlessOperationRunViewer so scope, return, show-all, refresh, related links, and resumable actions render as distinct layers.
• Refactor Operations so scope and show-all context stay visible but no longer read as the page’s primary work surface.

Tests:

• Add focused page tests for no-selection vs selected-workbench behavior on FindingExceptionsQueue.
• Extend TenantlessOperationRunViewerTest.php and relevant Monitoring tests with hierarchy and navigation assertions.

Phase C — Tighten shared patterns and classify bounded-scope references

Goal: bring shared monitoring patterns under the same contract without rebuilding calm pages.

Changes:

• Add an explicit declaration to Alerts and audit its origin-context placement.
• Review AuditLog and ListAlertDeliveries for minor alignment only, changing them only where real action-layer ambiguity exists.
• Confirm EvidenceOverview, BaselineCompareLanding, BaselineCompareMatrix, and ReviewRegister remain compliant or no-op references.
• Keep TenantDiagnostics as the single special-type acceptable exception and codify why it is allowed.

Tests:

• Extend OperateHubShellTest.php for scope-label and return-affordance expectations that remain relevant after the monitoring refactor.
• Add focused assertions for the Alerts overview in AlertsHierarchyTest.php, keep alert-delivery minor-alignment coverage in the existing alert-delivery suites, and verify that minor-alignment pages remain calm or declaration-complete.

Phase D — Browser verification and final regression protection

Goal: prove the new hierarchy in a real browser and prevent future mixed monitoring headers from re-entering the repo.

Changes:

• Add Spec193MonitoringSurfaceHierarchySmokeTest.php covering the three remediated pages, the TenantDiagnostics exception surface, and a no-regression subset of calm reference pages.
• Ensure the guard layer fails on scope-as-CTA regressions, mixed selection and global header lanes, and undocumented exceptions.
• Re-run formatting and the focused Sail test pack.

Tests:

• Browser smoke coverage for visible hierarchy and no JavaScript errors.
• Focused guard and feature tests for each remediated or exception surface.

Risk Assessment

Risk	Impact	Likelihood	Mitigation
Cleanup grows into a new monitoring-action framework	Medium	Low	Keep all work inside existing pages, views, and validator layers.
Shared-pattern loyalty masks real hierarchy issues	High	Medium	Treat OperateHubShell pages as review targets, not automatic exemptions.
Selection-aware workbench pages become too quiet when no selection exists	Medium	Medium	Add explicit no-selection vs selected-state tests on the queue and viewer surfaces.
Alerts stays outside regression coverage because of the old cluster exemption	Medium	Medium	Convert it to explicit declaration plus inventory coverage in Phase A.
Calm bounded-scope pages get unnecessary churn	Medium	Low	Maintain an explicit compliant/no-op reference set and cover it in browser smoke.

Test Strategy

• Extend ActionSurfaceContractTest.php and ActionSurfaceValidatorTest.php so Spec 193 becomes an explicit CI-enforced rule instead of a manual review note.
• Add Spec193MonitoringSurfaceHierarchyGuardTest.php to validate remediation-required pages, minor-alignment pages, calm references, and the explicit diagnostic exception.
• Add focused feature tests for FindingExceptionsQueue, Operations, and TenantlessOperationRunViewer covering state-driven hierarchy, scope behavior, and preserved authorization semantics.
• Reuse and extend OperateHubShellTest.php to keep DB-only rendering, tenant-context resolution, and scope-label behavior correct on canonical monitoring pages.
• Add Spec193MonitoringSurfaceHierarchySmokeTest.php using the existing browser-smoke patterns already present in Spec 192 and other surface smoke tests.
• Add explicit regression assertions that this feature does not expand confirmation depth, reason capture, provider-dispatch semantics, or record-page header rules.
• Run the focused Sail verification commands from quickstart.md, then run cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent.

Constitution Check (Post-Design)

Re-check result: PASS.

• Livewire v4.0+ compliance remains intact because all touched surfaces stay inside the existing Filament v5 + Livewire v4 stack.
• Provider registration remains unchanged in bootstrap/providers.php.
• The plan changes no global-search semantics; affected surfaces are pages or existing resource-backed pages whose search behavior already satisfies the Filament hard rule.
• Destructive and governance-changing actions keep ->requiresConfirmation() plus existing authorization.
• No new assets are introduced; existing filament:assets deployment behavior remains sufficient.