Ahmed Darrazi c61af23827 feat: implement heavy governance cost recovery

2026-04-17 15:15:23 +02:00

18 KiB

Raw Blame History

Tasks: Heavy Governance Lane Cost Reduction

Input: Design documents from /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/209-heavy-governance-cost/ 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 coverage and focused validation through Sail.

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

Phase 1: Setup (Shared Context)

Purpose: Refresh and confirm the current heavy-governance budget inputs, artifact contract, and hotspot families before changing shared seams.

T001 Refresh the current heavy-governance baseline by rerunning scripts/platform-test-lane and scripts/platform-test-report before family edits, then audit the refreshed artifacts in apps/platform/storage/logs/test-lanes/heavy-governance-latest.summary.md, apps/platform/storage/logs/test-lanes/heavy-governance-latest.budget.json, and apps/platform/storage/logs/test-lanes/heavy-governance-latest.report.json
T002 [P] Review the current heavy-lane seams in apps/platform/tests/Support/TestLaneManifest.php, apps/platform/tests/Support/TestLaneBudget.php, apps/platform/tests/Support/TestLaneReport.php, scripts/platform-test-lane, and scripts/platform-test-report
T003 [P] Review the primary hotspot families in apps/platform/tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php, apps/platform/tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php, apps/platform/tests/Feature/Filament/BaselineActionAuthorizationTest.php, apps/platform/tests/Feature/Findings/FindingWorkflowRowActionsTest.php, apps/platform/tests/Feature/Findings/FindingWorkflowViewActionsTest.php, and apps/platform/tests/Feature/Findings/FindingBulkActionsTest.php

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Add the shared manifest, budget, report, and wrapper seams that all user stories depend on.

Critical: No user story work should begin until this phase is complete.

T004 Extend apps/platform/tests/Support/TestLaneManifest.php with neutral accessors for the heavy-governance budget contract, hotspot inventory records, decomposition records, slimming decisions, and budget outcome placeholders aligned to specs/209-heavy-governance-cost/contracts/heavy-governance-hotspot-inventory.schema.json
T005 [P] Extend apps/platform/tests/Support/TestLaneBudget.php and apps/platform/tests/Support/TestLaneReport.php with neutral helpers for normalized heavy-governance thresholds, snapshot comparison, and explicit recovered or recalibrated outcomes
T006 [P] Update apps/platform/tests/Feature/Guards/TestLaneManifestTest.php, apps/platform/tests/Feature/Guards/TestLaneArtifactsContractTest.php, and apps/platform/tests/Feature/Guards/TestLaneCommandContractTest.php to accept the expanded heavy-governance inventory, snapshot, and budget outcome metadata shape
T007 [P] Update scripts/platform-test-lane and scripts/platform-test-report so heavy-governance baseline and rerun artifacts can be refreshed consistently under apps/platform/storage/logs/test-lanes

Checkpoint: Shared heavy-governance seams are ready for story-specific implementation.

Phase 3: User Story 1 - Inventory Heavy Governance Hotspots (Priority: P1)

Goal: Seed a checked-in hotspot inventory that names the dominant heavy-governance families, their measured cost, and the authoritative pre-normalization budget contract plus legacy drift signal that must be normalized.

Independent Test: Run the heavy-governance report path and confirm the manifest and artifacts expose the dominant families, their cost-driver categories, and the current budget signals.

Tests for User Story 1

T008 [P] [US1] Expand apps/platform/tests/Feature/Guards/HeavyGovernanceLaneContractTest.php to assert the top heavy-governance families, priority tiers, the authoritative pre-normalization 300s threshold, the visible legacy 200s drift signal, and lane-membership invariants for touched families are exposed from apps/platform/tests/Support/TestLaneManifest.php
T009 [P] [US1] Expand apps/platform/tests/Feature/Guards/ProfileLaneContractTest.php and apps/platform/tests/Feature/Guards/TestLaneArtifactsContractTest.php to assert heavy-governance reports surface top 10 hotspots, family totals, classification totals, inventory coverage for the top 5 families or at least 80% of runtime, whichever is larger, and snapshot artifact paths under apps/platform/storage/logs/test-lanes

