claw/docs/superpowers/specs/2026-04-20-generated-scene-rule-hardening-route-design.md

Generated Scene Rule Hardening Route Design

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

• docs/superpowers/plans/2026-04-20-generated-scene-source-first-runtime-semantics-hardening-plan.md Upstream ledger:
• docs/superpowers/plans/2026-04-20-generated-scene-source-first-runtime-semantics-ledger-plan.md

Intent

Define the bounded route-design stage that converts the completed source-first runtime-semantics ledger into reusable hardening routes.

This design does not implement analyzer/generator changes. It only decides:

1. which reusable hardening routes exist
2. how large each route is
3. which routes should be executed first
4. how downstream implementation slices should be decomposed

Why This Stage Exists

The ledger proved that the current 102-scene set contains reusable generator-level gaps, not just isolated scene-specific defects.

The project now needs a route map that:

1. groups scenes by reusable rule fixes
2. avoids scene-by-scene patching
3. defines a strict implementation order
4. makes full rematerialization and validation refresh possible after hardening

Fixed Inputs

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

Scope

In scope:

1. route clustering from the completed ledger
2. route prioritization by coverage and reuse
3. bounded child-plan sequencing for implementation
4. rematerialization dependency declaration
5. validation refresh dependency declaration

Out of scope:

1. any src/ change
2. any skill manifest edit
3. any rematerialization
4. any validation rerun
5. any inner-network execution

Route Candidates

The ledger already establishes five generator-level hardening routes.

Route 1: Resolver-to-Request Mapping Hardening

Goal:

Recover reusable mapping metadata between resolver outputs and request payload fields.

Examples:

1. org_code -> orgno
2. period_payload.fdate -> fdate
3. period_payload.weekSfdate -> weekSfdate
4. period_payload.weekEfdate -> weekEfdate

Reason for high priority:

This route spans the full 102-scene set and directly blocks runtime equivalence.

Route 2: Runtime URL Classification Hardening

Goal:

Separate URL roles during generation:

1. runtime context URL
2. module route URL
3. API endpoint URL
4. entry URL hints

Reason for high priority:

This route also spans the full set and is required to stop callers from guessing page_url semantics at execution time.

Route 3: Embedded Dictionary Extraction Hardening

Goal:

Recover richer dictionaries and trees from source-side JS/HTML assets instead of shipping starter subsets only.

Reason for high priority:

This route also spans the full set and is the only scalable answer to sweep-030-style organization coverage failures.

Route 4: Parameter Default Semantics Recovery Hardening

Goal:

Recover page-native default period/date/mode behavior from source evidence into generated parameter metadata.

Reason for priority:

This route is slightly narrower than the first three but still affects the majority of scenes and is highly visible in runtime invocation.

Route 5: Invocation Alias Generation Hardening

Goal:

Broaden deterministic invocation coverage so user wording is not forced to match canonical scene names exactly.

Reason for priority:

This route is selective rather than universal, so it should follow structural hardening routes unless a route-local blocker proves otherwise.

Prioritization Rules

Route order must be based on:

1. breadth of scene coverage
2. generator-level reuse
3. ability to reduce repeat inner-network rediscovery
4. dependency order between routes

It must not be based on:

1. anecdotal scene debugging order
2. whichever single scene was most recently tested

Fixed Route Order

The current route order should be:

1. resolver_request_mapping_hardening
2. runtime_url_classification_hardening
3. embedded_dictionary_extraction_hardening
4. parameter_default_semantics_recovery_hardening
5. alias_generation_hardening

Implementation-Slice Policy

No route should be implemented as one unbounded giant patch.

Each route must later be split into bounded child plans with:

1. a fixed scene bucket
2. explicit allowed files
3. explicit forbidden files
4. an expected coverage delta
5. a stop statement

Required Downstream Outputs

This route-design stage must yield:

1. one route-sequencing plan
2. one bounded implementation plan per top route
3. one full rematerialization refresh plan after route execution
4. one validation refresh plan after rematerialization

Acceptance Criteria

This design is complete when:

1. all five reusable routes are explicit
2. route order is fixed
3. route ordering is justified by ledger evidence, not anecdotes
4. downstream implementation decomposition rules are explicit
5. this stage remains design-only

Stop Statement

Stop after publishing the route design and its child sequencing plan.

Do not implement any hardening route inside this design.