QoderAI · anchenqlw · Aug 21, 2026 · Aug 21, 2026 · Aug 21, 2026
@@ -45,12 +45,58 @@ Automated checks do not determine factual correctness, public product status, De
 Auto-merge must remain disabled. Only a Maintainer with write access may manually add a pull request to the queue, and green checks alone are never sufficient authorization. Capture the PR's `headRefOid` before reviewing both outputs in full:
 
 ```bash
-TASK_REVIEWED_SHA="$(gh pr view <PR> --repo QoderAI/cloud-agents-cookbook --json headRefOid --jq .headRefOid)"
-gh pr diff <PR> --name-only
-gh pr diff <PR>
-TASK_CURRENT_SHA="$(gh pr view <PR> --repo QoderAI/cloud-agents-cookbook --json headRefOid --jq .headRefOid)"
-test "$TASK_CURRENT_SHA" = "$TASK_REVIEWED_SHA"
-gh pr merge <PR> --repo QoderAI/cloud-agents-cookbook --match-head-commit "$TASK_REVIEWED_SHA" --squash
+(
+  set -euo pipefail
+  TASK_PR_NUMBER=123
+  TASK_PR_NODE_ID="$(gh pr view "$TASK_PR_NUMBER" --repo QoderAI/cloud-agents-cookbook --json id --jq .id)"
+  TASK_REVIEWED_SHA="$(gh pr view "$TASK_PR_NUMBER" --repo QoderAI/cloud-agents-cookbook --json headRefOid --jq .headRefOid)"
+  gh pr diff "$TASK_PR_NUMBER" --repo QoderAI/cloud-agents-cookbook --name-only
+  gh pr diff "$TASK_PR_NUMBER" --repo QoderAI/cloud-agents-cookbook
+  TASK_CURRENT_SHA="$(gh pr view "$TASK_PR_NUMBER" --repo QoderAI/cloud-agents-cookbook --json headRefOid --jq .headRefOid)"
+  test "$TASK_CURRENT_SHA" = "$TASK_REVIEWED_SHA"
+  TASK_PRE_READBACK_JSON="$(gh api graphql \
+    -f query='query($id: ID!) { node(id: $id) { ... on PullRequest { state headRefOid mergeQueueEntry { id position } } } }' \
+    -F id="$TASK_PR_NODE_ID")"
+  printf '%s\n' "$TASK_PRE_READBACK_JSON" | jq -e --arg sha "$TASK_REVIEWED_SHA" \
+    '.data.node.state == "OPEN" and .data.node.headRefOid == $sha and .data.node.mergeQueueEntry == null' >/dev/null
+  TASK_ENQUEUE_UTC="$(node -e 'process.stdout.write(new Date().toISOString())')"
+  set +e
+  TASK_ENQUEUE_JSON="$(gh api graphql \
+    -f query='mutation($pullRequestId: ID!, $expectedHeadOid: GitObjectID!) { enqueuePullRequest(input: {pullRequestId: $pullRequestId, expectedHeadOid: $expectedHeadOid}) { mergeQueueEntry { id position } } }' \
+    -F pullRequestId="$TASK_PR_NODE_ID" \
+    -F expectedHeadOid="$TASK_REVIEWED_SHA")"
+  TASK_MUTATION_STATUS=$?
+  set -e
+  TASK_MUTATION_ENTRY_ID="$(printf '%s\n' "$TASK_ENQUEUE_JSON" | jq -er '.data.enqueuePullRequest.mergeQueueEntry.id | select(type == "string" and length > 0)' 2>/dev/null)" || TASK_MUTATION_ENTRY_ID=""
+  if ! TASK_POST_READBACK_JSON="$(gh api graphql \
+    -f query='query($id: ID!) { node(id: $id) { ... on PullRequest { state headRefOid mergeQueueEntry { id position } } } }' \
+    -F id="$TASK_PR_NODE_ID")"; then
+    printf 'post-readback failed; admission state is indeterminate; do not retry blindly\n' >&2
+    exit 1
+  fi
+  printf '%s\n' "$TASK_POST_READBACK_JSON" | jq -c '.data.node | {state, headRefOid, mergeQueueEntry}'
+  if TASK_QUEUE_ENTRY_ID="$(printf '%s\n' "$TASK_POST_READBACK_JSON" | jq -er --arg sha "$TASK_REVIEWED_SHA" \
+    'select(.data.node.state == "OPEN" and .data.node.headRefOid == $sha) | .data.node.mergeQueueEntry.id | select(type == "string" and length > 0)')"; then
+    if [ "$TASK_MUTATION_STATUS" -eq 0 ]; then
+      test -n "$TASK_MUTATION_ENTRY_ID"
+    fi
+    TASK_EXPECTED_ENTRY_ID="$TASK_QUEUE_ENTRY_ID"
+    if [ -n "$TASK_MUTATION_ENTRY_ID" ]; then
+      TASK_EXPECTED_ENTRY_ID="$TASK_MUTATION_ENTRY_ID"
+    fi
+    printf '%s\n' "$TASK_POST_READBACK_JSON" | jq -e --arg sha "$TASK_REVIEWED_SHA" --arg entry "$TASK_EXPECTED_ENTRY_ID" \
+      '.data.node.state == "OPEN" and .data.node.headRefOid == $sha and .data.node.mergeQueueEntry.id == $entry' >/dev/null
+    test "$TASK_QUEUE_ENTRY_ID" = "$TASK_EXPECTED_ENTRY_ID"
+    printf 'mutation_status=%s\nenqueue_time=%s\nqueue_entry=%s\n' "$TASK_MUTATION_STATUS" "$TASK_ENQUEUE_UTC" "$TASK_QUEUE_ENTRY_ID"
+  elif printf '%s\n' "$TASK_POST_READBACK_JSON" | jq -e --arg sha "$TASK_REVIEWED_SHA" \
+    '.data.node.state == "OPEN" and .data.node.headRefOid == $sha and .data.node.mergeQueueEntry == null' >/dev/null; then
+    printf 'confirmed not queued; stop and review before another admission attempt\n' >&2
+    exit 1
+  else
+    printf 'post-readback is indeterminate or the head changed; stop and dequeue if necessary\n' >&2
+    exit 1
+  fi
+)
 ```
 
