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

Feature Specification: Tenant Panel Dead-Code Retirement

Feature Branch: 304-tenant-panel-dead-code-retirement Created: 2026-05-15 Status: Draft Input: User description: "Retire remaining active Tenant Panel and legacy /admin/t runtime artifacts after Specs 301-303 repaired the workspace-first admin runtime and environment-bound surfaces."

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: The product contract is now workspace-first, but retired Tenant Panel and legacy /admin/t assumptions can still survive in provider registration, route definitions, tests, helper URLs, or compatibility-style assertions.
• Today's failure: Repo truth already shows no active Tenant Panel provider registration and no active /admin/t or /admin/tenants route collection entries, but active tests and historical seams still mention old route families. Without a bounded cleanup, future work can accidentally protect stale panel behavior or add compatibility routes instead of using canonical workspace/environment routes.
• User-visible improvement: Operators stay in one coherent workspace-first admin runtime. Environment-owned surfaces remain discoverable only in active environment context, and old Tenant Panel URLs fail clearly instead of redirecting or leaking state.
• Smallest enterprise-capable version: Verify and retire active Tenant Panel runtime residue, tighten route/provider/link guardrails, update stale tests to distinguish workspace-home cleanliness from environment-bound visibility, and preserve Inventory and Entra Groups contracts from Specs 301 and 303.
• Explicit non-goals: No new routing architecture, no ManagedEnvironment schema cutover, no tenant_id migration, no compatibility aliases, no redirects from retired routes, no new product surfaces, no Graph/provider adapter changes, no migrations, no assets, no broad terminology purge, and no customer portal changes.
• Permanent complexity imported: No new models, tables, enums, statuses, provider abstractions, UI frameworks, or runtime surfaces. The only permanent cost is focused guardrail coverage and clearer route/navigation tests.
• Why now: docs/product/spec-candidates.md sequences tenant-panel-dead-code-retirement after Specs 301, 302, and 303. Those specs closed the Inventory, route-audit, and Entra Groups prerequisites needed before deleting or guarding old Tenant Panel assumptions.
• Why not local: A one-off deletion risks either missing hidden link emitters or weakening workspace/environment access coverage. The cleanup must be repo-based and test-backed so it removes only dead runtime behavior while preserving canonical environment surfaces.
• Approval class: Cleanup
• Red flags triggered: None. This spec removes or guards legacy runtime behavior and does not introduce a new truth model, abstraction, taxonomy, or product surface.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 1 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: canonical-view
• Primary Routes:
  • Retired negative-control routes: /admin/t/{environment}, /admin/t/{environment}/..., /admin/tenants, and /admin/tenants/{environment} legacy entry shapes.
  • Canonical workspace route: /admin/workspaces/{workspace}/overview.
  • Canonical environment route: /admin/workspaces/{workspace}/environments/{environment}.
  • Canonical environment-owned resource routes under /admin/workspaces/{workspace}/environments/{environment}/....
• Data Ownership: No data ownership changes. Existing workspace-owned and managed-environment-owned tables remain unchanged. This spec does not introduce or migrate persistence.
• RBAC: Workspace membership and Managed Environment access remain server-side requirements. Navigation visibility is not authorization. Non-entitled workspace/environment access remains deny-as-not-found.

For canonical-view specs, the spec MUST define:

• Default filter behavior when tenant-context is active: Environment-bound resources continue to resolve through the active canonical workspace/environment context or explicit environment route parameters. Workspace-home surfaces remain tenantless by URL and must not show environment-owned navigation.
• Explicit entitlement checks preventing cross-tenant leakage: Direct legacy URLs, manipulated canonical environment URLs, stale remembered context, cross-workspace records, and cross-environment records must continue to deny as not found or safely return no results according to existing resource contracts.

Current Repo Truth To Preserve

• apps/platform/bootstrap/providers.php currently registers AppServiceProvider, AuthServiceProvider, AdminPanelProvider, and SystemPanelProvider; it does not register a Tenant Panel provider.
• Repo inspection found no active TenantPanelProvider.php under apps/platform/app.
• Laravel route inspection found no routes matching admin/t and no routes matching admin/tenants.
• Existing guard tests already include apps/platform/tests/Feature/Guards/NoLegacyTenantPanelRuntimeTest.php and apps/platform/tests/Feature/Guards/NoActiveTenantResourceRoutesTest.php.
• Existing canonical environment routes already include Inventory Items, Inventory Coverage, Entra Groups, Policy, Policy Versions, Backup Sets/Schedules, Restore Runs, Findings, Evidence, Environment Reviews, Stored Reports, and Operations through workspace/environment routes.
• Implementation must treat this repo truth as a starting point. If an artifact is already absent, the work is to strengthen or consolidate guardrails rather than inventing deletion.

