ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
49fe4626e8
TenantAtlas/specs/208-heavy-suite-segmentation/tasks.md
Ahmed Darrazi 49fe4626e8 Spec 208: finalize heavy suite segmentation
2026-04-17 11:44:04 +02:00

17 KiB
Raw Blame History

Tasks: Filament/Livewire Heavy Suite Segmentation

Input: Design documents from /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/208-heavy-suite-segmentation/ Prerequisites: plan.md (required), spec.md (required), research.md, data-model.md, contracts/, quickstart.md

Tests: Required. This feature changes repository test-governance behavior, so each user story includes Pest guard or contract coverage and focused validation runs through Sail.

Organization: Tasks are grouped by user story so each story can be implemented and validated independently.

Phase 1: Setup (Shared Context)

Purpose: Confirm the existing lane seams, guard anchors, and hotspot files that Spec 208 will segment.

  • T001 Audit lane command and artifact entry points in apps/platform/composer.json, scripts/platform-test-lane, and scripts/platform-test-report
  • T002 [P] Review the current manifest and shared guard anchors in apps/platform/tests/Support/TestLaneManifest.php, apps/platform/tests/Feature/Guards/TestLaneManifestTest.php, and apps/platform/tests/Feature/Guards/TestLaneArtifactsContractTest.php
  • T003 [P] Review the seeded hotspot clusters in apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php, apps/platform/tests/Feature/Filament/PolicyResourceAdminSearchParityTest.php, apps/platform/tests/Feature/Baselines/BaselineCompareMatrixCompareAllActionTest.php, apps/platform/tests/Feature/Rbac/BackupItemsRelationManagerUiEnforcementTest.php, apps/platform/tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php, apps/platform/tests/Feature/Filament/TenantReviewHeaderDisciplineTest.php, apps/platform/tests/Feature/Filament/PanelNavigationSegregationTest.php, and apps/platform/tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Add the shared manifest and artifact seams that all user stories rely on.

Critical: No user story work should begin until these tasks are complete.

  • T004 Extend apps/platform/tests/Support/TestLaneManifest.php with neutral accessors for classification catalogs, family inventory, lane placement rules, and mixed-file resolution to back the logical read operations in specs/208-heavy-suite-segmentation/contracts/heavy-suite-segmentation.logical.openapi.yaml
  • T005 [P] Update apps/platform/tests/Feature/Guards/TestLaneManifestTest.php to accept the expanded manifest metadata shape without locking story-specific families yet
  • T006 [P] Update apps/platform/tests/Feature/Guards/TestLaneArtifactsContractTest.php to reserve class and family attribution keys under apps/platform/storage/logs/test-lanes/

Checkpoint: Shared manifest and artifact seams are ready for story-specific implementation.

Phase 3: User Story 1 - Classify Existing Heavy UI Families (Priority: P1)

Goal: Seed a checked-in heavy-family catalog that names the first heavy Filament, Livewire, surface, discovery, and browser families with explicit purpose and lane intent.

Independent Test: Review the manifest inventory and guard coverage to confirm each seeded family has a class, purpose, current lane, target lane, selectors, hotspot files, and validation status.

Tests for User Story 1

  • T007 [P] [US1] Expand apps/platform/tests/Feature/Guards/TestTaxonomyPlacementGuardTest.php to assert the five-class catalog, allowed lanes, and forbidden lane semantics from specs/208-heavy-suite-segmentation/contracts/heavy-test-classification.schema.json
  • T008 [P] [US1] Expand apps/platform/tests/Feature/Guards/TestLaneManifestTest.php to assert every seeded heavy family in apps/platform/tests/Support/TestLaneManifest.php exposes purpose, current lane, target lane, selectors, hotspot files, validation status, and confidence rationale whenever the target lane is confidence

