TenantAtlas/specs/208-heavy-suite-segmentation/plan.md

# Implementation Plan: Filament/Livewire Heavy Suite Segmentation

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

## Summary

Build Spec 208 on top of the existing Spec 206 lane manifest and the Spec 207 fixture-cost work by introducing a repo-local heavy UI classification catalog, inventorying the current Filament-, Livewire-, surface-, discovery-, and workflow-heavy families, tightening manifest selectors and Pest groups around those families, extending guard coverage so heavy tests cannot drift into the wrong lanes, and adding class- and family-level attribution to heavy-lane reporting without introducing new runtime services or product-facing behavior.

## Technical Context

**Language/Version**: PHP 8.4.15  
**Primary Dependencies**: Laravel 12, Pest v4, PHPUnit 12, Filament v5, Livewire v4, Laravel Sail  
**Storage**: SQLite `:memory:` for the default test environment, existing lane artifacts under the app-root contract path `storage/logs/test-lanes`, and no new product persistence  
**Testing**: Pest unit, feature, browser, architecture, and guard suites run through Sail-wrapped `artisan test`; lane selection is currently controlled by `Tests\Support\TestLaneManifest`, Pest groups in `tests/Pest.php`, and focused guard tests under `tests/Feature/Guards`  
**Target Platform**: Laravel monorepo application in `apps/platform`, executed locally through Sail and later hardened in shared CI  
**Project Type**: Monorepo with a Laravel platform app and separate Astro website; this feature is scoped to platform test-governance infrastructure  
**Performance Goals**: Keep Fast Feedback free of Discovery-Heavy and broad Surface-Guard families, keep Confidence limited to documented UI-Light and selected UI-Workflow families, make Heavy Governance attributable by heavy class and family, and preserve or improve the post-Spec 207 fast-feedback and confidence baselines while keeping the heavy lane observable  
**Constraints**: Sail-first commands only; no new product routes, assets, runtime services, or dependencies; Browser remains a separate lane; the classification model must stay small and evidence-driven; directory names alone cannot be the source of truth; mixed files must be split or classified by their broadest cost driver  
**Scale/Scope**: Existing lane infrastructure already defines six checked-in lane entries; heavy families currently concentrate in `tests/Feature/Filament`, `tests/Feature/Rbac`, `tests/Feature/Baselines`, `tests/Feature/Concerns`, broad governance guards, and `tests/Browser`; the exploratory inventory identified roughly 209 Filament feature tests, about 35 RBAC-heavy files, and dozens of Baseline Compare and governance-adjacent tests that need explicit segmentation

### Filament v5 Implementation Notes

- **Livewire v4.0+ compliance**: Preserved. This feature changes only repository test-governance around Filament and Livewire surfaces, not runtime Filament or Livewire behavior.
- **Provider registration location**: Unchanged. Existing panel providers remain registered in `bootstrap/providers.php`.
- **Global search rule**: No globally searchable resources are added or modified. Tests may classify global-search parity checks as heavy discovery families, but runtime global-search behavior is unchanged.
- **Destructive actions**: No runtime destructive actions are introduced. Any new tests added by this feature continue to validate existing confirmation and authorization behavior.
- **Asset strategy**: No panel-only or shared assets are added. Existing `filament:assets` deployment behavior remains unchanged.
- **Testing plan**: Add Pest guard coverage for heavy-classification catalog validity, lane-to-class mapping, heavy-family drift detection, report attribution, and targeted validation of the resegmented Fast Feedback, Confidence, and Heavy Governance lanes.

## Constitution Check

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

- Inventory-first: PASS. No inventory, snapshot, or backup truth is changed.
- Read/write separation: PASS. The feature only changes repository test-governance behavior and introduces no end-user mutation path.
- Graph contract path: PASS. No Graph calls, contract-registry changes, or provider runtime integrations are added.
- Deterministic capabilities: PASS. No capability resolver or authorization registry changes.
- RBAC-UX, workspace isolation, tenant isolation: PASS. No runtime routes, policies, global search availability, or tenant/workspace enforcement semantics are changed.
- Run observability and Ops-UX: PASS. Reporting remains filesystem-based through the existing lane tooling and does not introduce `OperationRun` behavior.
- Data minimization: PASS. Heavy-family inventories and lane reports remain repo-local and contain no secrets or customer payloads.
- Proportionality and bloat control: PASS WITH LIMITS. The only new semantic layer is a narrow repo-local classification catalog for heavy UI test families. The plan explicitly avoids a broader meta-framework and keeps lane placement tied to measurable cost and purpose.
- TEST-TRUTH-001: PASS. The feature increases suite honesty by making broad discovery, surface, and workflow costs visible and governable instead of leaving them hidden in general feature lanes.
- Filament/UI constitutions: PASS / NOT APPLICABLE. No operator-facing UI, action-surface runtime contract, badge semantics, or panel IA is changed.

