docs(governed-guard): replace the retired sha pin with the ruled approval-record predicate - #7616
Merged
Conversation
…oval-record predicate The merge-queue leg stopped reading `commit_id` when the maintainer's 2026-09-04 ruling landed; two documents still described the pin, in the worst direction — a seat reads them, believes an approval goes stale on the next push, and re-requests an approval the gate does not want. Both passages now copy the guard header's own sentences (§ "What satisfies the queue leg", and the accepted-cost paragraph) rather than paraphrasing them, so the three places cannot drift apart again. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019RfFHiRCSs3JXLK4cwcfox
github-actions
Bot
added
the
documentation
This was referenced Sep 4, 2026
os-zhuang
approved these changes
Sep 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #7605
Two documents still described the governed-queue guard's sha pin, which PR #7606 retired when it executed the maintainer's 2026-09-04 ruling — quoted verbatim and untranslated, because rewriting a ruling is rewriting the ruling:
Both stale passages failed in the worst direction: a seat reads them, believes an approval goes stale on the next push, and re-requests an approval the gate does not want.
What changed
Both passages now copy the guard's own header sentences rather than paraphrasing them, so the three places cannot drift apart again. The source is
scripts/check-governed-queue-guard.mjsat0d8fd7c:APPROVEDreview by an account inGOVERNED_APPROVERS, on whichever commit it was left; dismissed, superseded, unauthorised and unreadable all still refuse).AGENTS.md(受管面 section). The clause that read 「它要求GOVERNED_APPROVERS(os-zhuang/hotlong)的 APPROVED review 钉在当前 head」 now states the ruled predicate, the refusals that survive, the ruling, and the accepted cost. Passage language and voice unchanged; no other sentence touched.content/docs/guide/ci-cd-pipeline.md(§ Governed Surface Guard). The three consecutive claims went stale together — that the review'scommit_idmust equal the current head sha, that "the sha pin is what makes the approval an approval of something", and that "a push after the approval goes stale and reopens the refusal". Replaced with the header's predicate plus the accepted-cost sentence. The workflow-inventory table row near L43 stated the same pin and is corrected to match.Left alone, deliberately: the section's cost paragraph. It claims only that a diff touching no governed path costs zero GitHub API calls, which is still true — it never stated the governed-PR count that PR #7606 changed. Verified in the source rather than assumed:
runGuardearly-returns withapiCalls: 0when nothing is governed, takes onefetchReviewsper governed pull request, and has no head-read parameter at all (L677: "There is nofetchPullHeadparameter any more"). The guard's own self-test prints the same reading — "the retired head read measured ABSENT at one lookup per governed PR".Why this stays a DRAFT
AGENTS.mdis a governed surface.node scripts/check-governed-queue-guard.mjs --test AGENTS.md content/docs/guide/ci-cd-pipeline.mdanswers GOVERNED, exit 3: one governed path governs the whole pull request. This pull request is parked as a draft for a human merge — not flipped ready, not enqueued, no auto-merge, no reviewer requested from the seat. One pull request for both files because they carry one fact; the guide is not governed but rides with the governed file.Verification (all at
8d78dbd, working tree clean)pnpm lint(whole repo, 47 tasks)0 errors, 2878 warnings— warnings pre-existing, unrelated to this diffpnpm check:control-bytesOK (scanned 6228 tracked text file(s); skipped 85 binary)pnpm check:governed-queue-guardOK ... 132 cases passpnpm check:doc-fencespnpm check:doc-snippets452 of 452 block(s) judged, 0 failed(after building its--build-filterclosure, 34 tasks)pnpm check:doc-typesEvery documented component type is registered.pnpm check:docs-route-closurepnpm check:skills-paths88/89 stated path(s) resolvepnpm check:shell-escape-residueOK (5/5 root(s) resolved ... 0 occurrence(s) outside a fence)node scripts/check-doc-links.mjsLinks are valid across 17 scan roots.node scripts/check-changeset-presence.mjsNo source or published contract of a released package changed in this range, so no changeset is owed.— verdict followed, no changeset addedci-cd-pipeline-doc,check-governed-queue-guard,merge-queue-reporting3 passed (3),69 passed (69)The three pin tests are the suites that read the two edited files, run in addition to the gate families the paths reach.
🤖 Generated with Claude Code
https://claude.ai/code/session_019RfFHiRCSs3JXLK4cwcfox
Generated by Claude Code