docs(branching): codify trunk-based Option A workflow

[omerakben]

Codifies the trunk-based Option A branching strategy adopted 2026-05-29, so the docs match the GitHub repo settings now in force.

What changed

• CLAUDE.md — "Working in this repo" rule 2 rewritten from the one-line "main only on tagged releases" into the full trunk-based contract: branch from latest main, feat|fix|refactor|test|docs|chore/ prefixes with issue-scoped slugs, one-branch = one-PR = one-squashed-commit, squash-merge + auto-delete, protected main, releases as tags behind chore/release-* PRs.
• CONTRIBUTING.md — replaced the "Branch naming" subsection with a "Branching and merge workflow" section covering the same contract, and fixed the stale "squash-merge to finalize/<release> branches or rebase to feature branches / main only receives release tags" line (that pattern is retired) to "squash-merge into main; head branch auto-deletes."

Why

On 2026-05-29 the repo settings were changed to match Option A: deleteBranchOnMerge=on, squash-only (merge-commit + rebase-merge disabled), and main branch protection (required bun test checks on both runners, strict/linear history, no force-push or deletion, PR-before-merge, enforce_admins on). The docs still described an older finalize/<release> + tag-only flow that no longer matches reality. This PR is the documentation half of that change.

Docs-only. bun test ./tests is green locally: 3789 pass / 0 fail / 2 skip.

Summary by CodeRabbit

• Documentation
  • Clarified and tightened trunk-based workflow: protected main, short-lived PR branches, required branch-name prefixes and kebab-case slugs, and branch/PR creation rules.
  • Specified mandatory squash-merge into main, disabled merge-commit/rebase merges, and formalized release tagging and release-PR conventions.
  • Updated offline test-suite expectations (pass/skip counts) and PR auto-delete behavior.

[gemini-code-assist]

Code Review

This pull request updates CLAUDE.md and CONTRIBUTING.md to document a transition to a trunk-based branching and merge workflow, detailing rules for branch naming, squash-merging, main branch protection, and releases. The review feedback suggests improving document navigation by converting plain text section references into clickable Markdown links and adjusting terminology to "Conventional Commits format" for consistency.

[gemini-code-assist]

The reference to the branching and merge workflow in CONTRIBUTING.md is plain text. Consider making it a clickable Markdown link to improve readability and navigation:

Full contract: [Branching and merge workflow](CONTRIBUTING.md#branching-and-merge-workflow).

[gemini-code-assist]

Use "Conventional Commits format" instead of "Conventional-Commit form" to be consistent with the "Commit conventions" section heading and standard terminology:

The PR title is the squash commit subject, so it must be in Conventional Commits format.

[gemini-code-assist]

The reference to the "Branching and merge workflow" section can be made into a clickable relative link to improve document navigation:

(see [Branching and merge workflow](#branching-and-merge-workflow))

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: af87ca92-de9f-4e6f-a934-6bcab4ddd141

📥 Commits

Reviewing files that changed from the base of the PR and between 0cb208d and 8e38610.

📒 Files selected for processing (1)

• CONTRIBUTING.md

---

📝 Walkthrough

Walkthrough

This PR updates project documentation: adjusts the offline test-suite pass/skip expectation and replaces previous branching guidance with a trunk-based workflow (protected main, short-lived 1:1 PR branches, branch-name prefixes and kebab-case slugs, squash-merge into main, and release tags via chore/release-* PRs).

Changes

Trunk-based branching workflow

Layer / File(s)	Summary
Offline test-suite expectation CONTRIBUTING.md	Adjusted documented expected pass/skip counts for the full offline test suite on main.
Branching and merge workflow documentation CLAUDE.md, CONTRIBUTING.md	Replaced previous branch guidance with trunk-based rules: protected main, short-lived branches mapped 1:1 to PRs, required branch-name prefixes (feat/, fix/, refactor/, test/, docs/, chore/) and kebab-case slugs, squash-merge into main only (no merge-commit/rebase-merge), auto-delete head branches, and release tagging via chore/release-* PRs on green main.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

I nibble at the README’s seam,
Trim commits to keep main a dream,
Short-lived branches, tidy and neat,
Squash them down — a polished feat.
🐇✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main change: codifying a trunk-based branching workflow (Option A) in documentation.
Description check	✅ Passed	The description covers all critical sections: Summary, Files changed, Why, and test confirmation (3789 pass / 0 fail / 2 skip). The required testing checkbox is implicitly confirmed with results.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/branching-strategy-option-a

---

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.}

[Copilot]

Pull request overview

Updates repository documentation to reflect the trunk-based “Option A” workflow now enforced by GitHub settings (protected main, squash-only merges, short-lived topic branches, and tag-based releases).

Changes:

• Replaces the old “main is tag-only / finalize/*” branching narrative with a trunk-based, short-lived branch + PR + squash-merge contract.
• Documents branch naming/prefix rules (including chore/) and the “one branch = one PR = one concern” convention.
• Clarifies release mechanics as tags cut on green main behind a chore/release-* PR.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
CONTRIBUTING.md	Rewrites the branching section to describe the trunk-based PR + squash-merge workflow and updates the PR expectations section accordingly.
CLAUDE.md	Updates “Working in this repo” rule 2 to reflect the same trunk-based workflow and points readers to CONTRIBUTING for the full contract.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.