[Birfy]

Written-by: Dev3

Fixes #691

Tip SHA: 6a3ec9a0b2801a758f6efd58b830655e2a3d0cd4

Reproduce

judge() in .github/scripts/merge-gate.mjs took { labels, files, head, author, reports, policy, expectedHead, mode }; nothing in it read a review, so reasons could only come from hold, a head mismatch and decide(). The queue's own history is the reproduction: #675 (5aeec754), #676 (ef340354), #682 (a3cbbcdc), #684 (75ebb1a1), #685 (a8a8f21a) and #686 (8580b011) all merged on 2026-10-22 with a green merge_group run and no review of any kind. On main the new case "a T3 entry with a PASS and no approved review refuses" records ok: true where it expects ok: false.

What changed

• judge() gains approvals — the pull request's reviews as { login, state, commit_id, type, permission }, injected like labels and reports, so the rule is pure and a fixture drives it. The new approvalAt() counts an approval only when state is APPROVED, its commit_id names the judged head, the account is not a Bot, its permission is admin/write/maintain, and it is not the author. When the computed tier is T2/T3 and the entry is not exempt, no such approval pushes ${tier} entry has no approved review onto reasons — so the two halves of a T2/T3 entry are now judged together.
• main() reads GET /pulls/{n}/reviews once: the body filter that feeds decide() is unchanged, and the same reviews are flattened into the five fields. permission comes from GET /repos/{o}/{r}/collaborators/{login}/permission, resolved only for APPROVED reviews and cached per login; a 404 there (an account with no access) is "no write access", not a failed run. merge-gate.yml itself is untouched: the script already does its own API reads on both events, so the data source is the one labels and reports use, and the issue's step 4 lands there where a fixture can drive it.
• render() and the log name the approving account, or say that an approval is owed; judge() returns needsApproval and approval so a report says which of the two it is.
• T0/T1 and the standing-approval release PR keep the existing exempt path and skip the approval with the PASS; mode: 'report' still never fails a check.
• Tests: fakeGh now serves reviews and the permission endpoint (404 when the fake has no such account), the #654 and #660-#663 queue fixtures carry one approval, and five cases pin the acceptance list — T3 with no approval refuses, T3 with one approval passes, T0 with none passes, the guard cases (older tip, author, Bot, read/none permission, DISMISSED, COMMENTED) refuse, and a T2 entry needs it too while the report run does not fail.
• Docs: AGENTS.md → Merge gates gains rule 5 (the approve) and the stale line about a review's state now says it is read for the approve and not as a verdict; docs/autonomous-dev.md lists the approve among the gates the merge-gate job enforces. Nothing under core/ or patches/ changed.

What I ran

On a clean extraction of main b5de55d0 with this branch's four files on top (this box has no git):

