100 lines
2.7 KiB
Markdown
100 lines
2.7 KiB
Markdown
# Timeout Budget and Rerun Hygiene Design
|
|
|
|
> Date: 2026-04-19
|
|
> Status: Draft
|
|
> Upstream Diagnostic: `docs/superpowers/reports/2026-04-19-timeout-regression-diagnostic-report.md`
|
|
|
|
## Intent
|
|
|
|
Prevent budget-sensitive scenes from being miscounted as `source-unreadable` when they can resolve into:
|
|
|
|
1. `executed-pass`
|
|
2. structured `fail-closed`
|
|
|
|
under a bounded rerun budget.
|
|
|
|
This design does not attempt to improve scene understanding. It only changes timeout handling and rerun classification hygiene.
|
|
|
|
## Problem Statement
|
|
|
|
The timeout regression diagnostic produced:
|
|
|
|
| Scene id | Diagnostic label | Actual behavior under `90s` |
|
|
| --- | --- | --- |
|
|
| `sweep-015-scene` | `timeout-rerun-pass` | completed successfully |
|
|
| `sweep-025-scene` | `timeout-rerun-pass` | completed successfully |
|
|
| `sweep-040-scene` | `timeout-rerun-fail-closed` | resolved into structured fail-closed |
|
|
|
|
This means the current fixed `45s` budget is too coarse for a subset of scenes. It collapses:
|
|
|
|
1. budget-sensitive success
|
|
2. budget-sensitive fail-closed
|
|
3. true unreadable or hanging cases
|
|
|
|
into the same `source-unreadable` bucket.
|
|
|
|
## Scope
|
|
|
|
In scope:
|
|
|
|
1. define a bounded timeout-budget policy
|
|
2. define when a diagnostic rerun is allowed
|
|
3. define how rerun results should be classified
|
|
4. define output JSON and report for timeout hygiene verification
|
|
|
|
Out of scope:
|
|
|
|
1. analyzer logic changes
|
|
2. generator contract recovery changes
|
|
3. scene promotion
|
|
4. execution board updates
|
|
5. full `102` sweep improvement work
|
|
6. timeout implementation unrelated to rerun hygiene
|
|
|
|
## Policy
|
|
|
|
### Primary Sweep Budget
|
|
|
|
The initial sweep still runs with the fixed primary budget.
|
|
|
|
### Secondary Diagnostic Budget
|
|
|
|
When a scene ends with:
|
|
|
|
1. `source-unreadable`
|
|
2. reason `generator timeout after 45s`
|
|
|
|
it becomes eligible for one bounded rerun under a secondary timeout budget.
|
|
|
|
### Rerun Result Mapping
|
|
|
|
A bounded rerun may only map to:
|
|
|
|
1. `timeout-rerun-pass`
|
|
2. `timeout-rerun-fail-closed`
|
|
3. `timeout-rerun-timeout`
|
|
4. `timeout-rerun-error`
|
|
|
|
These are hygiene classifications, not promoted scene statuses.
|
|
|
|
### Board and Promotion Boundary
|
|
|
|
Even when rerun succeeds:
|
|
|
|
1. do not update `scene_execution_board_2026-04-18.json`
|
|
2. do not convert the scene to promoted status
|
|
3. do not silently merge the rerun result into canonical scene status
|
|
|
|
## Output
|
|
|
|
1. `tests/fixtures/generated_scene/timeout_budget_rerun_hygiene_2026-04-19.json`
|
|
2. `docs/superpowers/reports/2026-04-19-timeout-budget-rerun-hygiene-report.md`
|
|
|
|
## Success Criteria
|
|
|
|
1. timeout scenes are no longer treated as a single unreadable bucket in the hygiene layer
|
|
2. rerun-pass and rerun-fail-closed are distinguishable
|
|
3. true timeout cases remain distinguishable
|
|
4. no analyzer or generator implementation changes are made
|
|
5. no execution board updates are made
|