claw/docs/superpowers/plans/2026-04-20-generated-scene-source-first-runtime-semantics-ledger-plan.md

Generated Scene Source-First Runtime Semantics Ledger Plan

Date: 2026-04-20 Status: Draft Parent roadmap:

• docs/superpowers/plans/2026-04-20-generated-scene-source-first-runtime-semantics-hardening-plan.md Parent design:
• docs/superpowers/specs/2026-04-20-generated-scene-source-first-runtime-semantics-ledger-design.md Upstream completed step:
• docs/superpowers/plans/2026-04-20-generated-scene-source-evidence-cross-scan-plan.md

Plan Intent

Build the full source-first runtime-semantics ledger for the current 102-scene set.

This stage exists to convert the completed source cross-scan into a reusable comparison ledger before any analyzer/generator hardening route is defined.

Fixed Inputs

1. tests/fixtures/generated_scene/generated_scene_source_evidence_cross_scan_2026-04-20.json
2. examples/scene_skill_102_final_materialization_2026-04-19/skills
3. tests/fixtures/generated_scene/scene_skill_102_deterministic_invocation_readiness_after_keyword_refinement_2026-04-20.json
4. tests/fixtures/generated_scene/scene_skill_102_natural_language_parameter_readiness_2026-04-20.json
5. tests/fixtures/generated_scene/scene_skill_102_parameter_dictionary_template_normalization_2026-04-20.json
6. sweep-030-scene inner-network findings already established in prior discussion and analysis assets

Scope Guardrails

Allowed:

1. read source cross-scan outputs
2. read current generated skills and references
3. compare source evidence with generated evidence
4. assign gap classes, risk levels, and route hints
5. publish ledger JSON and report

Forbidden:

1. no implementation changes in src/
2. no manifest or script edits
3. no rematerialization
4. no validation reruns
5. no execution-board update
6. no inner-network testing

Phase 0: Freeze Ledger Inputs

Objective

Make the cross-scan asset and current generated-skill assets the only valid inputs for this ledger stage.

Tasks

1. verify the cross-scan JSON parses
2. verify all 102 scenes are represented
3. verify the current generated skill root is readable

Acceptance

1. the ledger stage starts from a stable 102-scene evidence base

Phase 1: Build Per-Scene Comparison Records

Objective

For each scene, merge source evidence with generated-skill evidence into one comparison record.

Tasks

1. load source evidence flags, evidence files, alias samples, request tokens, and runtime URL samples
2. read current scene-level generated manifests/references as needed
3. summarize generated-side evidence for:
   • invocation aliases
   • dictionaries
   • parameter defaults
   • request mapping
   • runtime URL roles
4. write one comparison record per scene

Acceptance

1. all 102 scenes have both source-side and generated-side summaries

Phase 2: Assign Gap Classes and Risk Levels

Objective

Convert comparison records into a stable runtime-semantics risk ledger.

Tasks

1. assign gaps from the fixed five-class taxonomy
2. assign riskLevel = high|medium|low
3. assign:
   • generatorLevelGap
   • runtimeOnlyResidual
4. record comparisonNotes

Acceptance

1. every scene has gaps
2. every scene has riskLevel
3. every scene has recommendedFixRoutes

Phase 3: Aggregate Route-Level Signals

Objective

Produce route-level reuse signals from the scene ledger so the next stage can design bounded hardening routes.

Tasks

1. count scenes carrying each gap class
2. count scenes marked generatorLevelGap
3. count scenes marked runtimeOnlyResidual
4. identify the highest-density reusable route clusters

Acceptance

1. the ledger can drive downstream route prioritization without returning to anecdotal scene debugging

Deliverables

1. tests/fixtures/generated_scene/generated_scene_source_first_runtime_semantics_ledger_2026-04-20.json
2. docs/superpowers/reports/2026-04-20-generated-scene-source-first-runtime-semantics-ledger-report.md

Expected Coverage

The ledger should represent:

1. all 102 scenes
2. all five canonical gap classes
3. source-first route hints derived from the completed cross-scan

Stop Statement

Stop after:

1. publishing the ledger JSON
2. publishing the ledger report
3. summarizing the highest-reuse hardening routes

Do not yet create implementation route plans inside this ledger plan.