TenantAtlas/specs/317-legacy-tenant-environment-context-cleanup/tasks.md

Tasks: Legacy Tenant / Environment Context Cleanup

Input: spec.md, plan.md Prerequisites: Specs 313, 314, 315, and 316 are completed historical baseline context. Do not rewrite them as preparation artifacts.

Important: These tasks are for the later implementation loop. No runtime implementation was performed during preparation.

Test Governance Checklist

• Lane assignment is named and is the narrowest sufficient proof for static legacy terms, query aliases, routes, helper/API names, UI copy, and browser-visible links.
• New or changed tests stay in the smallest honest family, with browser smoke explicit and limited.
• Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented.
• Planned validation commands cover the cleanup without pulling in unrelated lane cost.
• Provider-boundary Tenant terminology is protected through an allowlist instead of blocked by naive grep.
• Any material budget, baseline, trend, browser limitation, or escalation note is recorded in the active spec or implementation close-out.

Phase 1: Guardrails and Baseline

• T001 Verify the implementation starts from branch 317-legacy-tenant-environment-context-cleanup with git status --short --branch and no unrelated user changes.
• T002 Re-read specs/313-workspace-environment-context-browser-verification/spec.md, specs/314-workspace-hub-navigation-context-contract/spec.md, specs/315-environment-cta-explicit-filter-contract/spec.md, and specs/316-workspace-hub-clear-filter-contract/spec.md as completed historical baseline context only.
• T003 Confirm Laravel/Filament/Livewire/Pest versions through Laravel Boost application_info.
• T004 Confirm AdminPanelProvider and SystemPanelProvider remain registered through apps/platform/bootstrap/providers.php and no TenantPanelProvider is active.
• T005 Confirm no migration, seeder, package, env var, queue, scheduler, storage, or deployment asset change is planned unless later inventory proves a bounded exception.

Phase 2: Inventory and Allowlist

• T006 Create specs/317-legacy-tenant-environment-context-cleanup/legacy-inventory.md with columns for file, symbol/method/route/label, current meaning, correct meaning, classification, action, and risk.
• T007 Create specs/317-legacy-tenant-environment-context-cleanup/tenant-usage-allowlist.md with allowed provider-boundary examples, disallowed platform-context examples, scan paths, and review rules.
• T008 Run the required Tenant/Environment search across apps/platform/app, apps/platform/resources, apps/platform/routes, apps/platform/tests, docs, and current/recent specs.
• T009 Classify all high-risk occurrences of TenantPageCategory, WorkspaceScopedTenantRoutes, CanonicalAdminTenantFilterState, EnsureFilamentTenantSelected, TenantPanelProvider, tenantPrefilterUrl, lastTenantId, remembered tenant, tenant_scope, tenant_id, managed_environment_id, Filament::getTenant(), getTenant(), tableFilters, and /admin/t.
• T010 Classify provider-boundary occurrences such as provider_tenant_id, external_tenant_id, microsoft_tenant_id, entra_tenant_id, Graph tenantId, and OAuth tenant authority segments as allowed provider-boundary when correct.
• T011 Mark completed historical spec/doc occurrences as allowed_historical_archived_doc unless they are current product truth.
• T012 Mark ambiguous cases as needs_product_decision and do not guess or implement those specific renames without a bounded decision.

Phase 3: Tests First - Static and Contract Guards

• T013 Add it_platform_context_does_not_use_legacy_tenant_terms in an appropriate guard test under apps/platform/tests/Feature/Guards/ with allowlist support from the Spec 317 allowlist artifact.
• T014 Add it_workspace_hubs_do_not_accept_legacy_tenant_query_aliases covering Operations, Governance Inbox, Decision Register, Finding Exceptions Queue, Provider Connections, Evidence, Review Register, and Customer Review Workspace.
• T015 Add assertions that tenant, tenant_id, managed_environment_id, tenant_scope, environment, and tableFilters do not show an Environment chip or filter Workspace hub data without environment_id.
• T016 Add assertions that valid environment_id still applies the Spec 315/316 canonical Environment filter behavior.
• T017 Add it_workspace_hubs_do_not_use_filament_tenant_or_remembered_tenant_as_scope with static checks for Filament::getTenant(), getTenant(), lastTenantId, and remembered Tenant fallback in Workspace hub classes.
• T018 Add it_admin_has_no_active_legacy_tenant_panel_routes proving no active /admin/t routes and no active TenantPanelProvider registration.
• T019 Add helper/API rename coverage proving tenantPrefilterUrl() is gone and the Environment-named replacement is used.
• T020 Add helper/class guard coverage for TenantPageCategory, WorkspaceScopedTenantRoutes, CanonicalAdminTenantFilterState, and EnsureFilamentTenantSelected once each is renamed, removed, or quarantined.
• T021 Add or update rendered-view/UI copy guard it_active_workspace_environment_ui_uses_environment_not_tenant for active Workspace/Environment surfaces, with provider-boundary exceptions.

