ci: bump detection reads BREAKING CHANGE footers, not prose in subjects

release.yml grepped subjects with -i for "BREAKING[ -]CHANGE" anywhere, so a
subject like "docs: explain breaking-change policy" would have cut a major
(reproduced: the old regex matches it), while a real conventional-commit
`BREAKING CHANGE:` footer in a body was never seen (only %s was scanned).
pages.yml carried a hand-copied variant of the same pattern.

.github/scripts/bump-kind.sh now owns the decision for both workflows. It reads
NUL-separated full messages and prints major/minor/patch/none:
- major: feat/fix subject with `!`, or a body line `BREAKING CHANGE: ` /
  `BREAKING-CHANGE: ` (case-sensitive, footer position)
- minor: feat; patch: fix; none: everything else
release.yml feeds `git log RANGE --format='%B%x00'`; pages.yml feeds the push
payload's messages via jq. tests/test_bump_kind.py (8 cases) runs in
validate-harness.

Closes #324

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: TMHSDigital

.github/scripts/bump-kind.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Print the release bump a set of commits calls for: major, minor, patch or none.
+#
+# stdin: full commit messages, each terminated by NUL
+#   git log RANGE --format='%B%x00' | bash .github/scripts/bump-kind.sh
+#
+#   major  a feat/fix subject marked breaking (`feat!:`, `fix(scope)!:`), or a
+#          body line starting `BREAKING CHANGE:` / `BREAKING-CHANGE:` (the
+#          conventional-commit footer; case-sensitive, so prose that merely
+#          mentions a breaking change in a subject does not cut a major)
+#   minor  a feat/feature subject
+#   patch  a fix subject
+#   none   anything else (docs, chore, ci, ...), which does not release
+#
+# release.yml uses the level; pages.yml only needs "not none". Both call this
+# script so the two decisions cannot drift apart.
+set -euo pipefail
+
+rank=0
+while IFS= read -r -d '' msg || [ -n "${msg:-}" ]; do
+  msg="${msg#$'\n'}"
+  subject="${msg%%$'\n'*}"
+  if printf '%s\n' "$subject" | grep -qiE '^(feat|feature|fix)(\(.+\))?!:' \
+     || printf '%s\n' "$msg" | tail -n +2 | grep -qE '^BREAKING[ -]CHANGE: '; then
+    rank=3
+  elif printf '%s\n' "$subject" | grep -qiE '^(feat|feature)(\(.+\))?:'; then
+    [ "$rank" -lt 2 ] && rank=2
+  elif printf '%s\n' "$subject" | grep -qiE '^fix(\(.+\))?:'; then
+    [ "$rank" -lt 1 ] && rank=1
+  fi
+  msg=""
+done
+
+case "$rank" in
+  3) echo major ;;
+  2) echo minor ;;
+  1) echo patch ;;
+  *) echo none ;;
+esac

.github/workflows/pages.yml

@@ -37,22 +37,25 @@ jobs:
   # A push that will cut a release gets its deploy from release.yml, which dispatches
   # this workflow after committing the version bump. Deploying on the push too only
   # built a page that the dispatch then cancelled (8 of 9 push runs measured, #215).
-  # The pattern mirrors release.yml's "Determine bump type" step exactly. If that
+  # Both workflows call .github/scripts/bump-kind.sh, so the decision cannot drift. If that
   # release fails, redeploy by hand: Actions > Deploy GitHub Pages > Run workflow.
   gate:
     runs-on: ubuntu-latest
     outputs:
       deploy: ${{ steps.decide.outputs.deploy }}
     steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          sparse-checkout: .github/scripts
       - id: decide
         env:
           EVENT: ${{ github.event_name }}
           COMMITS: ${{ toJSON(github.event.commits) }}
         run: |
           deploy=true
-          if [ "$EVENT" = "push" ] && echo "$COMMITS" \
-              | jq -r '.[].message | split("\n")[0]' \
-              | grep -qiE '^(feat|feature|fix)(\(.+\))?!?:|BREAKING[ -]CHANGE'; then
+          if [ "$EVENT" = "push" ] && [ "$(echo "$COMMITS" \
+              | jq -j '.[].message + "\u0000"' \
+              | bash .github/scripts/bump-kind.sh)" != "none" ]; then
             deploy=false
             echo "Release-worthy push: release.yml dispatches Pages after the version bump."
           fi

.github/workflows/release.yml

@@ -62,31 +62,25 @@ jobs:
         id: bump
         run: |
           last_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
-          if [ -z "$last_tag" ]; then
-            commits=$(git log --oneline --format="%s")
-          else
-            commits=$(git log "$last_tag"..HEAD --oneline --format="%s")
-          fi
+          range="${last_tag:+$last_tag..}HEAD"
 
           echo "Commits since last release:"
