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

# Implementation Plan: Post-Cutover Suite Stabilization & Baseline Reconciliation

**Branch**: `293-post-cutover-suite-stabilization` | **Date**: 2026-05-10 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `specs/293-post-cutover-suite-stabilization/spec.md`

**Note**: This plan is produced from the repo's Spec Kit templates and stays preparation-only. It does not implement application code.

## Summary

Stabilize the test suite after Specs `287` and `288` by classifying failures first, then aligning stale panel, route, provider-link, required-permissions, operations-link, managed-environment role-authority, and action-surface expectations to current workspace-first runtime truth. The plan intentionally keeps Package Execution, Guided Operations, UI expansion, and broad refactors out of scope.

This package is an interstitial stabilization slice. It does not renumber or replace the future Package Execution follow-up that existing repo artifacts already reserve separately. It exists to keep cutover debt from drifting into those later packages.

## Inherited Baseline / Explicit Delta

### Inherited baseline

- Spec `287` completed the remaining route, provider-core, access-scope, and helper prerequisites for the cutover.
- Spec `288` introduced the no-legacy and quality-gate enforcement baseline and its proof pack.
- The current repo truth is admin-panel-first, workspace-first, environment-scoped where required, tenantless provider-connection canonical routing, and narrowing-only managed-environment memberships.
- `289` remains untouched by this package.
- `292` already exists and remains unrelated to this stabilization work.

### Explicit delta in this plan

- Add one stabilization artifact, `failure-classification.md`, to classify suite failures before any repair work.
- Rebaseline retired TenantPanel and `/admin/t/...` assumptions on existing tests and, only if proven necessary, the current canonical helper path.
- Rebaseline workspace-aware operations route generation in the in-scope OpsUx and action-surface test families.
- Rebaseline tenant-scoped required-permissions and provider-connection legacy expectations to the current canonical surfaces.
- Rebaseline bounded action-surface expectations that are stale only because of the cutover.
- Keep the Spec `288` proof pack and current browser anchors green while documenting any unrelated debt that remains.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12.52  
**Primary Dependencies**: Pest 4, Filament 5.2.1, Livewire 4.1.4, current OpsUx helpers, current provider/verification helpers, current browser smoke suite  
**Storage**: no new application persistence; one spec-local `failure-classification.md` artifact for implementation tracking only  
**Testing**: targeted Pest feature/browser reruns, broader lane or full-suite reruns for classification and confidence, formatting  
**Validation Lanes**: confidence, heavy-governance, browser, and initial/final full-suite baseline when usable
**Target Platform**: Laravel monolith in `apps/platform`  
**Project Type**: web application  
**Performance Goals**: keep stabilization work bounded to cutover-driven debt and avoid turning the package into an open-ended full-suite repair program  
**Constraints**: no Package Execution work, no Guided Operations work, no UI expansion, no broad refactors, no TenantPanel or `/admin/t/...` reactivation, and no compatibility-route restoration  
**Scale/Scope**: one cross-cutting stabilization slice covering existing panel, OpsUx, provider, verification, RBAC, and browser proof seams

## Pinned Stabilization Seams

- `tenant_panel_baseline`: stale TenantPanel or `panel: 'tenant'` assumptions in the suite baseline
- `legacy_admin_t_routes`: stale `/admin/t/...` management-route assumptions
- `workspace_aware_operations_routes`: operations links or helpers missing workspace context
- `legacy_required_permissions_provider_connections`: tenant-scoped required-permissions or provider-connection legacy expectations
- `action_surface_rebaseline`: stale action-surface expectations caused by the cutover

## Likely Affected Repo Surfaces

- `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`
- `apps/platform/tests/Pest.php`

## Filament v5 / Surface Notes

- **Livewire v4.0+ compliance**: all touched runtime seams remain on Filament v5 with Livewire v4.
- **Provider registration location**: provider registration remains in `apps/platform/bootstrap/providers.php`; `293` does not add or move a panel provider.
- **Global search rule**: no new globally-searchable resource is introduced, and `293` does not broaden any existing global search surface.
- **Destructive actions**: no new destructive action is planned. Any later runtime correction must preserve current confirmation and authorization behavior.
- **Asset strategy**: no asset registration or deployment-step change is planned. Existing `php artisan filament:assets` expectations remain unchanged because this package adds no assets.

## Stabilization Fit

