TenantAtlas/specs/209-heavy-governance-cost/plan.md

# Implementation Plan: Heavy Governance Lane Cost Reduction

**Branch**: `209-heavy-governance-cost` | **Date**: 2026-04-17 | **Spec**: `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/209-heavy-governance-cost/spec.md`
**Input**: Feature specification from `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/209-heavy-governance-cost/spec.md`

## Summary

Build Spec 209 on top of the existing Spec 206, 207, and 208 lane infrastructure by using the current heavy-governance artifact set as the baseline, treating the current `300s` lane summary threshold as the authoritative pre-normalization contract while the `200s` `budgetTargets()` signal remains legacy drift evidence to be reconciled, decomposing the dominant heavy families by trust type and duplicated work, targeting the ui-workflow hotspots first, treating surface-guard families as intentional heavy checks unless repeatable redundancy is proven, and ending with explicit budget recovery or explicit recalibration evidence without moving heavy cost back into lighter lanes.

## Technical Context

**Language/Version**: PHP 8.4.15  
**Primary Dependencies**: Laravel 12, Pest v4, PHPUnit 12, Filament v5, Livewire v4, Laravel Sail  
**Storage**: SQLite `:memory:` for the default test environment, mixed database strategy for some heavy-governance families as declared in `TestLaneManifest`, and existing lane artifacts under the app-root contract path `storage/logs/test-lanes`  
**Testing**: Pest unit, feature, browser, architecture, and guard suites run through Sail-wrapped `artisan test`; heavy-lane selection and reporting already flow through `Tests\Support\TestLaneManifest`, `Tests\Support\TestLaneBudget`, `Tests\Support\TestLaneReport`, `tests/Pest.php`, and the repo-root wrappers `scripts/platform-test-lane` and `scripts/platform-test-report`  
**Target Platform**: Laravel monorepo application in `apps/platform`, executed locally through Sail and later enforced in shared CI  
**Project Type**: Monorepo with a Laravel platform app and separate Astro website; this feature is scoped to platform test-governance infrastructure  
**Performance Goals**: Recover the heavy-governance lane from the current `318.296962s` run to the authoritative pre-normalization heavy-lane threshold of `300s`, or explicitly recalibrate that threshold after evidence is gathered; explain at least 80% of heavy-lane runtime through named families; reduce duplicate work or accidental breadth in the top hotspot families without reducing governance trust  
**Constraints**: Sail-first commands only; no new product routes, assets, runtime services, or dependencies; no browser-lane redesign; no CI-matrix rollout; no lane-hiding by moving heavy families into Confidence or Fast Feedback; preserve Heavy Governance lane membership for touched families unless a non-budget, spec-backed rationale is recorded; treat the current `300s` lane summary threshold as the authoritative pre-normalization contract while the `200s` lane budget-target evaluation remains legacy drift evidence to be normalized  
**Scale/Scope**: Current heavy-governance reporting attributes 14 named families; `ui-workflow` accounts for `190.606431s`, `surface-guard` for `106.845887s`, and `discovery-heavy` for `0.863003s`; the dominant family hotspots are `baseline-profile-start-surfaces` (`98.112193s`), `action-surface-contract` (`40.841552s`), `ops-ux-governance` (`38.794861s`), `findings-workflow-surfaces` (`36.459493s`), `finding-bulk-actions-workflow` (`26.491446s`), and `workspace-settings-slice-management` (`21.740839s`)

### Filament v5 Implementation Notes

- **Livewire v4.0+ compliance**: Preserved. This feature changes only repository test-governance around Filament and Livewire-heavy tests, not runtime Filament or Livewire behavior.
- **Provider registration location**: Unchanged. Existing panel providers remain registered in `bootstrap/providers.php`.
- **Global search rule**: No globally searchable resources are added or modified. Discovery-heavy parity tests may be reclassified or slimmed, but runtime global-search behavior is unchanged.
- **Destructive actions**: No runtime destructive actions are introduced. Any tests touched by this feature continue to validate existing confirmation and authorization behavior only.
- **Asset strategy**: No panel-only or shared assets are added. Existing `filament:assets` deployment behavior remains unchanged.
- **Testing plan**: Add or update Pest guard coverage for heavy-hotspot inventory integrity, budget-signal consistency, family decomposition records, heavy-lane budget outcome reporting, and targeted hotspot family regression checks. Focused validation should cover the targeted families plus the heavy-governance lane wrapper.

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- Inventory-first: PASS. No Inventory, snapshots, or backup truth is changed.
- Read/write separation: PASS. The feature only changes repository test-governance behavior and introduces no end-user mutation path.
- Graph contract path: PASS. No Graph calls, contract-registry changes, or provider runtime integrations are added.
- Deterministic capabilities: PASS. No capability resolver or authorization registry changes.
- RBAC-UX, workspace isolation, tenant isolation: PASS. No runtime routes, policies, global search availability, or tenant/workspace enforcement semantics are changed.
- Run observability and Ops-UX: PASS. Reporting remains filesystem-based through the existing lane tooling and does not introduce `OperationRun` behavior.
- Data minimization: PASS. Heavy-lane inventories and reports remain repo-local and contain no secrets or customer payloads.
- Proportionality and bloat control: PASS WITH LIMITS. The only new semantic layer is a narrow repo-local hotspot inventory and decomposition model. The plan explicitly avoids a broader framework and keeps family changes tied to measured cost and guard preservation.
- TEST-TRUTH-001: PASS WITH WORK. The plan must prove that runtime gains come from removing duplicated work or accidental breadth rather than from quietly deleting governance trust.
- Filament/UI constitutions: PASS / NOT APPLICABLE. No operator-facing UI, action-surface runtime contract, badge semantics, or panel IA is changed.