Cross-Cutting / Shared Pattern Reuse

• Cross-cutting feature?: yes
• Interaction class(es): route registration, Filament provider registration, navigation guardrails, global search result destinations, operation/action links, and environment-bound resource link generation.
• 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/Navigation/NavigationScope.php
  • focused guard, navigation, search, and link tests under apps/platform/tests/
• Existing pattern(s) to extend: canonical workspace/environment routes, ManagedEnvironmentLinks, OperationRunLinks, WorkspaceScopedTenantRoutes, OperateHubShell, NavigationScope, and existing guard tests.
• Shared contract / presenter / builder / renderer to reuse: Existing route/link helpers and Filament resource URL helpers. No new route-helper framework is introduced.
• Why the existing shared path is sufficient or insufficient: Existing shared paths already emit canonical workspace/environment URLs. This cleanup only verifies no high-signal path still emits /admin/t or resurrects retired tenant-panel route names.
• Allowed deviation and why: none. Compatibility aliases, redirects, shims, and fallback helpers are forbidden in this spec.
• Consistency impact: Workspace home remains clean; environment-owned surfaces remain visible only in environment context; global search and operation links must not emit legacy route language.
• Review focus: Reviewers must verify no provider registration, route definition, link builder, global-search destination, or active test contract depends on the retired Tenant Panel runtime.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: link safety only. This spec does not start, queue, deduplicate, resume, block, complete, or redesign OperationRun behavior.
• Shared OperationRun UX contract/layer reused: Existing OperationRunLinks and App\Support\OpsUx\OperationRunUrl.
• Delegated start/completion UX behaviors: N/A for new behavior.
• Local surface-owned behavior that remains: Existing operation start and terminal notification behavior remains out of scope.
• Queued DB-notification policy: N/A.
• Terminal notification path: N/A.
• Exception required?: none.

Provider Boundary / Platform Core Check

• Shared provider/platform boundary touched?: yes, bounded to route/runtime cleanup and vocabulary guardrails.
• Boundary classification: mixed, because old tenant wording remains in some model and provider terminology while runtime routing must be workspace-first.
• Seams affected: provider registration, Filament panel IDs, route names, link builders, global search URLs, navigation tests, and historical route terminology.
• Neutral platform terms preserved or introduced: Workspace, Managed Environment, Environment, workspace-first admin runtime, canonical environment route.
• Provider-specific semantics retained and why: Tenant terminology may remain where existing database/model/provider vocabulary still requires it or where historical docs mention it. This spec is not a full terminology purge.
• Why this does not deepen provider coupling accidentally: No Microsoft provider behavior, Graph adapter, capability registry, or platform-core taxonomy is added.
• Follow-up path: navigation-contract-split only if implementation proves tests still conflate workspace-home cleanliness with environment-bound visibility after this cleanup.

UI / Surface Guardrail Impact

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Retired Tenant Panel URLs return not found	yes, negative route behavior	N/A	route guardrail	route collection	no	No new UI, route aliases, or redirects
Workspace-home sidebar stays clean	yes, regression control	Native Filament navigation	navigation	shell, route context, remembered environment context	no	Existing clean-sidebar contract is preserved
Environment-bound sidebar/resources stay visible	yes, regression control	Native Filament navigation/resources	navigation, resource links	shell, route context, resource URL generation	no	Existing Spec 301 and 303 contracts are preserved
Global search and operation links avoid /admin/t	yes, destination safety	Native Filament/global search plus shared links	search/action links	URL generation	no	No new search surface

Proportionality Review

• New source of truth?: no
• New persisted entity/table/artifact?: no
• New abstraction?: no
• New enum/state/reason family?: no
• New cross-domain UI framework/taxonomy?: no
• Current operator problem: Retired Tenant Panel assumptions can make the app appear to support two admin runtimes or can keep stale tests green while canonical workspace/environment routes regress.
• Existing structure is insufficient because: Existing guard tests are present but distributed; stale route assumptions remain in active tests and high-signal links must be verified as a set.
• Narrowest correct implementation: Delete only active dead runtime artifacts if found, update stale tests, consolidate guardrails, and run focused route/navigation/search/link validation.
• Ownership cost: Focused guardrail tests and clearer route/navigation assertions.
• Alternative intentionally rejected: Compatibility redirects or broad route-helper architecture are rejected because this is a pre-production cleanup with no legacy preservation requirement.
• Release truth: Current-release cleanup and guardrail hardening.

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope. Canonical replacement is preferred over preservation. Legacy /admin/t and /admin/tenants route families must not be revived.