- Classify failures before editing tests or helpers.
- Prefer fixing stale expectations over restoring compatibility behavior.
- Prefer current canonical helpers over raw route strings whenever repo truth already provides them.
- Allow minimal runtime fixes only when a current workspace-first primary path is demonstrably broken.
- Keep unrelated, flaky, or no-longer-needed failures explicit in `failure-classification.md`.

## UI / Surface Guardrail Plan

- **Guardrail scope**: existing provider, required-permissions, navigation, action-surface, and OpsUx shell surfaces only; no new operator-facing surface is planned
- **Native vs custom classification summary**: native Filament and existing shared shell/helpers only
- **Shared-family relevance**: route generation, action surfaces, workspace-first access semantics, and browser anchors
- **State layers in scope**: existing routes, shared URL helpers, page access surfaces, and browser-visible continuity only
- **Audience modes in scope**: maintainers and reviewers first; operator-facing behavior changes are only incidental to proven regressions
- **Decision/diagnostic/raw hierarchy plan**: unchanged runtime disclosure; the package validates current truth instead of redesigning it
- **Raw/support gating plan**: unchanged
- **One-primary-action / duplicate-truth control**: no new action family is introduced
- **Handling modes by drift class or surface**: cutover debt is implementation-required; unrelated or flaky debt is report-only in `failure-classification.md`
- **Repository-signal treatment**: review-mandatory for any runtime fix boundary crossing
- **Special surface test profiles**: `standard-native-filament`, `global-context-shell`, `browser-smoke`
- **Required tests or manual smoke**: targeted feature/core reruns plus the two named browser anchors
- **Exception path and spread control**: any runtime fix must stay on existing canonical helpers and may not restore compatibility behavior
- **Active feature PR close-out entry**: `SuiteStabilization`

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes
- **Systems touched**: panel navigation, action-surface contracts, OpsUx canonical links, provider and verification route expectations, RBAC proof surfaces, and the existing browser anchors
- **Shared abstractions reused**: `OperationRunLinks`, `OperateHubShell`, `WorkspaceScopedTenantRoutes`, existing provider or required-permissions helpers, existing browser anchors, and current RBAC proof seams
- **New abstraction introduced? why?**: none
- **Why the existing abstraction was sufficient or insufficient**: the abstractions already describe the desired runtime truth; they only need stale test assumptions removed and minimal helper corrections if a real regression is proven.
- **Bounded deviation / spread control**: runtime deviations are allowed only as minimal canonical fixes, never as compatibility restoration

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: yes, but only around canonical route generation for operations index and run detail links
- **Central contract reused**: `OperationRunLinks`
- **Delegated UX behaviors**: preserve current canonical operations index and run detail links; no new queued toast, browser event, or notification behavior is introduced
- **Surface-owned behavior kept local**: existing page-level assertions only
- **Queued DB-notification policy**: unchanged
- **Terminal notification path**: unchanged
- **Exception path**: none

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: yes
- **Provider-owned seams**: provider-specific nested detail remains bounded to existing provider-owned surfaces only
- **Platform-core seams**: canonical route builders, workspace-aware operations links, and current access semantics
- **Neutral platform terms / contracts preserved**: `workspace`, `managed environment`, `provider connection`, `operation run`, `required permissions`
- **Retained provider-specific semantics and why**: only provider-owned nested detail remains provider-specific; `293` does not deepen provider coupling
- **Bounded extraction or follow-up path**: Package Execution and later guided flows remain separate; `293` only stabilizes suite debt first

## Constitution Check

*GATE: Must pass before implementation begins and again after the design artifacts are complete.*

