193 lines
9.3 KiB
Markdown
193 lines
9.3 KiB
Markdown
# Data Model: Heavy Governance Lane Cost Reduction
|
|
|
|
This feature does not introduce new runtime database tables. The data-model work formalizes repository-level governance objects that describe how the heavy-governance lane is inventoried, decomposed, slimmed, and evaluated against a single explicit budget contract. It builds directly on the existing Spec 206 to 208 lane manifest and report artifacts.
|
|
|
|
## 1. Heavy Governance Budget Contract
|
|
|
|
### Purpose
|
|
|
|
Represents the deliberate budget rule for the heavy-governance lane, including the authoritative pre-normalization `300s` summary threshold, the legacy `200s` detailed budget-target evaluation, and the final reconciled threshold published by Spec 209.
|
|
|
|
### Fields
|
|
|
|
- `laneId`: expected to be `heavy-governance`
|
|
- `summaryThresholdSeconds`: current authoritative pre-normalization lane-level threshold used by the summary artifact
|
|
- `evaluationThresholdSeconds`: legacy threshold currently used in detailed budget evaluations until normalization is complete
|
|
- `normalizedThresholdSeconds`: the single threshold that will be treated as authoritative after Spec 209
|
|
- `baselineSource`: where the budget came from, such as `measured-lane`
|
|
- `enforcementLevel`: `report-only`, `warn`, or `hard-fail`
|
|
- `lifecycleState`: `draft`, `documented`, or `recalibrated`
|
|
- `reconciliationRationale`: explanation of why the single threshold is correct for the post-Spec-209 lane
|
|
- `decisionStatus`: `pending`, `recovered`, or `recalibrated`
|
|
|
|
### Validation rules
|
|
|
|
- `laneId` must be `heavy-governance`.
|
|
- `summaryThresholdSeconds` and `evaluationThresholdSeconds` must both be captured when they differ, and the authoritative pre-normalization contract must remain identifiable until normalization is complete.
|
|
- `normalizedThresholdSeconds` must be present before the rollout is considered complete.
|
|
- `decisionStatus = recovered` requires measured runtime less than or equal to `normalizedThresholdSeconds`.
|
|
- `decisionStatus = recalibrated` requires a non-empty `reconciliationRationale`.
|
|
|
|
## 2. Heavy Governance Hotspot Inventory Record
|
|
|
|
### Purpose
|
|
|
|
Represents one named heavy-governance family that materially contributes to the lane's runtime and needs explicit review.
|
|
|
|
### Fields
|
|
|
|
- `familyId`: stable family identifier
|
|
- `classificationId`: current owning class such as `ui-workflow`, `surface-guard`, or `discovery-heavy`
|
|
- `purpose`: why the family exists and what trust it provides
|
|
- `measuredSeconds`: current measured contribution from the latest heavy-governance report
|
|
- `hotspotFiles`: dominant files tied to the family
|
|
- `costDriverCategory`: primary cause such as `overbroad`, `redundant`, `discovery-heavy`, `workflow-heavy`, `surface-heavy`, `helper-driven`, `fixture-driven`, or `intentionally-heavy`
|
|
- `priorityTier`: `primary`, `secondary`, or `residual`
|
|
- `currentBudgetSeconds`: current family-level budget if one exists
|
|
- `status`: `seeded`, `decomposed`, `slimmed`, `retained`, or `follow-up`
|
|
|
|
### Validation rules
|
|
|
|
- `hotspotFiles` must contain at least one file.
|
|
- `priorityTier = primary` is required for the families that explain most of the lane runtime.
|
|
- The full hotspot inventory must cover the current top 5 families by runtime, or enough families to explain at least 80% of lane runtime, whichever set is larger.
|
|
- `status = slimmed` or `status = retained` requires a corresponding decomposition record.
|
|
- If `currentBudgetSeconds` exists, it must match the checked-in family budget contract.
|
|
|
|
## 3. Family Cost Decomposition Record
|
|
|
|
### Purpose
|
|
|
|
Represents the internal analysis for a targeted hotspot family so reviewers can see what part of the family is necessary and what part is duplicated or accidental.
|
|
|
|
### Fields
|
|
|
|
- `familyId`: referenced hotspot family
|
|
- `trustType`: primary trust delivered, such as `workflow-trust`, `surface-trust`, `guard-trust`, or `discovery-trust`
|
|
- `requiredBreadth`: what breadth is genuinely needed for product trust
|
|
- `duplicateWorkSources`: repeated work sources such as `repeated-livewire-mounts`, `header-action-gating-matrix`, `filter-state-persistence`, `audit-fan-out`, `resource-discovery-pass`, or `helper-graph-build`
|
|
- `duplicateWorkEstimateSeconds`: optional estimate of removable cost
|
|
- `residualCostSource`: `family-breadth`, `helper-driven`, `fixture-driven`, `mixed`, or `intentional-depth`
|
|
- `recommendedAction`: `split-family`, `centralize-work`, `narrow-assertions`, `retain-as-heavy`, or `route-follow-up`
|
|
- `notes`: reviewer-readable explanation
|
|
|
|
### Validation rules
|
|
|
|
- Every `primary` hotspot family must have one decomposition record.
|
|
- `recommendedAction = route-follow-up` requires `residualCostSource` to be `helper-driven`, `fixture-driven`, or `mixed`.
|
|
- `recommendedAction = retain-as-heavy` requires `residualCostSource = intentional-depth`.
|
|
- `duplicateWorkEstimateSeconds` may be omitted when cost is truly intentional, but the reason must be explicit.
|
|
|
|
## 4. Heavy Family Slimming Decision
|
|
|
|
### Purpose
|
|
|
|
Represents the implementation-facing decision taken for a hotspot family after decomposition.
|
|
|
|
### Fields
|
|
|
|
- `familyId`: referenced hotspot family
|
|
- `decisionType`: `split`, `centralize`, `trim-duplicate-work`, `retain`, or `follow-up`
|
|
- `scope`: list of files, helpers, or manifest entries touched by the decision
|
|
- `guardPreservationPlan`: how the original governance trust remains protected
|
|
- `expectedDeltaSeconds`: estimated improvement if known
|
|
- `owner`: responsible maintainer or team role
|
|
- `validationPlan`: focused tests or lane reruns needed to validate the decision
|
|
|
|
### Validation rules
|
|
|
|
- Every `decisionType` other than `retain` must include at least one item in `scope`.
|
|
- `guardPreservationPlan` is mandatory for all decisions.
|
|
- `follow-up` decisions must name the residual cause and target seam.
|
|
- `retain` decisions must still reference a validation plan showing why the retained heaviness is acceptable.
|
|
|
|
## 5. Budget Recovery Snapshot
|
|
|
|
### Purpose
|
|
|
|
Represents one snapshot in the before-and-after lane measurement pair used to prove recovery or justify recalibration.
|
|
|
|
### Fields
|
|
|
|
- `snapshotId`: stable identifier such as `pre-slimming` or `post-slimming`
|
|
- `capturedAt`: ISO timestamp
|
|
- `wallClockSeconds`: measured heavy-governance wall-clock time
|
|
- `classificationTotals`: totals by classification
|
|
- `familyTotals`: totals by family
|
|
- `slowestEntries`: top slowest test entries
|
|
- `artifactPaths`: references to summary, report, and budget artifacts
|
|
- `budgetStatus`: `within-budget`, `warning`, or `over-budget`
|
|
|
|
### Validation rules
|
|
|
|
- At least two snapshots are expected for a complete rollout: baseline and post-change.
|
|
- `artifactPaths` must stay under `storage/logs/test-lanes`.
|
|
- `familyTotals` must include the targeted hotspot families.
|
|
- Summary, budget, and report artifacts captured for the same snapshot must not disagree on the authoritative threshold or budget outcome classification.
|
|
|
|
## 6. Budget Outcome Record
|
|
|
|
### Purpose
|
|
|
|
Represents the final explicit outcome required by Spec 209.
|
|
|
|
### Fields
|
|
|
|
- `outcomeId`: stable identifier
|
|
- `decisionStatus`: `recovered` or `recalibrated`
|
|
- `finalThresholdSeconds`: authoritative heavy-governance threshold after the rollout
|
|
- `finalMeasuredSeconds`: measured post-change runtime
|
|
- `deltaSeconds`: change from the baseline snapshot
|
|
- `deltaPercent`: percentage change from the baseline snapshot
|
|
- `remainingOpenFamilies`: families still above expected cost or still awaiting follow-up
|
|
- `justification`: human-readable explanation of the decision
|
|
- `followUpDebt`: optional residual items that remain outside the current scope
|
|
|
|
### Validation rules
|
|
|
|
- `decisionStatus = recovered` requires `finalMeasuredSeconds <= finalThresholdSeconds`.
|
|
- `decisionStatus = recalibrated` requires a non-empty `justification` explaining why the new threshold is honest.
|
|
- `remainingOpenFamilies` may be non-empty only when their residual status is explicit.
|
|
|
|
## 7. Heavy Author Guidance Rule
|
|
|
|
### Purpose
|
|
|
|
Represents a short reviewer or author rule for future heavy-governance tests.
|
|
|
|
### Fields
|
|
|
|
- `ruleId`: stable identifier
|
|
- `whenToUse`: the situation the rule applies to
|
|
- `requiredDecision`: what the author or reviewer must decide
|
|
- `antiPattern`: what overbroad behavior the rule prevents
|
|
- `preferredOutcome`: the intended family or separation behavior
|
|
|
|
### Validation rules
|
|
|
|
- Guidance must cover at least: when to create a new heavy family, when to reuse an existing family, when a test is too broad, and when discovery, workflow, and surface trust must be separated.
|
|
|
|
## 8. Current Measured Inventory Snapshot
|
|
|
|
### Current dominant families
|
|
|
|
- `baseline-profile-start-surfaces` — `98.112193s` — `ui-workflow` — currently the largest heavy-governance family
|
|
- `action-surface-contract` — `40.841552s` — `surface-guard`
|
|
- `ops-ux-governance` — `38.794861s` — `surface-guard`
|
|
- `findings-workflow-surfaces` — `36.459493s` — `ui-workflow`
|
|
- `finding-bulk-actions-workflow` — `26.491446s` — `ui-workflow`
|
|
- `workspace-settings-slice-management` — `21.740839s` — `ui-workflow`
|
|
|
|
### Current classification totals
|
|
|
|
- `ui-workflow` — `190.606431s`
|
|
- `surface-guard` — `106.845887s`
|
|
- `discovery-heavy` — `0.863003s`
|
|
|
|
### Current budget signals
|
|
|
|
- Lane summary threshold: `300s` and currently the authoritative pre-normalization contract
|
|
- Budget target evaluation threshold: `200s` and currently legacy drift evidence, not a second passing threshold
|
|
- Current measured lane wall clock: `318.296962s`
|
|
|
|
This dual-signal state is intentional input to Spec 209 and must be resolved by the final budget outcome. |