TenantAtlas/specs/288-quality-gates-no-legacy-enforcement/plan.md

Implementation Plan: Quality Gates / No-Legacy Enforcement

Branch: 288-quality-gates-no-legacy-enforcement | Date: 2026-05-10 | Spec: spec.md Input: Feature specification from specs/288-quality-gates-no-legacy-enforcement/spec.md

Summary

Add the cutover enforcement layer that follows Spec 287 without reopening runtime work. The narrow implementation path adds bounded no-legacy and route-emission guards, forbids retired tenant-panel helper bootstrapping on owned seams, reinforces provider-core and role-authority boundaries, keeps targeted browser smoke proof on the current canonical admin/workspace surfaces, and documents that broader baseline fallout is classified only through existing lane/report seams instead of repaired under this spec.

This plan is intentionally not a runtime cutover package and not a Package Execution package. Filament remains v5 on Livewire v4, provider registration remains in apps/platform/bootstrap/providers.php, no new asset or deployment step is introduced, no new globally-searchable resource is created, no destructive-action contract changes are planned, and Spec 289 remains the explicit follow-up for Package Execution Contract work.

Inherited Baseline / Explicit Delta

Inherited baseline

• Spec 279 established the managed-environment core cutover and remains historical context only.
• Spec 280 established workspace-first routing and route-family cleanup patterns.
• Spec 281 established provider-boundary groundwork and the current provider-connection browser smoke anchor.
• Spec 282 retargeted governance artifact surfaces and remains adjacent history only.
• Spec 285 established the workspace-role and environment-scope authority direction and the current RBAC browser smoke anchor.
• Spec 286 owns UI copy cleanup and remains explicitly out of scope here.
• Spec 287 completed the remaining runtime and helper prerequisites and explicitly handed quality gates and no-legacy enforcement to this spec.

Explicit delta in this plan

• Add one bounded guard pack for retired route/path families and retired tenant-panel helper patterns.
• Add one bounded guard pack for provider-core forbidden seams and environment-scope role-authority regressions.
• Extend the existing Spec 281 and Spec 285 browser smokes so the guard pack keeps visible canonical route continuity honest.
• Document the quality-gate contract and the rule that broader baseline/full-suite fallout is classified only, not repaired, under this spec.
• Keep Package Execution Contract explicitly deferred to Spec 289.

Technical Context

Language/Version: PHP 8.4.15, Laravel 12.52
Primary Dependencies: Pest 4, Filament 5.2.1, Livewire 4.1.4, existing guard-test seams, TestLaneManifest, TestLaneReport, and the current browser smoke suite
Storage: no new persistence; this package updates tests, contributor-facing documentation, and lane/report classification seams only
Testing: targeted Pest feature/unit guards, targeted browser validation, and formatting
Validation Lanes: heavy-governance, browser
Target Platform: Laravel monolith in apps/platform
Project Type: web application
Performance Goals: keep proof bounded to the named guard and browser files; no full-suite rerun or repair program
Constraints: no runtime cutover rewrites, no provider-core rewrite, no RBAC rewrite, no Package Execution work, no Guided Operations work, and no broad compatibility layer
Scale/Scope: one bounded enforcement slice over existing cutover-owned seams and contributor workflow documentation

Likely Affected Repo Surfaces

• apps/platform/tests/Feature/Guards/Spec288NoLegacyRouteAndHelperGuardTest.php
• apps/platform/tests/Feature/Guards/Spec288ProviderCoreAndRoleAuthorityGuardTest.php
• apps/platform/tests/Feature/Guards/AdminWorkspaceRoutesGuardTest.php
• apps/platform/tests/Feature/Guards/ProviderBoundaryPlatformCoreGuardTest.php
• apps/platform/tests/Feature/Guards/BrowserLaneIsolationTest.php
• apps/platform/tests/Feature/Guards/CiLaneFailureClassificationContractTest.php
• apps/platform/tests/Feature/Guards/CiHeavyBrowserWorkflowContractTest.php
• apps/platform/tests/Feature/ProviderConnections/LegacyRedirectTest.php
• apps/platform/tests/Feature/ManagedEnvironment/LegacyTenantCoreGuardTest.php
• apps/platform/tests/Feature/Spec080WorkspaceManagedTenantAdminMigrationTest.php
• apps/platform/tests/Feature/Rbac/ProviderConnectionWorkspaceFirstPolicyTest.php
• apps/platform/tests/Feature/Filament/ManagedEnvironmentAccessScopeManagementTest.php
• apps/platform/tests/Unit/Auth/NoRoleStringChecksTest.php
• apps/platform/tests/Pest.php
• apps/platform/tests/Support/TestLaneManifest.php
• apps/platform/tests/Support/TestLaneReport.php
• apps/platform/tests/Browser/Spec281ProviderConnectionScopeSmokeTest.php
• apps/platform/tests/Browser/Spec285WorkspaceRbacEnvironmentAccessSmokeTest.php
• README.md
• scripts/platform-test-report

