TenantAtlas/specs/304-tenant-panel-dead-code-retirement/plan.md

Implementation Plan: Tenant Panel Dead-Code Retirement

Branch: 304-tenant-panel-dead-code-retirement | Date: 2026-05-15 | Spec: spec.md Input: Feature specification from /specs/304-tenant-panel-dead-code-retirement/spec.md

Summary

Retire and guard the remaining Tenant Panel and legacy route assumptions after the workspace-first admin runtime repair sequence. Current repo inspection shows the Tenant Panel provider and /admin/t route family are already absent from the active boot path and route collection, so the implementation should focus on verifying absence, removing any confirmed stale active tests or link assumptions, and preserving canonical workspace/environment navigation and RBAC behavior.

Technical Context

Language/Version: PHP 8.4.15 Primary Dependencies: Laravel 12.52.0, Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1 Storage: PostgreSQL; no schema changes Testing: Pest feature/guard tests through Laravel Sail Validation Lanes: confidence, formatting/diff-check, optional browser smoke only if rendered navigation changes Target Platform: Laravel Sail locally; Dokploy container deployment for staging/production Project Type: Web application under apps/platform Performance Goals: No new query families, polling, route discovery cost, or runtime indirection. Constraints: No migrations, no assets, no provider behavior changes, no Graph adapter changes, no compatibility routes, no redirects, no new product surfaces. Scale/Scope: Existing provider bootstrap, route registration, link builders, and focused tests.

UI / Surface Guardrail Plan

• Guardrail scope: workflow-only route/navigation guardrail change.
• Native vs custom classification summary: native Filament provider/panel and navigation behavior; no custom UI.
• Shared-family relevance: navigation, global search destinations, and action/deep links.
• State layers in scope: route collection, shell route context, remembered environment context, resource URL generation.
• Audience modes in scope: operator-MSP and support-platform where existing admin access already applies.
• Decision/diagnostic/raw hierarchy plan: N/A. No new operator decision surface.
• Raw/support gating plan: unchanged.
• One-primary-action / duplicate-truth control: unchanged; this cleanup adds no actions.
• Handling modes by drift class or surface: review-mandatory for active test or link assumptions that still encode retired route behavior.
• Repository-signal treatment: route/provider/link residues are hard-stop candidates if they revive retired runtime behavior; historical docs are report-only.
• Special surface test profiles: global-context-shell and standard-native-filament.
• Required tests or manual smoke: provider/route guard tests, legacy URL 404 tests, navigation separation tests, Inventory and Entra Groups regression tests, global-search/link URL tests. Browser smoke is recommended only if implementation changes rendered navigation or route registration.
• Exception path and spread control: none. If a real active dependency cannot be removed safely, document it as a deferred blocker rather than adding compatibility behavior.
• Active feature PR close-out entry: Guardrail / Smoke Coverage or feature-test substitute.

Shared Pattern & System Fit

• Cross-cutting feature marker: yes.
• Systems touched:
  • apps/platform/bootstrap/providers.php
  • apps/platform/routes/web.php
  • apps/platform/app/Providers/Filament/AdminPanelProvider.php
  • apps/platform/app/Support/ManagedEnvironmentLinks.php
  • apps/platform/app/Support/OperationRunLinks.php
  • apps/platform/app/Support/OpsUx/OperationRunUrl.php
  • apps/platform/app/Filament/Concerns/WorkspaceScopedTenantRoutes.php
  • apps/platform/app/Filament/Concerns/ResolvesPanelTenantContext.php
  • apps/platform/app/Support/OperateHub/OperateHubShell.php
  • apps/platform/app/Support/Navigation/NavigationScope.php
  • focused tests under apps/platform/tests/Feature/Guards, apps/platform/tests/Feature/Filament, apps/platform/tests/Feature/Workspaces, apps/platform/tests/Feature/Monitoring, apps/platform/tests/Feature/Operations, apps/platform/tests/Feature/ProviderConnections, and apps/platform/tests/Feature/RequiredPermissions
