claw/docs/superpowers/specs/2026-04-19-scene-skill-102-full-coverage-framework-design.md

# Scene Skill 102 Full Coverage Framework Design

> Date: 2026-04-19
> Status: Draft
> Upstream Roadmap: `docs/superpowers/plans/2026-04-17-scene-skill-60-to-90-roadmap-plan.md`
> Upstream Reconciliation: `tests/fixtures/generated_scene/full_sweep_status_reconciliation_2026-04-19.json`
> Upstream Follow-up: `tests/fixtures/generated_scene/structured_fail_closed_improvement_followup_2026-04-19.json`
> Upstream Timeout Hygiene: `tests/fixtures/generated_scene/timeout_rerun_hygiene_integration_2026-04-19.json`

## Intent

Provide the single post-roadmap framework design for driving the current sgClaw scene-to-skill pipeline from partial `102` scene coverage to full bounded `102` scene coverage.

This design is intentionally broader than the bounded micro-plans used so far. It defines:

1. the current actual state of the `102` scene set
2. what is still missing before `100%` coverage can be claimed
3. the layered framework that all future changes must fit into
4. the fixed route order for future implementation work
5. the stop rules that prevent the project from drifting into unbounded plan recursion

This design is meant to become the single parent framework for later bounded plans.

## Current State

### Raw Current State

From the latest integrated assets:

| Status | Count |
| --- | ---: |
| `auto-pass` | 48 |
| `fail-closed-known` | 47 |
| `adjudicated-valid-host-bridge` | 4 |
| raw `source-unreadable` | 3 |
| Total | 102 |

### Timeout Hygiene Overlay

The timeout hygiene layer shows that the raw `3` timeout records are not all hard unreadable records:

| Hygiene-aware timeout interpretation | Count |
| --- | ---: |
| `timeout-as-pass-candidate` | 2 |
| `timeout-as-fail-closed-candidate` | 1 |
| `timeout-still-unreadable` | 0 |
| `timeout-rerun-error` | 0 |

### Interpretation

This means the framework has already reached these milestones:

1. there are no `unsupported-family` scenes in the current `102` sweep
2. there are no unresolved route conflicts left in the current `102` sweep
3. the remaining gap is no longer “framework cannot classify this scene”
4. the remaining gap is “contract does not close” or “timeout budget/hygiene distorts the raw reading”

## What Is Still Missing Before 100% Coverage

`100%` coverage does not mean all `102` scenes must become direct `auto-pass`.

For this framework, `100% bounded coverage` means:

1. every scene is classified into a supported framework path
2. every non-pass result is either:
   - structured fail-closed with named blocker
   - valid host-bridge workflow adjudication
   - hygiene-aware timeout interpretation
3. there are no unresolved buckets like:
   - unsupported family
   - unresolved route conflict
   - opaque no-report failure
   - unexplained timeout

Under that definition, the missing gap is:

### Missing Gap A: Structured Contract Closure

There are still `47` structured fail-closed records.

Current distribution:

| Archetype | Count |
| --- | ---: |
| `paginated_enrichment` | 34 |
| `local_doc_pipeline` | 5 |
| `multi_mode_request` | 4 |
| `single_request_enrichment` | 2 |
| `host_bridge_workflow` | 1 |
| `page_state_eval` | 1 |

This is the largest remaining implementation gap.

### Missing Gap B: Timeout Hygiene Integration into Main Reporting

The timeout hygiene layer now exists, but it is still a reporting-side overlay. It has not yet been folded into the primary current-state narrative used by later roadmap decisions.

### Missing Gap C: Current-State Overlay vs Execution Board

The project intentionally did not update `scene_execution_board_2026-04-18.json` during these bounded plans. That is correct, but it means the official board is still behind the latest integrated view.

### Missing Gap D: Promotion Policy

The project still lacks a single parent rule that says when a structured fail-closed scene may be promoted from:

1. fail-closed
2. fail-closed with stronger evidence
3. bounded rerun pass candidate

into a stronger scene-level coverage status.

## Framework Layers

All future work must land in exactly one of these layers.

### Layer A: Source Scan and Budget Layer

Purpose:

1. source directory size handling
2. file filtering
3. timeout budget policy
4. rerun hygiene

Owned concerns:

1. source scan volume
2. timeout policy
3. rerun interpretation

Must not own:

1. archetype routing
2. contract closure logic
3. scene promotion

Primary code area:

1. `src/generated_scene/analyzer.rs`
2. reporting JSON and sweep scripts

### Layer B: Archetype Routing Layer

Purpose:

1. decide the correct framework path:
   - `single_request_table`
   - `single_request_enrichment`
   - `multi_mode_request`
   - `paginated_enrichment`
   - `host_bridge_workflow`
   - `multi_endpoint_inventory`
   - `local_doc_pipeline`

Owned concerns:

1. route precedence
2. mixed-evidence routing boundaries
3. route adjudication support

Must not own:

1. timeout policy
2. contract synthesis beyond routing evidence
3. board reconciliation

Primary code area:

1. `src/generated_scene/analyzer.rs`

### Layer C: Contract Recovery Layer

Purpose:

Recover the minimum business contract fields needed by each supported archetype.

