docs(contributing): document PR title format to prevent silent CHANGELOG drops

[bokelley]

Closes #578

release-please silently drops conventional commits from the CHANGELOG when their subjects contain (, ), or " in the description portion (verified in run 25326163877: three commits missing from v4.4.0). Since this repo uses squash merges, the PR title becomes the commit subject — keeping the title free of those characters is the primary fix. This PR documents that convention in CONTRIBUTING.md with before/after examples from the three affected commits, and adds scripts/check-commit-msg.sh as a commit-msg pre-commit hook to catch violations on direct commits.

What changed

• CONTRIBUTING.md — new "PR Title Format" subsection under Pull Request Process: causal chain (squash-merge → commit subject → release-please parser), bolded constraint, before/after examples, note on where to put moved details. Dev Setup step 2 now includes pre-commit install --hook-type commit-msg so new contributors get the hook without having to find the section.
• scripts/check-commit-msg.sh — executable bash script; validates that conventional-commit descriptions contain no (, ), or ". Prints an actionable error with the offending subject and a corrected example. No-ops on non-conventional-commit messages.
• .pre-commit-config.yaml — adds check-commit-msg as a commit-msg-stage local hook. Squash-merge subjects (set by GitHub on merge) bypass it, so the doc convention is the primary safeguard.

What tested

• bash -n scripts/check-commit-msg.sh — shell syntax clean
• Manual script test against all three real failing commit subjects from release-please: commit-message subjects with parens or quotes silently dropped from CHANGELOG #578: correctly rejected
• Clean commit subjects: correctly allowed
• python -c "import yaml; yaml.safe_load(...)" on updated .pre-commit-config.yaml: valid YAML

Pre-PR review:

• code-reviewer: approved — no blockers; removed always_run: true (redundant on commit-msg hooks) and added Dev Setup hook install steps per reviewer notes
• docs-expert: approved after fix — prose ambiguity in constraint sentence resolved (clarified "description portion only, not type(scope) prefix")

Known limitation (nit, not fixed): The description extraction in check-commit-msg.sh uses ${subject#*: } which could false-positive on a scope containing colon-space (e.g., fix(api: v2): add foo). Standard scope names don't contain spaces, so this is a low-risk edge case. A follow-up can tighten the extraction with sed -E if it triggers in practice.

Triage-managed PR. This bot does not currently iterate on
review comments or PR conversation threads (only on the source
issue). To unblock:

• Push fixup commits directly: gh pr checkout <num> →
  fix → push.
• Or re-trigger: comment /triage execute on the source
  issue.

See adcp#3121
for context.

Session: https://claude.ai/code/session_01RZJ2jX6omDh5V9ua1UKkzy

---

Generated by Claude Code