- `Inventory-first, Snapshots-second`: PASS. `293` introduces no new inventory or snapshot runtime truth.
- `Read/Write Separation by Default`: PASS. The package is stabilization-only and any later runtime fix must stay minimal, explicit, and within current primary-path truth.
- `Single Contract Path to Graph`: PASS by preservation. No new Graph integration seam is introduced.
- `Deterministic Capabilities`: PASS by preservation. Capability derivation and role authority do not change.
- `PROP-001`, `ABSTR-001`, `V1-EXP-001`, and `LAYER-001`: PASS. The package reuses existing tests, helpers, and canonical route seams instead of introducing a new stabilization layer or abstraction family.
- `PROV-001`: PASS. The work removes stale tenant-first assumptions while preserving neutral platform-core route and helper vocabulary.
- `PERSIST-001` and `STATE-001`: PASS. `failure-classification.md` is spec-local preparation truth only and does not become runtime persistence or product state.
- `XCUT-001`: PASS. Existing shared paths such as `OperationRunLinks`, `OperateHubShell`, `WorkspaceScopedTenantRoutes`, and current browser anchors are reused.
- `TEST-TRUTH-001` and `TEST-GOV-001`: PASS. The plan keeps proof explicit, classified, and bounded to existing feature, browser, lane, and proof-pack surfaces.
- `BLOAT-001`: PASS. The proportionality review covers the only new artifact-level taxonomy introduced by `293`.
- `LEAN-001`: PASS. The package explicitly forbids legacy compatibility restoration, TenantPanel reactivation, and fallback-route revival.

**Gate evaluation**: PASS.

**Post-design re-check**: PASS while the same failure-classification categories, canonical proof commands, and out-of-scope boundary remain aligned across `spec.md`, `plan.md`, `tasks.md`, `research.md`, `data-model.md`, `quickstart.md`, `checklists/requirements.md`, and `failure-classification.md`.

## Test Governance Check

- **Test purpose / classification by changed surface**: Feature, Browser, Heavy-Governance
- **Affected validation lanes**: confidence, heavy-governance, browser, and initial or final full-suite baseline when usable
- **Why this lane mix is the narrowest sufficient proof**: the package must classify failures first, repair only cutover-related debt, keep the existing enforcement proof pack green, and prove that browser-visible canonical flows still work.
- **Narrowest proving command(s)**:
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && git status --short --branch`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && git diff --stat`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && (cd apps/platform && ./vendor/bin/sail artisan test --compact)`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && ./scripts/platform-test-lane heavy-governance`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && ./scripts/platform-test-lane confidence`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && (cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/PanelNavigationSegregationTest.php tests/Feature/ManagedEnvironment/LegacyTenantCoreGuardTest.php)`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && (cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/OpsUx/CanonicalViewRunLinksTest.php tests/Feature/OpsUx/OperateHubShellTest.php tests/Feature/OpsUx/FailureSanitizationTest.php tests/Feature/OpsUx/NonLeakageWorkspaceOperationsTest.php)`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && (cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections tests/Feature/Verification)`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && (cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php tests/Feature/Rbac/ProviderConnectionWorkspaceFirstPolicyTest.php tests/Feature/Filament/ManagedEnvironmentAccessScopeManagementTest.php tests/Feature/Rbac/BackupItemsRelationManagerUiEnforcementTest.php)`
  - `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/Guards/Spec288NoLegacyRouteAndHelperGuardTest.php tests/Feature/Guards/Spec288ProviderCoreAndRoleAuthorityGuardTest.php tests/Feature/Guards/AdminWorkspaceRoutesGuardTest.php tests/Feature/Guards/ProviderBoundaryPlatformCoreGuardTest.php tests/Feature/ProviderConnections/LegacyRedirectTest.php tests/Feature/ManagedEnvironment/LegacyTenantCoreGuardTest.php tests/Feature/Spec080WorkspaceManagedTenantAdminMigrationTest.php tests/Feature/Rbac/ProviderConnectionWorkspaceFirstPolicyTest.php tests/Feature/Filament/ManagedEnvironmentAccessScopeManagementTest.php tests/Feature/Guards/BrowserLaneIsolationTest.php tests/Feature/Guards/CiLaneFailureClassificationContractTest.php tests/Feature/Guards/CiHeavyBrowserWorkflowContractTest.php tests/Unit/Auth/NoRoleStringChecksTest.php)`
  - `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)`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && (cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent)`
- **Fixture / helper / factory / seed / context cost risks**: moderate only because the package reuses broad existing suites and browser anchors; it must not add new expensive defaults.
- **Expensive defaults or shared helper growth introduced?**: no; the package should shrink stale assumptions, not widen helper cost.
- **Heavy-family additions, promotions, or visibility changes**: none new; only reuse of existing heavy-governance and confidence lanes
- **Surface-class relief / special coverage rule**: `standard-native-filament`, `global-context-shell`, and current browser anchors remain sufficient
- **Closing validation and reviewer handoff**: reviewers must re-run the exact commands above, confirm the Spec `288` proof pack and browser anchors stay green, and verify that remaining failures are classified rather than silently ignored.
- **Budget / baseline / trend follow-up**: limited to explicit failure classification; no new permanent lane or suite family is created.
- **Review-stop questions**: did the work restore legacy runtime behavior, turn into a feature redesign, or absorb unrelated debt without classification?
- **Escalation path**: `document-in-feature` for explicit debt classification, `reject-or-split` for scope expansion
- **Active feature PR close-out entry**: `SuiteStabilization`
- **Why no dedicated follow-up spec is needed**: `293` itself is the dedicated stabilization slice; later feature packages should not absorb this debt again.

