From eda99cc684eb648e744f8587ee5a75994ff7477a Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Fri, 23 Oct 2026 00:24:49 -0400
Subject: [PATCH 1/2] feat(pr-pipeline): fail ci-status while a pull request
 carries needs-human

ci-status now fails on a pull_request event, contract-only runs
included, while the pull request carries the human-gated label, and the
merge_group hold step fails on that label as well as do-not-merge. The
label is the base commit's .work-item-tracker.json
role_labels.human-gated (default needs-human), read through the contents
API at the base SHA; labels are read live with three tries and an
unreadable tracker config or label list fails closed. The PR-event error
names the reason from the newest review-lane hold comment (claude[bot],
or github-actions[bot] ending in a claude-lane footer) and says that
removing the label approves.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/pr-require-checks.yml | 124 +++++++++++++++--
 scripts/ci-hold-human-gated.test.sh     | 176 ++++++++++++++++++++++++
 scripts/ci-hold-merge-group.test.sh     |  69 ++++++++--
 3 files changed, 340 insertions(+), 29 deletions(-)
 create mode 100755 scripts/ci-hold-human-gated.test.sh

diff --git a/.github/workflows/pr-require-checks.yml b/.github/workflows/pr-require-checks.yml
index eed29e5784..b595fb1b45 100644
--- a/.github/workflows/pr-require-checks.yml
+++ b/.github/workflows/pr-require-checks.yml
@@ -3049,9 +3049,9 @@ jobs:
     runs-on: ubuntu-24.04
     # 9 s p95 and 42 s max in full mode, about 10 s contract-only. The cap is
     # the worst case of the pinned composites' waits: two 60 s rate-limit waits
-    # (`rate-limit-wait-seconds` on check-contract and aggregate-results), 15 s
+    # (`rate-limit-wait-seconds` on check-contract and aggregate-results), 45 s
     # of own-gate retries, 7 s of status-write retries and the 90 s
-    # `rerun-wait-seconds` wait, about four minutes.
+    # `rerun-wait-seconds` wait, about four and a half minutes.
     timeout-minutes: 5
     permissions:
       # `yield-to-full-run` lists this workflow's runs on the head SHA, and
@@ -3190,31 +3190,121 @@ jobs:
           msg="draft: lanes not run; the ready_for_review run lints and tests this SHA"
           echo "::notice::$msg"
           echo "$msg" >>"$GITHUB_STEP_SUMMARY"
