From 8aeea67d8d522f6c06cd44fd825a9617975494b0 Mon Sep 17 00:00:00 2001
From: cndgrr <59120057+cndgrr@users.noreply.github.com>
Date: Tue, 4 Aug 2026 12:12:52 +0000
Subject: [PATCH] docs(changelog): the citation is guard-enforced, not house
 style

Closes #262
---
 BUILDER.md         |  8 +++++++-
 CHANGELOG.md       |  3 +++
 changelog.d/262.md | 17 +++++++++++++++++
 3 files changed, 27 insertions(+), 1 deletion(-)
 create mode 100644 changelog.d/262.md

diff --git a/BUILDER.md b/BUILDER.md
index fe2d5fb..bc57d26 100644
--- a/BUILDER.md
+++ b/BUILDER.md
@@ -203,7 +203,13 @@ triage bug, and the move is to say so on the issue, not to guess.
   a change genuinely is one. An entry is at most 300 characters — the
   fragment guard reds longer (#167) — so a genuinely long change ships
   several short entries, never one long one; wrapping an entry over
-  continuation lines is fine and never counts against it. Never edit
+  continuation lines is fine and never counts against it. Every entry
+  **ends with its issue citation**, and the same guard reds an entry
+  without one: a single `(` group of `#N`, `repo#N` or `owner/repo#N`
+  references separated by `, `, then `)`, then the final `.` and nothing
+  after it — `(#262).` locally, `(#236, #250).` when one entry honestly
+  lands two. The citation need not name the fragment's own issue, because
+  the filename already carries the authorizing one (#262). Never edit
   `CHANGELOG.md` for an entry — the
   release PR assembles the section from the fragments (#112); the monotonic
   guard still refuses anything that deletes a shipped heading.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index dcd452c..491b733 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,9 @@ published verbatim as that release's body (lib/changelog.sh extracts it),
 so entries say what changed, cite the issue, and stop — at most 300
 characters each, guard-enforced on the PR that writes the fragment (#167);
 a genuinely long change ships several short entries, never one long one.
+The citation is guard-enforced too, and it closes the entry: one `(#N)`
+group, then the final `.` and nothing after it (#262). Sections published
+before that rule keep their prose; the guard reads fragments only.
 Entries arrive as fragments — one `changelog.d/<issue>.md` per PR, never
 an edit to this file — and the release PR assembles them into the next
 section here (`bin/changelog-assemble`, #112).
diff --git a/changelog.d/262.md b/changelog.d/262.md
new file mode 100644
index 0000000..aaf0a75
--- /dev/null
+++ b/changelog.d/262.md
@@ -0,0 +1,17 @@
+### Added
+
+- The fragment guard now requires each entry to end with its issue
+  citation: one `(#N)` group — local, `repo#N` or `owner/repo#N`
+  references separated by `, ` — then the final `.` and nothing after it
+  (#262).
+- The refusal distinguishes an entry carrying no reference at all from one
+  whose reference is present but not terminal, and names the shape to
+  write in both (#262).
+
+### Changed
+
+- `BUILDER.md` and `CHANGELOG.md` state the citation as guard-enforced
+  rather than as house style, beside the 300-character bound it now sits
+  next to (#262).
+- Four fragments in flight gained a terminal citation; published sections
+  are untouched, so no shipped prose is re-opened (#262).