claw/docs/superpowers/specs/2026-04-19-timeout-rerun-hygiene-integration-design.md

Timeout Rerun Hygiene Integration Design

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

Intent

Integrate timeout rerun hygiene into future sweep interpretation and reconciliation reporting so budget-sensitive timeout scenes are not miscounted as a single source-unreadable bucket.

This is a reporting and classification integration only. It does not change analyzer or generator behavior.

Problem Statement

The timeout hygiene layer now distinguishes:

1. rerun-resolved-pass
2. rerun-resolved-fail-closed
3. rerun-still-timeout
4. rerun-error

Without integration, a future sweep or reconciliation still risks reporting:

source-unreadable = 3

when the actual hygiene-aware interpretation is:

1. 2 budget-sensitive pass candidates
2. 1 budget-sensitive fail-closed candidate
3. 0 persistent timeout after rerun

Scope

In scope:

1. define a hygiene-aware reporting schema
2. define how raw timeout status and rerun hygiene status coexist
3. define reconciliation-layer summary fields
4. define output JSON and report for the integrated view

Out of scope:

1. analyzer changes
2. generator changes
3. execution board updates
4. scene promotion
5. full 102 sweep rerun
6. timeout implementation fixes

Integration Rules

Raw Status Preservation

The raw sweep status is preserved.

Example:

source-unreadable

remains stored as the raw sweep result.

Hygiene Overlay

When a timeout record has a hygiene record, the integrated layer adds:

1. hygieneStatus
2. hygieneInterpretation

Hygiene Interpretation

Allowed integrated timeout interpretations:

1. timeout-as-pass-candidate
2. timeout-as-fail-closed-candidate
3. timeout-still-unreadable
4. timeout-rerun-error

Summary Output

The integrated summary must report both:

1. raw status counts
2. hygiene-aware timeout interpretation counts

This prevents lossy reporting.

Output

1. tests/fixtures/generated_scene/timeout_rerun_hygiene_integration_2026-04-19.json
2. docs/superpowers/reports/2026-04-19-timeout-rerun-hygiene-integration-report.md

Success Criteria

1. raw timeout counts remain visible
2. hygiene-aware timeout interpretation counts are added
3. the three timeout records become distinguishable in reconciliation reporting
4. no analyzer or generator code is changed
5. no execution board state is updated