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)

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)

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
• 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 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 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 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 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.