@biffo/cli 0.298.27 → 0.298.28

package/_skeletons/plugin-template/scripts/check-closing-keywords.mjs

@@ -13,7 +13,9 @@
  *    what this file's lexical scan calls "deliberate" — see
  *    `deliberateClosingReferences` and the "3. Ground truth" section below
  *    (#1686). This is the one that reconciles the guard's model against the
- *    thing that actually acts, rather than trying to out-regex it.
+ *    thing that actually acts, rather than trying to out-regex it. Extended
+ *    in "3b" below (#1732) to a document `closingIssuesReferences` itself
+ *    cannot see.
  *
  * ── Three documents, not one (#1334, #1362) ──────────────────────────────
  *
@@ -153,6 +155,73 @@
  * meaning. What IS achievable, and what this does, is refuse to let our own
  * heuristic's blind spot silently diverge from GitHub's actual behaviour: the
  * two are reconciled every time, and a mismatch fails rather than passing.
+ *
+ * ── 3b. Ground truth's own blind spot: it never reads a commit (#1732) ───
+ *
+ * Section 3 above reconciles this file's lexical model against
+ * `closingIssuesReferences` — but that field is itself only a MODEL of one
+ * of the three documents GitHub honours: it is GitHub's ground truth for the
+ * PR BODY, computed by the same markdown-aware linker that renders the PR
+ * page, and it structurally cannot see a commit message at all. This repo's
+ * squash-merge strategy is `squash_merge_commit_message = COMMIT_MESSAGES`
+ * (confirmed via `gh api repos/{owner}/{repo}` → `squash_merge_commit_title`/
+ * `_message`), so the actual merge commit GitHub creates is composed from the
+ * branch's own commit messages, verbatim — not from the PR body at all. A
+ * closing-keyword hit that lives only in a commit message is therefore
+ * something GitHub WILL act on that section 3's check is a structural no-op
+ * for, not a considered "safe": `closingIssuesReferences.length > 0` is
+ * simply never true for it, no matter how dangerous the commit text is.
+ *
+ * Real instance: merging PR #1730 (this very guard's own #1686 fix)
+ * spuriously closed unrelated issue #1664. Its body quoted the historical
+ * bug it was fixing — "the one-word fix #1664 asked for" — inside a markdown
+ * code span, so GitHub's PR-body linker correctly ignored it and
+ * `closingIssuesReferences` read `[]`, exactly what section 3 checks and
+ * exactly what let it through. The identical phrase reached the real squash
+ * commit unchanged, in the PR's own commit message — WITHOUT a code span
+ * there, because a git commit message has no markdown semantics at all: a
+ * backtick in one is two literal characters, not a code-span delimiter, and
+ * GitHub's push-based "closes on merge to the default branch" keyword scan
+ * is a completely different mechanism from the PR-body linker, with no
+ * concept of markdown to respect. #1664 closed one second after merge.
+ *
+ * This is also why `stripCode` cannot simply be applied to a commit-message
+ * document the way it is to the body/title: doing so would make this file's
+ * OWN lexical scan (`closingReferences`, `deliberateClosingReferences`,
+ * `negatedClosingReferences` — checks 1 and 2 above, not just this one) less
+ * sensitive than GitHub's real behaviour for that document, the same
+ * "guard reads a different document from the one that acts" shape #1362
+ * names, just one level further in: the guard was reading the RIGHT document
+ * (#1334 already fixed that) but modelling it with the WRONG renderer's
+ * rules. Every function above therefore takes a `{ code: false }` option
+ * (see `documentsFor`'s `kind` tag and `assess`'s `rawScan`) that skips
+ * `stripCode` for a `'commit'` document — never for `'body'`/`'title'`,
+ * where a code span is genuine, GitHub-honoured protection.
+ *
+ * With that in place, `assess` runs a second, independent ground-truth
+ * reconciliation scoped to commit documents alone, using the commit text's
+ * own (now un-stripped) lexical hit as the ground truth `closingIssuesReferences`
+ * can never supply: on an otherwise-safe (non-deploy-only) path, if a commit
+ * document carries a hit and nothing anywhere reads as deliberate, fail —
+ * `kind: 'commit-ground-truth-mismatch'`. A hit on a genuinely deploy-only
+ * path is still caught by check 1 regardless, exactly as before; this only
+ * closes the gap check 1 always had by design (ordinary paths pass) and
+ * section 3 could not close for this one document (ground truth never
+ * arrives). See `scripts/check-closing-keywords-ground-truth.test.sh` for
+ * the fail-first reproduction of PR #1730's exact real shape, plus the
+ * corpus cases either side of it.
+ *
+ * Level of fix: still 3 (fail closed), same reasoning as section 3 — a
+ * commit message is prose an author legitimately writes, so intent cannot be
+ * derived with certainty here either. Not made MORE strict than GitHub's own
+ * closing behaviour: GitHub will act on a commit-message hit regardless of
+ * position or backticks, and this check only refuses the ones this file
+ * cannot explain as intentional, using the identical `deliberateClosingReferences`
+ * heuristic and its identical, already-accepted trade-off (see that
+ * function's docstring for two real, intentional, mid-line-parenthetical
+ * closes this heuristic already did not recognise before this change,
+ * unrelated to commits — this does not introduce a new blind spot, it
+ * extends an existing, documented one to a new document).
  */
 
 /** Closing keywords GitHub actually acts on, per its own documentation. */
@@ -207,11 +276,20 @@ export function stripCode(body) {
  * The issue references a body would close on merge.
  *
  * Matches `Closes #12`, `fixes owner/repo#12` and the `Closes: #12` colon
- * form. Ignores keywords inside code — see `stripCode`.
+ * form. Ignores keywords inside code — see `stripCode` — UNLESS `{ code:
+ * false }` is passed, which skips that blanking entirely.
+ *
+ * `code` must be `false` for a COMMIT MESSAGE document (#1732): a git commit
+ * message has no markdown semantics, so a backtick there is two literal
+ * characters, not a code-span delimiter, and GitHub's push-based "closes on
+ * merge to the default branch" keyword scan reads it exactly that way — it
+ * is not the same renderer as the PR body/title, which genuinely are
+ * markdown and where `stripCode` correctly models GitHub's own linker. See
+ * `assess`'s `rawForDoc` and the module docstring's "3b" section.
  */
-export function closingReferences(body) {
+export function closingReferences(body, { code = true } = {}) {
   if (!body) return []
-  const withoutCode = stripCode(body)
+  const withoutCode = code ? stripCode(body) : body
   const pattern = new RegExp(`\\b(${CLOSING_KEYWORDS.join('|')})\\b:?\\s+(${REFERENCE})`, 'gi')
   return [...withoutCode.matchAll(pattern)].map((m) => m[2])
 }
@@ -254,14 +332,29 @@ const CLAUSE_DECORATION = '(?:[-*•]\\s+|\\d+[.)]\\s+|#{1,6}\\s+|\\*{1,2})*'
  * `closingReferences` still does for checks 1 and 2 above.
  *
  * Known residual gap, accepted rather than solved: a trailer that starts
- * mid-line without sentence-ending punctuation before it (no case found in
- * this repo's history) reads as not-deliberate. That is the conservative
- * direction — it can make the ground-truth check (below) ask for a
- * clarifying reword it didn't strictly need, never the reverse.
+ * mid-line without sentence-ending punctuation before it reads as
+ * not-deliberate. That is the conservative direction — it can make the
+ * ground-truth check (below) ask for a clarifying reword it didn't strictly
+ * need, never the reverse. Two real instances, both intentional and both
+ * missed by this heuristic because a parenthesis is not a boundary this
+ * function looks for: `chore(core): mark services/pr-signer/ template-owned
+ * (closes #243/#548-shaped gap) (#581)` and `feat(cli): publish the CLI to
+ * npm as versioned `biffo` (closes #259) (#300)` (both real commit subjects,
+ * `git log --all --format='%B'`). Widening the boundary set to also start a
+ * clause after `(` was considered and rejected here: it would not even have
+ * caught either example (neither open-paren sits at a position this
+ * function currently recognises as a clause start), and it is exactly the
+ * kind of heuristic change #1628 warns against making without a full case
+ * matrix — see AGENTS.md. The remedy is the same as always: a `Closes #N` on
+ * its own line or sentence.
+ *
+ * `code`, same contract as `closingReferences` (#1732): pass `{ code: false
+ * }` for a commit-message document, since backticks are not markdown there
+ * and must not be treated as protection.
  */
-export function deliberateClosingReferences(text) {
+export function deliberateClosingReferences(text, { code = true } = {}) {
   if (!text) return []
-  const stripped = stripCode(text)
+  const stripped = code ? stripCode(text) : text
   const starts = new Set([0])
   const boundary = /\n|[.!?]\s+/g
   let m
@@ -333,11 +426,13 @@ const NEGATIONS = [
  * The negated closing references in a body, each with the line that carries
  * it — a guard that says only "no" gets worked around.
  *
- * Returns `[{ reference, line, lineNumber }]`, in body order.
+ * Returns `[{ reference, line, lineNumber }]`, in body order. `code`, same
+ * contract as `closingReferences` — pass `{ code: false }` for a commit
+ * message (#1732), since backticks do not protect text there.
  */
-export function negatedClosingReferences(body) {
+export function negatedClosingReferences(body, { code = true } = {}) {
   if (!body) return []
-  const text = stripCode(body)
+  const text = code ? stripCode(body) : body
   const authored = body.split('\n')
   const pattern = new RegExp(
     `(?:${NEGATIONS.join('|')})\\s+(?:${CLOSING_KEYWORDS.join('|')})\\b:?\\s+(${REFERENCE})`,
@@ -381,18 +476,26 @@ export function deployOnlyPaths(changedFiles) {
  * `commits` is the shape `gh pr view --json commits` returns: an array of
  * `{ messageHeadline, messageBody }`. Both are scanned — a keyword can sit
  * in either, and #1334's own repro had it in the headline.
+ *
+ * Each doc also carries `kind` — `'body'`, `'title'`, or `'commit'` (#1732).
+ * The PR body and title are genuinely markdown, rendered by GitHub's own PR
+ * page, so a code span in either is real protection. A commit message is
+ * neither: it has no markdown semantics for GitHub's push-based "closes on
+ * merge to the default branch" keyword scan, so `assess` must scan `'commit'`
+ * documents with `{ code: false }` — see that function and the module
+ * docstring's "3b" section.
  */
 export function documentsFor({ body, title, commits }) {
-  const docs = [{ source: 'the PR body', text: body }]
-  if (title) docs.push({ source: 'the PR title', text: title })
+  const docs = [{ source: 'the PR body', text: body, kind: 'body' }]
+  if (title) docs.push({ source: 'the PR title', text: title, kind: 'title' })
   const list = commits ?? []
   list.forEach((commit, i) => {
     const label = list.length === 1 ? 'the commit message' : `commit ${i + 1}`
     if (commit?.messageHeadline) {
-      docs.push({ source: `${label} (subject)`, text: commit.messageHeadline })
+      docs.push({ source: `${label} (subject)`, text: commit.messageHeadline, kind: 'commit' })
     }
     if (commit?.messageBody) {
-      docs.push({ source: `${label} (body)`, text: commit.messageBody })
+      docs.push({ source: `${label} (body)`, text: commit.messageBody, kind: 'commit' })
     }
   })
   return docs
@@ -420,28 +523,82 @@ export function documentsFor({ body, title, commits }) {
  * caller (and every existing test) keeps working unchanged, the same reason
  * `title`/`commits` are optional — see `documentsFor`.
  */
+// A document is markdown, and therefore genuinely protected by a code span,
+// only if GitHub's OWN renderer treats it that way. The PR body and title
+// are; a commit message is not — see `documentsFor` and the module
+// docstring's "3b" section (#1732). `closingReferences`, `deliberateClosingReferences`
+// and `negatedClosingReferences` all take `{ code: false }` to mean "scan
+// this raw, backticks are literal characters here".
+const rawScan = (doc) => ({ code: doc.kind !== 'commit' })
+
 export function assess({ body, title, commits, changedFiles, closingIssuesReferences = [] }) {
   const docs = documentsFor({ body, title, commits })
 
   const negated = docs.flatMap((doc) =>
-    negatedClosingReferences(doc.text).map((n) => ({ ...n, source: doc.source })),
+    negatedClosingReferences(doc.text, rawScan(doc)).map((n) => ({ ...n, source: doc.source })),
   )
   if (negated.length > 0) return { ok: false, kind: 'negated-keyword', negated }
 
-  if (closingIssuesReferences.length > 0) {
-    const deliberate = docs.some((doc) => deliberateClosingReferences(doc.text).length > 0)
-    if (!deliberate) {
-      return { ok: false, kind: 'ground-truth-mismatch', closingIssuesReferences }
-    }
+  // Whether ANY document reads as a deliberate closing directive — shared
+  // between the two ground-truth checks below, since both ask the identical
+  // question ("is this hit something the author actually meant"), just
+  // triggered by two different sources of ground truth.
+  const deliberate = docs.some(
+    (doc) => deliberateClosingReferences(doc.text, rawScan(doc)).length > 0,
+  )
+
+  if (closingIssuesReferences.length > 0 && !deliberate) {
+    return { ok: false, kind: 'ground-truth-mismatch', closingIssuesReferences }
   }
 
   const hits = docs
-    .map((doc) => ({ source: doc.source, references: closingReferences(doc.text) }))
+    .map((doc) => ({
+      source: doc.source,
+      isCommit: doc.kind === 'commit',
+      references: closingReferences(doc.text, rawScan(doc)),
+    }))
     .filter((h) => h.references.length > 0)
   if (hits.length === 0) return { ok: true, reason: 'no-closing-keyword' }
 
   const paths = deployOnlyPaths(changedFiles)
-  if (paths.length === 0) return { ok: true, reason: 'no-deploy-only-paths' }
+  if (paths.length === 0) {
+    // ── 3b. Ground truth, extended to the document GitHub actually squashes
+    // (#1732) ──────────────────────────────────────────────────────────────
+    //
+    // `closingIssuesReferences` is GitHub's OWN ground truth for what the PR
+    // BODY will close — but it structurally cannot see a commit message, and
+    // this repo's squash-merge composes the real merge commit from commit
+    // messages verbatim (`squash_merge_commit_message = COMMIT_MESSAGES`).
+    // A closing-keyword hit that lives only in a commit message is therefore
+    // something GitHub WILL act on that `closingIssuesReferences` can never
+    // confirm OR deny — the check above is a structural no-op for it, not a
+    // considered "safe". Real instance: PR #1730's body quoted the phrase
+    // "the one-word fix #1664 asked for" inside a markdown code span, so
+    // GitHub's PR-body linker correctly ignored it (closingIssuesReferences
+    // read `[]`) — but the identical phrase reached the actual squash commit
+    // verbatim from the branch's own commit message, WITHOUT a code span
+    // (a git commit message has no markdown semantics: a backtick there is
+    // two literal characters, not a code-span delimiter), and closed #1664
+    // one second after merge.
+    //
+    // So a commit-only hit gets the same reconciliation the body already
+    // gets from `closingIssuesReferences`, using the commit text itself as
+    // the ground truth `closingIssuesReferences` cannot supply: if a commit
+    // document carries a hit and nothing anywhere reads as deliberate, fail
+    // — regardless of path, and regardless of what `closingIssuesReferences`
+    // said, since it was never asked about this document.
+    //
+    // Known residual gap, same shape and same acceptance as
+    // `deliberateClosingReferences`'s own docstring: a deliberate close
+    // written as a mid-line parenthetical (`(closes #NNN)`) is not
+    // recognised as deliberate either, so it would ask for a reword it did
+    // not strictly need. Conservative direction only — see that docstring.
+    const commitHits = hits.filter((h) => h.isCommit)
+    if (commitHits.length > 0 && !deliberate) {
+      return { ok: false, kind: 'commit-ground-truth-mismatch', hits: commitHits }
+    }
+    return { ok: true, reason: 'no-deploy-only-paths' }
+  }
 
   if (hasVerifiedTrailer(body)) return { ok: true, reason: 'verified-trailer' }
 
@@ -452,6 +609,7 @@ export function assess({ body, title, commits, changedFiles, closingIssuesRefere
 export function formatFailure(result) {
   if (result.kind === 'negated-keyword') return formatNegatedFailure(result)
   if (result.kind === 'ground-truth-mismatch') return formatGroundTruthFailure(result)
+  if (result.kind === 'commit-ground-truth-mismatch') return formatCommitGroundTruthFailure(result)
   return formatDeployOnlyFailure(result)
 }
 
@@ -518,6 +676,48 @@ function formatGroundTruthFailure({ closingIssuesReferences }) {
   ].join('\n')
 }
 
+function formatCommitGroundTruthFailure({ hits }) {
+  const refs = [...new Set(hits.flatMap((h) => h.references))]
+  return [
+    `A COMMIT message would close ${refs.join(', ')} on merge — found in:`,
+    '',
+    ...hits.map((h) => `  - ${h.source}: ${h.references.join(', ')}`),
+    '',
+    "GitHub's own `closingIssuesReferences` cannot see this: that field",
+    'reflects only the PR body as GitHub itself parses it, and this repo',
+    "builds the real squash-merge commit from the branch's own commit",
+    'messages verbatim (squash_merge_commit_message = COMMIT_MESSAGES) — a',
+    'separate mechanism GitHub applies to that text with no markdown',
+    'awareness at all: a backtick in a commit message is a literal',
+    'character, not a code-span delimiter, so it does NOT protect a',
+    'closing keyword there the way it would in the PR body.',
+    '',
+    'This is #1732: PR #1730\'s body quoted "the one-word fix #1664 asked',
+    'for" inside a markdown code span, so closingIssuesReferences correctly',
+    'read [] — but the identical phrase, without a code span, was already',
+    "sitting in the branch's own commit message, and closed #1664 one",
+    'second after merge.',
+    '',
+    'Nothing in the PR body, title or commit messages reads as a DELIBERATE',
+    'closing directive (a keyword+reference at the start of the document, a',
+    'line, or a sentence). Either:',
+    '  - this close is NOT intended: reword the COMMIT (`git commit --amend`',
+    '    or an interactive rebase) so the keyword and reference are not',
+    '    adjacent, or move the reference into its own `Refs #N` line, and',
+    '    force-push; or',
+    '  - this close IS intended: make it a deliberate directive in the',
+    '    COMMIT — its own line, its own sentence, e.g. `Closes #1664` — so',
+    '    this file, and anyone reading `git log`, can tell the difference.',
+    '',
+    'Editing the PR body does NOT fix this: the commit message is what',
+    'reaches the squash-merge commit GitHub actually reads, independent of',
+    'anything in the PR description. Re-run after amending and force-pushing',
+    '— commits are read live, so a re-run genuinely re-evaluates:',
+    '',
+    '    gh run rerun <run-id> --failed',
+  ].join('\n')
+}
+
 function formatDeployOnlyFailure({ references, paths, hits }) {
   const shown = paths.slice(0, 10)
   const more = paths.length - shown.length

package/_skeletons/sibling-template/scripts/check-closing-keywords.mjs

@@ -13,7 +13,9 @@
  *    what this file's lexical scan calls "deliberate" — see
  *    `deliberateClosingReferences` and the "3. Ground truth" section below
  *    (#1686). This is the one that reconciles the guard's model against the
- *    thing that actually acts, rather than trying to out-regex it.
+ *    thing that actually acts, rather than trying to out-regex it. Extended
+ *    in "3b" below (#1732) to a document `closingIssuesReferences` itself
+ *    cannot see.
  *
  * ── Three documents, not one (#1334, #1362) ──────────────────────────────
  *
@@ -153,6 +155,73 @@
  * meaning. What IS achievable, and what this does, is refuse to let our own
  * heuristic's blind spot silently diverge from GitHub's actual behaviour: the
  * two are reconciled every time, and a mismatch fails rather than passing.
+ *
+ * ── 3b. Ground truth's own blind spot: it never reads a commit (#1732) ───
+ *
+ * Section 3 above reconciles this file's lexical model against
+ * `closingIssuesReferences` — but that field is itself only a MODEL of one
+ * of the three documents GitHub honours: it is GitHub's ground truth for the
+ * PR BODY, computed by the same markdown-aware linker that renders the PR
+ * page, and it structurally cannot see a commit message at all. This repo's
+ * squash-merge strategy is `squash_merge_commit_message = COMMIT_MESSAGES`
+ * (confirmed via `gh api repos/{owner}/{repo}` → `squash_merge_commit_title`/
+ * `_message`), so the actual merge commit GitHub creates is composed from the
+ * branch's own commit messages, verbatim — not from the PR body at all. A
+ * closing-keyword hit that lives only in a commit message is therefore
+ * something GitHub WILL act on that section 3's check is a structural no-op
+ * for, not a considered "safe": `closingIssuesReferences.length > 0` is
+ * simply never true for it, no matter how dangerous the commit text is.
+ *
+ * Real instance: merging PR #1730 (this very guard's own #1686 fix)
+ * spuriously closed unrelated issue #1664. Its body quoted the historical
+ * bug it was fixing — "the one-word fix #1664 asked for" — inside a markdown
+ * code span, so GitHub's PR-body linker correctly ignored it and
+ * `closingIssuesReferences` read `[]`, exactly what section 3 checks and
+ * exactly what let it through. The identical phrase reached the real squash
+ * commit unchanged, in the PR's own commit message — WITHOUT a code span
+ * there, because a git commit message has no markdown semantics at all: a
+ * backtick in one is two literal characters, not a code-span delimiter, and
+ * GitHub's push-based "closes on merge to the default branch" keyword scan
+ * is a completely different mechanism from the PR-body linker, with no
+ * concept of markdown to respect. #1664 closed one second after merge.
+ *
+ * This is also why `stripCode` cannot simply be applied to a commit-message
+ * document the way it is to the body/title: doing so would make this file's
+ * OWN lexical scan (`closingReferences`, `deliberateClosingReferences`,
+ * `negatedClosingReferences` — checks 1 and 2 above, not just this one) less
+ * sensitive than GitHub's real behaviour for that document, the same
+ * "guard reads a different document from the one that acts" shape #1362
+ * names, just one level further in: the guard was reading the RIGHT document
+ * (#1334 already fixed that) but modelling it with the WRONG renderer's
+ * rules. Every function above therefore takes a `{ code: false }` option
+ * (see `documentsFor`'s `kind` tag and `assess`'s `rawScan`) that skips
+ * `stripCode` for a `'commit'` document — never for `'body'`/`'title'`,
+ * where a code span is genuine, GitHub-honoured protection.
+ *
+ * With that in place, `assess` runs a second, independent ground-truth
+ * reconciliation scoped to commit documents alone, using the commit text's
+ * own (now un-stripped) lexical hit as the ground truth `closingIssuesReferences`
+ * can never supply: on an otherwise-safe (non-deploy-only) path, if a commit
+ * document carries a hit and nothing anywhere reads as deliberate, fail —
+ * `kind: 'commit-ground-truth-mismatch'`. A hit on a genuinely deploy-only
+ * path is still caught by check 1 regardless, exactly as before; this only
+ * closes the gap check 1 always had by design (ordinary paths pass) and
+ * section 3 could not close for this one document (ground truth never
+ * arrives). See `scripts/check-closing-keywords-ground-truth.test.sh` for
+ * the fail-first reproduction of PR #1730's exact real shape, plus the
+ * corpus cases either side of it.
+ *
+ * Level of fix: still 3 (fail closed), same reasoning as section 3 — a
+ * commit message is prose an author legitimately writes, so intent cannot be
+ * derived with certainty here either. Not made MORE strict than GitHub's own
+ * closing behaviour: GitHub will act on a commit-message hit regardless of
+ * position or backticks, and this check only refuses the ones this file
+ * cannot explain as intentional, using the identical `deliberateClosingReferences`
+ * heuristic and its identical, already-accepted trade-off (see that
+ * function's docstring for two real, intentional, mid-line-parenthetical
+ * closes this heuristic already did not recognise before this change,
+ * unrelated to commits — this does not introduce a new blind spot, it
+ * extends an existing, documented one to a new document).
  */
 
 /** Closing keywords GitHub actually acts on, per its own documentation. */
@@ -207,11 +276,20 @@ export function stripCode(body) {
  * The issue references a body would close on merge.
  *
  * Matches `Closes #12`, `fixes owner/repo#12` and the `Closes: #12` colon
- * form. Ignores keywords inside code — see `stripCode`.
+ * form. Ignores keywords inside code — see `stripCode` — UNLESS `{ code:
+ * false }` is passed, which skips that blanking entirely.
+ *
+ * `code` must be `false` for a COMMIT MESSAGE document (#1732): a git commit
+ * message has no markdown semantics, so a backtick there is two literal
+ * characters, not a code-span delimiter, and GitHub's push-based "closes on
+ * merge to the default branch" keyword scan reads it exactly that way — it
+ * is not the same renderer as the PR body/title, which genuinely are
+ * markdown and where `stripCode` correctly models GitHub's own linker. See
+ * `assess`'s `rawForDoc` and the module docstring's "3b" section.
  */
-export function closingReferences(body) {
+export function closingReferences(body, { code = true } = {}) {
   if (!body) return []
-  const withoutCode = stripCode(body)
+  const withoutCode = code ? stripCode(body) : body
   const pattern = new RegExp(`\\b(${CLOSING_KEYWORDS.join('|')})\\b:?\\s+(${REFERENCE})`, 'gi')
   return [...withoutCode.matchAll(pattern)].map((m) => m[2])
 }
@@ -254,14 +332,29 @@ const CLAUSE_DECORATION = '(?:[-*•]\\s+|\\d+[.)]\\s+|#{1,6}\\s+|\\*{1,2})*'
  * `closingReferences` still does for checks 1 and 2 above.
  *
  * Known residual gap, accepted rather than solved: a trailer that starts
- * mid-line without sentence-ending punctuation before it (no case found in
- * this repo's history) reads as not-deliberate. That is the conservative
- * direction — it can make the ground-truth check (below) ask for a
- * clarifying reword it didn't strictly need, never the reverse.
+ * mid-line without sentence-ending punctuation before it reads as
+ * not-deliberate. That is the conservative direction — it can make the
+ * ground-truth check (below) ask for a clarifying reword it didn't strictly
+ * need, never the reverse. Two real instances, both intentional and both
+ * missed by this heuristic because a parenthesis is not a boundary this
+ * function looks for: `chore(core): mark services/pr-signer/ template-owned
+ * (closes #243/#548-shaped gap) (#581)` and `feat(cli): publish the CLI to
+ * npm as versioned `biffo` (closes #259) (#300)` (both real commit subjects,
+ * `git log --all --format='%B'`). Widening the boundary set to also start a
+ * clause after `(` was considered and rejected here: it would not even have
+ * caught either example (neither open-paren sits at a position this
+ * function currently recognises as a clause start), and it is exactly the
+ * kind of heuristic change #1628 warns against making without a full case
+ * matrix — see AGENTS.md. The remedy is the same as always: a `Closes #N` on
+ * its own line or sentence.
+ *
+ * `code`, same contract as `closingReferences` (#1732): pass `{ code: false
+ * }` for a commit-message document, since backticks are not markdown there
+ * and must not be treated as protection.
  */
-export function deliberateClosingReferences(text) {
+export function deliberateClosingReferences(text, { code = true } = {}) {
   if (!text) return []
-  const stripped = stripCode(text)
+  const stripped = code ? stripCode(text) : text
   const starts = new Set([0])
   const boundary = /\n|[.!?]\s+/g
   let m
@@ -333,11 +426,13 @@ const NEGATIONS = [
  * The negated closing references in a body, each with the line that carries
  * it — a guard that says only "no" gets worked around.
  *
- * Returns `[{ reference, line, lineNumber }]`, in body order.
+ * Returns `[{ reference, line, lineNumber }]`, in body order. `code`, same
+ * contract as `closingReferences` — pass `{ code: false }` for a commit
+ * message (#1732), since backticks do not protect text there.
  */
-export function negatedClosingReferences(body) {
+export function negatedClosingReferences(body, { code = true } = {}) {
   if (!body) return []
-  const text = stripCode(body)
+  const text = code ? stripCode(body) : body
   const authored = body.split('\n')
   const pattern = new RegExp(
     `(?:${NEGATIONS.join('|')})\\s+(?:${CLOSING_KEYWORDS.join('|')})\\b:?\\s+(${REFERENCE})`,
@@ -381,18 +476,26 @@ export function deployOnlyPaths(changedFiles) {
  * `commits` is the shape `gh pr view --json commits` returns: an array of
  * `{ messageHeadline, messageBody }`. Both are scanned — a keyword can sit
  * in either, and #1334's own repro had it in the headline.
+ *
+ * Each doc also carries `kind` — `'body'`, `'title'`, or `'commit'` (#1732).
+ * The PR body and title are genuinely markdown, rendered by GitHub's own PR
+ * page, so a code span in either is real protection. A commit message is
+ * neither: it has no markdown semantics for GitHub's push-based "closes on
+ * merge to the default branch" keyword scan, so `assess` must scan `'commit'`
+ * documents with `{ code: false }` — see that function and the module
+ * docstring's "3b" section.
  */
 export function documentsFor({ body, title, commits }) {
-  const docs = [{ source: 'the PR body', text: body }]
-  if (title) docs.push({ source: 'the PR title', text: title })
+  const docs = [{ source: 'the PR body', text: body, kind: 'body' }]
+  if (title) docs.push({ source: 'the PR title', text: title, kind: 'title' })
   const list = commits ?? []
   list.forEach((commit, i) => {
     const label = list.length === 1 ? 'the commit message' : `commit ${i + 1}`
     if (commit?.messageHeadline) {
-      docs.push({ source: `${label} (subject)`, text: commit.messageHeadline })
+      docs.push({ source: `${label} (subject)`, text: commit.messageHeadline, kind: 'commit' })
     }
     if (commit?.messageBody) {
-      docs.push({ source: `${label} (body)`, text: commit.messageBody })
+      docs.push({ source: `${label} (body)`, text: commit.messageBody, kind: 'commit' })
     }
   })
   return docs
@@ -420,28 +523,82 @@ export function documentsFor({ body, title, commits }) {
  * caller (and every existing test) keeps working unchanged, the same reason
  * `title`/`commits` are optional — see `documentsFor`.
  */
+// A document is markdown, and therefore genuinely protected by a code span,
+// only if GitHub's OWN renderer treats it that way. The PR body and title
+// are; a commit message is not — see `documentsFor` and the module
+// docstring's "3b" section (#1732). `closingReferences`, `deliberateClosingReferences`
+// and `negatedClosingReferences` all take `{ code: false }` to mean "scan
+// this raw, backticks are literal characters here".
+const rawScan = (doc) => ({ code: doc.kind !== 'commit' })
+
 export function assess({ body, title, commits, changedFiles, closingIssuesReferences = [] }) {
   const docs = documentsFor({ body, title, commits })
 
   const negated = docs.flatMap((doc) =>
-    negatedClosingReferences(doc.text).map((n) => ({ ...n, source: doc.source })),
+    negatedClosingReferences(doc.text, rawScan(doc)).map((n) => ({ ...n, source: doc.source })),
   )
   if (negated.length > 0) return { ok: false, kind: 'negated-keyword', negated }
 
-  if (closingIssuesReferences.length > 0) {
-    const deliberate = docs.some((doc) => deliberateClosingReferences(doc.text).length > 0)
-    if (!deliberate) {
-      return { ok: false, kind: 'ground-truth-mismatch', closingIssuesReferences }
-    }
+  // Whether ANY document reads as a deliberate closing directive — shared
+  // between the two ground-truth checks below, since both ask the identical
+  // question ("is this hit something the author actually meant"), just
+  // triggered by two different sources of ground truth.
+  const deliberate = docs.some(
+    (doc) => deliberateClosingReferences(doc.text, rawScan(doc)).length > 0,
+  )
+
+  if (closingIssuesReferences.length > 0 && !deliberate) {
+    return { ok: false, kind: 'ground-truth-mismatch', closingIssuesReferences }
   }
 
   const hits = docs
-    .map((doc) => ({ source: doc.source, references: closingReferences(doc.text) }))
+    .map((doc) => ({
+      source: doc.source,
+      isCommit: doc.kind === 'commit',
+      references: closingReferences(doc.text, rawScan(doc)),
+    }))
     .filter((h) => h.references.length > 0)
   if (hits.length === 0) return { ok: true, reason: 'no-closing-keyword' }
 
   const paths = deployOnlyPaths(changedFiles)
-  if (paths.length === 0) return { ok: true, reason: 'no-deploy-only-paths' }
+  if (paths.length === 0) {
+    // ── 3b. Ground truth, extended to the document GitHub actually squashes
+    // (#1732) ──────────────────────────────────────────────────────────────
+    //
+    // `closingIssuesReferences` is GitHub's OWN ground truth for what the PR
+    // BODY will close — but it structurally cannot see a commit message, and
+    // this repo's squash-merge composes the real merge commit from commit
+    // messages verbatim (`squash_merge_commit_message = COMMIT_MESSAGES`).
+    // A closing-keyword hit that lives only in a commit message is therefore
+    // something GitHub WILL act on that `closingIssuesReferences` can never
+    // confirm OR deny — the check above is a structural no-op for it, not a
+    // considered "safe". Real instance: PR #1730's body quoted the phrase
+    // "the one-word fix #1664 asked for" inside a markdown code span, so
+    // GitHub's PR-body linker correctly ignored it (closingIssuesReferences
+    // read `[]`) — but the identical phrase reached the actual squash commit
+    // verbatim from the branch's own commit message, WITHOUT a code span
+    // (a git commit message has no markdown semantics: a backtick there is
+    // two literal characters, not a code-span delimiter), and closed #1664
+    // one second after merge.
+    //
+    // So a commit-only hit gets the same reconciliation the body already
+    // gets from `closingIssuesReferences`, using the commit text itself as
+    // the ground truth `closingIssuesReferences` cannot supply: if a commit
+    // document carries a hit and nothing anywhere reads as deliberate, fail
+    // — regardless of path, and regardless of what `closingIssuesReferences`
+    // said, since it was never asked about this document.
+    //
+    // Known residual gap, same shape and same acceptance as
+    // `deliberateClosingReferences`'s own docstring: a deliberate close
+    // written as a mid-line parenthetical (`(closes #NNN)`) is not
+    // recognised as deliberate either, so it would ask for a reword it did
+    // not strictly need. Conservative direction only — see that docstring.
+    const commitHits = hits.filter((h) => h.isCommit)
+    if (commitHits.length > 0 && !deliberate) {
+      return { ok: false, kind: 'commit-ground-truth-mismatch', hits: commitHits }
+    }
+    return { ok: true, reason: 'no-deploy-only-paths' }
+  }
 
   if (hasVerifiedTrailer(body)) return { ok: true, reason: 'verified-trailer' }
 
@@ -452,6 +609,7 @@ export function assess({ body, title, commits, changedFiles, closingIssuesRefere
 export function formatFailure(result) {
   if (result.kind === 'negated-keyword') return formatNegatedFailure(result)
   if (result.kind === 'ground-truth-mismatch') return formatGroundTruthFailure(result)
+  if (result.kind === 'commit-ground-truth-mismatch') return formatCommitGroundTruthFailure(result)
   return formatDeployOnlyFailure(result)
 }
 
@@ -518,6 +676,48 @@ function formatGroundTruthFailure({ closingIssuesReferences }) {
   ].join('\n')
 }
 
+function formatCommitGroundTruthFailure({ hits }) {
+  const refs = [...new Set(hits.flatMap((h) => h.references))]
+  return [
+    `A COMMIT message would close ${refs.join(', ')} on merge — found in:`,
+    '',
+    ...hits.map((h) => `  - ${h.source}: ${h.references.join(', ')}`),
+    '',
+    "GitHub's own `closingIssuesReferences` cannot see this: that field",
+    'reflects only the PR body as GitHub itself parses it, and this repo',
+    "builds the real squash-merge commit from the branch's own commit",
+    'messages verbatim (squash_merge_commit_message = COMMIT_MESSAGES) — a',
+    'separate mechanism GitHub applies to that text with no markdown',
+    'awareness at all: a backtick in a commit message is a literal',
+    'character, not a code-span delimiter, so it does NOT protect a',
+    'closing keyword there the way it would in the PR body.',
+    '',
+    'This is #1732: PR #1730\'s body quoted "the one-word fix #1664 asked',
+    'for" inside a markdown code span, so closingIssuesReferences correctly',
+    'read [] — but the identical phrase, without a code span, was already',
+    "sitting in the branch's own commit message, and closed #1664 one",
+    'second after merge.',
+    '',
+    'Nothing in the PR body, title or commit messages reads as a DELIBERATE',
+    'closing directive (a keyword+reference at the start of the document, a',
+    'line, or a sentence). Either:',
+    '  - this close is NOT intended: reword the COMMIT (`git commit --amend`',
+    '    or an interactive rebase) so the keyword and reference are not',
+    '    adjacent, or move the reference into its own `Refs #N` line, and',
+    '    force-push; or',
+    '  - this close IS intended: make it a deliberate directive in the',
+    '    COMMIT — its own line, its own sentence, e.g. `Closes #1664` — so',
+    '    this file, and anyone reading `git log`, can tell the difference.',
+    '',
+    'Editing the PR body does NOT fix this: the commit message is what',
+    'reaches the squash-merge commit GitHub actually reads, independent of',
+    'anything in the PR description. Re-run after amending and force-pushing',
+    '— commits are read live, so a re-run genuinely re-evaluates:',
+    '',
+    '    gh run rerun <run-id> --failed',
+  ].join('\n')
+}
+
 function formatDeployOnlyFailure({ references, paths, hits }) {
   const shown = paths.slice(0, 10)
   const more = paths.length - shown.length

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.298.27",
+  "version": "0.298.28",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",