TenantAtlas/specs/206-test-suite-governance/plan.md

# Implementation Plan: Test Suite Governance & Performance Foundation

**Branch**: `206-test-suite-governance` | **Date**: 2026-04-16 | **Spec**: `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/206-test-suite-governance/spec.md`
**Input**: Feature specification from `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/206-test-suite-governance/spec.md`

## Summary

Establish repo-wired test-suite governance on top of the current Laravel 12, Pest 4, and Sail stack by defining explicit fast-feedback, confidence, heavy-governance, and browser execution paths; using Sail-wrapped `artisan test` as the canonical checked-in runner; standardizing JUnit and slow-test reporting artifacts; slimming the most pervasive shared helper and factory defaults; and documenting runtime budgets and DB-reset rules without adding new runtime product surfaces.

## Technical Context

**Language/Version**: PHP 8.4.15  
**Primary Dependencies**: Laravel 12, Pest v4, PHPUnit 12, Pest Browser plugin, Filament v5, Livewire v4, Laravel Sail  
**Storage**: SQLite `:memory:` for the default test configuration, dedicated PostgreSQL config for the schema-level `Pgsql` suite, and local runner artifacts under the repo path `apps/platform/storage/logs/test-lanes` with the app-root contract value `storage/logs/test-lanes`  
**Testing**: Pest unit, feature, browser, architecture, and guard-style suites run via `artisan test`; `RefreshDatabase` is currently auto-applied to `tests/Feature` and `tests/Browser`; profiling must run serially because Pest rejects `--profile` with `--parallel`  
**Target Platform**: Laravel web application in `apps/platform`, executed locally through Sail on macOS/Linux with later CI hardening on shared runners  
**Project Type**: Monorepo with a Laravel platform app and separate Astro website; this feature is scoped to platform test infrastructure and repo-level command entry points  
**Performance Goals**: Fast-feedback lane at least 50% below the current full-suite baseline, confidence lane below the current full-suite baseline, browser and heavy-governance runs isolated from the default loop, and reporting lanes that surface the top 10 slowest tests or files  
**Constraints**: Sail-first commands only; `scripts/platform-sail` changes the working directory to `apps/platform`; no new runtime routes, panels, assets, or dependencies; artifact paths must be app-root relative; `RefreshDatabase` remains the first-slice reset default unless a targeted carve-out is explicitly justified  
**Scale/Scope**: Current suite footprint is approximately 1,122 test files (`873` feature, `234` unit, `12` browser, `2` architecture, `1` deprecation), existing Pest grouping is sparse (`ops-ux`, `spec081`), and `createUserWithTenant()` is referenced by roughly `607` test files

### Filament v5 Implementation Notes

- **Livewire v4.0+ compliance**: Preserved. This feature governs tests around existing Filament and Livewire surfaces but does not alter the runtime Filament stack.
- **Provider registration location**: Unchanged. Existing panel providers remain registered in `bootstrap/providers.php`.
- **Global search rule**: No globally searchable resources are added or changed.
- **Destructive actions**: Runtime destructive behavior is unchanged. Any new tests added by this feature continue to assert existing confirmation and authorization rules rather than introducing new action behavior.
- **Asset strategy**: No new panel or shared assets are introduced. Existing `filament:assets` deployment behavior remains unchanged.
- **Testing plan**: Add Pest coverage for lane manifest validity, command selection, helper minimal/full defaults, browser-lane isolation, artifact generation, and guard regressions that prevent lane drift.

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- Inventory-first: PASS. No inventory, backup, or snapshot truth is changed.
- Read/write separation: PASS. The feature governs repository test execution only and introduces no end-user write path.
- Graph contract path: PASS. No Graph calls, contract-registry changes, or provider runtime integrations are added.
- Deterministic capabilities: PASS. No capability model or authorization registry changes.
- RBAC-UX, workspace isolation, tenant isolation: PASS. No runtime route, policy, or tenant/workspace surface is changed.
- Run observability and Ops-UX: PASS. Reporting artifacts are local test-run outputs, not `OperationRun` records or operator notifications.
- Data minimization: PASS. Test artifacts stay in local log storage and contain runner metadata rather than secrets or customer payloads.
- Proportionality and bloat control: PASS WITH LIMITS. The only new semantic layer is a repo-local lane and taxonomy model bounded to test execution, reporting, and cheap-default discipline.
- TEST-TRUTH-001: PASS. The plan improves suite honesty and business-truth protection by making heavy setup and slow regressions more visible.
- Filament/UI constitutions: PASS / NOT APPLICABLE. No operator-facing UI, action surface, badge semantics, or information architecture is changed.