**Phase 0 Gate Result**: PASS

- The feature remains bounded to repository test governance, reporting, selector rules, and author guidance.
- No new runtime persistence, product routes, panels, assets, or Graph seams are introduced.
- The chosen approach extends the existing Spec 206/207 tooling instead of creating a second test-governance system.

## Project Structure

### Documentation (this feature)

```text
specs/208-heavy-suite-segmentation/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   ├── heavy-test-classification.schema.json
│   └── heavy-suite-segmentation.logical.openapi.yaml
└── tasks.md
```

### Source Code (repository root)

```text
apps/
├── platform/
│   ├── composer.json
│   ├── tests/
│   │   ├── Pest.php
│   │   ├── Support/
│   │   │   ├── TestLaneManifest.php
│   │   │   ├── TestLaneBudget.php
│   │   │   └── TestLaneReport.php
│   │   ├── Feature/
│   │   │   ├── Baselines/
│   │   │   ├── Concerns/
│   │   │   ├── Filament/
│   │   │   ├── Guards/
│   │   │   ├── Navigation/
│   │   │   ├── Onboarding/
│   │   │   └── Rbac/
│   │   ├── Browser/
│   │   └── Unit/
│   └── storage/logs/test-lanes/
├── website/
└── ...
scripts/
├── platform-test-lane
└── platform-test-report
```

**Structure Decision**: Keep implementation concentrated in the existing platform test-governance seams: `apps/platform/tests/Pest.php` for group tagging, `apps/platform/tests/Support/TestLaneManifest.php` for lane catalog and family metadata, `apps/platform/tests/Support/TestLaneReport.php` for attribution output, targeted guard tests under `apps/platform/tests/Feature/Guards`, and selective heavy-family files under `apps/platform/tests/Feature/Filament`, `apps/platform/tests/Feature/Rbac`, `apps/platform/tests/Feature/Baselines`, and `apps/platform/tests/Feature/Concerns`. Planning artifacts stay inside `specs/208-heavy-suite-segmentation`.

## Complexity Tracking

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

## Proportionality Review

- **Current operator problem**: Contributors and reviewers cannot reliably see when a Filament or Livewire test family is too broad for Fast Feedback or Confidence, so expensive discovery and surface-guard behavior silently erodes faster lanes.
- **Existing structure is insufficient because**: The current lane manifest distinguishes fast, confidence, browser, and heavy-governance at a coarse level but does not classify heavy UI families by their actual cost drivers or preserve their intent for reviewers.
- **Narrowest correct implementation**: Extend the existing lane manifest, Pest group seams, guard tests, and report attribution with a small heavy-family catalog and class model instead of adding a new runner, new persistence, or a broad test taxonomy framework.
- **Ownership cost created**: The repo must maintain the heavy classification catalog, targeted family inventory, lane-to-class rules, drift guards, and budget attribution as new UI-heavy tests are added.
- **Alternative intentionally rejected**: Purely directory-based moves or ad-hoc per-file exclusions, because they hide cost instead of making it reviewable and enforceable.
- **Release truth**: Current-release repository truth and the direct next step after Specs 206 and 207.

## Phase 0 — Research (complete)

- Output: [research.md](./research.md)
- Resolved key decisions:
  - Reuse the existing `TestLaneManifest`, `TestLaneBudget`, and `TestLaneReport` seams instead of introducing a new lane engine.
  - Model heavy UI cost with five explicit classes: `ui-light`, `ui-workflow`, `surface-guard`, `discovery-heavy`, and `browser`.
  - Keep `heavy-governance` as the operational destination for broad Surface-Guard and Discovery-Heavy families instead of adding a brand-new operational lane.
  - Represent heavy-family ownership through a hybrid of manifest selectors, granular Pest groups, and explicit hotspot file inventory rather than forcing a large directory move before the classification model stabilizes.
  - Treat mixed files as a first-class case: either split them or classify them by the broadest cost-driving behavior.
  - Start the heavy-family inventory from existing hotspots in `tests/Feature/Filament`, `tests/Feature/Rbac`, `tests/Feature/Baselines`, `tests/Feature/Concerns`, and the existing Browser lane, then tighten placement from profiling evidence.
  - Extend drift guards from coarse lane exclusion to explicit class-to-lane validation so new heavy tests cannot silently diffuse into Fast Feedback or Confidence.
  - Extend report output and family budgets to attribute heavy costs by class and family, not only by lane.