-          echo "$commits"
+          git log "$range" --format="%s"
 
-          # Release ONLY when a commit subject since the last tag carries a release-worthy
-          # conventional prefix. docs/chore/ci/refactor/test/style/build/perf land WITHOUT
-          # cutting a release. A mixed push (docs + a real fix) still releases: the scan
-          # matches any release-worthy commit in the range regardless of the others.
+          # Release ONLY when a commit since the last tag is release-worthy:
+          # feat/fix subjects, `!` breaking subjects, or a `BREAKING CHANGE:` body
+          # footer. docs/chore/ci/refactor/test/style/build/perf land WITHOUT
+          # cutting a release; a mixed push (docs + a real fix) still releases.
+          # .github/scripts/bump-kind.sh owns the patterns (pages.yml shares it).
           # [skip ci] (guarded on the job) remains an optional belt-and-suspenders override.
+          kind=$(git log "$range" --format='%B%x00' | bash .github/scripts/bump-kind.sh)
           bump="patch"
           release="false"
           if [ -z "$last_tag" ]; then
             # Initial release: no prior tag -> cut the first release at the current VERSION.
             release="true"
-          elif echo "$commits" | grep -qiE "^(feat|feature|fix)(\(.+\))?!:|BREAKING[ -]CHANGE"; then
-            bump="major"; release="true"
-          elif echo "$commits" | grep -qiE "^(feat|feature)(\(.+\))?:"; then
-            bump="minor"; release="true"
-          elif echo "$commits" | grep -qiE "^fix(\(.+\))?:"; then
-            bump="patch"; release="true"
+          elif [ "$kind" != "none" ]; then
+            bump="$kind"; release="true"
           fi
 
           echo "bump=$bump" >> "$GITHUB_OUTPUT"

.github/workflows/validate.yml

@@ -389,6 +389,9 @@ jobs:
       - name: Release gate fails closed (stubbed gh)
         run: python3 tests/test_release_gate.py -v
 
+      - name: Release bump detection (bump-kind.sh)
+        run: python3 tests/test_bump_kind.py -v
+
       - name: Hero-drift tool exit-code tests
         run: |
           pip install numpy==2.2.6 Pillow==11.2.1

tests/test_bump_kind.py

@@ -0,0 +1,57 @@
+"""Tests for .github/scripts/bump-kind.sh (release.yml and pages.yml share it).
+
+Run: python tests/test_bump_kind.py -v (needs bash).
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+import unittest
+from pathlib import Path
+
+SCRIPT = Path(__file__).resolve().parent.parent / ".github" / "scripts" / "bump-kind.sh"
+# Resolve now: on Windows CreateProcess would find System32\bash.exe (WSL) first.
+BASH = shutil.which("bash")
+
+
+def kind(*messages: str) -> str:
+    # git log --format='%B%x00' separates entries with "\n" after each NUL.
+    stdin = "\n".join(m + "\0" for m in messages)
+    # Bytes, not text mode: on Windows text mode rewrites LF as CRLF.
+    out = subprocess.run(
+        [BASH, SCRIPT.as_posix()], input=stdin.encode(), capture_output=True, check=True
+    )
+    return out.stdout.decode().strip()
+
+
+@unittest.skipIf(BASH is None, "bash not available")
+class BumpKind(unittest.TestCase):
+    def test_docs_and_chore_do_not_release(self):
+        self.assertEqual(kind("docs: tidy README\n", "chore: bump version to 1.2.3 [skip ci]\n"), "none")
+
+    def test_fix_is_patch(self):
+        self.assertEqual(kind("fix(snippets): x\n"), "patch")
+
+    def test_feat_is_minor_and_beats_fix(self):
+        self.assertEqual(kind("fix: a\n", "feat(showcase): b\n"), "minor")
+
+    def test_bang_subject_is_major(self):
+        self.assertEqual(kind("feat(api)!: drop 4.5\n"), "major")
+
+    def test_breaking_footer_is_major(self):
+        self.assertEqual(kind("refactor: x\n\nBREAKING CHANGE: removes y\n"), "major")
+
+    def test_breaking_prose_in_subject_is_not_major(self):
+        # Was major: the old grep matched "BREAKING[ -]CHANGE" anywhere, -i.
+        self.assertEqual(kind("docs: explain breaking-change policy\n"), "none")
+        self.assertEqual(kind("fix: note the breaking change in docs\n"), "patch")
+
+    def test_lowercase_footer_is_not_major(self):
+        self.assertEqual(kind("fix: x\n\nbreaking change: no\n"), "patch")
+
+    def test_empty_input_is_none(self):
+        self.assertEqual(kind(), "none")
+
+
+if __name__ == "__main__":
+    unittest.main()