-      # A QUEUED PULL REQUEST IS HELD BY ITS LABEL TOO. A merge-group payload
+      # A PULL REQUEST CARRYING THE HUMAN-GATED LABEL IS HELD. A review lane or
+      # an escalation puts the label on so a person decides; removing it is the
+      # approval, and the `unlabeled` event re-runs this job. The label's name
+      # is the base commit's .work-item-tracker.json role_labels.human-gated
+      # (default `needs-human`), resolved as pr-merge.yml resolves it, and read
+      # at the base so the pull request cannot rename its own hold. Labels are
+      # read live, not from the event payload, which a later label event
+      # outdates. The reason is the newest review-lane hold comment's text: a
+      # `<!-- claude-lane-hold lane=` comment by claude[bot], or by
+      # github-actions[bot] when its last non-blank line is the lane's
+      # `claude-lane: <lane>` footer. Without one the error names none. An unreadable tracker config or label list fails closed. Pinned
+      # by scripts/ci-hold-human-gated.test.sh, which runs this body.
+      - name: Fail a pull request carrying the human-gated label
+        if: ${{ !cancelled() && github.event_name == 'pull_request' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          if [[ ! $BASE_SHA =~ ^[0-9a-f]{40}$ ]]; then
+            echo "::error::the base commit '$BASE_SHA' is not a commit SHA."
+            exit 1
+          fi
+          for attempt in 1 2 3; do
+            if tracker=$(gh api -H 'Accept: application/vnd.github.raw+json' "repos/$GITHUB_REPOSITORY/contents/.work-item-tracker.json?ref=$BASE_SHA" 2>"$RUNNER_TEMP/tracker.err"); then
+              break
+            elif grep -q 'HTTP 404' "$RUNNER_TEMP/tracker.err"; then
+              tracker=
+              break
+            fi
+            [ "$attempt" -lt 3 ] || { echo "::error::could not read .work-item-tracker.json at $BASE_SHA; re-run this run."; exit 1; }
+            sleep $((attempt * 5))
+          done
+          human_gated=needs-human
+          if [ -n "$tracker" ]; then
+            human_gated=$(jq -er '[objects | .config | objects | .role_labels | objects
+              | .["human-gated"] | strings | gsub("^\\s+|\\s+$"; "")][0] // ""
+              | if . == "" then "needs-human" else . end' <<<"$tracker") || {
+              echo "::error::cannot read the human-gated role label from .work-item-tracker.json at $BASE_SHA"
+              exit 1
+            }
+          fi
+          for attempt in 1 2 3; do
+            if labels=$(gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/labels?per_page=100" --paginate --jq '.[].name'); then
+              break
+            fi
+            [ "$attempt" -lt 3 ] || { echo "::error::could not read the labels of #$PR_NUMBER; re-run this run."; exit 1; }
+            sleep $((attempt * 5))
+          done
+          if ! grep -qxF -- "$human_gated" <<<"$labels"; then
+            echo "#$PR_NUMBER carries no '$human_gated' label."
+            exit 0
+          fi
+          reason=$(gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments?per_page=100" --paginate \
+            --jq '.[] | select(.user.type == "Bot" and (.body | test("(^|\n)<!-- claude-lane-hold lane="))
+              and (.user.login == "claude[bot]" or (.user.login == "github-actions[bot]"
+                and ([.body | splits("\r?\n") | gsub("^\\s+|\\s+$"; "") | select(. != "")] | last // ""
+                  | test("^`?claude-lane: (claude-review|claude-security-review)`?$")))))
+              | .body | @json' | tail -n 1 |
+            jq -r '[splits("[\r\n]+") | gsub("^\\s+|\\s+$"; "")
+              | select(. != "" and (test("^<!--|^`?claude-lane: ") | not))] | join(" ") | .[0:300]') || reason=
+          why=
+          [ -z "$reason" ] || why=" (${reason//%/%25})"
+          echo "::error::#$PR_NUMBER carries '$human_gated'$why. Removing the label approves this pull request; ci-status re-runs on the unlabel."
+          exit 1
+      # A QUEUED PULL REQUEST IS HELD BY ITS LABELS TOO. A merge-group payload
       # carries no pull request, so `check-contract` above reports `skipped`,
-      # and a `do-not-merge` label applied after enqueue would merge (#5952).
-      # This step reads the live labels of the pull request the group was built
-      # for, named in the merge-group ref (`gh-readonly-queue/<base>/pr-<N>-<sha>`),
-      # and fails if it carries the label; the queue then removes that pull
-      # request. It reads only that one: under the ruleset's ALLGREEN grouping a
+      # and a `do-not-merge` or human-gated label applied after enqueue would
+      # merge. This step reads the live labels of the pull request the group was
+      # built for, named in the merge-group ref (`gh-readonly-queue/<base>/pr-<N>-<sha>`),
+      # and fails if it carries either; the queue then removes that pull
+      # request. The human-gated label is resolved at the group's base commit,
+      # as the step above resolves it. It reads only that one pull request: under the ruleset's ALLGREEN grouping a
       # pull request merges only when its own group passes, and a failed group
       # removes the pull request it was built for, never one ahead of it
       # (HEADGREEN would need every entry read), so failing on an earlier
       # entry's label would eject an unlabeled pull request while the labeled
       # one still merged. A label that lands after this step passed does not stop the merge;
-      # dequeue the pull request as well. An unparsable ref or an unreadable
-      # label list fails closed. Pinned by scripts/ci-hold-merge-group.test.sh,
-      # which runs this body.
-      - name: Fail a queued pull request labeled do-not-merge
+      # dequeue the pull request as well. An unparsable ref, an unreadable
+      # tracker config or an unreadable label list fails closed. Pinned by
+      # scripts/ci-hold-merge-group.test.sh, which runs this body.
+      - name: Fail a queued pull request carrying a hold label
         if: github.event_name == 'merge_group'
         env:
           GH_TOKEN: ${{ github.token }}
+          BASE_SHA: ${{ github.event.merge_group.base_sha }}
         run: |
           pr=$(sed -nE 's#^(refs/heads/)?gh-readonly-queue/.+/pr-([0-9]+)-[0-9a-f]{40}$#\2#p' <<<"$GITHUB_REF")
           if [ -z "$pr" ]; then
             echo "::error::cannot read a pull request number from the merge-group ref '$GITHUB_REF'."
             exit 1
           fi
+          if [[ ! $BASE_SHA =~ ^[0-9a-f]{40}$ ]]; then
+            echo "::error::the base commit '$BASE_SHA' is not a commit SHA."
+            exit 1
+          fi
+          for attempt in 1 2 3; do
+            if tracker=$(gh api -H 'Accept: application/vnd.github.raw+json' "repos/$GITHUB_REPOSITORY/contents/.work-item-tracker.json?ref=$BASE_SHA" 2>"$RUNNER_TEMP/tracker.err"); then
+              break
+            elif grep -q 'HTTP 404' "$RUNNER_TEMP/tracker.err"; then
+              tracker=
+              break
+            fi
+            [ "$attempt" -lt 3 ] || { echo "::error::could not read .work-item-tracker.json at $BASE_SHA; re-run this run."; exit 1; }
+            sleep $((attempt * 5))
+          done
+          human_gated=needs-human
+          if [ -n "$tracker" ]; then
+            human_gated=$(jq -er '[objects | .config | objects | .role_labels | objects
+              | .["human-gated"] | strings | gsub("^\\s+|\\s+$"; "")][0] // ""
+              | if . == "" then "needs-human" else . end' <<<"$tracker") || {
+              echo "::error::cannot read the human-gated role label from .work-item-tracker.json at $BASE_SHA"
+              exit 1
+            }
+          fi
           for attempt in 1 2 3; do
             if labels=$(gh api "repos/$GITHUB_REPOSITORY/issues/$pr/labels?per_page=100" --paginate --jq '.[].name'); then
               break