Testing / Lane / Runtime Impact

• Test purpose / classification: Feature and guardrail.
• Validation lane(s): confidence; optional browser smoke if route/navigation runtime changes affect rendered navigation.
• Why this classification and these lanes are sufficient: Feature and guardrail tests can prove provider absence, route collection absence, 404 behavior, navigation separation, canonical resource reachability, global-search URL safety, operation-link URL safety, and no compatibility alias behavior.
• New or expanded test families: Focused updates to existing guard and Filament feature tests. No new heavy-governance family.
• Fixture / helper cost impact: Low. Reuse existing createUserWithTenant, ManagedEnvironment factories, WorkspaceContext, route collection assertions, and resource URL helpers.
• Heavy-family visibility / justification: none.
• Special surface test profile: global-context-shell and standard-native-filament.
• Standard-native relief or required special coverage: Native Filament navigation/resources use feature tests; browser smoke is recommended only if rendered navigation or route registration changes cannot be proven by feature tests alone.
• Reviewer handoff: Confirm no /admin/t, no /admin/tenants, no tenant panel provider, no stale blanket-hidden admin contract, no link emission to retired routes, and no weakened RBAC/context coverage.
• Budget / baseline / trend impact: Low; focused tests only.
• Escalation needed: none unless implementation finds structural navigation-test coupling.
• Active feature PR close-out entry: Guardrail / Smoke Coverage if browser smoke runs; otherwise document feature-test substitute.
• Planned validation commands:
  • 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

User Scenarios & Testing

User Story 1 - Retired Tenant Panel runtime cannot boot (Priority: P1)

As a platform maintainer, I need the retired Tenant Panel provider and panel ID to stay out of the boot path so new features cannot accidentally bind to a second admin runtime.

Why this priority: Provider registration is the highest-signal runtime boundary. If a Tenant Panel provider can boot, route and navigation cleanup is incomplete.

Independent Test: Assert bootstrap providers do not register a Tenant Panel provider, no active provider class exists in app runtime paths, and Filament::getPanel('tenant') is absent.

Acceptance Scenarios:

1. Given the application boots, When registered providers are inspected, Then no Tenant Panel provider is registered.
2. Given runtime app paths are inspected, When Tenant Panel provider classes are searched, Then no active provider class remains unless a documented blocker explicitly allowlists it as non-runtime.
3. Given Filament panels are resolved, When the tenant panel ID is requested, Then no panel is returned.

---

User Story 2 - Legacy route families are unavailable (Priority: P1)

As a platform maintainer, I need legacy /admin/t and /admin/tenants entry routes to fail instead of redirecting, aliasing, or preserving old panel semantics.

Why this priority: Route availability is the visible compatibility boundary. This spec must retire old URLs, not preserve them.

Independent Test: Assert the route collection contains no admin/t or legacy admin/tenants product routes, route names do not carry retired tenant-panel semantics, and direct requests return 404.

Acceptance Scenarios:

1. Given the route collection is loaded, When route URIs are inspected, Then no active URI starts with admin/t.
2. Given the route collection is loaded, When legacy entry URIs are inspected, Then no active /admin/tenants/{environment} legacy entry route remains.
3. Given an authenticated workspace/environment user, When they request /admin/t/{environment} or /admin/t/{environment}/inventory-items, Then the response is not found.
4. Given an authenticated workspace/environment user, When they request /admin/tenants/{environment}, Then the response is not found and is not redirected to a canonical route.

---

User Story 3 - Workspace and environment navigation contracts remain precise (Priority: P2)

As an operator, I need workspace home to stay clean while eligible environment-bound surfaces remain visible inside the selected environment.

Why this priority: Specs 301 and 303 repaired the distinction between workspace-home navigation and environment-bound admin visibility. This cleanup must not regress those contracts.

Independent Test: Render workspace-home and canonical environment routes and assert the expected absence/presence of Inventory, Entra Groups, policy, backup, restore, findings, evidence, review, report, and operations surfaces.

Acceptance Scenarios:

1. Given a workspace-home route with remembered environment context, When navigation renders, Then environment-owned resources are absent.
2. Given a canonical environment route and an entitled user, When navigation renders, Then Inventory and Entra Groups remain visible according to Specs 301 and 303.
3. Given environment-bound resource URLs are generated, When their paths are inspected, Then they use workspace/environment routes and not /admin/t.

