# Quickstart: Cutover Prerequisite Completion

## Purpose

Use this guide to review or implement Feature `287` as the bounded runtime and test-harness completion slice that unblocks Spec `288`.

## Preconditions

- The package stays limited to the five named prerequisite areas:
  - provider connection legacy route retirement
  - provider target scope core neutralization
  - environment scope role persistence cleanup
  - tenant panel test helper cutover
  - targeted validation for the changed seams
- Spec `288` is treated as the follow-up package for quality gates and no-legacy enforcement.
- The implementation does not add a global guard suite, a full-suite baseline, package execution, guided operations, UI copy cleanup, or provider capability expansion.
- Filament remains v5 on Livewire v4 and provider registration remains in `apps/platform/bootstrap/providers.php`.

## Read Order

1. `spec.md`
2. `plan.md`
3. `research.md`
4. `data-model.md`
5. `contracts/cutover-prerequisite-completion.logical.openapi.yaml`
6. `tasks.md`
7. `checklists/requirements.md`

## Implementation Intent

- retire the remaining legacy provider-connection route family instead of guarding it
- finish provider target-scope and identity neutralization on the shared provider-core seams
- complete the cleanup that keeps workspace membership role-bearing and environment scope narrowing-only
- replace tenant-panel-era test helpers with post-cutover admin or workspace helpers and update `apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php` plus `apps/platform/tests/Feature/Rbac/TriageReviewStateAuthorizationTest.php`
- keep validation targeted to the changed seams only and leave quality gates to Spec `288`

## Review Scenarios

### Scenario 1: Canonical provider-connection routing is the only runtime path

- open canonical provider-connection paths and the launch-point inventory in `apps/platform/app/Providers/Filament/AdminPanelProvider.php`, `apps/platform/app/Filament/Resources/TenantResource.php`, `apps/platform/app/Filament/Pages/TenantRequiredPermissions.php`, `apps/platform/app/Support/OperationRunLinks.php`, `apps/platform/app/Support/Providers/ProviderReasonTranslator.php`, and `apps/platform/app/Support/Verification/VerificationLinkBehavior.php`
- confirm they resolve through `/admin/provider-connections...`
- confirm the retired legacy alias family no longer acts as accepted runtime fallback

### Scenario 2: Shared provider target-scope truth is neutral

- exercise the target-scope descriptor, provider identity resolution path, and provider-backed run or start context
- confirm the shared contract no longer depends on Microsoft-only keys such as `entra_tenant_id`, `tenantContext`, or `target_scope.entra_tenant_id`
- confirm provider-owned Microsoft detail remains nested where current consent or diagnostics still need it

### Scenario 3: Workspace membership remains the only role-bearing truth

- create workspace membership plus managed-environment access-scope combinations
- confirm workspace membership still owns role authority
- confirm environment scope only narrows visibility and does not behave like a second role matrix

### Scenario 4: The shared test harness no longer boots the retired tenant panel

- replace `setTenantPanelContext()` on the shared helper path, `apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php`, and `apps/platform/tests/Feature/Rbac/TriageReviewStateAuthorizationTest.php`
- rerun the targeted seam tests and browser validation
- confirm the changed seams no longer require tenant-panel-only test state

## Planned Validation Commands

```bash
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)
```

```bash
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)
```

```bash
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)
```

## Explicit Stop Conditions

- If implementation starts adding no-legacy guard families or quality gates, stop and move that work to Spec `288`.
- If implementation starts requiring a full-suite baseline to prove the slice, stop and narrow the seam inventory.
- If implementation widens into UI copy cleanup, package execution, guided operations, or provider capability expansion, stop and split the extra work out of `287`.