@@ -3222,11 +3312,17 @@ jobs:
             [ "$attempt" -lt 3 ] || { echo "::error::could not read the labels of #$pr; re-run this run."; exit 1; }
             sleep $((attempt * 5))
           done
+          held=0
           if grep -qxF do-not-merge <<<"$labels"; then
+            held=1
             echo "::error::#$pr carries the 'do-not-merge' label; the merge queue removes it. Remove the label and re-queue to merge."
-            exit 1
           fi
-          echo "#$pr carries no 'do-not-merge' label."
+          if grep -qxF -- "$human_gated" <<<"$labels"; then
+            held=1
+            echo "::error::#$pr carries '$human_gated'; the merge queue removes it. Removing the label approves this pull request; re-queue it to merge."
+          fi
+          [ "$held" -eq 0 ] || exit 1
+          echo "#$pr carries neither 'do-not-merge' nor '$human_gated'."
       # ORDERED SKIPS ARE CHECKED HERE. A test lane `test-<x>`, or `lint-shell`
       # on its `run_shell` row, skips as a job when `select-tests`'s `run_<x>`
       # row says the change gives it no work. Its
diff --git a/scripts/ci-hold-human-gated.test.sh b/scripts/ci-hold-human-gated.test.sh
new file mode 100755
index 0000000000..9e861110ab
--- /dev/null
+++ b/scripts/ci-hold-human-gated.test.sh
@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+# Runs the `Fail a pull request carrying the human-gated label` step body of
+# .github/workflows/pr-require-checks.yml's ci-status under the shell Actions
+# gives a step with no `shell:` (bash -e), against stub `gh` and `sleep`.
+#
+# On a pull_request event, contract-only runs included, ci-status fails while
+# the pull request carries the human-gated label the base commit's
+# .work-item-tracker.json names (default `needs-human`), read live from the API.
+# The error names the reason from the newest review-lane hold comment, and says
+# that removing the label approves. It fails closed when it cannot tell.
+# test-scope: .github/workflows/pr-require-checks.yml
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+WORKFLOW="$ROOT/.github/workflows/pr-require-checks.yml"
+
+# shellcheck source=lib/test-harness.sh
+. "$ROOT/scripts/lib/test-harness.sh"
+
+TMP_ROOT="$(mktemp -d)"
+trap 'rm -rf "$TMP_ROOT"' EXIT
+
+NAME='Fail a pull request carrying the human-gated label'
+step="$(awk -v name="      - name: $NAME" '$0 == name { on = 1; print; next }
+  on && /^      - / { exit }
+  on { print }' "$WORKFLOW")"
+awk '/^        run: \|$/ { on = 1; next }
+  on && /^          / { print substr($0, 11); next }
+  on && /^[[:blank:]]*$/ { print ""; next }
+  on { exit }' <<<"$step" >"$TMP_ROOT/body.sh"
+
+if [[ ! -s "$TMP_ROOT/body.sh" ]]; then
+  fail "no '$NAME' step with a run: | body in $WORKFLOW"
+  test_harness::report
+  exit 1
+fi
+# Every pull_request run, contract-only and draft included, and after a
+# failed earlier step, so the hold is never hidden.
+if [[ "$step" == *"if: \${{ !cancelled() && github.event_name == 'pull_request' }}"* ]]; then
+  ok "step runs on every pull_request run that is not cancelled"
+else
+  fail "step lost its pull_request condition"
+fi
+if [[ "$step" == *"continue-on-error"* ]]; then
+  fail "step must not continue on error: its exit code is the hold"
+else
+  ok "step fails the job on its exit code"
+fi
+if [[ "$step" == *"BASE_SHA: \${{ github.event.pull_request.base.sha }}"* ]]; then
+  ok "step reads the tracker config at the base commit, never the head"
+else
+  fail "step does not read the tracker config at pull_request.base.sha"
+fi
+order="$(grep -nE "^  ci-status:$|^      - name: ($NAME|Aggregate lane results)$" "$WORKFLOW" | cut -d: -f1 | paste -sd' ')"
+read -r job_line hold_line agg_line <<<"$order"
+if [[ -n "${agg_line:-}" && "$job_line" -lt "$hold_line" && "$hold_line" -lt "$agg_line" ]]; then
+  ok "step sits in ci-status before the aggregate"
+else
+  fail "step is not inside ci-status before the aggregate (lines: $order)"
+fi
+gate="$(awk '/^  ci-status:$/ { on = 1; next } on && /^    if: / { print; exit }' "$WORKFLOW")"
+if [[ "$gate" == "    if: \${{ !cancelled() }}" ]]; then
+  ok "ci-status carries no contract-only gate, so the step runs on label events"
+else
+  fail "ci-status gained a gate that could skip the hold: '$gate'"
+fi
+
+# The stub logs its arguments. A contents read fails its first
+# STUB_TRACKER_FAILS calls, then answers 404 when STUB_TRACKER is unset, else
+# prints STUB_TRACKER. A labels read fails its first STUB_FAILS calls, then
+# prints STUB_LABELS one per line. A comments read fails when STUB_COMMENTS_FAIL
+# is set, else applies the --jq filter to the STUB_COMMENTS array, as gh does
+# per page.
+mkdir -p "$TMP_ROOT/bin"
+cat >"$TMP_ROOT/bin/gh" <<'EOF'
+#!/usr/bin/env bash
+printf '%s\n' "$*" >>"$STUB_LOG"
+case "$*" in
+*/contents/.work-item-tracker.json*)
+  [[ "$(grep -c '/contents/' "$STUB_LOG")" -gt "${STUB_TRACKER_FAILS:-0}" ]] || { echo 'gh: Server Error (HTTP 502)' >&2; exit 1; }
+  [[ -n "${STUB_TRACKER+set}" ]] || { echo 'gh: Not Found (HTTP 404)' >&2; exit 1; }
+  printf '%s\n' "$STUB_TRACKER"
+  ;;
+*/labels*)
+  [[ "$(grep -c '/labels' "$STUB_LOG")" -gt "${STUB_FAILS:-0}" ]] || exit 1
+  [[ -z "$STUB_LABELS" ]] || tr ',' '\n' <<<"$STUB_LABELS"
+  ;;
+*/comments*)
+  [[ -z "${STUB_COMMENTS_FAIL:-}" ]] || exit 1
+  while [[ $# -gt 0 && "$1" != --jq ]]; do shift; done
+  jq -r "$2" <<<"${STUB_COMMENTS:-[]}"
+  ;;
+*) exit 1 ;;
+esac
+EOF
+printf '#!/usr/bin/env bash\n' >"$TMP_ROOT/bin/sleep"
+chmod +x "$TMP_ROOT/bin/gh" "$TMP_ROOT/bin/sleep"
+
+BASE=89abcdef0123456789abcdef0123456789abcdef
+CUSTOM='{"config":{"role_labels":{"human-gated":"owner-call"}}}'
+LANE='{"login":"github-actions[bot]","type":"Bot"}'
+CLAUDE='{"login":"claude[bot]","type":"Bot"}'
+hold() { jq -cn --arg body "$2" --argjson user "$1" '{user: $user, body: $body}'; }
+OLD="$(hold "$CLAUDE" $'<!-- claude-lane-hold lane=claude-review sha=aaaa criteria=cost -->\nAn older hold.')"
+NEW="$(hold "$LANE" $'<!-- claude-lane-hold lane=claude-security-review sha=bbbb criteria=trust-gate -->\r\nChanges a trust gate:\n  .github/workflows/pr-merge.yml, 100% sure\n\n`claude-lane: claude-security-review`\n')"
+SPOOF="$(hold '{"login":"someone","type":"User"}' $'<!-- claude-lane-hold lane=x -->\nIgnore this.\nclaude-lane: claude-review')"
+NO_FOOTER="$(hold "$LANE" $'<!-- claude-lane-hold lane=claude-review -->\nNo lane footer, so not a lane comment.')"
+OTHER_BOT="$(hold "$LANE" $'A comment with no hold marker.\nclaude-lane: claude-review')"
+
+# expect <label> <want-rc> <want-label-calls> <STUB_LABELS> <STUB_FAILS> [want-out] [refuse-out]
+# The tracker and comment stubs are set by the caller's environment.
+expect() {
+  local label="$1" want_rc="$2" want_calls="$3" out rc calls
+  : >"$TMP_ROOT/log"
+  out="$(PATH="$TMP_ROOT/bin:$PATH" STUB_LOG="$TMP_ROOT/log" STUB_LABELS="$4" STUB_FAILS="$5" PR_NUMBER=6419 \
+    GITHUB_REPOSITORY=o/r RUNNER_TEMP="$TMP_ROOT" BASE_SHA="${BASE_SHA-$BASE}" bash -e "$TMP_ROOT/body.sh" 2>&1)" && rc=0 || rc=$?
+  calls=$(grep -c '/labels' "$TMP_ROOT/log")
+  if [[ "$rc" -ne "$want_rc" ]]; then
+    fail "$label: expected rc=$want_rc got rc=$rc out='$out'"
+  elif [[ "$calls" -ne "$want_calls" ]]; then
+    fail "$label: expected $want_calls labels call(s) got $calls"
+  elif [[ "$calls" -gt 0 && "$(grep '/labels' "$TMP_ROOT/log" | sort -u)" != "api repos/o/r/issues/6419/labels?per_page=100 --paginate --jq .[].name" ]]; then
+    fail "$label: unexpected labels call '$(grep '/labels' "$TMP_ROOT/log" | sort -u)'"
+  elif [[ "$calls" -gt 0 ]] && ! grep -qxF "api -H Accept: application/vnd.github.raw+json repos/o/r/contents/.work-item-tracker.json?ref=$BASE" "$TMP_ROOT/log"; then
+    fail "$label: the tracker config was not read at the base commit: '$(sort -u "$TMP_ROOT/log")'"
+  elif [[ -n "${6:-}" && "$out" != *"$6"* ]]; then
+    fail "$label: output lacks '$6': '$out'"
+  elif [[ -n "${7:-}" && "$out" == *"$7"* ]]; then
+    fail "$label: output has '$7': '$out'"
+  else
+    ok "$label"
+  fi
+}
+
+APPROVE="Removing the label approves this pull request; ci-status re-runs on the unlabel."
+
+expect "an unlabeled pull request passes" 0 1 "enhancement,do-not-merge" 0 "#6419 carries no 'needs-human' label."
+if grep -q '/comments' "$TMP_ROOT/log"; then fail "comments are read only when the label is on"; else ok "comments are read only when the label is on"; fi
+expect "a pull request with no labels passes" 0 1 "" 0
+expect "a label that only contains the name does not hold" 0 1 "needs-human-later,not-needs-human" 0
+expect "needs-human with no hold comment fails without a reason" 1 1 "ci,needs-human" 0 \
+  "::error::#6419 carries 'needs-human'. $APPROVE"
+
+export STUB_COMMENTS="[$OLD,$NEW,$SPOOF,$NO_FOOTER,$OTHER_BOT]"
+expect "the newest lane hold comment gives the reason, without its footer" 1 1 "needs-human" 0 \
+  "::error::#6419 carries 'needs-human' (Changes a trust gate: .github/workflows/pr-merge.yml, 100%25 sure). $APPROVE" "An older hold"
+expect "a hold comment from a person is not read" 1 1 "needs-human" 0 "" "Ignore this"
+expect "a github-actions[bot] hold comment with no lane footer is not read" 1 1 "needs-human" 0 "" "No lane footer"
+export STUB_COMMENTS="[$NEW,$OLD]"
+expect "a claude[bot] hold comment gives the reason" 1 1 "needs-human" 0 "(An older hold.). $APPROVE"
+LONG="$(printf 'x%.0s' {1..400})"
+STUB_COMMENTS="[$(hold "$CLAUDE" "<!-- claude-lane-hold lane=claude-review -->
+$LONG")]"
+expect "a long reason is cut to 300 characters" 1 1 "needs-human" 0 "(${LONG:0:300}). $APPROVE"
+export STUB_COMMENTS_FAIL=1
+expect "an unreadable comment list still fails, without a reason" 1 1 "needs-human" 0 "::error::#6419 carries 'needs-human'. $APPROVE"
+unset STUB_COMMENTS STUB_COMMENTS_FAIL
+
+expect "a transient label read failure is retried" 1 2 "needs-human" 1
+expect "an unreadable label list fails closed" 1 3 "" 3 "::error::could not read the labels of #6419"
+
+export STUB_TRACKER="$CUSTOM"
+expect "the base tracker's human-gated label holds" 1 1 "owner-call" 0 "::error::#6419 carries 'owner-call'. $APPROVE"
+expect "needs-human does not hold when the tracker names another label" 0 1 "needs-human" 0 "#6419 carries no 'owner-call' label."
+export STUB_TRACKER='{not json'
+expect "an invalid tracker config fails closed" 1 0 "" 0 "::error::cannot read the human-gated role label"
+export STUB_TRACKER="$CUSTOM" STUB_TRACKER_FAILS=1
+expect "a transient tracker read failure is retried" 1 1 "owner-call" 0 "carries 'owner-call'"
+export STUB_TRACKER_FAILS=3
+expect "an unreadable tracker config fails closed" 1 0 "" 0 "::error::could not read .work-item-tracker.json"
+unset STUB_TRACKER STUB_TRACKER_FAILS
+export BASE_SHA=main
+expect "a base that is not a commit SHA fails closed without a call" 1 0 "" 0 "::error::the base commit 'main' is not a commit SHA"
+unset BASE_SHA
+
+test_harness::report
diff --git a/scripts/ci-hold-merge-group.test.sh b/scripts/ci-hold-merge-group.test.sh
index fb492f647f..b756a105ea 100755
--- a/scripts/ci-hold-merge-group.test.sh
+++ b/scripts/ci-hold-merge-group.test.sh
@@ -1,11 +1,12 @@
 #!/usr/bin/env bash
-# Runs the `Fail a queued pull request labeled do-not-merge` step body of
+# Runs the `Fail a queued pull request carrying a hold label` step body of
 # .github/workflows/pr-require-checks.yml's ci-status under the shell Actions
 # gives a step with no `shell:` (bash -e), against stub `gh` and `sleep`.
 #
 # A merge-group run carries no pull request, so this step is the only reader of
-# the hold label in the merge queue (#5952). It must fail on the label, pass
-# without it, and fail closed when it cannot tell.
+# the hold labels in the merge queue: `do-not-merge` and the human-gated label
+# the base commit's .work-item-tracker.json names (default `needs-human`). It
+# must fail on either, pass without them, and fail closed when it cannot tell.
 # test-scope: .github/workflows/pr-require-checks.yml
 set -uo pipefail
 
@@ -18,7 +19,7 @@ WORKFLOW="$ROOT/.github/workflows/pr-require-checks.yml"
 TMP_ROOT="$(mktemp -d)"
 trap 'rm -rf "$TMP_ROOT"' EXIT
 
-NAME='Fail a queued pull request labeled do-not-merge'
+NAME='Fail a queued pull request carrying a hold label'
 step="$(awk -v name="      - name: $NAME" '$0 == name { on = 1; print; next }
   on && /^      - / { exit }
   on { print }' "$WORKFLOW")"
@@ -42,6 +43,11 @@ if [[ "$step" == *"continue-on-error"* ]]; then
 else
   ok "step fails the job on its exit code"
 fi
+if [[ "$step" == *"BASE_SHA: \${{ github.event.merge_group.base_sha }}"* ]]; then
+  ok "step reads the tracker config at the group's base commit"
+else
+  fail "step does not read the tracker config at merge_group.base_sha"
+fi
 # Inside ci-status, before the aggregate, so a red here is the job's answer.
 order="$(grep -nE "^  ci-status:$|^      - name: ($NAME|Aggregate lane results)$" "$WORKFLOW" | cut -d: -f1 | paste -sd' ')"
 read -r job_line hold_line agg_line <<<"$order"
@@ -51,36 +57,52 @@ else
   fail "step is not inside ci-status before the aggregate (lines: $order)"
 fi
 
-# The stub logs its arguments; it fails the first STUB_FAILS calls, then
+# The stub logs its arguments. A contents read fails its first
+# STUB_TRACKER_FAILS calls, then answers 404 when STUB_TRACKER is unset, else
+# prints STUB_TRACKER. A labels read fails its first STUB_FAILS calls, then
 # prints STUB_LABELS one per line.
 mkdir -p "$TMP_ROOT/bin"
 cat >"$TMP_ROOT/bin/gh" <<'EOF'
 #!/usr/bin/env bash
 printf '%s\n' "$*" >>"$STUB_LOG"
-calls=$(wc -l <"$STUB_LOG")
-[[ "$calls" -gt "${STUB_FAILS:-0}" ]] || exit 1
-[[ -z "$STUB_LABELS" ]] || tr ',' '\n' <<<"$STUB_LABELS"
+case "$*" in
+*/contents/.work-item-tracker.json*)
+  [[ "$(grep -c '/contents/' "$STUB_LOG")" -gt "${STUB_TRACKER_FAILS:-0}" ]] || { echo 'gh: Server Error (HTTP 502)' >&2; exit 1; }
+  [[ -n "${STUB_TRACKER+set}" ]] || { echo 'gh: Not Found (HTTP 404)' >&2; exit 1; }
+  printf '%s\n' "$STUB_TRACKER"
+  ;;
+*/labels*)
+  [[ "$(grep -c '/labels' "$STUB_LOG")" -gt "${STUB_FAILS:-0}" ]] || exit 1
+  [[ -z "$STUB_LABELS" ]] || tr ',' '\n' <<<"$STUB_LABELS"
+  ;;
+*) exit 1 ;;
+esac
 EOF
 printf '#!/usr/bin/env bash\n' >"$TMP_ROOT/bin/sleep"
 chmod +x "$TMP_ROOT/bin/gh" "$TMP_ROOT/bin/sleep"
 
 SHA=0123456789abcdef0123456789abcdef01234567
