TenantAtlas/specs/297-managed-environment-canonical-route-cutover/tasks.md

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

• Lane assignment is named and is the narrowest sufficient proof for each changed behavior.
• New or changed tests stay in the smallest honest family; browser/heavy-governance additions are explicit.
• Shared helpers, factories, seeds, fixtures, provider setup, workspace context, session state, and capability defaults stay cheap by default.
• Planned validation commands cover route/link/helper/intended URL changes without pulling in unrelated lane cost.
• The declared surface test profile or standard-native-filament relief is explicit.
• 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.

• 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.
• T002 Confirm the implementation branch is 297-managed-environment-canonical-route-cutover or an isolated session branch derived from it.
• 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.
• 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".
• 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'.
• 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.
• 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.

• 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.
• 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.
• T010 Delete /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Providers/Filament/TenantPanelProvider.php if no true runtime dependency exists.
• 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.
• T012 Update tests that directly inspect the provider file so they assert registration and route behavior instead of requiring the file to exist.
• 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.

• T014 [P] Locate existing managed-environment route/helper owners in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app before creating a new helper.
• T015 [P] Audit current route names for environment index, detail, required permissions, diagnostics, access scopes, provider connections, and workspace operations.
• 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.
• 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.
• T018 Ensure every helper method receives enough workspace/environment context to avoid ambiguous cross-workspace URL generation.
• T019 Add tests proving generated canonical URLs never contain /admin/tenants or /admin/t/.
• 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.

• T021 [P] Audit runtime occurrences of TenantResource::getUrl(...), TenantDashboard::getUrl(...), and TenantRequiredPermissions::getUrl(...) under /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app.
• T022 Replace environment detail links with the canonical managed-environment link helper or repo-real equivalent.
• T023 Replace required-permissions links with canonical workspace/environment required-permissions URLs.
• T024 Replace diagnostics/provider-health/access-scope links with canonical workspace/environment URLs where repo-real routes exist.
• T025 Replace provider-connection tenant-detail backlinks with tenantless provider-connection URLs or canonical environment detail links, depending on the page owner.
• T026 Replace dashboard/workspace overview/action links that still point at /admin/tenants... or TenantDashboard legacy routes.
• T027 Ensure OperationRunLinks and related navigation still generate workspace-scoped operations URLs and do not reintroduce tenant-scoped operation paths.
• 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.

• 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.
• 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.
• T031 Apply the retirement strategy to /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/TenantResource.php and related registration/discovery owners.
• T032 Update global search behavior for any retired or moved resource: globally searchable resources must have Edit/View pages, otherwise disable global search.
• T033 Ensure no navigation item, table action, header action, empty-state action, notification, or redirect uses /admin/tenants... as an active product destination.
• 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.
• 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.

• T036 [P] Inspect /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Workspaces/WorkspaceRedirectResolver.php and any repo-real WorkspaceIntendedUrl owner.
• 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.
• T038 Update intended URL handling to reject /admin/t, /admin/t/*, /admin/tenants, /admin/tenants/*, /admin/tenants/*/required-permissions, and /admin/tenants/*/provider-connections.
• T039 Normalize legacy /admin/operations to workspace-scoped operations only when a workspace is known and authorized.
• T040 Fall back to workspace home or environment index when legacy URL resolution is ambiguous or unsafe.
• 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.

• T042 [P] Audit /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/TenantRequiredPermissions.php, provider-connection resources/pages, and related tests.
• T043 Update required-permissions runtime links and tests to use /admin/workspaces/{workspace}/environments/{environment}/required-permissions or the repo-real canonical equivalent.
• T044 Update provider-connection links and tests so provider connections remain tenantless admin resources with neutral workspace/environment scope context.
• 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.
• T046 Ensure old /admin/tenants/{environment}/required-permissions does not return 200 and is not used in link generation.
• 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.

• T048 [P] Audit every setTenantPanelContext() usage under /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests.
• T049 Add or extend a guard that asserts /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Pest.php does not contain setTenantPanelContext.
• 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().
• T051 Ensure the replacement helper sets admin panel + workspace + managed-environment context and documents that no TenantPanel exists.
• T052 Update every test call site to the new helper name.
• T053 Do not leave a compatibility alias under setTenantPanelContext.
• 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.

• T055 Confirm tests touching managed-environment memberships do not treat managed_environment_memberships.role as capability authority.
• T056 Update stale change_role or scope-role authority expectations to workspace-membership role/capability truth.
• T057 Confirm provider-connection and environment access policies still enforce workspace membership first and managed-environment narrowing second.
• 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.

• 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.
• T060 Keep provider-specific Microsoft tenant ID copy, technical model names, migrations, historical specs, and audit historical values where correct.
• 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.
• 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.

• 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.
• 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.
• T065 Run the existing Spec 293 cutover/stabilization proof if any touched tests overlap with Spec 293 seams.
• 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.

• T067 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards.
• T068 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces.
• T069 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections.
• T070 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/RequiredPermissions.
• T071 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament.
• T072 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail bin pint --dirty --format agent.
• T073 Run git diff --check from /Users/ahmeddarrazi/Documents/projects/wt-plattform.
• T074 Update legacy-surface-audit.md with fixed/remaining status and allowed references.
• 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.
• 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