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

Quickstart: Filament/Livewire Heavy Suite Segmentation

Goal

Segment the current heavy Filament, Livewire, surface, discovery, and browser families so Fast Feedback stays lean, Confidence retains meaningful UI trust, Heavy Governance becomes the deliberate home for broad governance scans, and heavy cost is attributable by class and family rather than only by lane total.

Implementation Order

1. Inventory the current heavy families already visible in tests/Feature/Filament, tests/Feature/Rbac, tests/Feature/Baselines, tests/Feature/Concerns, and tests/Browser.
2. Finalize the checked-in heavy class catalog: ui-light, ui-workflow, surface-guard, discovery-heavy, and browser.
3. Extend TestLaneManifest with the heavy-classification catalog, explicit heavy-family inventory, and budget targets for the first seeded heavy families.
4. Add or refine Pest groups and manifest selectors so the seeded heavy families are technically separable without broad directory churn.
5. Move the broadest Surface-Guard and Discovery-Heavy families out of Fast Feedback and Confidence into explicit heavy-governance ownership.
6. Add or expand guard tests so class-to-lane drift fails clearly for Browser, Discovery-Heavy, and broad Surface-Guard families.
7. Extend TestLaneReport so heavy-lane output attributes cost by heavy class and named family.
8. Validate Fast Feedback, Confidence, and Heavy Governance against the existing post-Spec 207 baselines and current heavy-lane thresholds.
9. Publish concise author and reviewer guidance explaining how to classify new heavy UI tests.

Suggested Code Touches

