From 16b2415b220ae7c0c8c0ff8b995809ec2c022241 Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Sun, 19 Jul 2026 11:51:48 -0400
Subject: [PATCH 1/2] fix(repo): add pull_request_template scaffolding ##
 Related contract
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add .github/pull_request_template.md scaffolding the sections the
pr-issue-linkage check enforces: a native closing-keyword placeholder
(Closes #) plus ## Summary / ## Fix / ## Verification / ## Related, with
guidance in HTML comments. The validator (ci-workflows reusable) is the
SSOT; the template only mirrors its required ## Related heading and
closing-keyword contract so web/editor authors scaffold a passing body
without a red-CI round-trip. Comments are stripped by the validator, so
an unedited template correctly fails until filled — matching the check's
explicit anti-vacuous-pass design.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011V31qpAHP3jfs76B9d5Rfo
---
 .github/pull_request_template.md | 36 ++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 .github/pull_request_template.md

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 000000000..61514bbed
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,36 @@
+<!--
+Fill in each section and delete these guidance comments before submitting.
+
+The pr-issue-linkage check requires BOTH a native closing keyword AND a
+non-empty ## Related section. It strips HTML comments before validating, so an
+unedited template does not pass until you replace the placeholders with real
+content.
+-->
+
+Closes #
+
+<!--
+Native GitHub closing keyword for the issue this PR closes on merge: replace the
+bare `#` above with the issue number (e.g. Closes #123). Closes/Fixes/Resolves
+are all honored, case-insensitive. If this PR closes no issue, replace the whole
+line with: No linked issue
+-->
+
+## Summary
+
+<!-- What this PR changes and why, in a sentence or two. -->
+
+## Fix
+
+<!-- The concrete change: what you altered and how it addresses the problem. -->
+
+## Verification
+
+<!-- Concrete evidence the change works: commands run, gates passed, output. -->
+
+## Related
+
+<!--
+Issues, PRs, ADRs, or decision-log entries this PR references but does NOT close.
+Required non-empty. Use `Refs #N` to link an issue without closing it.
+-->

From 73e894fa269a771826342be9a71c53efe0f9586a Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Sun, 19 Jul 2026 12:23:00 -0400
Subject: [PATCH 2/2] docs(repo): document ## Related non-empty rule on
 no-linked-issue path

The pull_request_template ## Related guidance only showed the linking
case (Refs #N), leaving the "No linked issue" path under-documented: an
author could replace the closing keyword and leave ## Related empty,
which the pr-issue-linkage validator rejects (its only failure mode is
an empty section). Note that the section stays required and to use N/A
when nothing applies. Comment-only; the validator strips HTML comments,
so the template's fail-until-filled behavior is unchanged.

Addresses the claude[bot] review nit on #490.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .github/pull_request_template.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 61514bbed..024d2d959 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -32,5 +32,7 @@ line with: No linked issue
 
 <!--
 Issues, PRs, ADRs, or decision-log entries this PR references but does NOT close.
-Required non-empty. Use `Refs #N` to link an issue without closing it.
+Required non-empty even when the closing-keyword line above is `No linked issue`
+— if nothing applies, put `N/A`. Use `Refs #N` to link an issue without closing
+it.
 -->