• Shared abstractions reused: existing canonical route helpers, ManagedEnvironmentLinks, OperationRunLinks, WorkspaceScopedTenantRoutes, OperateHubShell, NavigationScope, and current Filament resource URL behavior.
• New abstraction introduced? why?: none.
• Why the existing abstraction was sufficient or insufficient: Existing helpers already produce canonical workspace/environment URLs. The cleanup needs guardrails and stale-test removal, not a new route layer.
• Bounded deviation / spread control: no deviations. Compatibility redirects and aliases are forbidden.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: link safety only.
• Central contract reused: OperationRunLinks and App\Support\OpsUx\OperationRunUrl.
• Delegated UX behaviors: existing operation URL resolution remains shared.
• Surface-owned behavior kept local: none.
• Queued DB-notification policy: N/A.
• Terminal notification path: N/A.
• Exception path: none.

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: yes, bounded to retired tenant-route runtime language.
• Provider-owned seams: Existing Microsoft/tenant vocabulary where current models, provider payloads, or historical docs still require it.
• Platform-core seams: provider bootstrap, panel IDs, route names, canonical workspace/environment URLs, RBAC and navigation tests.
• Neutral platform terms / contracts preserved: Workspace, Managed Environment, Environment, workspace-first admin runtime, canonical environment route.
• Retained provider-specific semantics and why: Existing Tenant vocabulary remains only where this cleanup does not own the broader model/schema terminology cutover.
• Bounded extraction or follow-up path: none unless implementation discovers real model/schema-level tenant-core blockers; those must become a follow-up, not hidden scope.

Technical Approach

1. Confirm current runtime truth:
   • provider bootstrap does not register Tenant Panel provider
   • no active Tenant Panel provider class exists in runtime app paths
   • route collection has no admin/t or legacy admin/tenants product routes
   • Filament does not resolve a tenant panel
2. Inspect active tests that still mention /admin/t, /admin/tenants, TenantPanelProvider, or old tenant-panel route names.
   • Keep tests that explicitly assert removal.
   • Update or remove tests that expect compatibility redirects, tenant-panel reachability, or blanket admin-hidden semantics.
3. Inspect active link builders and resource search destinations.
   • Verify ManagedEnvironmentLinks, OperationRunLinks, OperationRunUrl, global search, and focused resource URL helpers do not emit /admin/t.
   • Add or update high-signal assertions only where coverage is missing.
4. Preserve navigation contracts from Specs 301 and 303.
   • Workspace home stays clean.
   • Environment context shows eligible environment-bound surfaces.
   • Inventory and Entra Groups keep canonical workspace/environment routes.
5. Delete active dead runtime files only if a file exists and repo references prove it is unused.
6. Update product docs minimally only if implementation changes current repo truth or candidate sequencing.
7. Run focused tests and git diff --check; run browser smoke if rendered navigation or route registration changed.

Current Repo Findings From Preparation

• apps/platform/bootstrap/providers.php registers only app/auth/admin/system providers for Filament runtime.
• No active TenantPanelProvider.php file was found under apps/platform/app.
• Laravel route inspection returned no matching routes for admin/t and no matching routes for admin/tenants.
• Existing guard tests already cover provider absence and active route absence:
  • apps/platform/tests/Feature/Guards/NoLegacyTenantPanelRuntimeTest.php
  • apps/platform/tests/Feature/Guards/NoActiveTenantResourceRoutesTest.php
• Existing route/navigation tests already cover portions of the intended contract, including PanelNavigationSegregationTest, InventoryCoverageAdminTenantParityTest, EntraGroupAdminScopeTest, and EntraGroupGlobalSearchScopeTest.
• Active test files still contain historical or stale /admin/t mentions. Implementation must classify them instead of blanket-deleting them.

Existing Repository Surfaces Likely Affected

Runtime Surfaces To Inspect

apps/platform/bootstrap/providers.php
apps/platform/routes/web.php
apps/platform/app/Providers/Filament/AdminPanelProvider.php
apps/platform/app/Providers/Filament/TenantPanelProvider.php
apps/platform/app/Filament/Providers/TenantPanelProvider.php
apps/platform/app/Filament/Concerns/WorkspaceScopedTenantRoutes.php
apps/platform/app/Filament/Concerns/ResolvesPanelTenantContext.php
apps/platform/app/Support/Navigation/NavigationScope.php
apps/platform/app/Support/OperateHub/OperateHubShell.php
apps/platform/app/Support/ManagedEnvironmentLinks.php
apps/platform/app/Support/OperationRunLinks.php
apps/platform/app/Support/OpsUx/OperationRunUrl.php
apps/platform/app/Filament/Resources/InventoryItemResource.php
apps/platform/app/Filament/Resources/EntraGroupResource.php
apps/platform/app/Filament/Pages/InventoryCoverage.php
apps/platform/app/Filament/Pages/EnvironmentDashboard.php

Test Surfaces To Inspect Or Update