Phase 4: Query and URL Cleanup

• T022 Update apps/platform/app/Support/Navigation/WorkspaceHubEnvironmentFilter.php so only environment_id is a valid Environment filter source.
• T023 Update apps/platform/app/Support/Navigation/WorkspaceHubRegistry.php and related clean URL helpers so generated Workspace hub links never emit legacy Tenant query params.
• T024 Update apps/platform/app/Support/Navigation/WorkspaceHubFilterStateResetter.php so legacy Tenant-like keys can be cleared/neutralized but never become valid Environment filter sources.
• T025 Remove Workspace hub handling for tenant, tenant_id, managed_environment_id, tenant_scope, environment, and tableFilters as Environment filter aliases.
• T026 Confirm Environment-owned CTA helpers still generate environment_id and do not regress Spec 315 behavior.
• T027 Confirm clear-filter links still remove legacy keys and do not regress Spec 316 behavior.

Phase 5: Helper, Class, and Fallback Cleanup

• T028 Rename or remove tenantPrefilterUrl() on apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php with no deprecated alias.
• T029 Rename tenantId, tenantLabel, tenantFilter, and tenantScope variables/properties when they mean Managed Environment on Workspace hub code paths.
• T030 Rename, remove, or explicitly quarantine apps/platform/app/Support/Tenants/TenantPageCategory.php based on actual responsibility after cleanup.
• T031 Rename, remove, or explicitly quarantine apps/platform/app/Filament/Concerns/WorkspaceScopedTenantRoutes.php based on actual route responsibility after cleanup.
• T032 Rename, remove, or explicitly quarantine apps/platform/app/Support/Filament/CanonicalAdminTenantFilterState.php based on actual table/filter responsibility after cleanup.
• T033 Rename, remove, or explicitly quarantine apps/platform/app/Support/Middleware/EnsureFilamentTenantSelected.php based on actual Environment context responsibility after cleanup.
• T034 Remove Workspace hub use of Filament::getTenant() or getTenant() as scope, fallback, query source, or shell context.
• T035 Remove Workspace hub use of lastTenantId, remembered Tenant state, or session Tenant state as data scope or Environment fallback.
• T036 Verify any remaining lastEnvironmentId behavior is switcher convenience only and cannot affect Workspace hub URLs, filters, queries, authorization, or shell context.

Phase 6: Route and Provider Boundary Cleanup

• T037 Inspect apps/platform/routes/web.php and remove or neutralize active /admin/t route assumptions where they remain product-facing.
• T038 Inspect apps/platform/app/Providers/Filament/AdminPanelProvider.php for Tenant page category, context, render hook, or navigation assumptions and rename/remove them.
• T039 Inspect apps/platform/app/Support/ManagedEnvironmentLinks.php and apps/platform/app/Support/Operations/OperationRunLinks.php for generated legacy Tenant query params or route helpers.
• T040 Inspect Provider Connections surfaces and preserve only provider-boundary Tenant labels such as Microsoft Tenant, Entra Tenant, and Provider Tenant ID.
• T041 Confirm provider external tenant identifiers are never used as Workspace hub environment_id substitutes.

Phase 7: Active UI Copy Cleanup

• T042 Update Workspace Overview active copy and links so Tenant wording is not used for Managed Environment context.
• T043 Update Environment Dashboard active copy, CTAs, and provider readiness snippets so Environment and Provider Tenant terms are distinct.
• T044 Update Operations active copy, chips, filters, and empty states where Tenant wording means Environment.
• T045 Update Governance Inbox, Decision Register, and Finding Exceptions Queue active copy where Tenant wording means Environment.
• T046 Update Provider Connections active copy so provider-boundary Tenant terminology is explicit and Environment filters use Environment wording.
• T047 Update Evidence, Reviews, Customer Reviews, Provider Readiness, and Required Permissions active copy where Tenant wording means Environment.

Phase 8: Docs and Current Spec Truth Cleanup

