claw/docs/superpowers/specs/2026-04-19-structured-fail-closed-improvement-roadmap-design.md

Structured Fail-Closed Improvement Roadmap Design

Date: 2026-04-19 Status: Draft Upstream Reconciliation: tests/fixtures/generated_scene/full_sweep_status_reconciliation_2026-04-19.json

Intent

Turn the 48 structured fail-closed records from the reconciled 102 sweep into a governed improvement roadmap.

The objective is not to weaken gates or inflate auto-pass. The objective is to classify contract gaps, identify the highest-value bounded correction slices, and then improve generic scene-to-skill conversion where evidence can be recovered safely.

Current Reconciled Baseline

After status reconciliation, the 102 scene set is:

Reconciled status	Count
auto-pass	48
fail-closed-known	48
adjudicated-valid-host-bridge	4
source-unreadable	2
missing-source	0
unsupported-family	0

The 4 raw route conflicts are no longer unresolved route bugs. They are valid host-bridge workflows.

This roadmap therefore focuses on fail-closed-known = 48.

Fail-Closed Buckets

Inferred archetype	Reason	Count
paginated_enrichment	workflow evidence is incomplete before package generation	35
local_doc_pipeline	workflow evidence is incomplete before package generation	5
multi_mode_request	workflow evidence is incomplete before package generation	4
single_request_enrichment	workflow evidence is incomplete before package generation	2
host_bridge_workflow	workflow evidence is incomplete before package generation	1
page_state_eval	bootstrap_target	1

The first priority is the 35 paginated_enrichment records because they are the largest bucket and map to the most important currently generic workflow family.

Scope Guardrails

In scope:

1. classify the 48 structured fail-closed records by missing contract piece
2. prioritize bounded correction slices
3. implement bounded evidence recovery only after classification shows repeated recoverable patterns
4. keep all fail-closed semantics intact
5. rerun a bounded follow-up sweep after corrections

Out of scope:

1. adding new scene families
2. starting G4/G5
3. login recovery
4. full browser host runtime transport
5. local document attachment runtime
6. auto-promoting scenes into the execution board
7. weakening readiness gates to increase pass counts
8. reopening the already adjudicated 4 valid-host-bridge workflows
9. handling the 2 remaining timeout records in this roadmap

Workstreams

1. WS1 Fail-Closed Inventory and Gap Taxonomy
2. WS2 G3 Paginated Enrichment Contract Recovery
3. WS3 Small-Bucket Contract Recovery
4. WS4 Bootstrap Target Isolation
5. WS5 Follow-Up Sweep and Coverage Delta

Gap Taxonomy

Every structured fail-closed record must receive one primary missing-contract label:

1. main_request_missing
2. pagination_plan_missing
3. enrichment_request_missing
4. join_key_missing
5. export_plan_missing
6. mode_matrix_missing
7. mode_request_contract_missing
8. single_request_enrichment_contract_missing
9. host_bridge_contract_missing
10. local_doc_contract_missing
11. bootstrap_target_unresolved
12. mixed_or_ambiguous_contract_gap

Secondary labels may be added, but every record must have exactly one primary label.

Correction Strategy

Corrections must be pattern-based, not scene-by-scene.

Allowed correction types:

1. bounded evidence extraction for repeated field names or workflow structures
2. bounded IR fallback only when evidence is explicit and traceable
3. more specific fail-closed reason reporting
4. regression tests for each recovered pattern

Forbidden correction types:

1. hard-coding a scene name to pass
2. converting fail-closed records to pass without closing the contract
3. broad route-precedence rewrites
4. disabling or relaxing gates

Expected Outputs

1. tests/fixtures/generated_scene/structured_fail_closed_inventory_2026-04-19.json
2. tests/fixtures/generated_scene/structured_fail_closed_improvement_followup_2026-04-19.json
3. docs/superpowers/reports/2026-04-19-structured-fail-closed-inventory-report.md
4. docs/superpowers/reports/2026-04-19-structured-fail-closed-improvement-coverage-delta-report.md
5. docs/superpowers/reports/2026-04-19-structured-fail-closed-improvement-roadmap-closure-report.md

Acceptance Criteria

1. all 48 fail-closed records are inventoried
2. all 48 records have exactly one primary missing-contract label
3. the 35 paginated_enrichment records are split into actionable G3 gap groups
4. implementation, if performed, is limited to repeated recoverable patterns
5. no adjudicated host-bridge record is reopened
6. follow-up results are measured against the reconciled baseline
7. execution board status remains unchanged

Completion Signal

The roadmap is complete when the 48 structured fail-closed records are no longer a single broad bucket and the follow-up sweep quantifies whether bounded evidence recovery improved safe conversion coverage.