werkrevisor/docs/prs/2026-10-23-PR#136-attach-checked.md

PR#136: draft-review --attach --checked Posts a Draft with the Reason Why Its Last Points Do Not Hold

Version: minor

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#130: --attach posts the checked draft.

Problem

--attach posts a draft only after the line "> Draft: …" is deleted, as proof that someone checked the findings. A coding agent that works through the draft must not edit the report: the auto mode of Claude Code refuses that as a change of an audit record. And the deletion says nothing about why the remaining points of the review do not hold.

Non-Goals

• No posting of a draft that nobody confirmed: without --checked the draft line still blocks --attach.

Specification

Feature: a reason confirms the check of a draft

Scenario#136.01: --checked posts the draft with its reason

… so that a coding agent confirms its check without an edit of the report, and says why the rest does not hold.

• Given a draft of PR 343 with the line "> Draft: …"
• When the agent runs tools/draft-review 343 --attach --checked-file - with a reason of several lines on stdin
• Then the posted comment has the reason as "Checked before posting" at the top, instead of the draft line

Verified by

• test_reviewreport.AttachTest.test_a_reason_replaces_the_draft_line_and_is_posted
• test_reviewreport.AttachTest.test_a_reason_that_quotes_the_draft_line_stays_whole
• test_draftreview.MainTest.test_checked_passes_its_reason_to_attach
• test_draftreview.MainTest.test_checked_file_reads_a_multiline_reason_from_stdin

Scenario#136.02: an empty reason confirms nothing

… so that no draft reaches the PR without a stated reason or a human edit.

• Given a draft with the line "> Draft: …"
• When the agent runs --attach --checked "", or --attach without a reason
• Then nothing is posted, and the message names the missing reason

Verified by

• test_reviewreport.AttachTest.test_an_empty_reason_is_refused_before_any_write
• test_reviewreport.AttachTest.test_an_unchecked_draft_is_refused

Solution

• werkrevisor/reviewreport.py: attach takes a reason; confirm replaces the draft line with "> Checked before posting:" and the reason as a quote, or puts both under the title of a draft whose draft line a human deleted. An empty reason is refused before any write. tools/review-report takes --checked REASON and --checked-file FILE|-, only with --attach.
• werkrevisor/draftreview.py: the same options; it reads the reason and passes it as one argument --checked=…, so that a reason which starts with "-" is no option.
• README.md and the help text of tools/draft-review: the new options.