From 1e4e16802536b658e1c8f582be78d96180252333 Mon Sep 17 00:00:00 2001
From: stxkxs <139715017+stxkxs@users.noreply.github.com>
Date: Fri, 7 Aug 2026 23:08:03 -0700
Subject: [PATCH] docs: contributing describes the protection that now exists
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`main` is protected on all sixteen public repos: pull requests required,
force pushes and deletions refused, linear history, and the rules applied
to admins. The single required status check is the merge gate.

CONTRIBUTING already said every CI job is required and none is advisory.
That was the intent and not the state — ten of the sixteen repos had no
branch protection at all, and the discipline was held up by a local git
hook on one machine. The sentence is now true.

Documents the two properties a contributor cannot infer: that the gate
treats a skipped dependency as a failure, because GitHub scores skipped as
passing and a rollup without `always()` reports green precisely when
something broke; and that the gate refuses to pass while any job in its
workflow sits outside its `needs:` list, so adding a job to CI makes it
blocking with no settings edit to remember.
---
 CONTRIBUTING.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9589ccd..5f90eab 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -63,6 +63,22 @@ dependency ≥1 major version back needs an adjacent written reason.
 2. **Get checks green.** Every CI job is required; none is advisory. That
    includes the security scanners — findings fail the build (see
    [SECURITY.md](SECURITY.md)).
+
+   Branch protection enforces this rather than trusting it. `main` is
+   protected on every repo: pull requests are required, force pushes and
+   deletions are refused, history stays linear, and the rules apply to
+   admins too. The single required status check is **`merge gate`** — one
+   job per workflow that depends on all the others and fails unless every
+   one of them succeeded. Repos with a separate security workflow also
+   require `merge gate (security)`.
+
+   The gate treats `skipped` as a failure, which is deliberate: GitHub
+   counts a skipped check as *passing* for branch protection, so a rollup
+   that is skipped when a dependency fails would report green exactly when
+   something broke. It also refuses to pass if any job in its workflow is
+   outside its `needs:` list — so adding a job to CI makes it blocking
+   automatically, with no branch-protection edit and nothing to forget.
+   See [`actions/merge-gate`](actions/merge-gate/README.md).
 3. **Mark ready for review.** Review focuses on correctness, fit with the
    repo's declared architecture, and the production bar (see
    [GOVERNANCE.md](GOVERNANCE.md)).