• T048 Update docs/product/spec-candidates.md current queue/follow-up wording so it reflects Workspace-first / Environment-second platform context and the selected Spec 317 numbering.
• T049 Update docs/product/roadmap.md only where current product truth or numbering notes conflict with Spec 317; leave strategic historical context intact when not current truth.
• T050 Update relevant current docs under docs/product, docs/ui, docs/architecture-guidelines.md, docs/filament-guidelines.md, and docs/testing-guidelines.md only where they describe Tenant as platform context.
• T051 Do not rewrite completed Specs 313-316 except for an explicit current-truth note if implementation proves they are used as current docs rather than history.
• T052 Document any intentionally quarantined legacy names in legacy-inventory.md with reason, risk, and follow-up.

Phase 9: Regression Safety

• T053 Re-run or update Spec 314 regression coverage proving sidebar/global Workspace hub entry remains clean and workspace-wide.
• T054 Re-run or update Spec 315 regression coverage proving Environment-owned CTAs use environment_id, visible chip renders when filtered, legacy params remain invalid, and cross-workspace IDs are rejected.
• T055 Re-run or update Spec 316 regression coverage proving clear removes URL/page/table/session state and does not restore stale Environment filters.
• T056 Confirm no globally searchable resource behavior changed; if a Resource is touched, verify it has Edit/View page or global search disabled.
• T057 Confirm no destructive action behavior changed; if a touched surface has destructive actions, verify ->action(...), ->requiresConfirmation(), authorization, and audit behavior remain intact.
• T058 Confirm no Graph calls, OperationRun lifecycle behavior, queue behavior, scheduler behavior, env var, storage, or asset registration changed.

Phase 10: Browser Verification

• T059 Start the local platform stack using Sail or the repo's platform dev command.
• T060 Resolve the absolute local app URL using Laravel Boost get_absolute_url.
• T061 Browser smoke Workspace Overview, Environment Dashboard, Operations, Governance Inbox, Decision Register, Finding Exceptions Queue, Provider Connections, Evidence, Reviews, Customer Reviews, Provider Readiness, and Required Permissions.
• T062 Verify active platform UI does not say Tenant when it means Environment.
• T063 Verify provider-specific details may still say Microsoft Tenant, Entra Tenant, or Provider Tenant ID only where provider-owned.
• T064 Verify sidebar/global clean entry still works and no old query params appear in generated links.
• T065 Verify Environment CTA filtered entry still uses environment_id.
• T066 Verify clear filter still returns to clean Workspace hub state.
• T067 Verify no /admin/t route appears in active navigation or generated links.
• T068 Save screenshots where useful under specs/317-legacy-tenant-environment-context-cleanup/artifacts/screenshots/.

Phase 11: Final Validation and Report

• T069 Run focused Spec 317 Pest guard/contract tests.
• T070 Run existing related Spec 314, Spec 315, and Spec 316 regression tests.
• T071 Run formatting/static checks expected by touched files, including Pint if PHP files changed.
• T072 Run git diff --check.
• T073 Prepare the final implementation report with changed behavior, legacy cleanup summary, provider-boundary Tenant usages kept, removed/renamed legacy platform usages, files changed, tests, browser verification, known issues, and Spec 318 follow-up.
• T074 Confirm the final report lists paths to legacy-inventory.md and tenant-usage-allowlist.md, renamed classes/helpers, removed query handlers, UI copy changes, docs/spec artifacts updated, and quarantined names with reasons.
• T075 Confirm the final report states no backwards compatibility layer was introduced, no legacy query alias support was preserved, and no provider-boundary Tenant concepts were incorrectly removed.

Explicit Non-Tasks

• NT001 Do not implement durable browser no-drift infrastructure; leave to Spec 318.
• NT002 Do not add compatibility redirects, dual-param support, alias readers, or adapter layers.
• NT003 Do not perform broad cosmetic database renames.
• NT004 Do not remove provider-boundary Microsoft/Entra/provider Tenant terminology.
• NT005 Do not add Environment CTA support to pages excluded from Specs 315/316.
• NT006 Do not rewrite completed historical specs or implementation close-out evidence.
• NT007 Do not create migrations, seeders, packages, env vars, queues, scheduler changes, storage changes, or asset registration unless a bounded implementation finding explicitly requires and documents the exception.

Dependencies

• T001-T005 block all runtime work.
• T006-T012 block cleanup edits.
• T013-T021 should be added before or alongside the corresponding cleanup changes.
• T022-T041 can proceed after inventory classifications are complete.
• T042-T052 can proceed after UI/docs inventory classification.
• T053-T058 run after code/test cleanup.
• T059-T068 run after local validation is green enough for browser smoke.
• T069-T075 close the implementation.

Suggested MVP Scope

Complete Phases 1-5 plus focused guards first. That proves the core hard-cut cleanup: inventory, allowlist, canonical environment_id, no helper aliases, and no Workspace hub Tenant fallback. UI/docs/browser phases then verify and close the visible product-truth layer.