TenantAtlas/specs/287-cutover-prerequisite-completion/tasks.md

description
Task list for Cutover Prerequisite Completion

Tasks: Cutover Prerequisite Completion

Input: Design documents from /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/287-cutover-prerequisite-completion/
Prerequisites: /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/287-cutover-prerequisite-completion/plan.md (required), /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/287-cutover-prerequisite-completion/spec.md (required), /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/287-cutover-prerequisite-completion/checklists/requirements.md (required), /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/287-cutover-prerequisite-completion/research.md, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/287-cutover-prerequisite-completion/data-model.md, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/287-cutover-prerequisite-completion/contracts/cutover-prerequisite-completion.logical.openapi.yaml, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/287-cutover-prerequisite-completion/quickstart.md

Review Artifact: /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/287-cutover-prerequisite-completion/checklists/requirements.md is the outcome-of-record for the review outcome class, workflow outcome, and test-governance outcome. If implementation expands into no-legacy guards, full-suite baselines, or adjacent feature work, update that artifact before continuing and stop when the work no longer fits 287.

Tests: Required (Pest) for runtime and helper changes. Keep proof bounded to targeted Feature tests plus targeted Browser validation because this package completes prerequisite seams only.
Operations: No new OperationRun, queue family, remote workflow, or notification policy is introduced. 287 only completes the existing provider-backed run context and canonical route truth.
RBAC: Reuse the workspace-first access contract from Spec 285; do not add a new role family, raw capability strings, or a second access overlay product.
Shared Pattern Reuse: Reuse /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/routes/web.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Providers/TargetScope/ProviderConnectionTargetScopeNormalizer.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Providers/TargetScope/ProviderConnectionTargetScopeDescriptor.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Providers/ProviderIdentityResolver.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Providers/ProviderIdentityResolution.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Providers/PlatformProviderIdentityResolver.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Providers/ProviderOperationStartGate.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Auth/TenantMembershipManager.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Auth/ManagedEnvironmentAccessScopeResolver.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Pest.php, and the targeted feature/browser tests named below. Do not introduce a new guard subsystem or a full-suite wrapper under this spec.
Filament / Panel Guardrails: Filament remains v5 on Livewire v4. Provider registration remains unchanged in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/bootstrap/providers.php. No new panel, no new globally-searchable resource, and no asset-strategy change are allowed in this slice.
Organization: Tasks are grouped by the four runtime/test-harness prerequisite areas so route retirement, provider-core neutralization, access persistence cleanup, and helper cutover remain independently reviewable.
Review Outcome: acceptable-special-case
Workflow Outcome: keep
Test-governance Outcome: keep

Test Governance Checklist

• Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
• New or changed tests stay in targeted feature or browser coverage and do not become a guard family.
• Shared helpers, fixtures, and context bootstrapping stay explicit and cheap by default.
• Planned validation commands cover the changed seams without becoming a full-suite baseline.
• Surface test profile stays explicit: standard-native-filament and global-context-shell.
• The active package records that Spec 288 owns quality gates and no-legacy enforcement after this slice lands.

Phase 1: Setup (Shared Context)

Purpose: Lock the bounded prerequisite-completion role, exact seam inventory, and targeted validation scope before runtime edits begin.

• T001 Review /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/287-cutover-prerequisite-completion/spec.md, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/287-cutover-prerequisite-completion/plan.md, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/287-cutover-prerequisite-completion/checklists/requirements.md to confirm the package stays on prerequisite completion only
• T002 [P] Review /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/287-cutover-prerequisite-completion/research.md, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/287-cutover-prerequisite-completion/data-model.md, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/287-cutover-prerequisite-completion/contracts/cutover-prerequisite-completion.logical.openapi.yaml to confirm the same seam categories, canonical replacements, and follow-up boundary to Spec 288 are pinned everywhere
• T003 [P] Confirm the focused Sail/Pest validation commands in /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/287-cutover-prerequisite-completion/quickstart.md and the current apps/platform/tests/Feature/ProviderConnections/, apps/platform/tests/Feature/Auth/, apps/platform/tests/Feature/Rbac/, and apps/platform/tests/Browser/ directories

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Fix the exact completion inventory before user-story work begins and keep Spec 288 explicitly out of scope.

Critical: No user-story work should begin until this phase is complete.

• T004 Audit the exact provider-connection legacy route seams across /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/routes/web.php and the current launch-point inventory in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Providers/Filament/AdminPanelProvider.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/TenantResource.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/TenantRequiredPermissions.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/OperationRunLinks.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Providers/ProviderReasonTranslator.php, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Verification/VerificationLinkBehavior.php so 287 retires only repo-real fallback paths
• T005 [P] Audit the provider target-scope core seams across /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Providers/ProviderConnectionResolver.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Providers/ProviderIdentityResolver.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Providers/ProviderIdentityResolution.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Providers/PlatformProviderIdentityResolver.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Providers/ProviderOperationStartGate.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Providers/TargetScope/ProviderConnectionTargetScopeNormalizer.php, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Providers/TargetScope/ProviderConnectionTargetScopeDescriptor.php
• T006 [P] Audit the environment-scope role persistence and tenant-panel test-helper seams across /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Auth/TenantMembershipManager.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Auth/ManagedEnvironmentAccessScopeResolver.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Pest.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Rbac/TriageReviewStateAuthorizationTest.php
• T007 Confirm the scope boundary to Spec 288 remains explicit in the artifact package and that no guard-suite, full-suite, UI copy, package execution, guided operations, or provider-capability work is added here

