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](./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)

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

```text
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.