+BASE=89abcdef0123456789abcdef0123456789abcdef
 QUEUE="refs/heads/gh-readonly-queue/main/pr-6419-$SHA"
+CUSTOM='{"config":{"role_labels":{"human-gated":" owner-call "}}}'
 
-# expect <label> <want-rc> <want-gh-calls> <want-pr|-> <GITHUB_REF> <STUB_LABELS> <STUB_FAILS> [want-out]
+# expect <label> <want-rc> <want-label-calls> <want-pr|-> <GITHUB_REF> <STUB_LABELS> <STUB_FAILS> [want-out]
+# The tracker stub is set by the caller's environment (STUB_TRACKER, STUB_TRACKER_FAILS, BASE_SHA).
 expect() {
   local label="$1" want_rc="$2" want_calls="$3" want_pr="$4" out rc calls
   : >"$TMP_ROOT/log"
   out="$(PATH="$TMP_ROOT/bin:$PATH" STUB_LOG="$TMP_ROOT/log" GITHUB_REF="$5" STUB_LABELS="$6" STUB_FAILS="$7" \
-    GITHUB_REPOSITORY=o/r bash -e "$TMP_ROOT/body.sh" 2>&1)" && rc=0 || rc=$?
-  calls=$(wc -l <"$TMP_ROOT/log")
+    GITHUB_REPOSITORY=o/r RUNNER_TEMP="$TMP_ROOT" BASE_SHA="${BASE_SHA-$BASE}" bash -e "$TMP_ROOT/body.sh" 2>&1)" && rc=0 || rc=$?
+  calls=$(grep -c '/labels' "$TMP_ROOT/log")
   if [[ "$rc" -ne "$want_rc" ]]; then
     fail "$label: expected rc=$want_rc got rc=$rc out='$out'"
   elif [[ "$calls" -ne "$want_calls" ]]; then