Checkpoint: the runtime seam inventory and validation boundary are fixed before story work begins.

---

Phase 3: User Story 1 - Retire provider-connection legacy routes (Priority: P1)

Goal: Make canonical provider-connection routing the only accepted runtime path.

Independent Test: hit the canonical provider-connection route family, retire the legacy alias family, and prove the launch-point inventory in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Providers/Filament/AdminPanelProvider.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/TenantResource.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/TenantRequiredPermissions.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/OperationRunLinks.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Providers/ProviderReasonTranslator.php, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Verification/VerificationLinkBehavior.php resolves only through the canonical path.

Tests for User Story 1

• T008 [P] [US1] Extend /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/ProviderConnections/LegacyRedirectTest.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/ProviderConnections/TenantlessListRouteTest.php, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/ProviderConnections/TenantlessListScopingTest.php so the canonical provider-connection route family is explicit

Implementation for User Story 1

• T009 [US1] Remove the remaining legacy provider-connection route family from /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/routes/web.php
• T010 [US1] Update the provider-connection launch-point builders in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Providers/Filament/AdminPanelProvider.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/TenantResource.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/TenantRequiredPermissions.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/OperationRunLinks.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Providers/ProviderReasonTranslator.php, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Verification/VerificationLinkBehavior.php so they resolve through the canonical admin route family only

Checkpoint: User Story 1 is independently functional when legacy provider-connection aliases are gone and canonical routes are the only runtime path.

---

Phase 4: User Story 2 - Neutralize provider target-scope core seams (Priority: P1)

Goal: Keep the shared provider-core contract provider-neutral while leaving Microsoft detail nested under provider-owned seams.

Independent Test: exercise the provider target-scope descriptor, shared provider identity path, and shared provider-backed run context without depending on Microsoft-only shared keys.

Tests for User Story 2

• T011 [P] [US2] Add or extend targeted provider-connection and provider-core tests under /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/ProviderConnections/ so shared target-scope and identity outputs stop depending on Microsoft-only core keys

Implementation for User Story 2

• T012 [US2] Complete target-scope neutralization in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Providers/TargetScope/ProviderConnectionTargetScopeNormalizer.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Providers/TargetScope/ProviderConnectionTargetScopeDescriptor.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Providers/ProviderConnectionResolver.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Providers/ProviderIdentityResolver.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Providers/ProviderIdentityResolution.php, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Providers/PlatformProviderIdentityResolver.php
• T013 [US2] Update /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Providers/ProviderOperationStartGate.php and any directly affected shared provider context payloads so provider-backed run context uses the completed neutral contract while preserving provider-owned nested detail where needed

Checkpoint: User Story 2 is independently functional when shared provider target-scope and identity seams no longer depend on Microsoft-only core truth.

---

Phase 5: User Story 3 - Clean environment-scope role persistence (Priority: P1)

Goal: Make workspace membership the only role-bearing truth and keep environment scope narrowing-only on the completed seams.

Independent Test: create workspace membership plus managed-environment scope combinations and prove authorization still derives role authority from workspace membership while environment scope narrows visibility only.

Tests for User Story 3

• T014 [P] [US3] Extend /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Auth/WorkspaceFirstManagedEnvironmentAccessTest.php and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Rbac/ProviderConnectionWorkspaceFirstPolicyTest.php so copied role-bearing environment-scope persistence is no longer accepted on the changed seams

Implementation for User Story 3

• T015 [US3] Complete the narrowing-only access-scope cleanup in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Auth/TenantMembershipManager.php and any directly affected access-scope resolver seam so workspace role truth is no longer mirrored as environment-scope role persistence

Checkpoint: User Story 3 is independently functional when workspace membership remains role-bearing and environment scope only narrows access on the completed seams.

---

Phase 6: User Story 4 - Cut over tenant-panel test helpers (Priority: P2)

Goal: Remove the retired tenant-panel helper dependency from the shared test harness and the in-slice proof-command consumer tests.

Independent Test: replace setTenantPanelContext() on the shared helper path, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Rbac/TriageReviewStateAuthorizationTest.php, then rerun the targeted seam validation without the retired panel context.

Critical order: complete T017 before T016. T016 is parallelizable only across the listed consumer files once the replacement helper exists.

Tests for User Story 4

• T016 [P] [US4] After T017 introduces the replacement helper, update /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Rbac/TriageReviewStateAuthorizationTest.php to prove the changed seams no longer require setTenantPanelContext()

Implementation for User Story 4