Filament v5 / Surface Notes

• Livewire v4.0+ compliance: all touched surfaces remain on Filament v5 with Livewire v4.
• Provider registration location: provider registration remains in apps/platform/bootstrap/providers.php; this package does not add a panel or move provider registration.
• Global search rule: this package introduces no new globally-searchable resource and does not modify an existing resource's search surface.
• Destructive actions: no new destructive runtime action is introduced. Any touched browser smoke continues to observe existing destructive-action semantics only.
• Asset strategy: no new asset registration or deployment step is planned. Existing php artisan filament:assets expectations remain unchanged because this package adds no assets.

Enforcement Fit

• Prefer exact retired route/path inventories over broad, ambiguous bans.
• Prefer explicit scan exclusions for immutable or historical material over open-ended allowlists.
• Prefer extending existing provider-boundary and role-authority tests over introducing a second policy or provider framework.
• Prefer targeted browser smoke on the two current high-signal cutover surfaces over a broader browser lane expansion.
• Prefer classification-only baseline/report wording over any ownership claim for unrelated full-suite repair.

UI / Surface Guardrail Plan

• Guardrail scope: browser proof and route continuity over existing canonical provider and workspace/environment surfaces only
• Native vs custom classification summary: existing native Filament resources and pages only; no new operator-facing surface
• Shared-family relevance: route emission continuity, environment access continuity, and contributor proof obligations
• State layers in scope: emitted URLs, browser-visible route continuity, test-support helper usage, provider-core seam inventories, and lane/report classification wording
• Audience modes in scope: maintainers and reviewers first; operator-facing surfaces are observed but not redesigned
• Decision/diagnostic/raw hierarchy plan: unchanged runtime disclosure; docs point maintainers to guard-first and browser-second proof
• Raw/support gating plan: provider-owned raw or support detail remains nested and out of platform-core enforcement seams
• One-primary-action / duplicate-truth control: no new action family is introduced
• Handling modes by drift class or surface: implementation-required for the named guards and browser smokes only; classification-only for broader baseline fallout
• Repository-signal treatment: review-mandatory, but bounded to cutover-owned seams
• Special surface test profiles: standard-native-filament, global-context-shell, browser-smoke
• Required tests or manual smoke: functional-core, targeted browser-smoke
• Exception path and spread control: any scan exception must be file-specific beyond the pinned historical exclusions
• Active feature PR close-out entry: NoLegacyGuardrail

Shared Pattern & System Fit

• Cross-cutting feature marker: yes
• Systems touched: guard tests, browser smoke tests, shared test helpers, lane/report classification seams, and contributor-facing quality-gate documentation
• Shared abstractions reused: ProviderBoundaryCatalog, ProviderOperationRegistry, existing RBAC feature tests, TestLaneManifest, TestLaneReport, and the existing browser smoke anchors
• New abstraction introduced? why?: none
• Why the existing abstraction was sufficient or insufficient: the abstractions already describe the current cutover truth; the missing piece is an explicit, bounded enforcement layer that uses them consistently.
• Bounded deviation / spread control: explicit exclusions for immutable or historical material only

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: no
• Central contract reused: N/A
• Delegated UX behaviors: N/A
• Surface-owned behavior kept local: N/A
• Queued DB-notification policy: N/A
• Terminal notification path: N/A
• Exception path: none

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: yes
• Provider-owned seams: provider-specific identifiers, consent links, and diagnostics remain provider-owned nested detail only
• Platform-core seams: shared identity resolution and shared operation-definition contracts
• Neutral platform terms / contracts preserved: provider connection, target scope, workspace, managed environment
• Retained provider-specific semantics and why: current-release provider flows still need provider-owned nested detail, but the platform-core guard layer must not depend on it
• Bounded extraction or follow-up path: Spec 289 for Package Execution Contract work after this enforcement baseline lands

Constitution Check

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