apps/platform/tests/Feature/Guards/NoLegacyTenantPanelRuntimeTest.php
apps/platform/tests/Feature/Guards/NoActiveTenantResourceRoutesTest.php
apps/platform/tests/Feature/Workspaces/WorkspaceIntendedUrlLegacyRejectionTest.php
apps/platform/tests/Feature/Filament/PanelNavigationSegregationTest.php
apps/platform/tests/Feature/Filament/AdminTenantSurfaceParityTest.php
apps/platform/tests/Feature/Filament/AdminSharedSurfacePanelParityTest.php
apps/platform/tests/Feature/Filament/TenantOwnedResourceScopeParityTest.php
apps/platform/tests/Feature/Filament/InventoryCoverageAdminTenantParityTest.php
apps/platform/tests/Feature/Filament/EntraGroupAdminScopeTest.php
apps/platform/tests/Feature/Filament/EntraGroupGlobalSearchScopeTest.php
apps/platform/tests/Feature/Filament/PolicyResourceAdminSearchParityTest.php
apps/platform/tests/Feature/Filament/PolicyVersionAdminSearchParityTest.php
apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php
apps/platform/tests/Feature/Operations/LegacyRunRoutesNotFoundTest.php
apps/platform/tests/Feature/ProviderConnections/LegacyRedirectTest.php
apps/platform/tests/Feature/RequiredPermissions/RequiredPermissionsLegacyRouteTest.php

Domain / Model Implications

• No model rename.
• No new model.
• No table migration.
• No tenant_id cleanup.
• No managed_environment_id retargeting.
• Existing model names and relationship names may still use Tenant where this spec does not own the broader core cutover.

UI / Filament Implications

• Filament v5 targets Livewire v4.0+; this repo currently uses Livewire 4.1.4.
• Provider registration remains in apps/platform/bootstrap/providers.php for Laravel 12; do not move panel provider registration to bootstrap/app.php.
• AdminPanelProvider and SystemPanelProvider remain the active panel providers.
• The retired Tenant Panel ID must not reappear.
• Globally searchable resources touched by this cleanup must keep valid View/Edit pages or disable global search. Entra Groups, Policy, and Policy Versions already have focused global-search tests and View pages in the current route family.
• No destructive actions are added. Existing destructive actions, if encountered incidentally, must still execute through ->action(...), ->requiresConfirmation(), and server-side authorization.
• No assets are added or changed; deploy-time cd apps/platform && php artisan filament:assets posture is unchanged.

RBAC / Policy Implications

• UI visibility remains non-authoritative.
• Workspace membership remains the primary admin runtime isolation boundary.
• Managed Environment access remains required for environment-owned data.
• Cross-workspace and cross-environment direct URL manipulation remains deny-as-not-found.
• Members without capability keep existing 403/denial semantics after membership is established.
• Global search must not bypass environment scoping or resource policies.

Data / Migration Implications

• No migrations.
• No data backfill.
• No seed changes unless a stale test fixture explicitly encodes a retired route and is updated in a test-only path.
• No PostgreSQL, JSONB, or index changes.

Documentation Implications

• Historical docs and old specs are allowed to mention Tenant Panel and /admin/t.
• Update current product docs only if implementation changes current repo truth or candidate sequencing.
• Likely optional docs:
  • docs/product/spec-candidates.md
  • docs/product/implementation-ledger.md
• Do not duplicate the full spec into product docs.

Testing Strategy

• Strengthen existing provider and route guard tests.
• Add missing route-name or route-collection checks for retired tenant-panel semantics.
• Update stale feature tests that still expect compatibility redirects or tenant-panel reachability.
• Preserve existing workspace-home and environment-context navigation proofs.
• Preserve Inventory and Entra Groups focused tests from Specs 301 and 303.
• Add high-signal link/search no-/admin/t assertions only where missing.
• Prefer feature tests over browser smoke unless rendered navigation behavior changed.

Constitution Check

GATE: Must pass before implementation. Re-check after implementation.

• Inventory-first: no inventory truth or snapshot semantics change.
• Read/write separation: no new write/change function.
• Single Graph contract path: no Graph calls or contract changes.
• Deterministic capabilities: no capability resolver changes.
• RBAC-UX: UI visibility is not authorization; server-side checks remain authoritative.
• Workspace isolation: non-member workspace access remains 404.
• Tenant/environment isolation: environment-owned data remains scoped to entitled environment context.
• OperationRun: no start/completion semantics change; only URL safety is checked.
• Proportionality: no new structure, layer, persisted truth, or semantic machinery.
• No premature abstraction: no new route framework, provider framework, or compatibility bridge.
• Persisted truth: no new persistence.
• State: no new status or reason family.
• Shared pattern first: reuse existing route/link helpers and guard tests.
• Provider boundary: no provider-specific behavior moves into platform core.
• Test governance: focused guard/feature tests, no hidden heavy-family expansion.
• Filament native first: native Filament provider/routing/navigation behavior; no custom UI.