Implementation for User Story 1

  • T009 [US1] Populate the ui-light, ui-workflow, surface-guard, discovery-heavy, and browser catalog plus lane placement rules in apps/platform/tests/Support/TestLaneManifest.php and expose the classification catalog through the logical read surface defined in specs/208-heavy-suite-segmentation/contracts/heavy-suite-segmentation.logical.openapi.yaml
  • T010 [US1] Seed the first heavy family inventory in apps/platform/tests/Support/TestLaneManifest.php using apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php, apps/platform/tests/Feature/Filament/PolicyResourceAdminSearchParityTest.php, apps/platform/tests/Feature/Baselines/BaselineCompareMatrixCompareAllActionTest.php, apps/platform/tests/Feature/Rbac/BackupItemsRelationManagerUiEnforcementTest.php, apps/platform/tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php, apps/platform/tests/Feature/Filament/TenantReviewHeaderDisciplineTest.php, apps/platform/tests/Feature/Filament/PanelNavigationSegregationTest.php, and apps/platform/tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php, and expose the family inventory through the logical read surface defined in specs/208-heavy-suite-segmentation/contracts/heavy-suite-segmentation.logical.openapi.yaml
  • T011 [US1] Record mixed-file resolution and hotspot cost signals in apps/platform/tests/Support/TestLaneManifest.php for apps/platform/tests/Feature/Filament/PolicyVersionAdminSearchParityTest.php, apps/platform/tests/Feature/Baselines/BaselineCompareMatrixBuilderTest.php, and apps/platform/tests/Feature/Concerns/BuildsBaselineCompareMatrixFixtures.php, and keep those records consistent with specs/208-heavy-suite-segmentation/contracts/heavy-test-classification.schema.json and specs/208-heavy-suite-segmentation/contracts/heavy-suite-segmentation.logical.openapi.yaml
  • T012 [US1] Align the seeded family inventory examples in specs/208-heavy-suite-segmentation/quickstart.md with the canonical catalog stored in apps/platform/tests/Support/TestLaneManifest.php without publishing final reviewer guidance yet

Checkpoint: User Story 1 is complete when the seeded heavy-family inventory is reviewable and contract-tested without changing lane membership yet.

Phase 4: User Story 2 - Keep Fast And Confidence Lanes Honest (Priority: P1)

Goal: Move discovery-heavy and broad surface-guard families out of Fast Feedback and ordinary Confidence while preserving documented ui-light and selected ui-workflow trust.

Independent Test: Run the lane contract guards and wrapper flows to verify Fast Feedback excludes discovery-heavy and broad surface-guard families, Confidence retains only the documented light or workflow families, and Heavy Governance receives the moved families.

Tests for User Story 2

  • T013 [P] [US2] Expand apps/platform/tests/Feature/Guards/FastFeedbackLaneContractTest.php and apps/platform/tests/Feature/Guards/FastFeedbackLaneExclusionTest.php to assert discovery-heavy and broad surface-guard families never run in Fast Feedback
  • T014 [P] [US2] Expand apps/platform/tests/Feature/Guards/ConfidenceLaneContractTest.php and apps/platform/tests/Feature/Guards/HeavyGovernanceLaneContractTest.php to assert only documented ui-light and selected ui-workflow families with explicit confidence rationale remain in Confidence while moved families land in Heavy Governance

Implementation for User Story 2

  • T015 [US2] Rework Fast Feedback, Confidence, and Heavy Governance membership rules in apps/platform/tests/Support/TestLaneManifest.php to consume the seeded family inventory instead of scattered file exclusions
  • T016 [US2] Add granular ui-light, ui-workflow, surface-guard, discovery-heavy, and browser grouping rules in apps/platform/tests/Pest.php for the seeded hotspot files
  • T017 [P] [US2] Reclassify discovery-heavy Filament parity hotspots in apps/platform/tests/Feature/Filament/PolicyResourceAdminSearchParityTest.php and apps/platform/tests/Feature/Filament/PolicyVersionAdminSearchParityTest.php
  • T018 [P] [US2] Reclassify workflow and matrix hotspots in apps/platform/tests/Feature/Baselines/BaselineCompareMatrixCompareAllActionTest.php and apps/platform/tests/Feature/Baselines/BaselineCompareMatrixBuilderTest.php
  • T019 [P] [US2] Reclassify fixture-amplifying concern hotspots in apps/platform/tests/Feature/Concerns/BuildsBaselineCompareMatrixFixtures.php and apps/platform/tests/Feature/Concerns/BuildsPortfolioTriageFixtures.php
  • T020 [P] [US2] Reclassify broad relation-manager, RBAC, and wizard hotspots in apps/platform/tests/Feature/Rbac/BackupItemsRelationManagerUiEnforcementTest.php, apps/platform/tests/Feature/Rbac/WorkspaceMembershipsRelationManagerUiEnforcementTest.php, and apps/platform/tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php
  • T021 [US2] Reclassify header-action and navigation-discipline hotspots in apps/platform/tests/Feature/Filament/TenantReviewHeaderDisciplineTest.php and apps/platform/tests/Feature/Filament/PanelNavigationSegregationTest.php, then reconcile lane entry point metadata in apps/platform/composer.json and scripts/platform-test-lane with the segmented family selectors from apps/platform/tests/Support/TestLaneManifest.php