-    fail "$label: expected $want_calls gh call(s) got $calls"
+    fail "$label: expected $want_calls labels call(s) got $calls"
   elif [[ "$want_pr" != - ]] &&
-    [[ "$(sort -u "$TMP_ROOT/log")" != "api repos/o/r/issues/$want_pr/labels?per_page=100 --paginate --jq .[].name" ]]; then
+    [[ "$(grep '/labels' "$TMP_ROOT/log" | sort -u)" != "api repos/o/r/issues/$want_pr/labels?per_page=100 --paginate --jq .[].name" ]]; then
     fail "$label: unexpected gh call '$(sort -u "$TMP_ROOT/log")'"
+  elif [[ "$want_pr" != - ]] && ! grep -qxF "api -H Accept: application/vnd.github.raw+json repos/o/r/contents/.work-item-tracker.json?ref=${BASE_SHA-$BASE}" "$TMP_ROOT/log"; then
+    fail "$label: the tracker config was not read at the base commit: '$(sort -u "$TMP_ROOT/log")'"
   elif [[ -n "${8:-}" && "$out" != *"$8"* ]]; then
     fail "$label: output lacks '$8': '$out'"
   else
@@ -88,10 +110,11 @@ expect() {
   fi
 }
 
-expect "unlabeled queued pull request passes" 0 1 6419 "$QUEUE" "enhancement,ci" 0 "#6419 carries no"
+expect "unlabeled queued pull request passes" 0 1 6419 "$QUEUE" "enhancement,ci" 0 "#6419 carries neither"
 expect "pull request with no labels passes" 0 1 6419 "$QUEUE" "" 0
 expect "do-not-merge fails the run" 1 1 6419 "$QUEUE" "ci,do-not-merge" 0 "::error::#6419 carries the 'do-not-merge' label"
