html_report: sort_phases superseded-bumping logic is hardcoded to gen-1 and needs generalisation for multi-generation timeouts

[decko]

Finding

File: src/raki/report/html_report.py:268

The sort_phases superseded bumping logic checks phase.generation == 1 when deciding which phases to bump. This correctly handles the current ticket's gen-1 scenario, but would produce incorrect results in future multi-generation timeout scenarios (e.g. an implement gen-2 times out, gen-3 supersedes it — gen-1 downstream phases that already completed would be incorrectly bumped).

Suggestion

Add a TODO/NOTE comment near line 268 acknowledging that this logic is gen-1-specific and will need generalisation if multi-generation timeout/supersede scenarios are introduced.

References

• Identified during review of ticket HTML report: superseded phases missing and gen-N implement sorts after submit when gen-1 is absent #319 (HTML report: superseded phases missing and gen-N implement sorts after submit when gen-1 is absent)

[decko]

Spec

Problem

sort_phases() in html_report.py has a bumping heuristic at line ~312:

if phase.generation == 1 and superseded_boundary >= 0 and phase_idx > superseded_boundary:
    return (max_non_superseded_gen + 1, phase_idx)

This correctly handles the current scenario: an implement(gen-1) times out, implement(gen-2) supersedes it, and subsequent gen-1 phases (verify(gen-1), review(gen-1)) are bumped to sort after the replacement generation. However, the condition is hardcoded to generation == 1.

In a hypothetical multi-generation timeout scenario — e.g., implement(gen-2) times out and implement(gen-3) supersedes it — the gen-2 downstream phases (verify(gen-2), review(gen-2)) would need to be bumped to after gen-3, but the generation == 1 check would not apply, leaving them sorted in the wrong position.

Current risk: Multi-generation timeout/supersede sequences do not yet occur in production. This is a known limitation that needs documentation, not an active bug.

Fix

Add a TODO comment near the bumping logic documenting the gen-1 assumption and the generalisation needed if multi-generation supersede sequences are introduced:

# TODO(#358): This bumping logic assumes only gen-1 phases are superseded.
# For multi-generation timeout scenarios (gen-N superseded by gen-N+1),
# the condition should be generalised to bump gen-N phases that follow
# a superseded phase boundary, not just gen-1. Implement when multi-gen
# supersede sequences appear in production data.
if phase.generation == 1 and superseded_boundary >= 0 and phase_idx > superseded_boundary:

Acceptance Criteria

• TODO(#358) comment added above the bumping condition in sort_phases()
• Comment accurately describes the limitation and the required generalisation
• No behavior changes — this is documentation only
• No tests needed

---

Plan

Step 1 — Add TODO comment in html_report.py

File: src/raki/report/html_report.py, line ~312 (the if phase.generation == 1 condition inside sort_phases())

Insert the comment block immediately above the condition. No code changes.

Step 2 — No towncrier fragment needed

This is a code comment addition only, with no user-facing behavior change. Use the misc fragment type if the project conventions require a fragment for all merged changes:

File: changes/358.misc

Added a code comment in ``sort_phases()`` documenting the gen-1 assumption in the superseded-phase bumping logic.

Estimated scope

• 4-line comment addition
• 0 test changes
• 1 misc changelog fragment (optional)