Checkpoint: User Story 2 is complete when lane membership is explainable from cataloged family rules and faster lanes no longer carry the prohibited heavy families.

Phase 5: User Story 3 - Catch Lane Drift During Review (Priority: P2)

Goal: Make wrong-lane placement fail clearly for Browser, Discovery-Heavy, and broad Surface-Guard families, with contributor guidance that keeps classification decisions reviewable.

Independent Test: Introduce a representative wrong-lane placement locally and confirm the guard suite fails with actionable output naming the violating class, family, or file.

Tests for User Story 3

  • T022 [P] [US3] Expand apps/platform/tests/Feature/Guards/BrowserLaneIsolationTest.php and apps/platform/tests/Feature/Guards/TestTaxonomyPlacementGuardTest.php to fail on browser misplacement and invalid class-to-lane mappings
  • T023 [P] [US3] Expand apps/platform/tests/Feature/Guards/ConfidenceLaneContractTest.php and apps/platform/tests/Feature/Guards/HeavyGovernanceLaneContractTest.php to cover mixed-file fallback and wrong-lane regression cases

Implementation for User Story 3

  • T024 [US3] Implement manifest-side lane placement validation and mixed-file resolution helpers in apps/platform/tests/Support/TestLaneManifest.php consistent with specs/208-heavy-suite-segmentation/contracts/heavy-suite-segmentation.logical.openapi.yaml
  • T025 [US3] Add failure-friendly family and class lookup output for guard consumers in apps/platform/tests/Support/TestLaneManifest.php and apps/platform/tests/Feature/Guards/TestLaneManifestTest.php
  • T026 [US3] Publish contributor and reviewer classification guidance in specs/208-heavy-suite-segmentation/quickstart.md and keep the canonical reviewer signals in apps/platform/tests/Support/TestLaneManifest.php

Checkpoint: User Story 3 is complete when wrong-lane drift fails automatically and reviewers can classify new heavy tests from checked-in guidance alone.

Phase 6: User Story 4 - Observe Heavy Budgets Separately (Priority: P2)

Goal: Attribute Heavy Governance cost by lane, class, and family so hotspot growth is visible without distorting the signal of faster lanes.

Independent Test: Generate heavy-governance report artifacts and confirm they expose the top hotspots, class attribution, family attribution, and budget evaluations under the existing artifact root.

Tests for User Story 4

  • T027 [P] [US4] Expand apps/platform/tests/Feature/Guards/TestLaneArtifactsContractTest.php and apps/platform/tests/Feature/Guards/ProfileLaneContractTest.php to assert heavy reports emit the canonical top 10 runtime hotspot view ordered by slowest entries plus class attribution, family attribution, and budget evaluation payloads
  • T028 [P] [US4] Expand apps/platform/tests/Feature/Guards/FixtureLaneImpactBudgetTest.php and apps/platform/tests/Feature/Guards/HeavyGovernanceLaneContractTest.php to assert lane-, class-, and family-level budget targets for Heavy Governance

