From 1ac5294f3d5a55887cc99c07e4e1102d987fe24e Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Tue, 15 Sep 2026 10:00:12 -0400
Subject: [PATCH] fix(pr-template): name one no-issue escape and require its
 reason

The top-of-template guidance told the author to write
`No related issue: <reason>`; the `## Related` comment told them to state
`No linked issue`, in backticks, with no reason. The `pr-contract` composite
masks inline code spans before matching, so the backticked form is invisible
to the linkage check: the PR draws the advisory `needs-issue-linkage` label
with nothing on screen to explain why.

Keep one escape, on the top line, written as plain text, with the reason
required and the backtick trap named. The `## Related` comment now points at
that line instead of offering a second form.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M98vWnd3jQJ19Pe6Uj7bV9
---
 .github/PULL_REQUEST_TEMPLATE.md | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index aaa8497..55008f0 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -6,8 +6,14 @@ merge, one closing keyword per issue (cross-repo:
 `Closes <owner>/<repo>#<issue-number>`). Supported keywords are GitHub's:
 https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue
 
-If this PR closes no issue, replace that line with `No related issue: <reason>`
-for an orphan PR (drift sweep, hotfix, refactor).
+If this PR closes no issue (an orphan PR: drift sweep, hotfix, refactor),
+replace that line with the no-issue escape and its reason, as plain text:
+
+No related issue: <reason>
+
+The reason is required. Write the escape without backticks: the gate masks
+inline code spans before matching, so a backticked escape is invisible to it
+and the PR draws the advisory `needs-issue-linkage` label anyway.
 
 Every `##` section below must be filled with real content. HTML comments like
 this one are stripped before validation, so an untouched template is reported
@@ -33,6 +39,7 @@ exact rule it applied and is authoritative over this comment.
 
 <!--
 Issues, PRs, or decision records this change touches without closing
-(one per line, e.g. `- Refs #<issue-number>`). If nothing applies, state
-`No linked issue` and why.
+(one per line, e.g. `- Refs #<issue-number>`). This section must not be empty:
+if nothing applies, say so in a sentence. The no-issue escape goes on the top
+line of this template, not here.
 -->