-expect "a label that only contains the name does not hold" 0 1 6419 "$QUEUE" "do-not-merge-later,not-do-not-merge" 0
+expect "needs-human fails the run" 1 1 6419 "$QUEUE" "ci,needs-human" 0 "::error::#6419 carries 'needs-human'; the merge queue removes it. Removing the label approves this pull request"
+expect "a label that only contains the name does not hold" 0 1 6419 "$QUEUE" "do-not-merge-later,not-do-not-merge,needs-human-later" 0
 expect "ref without refs/heads/ is read" 1 1 6419 "gh-readonly-queue/main/pr-6419-$SHA" "do-not-merge" 0
 expect "base branch with a slash is read" 1 1 12 "refs/heads/gh-readonly-queue/release/v2/pr-12-$SHA" "do-not-merge" 0
 expect "a transient read failure is retried" 1 2 6419 "$QUEUE" "do-not-merge" 1
@@ -99,4 +122,20 @@ expect "an unreadable label list fails closed" 1 3 6419 "$QUEUE" "" 3 "::error::
 expect "a non-queue ref fails closed without a call" 1 0 - "refs/heads/main" "" 0 "::error::cannot read a pull request number"
 expect "a short sha fails closed without a call" 1 0 - "refs/heads/gh-readonly-queue/main/pr-6419-abc123" "" 0
 
