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)

```text
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)

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