docs: add the optimal repository settings guide

[hyperpolymath]

Adds docs/REPO-SETTINGS.adoc — how to apply and measure config/settings/repo.json, without restating a single value it already carries.

Why this and not a settings file

The canon already exists and is complete. What was missing is the operational knowledge around it, which until now lived only in session memory: the cases where "not compliant" is the wrong verdict.

The four exclusion rules recorded

1. Forks are excluded entirely — from application and from the compliance denominator. Leaving them in produces a permanent false deficit.

2. Private repos on a Free account are N/A, never disabled — secret_scanning and push protection are unavailable there. Recording them as disabled invents a finding that no PATCH can ever clear, and every subsequent audit re-opens it.

3. security_and_analysis is absent from LIST endpoints — it appears only on the single-repo GET. A census built from GET /orgs/{org}/repos sees the key missing and, if missing is treated as false, reports the whole estate non-compliant. There is no bulk shortcut.

4. secret_scanning must be PATCHed before secret_scanning_push_protection — push protection is a dependent. A single combined PATCH returning HTTP 200 is not evidence both landed; read back before recording compliance.

The document also insists on three result buckets — compliant, remediable, N/A — because collapsing N/A into non-compliant is what produces an audit number that cannot be driven to zero.

Open owner decision carried forward

open_owner_decisions.O8 is restated with the coupling made explicit: flipping allow_merge_commit without adding merge to allowed_merge_methods in rulesets/base.json leaves the ruleset refusing the method the setting now permits, which presents to a contributor as an unexplained blocked merge.

Verification

Docs-only, one added file. The three relative links (../config/settings/repo.json, ../config/rulesets/base.json, ../config/rulesets/gates.json) were checked against the tree. SPDX CC-BY-SA-4.0 on line 1 per the estate docs licence.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QMTyDv9CoJo5PfeNzyp519

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 87cadd23-bb9b-4373-8e1c-9d646357d843

📥 Commits

Reviewing files that changed from the base of the PR and between cd2ab49 and d16438f.

📒 Files selected for processing (1)

• docs/REPO-SETTINGS.adoc

---

📝 Summary

Summary by CodeRabbit

• Documentation
  • Added guidance for applying and measuring repository settings.
  • Documented repository exclusion rules and settings dependencies.
  • Explained compliance measurement using compliant, remediable and not-applicable outcomes.
  • Recorded an open decision regarding merge methods and coordination with repository rules.

Walkthrough

The pull request adds an AsciiDoc document that defines how to apply and measure the repository settings canon, including exclusions, compliance buckets, and the open merge-method decision O8.

Changes

Repository settings documentation

Layer / File(s)	Summary
Settings canon and compliance guidance docs/REPO-SETTINGS.adoc	Documents the settings canon, exclusion rules, per-repository compliance measurement, result buckets, and merge-method decision O8.

Estimated code review effort: 1 (Trivial) | ~2 minutes

---

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

_{A rabbit checks each setting in line
Forks and free accounts get a sign
Compliant or remediable, clear
N/A keeps exclusions near
O8 waits where merge methods align}

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