**Phase 0 Gate Result**: PASS

- The feature is bounded to repo test governance, reporting, and fixture discipline.
- No new runtime persistence, product routes, panels, assets, or Graph behavior is introduced.
- The new lane taxonomy is narrow enough to satisfy PROP-001 while still creating a reusable repo standard.

## Project Structure

### Documentation (this feature)

```text
specs/206-test-suite-governance/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   ├── test-lane-manifest.schema.json
│   └── test-suite-governance.logical.openapi.yaml
└── tasks.md
```

### Source Code (repository root)

```text
apps/
├── platform/
│   ├── composer.json
│   ├── phpunit.xml
│   ├── phpunit.pgsql.xml
│   ├── tests/
│   │   ├── Pest.php
│   │   ├── TestCase.php
│   │   ├── Unit/
│   │   ├── Feature/
│   │   ├── Browser/
│   │   ├── Architecture/
│   │   ├── Deprecation/
│   │   └── Support/
│   ├── database/factories/
│   └── storage/logs/
├── website/
└── ...
package.json
scripts/
└── platform-sail
```

**Structure Decision**: Use the existing monorepo and keep implementation concentrated in `apps/platform` test bootstrap/configuration plus checked-in command seams. The feature is expected to touch `apps/platform/composer.json`, `apps/platform/phpunit.xml`, `apps/platform/tests/Pest.php`, selected factory/helper files under `apps/platform/tests` and `apps/platform/database/factories`, and focused guard or performance tests under `apps/platform/tests/Feature` and `apps/platform/tests/Unit`.

## Phase 0 — Research (complete)

- Output: [research.md](./research.md)
- Resolved key decisions:
  - Use Sail-wrapped `artisan test` as the canonical checked-in runner for fast, confidence, browser, heavy, profile, and JUnit paths.
  - Model lane membership through a hybrid of existing PHPUnit suites, directory selectors, and curated Pest groups instead of a full folder reorganization.
  - Keep fast-feedback and confidence lanes parallelized, but require serial profiling because Pest forbids `--profile` with `--parallel`.
  - Keep `RefreshDatabase` as the first-slice default for feature and browser tests while targeting helper and factory slimming first.
  - Split the dominant shared tenant-user helper into minimal and explicit heavy profiles because it currently provisions workspace, membership, session, cache, and provider connection state by default.
  - Standardize machine-readable artifacts and budget summaries under the repo path `apps/platform/storage/logs/test-lanes`, which corresponds to the app-root contract value `storage/logs/test-lanes`, because `scripts/platform-sail` already runs from the app root.
  - Treat schema dumps as a follow-up evaluation, not a first-slice requirement, because the default suite uses in-memory SQLite and the PostgreSQL suite is currently isolated.

## Phase 1 — Design & Contracts (complete)

- Output: [data-model.md](./data-model.md) formalizes lane, selector, helper-profile, factory-cost, DB-reset, artifact, and budget entities.
- Output: [contracts/test-lane-manifest.schema.json](./contracts/test-lane-manifest.schema.json) defines the checked-in manifest structure for lane membership, artifacts, budgets, and DB strategy.
- Output: [contracts/test-suite-governance.logical.openapi.yaml](./contracts/test-suite-governance.logical.openapi.yaml) captures the logical run/report contract for lane execution and artifact inspection.
- Output: [quickstart.md](./quickstart.md) provides the planned implementation order, focused validation commands, and rollout checkpoints.

