docs(docs): document release-please merge-subject trap (#102)

[w7-mgfcode]

Summary

Closes #102. Adds a new "Common Incidents" entry to docs/_base/RUNBOOKS.md plus a warning callout under "Cut a release", covering the merge-subject trap that caused release-please to skip the v0.2.8 bump (see #98 recovery story).

Background

gh pr merge --merge uses the PR title as the merge-commit subject. If the PR title is a non-bumping conventional commit (chore(...), docs(...), refactor(...), test(...), ci(...)), release-please will read it at face value and skip — even when the merge contains many underlying feat: / fix: commits.

Prior dev → main releases were merged via the GitHub web UI, which uses the default Merge pull request #N from <branch> subject. Non-conventional → release-please traverses the underlying commits → bump fires.

What's documented

• Symptoms — CD Release workflow ends in ~10s, no Release PR, log says "No user facing commits found".
• Diagnosis — git log origin/main -1 --format='%s' test for the trap.
• Prevention — three equivalent fixes (web UI / --subject / non-chore PR title).
• Recovery — empty feat(release): trigger commit pattern, with PRs feat(release): trigger v0.2.8 release for seeder phases 1+2 (#98) #99 → chore(main): release 0.2.8 #100 → chore(repo): sync dev with main after v0.2.8 release (#98) #101 as reference.

Note on .claude/rules/versioning.md

The issue's acceptance criteria suggested cross-linking from .claude/rules/versioning.md. The entire .claude/ directory is .gitignored (only root CLAUDE.md is tracked), so cross-link in that file can't be shipped via PR. Worth filing a separate issue to consider un-ignoring .claude/rules/ if those policy files are meant to be shared across contributors (the docs say they are).

Test plan

• ruff not relevant (markdown only)
• No code change
• CI green
• Merge to dev

[sourcery-ai]

Sorry @w7-mgfcode, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f6f0b668-a37a-4f65-8558-c9d9f987599b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/runbook-release-please-merge-trap

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}