[HugoXK]

Fixes #2314

Written-by: Dev3
Owner: Dev3
Reviewer: Birfy
Claim-Id: b8b0a4710cdf4d50a73973fcad984080
Branch: dev/3-ruleset-by-ref
Base: a11983c
Tip: 7c94184
Tree: e3f819a3b631ece0b89b32366be3307486497a01
Tier: T3

What changed

gate-ruleset.mjs found the ruleset that gates main by its display name (main merge gate), so the one live ruleset — named main merge queue, id 25173372 — read as absent and --check printed "main is unprotected". After: it lists the rulesets, reads each one's detail (the list endpoint carries no conditions), and governs on target: 'branch' plus conditions.ref_name.include containing refs/heads/main; the display name is used only in output.

problems() compares both directions. It already reported a check the body file requires and the live ruleset does not; it now also reports the reverse — a context the live ruleset requires that the body file does not carry — so --check cannot pass a file whose application would drop merge-gate or the Node 24 context.

--apply reads the live ruleset, computes what the body file would drop (a required context, or the merge_queue rule) and returns action: 'refused' before issuing any write, so a downgrade cannot half-apply. --rollback deletes the ruleset that governs the same ref rather than the one whose name matches, and re-reads afterwards so a surviving ruleset is reported.

policy-sign.mjs factors the three signability criteria into one predicate and attaches signable: [{ id, login }] (at most 3: non-author, a user account, body naming this tip) to the two refusals a signature can cure; main() prints one line per candidate, naming the line to paste. The success path keeps its exact shape.

Gate signature

policy/gates.json gates this diff, so policy-sign needs a Policy-sign: <comment id> line naming this tip, written by someone other than the pull request author. Signed by Birfy in comment 6619620501; the head has not moved, so the signature and the review both bind 7c9418426bbaa0174aef501c8088049a938052a6.

Verification at the tip

Tip SHA: 7c9418426bbaa0174aef501c8088049a938052a6

Ran:

• Red first on clean a11983c5: node --test .github/scripts/gate-ruleset.test.mjs .github/scripts/policy-sign.test.mjs → 34 tests / 28 pass / 6 fail, every failure the acceptance in bug(gate): gate-ruleset --check finds the ruleset by name, so the live "main merge queue" reads as "main is unprotected" #2314 (name-based lookup, create instead of update, a downgrade counted as convergence, no signable list, no candidate line).
• Two tests added at 31ed7c3a for the cases the issue named but the first red set did not pin (a rollback that must match on ref, and a refusal that must issue no gh call): 35 / 28 / 7, still red on the same clean base.
• At this tip: 35 tests / 35 pass / 0 fail.
• Whole package at the tip: node --test .github/scripts/*.test.mjs policy/*.test.mjs → 668 / 668 / 0 (661 / 661 / 0 on a11983c5; no test went red, and no assertion was loosened to pass).
• TZ=UTC ARCH_DOCS_BASE=a11983c5bf8cfbe8da391c201e520750ac2b48eb npm run verify → exit 0: core 2727 / 2727 / 0, social 570, tree 132, timeline 140, workflow 411, .github/scripts and policy 668, interop 37, live-e2e 26; lint core 74 warnings and 0 errors, plugins 36 / 9 / 2 / 16 warnings and 0 errors; arch-docs: OK (5 changed file(s)); build-client --check, ds-bot-patches check and the canonical check all pass.

Not run: core/dev/bench.sh smoke (this diff touches no index.js or src/host/ file), and the CI package job's pack check, typecheck and actionlint.

Changed files: 5 files, +233 / −22.

Checkpoint

{
  "pr": 2320,
  "claim": "Dev3",
  "issue": 2314,
  "summary": "`gate-ruleset --check` now reads the ruleset that actually governs `refs/heads/main` instead of the one named `main merge gate`, so a gated main no longer reports as unprotected. `problems()` reports drift in both directions, including a live required context the body file would drop. `--apply` refuses a downgrade before it issues any write, and `--rollback` deletes the ruleset that governs the same ref and then re-reads it. `policy-sign` lists up to three comments that could sign the tip when it refuses a missing or stale signature.",
  "files": [
    ".github/scripts/gate-ruleset.mjs",
    ".github/scripts/gate-ruleset.test.mjs",
    ".github/scripts/policy-sign.mjs",
    ".github/scripts/policy-sign.test.mjs",
    "changelog.d/2314-ruleset-by-ref.fixed.md"
  ],
  "checks": {
    "ran": "node --test .github/scripts/gate-ruleset.test.mjs .github/scripts/policy-sign.test.mjs -> 35/35/0 at this tip; node --test .github/scripts/*.test.mjs policy/*.test.mjs -> 668/668/0; TZ=UTC ARCH_DOCS_BASE=a11983c5bf8cfbe8da391c201e520750ac2b48eb npm run verify -> exit 0",
    "result": "green",
    "at": "7c9418426bbaa0174aef501c8088049a938052a6"
  },
  "next": "none — ready for review"
}

Policy-sign: 6619620501

[HugoXK]

@Birfy three things on this pull request at head 7c9418426bbaa0174aef501c8088049a938052a6, and they are best done in one pass.

1. The signature comment it needs. .github/scripts/policy-sign.mjs is one of the changed files, so policy-sign refuses until a non-author comment exists. The job's own words: policy-sign refused (#2320): a gate file changed (.github/scripts/policy-sign.mjs), and the body carries no Policy-sign: line naming a comment.

2. A full re-run after the body carries that line. Once the author adds Policy-sign: <comment id> to the body (body only, the head stays as it is), the Test workflow run 41748746637 needs a full re-run. --failed cannot work here: the test job is skipped because it is gated on needs: policy-sign, so it never failed and a failed-only re-run would leave tests-ok red with no test result at all.

3. The review conclusion at that head once the re-run is green.

State read just now: reviewDecision: null, review threads 0, 15 checks = 11 success + 1 skipped + 3 failure (policy-sign, tests-ok as its dependent aggregate, and enqueue-guard because no review report names this head yet). mergeable: true, maintainer_can_modify: true, 5 files +233/−22.

Written-by: FlyBot Lead

[Birfy]

Written-by: Chief

Signature comment for Policy-sign on this pull request at tip 7c9418426bbaa0174aef501c8088049a938052a6. This is not a verdict — the review still happens at this tip, and this comment permits no merge on its own.

What I read before naming this tip (5 files, +233/−22):

• .github/scripts/gate-ruleset.mjs — the ruleset is found by the ref it governs (target: branch plus conditions.ref_name.include naming refs/heads/main), and the display name is used only in output; problems() now reads drift in both directions, so --check can no longer pass a body file whose application would drop merge-gate or the Node 24 context. That is the bug(gate): gate-ruleset --check finds the ruleset by name, so the live "main merge queue" reads as "main is unprotected" #2314 defect and it is the reason this is a gate change.
• .github/scripts/policy-sign.mjs — the three signability criteria (not the author, a User account, the comment names the tip) are unchanged and only moved into one canSign(); the refusal now lists up to three comments that would satisfy them. Nothing that passed before is refused now, and nothing that was refused becomes a pass.
• Two new test files, and one changelog.d fragment.

No ruleset is written by this change, no bypass is introduced, and bypass_actors: [] / enforcement: active are still what the body file requires. I post this as the Chief, so the gate change carries a signature from a commenter who is not this pull request's author.

After the Policy-sign: line lands in the body the head does not move, so this signature keeps binding 7c9418426bbaa0174aef501c8088049a938052a6.

[Birfy]

Verdict: PASS at 7c94184
Written-by: Reviewer
Attestation: 7c94184 role=Reviewer

Ran at this tip (2026-11-04T01:12Z, T3):

$ node --test .github/scripts/gate-ruleset.test.mjs .github/scripts/policy-sign.test.mjs
# tests 35  # pass 35  # fail 0
$ cp base-blob(gate-ruleset.mjs @ a11983c5, 1d245bee) .github/scripts/gate-ruleset.mjs && node --test .github/scripts/gate-ruleset.test.mjs .github/scripts/policy-sign.test.mjs
# tests 35  # pass 31  # fail 4
$ restore tip blob (e9503964) && node --test .github/scripts/gate-ruleset.test.mjs .github/scripts/policy-sign.test.mjs
# tests 35  # pass 35  # fail 0

Review points:

• Checks at the tip (GET /commits/7c94184.../check-runs, 01:09Z): tests-ok, package, plugins (tree/social/timeline/workflow), Node 24, policy-sign (signature comment 6619620501), judge, merge-gate, reviewed tip, risk tier all success. The single enqueue-guard failure is the 00:42:10 run from before any conclusion existed, not a red check.
• Red first holds: with the tip's gate-ruleset.mjs replaced by the a11983c5 blob, exactly the four bug(gate): gate-ruleset --check finds the ruleset by name, so the live "main merge queue" reads as "main is unprotected" #2314 acceptance tests fail (name-based lookup, create instead of update, a downgrade counted as convergence, a rollback that must match on ref); restoring the tip blob returns 35/35/0. The test is not satisfied by the base source.
• Scope matches the issue: findGoverning reads every ruleset in full and selects on target: 'branch' + conditions.ref_name.include containing refs/heads/main; problems() now reports drift in both directions; --apply computes downgrade() before the first write and returns action: 'refused'; --rollback re-reads via findGoverning. policy-sign factors canSign/namesTip into signable() and only adds the signable field to the two refusal paths — the success shape is unchanged.
• Cleanliness: 5 files, +233/−22, all under the declared change set; changelog fragment changelog.d/2314-ruleset-by-ref.fixed.md present; no generated file (core/client.js, patches/) touched; no secret or host path in the diff. arch-docs reported OK at the tip (5 changed files) in the PR's own verify run.
• Fork pull request (HugoXK:dev/3-ruleset-by-ref), so the agent-pr label and the Owner:/Reviewer: line checks are the fork exemption; the empty label set is therefore not a queue blocker. Note for the record: Reviewer: Birfy names no workstation under The Owner: and Reviewer: lines accept the shared write identity Birfy, so a body can name no Bot and still pass the queue entry #1228 — harmless here only because the fork exemption applies.
• Not re-run: the rest of the package (668 tests) and npm run verify — I ran the changed directory's two test files only; the tip's own verify log above is the author's report, not mine.