-Replace the `TASK_` prefix with a name unique to the operation. Read `headRefOid` again immediately before enqueueing and require strict equality with the reviewed SHA. If the head changes, stop and repeat the complete review; `--match-head-commit` is mandatory. Do not queue an external pull request that touches `.github/**`, `scripts/**`, `tests/**`, root `package*.json`, `config/**`, `schema/**`, `docs/**`, or other Maintainer-owned automation/security infrastructure. Recreate and review that work as a Maintainer-owned infrastructure pull request. The Ruleset keeps zero required approvals only because the repository currently has a single Maintainer; it compensates with an empty bypass list and this explicit manual admission boundary. When a second Maintainer is available, require approval, Code Owner review, and latest-push approval.
+Replace the `TASK_` prefix with a name unique to the operation. Before mutation, readback must prove `state=OPEN`, the reviewed head, and no existing queue entry. A mutation transport failure is indeterminate, so the script always performs post-readback and never retries blindly. The PR is admitted only when post-readback returns the same head and a non-empty entry ID; when the mutation response also contains an ID, both IDs must match. The same head with `mergeQueueEntry=null` confirms no admission and stops the workflow. A head mismatch or any other state is indeterminate: stop and dequeue first if necessary. Never set `jump`. Do not queue an external pull request that touches `.github/**`, `scripts/**`, `tests/**`, root `package*.json`, `config/**`, `schema/**`, `docs/**`, or other Maintainer-owned automation/security infrastructure. Recreate and review that work as a Maintainer-owned infrastructure pull request. The Ruleset keeps zero required approvals only because the repository currently has a single Maintainer; it compensates with an empty bypass list and this explicit manual admission boundary. When a second Maintainer is available, require approval, Code Owner review, and latest-push approval.
@@ -61,7 +61,7 @@ For public content pull requests, the intended validation path checks out truste
 
 Automated checks cover metadata schema, global slug uniqueness, path consistency, taxonomy, article structure, required sections, images, links, Markdown fences, footnotes, Mermaid syntax and safety, unsupported elements, common secret patterns, Demo binding and static safety, configuration references, and deterministic catalog generation. Submitted Demo commands and source are never executed.
 
