werkrevisor/docs/prs/2026-10-18-PR#122-generated-sections.md

PR#122: The Reviews Skip Generated Sections of the Docs

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.

Problem

hsadmin-ng fills the ##### Verified by sections of its PR documents with tools/generate-verified-by. A generated section starts with the comment <!-- generated by tools/generate-verified-by --> and ends at the next heading; it has no end marker. Its lines hold long links to test sources and scenario reports, up to about 440 characters.

The writing rule exempts a long line only if the line is a link and nothing else. Lines such as using the use-case [X](…) or - Scenario-Reports “…”: [Branch](…), [master](…) hold text besides the links, so werkrevisor reports each of them as "line longer than 128 characters". The Codex review reports them too: it reads the 128-character rule in the AGENTS.md of the repository. Nobody can fix such a finding by hand, because the tool overwrites the section.

Non-Goals

• No change of tools/generate-verified-by in hsadmin-ng.
• No removal of generated sections from the diff that the model or Codex sees.
• No configuration of the marker per repository: any <!-- generated by … --> comment marks a generated section.

Specification

Feature: the writing rules skip generated sections

Scenario#122.01: a long line in a generated section is no violation

… so that a review reports nothing that only the generator could change.

• Given a changed PR document with a heading, then a comment <!-- generated by tools/generate-verified-by -->, then a line of 415 characters with text and links
• When werkrevisor checks the writing rules
• Then it reports no violation for that line

Verified by

• test_writing.GeneratedSectionTest.test_a_long_line_in_a_generated_section_is_no_violation

Scenario#122.02: the next heading ends the generated section

… so that hand-written text after a generated section is still checked.

• Given a changed PR document with a generated section, then a heading, then a hand-written line of 130 characters
• When werkrevisor checks the writing rules
• Then it reports "line longer than 128 characters" for the hand-written line

Verified by

• test_writing.GeneratedSectionTest.test_the_next_heading_ends_the_generated_section

Solution

• werkrevisor/writing.py: a line that starts with <!-- generated by starts a generated section; it and all lines up to the next heading are of the kind generated, which no writing rule checks.
• werkrevisor/codex.py: the prompt tells Codex to report nothing about a generated section.
• The [instructions] of .werkrevisor.toml and of the host configs under config/ tell the model the same.
• Version 0.49.1.

The change of .werkrevisor.toml makes this PR wait for the approval of the human. The host configs under config/ reach the machine configs only with tools/sync-host-config --apply.

Open Questions

None.

Additional Changes

• Werkbaum: #ops.release and the two Podman nodes (PR#114, PR#115) are [^]; since PR#118 each merge is released to mih09.