ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
8475d85bc8
TenantAtlas/specs/193-monitoring-action-hierarchy/plan.md

303 lines
23 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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.
Reference in New Issue View Git Blame Copy Permalink