Implementation for User Story 4

  • T029 [US4] Extend apps/platform/tests/Support/TestLaneBudget.php with lane, class, and family budget targets plus baseline sources, enforcement levels, and lifecycle states for the seeded heavy families
  • T030 [US4] Extend apps/platform/tests/Support/TestLaneReport.php to emit the canonical top 10 runtime hotspot view ordered by slowest entries, classification attribution, family attribution, budget evaluations, and artifact paths under apps/platform/storage/logs/test-lanes/ consistent with specs/208-heavy-suite-segmentation/contracts/heavy-suite-segmentation.logical.openapi.yaml
  • T031 [US4] Update scripts/platform-test-report and apps/platform/composer.json to surface the heavy attribution report contract emitted by apps/platform/tests/Support/TestLaneReport.php and preserve reviewable top 10 runtime hotspot output for Heavy Governance

Checkpoint: User Story 4 is complete when Heavy Governance artifacts explain slowdowns by class and family, not only by lane total.

Phase 7: Polish & Cross-Cutting Concerns

Purpose: Validate the end-to-end rollout, format the code, and remove superseded ad-hoc lane logic.

  • T032 Run focused Pest coverage for apps/platform/tests/Feature/Guards/, apps/platform/tests/Feature/Filament/, apps/platform/tests/Feature/Baselines/, and apps/platform/tests/Feature/Rbac/ with cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards tests/Feature/Filament tests/Feature/Baselines tests/Feature/Rbac
  • T033 Run lane wrapper validation with scripts/platform-test-lane and scripts/platform-test-report, compare Fast Feedback and Confidence against the post-Spec 207 baselines, confirm Fast Feedback measures lower wall-clock than Confidence and Heavy Governance, record Heavy Governance threshold or refreshed baseline evidence, and inspect emitted artifacts under apps/platform/storage/logs/test-lanes/
  • T034 Run formatting for apps/platform/ with cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
  • T035 Remove stale ad-hoc lane comments or exclusions in apps/platform/tests/Pest.php, apps/platform/tests/Support/TestLaneManifest.php, and apps/platform/tests/Support/TestLaneBudget.php once the segmented catalog is authoritative

Dependencies

  • Phase 1 must complete before Phase 2.
  • Phase 2 must complete before any user story work begins.
  • User Story 1 is the MVP and must complete before User Story 2, User Story 3, or User Story 4.
  • User Story 2 depends on User Story 1 because lane membership must consume the seeded family inventory.
  • User Story 3 depends on User Story 1 and User Story 2 because drift validation relies on the final catalog and lane mappings.
  • User Story 4 depends on User Story 1 and User Story 2 because report attribution relies on the seeded family inventory and segmented lane ownership.
  • Phase 7 depends on all user stories.

Parallel Execution Examples

User Story 1

  • Run T007 and T008 in parallel to lock the schema and inventory guard coverage.
  • After T009 lands, T010 and T011 can be split between seeded family inventory work and mixed-file resolution work.

User Story 2

  • Run T013 and T014 in parallel because they cover different lane guard files.
  • After T015 and T016 land, T017, T018, T019, and T020 can run in parallel across Filament, Baselines, Concerns, and RBAC hotspots.

User Story 3

  • Run T022 and T023 in parallel because they touch separate guard surfaces.
  • T024 should land before T025 and T026 so the guidance and failure output describe the actual validation helpers.

User Story 4

  • Run T027 and T028 in parallel because artifact-contract and budget-guard coverage live in different test files.
  • After T029 lands, T030 and T031 can be split between report payload generation and wrapper exposure work.

Implementation Strategy

MVP First

  • Deliver User Story 1 first to establish the canonical heavy-family catalog, seeded inventory, and reviewable hotspot metadata.
  • Deliver User Story 2 next to produce the first operational benefit by keeping Fast Feedback and Confidence honest.

Incremental Delivery

  • Add User Story 3 after lane segmentation so drift protection describes the real final placement rules instead of a temporary draft.
  • Add User Story 4 after the lane moves settle so the attribution model reflects stable family ownership and budget targets.

Validation Sequence

  • Use focused guard suites first, then targeted hotspot files, then the lane wrappers, and only then refresh formatting and stale exclusion cleanup.
  • Treat apps/platform/storage/logs/test-lanes/ as the canonical artifact root throughout validation and report review.