chore: version the canonical estate ruleset + apply docs (A-425)

[RobEasthope]

Summary

• Versions the estate's canonical GitHub ruleset as JSON
  (.github/rulesets/trunk.json) so branch-protection is reproducible and
  reviewable, not click-ops only. It folds the two rulesets previously live on this
  repo (Trunk + the redundant org-level Protect main trunk) into one: deletion
  • non_fast_forward + pull_request (squash-only, 0 approvals) +
    required_status_checks pinned to the GitHub Actions integration
    (integration_id: 15368, anti-spoof) requiring GO/NO GO (A-418) and the
    pr-title / Validate PR title is a Conventional Commit context (A-400/405).
• Adds docs/rulesets.md: the per-repo apply process (gh api PUT/POST to
  replace, not add), the prerequisite that the GO/NO GO check must exist first,
  the two pr-title context forms (consumer caller vs this repo's inline dogfood),
  the org-only scope, and decommissioning the redundant org ruleset.

Stores JSON + docs only — no live apply. Applying it (which switches this repo's
required check to GO/NO GO) is a gated admin step for after A-418 merges and the
GO/NO GO check is emitting.

no release (governance/docs only).

Related Issues

• A-425

Test Plan

• jq . .github/rulesets/trunk.json validates (confirmed locally).
• Apply doc reviewed; no live ruleset change made by this PR.
• After A-418 merges, dry-run the apply against this repo's live Trunk ruleset id (18130461) and verify the integration pin + GO/NO GO context.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 34 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 68b5caad-84df-431d-9505-fcf8c3862fd9

📥 Commits

Reviewing files that changed from the base of the PR and between 990abae and 2e8e8a1.

📒 Files selected for processing (2)

• .github/rulesets/trunk.json
• docs/rulesets.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch a-425-define-version-estate-rulesets-in-shared-workflows

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch a-425-define-version-estate-rulesets-in-shared-workflows

---

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

[claude]

Claude finished @RobEasthope's task in 1m 57s —— View job

---

Code Review — PR #17

• Read changed files
• Review .github/rulesets/trunk.json
• Review docs/rulesets.md
• Post findings

---

.github/rulesets/trunk.json

The JSON is structurally correct and well-considered. A few observations:

Anti-spoof pin (integration_id: 15368) — correct. 15368 is the canonical GitHub Actions integration ID; pinning to it on every required_status_checks entry prevents a forged commit-status API call from satisfying the rule. Good.

~DEFAULT_BRANCH condition — correct use of the magic pattern; the ruleset follows main even if it's renamed. The empty exclude: [] is fine (explicit rather than omitted).

strict_required_status_checks_policy: false and required_review_thread_resolution: false — both deliberate and defended in the PR description and prior review. Accepted.

do_not_enforce_on_create: false — the secure default; no concern.

bypass_actors: [] — correctly documented in the doc. GitHub enforces repo-level rulesets with enforcement: active on org admins when no bypass actors are listed. The blockquote in the doc accurately describes this (emergency = toggle to evaluate, not rely on admin override).

required_reviewers: [] — harmless with required_approving_review_count: 0; the empty array is needed to satisfy the schema.

One minor nit on the compact vs. expanded formatting:

// These are inline-compact:
{ "type": "deletion" },
{ "type": "non_fast_forward" },

// These are multi-line objects:
{ "type": "pull_request", "parameters": { ... } }

Purely cosmetic — no functional concern. The compact form for parameter-less rules is idiomatic and readable. Fix this → (optional)

---

docs/rulesets.md

Well-structured, precise, and covers the non-obvious operational details that matter.

Forward references to docs/go-no-go-gate.md (lines 23 and 77) — the file does not exist yet (A-418). The PR description confirms this is intentional (converted from dead links to prose references). Accepted.

--method POST continuation line (line 106–107):

   Or, if the repo has no repo-level ruleset yet, **create** one with `--method
POST repos/<owner>/<repo>/rulesets` instead (same `--input` rule).

Line 107 (POST repos/...) is not indented to the list item's 3-space continuation level. CommonMark's lazy-continuation rule means this renders correctly (the line break inside the code span becomes a space, giving `--method POST repos/...`), and it likely passes markdownlint. But it is visually jarring in the source. Fix this → (optional)

/tmp/trunk-shared-workflows.json path — ephemeral by nature, but these are sequential manual steps in the same shell session (jq writes it, apply reads it immediately). Fine for the use case.

Table alignment (lines 54–57): Nicely formatted; the two-form distinction is clear and prevents the "which context string?" surprise when applying to shared-workflows itself.

Decommission section — correctly scoped to org-level action outside this repo's control, with both a UI and CLI path. Good.

---

Summary

This is a clean, narrowly-scoped PR — JSON + doc, no live apply. The ruleset JSON is correct, the anti-spoof integration pin is in place, and the apply doc covers the non-obvious edge cases well. The two nits above (compact rule formatting, unindented continuation line) are cosmetic and entirely optional to fix. No blocking concerns.

[RobEasthope]

triage-pr — review feedback summary

Acknowledging the issue-level review feedback (no resolvable thread per finding):

Finding	Outcome	Reference
Dead links to go-no-go-gate.md (forward ref to A-418)	Accepted	converted both to prose references to docs/go-no-go-gate.md (A-418), matching how that doc refers back to the ruleset
Apply command ambiguity — swapped file for shared-workflows	Accepted	step 2 now has explicit, separate consumer vs shared-workflows commands
bypass_actors:[] — document emergency access	Accepted	added a No-bypass-actors note: emergency access = toggling the ruleset, not an admin override
strict_required_status_checks_policy:false deliberate?	Out of scope	deliberate — mirrors the live Trunk ruleset; avoids rebase churn for a solo-maintainer estate (squash-merge)
required_review_thread_resolution:false deliberate?	Out of scope	deliberate — meaningless with required_approving_review_count:0; mirrors live Trunk