### Post-design Constitution Re-check

- PASS: No runtime routes, panels, authorization planes, or Graph seams are introduced.
- PASS: The only new taxonomy is repo-local and directly justified by current suite cost and contributor workflow.
- PASS: The design prefers local selectors, helper splits, and manifest-backed commands over new generalized platform abstractions.
- PASS WITH WORK: Initial heavy-family selection must remain evidence-driven and should start with obviously separate seed families such as architecture, deprecation, browser-adjacent governance scans, and wide scan or guard suites, while browser itself remains its own dedicated lane, then be refined after the first profiling pass.
- PASS WITH WORK: Budget enforcement starts as documented reporting thresholds and can harden later once baseline measurements stabilize.

## Phase 2 — Implementation Planning

`tasks.md` should cover:

- Adding the checked-in lane command entry points for fast-feedback, confidence, browser, heavy-governance, profiling, and JUnit/reporting.
- Introducing a lane manifest or equivalent checked-in selector map that combines suites, directories, files, and groups without broad test relocation.
- Keeping the default contributor run aligned to fast-feedback rather than the current broad serial behavior.
- Creating artifact output conventions and summary generation under the repo path `apps/platform/storage/logs/test-lanes` and the app-root contract value `storage/logs/test-lanes`.
- Adding guard coverage that verifies browser exclusion from the fast lane, valid lane manifest shape, and stable budget/report semantics.
- Capturing the current full-suite baseline and the first measured lane baselines before final budget publication.
- Refactoring `createUserWithTenant()` into minimal and explicit heavy/provider-enabled paths, then migrating the first high-value callers.
- Introducing explicit minimal versus heavy factory states for at least one additional cascading fixture cluster touched in this slice, plus guidance that future touched heavy clusters must follow the same pattern.
- Documenting honest taxonomy rules for Unit, Feature or Integration, Browser, and Architecture or Governance tests, plus auditing and reclassifying the first obvious misfit batch surfaced during rollout.
- Defining and documenting initial runtime budgets for at least fast-feedback, confidence, browser, and the first identified heavy family, with heavy-governance refinement informed by the first profiling evidence.
- Capturing DB strategy guidance for SQLite-memory default runs, the isolated PostgreSQL suite, seeds policy, and later schema-baseline evaluation.

### Contract Implementation Note

- The lane manifest contract is schema-first and intentionally runner-agnostic. It defines what a checked-in lane declaration must contain even if the first implementation stores it in PHP arrays or config instead of a dedicated parser.
- The OpenAPI file is logical rather than transport-prescriptive. It documents the expected semantics of lane execution and report generation for commands, tasks, or wrappers that will remain in-process repository tooling.
- The plan intentionally avoids introducing a new runtime service or database table for lane reporting. Artifacts remain filesystem-based and ephemeral.

### Deployment Sequencing Note

- No database migration is planned.
- No asset publish step changes.
- The rollout should start with lane/report visibility, then cheap helper defaults, then lane reshaping of the heaviest families, and only afterward optional framework-level tuning such as schema-baseline evaluation.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| None | Not applicable | Not applicable |

## Proportionality Review

- **Current operator problem**: Contributors cannot reliably choose the right test lane, and maintainers cannot see slow-test drift or hidden heavy setup early enough to keep the default run healthy.
- **Existing structure is insufficient because**: Current execution relies on a broad serial default, sparse Pest groups, heavyweight shared defaults, and ad-hoc local reporting rather than checked-in governance.
- **Narrowest correct implementation**: A repo-local lane manifest, explicit checked-in commands, artifact/report conventions, and minimal/full fixture profiles solve the problem without adding runtime services or persistence.
- **Ownership cost created**: The repo must maintain lane selectors, helper profile rules, budgets, and a small set of guard tests that keep drift visible.
- **Alternative intentionally rejected**: Pure parallelization without taxonomy, or local-only helper workarounds without checked-in reporting and lane definitions.
- **Release truth**: Current-release truth and immediate prerequisite for larger suite growth and later CI hardening.