-Automated checks do not decide factual accuracy, Demo runtime correctness or operational safety, publication value, copyright ownership, customer authorization, or whether a statement describes a public product capability. Maintainers review these areas and Demo source manually. In the current single-Maintainer configuration, Auto-merge is disabled and only a write-access Maintainer may manually queue a change after binding the full file-list and diff review to the PR's immutable `headRefOid`. The head SHA is read again immediately before `gh pr merge --match-head-commit`; any change requires a complete re-review. Green checks are evidence, not queue authorization. After a second Maintainer is available, require approval, Code Owner review, and latest-push approval while retaining the SHA-bound manual infrastructure review.
+Automated checks do not decide factual accuracy, Demo runtime correctness or operational safety, publication value, copyright ownership, customer authorization, or whether a statement describes a public product capability. Maintainers review these areas and Demo source manually. In the current single-Maintainer configuration, Auto-merge is disabled and only a write-access Maintainer may manually queue a change after binding the full file-list and diff review to the PR's immutable `headRefOid`. Pre-readback proves the PR is open and unqueued; GraphQL `enqueuePullRequest` then uses the reviewed SHA as `expectedHeadOid` and never sets `jump`. Post-readback always runs even if mutation transport fails. Success requires the reviewed head and a non-empty readback entry ID, equal to the mutation entry ID when the response supplies one. A same-head null entry confirms no admission; any other result is indeterminate and may require dequeue. Green checks are evidence, not queue authorization. After a second Maintainer is available, require approval, Code Owner review, and latest-push approval while retaining the SHA-bound manual infrastructure review.
 
 ## Preview and publication
 