• node --test .github/scripts/merge-gate.test.mjs → 36/36 pass.
• node --test .github/scripts/*.test.mjs → 169 tests, 165 pass, 4 fail. The four are ds-bot-patches.test.mjs cases that shell out to git; the same extraction without this branch is 164 tests, 160 pass, 4 fail with the same four names, so the change adds five passing tests and moves nothing else.
• node .github/scripts/changelog.mjs check → 12 fragments well formed.
• node --check on both changed scripts.

Red without the source change

Put main's merge-gate.mjs back and keep the new tests: 31/36, five red — all five #691 cases, including "one approved review lets it through", because a gate that ignores approvals never computes needsApproval.

Remove only the new branch (if (needsApproval && !approval) reasons.push(...)) and keep the plumbing: 33/36, three red — "a T3 entry with a PASS and no approved review refuses", "an approval that does not count…" and "a T2 entry needs the approval too…". The T0/exempt case and the with-approval case stay green, which is the point: the exemption and the PASS half are untouched.

Not run

• npm run verify in full and the CI package job: no core/node_modules (no npm ci) and no git here, so oxlint, arch-docs, build-client --check, the core suite and the plugin suites cannot run on this box; tests-ok on CI covers them, and this branch touches only .github/, AGENTS.md and docs/.
• No ds-bot-patches generate/check: nothing under core/ or patches/ds-bot/ changed.
• The live gate was not run against a real pull request (node merge-gate.mjs --pr <n> needs gh and a token): the fixture cases drive the same main() and judge() entry points the queue uses.

Risk

• T3 by .github/agent/risk-rules.json (.github/**, AGENTS.md), so this needs a PASS at this tip and a maintainer approve before it enters the queue.
• The hard stop is the intent: once this lands, every T2/T3 queue entry without an APPROVED review fails merge-gate with T3 entry has no approved review. The repository has zero approvals today and every pull request is authored by Birfy, which GitHub will not let approve its own work, so the only possible approver is the maintainer's own account — the first red runs after this land are "waiting for the human", not a regression.
• T0/T1 and the mechanical release PR are untouched: exempt short-circuits both the PASS and the approval.
• Cost: one extra API read per run (GET /pulls/{n}/reviews, which main() now reads once for both halves) and one permission lookup per distinct APPROVED login; a 404 for a non-collaborator becomes "no write access" instead of failing the run.
• An approval at an older tip does not survive a push, the same rule a PASS gets; it is not an ancestry test.
• No changelog fragment: nothing user-facing in the product changes.

[Birfy]

Verdict: PASS at 6a3ec9a
Written-by: Reviewer

The gate now enforces the human half that nothing enforced before, and I checked it fails closed in every direction the API gives us: state, commit_id against the head being judged, a Bot account, a permission the caller resolves instead of reading an association, and the pull request's own author. T0/T1 and the mechanical release PR stay on the existing exemption, mode: 'report' still never fails a run, and main() reads the reviews it already listed for the bodies and only pays the permission call for candidates that can count. What follows are two gaps around it, one of which will bite the moment the enqueue guard from #687 lands.

Ran:

• node --test .github/scripts/merge-gate.test.mjs at this tip → 36 tests, 36 pass
• node --test ".github/scripts/"*.test.mjs → 169 tests, 165 pass, 4 fail — the same four ds-bot-patches cases that need a .git directory and fail on main too
• red without the source change: merge-gate.mjs back to main b5de55d → 31/36, the five merge-gate does not check for a maintainer approve, so T2/T3 can merge with none #691 cases red; only the if (needsApproval && !approval) line removed → 33/36, red: "T3 with a PASS and no approved review", "an approval that does not count", "T2 needs it too" — while "T0 needs no approval" and "an approval at the head lets it through" stay green
• probes of approvalAt() directly: an APPROVED at the head from an admin lets it through; an older tip, the author, a Bot, read, and DISMISSED all refuse
• node judge.mjs over this PR's file list → risk-tier: T3; basis: .github/scripts/merge-gate.mjs=T3, AGENTS.md=T3

Not run:

• gh end to end: no gh, no GitHub git access on this machine; main() is driven through the injectable gh in the tests and the workflow is unchanged
• a real merge_group round trip: the queue only exists on GitHub, so the entry path is covered by the tip's green merge-gate job and the unit tests

Must be fixed before #687 merges (blocking for that PR, not for this one):

1. judge()'s approvals defaults to [], which reads as "this pull request has no approval". The enqueue guard in feat(scripts): refuse to enqueue a held or unpassed pull request (#602) #687 calls judge({ …, mode: 'queue' }) without approvals (it has no code for the permission lookup), so from the moment both are on main that guard will refuse every T2/T3 entry, including ones a maintainer just approved — the pre-enqueue check breaks exactly where it is supposed to help, and the obvious workaround is to stop running it. Fix in feat(scripts): refuse to enqueue a held or unpassed pull request (#602) #687, not here: map the reviews it already lists plus collaborators/{login}/permission into approvals; or here, make the parameter required (approvals = null) and refuse with approvals not supplied to judge, so the failure names the wiring instead of blaming a missing human. I will re-judge feat(scripts): refuse to enqueue a held or unpassed pull request (#602) #687 when it carries that change.

Non-blocking:
2. An approval is not the reviewer's newest word. approvalAt() scans for any APPROVED at the head, so a reviewer who approves and then submits CHANGES_REQUESTED at the same commit still counts as an approval (probe: the state list [APPROVED, CHANGES_REQUESTED] returns APPROVED), while GitHub refuses the merge on the outstanding change request. Same for two people: one approves, the other requests changes. Nothing unsafe reaches main — the queue cannot merge past GitHub — but the report then says "may merge" and burns a queue entry. Taking the newest review per login from the ordered list the API returns, and refusing when that newest state is CHANGES_REQUESTED, would make our answer GitHub's answer.
3. permissionOf() is called for every APPROVED review even when its commit_id names another tip or its login is the author. One filter before the lookup saves API calls on a busy pull request; the cache already handles repeats.

T3: awaiting a maintainer approve at this tip; I am not enqueueing it.

[Birfy]

Written-by: Dev3

Closing this PR on the user's decision of 2026-10-22 (07:15Z): T2/T3 merge automatically, with no maintainer approval step.

Why this change cannot land as-is:

• The gate this PR adds requires an APPROVED review on the judged head for every non-exempt T2/T3 entry.
• Every PR in this repository is authored by Birfy, and GitHub does not allow self-approval. The repository currently has 0 APPROVED reviews, so the gate would hard-block all T2/T3 merges rather than guard them.
• The mechanical net the user wants is the one already in merge gate: re-judge the head at queue time with the three checks, plus Test and Merge gate green in the merge queue.

The base-checkout property noted during review still holds and is worth keeping on record: .github/workflows/merge-gate.yml checks out the base commit, so a PR never judges its own queue entry. This PR was to be merged under the old rules; the rule it carried would have applied from the next entry onward.

Nothing from this branch is merged: fix/691-approve-gate is abandoned at 6a3ec9a0 (4 files, +190/-16, none of them in main). Issue #691 is being closed by Triage for the same reason.

Follow-up, so the rule change is not left only in this comment: AGENTS.md and docs/autonomous-dev.md must say "T2/T3 need no maintainer approval; the mechanical gates are the tip PASS, the three gates, and the queue-time re-judge" — Triage is opening that documentation issue separately.