Owned concerns:

1. request contract recovery
2. response contract recovery
3. pagination plan recovery
4. enrichment request recovery
5. join key recovery
6. export plan recovery
7. mode matrix recovery

Must not own:

1. timeout policy
2. execution board updates
3. status promotion

Primary code area:

1. `src/generated_scene/generator.rs`
2. `src/generated_scene/ir.rs`

### Layer D: Structured Fail-Closed and Reporting Layer

Purpose:

Make every incomplete scene fail in an explainable and structured way.

Owned concerns:

1. readiness-before-report classification
2. blocker naming
3. `contractSnapshot`
4. generation-report completeness

Must not own:

1. route preference
2. source scan budget
3. promotion policy

Primary code area:

1. `src/generated_scene/generator.rs`
2. reporting assets under `tests/fixtures/generated_scene/`

### Layer E: Sweep, Reconciliation, and Coverage Layer

Purpose:

Measure the whole `102` scene set, reconcile multiple interpretation layers, and report trustworthy coverage.

Owned concerns:

1. full sweep outputs
2. route adjudication overlay
3. timeout hygiene overlay
4. integrated coverage reporting
5. board reconciliation planning

Must not own:

1. analyzer implementation changes
2. generator implementation changes

Primary assets:

1. `tests/fixtures/generated_scene/*full_sweep*`
2. `tests/fixtures/generated_scene/*reconciliation*`
3. `tests/fixtures/generated_scene/*timeout*hygiene*`
4. `docs/superpowers/reports/*coverage*`

## Coverage Definitions

This framework uses four explicit coverage concepts.

### Coverage 1: Direct Pass Coverage

Scenes with direct `auto-pass`.

Current count:

`48 / 102`

### Coverage 2: Framework-Resolved Coverage

Scenes in one of:

1. `auto-pass`
2. `adjudicated-valid-host-bridge`
3. structured `fail-closed-known`
4. hygiene-aware timeout interpretation

This is the best measure of whether the framework has “caught” the scene set.

### Coverage 3: Promotion Coverage

Scenes already represented as promoted or boundary family assets in current project assets.

This is lower than framework-resolved coverage because promotion is intentionally conservative.

### Coverage 4: Real-Sample Execution Coverage

Scenes that have actual selected and executed real-sample validation records.

This is the strictest coverage metric.

## Fixed Route Order for Future Work

Future work must follow this order.

### Route 1: Finish Layer E Hygiene Integration

Goal:

Make sweep and reconciliation reporting hygiene-aware by default.

This route is nearly finished and should be closed first.

### Route 2: `G3 / paginated_enrichment` Contract Closure

Goal:

Work down the largest remaining structured fail-closed bucket.

Why first:

1. largest bucket by count
2. most important for closing the remaining `102` gap
3. already split into repeated missing-contract patterns

Expected sub-order:

1. `enrichment_request_missing`
2. `export_plan_missing`
3. then any remaining `join_key` or runtime-scope style gaps

### Route 3: `G2 / multi_mode_request` Small-Bucket Closure

Goal:

Close the remaining `4` multi-mode structured fail-closed records.

Why third:

1. clear archetype
2. relatively small bucket
3. mainline family already has real-sample pass anchor

### Route 4: `G1-E / single_request_enrichment` Small-Bucket Closure

Goal:

Close the remaining `2` G1-E structured fail-closed records.

Why fourth:

1. smallest mainline bucket
2. framework anchor already exists
3. lower leverage than G3 and G2

### Route 5: Decide on `local_doc_pipeline` and `host_bridge_workflow`

Goal:

Handle the remaining boundary-family fail-closed records only after the mainline buckets are reduced.

This route must not start before Routes 2–4 have completed or been explicitly deferred.

### Route 6: Reconciliation and Board Promotion Policy

Goal:

Define how stronger framework-resolved statuses can update the execution board without over-promoting scenes.

This must be done only after contract-closure routes have produced stable deltas.

## What Future Plans Must Contain

Every later bounded implementation plan must explicitly declare:

1. which framework layer it belongs to
2. which route from this design it belongs to
3. which code modules it is allowed to touch
4. which code modules it must not touch
5. how it protects current real-sample and canonical passes
6. what exact delta it expects to produce in the `102` scene state

If a future plan cannot answer those six items, it is out of framework and should not start.

## Stop Rules

The framework forbids:

1. starting a new micro-plan that only renames a narrower semantics problem without moving toward a route completion
2. treating timeout rerun success as promotion
3. updating execution board state inside a diagnostic plan
4. opening `G4/G5` before the current structured fail-closed mainline is reduced
5. using prompt-only tuning as a substitute for contract recovery

## What 100% Looks Like

This framework considers `100% bounded coverage` achieved when:

1. `unsupported-family = 0`
2. `missing-source = 0`
3. `misclassified-unresolved = 0`
4. `timeout-still-unreadable = 0`
5. every remaining non-pass scene is structured and attributable to a supported framework path
6. execution board and reconciliation reporting can express the current scene state without ambiguity

This is different from `100% auto-pass`.

`100% auto-pass` is not the immediate target.

`100% bounded framework coverage` is the immediate target.