Implementation for User Story 1

T010 [US1] Populate the canonical hotspot inventory and current heavy-governance budget contract in apps/platform/tests/Support/TestLaneManifest.php for the current top 5 heavy families by runtime, or enough families to explain at least 80% of runtime, whichever set is larger, including baseline-profile-start-surfaces, findings-workflow-surfaces, finding-bulk-actions-workflow, action-surface-contract, ops-ux-governance, and workspace-settings-slice-management
T011 [US1] Extend apps/platform/tests/Support/TestLaneReport.php to emit coverage-oriented heavy-governance snapshot data that explains the top 5 families or at least 80% of lane runtime, whichever is larger, and reports whether the inclusion rule is satisfied
T012 [US1] Align the measured hotspot baseline and reviewer-facing inventory summary in specs/209-heavy-governance-cost/quickstart.md with the canonical inventory stored in apps/platform/tests/Support/TestLaneManifest.php, including the authoritative pre-normalization 300s threshold and the legacy 200s drift signal

Checkpoint: User Story 1 is complete when the dominant heavy-governance hotspots are reviewable and contract-tested without yet changing the family internals.

Phase 4: User Story 2 - Slim Overbroad Heavy Families Without Losing Trust (Priority: P1)

Goal: Reduce duplicated work and accidental breadth in the dominant heavy families while preserving their governance guarantees.

Independent Test: Refactor the targeted hotspot families, run the focused packs, and confirm the resulting families keep their guard intent while shedding repeated work.

Tests for User Story 2

T013 [P] [US2] Expand focused regression coverage in apps/platform/tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php, apps/platform/tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php, and apps/platform/tests/Feature/Filament/BaselineActionAuthorizationTest.php to lock baseline start-surface guard behavior before slimming
T014 [P] [US2] Expand focused regression coverage in apps/platform/tests/Feature/Findings/FindingBulkActionsTest.php, apps/platform/tests/Feature/Findings/FindingWorkflowRowActionsTest.php, apps/platform/tests/Feature/Findings/FindingWorkflowViewActionsTest.php, apps/platform/tests/Feature/Findings/FindingsListFiltersTest.php, and apps/platform/tests/Feature/Findings/FindingExceptionRenewalTest.php to lock workflow, filter, and audit behavior before decomposition
T015 [P] [US2] Expand apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php and apps/platform/tests/Feature/Guards/OperationLifecycleOpsUxGuardTest.php to preserve current governance invariants if second-wave surface-guard slimming becomes necessary

Implementation for User Story 2

T016 [US2] Decompose the baseline-profile-start-surfaces family across apps/platform/tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php, apps/platform/tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php, and apps/platform/tests/Feature/Filament/BaselineActionAuthorizationTest.php to remove repeated Livewire mounts and gating matrices while preserving authorization and rollout guards
T017 [P] [US2] Slim the findings-workflow-surfaces family in apps/platform/tests/Feature/Findings/FindingWorkflowRowActionsTest.php, apps/platform/tests/Feature/Findings/FindingWorkflowViewActionsTest.php, apps/platform/tests/Feature/Findings/FindingsListFiltersTest.php, and apps/platform/tests/Feature/Findings/FindingExceptionRenewalTest.php by separating required workflow trust from repeated surface or filter work
T018 [P] [US2] Slim the finding-bulk-actions-workflow family in apps/platform/tests/Feature/Findings/FindingBulkActionsTest.php to remove duplicated bulk-action setup and audit fan-out without weakening per-record workflow guarantees
T019 [US2] Record decomposition results, residual causes, and slimming decisions for the workflow-heavy hotspot families in apps/platform/tests/Support/TestLaneManifest.php
T020 [US2] Audit apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php, apps/platform/tests/Feature/Guards/OperationLifecycleOpsUxGuardTest.php, apps/platform/tests/Feature/OpsUx/OperationCatalogCoverageTest.php, apps/platform/tests/Feature/OpsUx/OperateHubShellTest.php, and apps/platform/tests/Feature/OpsUx/ActiveRunsTest.php to either identify removable duplication or explicitly retain them as intentionally heavy in apps/platform/tests/Support/TestLaneManifest.php

