--- description: "Task list for Managed Environment Canonical Route Cutover & Legacy Tenant Surface Retirement" --- # Tasks: Managed Environment Canonical Route Cutover & Legacy Tenant Surface Retirement **Input**: Design documents from `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/297-managed-environment-canonical-route-cutover/` **Prerequisites**: `spec.md`, `plan.md`, `research.md`, `data-model.md`, `quickstart.md`, `legacy-surface-audit.md`, `contracts/managed-environment-canonical-route-contract.md`, `checklists/requirements.md` **Tests**: Required (Pest) for route/link/intended URL/helper changes. Browser smoke is required only if visible navigation flows are touched. **Operations**: No new `OperationRun` behavior. Existing operation links must stay workspace-scoped through the shared OperationRun link contract. **RBAC**: Workspace membership remains role/capability authority. Managed-environment membership remains narrowing-only. Non-member/out-of-scope returns 404; established member missing capability returns 403. **Filament / Panel Guardrails**: Filament remains v5 on Livewire v4. Provider registration remains in `apps/platform/bootstrap/providers.php`. No new panel. No asset-strategy change unless explicitly documented. **Review Outcome**: preparation-ready **Workflow Outcome**: keep **Test-governance Outcome**: keep ## Test Governance Checklist - [x] Lane assignment is named and is the narrowest sufficient proof for each changed behavior. - [x] New or changed tests stay in the smallest honest family; browser/heavy-governance additions are explicit. - [x] Shared helpers, factories, seeds, fixtures, provider setup, workspace context, session state, and capability defaults stay cheap by default. - [x] Planned validation commands cover route/link/helper/intended URL changes without pulling in unrelated lane cost. - [x] The declared surface test profile or `standard-native-filament` relief is explicit. - [x] Any material runtime, budget, baseline, trend, or escalation note is recorded in the active spec close-out. ## Phase 1: Safety Gate And Baseline Audit **Purpose**: Start from a clean branch and refresh repo truth before runtime edits. - [x] T001 Run `git status --short --branch`, `git diff --stat`, and `git log -1 --oneline` in `/Users/ahmeddarrazi/Documents/projects/wt-plattform`; stop if unrelated uncommitted changes are present. - [x] T002 Confirm the implementation branch is `297-managed-environment-canonical-route-cutover` or an isolated session branch derived from it. - [x] T003 Review `/Users/ahmeddarrazi/Documents/projects/wt-plattform/.specify/memory/constitution.md`, this spec package, and related Specs 287, 288, 293, and 296 as context only. - [x] T004 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan route:list | rg "admin/t|admin/tenants|provider-connections|required-permissions|workspaces/.*/environments|operations"`. - [x] T005 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && rg "TenantPanelProvider|panel:\\s*'tenant'|panel:\\s*\\\"tenant\\\"|/admin/t/|/admin/tenants|TenantResource::getUrl|TenantDashboard::getUrl|TenantRequiredPermissions::getUrl|setTenantPanelContext|admin\\.operations" . --glob '!vendor' --glob '!node_modules'`. - [x] T006 Update `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/297-managed-environment-canonical-route-cutover/legacy-surface-audit.md` with every active runtime, test, copy, historical, provider-specific, and allowed technical finding before editing application code. - [x] T007 Confirm the scope boundary remains explicit: no DB/model rename, no compatibility surface, no Package Execution, no Guided Operations, no broad localization, no broad RBAC rewrite, and no TenantPanel restoration. ## Phase 2: Remove Or Permanently Neutralize TenantPanelProvider **Goal**: Ensure the retired tenant panel cannot be reactivated as runtime code. - [x] T008 [P] Inspect `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Providers/Filament/TenantPanelProvider.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/bootstrap/providers.php`, and current tests that reference `TenantPanelProvider`. - [x] T009 Add or extend `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Guards/NoLegacyTenantPanelRuntimeTest.php` to assert `TenantPanelProvider` is not registered, no `/admin/t...` route exists, and no active panel provider with `id('tenant')` exists. - [x] T010 Delete `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Providers/Filament/TenantPanelProvider.php` if no true runtime dependency exists. - [x] T011 If T010 is blocked by a true dependency, document the dependency in `legacy-surface-audit.md` and still guard against registration or route activation. - [x] T012 Update tests that directly inspect the provider file so they assert registration and route behavior instead of requiring the file to exist. - [x] T013 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/NoLegacyTenantPanelRuntimeTest.php`. ## Phase 3: Establish Canonical Managed Environment Link Contract **Goal**: Route all environment links through one canonical owner. - [x] T014 [P] Locate existing managed-environment route/helper owners in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app` before creating a new helper. - [x] T015 [P] Audit current route names for environment index, detail, required permissions, diagnostics, access scopes, provider connections, and workspace operations. - [x] T016 Add or extend `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Guards/ManagedEnvironmentCanonicalRouteContractTest.php` to prove canonical link generation for index/detail/required-permissions/diagnostics/access-scopes/operations. - [x] T017 Create or extend the bounded canonical link helper, such as `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/ManagedEnvironmentLinks.php`, only if no repo-real helper already owns this contract. - [x] T018 Ensure every helper method receives enough workspace/environment context to avoid ambiguous cross-workspace URL generation. - [x] T019 Add tests proving generated canonical URLs never contain `/admin/tenants` or `/admin/t/`. - [x] T020 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/ManagedEnvironmentCanonicalRouteContractTest.php`. ## Phase 4: Replace Runtime Legacy URL Generation **Goal**: Stop runtime links from emitting TenantResource/TenantDashboard/TenantRequiredPermissions URLs as product truth. - [x] T021 [P] Audit runtime occurrences of `TenantResource::getUrl(...)`, `TenantDashboard::getUrl(...)`, and `TenantRequiredPermissions::getUrl(...)` under `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app`. - [x] T022 Replace environment detail links with the canonical managed-environment link helper or repo-real equivalent. - [x] T023 Replace required-permissions links with canonical workspace/environment required-permissions URLs. - [x] T024 Replace diagnostics/provider-health/access-scope links with canonical workspace/environment URLs where repo-real routes exist. - [x] T025 Replace provider-connection tenant-detail backlinks with tenantless provider-connection URLs or canonical environment detail links, depending on the page owner. - [x] T026 Replace dashboard/workspace overview/action links that still point at `/admin/tenants...` or TenantDashboard legacy routes. - [x] T027 Ensure `OperationRunLinks` and related navigation still generate workspace-scoped operations URLs and do not reintroduce tenant-scoped operation paths. - [x] T028 Update runtime tests around notifications, toast actions, review detail links, evidence links, decision-register links, provider connection links, required-permissions links, workspace dashboard links, governance inbox links, and tenant dashboard/back links as directly touched. ## Phase 5: Retire Active `/admin/tenants...` Product Routes **Goal**: Remove `/admin/tenants...` as active product truth. - [x] T029 Add or extend `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Guards/NoActiveTenantResourceRoutesTest.php` to assert `/admin/tenants`, `/admin/tenants/{environment}`, `/admin/tenants/{environment}/edit`, and `/admin/tenants/{environment}/memberships` are not active product pages. - [x] T030 Decide the narrowest repo-real retirement strategy for TenantResource: remove active route registration, move it out of auto-discovery, disable it as a product surface, or replace it with canonical managed-environment routing. - [x] T031 Apply the retirement strategy to `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/TenantResource.php` and related registration/discovery owners. - [x] T032 Update global search behavior for any retired or moved resource: globally searchable resources must have Edit/View pages, otherwise disable global search. - [x] T033 Ensure no navigation item, table action, header action, empty-state action, notification, or redirect uses `/admin/tenants...` as an active product destination. - [x] T034 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan route:list | rg "admin/tenants"` and classify any remaining route in `legacy-surface-audit.md`. - [x] T035 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/NoActiveTenantResourceRoutesTest.php`. ## Phase 6: Intended URL Legacy Rejection **Goal**: Prevent old paths from surviving login/workspace-selection redirects. - [x] T036 [P] Inspect `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Workspaces/WorkspaceRedirectResolver.php` and any repo-real `WorkspaceIntendedUrl` owner. - [x] T037 Add `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Workspaces/WorkspaceIntendedUrlLegacyRejectionTest.php` covering retired tenant-panel URLs, retired tenant-resource URLs, legacy operations normalization, unsafe fallback, and external URL blocking. - [x] T038 Update intended URL handling to reject `/admin/t`, `/admin/t/*`, `/admin/tenants`, `/admin/tenants/*`, `/admin/tenants/*/required-permissions`, and `/admin/tenants/*/provider-connections`. - [x] T039 Normalize legacy `/admin/operations` to workspace-scoped operations only when a workspace is known and authorized. - [x] T040 Fall back to workspace home or environment index when legacy URL resolution is ambiguous or unsafe. - [x] T041 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces/WorkspaceIntendedUrlLegacyRejectionTest.php`. ## Phase 7: Required Permissions And Provider Connections Canonicalization **Goal**: Keep tenant-scoped required-permissions and provider-connection URLs retired. - [x] T042 [P] Audit `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/TenantRequiredPermissions.php`, provider-connection resources/pages, and related tests. - [x] T043 Update required-permissions runtime links and tests to use `/admin/workspaces/{workspace}/environments/{environment}/required-permissions` or the repo-real canonical equivalent. - [x] T044 Update provider-connection links and tests so provider connections remain tenantless admin resources with neutral workspace/environment scope context. - [x] T045 Update `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/ProviderConnections/LegacyRedirectTest.php` so old tenant-scoped provider-connection URLs assert not-found rather than compatibility redirect. - [x] T046 Ensure old `/admin/tenants/{environment}/required-permissions` does not return 200 and is not used in link generation. - [x] T047 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/RequiredPermissions tests/Feature/ProviderConnections`. ## Phase 8: Rename Tenant-Panel Test Helper **Goal**: Remove `setTenantPanelContext()` with no alias. - [x] T048 [P] Audit every `setTenantPanelContext()` usage under `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests`. - [x] T049 Add or extend a guard that asserts `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Pest.php` does not contain `setTenantPanelContext`. - [x] T050 Rename the helper in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Pest.php` to the selected canonical name, such as `setAdminEnvironmentContext()` or `setManagedEnvironmentContext()`. - [x] T051 Ensure the replacement helper sets admin panel + workspace + managed-environment context and documents that no TenantPanel exists. - [x] T052 Update every test call site to the new helper name. - [x] T053 Do not leave a compatibility alias under `setTenantPanelContext`. - [x] T054 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && rg "setTenantPanelContext|panel:\\s*'tenant'|panel:\\s*\\\"tenant\\\"" tests` and classify only explicit retired-behavior guards if any remain. ## Phase 9: RBAC And Access-Scope Authority Check **Goal**: Preserve workspace-first RBAC while route/test fixtures move. - [x] T055 Confirm tests touching managed-environment memberships do not treat `managed_environment_memberships.role` as capability authority. - [x] T056 Update stale `change_role` or scope-role authority expectations to workspace-membership role/capability truth. - [x] T057 Confirm provider-connection and environment access policies still enforce workspace membership first and managed-environment narrowing second. - [x] T058 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/ManagedEnvironmentAccessScopeManagementTest.php tests/Feature/Rbac/ProviderConnectionWorkspaceFirstPolicyTest.php`. ## Phase 10: Copy Cleanup In Touched Active Surfaces **Goal**: Avoid tenant-first product copy in files touched by this cutover. - [x] T059 Replace tenant-first user-facing copy in touched active surfaces, including `Tenant dashboard`, `Tenant detail`, `Open tenant detail`, `Select tenant`, `Tenant scope`, `Managed tenant`, `Remove tenant`, `Restore tenant`, and `Tenant memberships`. - [x] T060 Keep provider-specific Microsoft tenant ID copy, technical model names, migrations, historical specs, and audit historical values where correct. - [x] T061 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && rg "Tenant dashboard|Tenant detail|Open tenant|Select tenant|Tenant scope|Remove tenant|Restore tenant|Tenant memberships" app resources lang tests`. - [x] T062 Record every remaining touched-file hit in `legacy-surface-audit.md` as allowed, provider-specific, technical/internal, historical, or follow-up. ## Phase 11: Regression Proof Pack **Goal**: Prove the new cutover and existing guard packs stay green. - [x] T063 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/NoLegacyTenantPanelRuntimeTest.php tests/Feature/Guards/NoActiveTenantResourceRoutesTest.php tests/Feature/Guards/ManagedEnvironmentCanonicalRouteContractTest.php tests/Feature/Workspaces/WorkspaceIntendedUrlLegacyRejectionTest.php tests/Feature/ProviderConnections/LegacyRedirectTest.php tests/Feature/ManagedEnvironment/LegacyTenantCoreGuardTest.php tests/Feature/Spec080WorkspaceManagedTenantAdminMigrationTest.php tests/Feature/Filament/ManagedEnvironmentAccessScopeManagementTest.php tests/Feature/Rbac/ProviderConnectionWorkspaceFirstPolicyTest.php`. - [x] T064 Run the existing Spec 288 guard pack exactly as listed in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/297-managed-environment-canonical-route-cutover/spec.md`. - [x] T065 Run the existing Spec 293 cutover/stabilization proof if any touched tests overlap with Spec 293 seams. - [x] T066 If visible navigation or browser flow files changed, run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec281ProviderConnectionScopeSmokeTest.php tests/Browser/Spec285WorkspaceRbacEnvironmentAccessSmokeTest.php`. ## Phase 12: Broad Validation And Close-Out **Goal**: Finish with focused broad lanes, formatting, and the required decision. - [x] T067 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards`. - [x] T068 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces`. - [x] T069 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections`. - [x] T070 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/RequiredPermissions`. - [x] T071 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament`. - [x] T072 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`. - [x] T073 Run `git diff --check` from `/Users/ahmeddarrazi/Documents/projects/wt-plattform`. - [x] T074 Update `legacy-surface-audit.md` with fixed/remaining status and allowed references. - [x] T075 Confirm the Filament output contract: Livewire v4.0+ compliance, provider registration in `bootstrap/providers.php`, global-search handling for retired resources, destructive-action confirmation/authorization unchanged, asset strategy unchanged or deploy note added, and tests cover pages/actions/widgets through Livewire/Filament where applicable. - [x] T076 Write the final implementation summary with commands run, deleted legacy code, retired routes, canonical replacements, remaining legacy references, test results, and one final decision string. ## Dependencies & Execution Order - Phase 1 blocks all runtime edits. - Phase 2 and Phase 5 are high-risk route/provider changes and should happen before broad runtime link replacement is considered complete. - Phase 3 can begin after Phase 1 and should land before most runtime replacement work in Phase 4. - Phase 6 depends on enough canonical route/link contract from Phase 3 to choose safe fallbacks. - Phase 7 depends on Phase 3 and Phase 5 route decisions. - Phase 8 can run alongside later route replacement but must finish before final guards. - Phase 9 must run after helper/test fixture changes that might affect RBAC setup. - Phase 10 applies only to files touched by implementation. - Phases 11 and 12 close the proof loop. ## Parallel Execution Examples - T008 and T014 can run in parallel because provider deletion and link helper discovery inspect different owners. - T021 and T036 can run in parallel after Phase 1 because runtime link audit and intended URL audit touch different seams. - T042 and T048 can run in parallel because required-permissions/provider-connection audit and helper-call-site audit are separate. - T059 can run after any touched-file set is known; it should not begin a repo-wide localization sweep. ## Explicit Follow-Ups / Out of Scope - Database/model rename from `Tenant` to `ManagedEnvironment` - Broad tenant-to-environment localization sweep - Package Execution Contract - Guided Operations - Microsoft Provider Refactor - New provider abstraction or route framework - Full-suite repair unless separately requested