Merge pull request #152 from claude-bot-andresmgsl/build/151-refs-not-closes

docs: a post-merge acceptance criterion rides Refs #N — triage closes on the evidence

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

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
+   `Closes #N` in the body — its exceptions (cross-repo work, a post-merge
-   purpose. Every behavior change writes one fragment,
+   criterion) live in [BUILDER.md](BUILDER.md). Drafts are invisible to the
+   reviewer panel on purpose. Every behavior change writes one fragment,
    `changelog.d/<issue>.md` — the exact prose to publish, nothing else
    (cross-repo work names it `<repo>-<issue>.md`; a grouped repo puts its
    `### Added` / `### Changed` / `### Fixed` headings inside the fragment).

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
+1. **The issue's acceptance criteria** — the PR's `Closes #N`, its
-   cross-repo `Part of <owner>/<repo>#N`, names your spec. Check every
+   cross-repo `Part of <owner>/<repo>#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

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

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 <owner>/<repo>#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).