ci: enforce Conventional Commits with a commitlint gate

.commitlintrc.json

@@ -0,0 +1,8 @@
+{
+  "extends": ["@commitlint/config-conventional"],
+  "defaultIgnores": false,
+  "rules": {
+    "body-max-line-length": [0],
+    "footer-max-line-length": [0]
+  }
+}

.github/workflows/ci.yml

@@ -18,6 +18,33 @@ on:
   workflow_dispatch:
 
 jobs:
+  # Enforce Conventional Commits on PR commits. semantic-release derives the
+  # version bump from these messages, so a non-conventional subject (missing
+  # type, an unknown type, or wrong-case type) yields no bump or the wrong one.
+  # Fast, dependency-light gate via npx so it fails before the expensive
+  # `check` job.
+  commitlint:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Validate PR commit messages (Conventional Commits)
+        run: |
+          npx --yes \
+            -p @commitlint/cli@21 \
+            -p @commitlint/config-conventional@21 \
+            commitlint \
+            --config .commitlintrc.json \
+            --from "${{ github.event.pull_request.base.sha }}" \
+            --to "${{ github.event.pull_request.head.sha }}" \
+            --verbose
+
   # ENFORCE: PRs to main must come from dev branch only
   enforce-main-pr-source:
     if: github.event_name == 'pull_request' && github.base_ref == 'main'

.husky/commit-msg

@@ -0,0 +1 @@
+npx --no -- commitlint --edit "$1"