TenantAtlas/specs/293-post-cutover-suite-stabilization/research.md

# Research: Post-Cutover Suite Stabilization & Baseline Reconciliation

## Pinned Failure-Classification Categories

`293` uses exactly these spec-local categories:

- `cutover-baseline-debt`
- `cutover-runtime-regression`
- `unrelated-existing-debt`
- `flaky-or-environment`
- `resolved-or-not-needed`

These categories are implementation-tracking vocabulary only. They do not become runtime product state.

## Pinned Stabilization Seams

`293` stabilizes exactly these seam families:

- `tenant_panel_baseline`
- `legacy_admin_t_routes`
- `workspace_aware_operations_routes`
- `legacy_required_permissions_provider_connections`
- `action_surface_rebaseline`

## Decision 1: Baseline and classification come before any fixes

- The package must start by running the initial full suite or the fallback lane split and recording the resulting groups in `failure-classification.md`.
- No test or runtime changes should land before those groups are classified.
- This keeps `293` bounded to cutover-driven debt instead of silently becoming a general suite cleanup.

## Decision 2: Retired TenantPanel and `/admin/t/...` assumptions are baseline debt, not compatibility gaps

- Treat lingering `panel: 'tenant'`, TenantPanel bootstrapping, and `/admin/t/...` management-path expectations as stale suite assumptions.
- The fix path is to align tests to current admin-panel and workspace-aware runtime truth or explicitly assert retirement.
- Do not restore TenantPanel or `/admin/t/...` compatibility behavior.

## Decision 3: Workspace-aware operations links should reuse current canonical helpers

- The expected post-cutover baseline for operations routes is workspace-aware link generation.
- Prefer `OperationRunLinks` and current shell helpers over raw route strings whenever repo truth already provides them.
- If a current primary-path helper is actually broken, classify the issue as `cutover-runtime-regression` before considering any minimal runtime fix during later implementation.

## Decision 4: Tenant-scoped required-permissions and provider-connection fallback URLs stay retired

- Tests must not treat tenant-scoped required-permissions URLs or tenant-scoped provider-connection URLs as current canonical runtime paths.
- The remediation path is to move expectations to the current canonical admin or workspace-aware route helpers.
- Reintroducing those fallbacks is forbidden.

## Decision 5: Action-surface rebaseline stays bounded to cutover drift

- `ActionSurfaceContractTest` and adjacent RBAC or Filament tests may be updated only where the expectation is stale because of workspace-first routing, managed-environment scope semantics, or TenantPanel removal.
- `293` must not add new actions, widen UX, or redesign surfaces merely to satisfy old tests.
- When a mismatch is not actually caused by the cutover, reclassify it as `unrelated-existing-debt` instead of absorbing it.

## Decision 6: Spec `288` proof pack and browser anchors remain non-negotiable regression guards

- The Spec `288` proof pack stays the enforcement baseline that `293` must keep green.
- The browser anchors `Spec281ProviderConnectionScopeSmokeTest` and `Spec285WorkspaceRbacEnvironmentAccessSmokeTest` remain the visible continuity proof.
- `293` can extend adjacent tests for stabilization, but it must not weaken or replace those proof surfaces.

## Decision 7: Remaining debt must stay explicit

- `failure-classification.md` is the single implementation artifact for recording what remains after cutover stabilization work.
- Each remaining group must stay categorized as `unrelated-existing-debt`, `flaky-or-environment`, or `resolved-or-not-needed` when it is not owned by the stabilization slice.
- Do not leave residual failures unclassified.

## Rejected Alternatives

### Rejected: split every failing group into separate micro-specs

That would scatter one cutover-stabilization thread across multiple tiny packages and keep the ownership boundary ambiguous.

### Rejected: restore compatibility behavior to make tests green faster

That would directly violate the cutover direction established by Specs `287` and `288`.

### Rejected: absorb all remaining full-suite failures into `293`

The package is meant to stabilize cutover-driven debt, not to become a permanent fix-all suite lane.

### Rejected: redesign action surfaces while rebaselining tests

That would widen `293` from stabilization into product work.

## Evidence Anchors

- `apps/platform/tests/Feature/Filament/PanelNavigationSegregationTest.php`
- `apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php`
- `apps/platform/tests/Feature/OpsUx/CanonicalViewRunLinksTest.php`
- `apps/platform/tests/Feature/OpsUx/OperateHubShellTest.php`
- `apps/platform/tests/Feature/OpsUx/FailureSanitizationTest.php`
- `apps/platform/tests/Feature/OpsUx/NonLeakageWorkspaceOperationsTest.php`
- `apps/platform/tests/Feature/OpsUx/TenantSyncBulkJobTest.php`
- `apps/platform/tests/Feature/ProviderConnections/TenantlessListRouteTest.php`
- `apps/platform/tests/Feature/ProviderConnections/TenantlessListScopingTest.php`
- `apps/platform/tests/Feature/Verification/*`
- `apps/platform/tests/Feature/Rbac/BackupItemsRelationManagerUiEnforcementTest.php`
- `apps/platform/tests/Feature/Rbac/ProviderConnectionWorkspaceFirstPolicyTest.php`
- `apps/platform/tests/Feature/Filament/ManagedEnvironmentAccessScopeManagementTest.php`
- `apps/platform/tests/Feature/ManagedEnvironment/LegacyTenantCoreGuardTest.php`
- `apps/platform/tests/Browser/Spec281ProviderConnectionScopeSmokeTest.php`
- `apps/platform/tests/Browser/Spec285WorkspaceRbacEnvironmentAccessSmokeTest.php`
- `apps/platform/app/Support/OperationRunLinks.php`
- `apps/platform/app/Support/OperateHub/OperateHubShell.php`
- `apps/platform/app/Filament/Concerns/WorkspaceScopedTenantRoutes.php`
- `apps/platform/app/Providers/Filament/AdminPanelProvider.php`
- `apps/platform/app/Filament/Pages/TenantDashboard.php`
- `apps/platform/app/Filament/Pages/TenantRequiredPermissions.php`
- `apps/platform/app/Filament/Resources/TenantResource.php`

## Boundary Summary

- `293` is a shared stabilization package, not a Package Execution or Guided Operations package.
- `289` remains untouched.
- `292` remains untouched.
- The package keeps existing canonical runtime truth and only allows minimal runtime fixes later if a current primary path is proven broken.