claw/docs/superpowers/specs/2026-04-19-g2-real-sample-contract-correction-design.md

G2 Real Sample Contract Correction Design

Date: 2026-04-19 Status: Draft Upstream Roadmap: 2026-04-18-scene-skill-real-sample-validation-roadmap-plan.md Trigger Record: rsv-g2-001

1. Intent

This bounded design defines the next mainline correction slice after G3 is closed as an executed pass.

The only target is:

G2 real-sample contract correction

The purpose is to reduce the current G2 real-sample mismatch from a broad first-round failure bundle into either:

1. a corrected executable pass
2. or a smaller named contract mismatch

2. Current Trigger

The current real-sample validation record for G2 is:

1. recordId = rsv-g2-001
2. validationState = executed-mismatch
3. mismatchCodes = [archetype_mismatch, bootstrap_mismatch, request_contract_missing, column_defs_missing]

From the current mainline status, G2 is now the strongest unresolved real-sample pressure.

3. Scope Boundary

This design is strictly bounded to the real-sample contract gap for the fixed G2 anchor:

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

The correction scope is limited to:

1. bootstrap target correctness
2. request contract correctness
3. column-definition correctness
4. output-contract correctness

This design does not reopen:

1. completed G2 family expansion work
2. new G2 candidate promotion
3. G1-E
4. G3
5. G6 / G7 / G8
6. G4 / G5
7. login recovery or broader runtime-platform work

4. Problem Statement

The current mismatch is no longer about whether G2 exists as a family.

That work is already closed at the repo-local family layer.

The current problem is narrower:

1. the fixed real sample still does not close against the intended tq-lineloss-report-level business contract
2. the validation layer still records a compound mismatch instead of a narrowed real-sample outcome

Based on the real-sample analysis and existing G2 remediation reports, the remaining pressure should be treated as a contract-alignment issue around:

1. target bootstrap surface
2. mode-specific request template completeness
3. output column semantics
4. output correctness against the intended lineloss artifact

5. Correction Principles

The correction must obey these principles:

1. prefer narrowing the current real-sample mismatch over broad family refactoring
2. preserve fail-closed behavior for unresolved G2 variants
3. do not broaden G2 routing into unrelated line-loss-like scenes
4. keep the correction anchored on the fixed real sample rather than batch fixtures
5. only update validation assets after the real-sample outcome becomes narrower than the current broad mismatch bundle

6. Target Outcome

The target outcome is one of two bounded states:

A. Preferred outcome

rsv-g2-001 becomes:

1. executed-pass

B. Acceptable narrower outcome

rsv-g2-001 remains executed-mismatch, but with a smaller named mismatch such as:

1. bootstrap-only mismatch
2. request-contract-only mismatch
3. column-contract-only mismatch
4. output-contract-only mismatch

The design explicitly rejects leaving G2 unchanged at the same coarse four-code mismatch bundle.

7. Required Verification Surfaces

The correction must be verified against these surfaces:

1. real generated generation-report.json
2. intended tq-lineloss-report semantic baseline
3. automated regression that names the corrected real-sample pattern
4. validation-layer assets:
   • real_sample_validation_records_2026-04-18.json
   • scene_execution_board_2026-04-18.json
   • boundary_runtime_entry_rules_2026-04-18.json if prioritization changes

8. Out of Scope

The following are explicitly out of scope for this design:

1. promoting more G2 fixtures
2. redesigning all G2 subtype handling
3. rewriting the general multi_mode_request compiler
4. opening a new G2 family roadmap
5. changing unrelated validation records

9. Exit Condition

This design is complete when implementation can be bounded to a single plan that:

1. freezes the fixed G2 real sample
2. isolates the remaining bootstrap/request/column/output gap
3. narrows the real-sample outcome
4. updates validation assets without reopening family-expansion work