182 lines
18 KiB
Markdown
182 lines
18 KiB
Markdown
# 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.
|
|
|
|
- [X] 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`
|
|
- [X] 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`
|
|
- [X] 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.
|
|
|
|
- [X] 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`
|
|
- [X] 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
|
|
- [X] 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
|
|
- [X] 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
|
|
|
|
- [X] 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`
|
|
- [X] 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
|
|
|
|
- [X] 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`
|
|
- [X] 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
|
|
- [X] 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
|
|
|
|
- [X] 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
|
|
- [X] 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
|
|
- [X] 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
|
|
|
|
- [X] 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
|
|
- [X] 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
|
|
- [X] 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
|
|
- [X] T019 [US2] Record decomposition results, residual causes, and slimming decisions for the workflow-heavy hotspot families in `apps/platform/tests/Support/TestLaneManifest.php`
|
|
- [X] 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
|
|
|
|
- [X] 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
|
|
- [X] 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
|
|
|
|
- [X] 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
|
|
- [X] 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
|
|
- [X] 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`
|
|
- [X] 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
|
|
- [X] 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
|
|
- [X] 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
|
|
|
|
- [X] 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
|
|
- [X] 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
|
|
|
|
- [X] T031 [US4] Add canonical heavy-author guidance rules and anti-pattern signals to `apps/platform/tests/Support/TestLaneManifest.php`
|
|
- [X] 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.
|
|
|
|
- [X] 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 ...`
|
|
- [X] 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
|
|
- [X] T035 Run formatting for `apps/platform/` with `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
|
|
- [X] 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. |