Checkpoint: User Story 2 is complete when the primary workflow-heavy hotspot families are slimmer, their trust boundaries are explicit, and any intentionally retained heavy families are documented as such.

Phase 5: User Story 3 - Resolve Heavy Lane Budget Failure Explicitly (Priority: P2)

Goal: Normalize the heavy-governance budget contract, rerun the lane, and end with an explicit recovered or recalibrated outcome.

Independent Test: Rerun the heavy-governance lane after the slimming pass and confirm the updated artifacts expose one authoritative threshold, before-and-after deltas, and an explicit budget decision.

Tests for User Story 3

T021 [P] [US3] Expand apps/platform/tests/Feature/Guards/HeavyGovernanceLaneContractTest.php and apps/platform/tests/Feature/Guards/FixtureLaneImpactBudgetTest.php to assert one authoritative heavy-governance threshold, explicit budget decision status, and remaining-open-family reporting
T022 [P] [US3] Expand apps/platform/tests/Feature/Guards/ProfileLaneContractTest.php and apps/platform/tests/Feature/Guards/TestLaneArtifactsContractTest.php to assert baseline and post-change heavy-governance snapshots plus final budget outcome artifacts under apps/platform/storage/logs/test-lanes, including non-conflicting threshold and outcome values across summary, budget, and report outputs

Implementation for User Story 3

T023 [US3] Normalize the heavy-governance budget contract in apps/platform/tests/Support/TestLaneBudget.php and apps/platform/tests/Support/TestLaneManifest.php so the authoritative pre-normalization 300s summary threshold and the legacy 200s detailed budget evaluation resolve to one authoritative threshold and lifecycle state
T024 [US3] Extend apps/platform/tests/Support/TestLaneReport.php to emit baseline or post-change deltas, remaining open families, and explicit recovered or recalibrated budget outcome records
T025 [US3] Audit apps/platform/tests/Feature/SettingsFoundation/WorkspaceSettingsManageTest.php as the first fallback ui-workflow hotspot and either narrow duplicated work or record it as retained residual cost in apps/platform/tests/Support/TestLaneManifest.php
T026 [US3] Update scripts/platform-test-lane and scripts/platform-test-report so heavy-governance baseline capture and rerun reporting produce consistent summary, budget, and report artifacts for the final decision
T027 [US3] Refresh apps/platform/storage/logs/test-lanes/heavy-governance-latest.summary.md, apps/platform/storage/logs/test-lanes/heavy-governance-latest.budget.json, and apps/platform/storage/logs/test-lanes/heavy-governance-latest.report.json by rerunning the heavy-governance lane after the slimming pass and confirming the refreshed artifacts agree on the final threshold and budget outcome classification
T028 [US3] Record the final heavy-governance recovery or recalibration rationale in apps/platform/tests/Support/TestLaneManifest.php and specs/209-heavy-governance-cost/quickstart.md

Checkpoint: User Story 3 is complete when the heavy-governance lane exposes one authoritative budget contract and a final explicit budget decision backed by refreshed artifacts.

Phase 6: User Story 4 - Guide Future Heavy Test Authors (Priority: P2)

Goal: Leave behind short, enforceable rules that stop new heavy-governance tests from recreating the same overbroad patterns.

Independent Test: Review the manifest guidance and taxonomy guards to confirm a reviewer can decide whether a new heavy test belongs in an existing family, needs a new family, or must be split.

Tests for User Story 4

T029 [P] [US4] Expand apps/platform/tests/Feature/Guards/TestLaneManifestTest.php to assert the heavy author-guidance rules cover new-family creation, family reuse, overbroad tests, and separation of discovery, workflow, and surface trust
T030 [P] [US4] Expand apps/platform/tests/Feature/Guards/TestTaxonomyPlacementGuardTest.php and apps/platform/tests/Feature/Guards/HeavyGovernanceLaneContractTest.php to require a valid family or guidance-backed classification decision for future heavy-governance additions

Implementation for User Story 4

