werkrevisor/docs/prs/2026-10-07-PR#44-writing-line-comments.md

PR#44: a writing-rule violation is a line comment and holds the merge

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

Since PR#32, a GREEN review with open hints approves, but holds the automerge until each line comment of werkrevisor has a reply and is resolved. A violation of the writing rules, e.g. a line longer than 128 characters, is only a line of the result comment. It gets no line comment, so it does not hold the merge: on 2026-10-07 a GREEN PR merged with such a violation, and its PR document is now a fixed state with the long line.

Non-Goals

• No change of the writing rules themselves.
• No change for the other reasons in the result comment, e.g. "model recommends merge with caution".

The Scenarios

Feature: writing-rule violations hold the merge like the hints of the model

A hint is a line comment of werkrevisor that leaves the verdict GREEN, but holds the merge until it is resolved.

Scenario#44.01: a writing-rule violation is a line comment that holds the merge

So that the author fixes the violation or answers it before the PR merges.

• Given automerge with [gate] hints_hold_merge = true
• When a PR adds a line longer than [writing] max_line_length, and the review is GREEN
• Then the violation is a line comment at that line
  • and werkrevisor approves, but schedules no merge

Verified by

• test_hints_hold_merge: test_a_writing_rule_violation_is_a_line_comment_that_holds_the_merge

Scenario#44.02: a resolved hint releases the merge

So that a reply is enough when the author keeps a line on purpose.

• Given automerge is on
  • and werkrevisor rated the PR GREEN
  • and werkrevisor wrote a hint as a line comment, e.g. on a line longer than 128 characters
  • and the merge waits for this hint
  • and the author resolved the hint
• When the review runs again for the same commit
• Then werkrevisor schedules the merge

Verified by

• test_hints_hold_merge: test_a_resolved_writing_rule_comment_releases_the_merge
• test_hints_hold_merge: test_a_restarted_review_schedules_the_merge_once_all_hints_are_resolved

The Solution

• Each writing-rule violation of the changed lines becomes a line comment of the bot review, at most 10 per review; further violations stay in the result comment and hold the merge as well.
• An open writing-rule comment at the same line is reused instead of repeated; the comments of the model's findings never reuse a writing-rule comment, and the other way round.
• If Gitea refuses the line comments, the violations stay in the result comment and hold the merge.
• werkrevisor 0.21.4.

Prerequisite PRs

• PR#43: werkrevisor 0.21.3, merged.