docs(security): record the case-sensitive ruleset patterns and the case-variant guard

[modelmirror-agent]

What changed and why

This records the repository's ruleset settings as they now stand. The maintainer applied the settings today; this PR changes the docs only.

• promote: restrict creation and promote: freeze now include refs/heads/[Pp][Rr][Oo][Mm][Oo][Tt][Ee]/** alongside refs/heads/promote/**. Ruleset patterns match case-sensitively: before the bracket include, a non-admin push of Promote/x succeeded even though promote/x was refused.
• New ruleset, case variants: restrict creation. It refuses creation of every other casing of main and staging, and only the repository admin role can bypass it. Every environment that admits those names by branch policy is therefore safe whether or not policy matching ignores case. That question is undocumented and untested.
• Setup trap. The ruleset form adds refs/heads/ to whatever you type. Typing the full ref stored refs/heads/refs/heads/promote/**, which covered no branch. The contexts stage caught it.
• The "confirm case on first setup and record the result here" open question becomes a standing non-admin push check.
• The note now says that contexts reads only the promote/** include. The bracket include and the case-variants ruleset are confirmed by the push checks, not by the gate.
• docs/pipeline.md's one-time setup step now lists both protections.

Artifact served: none directly. This covers the integrity of the promote/* candidates and of the environment branch policies they rest on.

Evidence (observed 2026-10-18)

All pushes below were made from the non-admin agent account.

• Before the bracket include:
  • promote/ruleset-probe was refused ("push declined due to repository rule violations").
  • Promote/ruleset-probe was created. The maintainer deleted it; it started no workflow runs.
• After the bracket include:
  • Promote/ruleset-probe was refused.
  • The rulesets API shows both includes, with no excludes.
• After the case-variants ruleset: Staging was refused. Main was not pushed; the pattern is the same single rule.
• Bypass list of the case-variants ruleset: admin role only. This rests on the maintainer's confirmation, because a non-admin can't read bypass lists and contexts does not check this ruleset.
• scripts/promotion-gate.sh contexts, run by the maintainer with an admin token:
  • With the doubled-prefix pattern: four rulesets: errors, exit 1.
  • After the fix: promotion gate: contexts clean, exit 0.

Review

• docs-reviewer. It raised one blocker: the claim that staging is kept from deletion was undocumented. It is true: the staging: protect history ruleset (id 19778491, rules deletion,non_fast_forward) is active, as the API shows. The text now names that ruleset. Its recommended changes are applied:

  • the gate's scope is stated;
  • the full list of environments is given (checked against the deployment-branch paragraph and the website section);
  • the setup step in pipeline.md is updated.

  Its nits are applied: the rulesets summary line and the error-message hint.

• No reviewer subagent ran for security. The change only records settings that are already applied and widens no access. I self-reviewed it against the security checklist.

Left for the maintainer. docs/security.md is a CODEOWNERS path that describes the security posture, so it waits for your review. I have not merged it.

---

Generated by Claude Code