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

Research: Monitoring Surface Action Hierarchy and Workbench Semantics

Decision: Reuse the existing ActionSurfaceExemptions plus ActionSurfaceValidator inventory pattern instead of introducing a monitoring-specific action-placement framework

Rationale

Spec 192 already proved that the repo can encode a bounded surface-class contract through ActionSurfaceExemptions, ActionSurfaceValidator, and a dedicated guard test. Spec 193 needs the same kind of explicit inventory and CI protection for monitoring and workbench pages, not a second runtime engine for action placement.

Alternatives considered

• Add a MonitoringActionHierarchyResolver or WorkbenchActionRegistry: rejected because the placement rules remain page- and state-sensitive, and the repo already has enough validation infrastructure.
• Keep the rules only in the spec with manual review: rejected because mixed monitoring headers are exactly the sort of drift CI should catch.

Decision: Keep OperateHubShell and CanonicalNavigationContext as the canonical scope and return-context sources for /admin monitoring pages

Rationale

The affected canonical workspace routes already rely on OperateHubShell for entitled tenant context and on CanonicalNavigationContext for back-link semantics. The narrowest correct move is to preserve those sources and only change how their outputs are layered, rather than letting each page improvise its own scope or return logic.

Alternatives considered

• Resolve tenant and return context ad hoc in each page: rejected because it would duplicate authorization-sensitive context logic and risk canonical-route drift.
• Remove remembered-tenant context from canonical monitoring pages: rejected because the current product truth intentionally supports tenant-prefiltered monitoring views.

Decision: Express the hierarchy with native Filament actions, ActionGroup, context bars, and targeted Blade adjustments

Rationale

The codebase already uses native Filament header actions, grouped actions, page views, and context-bar partials. The problem is semantic weight and layering, not a missing UI toolkit. Using those existing primitives keeps the feature local and avoids importing a new presentation framework.

Alternatives considered

• Add custom header components or a page-level action-slot DSL: rejected because the existing Filament action primitives already cover the needed hierarchy.
• Solve the issue only by button restyling: rejected because the problem is semantic competition, not color alone.

Decision: Bring Alerts under explicit Spec 193 coverage instead of leaving it as a blanket baseline exemption

Rationale

Alerts is in scope for minor alignment and currently carries a baseline exemption because the active route resolves through the cluster entry. That exemption is too coarse for Spec 193, which needs an explicit verdict for every in-scope surface. The clean approach is to add an explicit declaration and inventory entry while keeping the page minor-alignment only unless a real hierarchy issue is found.

Alternatives considered

• Keep the existing exemption and rely on browser smoke only: rejected because the spec requires explicit classification and regression protection for all in-scope surfaces.
• Fully remediate Alerts as if it were a noisy workbench: rejected because the current surface is probably already calm enough for minor alignment only.

Decision: Model selection-heavy workbench behavior locally on the affected pages instead of in a shared state resolver

Rationale

FindingExceptionsQueue and TenantlessOperationRunViewer already have page-local state and action visibility rules. The narrowest correct implementation is to keep that local state and only classify actions into explicit layers. That preserves current authorization, notifications, and run semantics while avoiding a premature shared workbench state machine.

Alternatives considered

• Add a shared WorkbenchState resolver or enum family: rejected because the feature does not yet have enough truly shared runtime behavior to justify it.
• Collapse all non-global actions into a single More menu: rejected because the spec requires visible state transitions between calm monitoring mode and active work mode.

Decision: Preserve bounded-scope monitoring pages as explicit references

Rationale

EvidenceOverview, BaselineCompareLanding, BaselineCompareMatrix, and ReviewRegister already read as bounded-scope monitoring pages with one primary question and limited header complexity. The spec should name them as calm references and use them as a regression baseline, rather than rebuilding them to mimic the remediated workbench pages.

Alternatives considered

• Normalize every in-scope page to the same visible action-layer structure: rejected because it would create churn without additional operator value.
• Ignore calm pages and only document the noisy ones: rejected because the spec explicitly requires full-scope classification.

Decision: Keep TenantDiagnostics as the only special-type acceptable exception

Rationale

TenantDiagnostics is not a generic monitoring list; it is a focused diagnostic repair surface whose actions are meaningful only when a broken membership state exists. It should remain allowed as a special type, with explicit documentation and regression expectations, rather than being forced into the same pattern as a queue or a read-only registry report.

Alternatives considered

• Force diagnostics into a quiet read-only monitoring pattern: rejected because it would obscure legitimate repair actions.
• Let diagnostics stay different without explicit cataloging: rejected because silent exceptions produce review drift.

Decision: Build regression protection with one extra inventory, focused feature tests, and one browser smoke suite

Rationale

The repo already has the right three test layers for this kind of change: inventory and validator guards, focused feature tests around page state and authorization, and browser smoke for visible hierarchy. Extending those layers gives the feature durable protection without overbuilding.

Alternatives considered

• Browser-test every state permutation of every monitoring page: rejected because it is expensive and redundant with feature tests.
• Add only static guard coverage: rejected because no-selection vs active-selection behavior still needs runtime assertions.

Decision: No new assets, provider changes, or route changes are needed

Rationale

The work stays within existing Filament pages and resource pages. No panel/provider registration, asset registration, or route family change is required. Existing deployment handling of cd apps/platform && php artisan filament:assets remains unchanged.

Alternatives considered

• Introduce a custom asset or component library for layered monitoring headers: rejected because native Filament surfaces already provide the necessary primitives.