claw/docs/superpowers/plans/2026-04-19-timeout-budget-rerun-hygiene-plan.md

Timeout Budget and Rerun Hygiene Plan

Date: 2026-04-19 Status: Draft Upstream Design: docs/superpowers/specs/2026-04-19-timeout-budget-rerun-hygiene-design.md Upstream Diagnostic: docs/superpowers/reports/2026-04-19-timeout-regression-diagnostic-report.md

Plan Intent

Create a bounded timeout-budget and rerun-hygiene layer so budget-sensitive scenes are not collapsed into a single source-unreadable bucket.

This plan is classification and reporting only. It does not change analyzer or generator code.

Scope Guardrails

1. do not modify src/generated_scene/analyzer.rs
2. do not modify src/generated_scene/generator.rs
3. do not update scene_execution_board_2026-04-18.json
4. do not promote scenes
5. do not rerun the full 102 sweep
6. do not treat rerun success as validated pass
7. do not start timeout implementation fixes

Fixed Input

The fixed input is:

tests/fixtures/generated_scene/timeout_regression_diagnostic_2026-04-19.json

Only the three diagnosed timeout records enter this plan.

Phase 0: Freeze Timeout Diagnostic Input

Objective

Freeze the timeout diagnostic records before hygiene mapping.

Tasks

1. read the timeout diagnostic JSON
2. verify total timeout records is 3
3. verify the label set is:
   • timeout-rerun-pass = 2
   • timeout-rerun-fail-closed = 1

Deliverables

1. frozen timeout diagnostic baseline

Acceptance Criteria

1. exactly 3 records enter this hygiene plan
2. no non-timeout scene enters the plan

Phase 1: Define Hygiene Mapping

Objective

Map timeout diagnostic results to explicit rerun hygiene statuses.

Tasks

1. map timeout-rerun-pass to rerun-resolved-pass
2. map timeout-rerun-fail-closed to rerun-resolved-fail-closed
3. preserve any future timeout as rerun-still-timeout
4. preserve any future unexpected exit as rerun-error

Deliverables

1. explicit rerun hygiene mapping table

Acceptance Criteria

1. each timeout diagnostic label maps to one hygiene status
2. pass-like rerun and fail-closed rerun remain distinct

Phase 2: Build Hygiene Output

Objective

Publish a hygiene-layer view for the three timeout records.

Tasks

1. write tests/fixtures/generated_scene/timeout_budget_rerun_hygiene_2026-04-19.json
2. include:
   • original timeout status
   • diagnostic label
   • rerun hygiene status
   • elapsed seconds
   • report presence
   • readiness if present
3. summarize how many records are:
   • rerun-resolved-pass
   • rerun-resolved-fail-closed
   • rerun-still-timeout
   • rerun-error

Deliverables

1. timeout budget hygiene JSON

Acceptance Criteria

1. all three timeout records appear in the hygiene JSON
2. each has exactly one hygiene status

Phase 3: Publish Report

Objective

Publish the bounded timeout hygiene report without changing scene status.

Tasks

1. write docs/superpowers/reports/2026-04-19-timeout-budget-rerun-hygiene-report.md
2. explain why sweep-040-scene should not be counted the same way as a hard unreadable source
3. explain why sweep-015-scene and sweep-025-scene are budget-sensitive pass candidates
4. state that this remains a hygiene layer, not a promotion layer

Deliverables

1. timeout budget and rerun hygiene report

Acceptance Criteria

1. report exists
2. no execution board update is made
3. no implementation change is made

Completion Criteria

This plan is complete when:

1. timeout diagnostic input is frozen
2. rerun hygiene mapping is defined
3. hygiene JSON is published
4. hygiene report is published

Stop Statement

Stop after publishing the timeout hygiene JSON and report.

Do not start timeout implementation or scene promotion inside this plan.