fix(ci): the ADR gate goes red while auto-merge is armed on a docs/adr/** PR

.github/workflows/adr-merge-approval.yml

@@ -6,10 +6,23 @@ name: ADR Merge Approval
 # A PR whose diff touches docs/adr/** must carry an APPROVED review before it
 # is mergeable. The gate does NOT check WHO approved: any account with review
 # rights on this repo — including an AI seat — satisfies it, which is the
-# accepted cost of the ruling and is stated in full in the two-clause table at
+# accepted cost of the ruling and is stated in full in the guarantee table at
 # the head of scripts/check-adr-merge-approval.mjs. The approval must be
 # current: a later CHANGES_REQUESTED or DISMISSED revokes it.
 #
+# Second clause (#8012): the PR must ALSO not be sitting on an armed
+# auto-merge. Arming is not merging — it is a standing instruction to merge
+# later — so no gate used to fire on it, and an AI seat armed one on a live
+# docs/adr/** PR at 11:15Z on 2026-08-12. The next approving review would have
+# turned this check green and GitHub would have merged the PR unattended, every
+# check reporting success. Armed is now RED whether or not the PR is approved:
+# the approved case is the only one in which the unattended merge actually
+# happens, so a rule that fired only on the unapproved case would change no
+# verdict at all. This is how 「人工合并」 becomes machine-enforced — the gate is
+# green only while the merge still requires a person to press the button.
+# It is not a deadlock: anyone can disable auto-merge, and doing so re-runs
+# this workflow (see the trigger below) and clears the check by itself.
+#
 # This supersedes the account-identity rule this workflow used to describe
 # (#6741 「adr 只能由维护者自己确认,人工合并,ai 不得擅自合并。」, enforced by
 # matching the maintainer's numeric account id). That proxy became
@@ -40,6 +53,21 @@ name: ADR Merge Approval
 on:
  pull_request:
  branches: [main]
+ # `opened`/`synchronize`/`reopened` are GitHub's default set and are
+ # RESTATED here because naming any `types:` replaces that default — dropping
+ # one would mean no check run on that activity, and a required context that
+ # never reports is permanent pending, not a skip (the same failure mode the
+ # `paths:` note below describes).
+ #
+ # The two auto-merge activities are the #8012 addition, and they are what
+ # make the arming clause observable at all:
+ # auto_merge_enabled — arming is otherwise a silent state change that
+ # fires no event this workflow listens to, so the gate would keep
+ # reporting its last green while the PR sat armed.
+ # auto_merge_disabled — the zero-friction exit, and the reason the arming
+ # clause is not a deadlock: disarming re-runs the gate, which then goes
+ # green on its own with no push, no re-review and no admin action.
+ types: [opened, synchronize, reopened, auto_merge_enabled, auto_merge_disabled]
  # An approval does not fire `pull_request`, so without this trigger the
  # failed check would sit red after the approval lands until someone re-ran
  # it by hand. Subscribing to reviews makes the approval itself re-run the
@@ -63,7 +91,13 @@ concurrency:
 
 permissions:
  contents: read
- # The gated path lists the PR's reviews via the REST API.
+ # The gated path lists the PR's reviews and reads the PR itself (for
+ # `auto_merge`) via the REST API. `read` covers both — the #8012 clause needs
+ # no new permission and no new token scope. The PR object is read LIVE rather
+ # than taken from the event payload: `auto_merge` is not documented as a
+ # member of the pull_request object carried by `pull_request_review`, and a
+ # projection that merely lacks the key would read as "not armed". The script
+ # refuses such a payload instead; see its header.
  pull-requests: read
 
 jobs:
@@ -97,8 +131,9 @@ jobs:
  # A checkout, setup-node, and one `node` call over `git diff` — no
  # install, no build. The self-test runs first (repo convention), then
  # the gate. GITHUB_TOKEN is only read on the gated path (a docs/adr/**
- # diff needs the PR's review list); the clean path does zero lookups.
- - name: Require an APPROVED review on docs/adr/** diffs
+ # diff needs the PR's review list and arming state); the clean path does
+ # zero lookups.
+ - name: Require an APPROVED review and no armed auto-merge on docs/adr/** diffs
  env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: node scripts/check-adr-merge-approval.mjs --self-test && node scripts/check-adr-merge-approval.mjs