claw/docs/superpowers/plans/2026-04-19-structured-fail-closed-improvement-roadmap-plan.md

Structured Fail-Closed Improvement Roadmap Plan

Date: 2026-04-19 Status: Draft Upstream Spec: docs/superpowers/specs/2026-04-19-structured-fail-closed-improvement-roadmap-design.md Upstream Reconciliation: tests/fixtures/generated_scene/full_sweep_status_reconciliation_2026-04-19.json

Plan Intent

Coordinate the next improvement cycle for the 48 structured fail-closed records from the reconciled 102 sweep.

This is a roadmap-level plan. It intentionally starts with inventory and gap taxonomy before any implementation correction.

Baseline

Current reconciled 102 status:

Status	Count
auto-pass	48
fail-closed-known	48
adjudicated-valid-host-bridge	4
source-unreadable	2

Fail-closed distribution:

Inferred archetype	Count
paginated_enrichment	35
local_doc_pipeline	5
multi_mode_request	4
single_request_enrichment	2
host_bridge_workflow	1
page_state_eval	1

Scope Guardrails

1. do not add new scene families
2. do not start G4/G5
3. do not implement login recovery
4. do not implement full host runtime transport
5. do not implement local document attachment runtime
6. do not update scene_execution_board_2026-04-18.json
7. do not promote scenes directly from dry-run or follow-up results
8. do not reopen adjudicated-valid-host-bridge records
9. do not handle the 2 timeout records in this roadmap
10. do not loosen readiness gates to increase pass count

Workstreams

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

Phase 0: Freeze Structured Fail-Closed Baseline

Objective

Freeze the 48 fail-closed records as the only implementation-analysis input.

Tasks

1. read full_sweep_status_reconciliation_2026-04-19.json
2. verify total scene count is 102
3. verify fail-closed-known = 48
4. verify adjudicated-valid-host-bridge = 4
5. verify source-unreadable = 2
6. extract only records with reconciledStatus = fail-closed-known

Deliverables

1. frozen fail-closed input list
2. baseline validation summary

Acceptance Criteria

1. exactly 48 records enter this roadmap
2. route-adjudicated records are excluded
3. timeout records are excluded

Phase 1: Build Fail-Closed Inventory and Gap Taxonomy

Objective

Split the 48 records into actionable missing-contract buckets.

Tasks

1. inspect each fail-closed record
2. assign exactly one primary missing-contract label:
   • main_request_missing
   • pagination_plan_missing
   • enrichment_request_missing
   • join_key_missing
   • export_plan_missing
   • mode_matrix_missing
   • mode_request_contract_missing
   • single_request_enrichment_contract_missing
   • host_bridge_contract_missing
   • local_doc_contract_missing
   • bootstrap_target_unresolved
   • mixed_or_ambiguous_contract_gap
3. attach secondary labels when useful
4. group by inferred archetype and primary label
5. identify top repeated recoverable patterns

Deliverables

1. tests/fixtures/generated_scene/structured_fail_closed_inventory_2026-04-19.json
2. docs/superpowers/reports/2026-04-19-structured-fail-closed-inventory-report.md

Acceptance Criteria

1. all 48 records have exactly one primary label
2. the 35 paginated_enrichment records are explicitly split
3. no implementation is performed in this phase

Phase 2: G3 Paginated Enrichment Recovery Slice

Objective

Improve the largest bucket only when Phase 1 identifies repeated recoverable G3 patterns.

Tasks

1. select only paginated_enrichment records from the inventory
2. prioritize repeated primary labels in this order:
   • main_request_missing
   • pagination_plan_missing
   • enrichment_request_missing
   • join_key_missing
   • export_plan_missing
3. define bounded recovery rules for the top repeated pattern
4. implement only traceable evidence recovery
5. add regression tests for the recovered pattern
6. preserve canonical G3 and real-sample G3 pass

Deliverables

1. G3 recovery implementation if evidence supports it
2. regression tests for the recovered pattern
3. G3 recovery report

Acceptance Criteria

1. no scene-name hardcoding
2. no gate relaxation
3. recovered fields are traceable to source evidence
4. existing G3 canonical and real-sample tests pass

Phase 3: Small-Bucket Recovery Slice

Objective

Handle smaller buckets only after the G3 slice is complete or explicitly deferred.

Tasks

1. inspect local_doc_pipeline = 5
2. inspect multi_mode_request = 4
3. inspect single_request_enrichment = 2
4. inspect host_bridge_workflow = 1
5. choose at most one bounded non-G3 recovery slice
6. preserve existing real-sample passes for G1-E, G2, G6, G7

Deliverables

1. small-bucket recovery decision report
2. optional bounded implementation and tests

Acceptance Criteria

1. only one small-bucket slice is implemented in this roadmap
2. no G8 attachment/local document runtime is started
3. no full host runtime transport is started

Phase 4: Bootstrap Target Isolation

Objective

Keep the single page_state_eval + bootstrap_target record separate.

Tasks

1. identify the bootstrap target record
2. preserve it as a separate future input
3. do not implement login recovery
4. produce bootstrap isolation note

Deliverables

1. bootstrap isolation note

Acceptance Criteria

1. bootstrap target does not pollute G3 or small-bucket recovery
2. no login or bootstrap auto-recovery is implemented

Phase 5: Follow-Up Sweep and Coverage Delta

Objective

Measure the impact of bounded recovery work.

Tasks

1. rerun the fixed 102 scene sweep
2. produce a new follow-up result
3. compare against the reconciled baseline:
   • auto-pass delta
   • fail-closed-known delta
   • actionable coverage delta
   • timeout count
   • adjudicated host-bridge count
4. publish coverage delta report

Deliverables

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

Acceptance Criteria

1. scene set remains exactly 102
2. improvements are measured, not assumed
3. execution board remains unchanged
4. fail-closed count only drops when contracts close or become more specifically isolated

Milestone Order

The order is fixed:

1. Phase 0: freeze fail-closed baseline
2. Phase 1: build inventory and taxonomy
3. Phase 2: G3 recovery slice
4. Phase 3: small-bucket recovery slice
5. Phase 4: bootstrap target isolation
6. Phase 5: follow-up sweep and delta

Do not start implementation before Phase 1 is complete.

Do not start small-bucket recovery before the G3 slice is completed or explicitly deferred with reasons.

Completion Criteria

This roadmap is complete when:

1. all 48 structured fail-closed records are inventoried and labeled
2. the 35 G3 records are split into actionable contract-gap groups
3. at least the highest-value repeated recoverable pattern is either implemented or explicitly deferred
4. small buckets are inspected and at most one bounded slice is implemented
5. the bootstrap target remains isolated
6. a follow-up sweep quantifies coverage delta
7. no new family is introduced

Stop Statement

Stop after the follow-up sweep, delta report, and closure report.

Do not automatically update the execution board or start another roadmap inside this plan.