From b3b983070055749d0d8ba71e63a76e1b78139804 Mon Sep 17 00:00:00 2001 From: claude-bot-andresmgsl Date: Fri, 24 Jul 2026 13:48:27 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20a=20post-merge=20acceptance=20criterion?= =?UTF-8?q?=20rides=20Refs=20#N=20=E2=80=94=20triage=20closes=20on=20the?= =?UTF-8?q?=20evidence?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Merging #143 auto-closed #137 with a post-merge criterion unmet: the PR carried Closes #137 as doctrine required, the criterion could only be checked after the merge, and the contract was silent on the disagreement between GitHub's keyword and the pipeline's close authority — the same disagreement the cross-repo carve-out already resolved, one case over. BUILDER.md gains the second exception beside the first: when the issue body marks a criterion post-merge, the same-repo PR uses Refs #N and triage closes by hand on the evidence. TRIAGE.md makes the criterion carry its own mechanism; REVIEWER.md lists Refs #N as a spec pointer and stops treating the reference-only PR as a defect; CONTRIBUTING.md points at the one home instead of restating. No machinery, no label (#151 D5). Closes #151 Co-Authored-By: Claude Fable 5 --- BUILDER.md | 13 ++++++++++++- CONTRIBUTING.md | 5 +++-- REVIEWER.md | 9 +++++++-- TRIAGE.md | 7 +++++++ changelog.d/151.md | 11 +++++++++++ 5 files changed, 40 insertions(+), 5 deletions(-) create mode 100644 changelog.d/151.md diff --git a/BUILDER.md b/BUILDER.md index 4ce7949..f80fe70 100644 --- a/BUILDER.md +++ b/BUILDER.md @@ -99,7 +99,18 @@ triage bug, and the move is to say so on the issue, not to guess. merged or closed and clears `offsite` in the same comment. The cross-repo merge never closes the authorizing issue. This codifies the linkage builders already used on rig#112 and ceremony #13/#16 rather than adding a - new review obligation. Drafts are invisible to the reviewer panel on + new review obligation. + `Closes #N` also does not survive a post-merge criterion: when the issue's + body states that an acceptance criterion can only be checked after the + merge — a live proof of a workflow trigger, a released-artifact check, + anything whose subject does not exist until the change is on the base + branch — the same-repo PR uses `Refs #N` instead, and triage closes the + issue by hand on the evidence, exactly as it does for cross-repo work. + The issue body is what says so; you never judge which issues qualify, and + absent that instruction `Closes #N` remains the default. The exception was + bought the hard way: #143 carried `Closes #137` as doctrine then required, + and the merge closed #137 with its post-merge criterion unmet (#151). + Drafts are invisible to the reviewer panel on purpose — the draft phase is yours. - **The issue's acceptance criteria are your definition of done.** Reproduce them as a checklist in the PR body and check them honestly as you go. If diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 940686a..2556581 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,8 +39,9 @@ The same flow the sibling repos run, and the part of this pipeline that is already proven: 1. **One issue, one PR**, opened as a **draft** while building, with - `Closes #N` in the body. Drafts are invisible to the reviewer panel on - purpose. Every behavior change writes one fragment, + `Closes #N` in the body — its exceptions (cross-repo work, a post-merge + criterion) live in [BUILDER.md](BUILDER.md). Drafts are invisible to the + reviewer panel on purpose. Every behavior change writes one fragment, `changelog.d/.md` — the exact prose to publish, nothing else (cross-repo work names it `-.md`; a grouped repo puts its `### Added` / `### Changed` / `### Fixed` headings inside the fragment). diff --git a/REVIEWER.md b/REVIEWER.md index bf405e0..22f102f 100644 --- a/REVIEWER.md +++ b/REVIEWER.md @@ -28,8 +28,13 @@ The machine reads only your **verdict**; humans read your reasons. In order of authority: -1. **The issue's acceptance criteria** — the PR's `Closes #N`, or its - cross-repo `Part of /#N`, names your spec. Check every +1. **The issue's acceptance criteria** — the PR's `Closes #N`, its + cross-repo `Part of /#N`, or its `Refs #N` when the issue + body marks a criterion post-merge, names your spec. That last shape is + not a defect: the issue directs it, triage owns that close, and a + request-changes on the "missing" keyword enforces the bug the shape + exists to fix — `Closes #137` closed its issue with a post-merge + criterion unmet (#151). Check every criterion; a PR that ships less than the issue says is a request-changes even if the code is beautiful. 2. **The repo's load-bearing constraints** — the rules bought with diff --git a/TRIAGE.md b/TRIAGE.md index 84e0626..8638b3e 100644 --- a/TRIAGE.md +++ b/TRIAGE.md @@ -79,6 +79,13 @@ Every issue you mint carries, in this order: - **Tasks**: the steps, checkboxed, in order. - **Acceptance criteria**: checkboxed, verifiable, and honest — these become the builder's definition of done and the reviewer's review spec, verbatim. + A criterion that can only be checked after the merge must carry its own + mechanism, in the criterion itself: that it is post-merge, that triage + owns the close, and that the PR references the issue with `Refs #N` + rather than `Closes #N`. A criterion that survives the merge only if + someone remembers to reopen the issue is an incomplete criterion — #137's + amended body is the worked example, reopened by hand after `Closes #137` + closed it with the criterion unmet (#151). - **Test plan**: what proves it, including the cases that must fail. - **Dependencies**: `Blocked by #N` / `Blocks #N`, and `Part of #E` when an epic organizes it. Name a cross-repo dependency the same way with its diff --git a/changelog.d/151.md b/changelog.d/151.md new file mode 100644 index 0000000..6f80c85 --- /dev/null +++ b/changelog.d/151.md @@ -0,0 +1,11 @@ +### Changed + +- Doctrine names the second `Closes #N` exception: a same-repo PR whose + authorizing issue marks an acceptance criterion post-merge uses `Refs #N`, + and triage closes the issue by hand on the evidence — merging #143 + auto-closed #137 with exactly such a criterion unmet, and no role had been + told otherwise. TRIAGE.md now requires a post-merge criterion to carry its + own mechanism (post-merge, triage closes, `Refs #N`), REVIEWER.md lists + `Refs #N` beside `Closes #N` and `Part of /#N` and stops + treating the reference-only PR as a defect, and CONTRIBUTING.md points at + BUILDER.md as the rule's one home (#151).