## Phase 1 — Design & Contracts (complete)

- Output: [data-model.md](./data-model.md) formalizes the heavy classification catalog, heavy family inventory, lane placement rules, mixed-file handling, drift guards, and report attribution model.
- Output: [contracts/heavy-test-classification.schema.json](./contracts/heavy-test-classification.schema.json) defines the checked-in schema for the heavy classification catalog, family inventory, confidence rationale requirements, and mixed-file resolution records.
- Output: [contracts/heavy-suite-segmentation.logical.openapi.yaml](./contracts/heavy-suite-segmentation.logical.openapi.yaml) captures the logical contract for classifying heavy families, reading family and mixed-file inventories, validating lane placement, and reading heavy-attribution reports.
- Output: [quickstart.md](./quickstart.md) provides the rollout order, validation commands, and review checkpoints for the segmentation work.

### Post-design Constitution Re-check

- PASS: No runtime routes, panels, authorization planes, or Graph seams are introduced.
- PASS: The new classification catalog is repo-local, directly justified by current suite cost, and bounded to existing lane-governance infrastructure.
- PASS: The design prefers extending existing manifest, guard, and reporting seams over adding a second governance framework.
- PASS WITH WORK: The heavy-family inventory must remain evidence-driven and limited to families that materially change lane cost or review behavior.
- PASS WITH WORK: Confidence preservation must be documented explicitly as families move so the faster lane mix does not become a hollow smoke-only layer.

## Phase 2 — Implementation Planning

`tasks.md` should cover:

- Inventorying the current heavy Filament, Livewire, surface, discovery, workflow, wizard, header-action, and navigation-discipline families touched by current lanes.
- Extending `TestLaneManifest` with a checked-in heavy-classification catalog and explicit heavy-family inventory.
- Adding granular Pest groups or equivalent checked-in metadata for `ui-light`, `ui-workflow`, `surface-guard`, and `discovery-heavy` where group-based selection provides better drift control.
- Refining Fast Feedback and Confidence selectors so Discovery-Heavy and broad Surface-Guard families are excluded intentionally rather than by scattered file exceptions.
- Reassigning the first heavy hotspot families from coarse exclusions into explicit `heavy-governance` family ownership, including action-surface, header-action, navigation-discipline, relation-manager, wizard, and discovery-heavy hotspots.
- Extending `TestLaneBudget` and `TestLaneReport` so heavy budgets and slowest entries are attributable by class and family, not only by lane.
- Adding or expanding guard tests that verify class-to-lane rules, browser isolation, mixed-family handling, and heavy-family drift detection.
- Validating that Confidence still contains the intended UI-Light and selected UI-Workflow safety after the moves.
- Running the existing lane wrappers to compare Fast Feedback, Confidence, and Heavy Governance behavior against the post-Spec 207 baselines.
- Publishing concise author and reviewer guidance for new heavy UI tests so placement intent is visible at review time.

### Contract Implementation Note

- The JSON schema is schema-first and repository-tooling-oriented. It defines what the checked-in heavy classification catalog, family inventory, confidence rationale, and mixed-file resolution records must express even if the first implementation remains PHP arrays in `TestLaneManifest`.
- The OpenAPI file is logical rather than transport-prescriptive. It documents the expected semantics of heavy-family classification, mixed-file resolution, lane-validation, and report-attribution flows for in-process repository tooling.
- The plan intentionally avoids introducing a new runtime service, a new database table, or a new artifact root outside the existing `storage/logs/test-lanes` contract.

### Deployment Sequencing Note

- No database migration is planned.
- No asset publish step changes.
- The rollout should start with heavy-family inventory and classification rules, then tighten selectors and guard tests, then extend heavy-attribution reporting, and finally validate the affected lanes against the existing baseline and budget seams.