## Review Checklist Status

- **Review checklist artifact**: `checklists/requirements.md`
- **Review outcome class**: `acceptable-special-case`
- **Workflow outcome**: `keep`
- **Test-governance outcome**: `keep`
- **Resolution note**: the package is implementation-ready as one shared stabilization slice following Specs `287` and `288`
- **Escalation rule**: if implementation starts restoring legacy behavior or absorbing Package Execution, Guided Operations, or unrelated debt without classification, stop and split the work out of `293`

## Rollout Considerations

- Record the initial baseline and failure-classification artifact before any fixes.
- Land panel and `/admin/t/...` baseline cleanup before broader action-surface adjustments so the visible runtime truth is pinned first.
- Stabilize workspace-aware operations links before final action-surface and browser reruns, because those helpers feed multiple suites.
- Keep Spec `288` proof-pack reruns and browser anchors as explicit midstream and final checkpoints.
- Treat full-suite or lane reruns as classification and confidence proof, not as license for unlimited unrelated repair.

## Risk Controls

- Reject any implementation that restores TenantPanel bootstrapping or `/admin/t/...` compatibility behavior.
- Reject any implementation that fixes tests by hardcoding legacy route shapes instead of using current canonical helpers or explicit workspace parameters.
- Reject any implementation that adds new actions or redesigns action surfaces merely to satisfy pre-cutover assertions.
- Reject any implementation that changes Package Execution or Guided Operations scope under the label of stabilization.
- Reject any implementation that leaves remaining unrelated or flaky failures undocumented.

## Research & Design Outputs

- `research.md` records the stabilization-first decisions, rejected alternatives, and evidence anchors.
- `data-model.md` captures the spec-local failure-classification categories, stabilization seam inventory, and invariants.
- `quickstart.md` gives reviewers the read order, review scenarios, exact proof commands, and stop conditions.
- `failure-classification.md` is the planned implementation artifact used to record baseline findings and remaining debt.
- `checklists/requirements.md` records the readiness and bounded-scope checks for the package.

## Project Structure

### Documentation (this feature)

```text
specs/293-post-cutover-suite-stabilization/
├── checklists/
│   └── requirements.md
├── data-model.md
├── failure-classification.md
├── plan.md
├── quickstart.md
├── research.md
├── spec.md
└── tasks.md
```

### Source Code (repository root)

```text
apps/platform/
├── app/
├── routes/
└── tests/
    ├── Browser/
    ├── Feature/
    ├── Support/
    └── Unit/

scripts/
├── platform-test-lane
└── platform-test-report
```

**Structure Decision**: keep the package within the existing Laravel app and test structure. Reuse the current tests, support helpers, canonical route helpers, and lane scripts instead of introducing a new stabilization subsystem.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|---|---|---|
| Spec-local failure-classification category set | The package needs an explicit, bounded way to distinguish cutover debt from unrelated or flaky failures | Ad hoc notes would hide scope drift and make later stabilization work ambiguous |

## Proportionality Review

- **Current operator problem**: without an explicit failure-classification artifact and category set, maintainers cannot tell which failures are still owned by the `287` and `288` cutover and which ones should stay out of scope.
- **Existing structure is insufficient because**: scattered notes in tasks, PR comments, or terminal output would not preserve a single auditable baseline for later implementation and review.
- **Narrowest correct implementation**: one spec-local markdown artifact plus five pinned categories and five pinned seam keys is enough to keep the stabilization work bounded without introducing runtime semantics.
- **Ownership cost created**: one additional markdown file and one small alignment burden across the `293` artifacts.
- **Alternative intentionally rejected**: ad hoc notes embedded only in tasks or execution logs, because they are easy to drift, hard to review, and poor at preventing scope creep.
- **Release truth**: current-release preparation truth only; this is not new runtime product state.