---

User Story 4 - Links and search never emit retired routes (Priority: P3)

As an operator following links from search, operations, dashboards, or notifications, I need destinations to use canonical workspace/environment URLs so I do not land on retired route families.

Why this priority: Hidden link emission can keep old runtime assumptions alive after route definitions are gone.

Independent Test: Exercise high-signal link builders and global-search result URLs and assert no generated URL contains /admin/t or old tenant-panel route names.

Acceptance Scenarios:

1. Given Entra Groups global search has an active environment context, When result URLs are generated, Then URLs point to canonical workspace/environment View routes and do not contain /admin/t.
2. Given ManagedEnvironmentLinks, OperationRunLinks, and OperationRunUrl generate destinations, When generated URLs are inspected, Then they use canonical workspace or workspace/environment routes.
3. Given legacy references remain only in historical docs or removal tests, When active app code and active tests are searched, Then no runtime dependency on retired route emission remains.

Edge Cases

• The Tenant Panel provider class is already absent; implementation must strengthen tests rather than recreate a deletion diff.
• Legacy /admin/tenants/{environment}/provider-connections tests may represent stale compatibility behavior and must be updated only if repo route truth confirms no active route exists.
• Historical docs and old specs mention /admin/t; these are allowed and must not be purged.
• Test names may mention legacy routes when they explicitly assert removal.
• Remembered environment context exists while the user is on workspace home.
• A generated route uses a record's environment relation but no explicit tenant parameter.
• A global-search result is generated after the active environment changes.
• Cross-workspace or cross-environment URLs are manipulated manually.

Functional Requirements

• FR-001: No active Tenant Panel provider may remain in application provider bootstrap.
• FR-002: No active Tenant Panel provider class may remain in runtime app code unless an explicit preparation finding documents a temporary blocker and proves it is not registered.
• FR-003: The application MUST NOT register routes whose URI starts with admin/t.
• FR-004: Retired /admin/t/{environment} and /admin/t/{environment}/... URLs MUST return not found or equivalent non-match behavior.
• FR-005: Legacy /admin/tenants/{environment} entry URLs MUST remain unavailable unless proven to be current canonical workspace/environment routes.
• FR-006: The implementation MUST NOT add compatibility redirects, aliases, fallback middleware, or helper shims for retired route families.
• FR-007: Workspace MUST remain the active Filament admin tenant context; Managed Environment remains a secondary domain context inside a workspace.
• FR-008: Inventory Items, Inventory Coverage, Entra Groups, Policy, Policy Versions, Backup Sets/Schedules, Restore Runs, Findings, Evidence Snapshots, Environment Reviews, Stored Reports, and applicable Operations MUST remain reachable through canonical workspace/environment routes.
• FR-009: Workspace-home navigation MUST remain clean and MUST NOT show environment-owned resources without active environment context.
• FR-010: Environment-bound navigation MUST remain visible only where the product contract permits it, including the Spec 301 Inventory and Spec 303 Entra Groups contracts.
• FR-011: Tests MUST NOT preserve a blanket rule that all tenant-owned resources are hidden from admin. They MUST distinguish workspace-home hidden from environment-context visible.
• FR-012: High-signal link builders and global-search destinations MUST NOT emit /admin/t URLs.
• FR-013: Server-side RBAC, workspace isolation, environment scoping, tenant-owned record scoping, capability checks, and global-search scoping MUST remain intact.
• FR-014: Historical docs, old specs, migration notes, and removal tests MAY mention Tenant Panel or /admin/t if clearly historical or removal-focused.
• FR-015: No Microsoft/provider-specific behavior may move into platform core during cleanup.
• FR-016: This spec MUST NOT introduce migrations, persisted entities, runtime features, new destructive actions, new assets, or broad localization/terminology cleanup.

Non-Functional Requirements

• NFR-001: Filament v5 compatibility must be preserved with Livewire v4.0+; this repo currently uses Filament 5.2.1 and Livewire 4.1.4.
• NFR-002: Laravel provider registration stays in apps/platform/bootstrap/providers.php; providers must not be moved into bootstrap/app.php.
• NFR-003: Globally searchable resources touched by this cleanup must either keep valid View/Edit destinations or disable global search. Entra Groups, Policy, and Policy Versions currently have focused global-search parity coverage.
• NFR-004: No destructive Filament actions are added. If cleanup touches an existing destructive action indirectly, confirmation and authorization requirements remain unchanged.
• NFR-005: No assets are added. Deployment asset strategy remains unchanged; the normal Filament asset deployment step remains cd apps/platform && php artisan filament:assets when registered assets are deployed.
• NFR-006: Test additions must stay focused and avoid broad heavy-governance or browser lanes unless rendered navigation changes require browser smoke.