apps/platform/composer.json
apps/platform/tests/Pest.php
apps/platform/tests/Support/TestLaneManifest.php
apps/platform/tests/Support/TestLaneBudget.php
apps/platform/tests/Support/TestLaneReport.php
apps/platform/tests/Feature/Guards/*
apps/platform/tests/Feature/Filament/*
apps/platform/tests/Feature/Rbac/*
apps/platform/tests/Feature/Baselines/*
apps/platform/tests/Feature/Concerns/*
apps/platform/tests/Browser/*
scripts/platform-test-lane
scripts/platform-test-report

Validation Flow

Validate the segmented end-state through the existing checked-in lane wrappers first:

./scripts/platform-test-lane fast-feedback
./scripts/platform-test-lane confidence
./scripts/platform-test-lane heavy-governance
./scripts/platform-test-lane browser
./scripts/platform-test-lane profiling
./scripts/platform-test-report fast-feedback
./scripts/platform-test-report confidence
./scripts/platform-test-report heavy-governance
./scripts/platform-test-report profiling
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

Keep the implementation loop tight with the most relevant focused suites first:

cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament --filter=PolicyResourceAdminSearchParityTest
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines --filter=BaselineCompareMatrixPageTest
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac --filter=UiEnforcement
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser

Recorded Baselines

Use the existing Spec 206/207 evidence as the starting comparison point for this rollout.

Scope	Current reference	Budget / note
fast-feedback	176.74s post-Spec 207 comparison baseline	Must stay stable or improve while excluding Discovery-Heavy and broad Surface-Guard families
confidence	394.38s post-Spec 207 comparison baseline	Must stay stable or improve while retaining documented UI-Light and selected UI-Workflow coverage
heavy-governance	Existing documented heavy-lane threshold 300s; refresh measured baseline during rollout	Needs updated family attribution after segmentation
browser	Existing isolated lane with dedicated budget	Remains separate and must not diffuse into other lanes

Classification Rules

• ui-light: localized component, page, or narrow action tests with limited mounts, limited reflection, and no broad discovery.
• ui-workflow: bounded multi-step or multi-surface workflows that still represent real product trust and normally belong in Confidence.
• surface-guard: broad action-surface, header-action, navigation-discipline, or relation-manager governance tests whose breadth makes them intentional heavy checks.
• discovery-heavy: tests that scan resources, pages, relation managers, global-search behavior, or reflection-heavy registries across a broad surface.
• browser: real end-to-end browser interaction and smoke coverage; always separate.

Seeded Family Examples

Use the manifest catalog as the source of truth. The first checked-in families should stay aligned with these examples:

Family	Classification	Target lane	Representative hotspots
backup-set-admin-tenant-parity	ui-light	confidence	tests/Feature/Filament/BackupSetAdminTenantParityTest.php
baseline-compare-matrix-workflow	ui-workflow	confidence	tests/Feature/Baselines/BaselineCompareMatrixCompareAllActionTest.php, tests/Feature/Baselines/BaselineCompareMatrixBuilderTest.php
onboarding-wizard-enforcement	ui-workflow	confidence	tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php
finding-bulk-actions-workflow	ui-workflow	heavy-governance	tests/Feature/Findings/FindingBulkActionsTest.php
findings-workflow-surfaces	ui-workflow	heavy-governance	tests/Feature/Findings/FindingWorkflowRowActionsTest.php, tests/Feature/Findings/FindingWorkflowViewActionsTest.php, tests/Feature/Findings/FindingsListFiltersTest.php, tests/Feature/Findings/FindingExceptionRenewalTest.php
drift-bulk-triage-all-matching	ui-workflow	heavy-governance	tests/Feature/Drift/DriftBulkAcknowledgeAllMatchingConfirmationTest.php
baseline-profile-start-surfaces	ui-workflow	heavy-governance	tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php, tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php, tests/Feature/Filament/BaselineActionAuthorizationTest.php
workspace-settings-slice-management	ui-workflow	heavy-governance	tests/Feature/SettingsFoundation/WorkspaceSettingsManageTest.php
workspace-only-admin-surface-independence	surface-guard	heavy-governance	tests/Feature/Filament/WorkspaceOnlySurfaceTenantIndependenceTest.php
action-surface-contract	surface-guard	heavy-governance	tests/Feature/Guards/ActionSurfaceContractTest.php
backup-items-relation-manager-enforcement	surface-guard	heavy-governance	tests/Feature/Rbac/BackupItemsRelationManagerUiEnforcementTest.php
workspace-memberships-relation-manager-enforcement	surface-guard	heavy-governance	tests/Feature/Rbac/WorkspaceMembershipsRelationManagerUiEnforcementTest.php
tenant-review-header-discipline	surface-guard	heavy-governance	tests/Feature/Filament/TenantReviewHeaderDisciplineTest.php
panel-navigation-segregation	surface-guard	heavy-governance	tests/Feature/Filament/PanelNavigationSegregationTest.php
ops-ux-governance	surface-guard	heavy-governance	tests/Feature/Filament/Alerts/AlertsKpiHeaderTest.php, tests/Feature/Guards/OperationLifecycleOpsUxGuardTest.php, tests/Feature/ProviderConnections/CredentialLeakGuardTest.php
policy-resource-admin-search-parity	discovery-heavy	heavy-governance	tests/Feature/Filament/PolicyResourceAdminSearchParityTest.php
policy-version-admin-search-parity	discovery-heavy	heavy-governance	tests/Feature/Filament/PolicyVersionAdminSearchParityTest.php
browser-smoke	browser	browser	tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php

Mixed-file fallback remains explicit for PolicyVersionAdminSearchParityTest.php, BaselineCompareMatrixBuilderTest.php, BuildsBaselineCompareMatrixFixtures.php, and BuildsPortfolioTriageFixtures.php; reviewers should treat the manifest record as authoritative until those files are further split.

Reviewer Guidance

1. Default new localized Filament assertions to ui-light only when the test stays scoped to one page or action surface and does not enumerate broad registries.
2. Keep a test in confidence only if the manifest can justify it as ui-light or selected ui-workflow with a clear confidence rationale.
3. Move any test that scans resources, global search, relation-manager registries, or broad action inventories into discovery-heavy or surface-guard even if it still lives under tests/Feature/Filament.
4. Treat relation-manager enforcement, header-discipline, navigation-discipline, and action-surface governance as heavy-governance by default unless the scope is materially narrowed.
5. When a file mixes confidence-worthy workflow checks and heavier fixture or discovery setup, record the dominant cost driver in the manifest and let the guard output explain the fallback.
6. Keep browser smoke and end-to-end interaction isolated in the browser class and lane; no browser file should be justified into Fast Feedback or Confidence.
7. Review heavy attribution reports by family first, then by classification, so lane-total regressions are traced back to a named hotspot family instead of a generic heavy bucket.

Manual Review Checklist

1. Confirm every seeded heavy family has a checked-in class, current lane, target lane, selectors, and hotspot files.
2. Confirm Fast Feedback contains no Discovery-Heavy families and no broad Surface-Guard families.
3. Confirm Confidence retains only documented ui-light families and explicitly selected ui-workflow families.
4. Confirm Browser remains isolated by suite, group, and guard tests.
5. Confirm mixed files are either split or explicitly classified by their broadest cost driver.
6. Confirm heavy-lane reporting attributes slowest cost by heavy class and family, not only by lane total.
7. Confirm new drift guards fail with actionable output that names the violating file or family.
8. Confirm author guidance makes it obvious when a new test is too heavy for Fast Feedback or Confidence.

Exit Criteria

1. The repository has a checked-in heavy classification catalog and seeded heavy family inventory.
2. Fast Feedback and Confidence exclude the families they are no longer supposed to carry.
3. Heavy Governance owns the broad Surface-Guard and Discovery-Heavy families targeted by the rollout.
4. Browser remains a separate class and lane.
5. Drift guards prevent wrong-lane placement for Browser and seeded heavy governance families.
6. Heavy-lane reporting exposes class- and family-level attribution.
7. Fast Feedback and Confidence remain stable or improved against the recorded post-Spec 207 baselines.