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

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)

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.