Test Governance Check

• Test purpose / classification by changed surface: Feature/guardrail.
• Affected validation lanes: confidence and diff-check.
• Why this lane mix is the narrowest sufficient proof: The change is provider bootstrap, route collection, URL generation, navigation contract, and test cleanup. Focused feature/guard tests prove these without broad browser or heavy-governance lanes.
• Narrowest proving command(s):
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/NoLegacyTenantPanelRuntimeTest.php tests/Feature/Guards/NoActiveTenantResourceRoutesTest.php tests/Feature/Workspaces/WorkspaceIntendedUrlLegacyRejectionTest.php
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/PanelNavigationSegregationTest.php tests/Feature/Filament/AdminTenantSurfaceParityTest.php tests/Feature/Filament/AdminSharedSurfacePanelParityTest.php tests/Feature/Filament/TenantOwnedResourceScopeParityTest.php tests/Feature/Filament/InventoryCoverageAdminTenantParityTest.php tests/Feature/Filament/EntraGroupAdminScopeTest.php tests/Feature/Filament/EntraGroupGlobalSearchScopeTest.php tests/Feature/Filament/PolicyResourceAdminSearchParityTest.php tests/Feature/Filament/PolicyVersionAdminSearchParityTest.php
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php tests/Feature/Operations/LegacyRunRoutesNotFoundTest.php tests/Feature/ProviderConnections/LegacyRedirectTest.php tests/Feature/RequiredPermissions/RequiredPermissionsLegacyRouteTest.php
  • git diff --check
• Fixture / helper / factory / seed / context cost risks: low; reuse existing factories and helpers.
• Expensive defaults or shared helper growth introduced?: no.
• Heavy-family additions, promotions, or visibility changes: none expected.
• Surface-class relief / special coverage rule: standard-native-filament and global-context-shell feature coverage.
• Closing validation and reviewer handoff: verify no provider/route/link compatibility residue, no stale blanket hidden tests, and no RBAC/context coverage weakened.
• Budget / baseline / trend follow-up: none expected.
• Review-stop questions: Did any compatibility redirect get added? Did any route collection include admin/t? Did any global-search or operation URL contain /admin/t? Did workspace home stay clean? Did environment surfaces stay visible?
• Escalation path: follow-up-spec only if structural navigation-test coupling remains.
• Active feature PR close-out entry: Guardrail and optional Smoke Coverage.
• Why no dedicated follow-up spec is needed now: This spec is the dedicated cleanup slice. Follow-ups are conditional only if implementation uncovers new blockers.

Project Structure

Documentation (this feature)

specs/304-tenant-panel-dead-code-retirement/
+-- checklists/
|   +-- requirements.md
+-- plan.md
+-- spec.md
+-- tasks.md

Source Code (likely implementation surfaces)

apps/platform/bootstrap/
apps/platform/routes/
apps/platform/app/Providers/Filament/
apps/platform/app/Filament/
apps/platform/app/Support/
apps/platform/tests/Feature/Guards/
apps/platform/tests/Feature/Filament/
apps/platform/tests/Feature/Workspaces/
apps/platform/tests/Feature/Monitoring/
apps/platform/tests/Feature/Operations/
apps/platform/tests/Feature/ProviderConnections/
apps/platform/tests/Feature/RequiredPermissions/

Structure Decision: Use the existing Laravel/Filament app structure and existing Pest test directories. Do not create new base folders.

Complexity Tracking

No constitution violation and no BLOAT-001 trigger. The spec removes or guards legacy behavior and introduces no new persistence, abstraction, state family, taxonomy, or UI framework.

Implementation Phases

1. Confirm active provider and route truth.
2. Classify active tests and link builders that mention retired route families.
3. Update guardrails for provider, route collection, route names, and not-found behavior.
4. Replace stale test contracts with workspace-home clean and environment-context visible assertions.
5. Add or update link/search no-legacy assertions.
6. Delete active dead runtime files only if found and proven unused.
7. Run focused validation and document browser smoke decision.

Rollout Considerations

• No deployment migration.
• No environment variables.
• No queue or cron worker changes.
• No storage/volume changes.
• No reverse proxy/Dokploy changes.
• Staging validation should run the focused Pest suite before production promotion.