T031 [US4] Add canonical heavy-author guidance rules and anti-pattern signals to apps/platform/tests/Support/TestLaneManifest.php
T032 [US4] Publish reviewer-facing heavy-family guidance and residual-debt rules in specs/209-heavy-governance-cost/quickstart.md and keep the canonical wording synchronized with apps/platform/tests/Support/TestLaneManifest.php

Checkpoint: User Story 4 is complete when future heavy-governance additions have explicit guidance and guard-backed review rules.

Phase 7: Polish & Cross-Cutting Concerns

Purpose: Validate the end-to-end rollout, format the code, and remove superseded notes after the heavy-lane decision is settled.

T033 Run focused Pest coverage for apps/platform/tests/Feature/Guards/HeavyGovernanceLaneContractTest.php, apps/platform/tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php, apps/platform/tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php, apps/platform/tests/Feature/Filament/BaselineActionAuthorizationTest.php, apps/platform/tests/Feature/Findings/FindingBulkActionsTest.php, apps/platform/tests/Feature/Findings/FindingWorkflowRowActionsTest.php, apps/platform/tests/Feature/Findings/FindingWorkflowViewActionsTest.php, apps/platform/tests/Feature/Findings/FindingsListFiltersTest.php, apps/platform/tests/Feature/Findings/FindingExceptionRenewalTest.php, and apps/platform/tests/Feature/SettingsFoundation/WorkspaceSettingsManageTest.php with cd apps/platform && ./vendor/bin/sail artisan test --compact ...
T034 Run heavy-governance wrapper validation via scripts/platform-test-lane, scripts/platform-test-report, and inspect apps/platform/storage/logs/test-lanes/heavy-governance-latest.summary.md, apps/platform/storage/logs/test-lanes/heavy-governance-latest.budget.json, and apps/platform/storage/logs/test-lanes/heavy-governance-latest.report.json to confirm the final budget outcome and a non-conflicting threshold or outcome contract across all three artifacts
T035 Run formatting for apps/platform/ with cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
T036 Remove stale dual-threshold comments, superseded family notes, and obsolete draft placeholders in apps/platform/tests/Support/TestLaneManifest.php, apps/platform/tests/Support/TestLaneBudget.php, apps/platform/tests/Support/TestLaneReport.php, and specs/209-heavy-governance-cost/quickstart.md

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 slimming decisions require the canonical hotspot inventory and decomposition scaffolding.
User Story 3 depends on User Story 1 and User Story 2 because the explicit budget decision depends on the updated inventory and the slimming pass.
User Story 4 depends on User Story 1 and User Story 3 because the final guidance should reflect the authoritative family model and the settled budget contract.
Phase 7 depends on all user stories.

Parallel Execution Examples

User Story 1

Run T008 and T009 in parallel to lock the inventory and artifact-report contracts.
After T010 lands, T011 and T012 can proceed in parallel across report output and reviewer-facing guidance.

User Story 2

Run T013, T014, and T015 in parallel because they lock separate hotspot families before slimming.
After T016 lands, T017 and T018 can run in parallel across findings workflow and bulk-action families.

User Story 3

Run T021 and T022 in parallel because they cover budget-contract and artifact-outcome guards separately.
After T023 lands, T024 and T026 can run in parallel across report generation and wrapper reporting.

User Story 4

Run T029 and T030 in parallel because they enforce different review surfaces.
After T031 lands, T032 can publish the final wording in the quickstart guidance.

Implementation Strategy

MVP First

Deliver User Story 1 first to establish the canonical hotspot inventory and the current heavy-governance budget signal.
Deliver User Story 2 next to produce the first real runtime recovery by narrowing the dominant workflow-heavy families.

Incremental Delivery

Add User Story 3 after the primary slimming pass so the budget decision reflects real runtime changes rather than a draft threshold.
Add User Story 4 last so the guidance codifies the final family model and budget contract.

Validation Sequence

Use focused hotspot tests first, then guard suites, then heavy-governance wrapper reruns, and only then refresh formatting and stale-note cleanup.
Treat apps/platform/storage/logs/test-lanes/ as the canonical artifact root throughout validation and budget review.

18 KiB Raw Blame History