Out Of Scope

• New workspace/environment routing model.
• ManagedEnvironment schema/core cutover.
• tenant_id to managed_environment_id migration.
• Dual-read, dual-write, route aliases, redirects, or compatibility bridges.
• New product navigation or new Directory/Identity features.
• Customer portal, Customer Review Workspace, Governance Inbox, OperationRun progress, billing, entitlement, provider, or Microsoft Graph changes.
• Migrations, destructive actions, asset changes, broad localization cleanup, or full repository terminology purge.

Acceptance Criteria

• AC-001: No Tenant Panel provider is registered in active runtime bootstrap.
• AC-002: No active Tenant Panel provider/runtime class remains, or a narrow documented blocker proves why it is temporarily non-runtime.
• AC-003: /admin/t/{environment} and /admin/t/{environment}/... are unavailable and not registered.
• AC-004: /admin/tenants/{environment} legacy entry behavior is unavailable unless proven canonical and non-legacy.
• AC-005: No redirects, aliases, or middleware shims from retired routes to canonical workspace/environment routes are introduced.
• AC-006: Workspace-first admin runtime remains functional.
• AC-007: Canonical environment routes remain functional.
• AC-008: Inventory remains hidden on workspace home and visible/reachable in environment context.
• AC-009: Entra Groups remains hidden on workspace home and visible/reachable in environment context according to Spec 303.
• AC-010: Global-search result URLs and high-signal link builders do not emit /admin/t.
• AC-011: Tests no longer protect stale blanket hidden assumptions for all tenant-owned resources in admin.
• AC-012: RBAC, workspace isolation, environment scoping, and cross-environment denial remain covered.
• AC-013: At least one guardrail test fails if Tenant Panel runtime or /admin/t routes return.
• AC-014: No new product surfaces, mutation workflows, provider behavior, migrations, assets, or compatibility layers are introduced.
• AC-015: Focused tests and git diff --check pass. Browser smoke is either passed or explicitly documented as not run with a feature-test substitute.

Success Criteria

• A repo search of active runtime paths finds no registered Tenant Panel provider and no active /admin/t route definitions.
• Route collection tests prove no /admin/t route and no legacy tenant-panel route names are active.
• Focused navigation tests prove workspace-home cleanliness and environment-bound visibility independently.
• Focused link/search tests prove generated destinations use canonical workspace/environment paths.
• Implementation close-out reports whether Tenant Panel provider and legacy routes were already absent or removed during the spec.

Risks

• Risk: Removing or rewriting stale tests could weaken RBAC coverage. Mitigation: Replace blanket hidden assertions with explicit workspace-home, environment-context, no-context, cross-workspace, and cross-environment assertions.
• Risk: Old route URLs are still emitted by notifications, operation links, or references. Mitigation: Inspect high-signal link builders and add targeted no-/admin/t assertions.
• Risk: Historical docs cleanup expands the scope. Mitigation: Allow historical mentions and update only current product truth docs if needed.
• Risk: Cleanup drifts into ManagedEnvironment core cutover. Mitigation: No schema work, no model rename, no dual relation cleanup, and no provider-neutral core refactor.

Assumptions

• Specs 301, 302, and 303 are completed or reviewed context packages and must not be rewritten by this preparation work.
• The current route truth from Laravel route inspection is authoritative unless implementation discovers a runtime-only route path not visible in the route collection.
• The product remains pre-production, so legacy compatibility is not required unless a future spec explicitly changes that posture.
• Historical /admin/t mentions in old specs and docs are allowed.

Open Questions

• None blocking. If implementation discovers a real active dependency on /admin/t or /admin/tenants, document the dependency and either remove it within scope or defer it as a narrow blocker instead of adding compatibility behavior.

Follow-Up Spec Candidates

• navigation-contract-split: Promote only if tests still conflate workspace-home cleanliness with environment-bound surface visibility after this cleanup.
• governance-artifact-navigation-proof-pass: Promote only if governance artifacts still need one canonical proof lane for environment navigation after current tests remain distributed.
• alert-delivery-route-rbac-audit: Promote only if alert delivery becomes part of the tenant-owned/environment-owned navigation repair sequence.
• managed-environment-core-cutover-follow-up: Promote only if cleanup exposes model/schema-level tenant-core blockers. Do not hide that work inside this spec.