enhance(#1549): validate PR-title issue-ref convention at open time (#1576)

* enhance(#1549): validate PR-title issue-ref convention at open time

The release changelog is title-driven: release.yml generates "What's Changed"
from PR titles, then format-github-release-notes.cjs buckets each line by its
conventional-commit prefix and relies on a `(#<issue>)` in the title to render
the issue link. Both rules were enforced only socially, so titles like
`fix(core): ...` (no issue link) and `[security] fix(...): ...` (leading tag
defeats the `^fix` bucket anchor -> mis-filed under Enhancement) silently broke
the changelog, landing on the maintainer as release-time cleanup.

Extract the title matcher into one shared module consumed by BOTH the changelog
classifier and a new PR-title CI gate, so a title that passes the gate cannot
mis-bucket in the changelog (single source of truth).

- scripts/lib/conventional-title.cjs (new): classifyBucket + evaluatePrTitle +
  the anchored regexes. One matcher, two consumers.
- scripts/release-notes/format-github-release-notes.cjs: classifyTitle now
  delegates to classifyBucket (behavior preserved; existing tests green).
- .github/workflows/pr-title-validator.yml (new): runs evaluatePrTitle on
  pull_request opened/edited/reopened/synchronize, for ALL authors (the drift
  came from member PRs). Trusted base-ref checkout; WARN_ONLY knob for rollout.
- tests/conventional-title.test.cjs (new): bucket + gate cases incl. the
  leading-tag mis-bucket (backfills the untested classifyTitle case) and a
  cross-check that the classifier delegates to the shared matcher.
- CONTRIBUTING.md: document the `type(#<issue>):` rule and no-leading-tag.

Claude-Session: https://claude.ai/code/session_01UMV5Qr3H4oFikbuiEauGQk

* fix(#1549): check out the PR in pr-title-validator so the new matcher resolves

The workflow checked out the base branch (next) as a trusted policy source, but
the shared matcher (scripts/lib/conventional-title.cjs) is introduced by this PR
and does not exist on next yet — so require() failed and validate-title errored
on its own introducing PR. Check out the PR's merge ref instead: the matcher
under review is present, the check is self-consistent, and a fork pull_request
runs read-only with no secrets, so running the PR's own pure-string regex is
safe.

* fix(#1549): move conventional-title.cjs out of installed scripts/lib/

bin/install.js bundles every file under scripts/lib/ into the user-installed
payload (the changeset CLI's dependencies), and install.test.cjs (#935) asserts
that exact set. The new matcher is release/CI tooling that must NOT ship to
users, so placing it in scripts/lib/ both broke the install manifest test and
would have shipped dead code. Relocate it next to its consumer in
scripts/release-notes/ (which the installer does not copy) and update the three
require paths (classifier, workflow, test) + the CONTRIBUTING reference.

install.test.cjs now 125/125; conventional-title + release-notes suites green;
lint:ci clean.

* fix(#1549): load title matcher from trusted base ref, not PR code

Addresses review (Solvely-Colin + trek-e): the gate checked out the PR
merge ref and require()'d evaluatePrTitle from PR-controlled code, so any
future PR could edit conventional-title.cjs to return { valid: true } and
wave its own malformed title through — a self-bypassable required check.

Load the matcher from a base-branch checkout instead (ref:
github.event.pull_request.base.ref), the same trusted-policy-source pattern
pr-target-validator.yml already uses. The PR can change its title but not
the ruler that measures it. An existsSync bootstrap guard skips the check
when the matcher isn't on the base branch yet (the introducing PR); every
PR after merge is fully gated. This keeps the single shared matcher (#1549's
whole point) rather than forking the regex into the workflow.

Also per review:
- add tests/conventional-title.property.test.cjs (fast-check): any
  `type(#n): summary` round-trips to valid; evaluatePrTitle/classifyBucket
  are total functions (never throw).
- pin the `fix(#):` zero-digit boundary as missing-issue-ref.

Claude-Session: https://claude.ai/code/session_01VqUHNQCh71pEqjo96zkgQL

---------

Co-authored-by: Tom Boucher <trekkie@nomorestars.com>

scripts/release-notes/conventional-title.cjs

@@ -0,0 +1,88 @@
+'use strict';
+
+/**
+ * Single source of truth for conventional-commit PR-title parsing.
+ *
+ * Consumed by BOTH:
+ *   - the release-notes changelog classifier
+ *     (scripts/release-notes/format-github-release-notes.cjs), and
+ *   - the PR-title CI gate (.github/workflows/pr-title-validator.yml, via
+ *     evaluatePrTitle).
+ *
+ * Keeping one matcher here is the point of #1549: a forked copy of the regex
+ * would let the gate accept a title that the changelog then mis-buckets. Both
+ * the bucket anchors and the gate must read the title the same way.
+ */
+
+// Bucket anchors. The leading `^` is load-bearing: the changelog buckets on the
+// type at the START of the title. Anything before it (e.g. a `[security] ` tag)
+// defeats the anchor and silently mis-files the entry — which is exactly the
+// drift the PR-title gate below rejects at open time.
+const FEATURE_RE = /^feat(?:ure)?\s*(?:\(|!|:)/i;
+const FIX_RE = /^fix\s*(?:\(|!|:)/i;
+
+// A well-formed conventional header at the START of the title:
+//   <type>[(<scope>)][!]:
+// e.g. `fix(#1542):`, `feat(#39)!:`, `fix:`, `enhance(verify-phase):`.
+// Anchored with `^` so a leading tag/prefix fails to match (no `bad-prefix`).
+const HEADER_RE = /^([a-z]+)(\([^)]*\))?(!)?:/i;
+
+// An issue reference inside a scope: `(#123)`, `(#123, core)`, etc.
+const ISSUE_REF_IN_SCOPE_RE = /#\d+/;
+
+/**
+ * Classify a clean conventional title into a changelog bucket.
+ * Callers that hold a full changelog bullet line (with a `* ` marker and a
+ * ` by @author` suffix) must strip those first; this operates on the title.
+ *
+ * @param {string} title
+ * @returns {'Feature'|'Fix'|'Enhancement'}
+ */
+function classifyBucket(title) {
+  const t = String(title == null ? '' : title).trim();
+  if (FEATURE_RE.test(t)) return 'Feature';
+  if (FIX_RE.test(t)) return 'Fix';
+  return 'Enhancement';
+}
+
+const REQUIRED_FORMAT_MESSAGE = [
+  'PR title must follow `type(#<issue>): summary`.',
+  'The type must come first (no leading tags like `[security]`) and the scope',
+  'must carry the linked issue ref so the release changelog links to it.',
+  'Examples: `fix(#1542): roadmap rollback`, `feat(#39)!: drop legacy flag`,',
+  '`enhance(#1549): add PR-title validator`.',
+].join(' ');
+
+/**
+ * Validate a PR title against the convention the changelog depends on (#1549).
+ *
+ * @param {{ title?: string }} input
+ * @returns {{ valid: true, reason: 'valid' }
+ *          | { valid: false, reason: 'bad-prefix'|'missing-issue-ref', message: string }}
+ */
+function evaluatePrTitle({ title } = {}) {
+  const t = String(title == null ? '' : title).trim();
+
+  const m = HEADER_RE.exec(t);
+  if (!m) {
+    // No clean `type[(scope)][!]:` at the start — covers leading tags,
+    // `Revert "..."`, empty, and freeform titles.
+    return { valid: false, reason: 'bad-prefix', message: REQUIRED_FORMAT_MESSAGE };
+  }
+
+  const scope = m[2]; // includes the parens, e.g. "(#1542)" — or undefined
+  if (!scope || !ISSUE_REF_IN_SCOPE_RE.test(scope)) {
+    return { valid: false, reason: 'missing-issue-ref', message: REQUIRED_FORMAT_MESSAGE };
+  }
+
+  return { valid: true, reason: 'valid' };
+}
+
+module.exports = {
+  FEATURE_RE,
+  FIX_RE,
+  HEADER_RE,
+  classifyBucket,
+  evaluatePrTitle,
+  REQUIRED_FORMAT_MESSAGE,
+};

scripts/release-notes/format-github-release-notes.cjs

@@ -5,6 +5,7 @@ const os = require('os');
 const fs = require('fs');
 const { execFileSync } = require('child_process');
 const { runMain, ExitError } = require('../lib/cli-exit.cjs');
+const { classifyBucket } = require('./conventional-title.cjs');
 
 /**
  * Classify a What's-Changed bullet line into 'Feature', 'Fix', or 'Enhancement'.
@@ -19,9 +20,9 @@ function classifyTitle(bulletLine) {
   const byIdx = withoutMarker.indexOf(' by @');
   const title = (byIdx !== -1 ? withoutMarker.slice(0, byIdx) : withoutMarker).trim();
 
-  if (/^feat(?:ure)?\s*(?:\(|!|:)/i.test(title)) return 'Feature';
-  if (/^fix\s*(?:\(|!|:)/i.test(title)) return 'Fix';
-  return 'Enhancement';
+  // Delegate to the shared matcher so the gate and the changelog can never
+  // disagree on bucketing (#1549 — single source of truth).
+  return classifyBucket(title);
 }
 
 /**