**Phase 0 Gate Result**: PASS

- The feature remains bounded to repository test governance, hotspot evidence, family decomposition, and budget normalization.
- No new runtime persistence, product routes, panels, assets, or Graph seams are introduced.
- The chosen approach extends the existing Spec 206 to 208 tooling instead of creating a second heavy-lane governance system.

## Project Structure

### Documentation (this feature)

```text
specs/209-heavy-governance-cost/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   ├── heavy-governance-hotspot-inventory.schema.json
│   └── heavy-governance-cost-recovery.logical.openapi.yaml
└── tasks.md
```

### Source Code (repository root)

```text
apps/
├── platform/
│   ├── composer.json
│   ├── tests/
│   │   ├── Pest.php
│   │   ├── Support/
│   │   │   ├── TestLaneBudget.php
│   │   │   ├── TestLaneManifest.php
│   │   │   └── TestLaneReport.php
│   │   ├── Feature/
│   │   │   ├── Baselines/
│   │   │   ├── Drift/
│   │   │   ├── Filament/
│   │   │   ├── Findings/
│   │   │   ├── Guards/
│   │   │   ├── OpsUx/
│   │   │   ├── Rbac/
│   │   │   └── SettingsFoundation/
│   └── storage/logs/test-lanes/
├── website/
└── ...
scripts/
├── platform-test-lane
└── platform-test-report
```

**Structure Decision**: Keep implementation concentrated in the existing platform test-governance seams: `apps/platform/tests/Support/TestLaneManifest.php` for hotspot inventory, family budgets, and budget-signal normalization; `apps/platform/tests/Support/TestLaneReport.php` for before-and-after attribution and explicit budget outcomes; focused heavy families under `apps/platform/tests/Feature/Baselines`, `apps/platform/tests/Feature/Filament`, `apps/platform/tests/Feature/Findings`, `apps/platform/tests/Feature/Guards`, `apps/platform/tests/Feature/OpsUx`, and `apps/platform/tests/Feature/SettingsFoundation`; and the existing repo-root wrappers for measurement. Planning artifacts stay inside `specs/209-heavy-governance-cost`.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| None | Not applicable | Not applicable |

## Proportionality Review

- **Current operator problem**: Maintainers and reviewers cannot tell which heavy-governance families are legitimately expensive, which are redundant, and which are simply overbroad, so the lane remains over budget without a stable correction path.
- **Existing structure is insufficient because**: Spec 208 established heavy-family ownership and attribution, but it did not yet decompose the internal cost of the dominant families or reconcile the current heavy-budget mismatch.
- **Narrowest correct implementation**: Extend the existing lane manifest, report artifacts, and heavy-family catalog with hotspot decomposition, explicit residual-cause records, a budget-outcome record, and targeted guidance for future heavy tests.
- **Ownership cost created**: The repo must maintain hotspot decomposition notes, the reconciled heavy-budget contract, and author or reviewer guidance as heavy families evolve.
- **Alternative intentionally rejected**: Local one-off runtime trims or moving families back into lighter lanes, because those approaches hide cost instead of making it governable.
- **Release truth**: Current-release repository truth and the necessary stabilization step before CI budget enforcement.

## Phase 0 — Research (complete)

