werkregie/doc/prs/2026-10-11-PR#17-pr-order.md

PR#17: Pull Requests Sorted by the User's Next Step

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

• werkregie PR#16: the pull request that the panel hid.

Problem

The panel "Offene Pull Requests" showed werkregie PR#16 far down, although only the user's merge was missing. The marker "Mergen" exists only for the user's own pull requests; an agent's pull request with GREEN gets no marker and goes among the ones that wait for others. In the agentic workflow the agents are the authors, so this is the normal case.

Non-Goals

• No merge button; the link leads to Gitea.
• No marker for what an agent has to do.

Specification

Feature: pull requests sorted by the user's next step

Scenario#17.01: an agent's pull request that passed everything asks for the merge

… so that the user sees that only the merge is missing.

• Given an agent's pull request whose head commit ai-reviewer or the user approved, with all commit statuses green, without conflict and without a scheduled automerge
• When the dashboard reads it from Gitea
• Then it carries the marker ➜ Mergen with the names of the approvers

Verified by

• GiteaSourceTest: "an agent's pull request that passed build and review waits for the user's merge", "an agent's pull request the user approved and that passed everything is the user's to merge", "the author's own approval does not make a pull request mergeable".
• Manual: werkregie PR#16 carries "Mergen, approved von ai-reviewer" on port 4748.

Scenario#17.02: no merge marker while the merge is not the user's

… so that the marker does not call for a merge that Gitea does itself or that cannot happen yet.

• Given such a pull request with a scheduled automerge, a running or failed check, or a conflict
• When the dashboard reads it from Gitea
• Then it carries no marker ➜ Mergen

Verified by

• GiteaSourceTest: "no merge for the user while Gitea merges it, a check runs or fails, or a conflict blocks it", "the last scheduled or cancelled merge in the timeline decides".

Scenario#17.03: the user's next step comes first

… so that the most important pull request stands at the top of the panel.

• Given open pull requests with different markers
• When the page shows the panel "Offene Pull Requests"
• Then the order is ⚠ Festgefahren, ✋ Dein Approval with ORANGE before YELLOW before no werkrevisor, ➜ Mergen, 🔧 Nacharbeit, ⏳ Wartet auf Review, ✓ Von dir approved, unmarked, drafts; a pull request with several markers ranks by its most urgent one

Verified by

• Manual: in the browser console, prRank with the time as second key orders ten example rows, one per marker and named after it, in the shuffled input: "stuck < orange-old < orange-new < yellow < kein < merge < rework < approved < none < draft". "kein" is Dein Approval without werkrevisor, "rework" also carries Wartet auf Review, "none" has no marker; "orange-old" changed three days before "orange-new".
• Manual: on port 4748 with the real data of git.javagil.de and dev.hostsharing.net, werkregie PR#16 stands first, before the pull requests that wait for review and the drafts.

Scenario#17.04: the longest waiting pull request first

… so that nothing waits at the end of a group for ever.

• Given two pull requests with the same marker
• When the page shows the panel "Offene Pull Requests"
• Then the one with the older last change comes first

Verified by

• Manual: "orange-old" before "orange-new" in the example rows of Scenario#17.03; "396 d" before "37 d" before "9 d" among the real ones.

Solution

• GiteaSource gives a foreign pull request the marker "Mergen" when anybody but its author approved its head commit, every commit status is green and nothing conflicts. For such a pull request it reads the timeline; the last pull_scheduled_merge or pull_cancel_scheduled_merge tells whether Gitea merges it itself.
• The page ranks a pull request by its most urgent marker, the approvals by verdict, and then by its last change, oldest first. Before, it took the first marker only and kept the order of the sources.
• The marker chips show in the new order; the demo marks its GREEN pull request "Mergen".
• dashboard/README.md describes the markers in their order.
• Version 0.7.0.

Open Questions

• Should "Mergen" wait until the review hints of werkrevisor are resolved? No: the commit statuses tell nothing about open threads; a green assessment with an approval is enough. werkregie PR#16 waited after its only thread was resolved.