werkregie/doc/prs/2026-10-14-PR#65-watch-all-statuses.md

PR#65: watch-pr Reports READY Only When Each Required Check Passed

Version: patch

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.

Related Links

• PR#48, which brought watch-pr.

Problem

watch-pr reports READY for a WIP: pull request as soon as each status that its head has is green. A check that has not reported yet does not count, e.g. werkator/dependencies while only werkator has reported. The coding agent then removes WIP: before all checks have passed.

Non-Goals

• No change of the outcomes of a pull request in review.
• No list of expected checks of its own; the branch protection of the base branch names them.

Specification

Feature: READY waits for each required check

Scenario#65.01: a required check without a status holds READY back

… so that the agent removes WIP: only after all required checks passed.

• Given a WIP: pull request into main, whose branch protection requires werkator and werkator/dependencies
• And its head has only a green werkator
• When the agent watches it with watch-pr
• Then watch-pr keeps watching

Verified by

• PullRequestWatchTest "READY waits for each check the branch protection requires"
• PullRequestWatchTest "the required checks are those of the base branch's protection, none without status checks"

Scenario#65.02: READY once each required check passed

… so that the agent does not wait longer than needed.

• Given the same pull request, whose head has a green werkator and a green werkator/dependencies
• When the agent watches it with watch-pr
• Then watch-pr reports READY

Verified by

• PullRequestWatchTest "READY waits for each check the branch protection requires"

Solution

• watch-pr reads the base branch of the pull request; requiredChecks takes the status check patterns of its protection, which Gitea shows to each collaborator, none while the protection requires no checks.
• outcome reports READY for a draft only when each required pattern, other than ai-review/…, matches a status and all statuses are green; the review checks stay away from a draft, so they do not hold it.
• Gitea's patterns are globs: * stands for any text, ? for one character.
• Rebased onto main after werkregie PR#67: the reading of the branch stays in watchPullRequest, the decision in the tested requiredChecks.
• As this branch changes PullRequestWatch.kt, its methods come to a Mutation-CRAP of at most 15: outcome hands over to closed, apart, red, ready and reviewed, and PullRequestWatchTest "the token of the Gitea of a pull request: its own, from its variable, or none for an unknown Gitea" covers token, which no test reached.

Open Questions

None.