• T017 [US4] Replace the shared tenant-panel helper path in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Pest.php with a post-cutover admin or workspace context helper suitable for the changed seams

Checkpoint: User Story 4 is independently functional when the named targeted seam tests run without the retired tenant-panel helper.

---

Phase 7: Polish & Cross-Cutting Validation

Purpose: Run the canonical targeted proof commands, format touched files, and keep Spec 288 as the explicit follow-up.

• T018 Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/LegacyRedirectTest.php tests/Feature/ProviderConnections/TenantlessListRouteTest.php tests/Feature/ProviderConnections/TenantlessListScopingTest.php tests/Feature/Auth/WorkspaceFirstManagedEnvironmentAccessTest.php tests/Feature/Rbac/ProviderConnectionWorkspaceFirstPolicyTest.php tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php tests/Feature/Rbac/TriageReviewStateAuthorizationTest.php) exactly as recorded in spec.md, plan.md, and quickstart.md
• T019 Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Browser/Spec281ProviderConnectionScopeSmokeTest.php tests/Browser/Spec285WorkspaceRbacEnvironmentAccessSmokeTest.php) exactly as recorded in spec.md, plan.md, and quickstart.md
• T020 Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail bin pint --dirty --format agent)
• T021 Review the touched runtime seams, helper updates, and the review artifact to confirm Filament remains on Livewire v4, provider registration still lives in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/bootstrap/providers.php, no asset registration or deployment-step drift was introduced, no guard suite, full-suite baseline, UI copy cleanup, package execution, guided operations, or provider capability expansion was absorbed, and Spec 288 remains the explicit follow-up

---

Dependencies & Execution Order

Phase Dependencies

• Phase 1 (Setup): no dependencies; start immediately.
• Phase 2 (Foundational): depends on Phase 1 and blocks all user-story work until the seam inventory and scope boundary are settled.
• Phase 3 (US1): depends on Phase 2 and delivers the first independent prerequisite slice.
• Phase 4 (US2): depends on Phase 2 and should follow US1 because provider route truth should settle before provider-core target-scope cleanup is validated through those surfaces.
• Phase 5 (US3): depends on Phase 2 and should follow US2 because access persistence cleanup should consume the final provider-core and route baseline.
• Phase 6 (US4): depends on Phases 3 through 5 and should follow them because the helper cutover must reflect the completed runtime seams.
• Phase 7 (Polish): depends on all implemented stories.

User Story Dependencies

• US1 (P1): first independently testable increment once the seam inventory is settled.
• US2 (P1): independently testable after Phase 2, but safer after US1 because provider summaries and launch points should already use the canonical route family.
• US3 (P1): independently testable after Phase 2, but should merge after US2 because access persistence should validate against the completed provider-core truth.
• US4 (P2): independently testable after Phase 2, but should merge after US1-US3 because the helper cutover must support the final runtime baseline rather than a moving target.

Within Each User Story

• Extend or add the targeted tests first and make the current drift visible, unless the story defines an explicit helper-prerequisite step such as US4's T017 before T016.
• Complete the minimum runtime seam needed for that story.
• Re-run the narrowest relevant validation command after each story checkpoint before moving on.

---

Parallel Execution Examples

Phase 1

• T002 and T003 can run in parallel after T001 confirms the bounded package role.

Phase 2

• T004, T005, and T006 can run in parallel because they inspect different seam families.

User Story 1

• T008 can run while T009 and T010 are being prepared, but the runtime route cleanup should land as one coherent slice.

User Story 2

• T011 can run in parallel with the seam audit, but T012 and T013 should land together because they define one shared provider-core contract.

User Story 4

• T016 can run in parallel across /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Rbac/TriageReviewStateAuthorizationTest.php once T017 has defined the replacement helper path.

---

Implementation Strategy

Suggested MVP Scope

• MVP = Phase 2 + US1. The package starts delivering value once the legacy provider-connection route family is retired and the canonical path becomes real runtime truth.

Incremental Delivery

1. Complete Phase 1 and Phase 2.
2. Deliver US1 and validate canonical route retirement.
3. Deliver US2 and validate provider target-scope core neutralization.
4. Deliver US3 and validate environment-scope persistence cleanup.
5. Deliver US4 and validate the helper cutover.
6. Finish with Phase 7 targeted validation, formatting, and scope review.

Team Strategy

1. Keep Spec 288 explicitly out of implementation commits for this slice.
2. Land provider route and provider-core cleanup before helper migration so the test-support change reflects final runtime truth.
3. Serialize merges around routes/web.php, provider-core services, and tests/Pest.php because those are likely conflict hotspots.

---

Explicit Follow-Ups / Out of Scope

• no-legacy guard suite and quality gates, which move to Spec 288
• any full-suite baseline or budget recalibration work
• package execution or guided operations
• UI copy cleanup from Spec 286
• provider capability expansion from Spec 283
• broader repo-wide setTenantPanelContext() migration beyond /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Rbac/TriageReviewStateAuthorizationTest.php