- Output: [research.md](./research.md)
- Resolved key decisions:
  - Reuse the existing heavy-governance manifest, budget, report, and wrapper seams rather than creating a second heavy-lane system.
  - Treat the current heavy-governance artifact set as the baseline, specifically `318.296962s` wall-clock against the authoritative pre-normalization `300s` lane summary threshold.
  - Make the dual heavy-budget signal explicit: the lane summary uses `300s` as the authoritative pre-normalization contract, while `budgetTargets()` still evaluates the lane against `200s` as legacy drift evidence that must be normalized.
  - Prioritize `baseline-profile-start-surfaces`, `findings-workflow-surfaces`, and `finding-bulk-actions-workflow` as the first slimming targets because the `ui-workflow` classification currently dominates the lane.
  - Decompose targeted families by repeated work before splitting files mechanically.
  - Record helper-driven or fixture-driven cost as explicit residual debt when that is the real cause.
  - Treat `action-surface-contract` and `ops-ux-governance` as intentional heavy second-wave candidates unless repeated duplication is proven.
  - Keep before-and-after evidence inside the existing heavy-governance artifact set under `storage/logs/test-lanes`.
  - End the feature with explicit recovery or explicit recalibration, not an implicit “still heavy” state.

## Phase 1 — Design & Contracts (complete)

- Output: [data-model.md](./data-model.md) formalizes the hotspot inventory, per-family cost decomposition, slimming decisions, dual-budget contract, explicit budget outcome, and author-guidance rule set.
- Output: [contracts/heavy-governance-hotspot-inventory.schema.json](./contracts/heavy-governance-hotspot-inventory.schema.json) defines the checked-in schema for the heavy-governance hotspot inventory, decomposition records, budget signals, and final outcome contract.
- Output: [contracts/heavy-governance-cost-recovery.logical.openapi.yaml](./contracts/heavy-governance-cost-recovery.logical.openapi.yaml) captures the logical contract for reading hotspots, recording family decomposition, evaluating budget outcomes, and publishing reviewer guidance.
- Output: [quickstart.md](./quickstart.md) provides the rollout order, validation commands, and review checkpoints for the cost-recovery work.

### Post-design Constitution Re-check

- PASS: No runtime routes, panels, authorization planes, or Graph seams are introduced.
- PASS: The new hotspot inventory and budget-outcome records are repo-local, directly justified by current lane drift, and bounded to existing test-governance seams.
- PASS: The design prefers extending existing manifest, guard, and reporting seams over adding a second governance framework.
- PASS WITH WORK: The final implementation must normalize the conflicting heavy-lane budget signals so reviewers see one intentional contract instead of two competing thresholds.
- PASS WITH WORK: The final implementation must show that heavy runtime improvements came from duplicate-work removal or narrower family scope, not from hidden trust reduction.

## Phase 2 — Implementation Planning

`tasks.md` should cover:

- Refreshing the current heavy-governance baseline artifact set through the standard lane wrappers before any family edits.
- Building a checked-in hotspot inventory that covers the current top 5 families by runtime, or enough families to explain at least 80% of lane runtime, whichever set is larger.
- Auditing `baseline-profile-start-surfaces`, `findings-workflow-surfaces`, and `finding-bulk-actions-workflow` for repeated Livewire mounts, gating matrices, filter persistence, audit fan-out, and helper-driven cost.
- Deciding for each targeted family whether the right fix is splitting, centralizing repeated work, or recording explicit intentional heaviness.
- Auditing second-wave surface-guard families such as `action-surface-contract` and `ops-ux-governance` for internal redundancy only after the workflow-heavy hotspots are addressed.
- Extending `TestLaneManifest` and `TestLaneReport` so hotspot inventory, residual causes, and budget outcomes stay reviewable and attributable.
- Adding or updating guard tests that protect budget-signal consistency, hotspot-inventory integrity, the top-5-or-80%-coverage rule, lane-membership invariants for touched heavy families, and future heavy-family authoring discipline.
- Normalizing the heavy-governance budget contract from the authoritative pre-normalization `300s` summary threshold and the legacy `200s` `budgetTargets()` signal to one deliberate rule after the hotspot inventory and slimming pass have established the honest lane shape.
- Rerunning the heavy-governance lane and its focused hotspot packs to produce post-change summary, report, and budget artifacts.
- Recording the final budget decision as explicit recovery within the authoritative threshold or explicit recalibration with evidence.

### Contract Implementation Note

- The JSON schema is schema-first and repository-tooling-oriented. It defines what the checked-in hotspot inventory, decomposition records, budget contract, and final budget outcome must express even if the first implementation remains PHP arrays in `TestLaneManifest` and JSON output from `TestLaneReport`.
- The OpenAPI file is logical rather than transport-prescriptive. It documents the expected semantics of hotspot inspection, decomposition review, budget-outcome evaluation, and author guidance for in-process repository tooling.
- The design intentionally avoids introducing a new runtime service, new database table, or new artifact root outside the existing `storage/logs/test-lanes` contract.

### Deployment Sequencing Note

- No database migration is planned.
- No asset publish step changes.
- The rollout should start with a fresh heavy-governance baseline capture through the standard wrappers, then hotspot decomposition, then family-level slimming or centralization, then budget-signal normalization, and finally a rerun whose summary, budget, and report artifacts agree on one authoritative threshold and one explicit outcome.