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

# Research: Heavy Governance Lane Cost Reduction

## Decision 1: Reuse the existing heavy-lane governance seams instead of adding a new runner or metadata system

- Decision: Spec 209 should extend the existing `TestLaneManifest`, `TestLaneBudget`, `TestLaneReport`, `scripts/platform-test-lane`, and `scripts/platform-test-report` seams rather than introducing a second planning or reporting framework.
- Rationale: The repository already has checked-in heavy-family attribution, family budgets, lane budgets, and report artifacts under `apps/platform/storage/logs/test-lanes`. The missing work is family decomposition and budget recovery, not missing lane infrastructure.
- Alternatives considered:
  - Add a separate heavy-cost analysis runner: rejected because it would duplicate the current test-governance contract.
  - Use only ad-hoc profiling commands: rejected because Spec 209 requires repeatable before-and-after evidence and reviewer-visible outputs.

## Decision 2: Treat the feature as a budget-recovery exercise against the current measured heavy-governance overrun

- Decision: The planning baseline for Spec 209 is the current heavy-governance artifact set showing `318.296962` seconds wall-clock versus the authoritative pre-normalization lane summary budget of `300` seconds.
- Rationale: Spec 208 already moved the correct heavy families into the heavy-governance lane. The remaining issue is now an explicit cost-recovery problem, not a classification problem.
- Alternatives considered:
  - Re-profile from scratch without using the current heavy artifact: rejected because the current artifact already captures the relevant runtime signal and hotspot attribution.
  - Treat the lane as healthy because the overrun is relatively small: rejected because the spec requires an explicit budget outcome, not quiet acceptance of ongoing drift.

## Decision 3: Make the dual heavy-lane budget signal an explicit planning concern

- Decision: Spec 209 should explicitly reconcile the current heavy-governance budget mismatch by treating the lane summary threshold of `300` seconds as the authoritative pre-normalization contract and the separate `budgetTargets()` lane target of `200` seconds as legacy drift evidence until one normalized threshold is published.
- Rationale: The current report summary and the detailed budget evaluation do not describe the same target. A later CI budget-enforcement phase cannot be credible while that inconsistency exists.
- Alternatives considered:
  - Ignore the mismatch and optimize only against the 300-second lane summary: rejected because the stricter 200-second target still appears in checked-in budget evaluations and will confuse reviewers.
  - Force the lane to 200 seconds immediately: rejected because the spec first needs to determine whether the 200-second target is still realistic for the now-honest heavy lane.

## Decision 4: Prioritize the dominant ui-workflow families before second-wave surface guards

- Decision: The first slimming pass should prioritize `baseline-profile-start-surfaces`, `findings-workflow-surfaces`, and `finding-bulk-actions-workflow`, with `workspace-settings-slice-management` as the next workflow-heavy fallback if more recovery is required.
- Rationale: Current heavy-governance attribution shows `ui-workflow` at `190.606431` seconds, or roughly 60% of lane cost. The three named families together account for about `161.06` seconds and directly align with the spec's required hotspot set.
- Alternatives considered:
  - Start with `action-surface-contract`: rejected as the first pass because it is clearly expensive but already documented as an intentional governance guard and may have less removable duplication than the workflow-heavy hotspots.
  - Start with all surface-guard families equally: rejected because the current runtime evidence shows ui-workflow as the dominant cost bucket.

## Decision 5: Decompose targeted families by repeated work before splitting files mechanically

- Decision: Each targeted hotspot family should first be decomposed by repeated Livewire mounts, header-action gating matrices, filter-state persistence checks, bulk-action fan-out, evidence or audit verification, and any helper-driven fixture cost before deciding whether to split files.
- Rationale: Spec 209 is about real cost reduction, not cosmetic decomposition. A family can remain overbroad even after being split if the same expensive setup still runs in every resulting file.
- Alternatives considered:
  - Split all top families immediately: rejected because that can produce cleaner file boundaries without removing the dominant repeated work.
  - Only centralize helper setup without family-level analysis: rejected because some cost may be due to semantic breadth rather than helper shape.