+export STUB_TRACKER="$CUSTOM"
+expect "the base tracker's human-gated label holds" 1 1 6419 "$QUEUE" "owner-call" 0 "::error::#6419 carries 'owner-call'"
+expect "needs-human does not hold when the tracker names another label" 0 1 6419 "$QUEUE" "needs-human" 0 "carries neither 'do-not-merge' nor 'owner-call'"
+export STUB_TRACKER='{"config":{"lease_ttl_hours":24}}'
+expect "a tracker naming no label falls back to needs-human" 1 1 6419 "$QUEUE" "needs-human" 0 "carries 'needs-human'"
+export STUB_TRACKER='{not json'
+expect "an invalid tracker config fails closed" 1 0 - "$QUEUE" "" 0 "::error::cannot read the human-gated role label"
+export STUB_TRACKER="$CUSTOM" STUB_TRACKER_FAILS=1
+expect "a transient tracker read failure is retried" 1 1 6419 "$QUEUE" "owner-call" 0 "carries 'owner-call'"
+export STUB_TRACKER_FAILS=3
+expect "an unreadable tracker config fails closed" 1 0 - "$QUEUE" "" 0 "::error::could not read .work-item-tracker.json"
+unset STUB_TRACKER STUB_TRACKER_FAILS
+export BASE_SHA=main
+expect "a base that is not a commit SHA fails closed without a call" 1 0 - "$QUEUE" "" 0 "::error::the base commit 'main' is not a commit SHA"
+unset BASE_SHA
+
 test_harness::report

