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.