## Decision 6: Record helper-driven or fixture-driven cost as residual debt instead of forcing a family explanation that is not true

- Decision: If a targeted hotspot is found to be dominated by helper, fixture, or support-path cost rather than family breadth, the resulting plan should record that as explicit residual debt and treat it as follow-up work instead of pretending the family itself was narrowed.
- Rationale: The spec requires honest attribution. Mislabeling helper or fixture cost as family-width improvement would create false confidence and make later budget work less reliable.
- Alternatives considered:
  - Force all heavy cost into family-width categories: rejected because it would violate the spec's explicit residual-cause requirement.
  - Reopen Spec 207 inside Spec 209: rejected because fixture slimming remains a separate concern even when its residual effects appear here.

## Decision 7: Treat `action-surface-contract` and `ops-ux-governance` as intentional heavy families unless decomposition exposes repeatable duplication

- Decision: `action-surface-contract` and `ops-ux-governance` should be treated as second-wave slimming candidates. They remain in heavy-governance by default and should only be narrowed where clear duplicate discovery or repeated governance passes can be shown.
- Rationale: Together they account for `79.636413` seconds and are meaningful heavy governance checks. They may still contain removable redundancy, but their default assumption should be “intentionally heavy until proven otherwise,” not “overbroad by default.”
- Alternatives considered:
  - Treat all surface-guard cost as excessive: rejected because these families intentionally protect cross-resource governance contracts.
  - Exclude them from the plan entirely: rejected because they are still major contributors to lane cost and may need second-pass analysis.

## Decision 8: Use the existing heavy-governance report artifacts as the before-and-after evidence contract

- Decision: Pre-change and post-change evidence should continue to flow through `heavy-governance-latest.summary.md`, `heavy-governance-latest.budget.json`, and `heavy-governance-latest.report.json` under `apps/platform/storage/logs/test-lanes`.
- Rationale: The repository already reads and writes these artifacts. Extending the same contract keeps Spec 209 measurable without introducing a new artifact root or new tool surface.
- Alternatives considered:
  - Add a second report directory specifically for Spec 209: rejected because the current lane artifact contract is already canonical.
  - Depend only on terminal output: rejected because reviewers need checked-in, inspectable budget evidence.

## Decision 9: Keep author guidance repo-local and adjacent to the existing lane contract

- Decision: Spec 209 should place future heavy-family guidance in the existing test-governance seam, centered on `TestLaneManifest` semantics, guard expectations, and checked-in review guidance rather than creating a separate framework or documentation tree.
- Rationale: Authors and reviewers already need the manifest and guard seams to understand lane ownership. Keeping the guidance there avoids a new abstraction layer and keeps maintenance local to the existing contract.
- Alternatives considered:
  - Create a new standalone documentation subsystem for heavy tests: rejected because the guidance is specific to the repository's existing lane contract.
  - Leave guidance only in the spec artifacts: rejected because authors need a lasting checked-in hint near the implementation seam after the spec is complete.

## Decision 10: Success requires explicit recovery or explicit recalibration, not quiet tolerance

- Decision: The feature should end in exactly one of two explicit outcomes: the heavy-governance lane recovers within the authoritative threshold for the rollout, which starts at `300` seconds until normalization completes, or the repository documents a conscious recalibration once the honest lane composition and dominant residual costs are understood.
- Rationale: Spec 209 exists to stabilize the heavy lane before CI enforcement. A vague “improved but still heavy” outcome would not satisfy that purpose.
- Alternatives considered:
  - Accept any measurable improvement as sufficient: rejected because the spec explicitly requires a budget decision.
  - Hard-code recalibration in advance: rejected because the plan must first test whether real recovery is feasible from the dominant hotspot families.