From 1b58fe1fc1e4e9ec1f7c226034f3e9697bfe47c2 Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Fri, 23 Oct 2026 00:51:10 -0400
Subject: [PATCH 2/2] fix(pr-pipeline): spell the lane footer backtick as a jq
 escape

actionlint's shellcheck pass (SC2016) read the literal backtick inside
the single-quoted jq programs as an unexpanded expression and failed
lint-repo. ` is the same character to jq's regex, so behavior is
unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/pr-require-checks.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/pr-require-checks.yml b/.github/workflows/pr-require-checks.yml
index b595fb1b45..e295a0f306 100644
--- a/.github/workflows/pr-require-checks.yml
+++ b/.github/workflows/pr-require-checks.yml
@@ -3247,10 +3247,10 @@ jobs:
             --jq '.[] | select(.user.type == "Bot" and (.body | test("(^|\n)<!-- claude-lane-hold lane="))
               and (.user.login == "claude[bot]" or (.user.login == "github-actions[bot]"
                 and ([.body | splits("\r?\n") | gsub("^\\s+|\\s+$"; "") | select(. != "")] | last // ""
-                  | test("^`?claude-lane: (claude-review|claude-security-review)`?$")))))
+                  | test("^\u0060?claude-lane: (claude-review|claude-security-review)\u0060?$")))))
               | .body | @json' | tail -n 1 |
             jq -r '[splits("[\r\n]+") | gsub("^\\s+|\\s+$"; "")
-              | select(. != "" and (test("^<!--|^`?claude-lane: ") | not))] | join(" ") | .[0:300]') || reason=
+              | select(. != "" and (test("^<!--|^\u0060?claude-lane: ") | not))] | join(" ") | .[0:300]') || reason=
           why=
           [ -z "$reason" ] || why=" (${reason//%/%25})"
           echo "::error::#$PR_NUMBER carries '$human_gated'$why. Removing the label approves this pull request; ci-status re-runs on the unlabel."