📝 docs: document the main branch protection and the PR-only path to main

[kbrdn1]

Description

main is now protected: pull requests required, seven status checks required, enforce_admins on. The release process documented in CONTRIBUTING.md was written around a local dev → main merge (step 4), which is exactly the push that is now rejected, so the doc had to move with the setting.

Closes #397

Type of change

• 📝 Docs

Changes

• CONTRIBUTING.md: new ## Branch protection section, placed between Merge strategy and Releases because it constrains both. Lists the active rules and records why three of them look wrong at a glance.
• CONTRIBUTING.md: stable release step 4 now goes through a dev → main PR; step 5 tags the merge commit and notes that tags are not covered by the protection.
• CONTRIBUTING.md: table of contents entry.
• CLAUDE.md: house rule, placed first in the list since it gates every release, naming the two cuts (v1.0.2, v1.1.1) done the way that no longer works.

Tests

• cargo test passes locally: 1972 passed, 0 failed
• cargo fmt --check passes: exit 0
• cargo clippy --all-targets -- -D warnings passes: exit 0
• New tests added under tests/

No test, and this is the argued exception. The protection lives in GitHub server state, not in this repo, so there is no public surface to assert against. This is the comments/docs exception in CLAUDE.md. Codifying the protection as a committed ruleset JSON just to have something to test would be over-engineering for a single branch, and the JSON could drift from the real setting anyway, which is the exact failure this PR is cleaning up after (a comment asserting an invariant nothing enforces, same shape as #393). The suite was run anyway and is green.

Checklist

• Branch follows <type>/#<issue>-<description>
• Commits follow Gitmoji + Conventional Commits
• Commits are Verified
• CHANGELOG.md updated under ## [Unreleased]
• README updated if CLI surface changed
• examples/gwm.toml.example updated if config schema changed

No CHANGELOG entry on purpose: contributor-facing docs, nothing a gwm user consumes. Same call as #395 (the signed-commits doc), which shipped without one.

Notes for reviewers

The applied configuration, for the record:

required_status_checks:
  strict:   false
  contexts: rustfmt, clippy, test (ubuntu-latest), test (macos-latest),
            test (windows-latest), pre-commit hook smoke, cargo audit
required_pull_request_reviews:
  required_approving_review_count: 0
enforce_admins:           true
required_linear_history:  false
allow_force_pushes:       false
allow_deletions:          false

What was checked before applying it, since a wrong setting here is the kind that only surfaces when you cannot ship:

• ci.yml runs on pull_request: branches: [main, dev], so the seven required checks do report on a dev → main PR. Requiring a check that never reports would block the branch permanently.
• The two git push sites in release.yml target the Homebrew tap and the Scoop bucket, not main, so no release automation breaks.
• Tag-triggered releases are unaffected: protection guards branch refs, not tags.
• required_signatures is left off, per the decision recorded in [Task]: document the signed-commits preference in CONTRIBUTING #394: it has real consequences for drive-by contributors and deserves its own call. The ### Signing (preferred) line saying nothing in CI or branch protection enforces signing therefore stays accurate.

The three rules worth arguing about are covered in the new section, but in short: 0 approvals because a solo repo cannot self-approve and 1 would be a permanent lockout; linear history off so merge commits stay legal; advisory and third-party checks excluded so they cannot wedge the branch.

This PR is itself the first thing to go through the new rail, though against dev, which is unprotected.

Linked issues / docs

• Issue: [Task]: Document the main branch protection and adapt the release process #397
• Related: [Task]: document the signed-commits preference in CONTRIBUTING #394 / 📝 docs: document the signed-commits preference (#394) #395 (signing preference, and the required_signatures decision left open)

[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: 826543bd-9e7e-46d6-9e83-3bab990765df

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/#397-main-branch-protection

---

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