claw/docs/superpowers/plans/2026-04-19-g2-real-sample-contract-correction-plan.md

G2 Real Sample Contract Correction Plan

Date: 2026-04-19 Status: Draft Upstream Spec: 2026-04-19-g2-real-sample-contract-correction-design.md Trigger Record: rsv-g2-001

Plan Intent

This plan implements one bounded mainline correction slice:

G2 real-sample contract correction

Its purpose is to reduce the current real-sample G2 mismatch from the broad bundle:

1. bootstrap_mismatch
2. request_contract_missing
3. column_defs_missing
4. output correctness not closed

into either:

1. a verified pass
2. or a smaller named contract mismatch

Scope Guardrails

1. do not reopen completed G2 family expansion work
2. do not add new G2 fixtures or promote new G2 candidates
3. do not reopen G3, G1-E, or boundary families
4. do not turn this work into login recovery or broader runtime-platform implementation
5. do not update validation assets until the real-sample outcome becomes narrower than the current broad mismatch bundle

Fixed Verification Anchor

The only anchor under this plan is:

1. 台区线损大数据-月_周累计线损率统计分析

Mapped real-sample record:

1. rsv-g2-001

Workstreams

1. WS1 Real-Sample Contract Differential
2. WS2 Bootstrap and Request Contract Narrowing
3. WS3 Column and Output Contract Narrowing
4. WS4 Regression, Rerun, and Validation Closure

Phase 0: Freeze the Correction Boundary

Objective

Lock the scope to the fixed G2 real sample and its remaining contract gaps.

Tasks

1. freeze rsv-g2-001 as the only real-sample correction target
2. freeze the current mismatch bundle from the validation layer
3. freeze G2 family-expansion outputs as completed and out of scope

Deliverables

1. correction-boundary note
2. fixed mismatch statement

Acceptance Criteria

1. no new G2 family-expansion task is opened
2. the correction target is explicitly limited to real-sample contract closure

Phase 1: Build the Real-Sample Contract Differential

Objective

Make the smallest remaining real-sample contract mismatch explicit before code changes.

Tasks

1. compare the current real generated SceneIr against the intended tq-lineloss-report contract
2. isolate whether the dominant remaining gap is:
   • bootstrap target selection
   • per-mode request template completeness
   • output column semantics
   • output artifact correctness
3. write a minimum contract-gap summary

Deliverables

1. contract differential note
2. minimum gap summary

Acceptance Criteria

1. the smallest remaining G2 mismatch is explicit
2. the next implementation target is narrower than the current broad mismatch bundle

Phase 2: Narrow Bootstrap and Request Contract Gaps

Objective

Correct only the bootstrap and request-side contract pieces that the real sample proves are still too coarse.

Tasks

1. adjust G2 bootstrap resolution only where the real sample proves it is still misaligned
2. adjust mode-specific request contract recovery only where the real sample proves it is still incomplete
3. preserve fail-closed behavior for unresolved G2 variants

Deliverables

1. bounded bootstrap correction
2. bounded request-contract correction

Acceptance Criteria

1. the real sample no longer keeps the same broad bootstrap/request mismatch shape
2. unrelated G2 family fixtures are not broadened or reclassified

Phase 3: Narrow Column and Output Contract Gaps

Objective

Reduce the remaining output-side mismatch to a verified or smaller state.

Tasks

1. adjust G2 column-definition recovery only where the real sample proves it is still incomplete
2. adjust output-contract verification only where the real sample proves the generated artifact is too coarse
3. keep readiness and fail-closed behavior intact for still-unresolved samples

Deliverables

1. bounded column-contract correction
2. bounded output-contract correction

Acceptance Criteria

1. the real-sample mismatch becomes narrower than the current broad bundle
2. G2 does not regress into false positives for unresolved variants

Phase 4: Regression, Rerun, and Validation Closure

Objective

Use rerun and validation-layer updates to close the bounded G2 correction loop.

Tasks

1. add or update regression that names the corrected G2 real-sample pattern
2. rerun the fixed real sample
3. record whether:
   • the sample becomes executed-pass
   • or the remaining mismatch is now smaller and named
4. update the validation-layer assets
5. write a formal closure report

Deliverables

1. rerun output
2. updated validation assets
3. G2 real-sample contract-correction closure report

Acceptance Criteria

1. rsv-g2-001 no longer remains unchanged as the same broad mismatch bundle
2. the narrowed outcome is covered by automated regression
3. validation assets record the narrower G2 state

Completion Criteria

This plan is complete when:

1. the fixed G2 real sample no longer remains at the same broad mismatch bundle
2. the narrower result is covered by automated regression
3. validation assets are updated with the narrowed outcome
4. completed G2 family-expansion work remains untouched

Next Step

After this plan completes:

1. if G2 becomes executed-pass, mainline real-sample pressure leaves both G2 and G3
2. if G2 still has a smaller named mismatch, move only to that narrower G2 correction slice