# Feature Specification: Filament/Livewire Heavy Suite Segmentation **Feature Branch**: `208-heavy-suite-segmentation` **Created**: 2026-04-16 **Status**: Draft **Input**: User description: "Spec 208 - Filament/Livewire Heavy Suite Segmentation" ## Spec Candidate Check *(mandatory — SPEC-GATE-001)* - **Problem**: TenantPilot's growing Filament-, Livewire-, surface-, discovery-, and governance-heavy test families are still mixed too closely with faster feedback paths, so the suite pays heavy UI and discovery cost in lanes that should stay lean. - **Today's failure**: Broad surface guards, discovery-heavy checks, and multi-mount workflow tests can drift into Fast Feedback or Confidence lanes without a clear classification model, making runtime slower while hiding which families are responsible. - **User-visible improvement**: Contributors get faster and more predictable standard lanes, maintainers can see heavy UI and discovery families as their own cost class, and reviewers can place new heavy tests correctly without relying on local tribal knowledge. - **Smallest enterprise-capable version**: Inventory the heavy Filament or Livewire families, define a small classification model, map those classes to existing lanes, make heavy families technically separable, add drift guards, document author guidance, and validate that the affected lanes still provide the intended confidence. - **Explicit non-goals**: No blanket reduction of Filament or Livewire coverage, no browser-strategy redesign, no wholesale rewrite of every UI test, no product runtime refactor, and no CI-matrix wiring rollout in this spec. - **Permanent complexity imported**: A repo-level heavy-test classification vocabulary, lane-mapping rules, heavy-family inventory, drift-guard expectations, and explicit heavy-lane budget visibility. - **Why now**: Spec 206 established lane governance and Spec 207 lowers per-test setup cost; without segmenting the heaviest UI and discovery families next, faster lanes will keep eroding as the platform surface grows. - **Why not local**: Local file moves or one-off exclusions cannot keep heavy families out of the wrong lane over time. The classification and placement rules must be shared, visible, and enforceable at repository level. - **Approval class**: Cleanup - **Red flags triggered**: New classification vocabulary and a new repo-wide taxonomy for heavy tests. Defense: the taxonomy is intentionally narrow, limited to test-lane governance, and does not introduce new product runtime truth, new product persistence, or speculative application abstractions. - **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 1 | Produktnähe: 1 | Wiederverwendung: 2 | **Gesamt: 10/12** - **Decision**: approve ## Spec Scope Fields *(mandatory)* - **Scope**: workspace - **Primary Routes**: No end-user HTTP routes change. The affected surfaces are repository-level lane manifests, grouping rules, wrapper entry points, profiling outputs, hotspot visibility, and checked-in author or reviewer guidance. - **Data Ownership**: Workspace-owned test taxonomy, family inventory, lane assignments, drift guards, heavy-lane budget rules, and reporting evidence. No tenant-owned runtime records or end-user product data are introduced. - **RBAC**: No end-user authorization behavior changes. The affected actors are repository contributors, reviewers, and maintainers who need stable, explicit lane placement for heavy UI and discovery tests. ## Proportionality Review *(mandatory when structural complexity is introduced)* - **New source of truth?**: no - **New persisted entity/table/artifact?**: no new product persistence; only repository-owned classification metadata, checked-in guidance, and runtime evidence for lane validation - **New abstraction?**: yes, but limited to a repository-level heavy-suite classification and lane-mapping model - **New enum/state/reason family?**: no product runtime state is added; the new categories are test-governance classes only - **New cross-domain UI framework/taxonomy?**: yes, but narrowly scoped to classifying heavy test families by cost and purpose so lane placement remains reviewable and enforceable - **Current operator problem**: Contributors and maintainers cannot keep fast lanes lean when broad Filament or Livewire discovery and surface-governance families look similar to ordinary UI tests and drift into the wrong run path. - **Existing structure is insufficient because**: Directory names and current lane assignments do not reliably communicate discovery breadth, mount count, reflection cost, or surface-wide governance intent, so the real cost class is often only visible after runtime has already degraded. - **Narrowest correct implementation**: Add a small classification model, map it to existing lanes, inventory the heaviest current families, make those families technically separable, add drift guards, and publish concise author guidance. - **Ownership cost**: The team must maintain class definitions, lane-mapping rules, heavy-family inventory, drift guards, and heavy-budget visibility as the suite evolves. - **Alternative intentionally rejected**: Purely directory-based moves or ad-hoc exclusions without a shared semantic model, because those approaches hide cost instead of making it governable. - **Release truth**: Current-release repository truth that protects the lane model already introduced in Spec 206 and strengthened by Spec 207. ## Problem Statement Even with slimmer fixtures, the suite stays expensive if the heaviest UI and discovery families remain organizationally mixed with ordinary feedback paths. The structural issues are now clear: - Filament and Livewire tests do not all belong to the same cost class. - Discovery-heavy and surface-wide guard tests grow with every new resource, page, relation manager, or system surface. - Broad UI or surface checks can compete directly with the fast authoring loop when they land in the wrong lane. - Lane placement is unstable if cost and purpose are not classified explicitly. - Some tests only reveal their real heaviness at runtime because they combine discovery, reflection, multiple mounts, and broad assertion sets in one file. - The most expensive families need their own budgets and visibility so runtime drift can be attributed accurately. Without explicit segmentation, the Fast Feedback and Confidence lanes created by Spec 206 will gradually absorb more broad UI and discovery cost, even after per-test setup has been slimmed by Spec 207. ## Dependencies - Depends on Spec 206 - Test Suite Governance & Performance Foundation for the lane vocabulary, wrappers, baseline visibility, and budget discipline. - Recommended after Spec 207 - Shared Test Fixture Slimming so per-test setup cost is reduced before the heaviest families are separated more sharply. - Blocks clean lane-based separation of expensive UI-, surface-, and discovery-heavy families. - Does not block ongoing feature delivery as long as newly added heavy tests are classified and placed lane-conform from the start. ## Goals - Identify and classify heavy Filament, Livewire, surface, and discovery test families clearly. - Protect Fast Feedback from deliberate heavy UI and discovery cost. - Keep the Confidence lane broad enough to remain trusted while excluding surface-wide heavy governance families. - Establish Heavy Governance as the explicit home for surface-guard and discovery-heavy families. - Prevent new heavy tests from drifting silently into the wrong lane. - Preserve valuable Filament and Livewire safety while making its operating cost visible and governable. - Make future UI test growth scale through explicit class and lane rules rather than informal directory folklore. ## Non-Goals - Reducing legitimate Filament or Livewire coverage just to improve runtime headline numbers. - Redefining the Browser lane or folding browser behavior into this spec. - Replacing the fixture-cost work from Spec 207. - Rewriting every existing UI test into a new structure in one pass. - Performing CI-matrix or enforcement wiring that belongs in a later spec. - Changing Filament runtime semantics, application IA, or product behavior outside repository test organization and guidance. ## Assumptions - The lane model, wrappers, and baseline discipline from Spec 206 already exist or can be regenerated before this rollout is validated. - Fixture slimming from Spec 207 lowers per-test setup cost but does not by itself solve heavy-family placement. - Browser remains a separate cost class and is not merged into the heavy Filament or Livewire taxonomy. - Not every class needs its own dedicated directory, as long as its lane placement is explicit, technically separable, and reviewable. - Some borderline UI workflow tests may remain in Confidence if their scope is localized and their cost stays within documented lane budgets. ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Classify Existing Heavy UI Families (Priority: P1) As a maintainer, I want the current heavy Filament, Livewire, surface, and discovery families inventoried and classified so the repository can stop treating them as a single undifferentiated UI cost bucket. **Why this priority**: The rollout cannot be reliable until the existing heavy families are visible, named, and assigned a clear cost class. **Independent Test**: Review the inventory produced by the rollout and confirm that each targeted heavy family has a named class, a purpose, a current lane, a target lane, and identifiable hotspot files. **Acceptance Scenarios**: 1. **Given** a currently known heavy Filament or Livewire family, **When** the inventory is reviewed, **Then** its cost class, purpose, current lane, target lane, and hotspot files are documented. 2. **Given** a family performs broad discovery, reflection, or surface-wide validation, **When** it is classified, **Then** it is not treated as ordinary UI-Light coverage. 3. **Given** a family mixes UI interaction and governance-wide inspection, **When** it is reviewed, **Then** the broadest cost-driving behavior determines its class unless the family is split intentionally. --- ### User Story 2 - Keep Fast And Confidence Lanes Honest (Priority: P1) As a contributor, I want Fast Feedback and Confidence to exclude the heaviest surface-wide and discovery-wide families so the normal authoring loop stays fast without hiding where broader governance checks now run. **Why this priority**: Lane shaping only matters if the most commonly used runs stop paying for deliberately heavy families. **Independent Test**: Run the affected lanes after segmentation and verify that Fast Feedback excludes Discovery-Heavy and broad Surface-Guard families, while Confidence retains only documented UI-Light and selected UI-Workflow coverage. **Acceptance Scenarios**: 1. **Given** a family is classified as Discovery-Heavy or a broad Surface-Guard, **When** Fast Feedback runs, **Then** that family is excluded. 2. **Given** a UI-Light or selected UI-Workflow family is explicitly approved for Confidence, **When** Confidence runs, **Then** it remains present without pulling in undocumented heavy governance families. 3. **Given** a maintainer compares lane manifests after segmentation, **When** they inspect Fast Feedback and Confidence, **Then** the absence or inclusion of heavy UI families is explainable from written rules instead of local habit. --- ### User Story 3 - Catch Lane Drift During Review (Priority: P2) As a reviewer, I want clear author rules and drift guards so a newly added heavy UI test cannot silently land in the wrong lane. **Why this priority**: The segmentation work decays quickly if new tests can bypass it without being noticed. **Independent Test**: Add or move a representative heavy test to the wrong lane and confirm that the repository's drift guard or validation path fails clearly enough for a reviewer to correct placement. **Acceptance Scenarios**: 1. **Given** a new test performs broad resource discovery or surface-wide governance checks, **When** it is placed in Fast Feedback or ordinary Confidence by mistake, **Then** drift validation flags the mismatch. 2. **Given** a reviewer inspects a new heavy UI test, **When** they read the repository guidance, **Then** they can determine whether the test is UI-Light, UI-Workflow, Surface-Guard, Discovery-Heavy, or Browser. 3. **Given** a test belongs to the Browser class, **When** it is assigned to a non-browser lane, **Then** the repository rejects the placement. --- ### User Story 4 - Observe Heavy Budgets Separately (Priority: P2) As a maintainer, I want the Heavy Governance lane and its heaviest families measured separately so runtime drift is visible without distorting the health signal of faster lanes. **Why this priority**: Once heavy families are separated, the team still needs to see whether they are growing responsibly or becoming the next uncontrolled hotspot cluster. **Independent Test**: Generate the heavy-lane reporting view after segmentation and confirm that the top hotspots are attributable to named heavy families or classes instead of appearing as undifferentiated suite slowdown. **Acceptance Scenarios**: 1. **Given** the Heavy Governance lane completes, **When** its reporting output is reviewed, **Then** the top hotspots are tied to named heavy families or classes. 2. **Given** heavy-family runtime grows over time, **When** maintainers inspect the reporting signal, **Then** they can see whether the drift belongs to discovery-heavy, surface-guard, or workflow-heavy families. ### Edge Cases - A single file mixes a localized component assertion with broad discovery or reflection, making directory-only classification misleading. - A discovery-heavy family sits in a generic Feature location and looks cheap until it scans resources or relation managers at runtime. - A previously narrow UI test becomes heavy after adding multiple mounts, wide action-surface assertions, or broad reflection checks. - A borderline workflow test is too broad for Fast Feedback but still narrow enough for Confidence if its scope remains local and its cost stays within the documented budget. - Browser-like interaction depth must not be relabeled as heavy Filament or Livewire merely to avoid Browser-lane isolation. ## Requirements *(mandatory)* **Constitution alignment (required):** This feature changes no end-user routes, no Microsoft Graph behavior, no authorization plane, no queued operation semantics, and no operator-facing product surface. It does introduce a repository-level taxonomy for heavy UI and discovery tests, so the class model, lane mapping, drift guards, and validation evidence must remain explicit, reviewable, and measurable. **Constitution alignment (PROP-001 / ABSTR-001 / BLOAT-001 / TEST-TRUTH-001):** The new structure is limited to repository test governance. It is justified because current lane drift is caused by real cost differences between heavy and ordinary UI families, and a narrower local move-only approach cannot keep those families out of the wrong lanes over time. The classification must stay small, cost-driven, and directly tied to business-useful confidence rather than creating an elaborate semantic framework. ### Functional Requirements - **FR-001 Heavy Classification Model**: The repository MUST define a documented classification model for heavy UI-related test families with at least these classes: UI-Light, UI-Workflow, Surface-Guard, Discovery-Heavy, and Browser. - **FR-002 Class Meaning**: Each class MUST have a written purpose, typical cost profile, characteristic behaviors, and boundary rules that explain why a test belongs there. - **FR-003 Cost-And-Purpose Placement**: Test classification MUST be determined by cost and purpose, including mount breadth, discovery breadth, reflection passes, assertion density, and surface coverage, rather than by directory name alone. - **FR-004 Lane Mapping Rules**: The repository MUST define binding lane-mapping rules stating which classes may appear in Fast Feedback, Confidence, Heavy Governance, and Browser. - **FR-005 Fast Feedback Protection**: Fast Feedback MUST exclude Discovery-Heavy families and broad Surface-Guard families. Only explicitly approved, low-cost UI-Light cases may remain there. - **FR-006 Confidence Preservation**: Confidence MUST retain documented UI-Light coverage and selected UI-Workflow coverage, while excluding undocumented discovery-wide or surface-wide heavy governance families. The repository MUST explain which UI safety remains in Confidence and why the exclusions are safe. - **FR-007 Heavy Governance Isolation**: Heavy Governance MUST be the explicit home for Surface-Guard, Discovery-Heavy, and other broad Filament or Livewire contract families whose cost or breadth makes them unsuitable for ordinary authoring loops. - **FR-008 Browser Isolation**: Browser MUST remain an independent class and lane. Browser tests MUST NOT diffuse into Fast Feedback, Confidence, or Heavy Governance. - **FR-009 Heavy Family Inventory**: The rollout MUST inventory the heaviest Filament, Livewire, surface, and discovery families touched by current lanes, documenting for each family its purpose, class, current lane, target lane, and hotspot files. - **FR-010 Technical Separability**: Heavy families MUST be technically separable through an explicit combination of grouping, manifest assignment, namespace or directory convention, wrapper metadata, or equivalent checked-in mechanism. Lane placement MUST NOT depend on unwritten team knowledge. - **FR-011 Surface Family Rationalization**: The heaviest action-surface, header-action, navigation-discipline, relation-manager, wizard, and discovery-wide governance families MUST be reviewed and intentionally placed in the correct class and lane. - **FR-012 Drift Guards**: The repository MUST include guard logic, validation tests, or an equivalent checked-in control that detects when Browser, Discovery-Heavy, or broad Surface-Guard families are assigned to the wrong lane. - **FR-013 Mixed-Family Handling**: When a file combines multiple behaviors with different cost classes, the repository MUST either split the file or classify it by its broadest cost-driving behavior and document that choice. - **FR-014 Heavy Budget Visibility**: Heavy Governance and other heavy UI family outputs MUST expose a lane budget, top hotspots, and named family or class attribution so runtime drift is visible over time. - **FR-015 Author And Reviewer Guidance**: Contributors and reviewers MUST have concise, binding guidance that explains when a test is UI-Light, UI-Workflow, Surface-Guard, Discovery-Heavy, or Browser, and when a test is too heavy for Fast Feedback or Confidence. - **FR-016 Validation Evidence**: After segmentation, the affected lanes MUST be validated successfully, and the validation evidence MUST show that faster lanes remain protected while heavy governance coverage is still runnable and observable. ### Non-Functional Requirements - **NFR-001 Fast-Lane Integrity**: Fast Feedback must remain stable or improved against its post-Spec 207 baseline and must measure lower wall-clock duration than Confidence and Heavy Governance in wrapper validation after segmentation. - **NFR-002 Review Clarity**: A reviewer must be able to determine the intended class and lane of a new heavy UI test from checked-in guidance and test-local signals without case-by-case reinvention. - **NFR-003 Observability**: Heavy-family runtime drift must be attributable to named classes or families rather than surfacing only as general suite slowdown. - **NFR-004 Scalability Readiness**: As the platform gains more resources, pages, and relation managers, growth in broad discovery or surface-governance coverage must scale primarily in Heavy Governance rather than silently inflating faster lanes. ## Work Packages ### Work Package A - Heavy Family Inventory - Catalogue the current heavy Filament, Livewire, surface, and discovery families. - Record each family's purpose, cost class, current lane, target lane, and hotspot files. - Identify the most expensive broad-surface and discovery-heavy families that currently distort faster lanes. - Distinguish localized workflow coverage from governance-wide inspection families before any mechanical moves begin. ### Work Package B - Classification And Lane Rules - Finalize the UI-Light, UI-Workflow, Surface-Guard, Discovery-Heavy, and Browser classes. - Define the lane-mapping rules for Fast Feedback, Confidence, Heavy Governance, and Browser. - Document boundary rules for borderline cases, especially mixed workflow and discovery behavior. - Publish concise reviewer rules so lane placement decisions stay consistent. ### Work Package C - Mechanical Segmentation - Adjust groups, manifests, wrapper metadata, namespaces, directories, or other checked-in selectors so heavy families are technically separable. - Move or reassign the broadest heavy families into their correct lane. - Ensure ordinary faster lanes cannot inherit those families accidentally. - Keep the resulting structure visible enough that reviewers can understand placement intent immediately. ### Work Package D - Drift Guards - Add validation that Browser families stay browser-only. - Add validation that Discovery-Heavy and broad Surface-Guard families do not drift into Fast Feedback or ordinary Confidence. - Protect against newly added heavy families being treated as ordinary UI tests without a classification decision. - Ensure mixed or borderline families are either split or explicitly justified. ### Work Package E - Lane Validation - Validate Fast Feedback after heavy-family removal. - Validate Confidence after the intended UI-Light and UI-Workflow coverage remains. - Validate Heavy Governance as a runnable lane for deliberate surface and discovery cost. - Compare the resulting lane behavior against the post-Spec 207 baseline so the benefit and the retained confidence are both visible. ## Deliverables - An inventory of the heavy Filament, Livewire, surface, and discovery families touched by this rollout. - A documented heavy-test classification model. - Updated lane mappings and checked-in technical separation for the targeted heavy families. - Drift guards that reject wrong-lane placement for Browser and heavy governance families. - Concise author and reviewer guidance for new heavy UI tests. - Validation evidence for Fast Feedback, Confidence, and Heavy Governance after segmentation. - Updated heavy-lane budget and hotspot visibility. ## Risks ### False Confidence Through Over-Segmentation If too much meaningful UI safety leaves Confidence, the faster lane mix may look healthy while real product trust declines. ### Taxonomy Complexity If the class model grows too many exceptions or subclasses, contributors may stop using it consistently. ### Mechanical Moves Without Semantic Clarity If files are merely moved between groups or directories without a clear class model, the repository will hide cost rather than govern it. ### Reviewer Inconsistency If reviewers do not apply the new class and lane rules consistently, heavy-family drift will return quickly. ### Hidden Cost Inside Ordinary Files Some heavy behavior is only visible through runtime breadth, so directory rules alone can miss expensive mixed files unless drift guards are strong enough. ## Rollout Guidance - Inventory the heavy families before changing structure. - Finalize the class model and lane rules before large mechanical moves. - Move the broadest and most obviously misplaced heavy families first. - Add drift guards before the rollout is considered complete. - Validate faster lanes and Heavy Governance separately after segmentation. - Document author and reviewer guidance only after the class model and lane rules are stable. - Avoid broad mechanical relocation before the semantic boundaries are explicit. ## Design Rules - **Heavy must be explicit**: A broad UI, surface, or discovery family must never look like an ordinary test by accident. - **Fast feedback stays fast**: Fast Feedback must not inherit deliberate governance-wide Filament or Livewire cost. - **Confidence keeps real trust**: Confidence must still carry meaningful UI-Light and selected UI-Workflow safety. - **Discovery is governance**: Broad discovery and reflection families are governance checks, not convenience coverage. - **Browser is always separate**: Browser remains its own class and lane. - **Classification beats directory folklore**: The real test character decides placement, not the folder name alone. - **Reviewer intent must be immediate**: A reviewer must be able to see why a heavy test belongs where it does. ## Key Entities *(include if feature involves data)* - **Heavy Test Class**: A repository-defined cost and purpose category used to describe a UI-related test family's expected behavior and lane fit. - **Heavy Test Family**: A named cluster of related tests, usually sharing a surface, workflow, discovery pattern, or governance concern. - **Lane Mapping Rule**: A checked-in rule that defines which test classes may or may not appear in each operational lane. - **Drift Guard**: A validation path that detects when a test family is assigned to a lane that conflicts with its class. - **Heavy Budget View**: The reporting signal that shows the runtime budget, top hotspots, and attribution for heavy families and their lane. ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: Every heavy Filament, Livewire, surface, or discovery family targeted by this rollout is classified, assigned a target lane, and documented with no unclassified exceptions remaining in the touched scope. - **SC-002**: Fast Feedback contains zero Discovery-Heavy families and zero broad Surface-Guard families after segmentation. - **SC-003**: Confidence contains only documented UI-Light families and explicitly selected UI-Workflow families, with zero undocumented heavy-governance exceptions. - **SC-004**: Heavy Governance reporting exposes at least the top 10 runtime hotspots with named family or class attribution. - **SC-005**: Wrong-lane placement for Browser, Discovery-Heavy, or broad Surface-Guard families is detected by a checked-in validation path before those tests become accepted lane members. - **SC-006**: Fast Feedback and Confidence are stable or improved against their post-Spec 207 baselines after segmentation, Fast Feedback remains lower wall-clock than Confidence and Heavy Governance in wrapper validation, and the documented UI safety coverage assigned to each lane remains intact. - **SC-007**: A reviewer can classify a newly added heavy UI-related test using checked-in guidance alone, without relying on undocumented local knowledge.