• Inventory-first: PASS. No new inventory or snapshot truth is introduced.
• Read/write separation: PASS. The package adds guardrails and documentation only.
• Graph contract path: PASS by preservation. No new Graph integration surface is introduced.
• Deterministic capabilities: PASS by preservation. Capability families do not expand.
• RBAC-UX: PASS. Workspace membership remains role-bearing and environment scope remains narrowing-only.
• Workspace isolation: PASS. The package reinforces existing route and entitlement isolation.
• Managed-environment isolation: PASS. Wrong-scope and in-scope denial semantics remain distinct.
• Run observability: PASS. No new OperationRun behavior is introduced.
• OperationRun start UX: PASS. N/A for this package.
• Data minimization: PASS. No new persistence or ledger is introduced.
• Test governance: PASS. The proof set is explicit and bounded.
• Proportionality / no premature abstraction: PASS. Existing guard and report seams are extended instead of replaced.
• Persisted truth / behavioral state: PASS. No new state family is introduced.
• Provider boundary: PASS. Shared provider-boundary enforcement becomes stricter without widening runtime coupling.

Gate evaluation: PASS.

Post-design re-check: PASS while spec.md, plan.md, tasks.md, and quickstart.md keep the same literal proof commands and while the supporting artifacts keep the same retired-route, helper, provider-boundary, role-authority, and classification-only boundary.

Test Governance Check

• Test purpose / classification by changed surface: Feature, Browser
• Affected validation lanes: heavy-governance, browser
• Why this lane mix is the narrowest sufficient proof: route/helper scans and classification contracts are broad guard work, while visible route continuity belongs in targeted browser smoke. Anything broader would be a different package.
• Narrowest proving command(s):
  • 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" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail bin pint --dirty --format agent)
• Fixture / helper / factory / seed / context cost risks: low to moderate only because the package relies on explicit source-scan inventories and the current browser fixtures.
• Expensive defaults or shared helper growth introduced?: no; the guard pack should reduce legacy helper spread, not add new implicit defaults.
• Heavy-family additions, promotions, or visibility changes: none beyond the bounded cutover guard files and the matching classification wording.
• Surface-class relief / special coverage rule: standard-native-filament, global-context-shell, and browser-smoke remain sufficient; no broader browser lane ownership is justified.
• Closing validation and reviewer handoff: rerun the exact commands above, verify Filament stays on Livewire v4, provider registration remains in apps/platform/bootstrap/providers.php, no global-search or asset drift was added, no destructive-action contract drift was introduced, and confirm Spec 289 remains the Package Execution follow-up.
• Budget / baseline / trend follow-up: classification-only; no full-suite refresh or repair ownership is taken here.
• Review-stop questions: did the implementation widen into runtime cutover, provider-core rewrite, RBAC rewrite, UI copy cleanup, review-pack export, package execution, guided operations, or full-suite repair?
• Escalation path: document-in-feature for bounded classification wording, reject-or-split for scope expansion
• Active feature PR close-out entry: NoLegacyGuardrail

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 a bounded enforcement slice following Spec 287
• Escalation rule: if implementation starts repairing unrelated full-suite failures or reopening runtime cutover work, stop and split the work out of 288

Rollout Considerations

• Land the route/helper guard inventories before touching browser-smoke or classification docs so the core enforcement vocabulary stabilizes first.
• Keep provider-core and role-authority enforcement adjacent so reviewers can judge shared-boundary and authorization truth together.
• Update contributor-facing quality-gate guidance only after the final proof-command set is stable.
• Do not let baseline classification wording imply ownership of unrelated full-suite repair.

Risk Controls

• Reject any implementation that broad-bans all /admin/t/... paths instead of the exact retired management-only families already defined by the cutover.
• Reject any implementation that solves helper enforcement by leaving open-ended or directory-wide allowlists.
• Reject any implementation that rewrites provider-core runtime services instead of extending the guard inventory.
• Reject any implementation that changes RBAC behavior instead of proving the current workspace-role and environment-scope contract.
• Reject any implementation that promotes 288 into a full-suite stabilization effort.

Research & Design Outputs

• research.md records the guard-first decisions, explicit exclusions, and rejected full-suite repair alternative.
• data-model.md captures the exact guard categories, forbidden pattern families, and classification-only boundary.
• quickstart.md gives reviewers the scope boundary, review scenarios, and exact targeted proof commands.
• contracts/quality-gates-no-legacy-enforcement.logical.openapi.yaml models the logical enforcement contracts and the targeted validation authority.
• checklists/requirements.md records the review outcome, bounded scope rules, and the explicit Spec 289 follow-up.

Project Structure

Documentation (this feature)

specs/288-quality-gates-no-legacy-enforcement/
├── checklists/
│   └── requirements.md
├── contracts/
│   └── quality-gates-no-legacy-enforcement.logical.openapi.yaml
├── data-model.md
├── plan.md
├── quickstart.md
├── research.md
├── spec.md
└── tasks.md

Source Code (repository root)

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

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

Structure Decision: keep the package inside the existing Laravel tests, support, and wrapper structure. Extend the current guard, browser, and lane/report seams instead of creating a new enforcement subsystem or documentation tree.