werkrevisor/docs/prs/2026-10-08-PR#62-red-rounds.md

PR#62: after three rounds of RED, werkrevisor asks a human

WARNING: This document describes only the change applied in this PR. It may already be outdated once the next PR is merged. Historic PR documentation is not maintained along with new PRs; treat it as a snapshot.

The Problem

RED holds a PR until a new commit lifts it; no human can override it. Since PR#51 and PR#53, Jev can give RED for a very likely risk and a confirmed finding, and since 2026-10-08 this runs for werkator and werkprobe. A wrong RED, e.g. from a classifier that misjudges a file, cannot be lifted by the author: the coding agent commits again and again, and the PR never reaches a human. The design of 2026-10-08 limits these rounds and then escalates to a human.

Non-Goals

• No override of RED: after the limit, the PR stays blocked; the human decides how to go on, e.g. to restructure the PR, or to fix a wrong classification in its own PR.
• No check whether a commit really lowers the risk; each new head counts as a round.

The Scenarios

Feature: after three rounds of RED, werkrevisor asks a human

Background

• Given [gate] max_red_rounds = 3 and a human reviewer in [gate] human_reviewers

Scenario#62.01: the fourth RED in a row asks a human

So that a PR that the author cannot fix does not wait forever.

• Given werkrevisor rated the three earlier heads of the PR RED, one after the other
• When the review of the new head is RED again
• Then the review stays RED
  • and a reason says that the automatic rounds end and a human decides
  • and werkrevisor requests the review of the human reviewer

Verified by

• test_red_rounds: test_the_fourth_red_in_a_row_asks_a_human

Scenario#62.02: fewer rounds give RED as before

So that the author gets the rounds to fix the PR first.

• Given werkrevisor rated two earlier heads RED
• When the review of the new head is RED again
• Then the review is RED without escalation and without a review request

Verified by

• test_red_rounds: test_fewer_rounds_give_red_as_before

Scenario#62.03: a head without RED starts the count anew

So that an old problem that was fixed does not count against a new one.

• Given werkrevisor rated three earlier heads RED, and then one head GREEN
• When the review of the new head is RED
• Then the review is RED without escalation

Verified by

• test_red_rounds: test_a_head_without_red_starts_the_count_anew

The Solution

• [gate] max_red_rounds, host only, default 3; 0 never escalates.
• werkrevisor counts the earlier heads of the PR in a row whose own result comment is RED.
• From the limit on, a RED review gets the reason red_escalated and requests the human reviewers.
• The README names the key; docs/werkrevisor.werkbaum marks the node as merged.
• werkrevisor 0.29.0.

Prerequisite PRs

• PR#61: werkrevisor 0.28.1, merged.