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)

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)

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
• 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 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 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 captures the logical contract for reading hotspots, recording family decomposition, evaluating budget outcomes, and publishing reviewer guidance.
• Output: 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.