@@ -31,15 +31,61 @@ The initial CODEOWNER is `@anchenqlw`, but CODEOWNERS is currently routing infor
 Green checks show that the candidate produced the expected contexts; they do not authorize a merge. A pull request can propose changes to the workflows, scripts, and tests that produce those contexts. Every admission review is bound to one immutable pull-request head SHA. Use a task-specific variable name when operating on a real PR:
 
 ```bash
-TASK_REVIEWED_SHA="$(gh pr view <PR> --repo QoderAI/cloud-agents-cookbook --json headRefOid --jq .headRefOid)"
-gh pr diff <PR> --name-only
-gh pr diff <PR>
-TASK_CURRENT_SHA="$(gh pr view <PR> --repo QoderAI/cloud-agents-cookbook --json headRefOid --jq .headRefOid)"
-test "$TASK_CURRENT_SHA" = "$TASK_REVIEWED_SHA"
-gh pr merge <PR> --repo QoderAI/cloud-agents-cookbook --match-head-commit "$TASK_REVIEWED_SHA" --squash
+(
+  set -euo pipefail
+  TASK_PR_NUMBER=123
+  TASK_PR_NODE_ID="$(gh pr view "$TASK_PR_NUMBER" --repo QoderAI/cloud-agents-cookbook --json id --jq .id)"
+  TASK_REVIEWED_SHA="$(gh pr view "$TASK_PR_NUMBER" --repo QoderAI/cloud-agents-cookbook --json headRefOid --jq .headRefOid)"
+  gh pr diff "$TASK_PR_NUMBER" --repo QoderAI/cloud-agents-cookbook --name-only
+  gh pr diff "$TASK_PR_NUMBER" --repo QoderAI/cloud-agents-cookbook
+  TASK_CURRENT_SHA="$(gh pr view "$TASK_PR_NUMBER" --repo QoderAI/cloud-agents-cookbook --json headRefOid --jq .headRefOid)"
+  test "$TASK_CURRENT_SHA" = "$TASK_REVIEWED_SHA"
+  TASK_PRE_READBACK_JSON="$(gh api graphql \
+    -f query='query($id: ID!) { node(id: $id) { ... on PullRequest { state headRefOid mergeQueueEntry { id position } } } }' \
+    -F id="$TASK_PR_NODE_ID")"
+  printf '%s\n' "$TASK_PRE_READBACK_JSON" | jq -e --arg sha "$TASK_REVIEWED_SHA" \
+    '.data.node.state == "OPEN" and .data.node.headRefOid == $sha and .data.node.mergeQueueEntry == null' >/dev/null
+  TASK_ENQUEUE_UTC="$(node -e 'process.stdout.write(new Date().toISOString())')"
+  set +e
+  TASK_ENQUEUE_JSON="$(gh api graphql \
+    -f query='mutation($pullRequestId: ID!, $expectedHeadOid: GitObjectID!) { enqueuePullRequest(input: {pullRequestId: $pullRequestId, expectedHeadOid: $expectedHeadOid}) { mergeQueueEntry { id position } } }' \
+    -F pullRequestId="$TASK_PR_NODE_ID" \
+    -F expectedHeadOid="$TASK_REVIEWED_SHA")"
+  TASK_MUTATION_STATUS=$?
+  set -e
+  TASK_MUTATION_ENTRY_ID="$(printf '%s\n' "$TASK_ENQUEUE_JSON" | jq -er '.data.enqueuePullRequest.mergeQueueEntry.id | select(type == "string" and length > 0)' 2>/dev/null)" || TASK_MUTATION_ENTRY_ID=""
+  if ! TASK_POST_READBACK_JSON="$(gh api graphql \
+    -f query='query($id: ID!) { node(id: $id) { ... on PullRequest { state headRefOid mergeQueueEntry { id position } } } }' \
+    -F id="$TASK_PR_NODE_ID")"; then
+    printf 'post-readback failed; admission state is indeterminate; do not retry blindly\n' >&2
+    exit 1
+  fi
+  printf '%s\n' "$TASK_POST_READBACK_JSON" | jq -c '.data.node | {state, headRefOid, mergeQueueEntry}'
+  if TASK_QUEUE_ENTRY_ID="$(printf '%s\n' "$TASK_POST_READBACK_JSON" | jq -er --arg sha "$TASK_REVIEWED_SHA" \
+    'select(.data.node.state == "OPEN" and .data.node.headRefOid == $sha) | .data.node.mergeQueueEntry.id | select(type == "string" and length > 0)')"; then
+    if [ "$TASK_MUTATION_STATUS" -eq 0 ]; then
+      test -n "$TASK_MUTATION_ENTRY_ID"
+    fi
+    TASK_EXPECTED_ENTRY_ID="$TASK_QUEUE_ENTRY_ID"
+    if [ -n "$TASK_MUTATION_ENTRY_ID" ]; then
+      TASK_EXPECTED_ENTRY_ID="$TASK_MUTATION_ENTRY_ID"
+    fi
+    printf '%s\n' "$TASK_POST_READBACK_JSON" | jq -e --arg sha "$TASK_REVIEWED_SHA" --arg entry "$TASK_EXPECTED_ENTRY_ID" \
+      '.data.node.state == "OPEN" and .data.node.headRefOid == $sha and .data.node.mergeQueueEntry.id == $entry' >/dev/null
+    test "$TASK_QUEUE_ENTRY_ID" = "$TASK_EXPECTED_ENTRY_ID"
+    printf 'mutation_status=%s\nenqueue_time=%s\nqueue_entry=%s\n' "$TASK_MUTATION_STATUS" "$TASK_ENQUEUE_UTC" "$TASK_QUEUE_ENTRY_ID"
+  elif printf '%s\n' "$TASK_POST_READBACK_JSON" | jq -e --arg sha "$TASK_REVIEWED_SHA" \
+    '.data.node.state == "OPEN" and .data.node.headRefOid == $sha and .data.node.mergeQueueEntry == null' >/dev/null; then
+    printf 'confirmed not queued; stop and review before another admission attempt\n' >&2
+    exit 1
+  else
+    printf 'post-readback is indeterminate or the head changed; stop and dequeue if necessary\n' >&2
+    exit 1
+  fi
+)
 ```
 
-Replace the `TASK_` prefix with a name unique to the operation, such as `INFRA_` or `PR11_`. Capture the reviewed SHA before inspecting the complete file list and full diff. Immediately before the queue command, read `headRefOid` again and require strict equality. If it changed for any reason, stop and restart the review against the new SHA. `--match-head-commit` is mandatory and prevents the enqueue operation from racing with a later push.
+Replace the `TASK_` prefix with a name unique to the operation. Before mutation, readback must prove `state=OPEN`, the reviewed head, and no existing queue entry. A mutation transport failure is indeterminate, so the script always performs post-readback and never retries blindly. The PR is admitted only when post-readback returns the same head and a non-empty entry ID; when the mutation response also contains an ID, both IDs must match. The same head with `mergeQueueEntry=null` confirms no admission and stops the workflow. A head mismatch or any other state is indeterminate: stop and dequeue first if necessary. Do not set `jump`.
 
 Do not queue an external pull request that changes `.github/**`, `scripts/**`, `tests/**`, root `package*.json`, `config/**`, `schema/**`, `docs/**`, or other Maintainer-owned repository automation/security infrastructure. Recreate such work on a Maintainer-owned branch and submit it as a separate infrastructure pull request.
 

@@ -28,7 +28,7 @@ Introducing or removing a Demo requires changing its owner article in the same p
 
 Required checks, resolved review conversations, and a successful preview are required before merge. While the repository has only one Maintainer, the Ruleset requires zero approvals, no Code Owner review, and no last-push approval because GitHub does not allow an author to approve their own pull request. Auto-merge is disabled and the bypass list is empty.
 
-Only a Maintainer with write access may manually add a PR to Merge Queue. Before doing so, the Maintainer captures `headRefOid` in a task-specific variable, reviews `gh pr diff <PR> --name-only` and the complete `gh pr diff <PR>`, reads `headRefOid` again and requires exact equality, then uses `gh pr merge <PR> --match-head-commit "$TASK_REVIEWED_SHA" --squash`. Any head change invalidates the review and requires a complete re-review. Green checks alone never authorize queue admission. External infrastructure changes are rebuilt as separate Maintainer-owned pull requests.
+Only a Maintainer with write access may manually add a PR to Merge Queue. Before doing so, the Maintainer captures the PR node ID and `headRefOid` in task-specific variables, reviews `gh pr diff <PR> --name-only` and the complete `gh pr diff <PR>`, then reads `headRefOid` again and requires exact equality. Pre-readback must prove the reviewed PR is open and unqueued. Queue admission uses GraphQL `enqueuePullRequest` with `pullRequestId` and the reviewed SHA as `expectedHeadOid`; it never sets `jump`. Mutation transport failure is indeterminate, so post-readback always runs and the mutation is never retried blindly. Successful admission requires the same head SHA and a non-empty post-readback entry ID; if the mutation response contains an entry ID, it must be the same ID. A same-head null entry confirms no admission, while any other state requires stopping and potentially dequeueing. Green checks alone never authorize queue admission. External infrastructure changes are rebuilt as separate Maintainer-owned pull requests.
 
 When a second Maintainer or Maintainer team has write access, upgrade the Ruleset to require at least one approval, Code Owner review, and approval of the latest push. The SHA-bound infrastructure diff review remains required. A merge to `main` is the publication event; there is no later content-import step.