메뉴
Drive one open ScenarioCraft pull request through CI repair, review-thread resolution, final review, and squash merge. Use after opening a PR or when asked to fix CI or review feedback and continue until the PR is green, clean, and merged.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | resolve-pr |
| description | Drive one open ScenarioCraft pull request through CI repair, review-thread resolution, final review, and squash merge. Use after opening a PR or when asked to fix CI or review feedback and continue until the PR is green, clean, and merged. |
Job: Drive one open pull request to green-and-clean, then merge it.
Inputs: A PR number.
Outputs: A merged PR, or an escalation comment explaining what a human must decide.
gh auth status must succeed, with repository access, pull-request write scope, and
Actions/checks read access. The installed gh must expose --match-head-commit; verify it
with gh pr merge --help. The workflow requires the GitHub CLI; fail fast when gh is
absent instead of attempting installation during PR resolution. Verify the checked-in CI
workflow exists before relying on check state.
SCENARIOCRAFT_REPO is an optional owner/name string; it defaults to
agorokh/scenariocraft.SCENARIOCRAFT_CI_WAIT_SECONDS is an optional positive integer in seconds; it defaults to
1800.RESOLVE_PR_POLL_INTERVAL_SECONDS is an optional positive integer in seconds; it defaults
to 600.SCENARIOCRAFT_REVIEW_APP_LOGIN is the GraphQL login of the repository's configured
review app; it defaults to ws-ops-cursor-reviewer.Set overrides with export NAME=value in the shell that launches the agent. These skills
do not load .env files or service-manager configuration implicitly.
Execute the shell snippets in one persistent shell process so validated variables and helper functions remain defined. If the turn or shell ends, resume by rerunning steps 1–4 before calling any helper; do not assume shell functions are exported across processes.
Authenticate, resolve the repository target, reject a dirty worktree, check out the
requested PR head, and verify that local HEAD matches it before editing or pushing.
SCENARIOCRAFT_REPO supports an intentional fork or renamed remote while retaining the
canonical repository as the fallback:
set -euo pipefail
command -v gh
command -v jq
JQ_VERSION="$(jq --version)"
JQ_VERSION_NUMBER="$(
printf '%s\n' "${JQ_VERSION}" |
grep -Eo '[0-9]+\.[0-9]+' |
head -n 1
)"
[[ "${JQ_VERSION_NUMBER}" =~ ^[0-9]+\.[0-9]+$ ]] ||
{ printf 'Cannot parse jq version: %s\n' "${JQ_VERSION}" >&2; exit 1; }
JQ_MAJOR="${JQ_VERSION_NUMBER%%.*}"
JQ_MINOR="${JQ_VERSION_NUMBER#*.}"
if ! { test "${JQ_MAJOR}" -gt 1 ||
{ test "${JQ_MAJOR}" -eq 1 && test "${JQ_MINOR}" -ge 6; }; }; then
printf 'jq 1.6 or newer is required\n' >&2
exit 1
fi
command -v sleep
command -v awk
command -v date
command -v grep
command -v head
command -v mktemp
REPO="${SCENARIOCRAFT_REPO:-agorokh/scenariocraft}"
[[ "${REPO}" =~ ^[A-Za-z0-9][A-Za-z0-9_.-]*/[A-Za-z0-9][A-Za-z0-9_.-]*$ ]] &&
test "${REPO%%/*}" != "." && test "${REPO%%/*}" != ".." &&
test "${REPO#*/}" != "." && test "${REPO#*/}" != ".." ||
{ printf 'Repository must be owner/name\n' >&2; exit 1; }
OWNER="${REPO%%/*}"
NAME="${REPO#*/}"
REVIEW_APP_LOGIN="${SCENARIOCRAFT_REVIEW_APP_LOGIN:-ws-ops-cursor-reviewer}"
[[ "${REVIEW_APP_LOGIN}" =~ ^[A-Za-z0-9-]+$ ]] ||
{ printf 'Invalid review app login\n' >&2; exit 1; }
PR=<P>
[[ "${PR}" =~ ^[1-9][0-9]*$ ]] ||
{ printf 'PR number must be a positive integer\n' >&2; exit 1; }
gh auth status
RESOLVER_LOGIN="$(gh api user --jq .login)"
PERMISSION="$(gh repo view "${REPO}" --json viewerPermission --jq .viewerPermission)"
[[ "${PERMISSION}" =~ ^(WRITE|MAINTAIN|ADMIN)$ ]] ||
{ printf 'Pull-request write access is required\n' >&2; exit 1; }
gh api "repos/${REPO}/actions/runs?per_page=1" >/dev/null
GH_PR_MERGE_HELP="$(gh pr merge --help)"
grep -q -- '--match-head-commit' <<<"${GH_PR_MERGE_HELP}"
GH_PR_EDIT_HELP="$(gh pr edit --help)"
grep -q -- '--body-file' <<<"${GH_PR_EDIT_HELP}"
gh repo view "${REPO}" --json nameWithOwner
test -z "$(git status --porcelain)"
gh pr checkout <P> --repo "${REPO}"
test "$(git rev-parse HEAD)" = \
"$(gh pr view <P> --repo "${REPO}" --json headRefOid --jq .headRefOid)"
test -f Makefile
make -n ci-fast >/dev/null
test -f code_review.md
test -f .github/workflows/ci.yml
Inspect the PR:
gh pr view <P> --repo "${REPO}" \
--json number,state,isDraft,headRefOid,statusCheckRollup,mergeable,reviewDecision,reviewRequests,comments,reviews
test "$(gh pr view <P> --repo "${REPO}" --json state --jq .state)" = "OPEN" || {
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: resolve-pr only operates on an OPEN pull request."
exit 1
}
If isDraft is true, stop and hand it back to its author or the deliver skill.
deliver owns the draft-to-ready transition after CI is green; resolve-pr starts once
external review has begun. Keep a ## Codex sessions list in the PR description and add
this resolution session's ID only when that exact list item is absent. Preserve the rest
of the description. This idempotent set of unique IDs keeps every session that changed
the PR auditable without duplicating entries after a resumed invocation.
Before entering the CI-repair path, initialize the head watermark and load the durable repair counters. Step 4 reloads the complete ledger, but step 3 must never read an unset counter:
REVIEWED_SHA="$(gh pr view <P> --repo "${REPO}" \
--json headRefOid --jq .headRefOid)"
[[ "${REVIEWED_SHA}" =~ ^[0-9a-f]{40}$ ]] ||
{ printf 'GitHub returned an invalid full head OID\n' >&2; exit 1; }
RESOLVE_PR_DEFAULT_POLL_INTERVAL_SECONDS=600
CONVERSATION_LEDGER_JSON='[]'
REVIEW_LEDGER_JSON='[]'
LEDGER_INVENTORY_AUTHORITATIVE=0
REPAIR_ATTEMPTS_JSON='{}'
PR_BODY="$(gh pr view <P> --repo "${REPO}" --json body --jq .body)"
if printf '%s\n' "${PR_BODY}" |
grep -q '^<!-- resolve-pr-ledgers:v1$'; then
EARLY_LEDGER_JSON="$(
printf '%s\n' "${PR_BODY}" |
awk '
/^<!-- resolve-pr-ledgers:v1$/ { capture = 1; next }
capture && /^-->$/ { exit }
capture { print }
'
)"
REPAIR_ATTEMPTS_JSON="$(
printf '%s' "${EARLY_LEDGER_JSON}" |
jq -e '(.repair_attempts // {}) |
if type == "object" then . else error("invalid repair ledger") end'
)"
CONVERSATION_LEDGER_JSON="$(
printf '%s' "${EARLY_LEDGER_JSON}" |
jq -e '.conversation |
if type == "array" then . else error("invalid conversation ledger") end'
)"
REVIEW_LEDGER_JSON="$(
printf '%s' "${EARLY_LEDGER_JSON}" |
jq -e '.reviews |
if type == "array" then . else error("invalid review ledger") end'
)"
fi
validate_managed_ledger() {
local body="$1" marker_count extracted
marker_count="$(
printf '%s\n' "${body}" |
awk '/^<!-- resolve-pr-ledgers:v1$/ { count++ } END { print count + 0 }'
)"
test "${marker_count}" -le 1 || return 1
test "${marker_count}" -eq 1 || return 0
extracted="$(
printf '%s\n' "${body}" |
awk '
/^<!-- resolve-pr-ledgers:v1$/ { capture = 1; next }
capture && /^-->$/ { closed = 1; exit }
capture { print }
END { if (capture && !closed) exit 1 }
'
)" || return 1
printf '%s' "${extracted}" |
jq -e '
(.conversation | type == "array") and
(.reviews | type == "array") and
((.repair_attempts // {}) | type == "object")
' >/dev/null
}
persist_resolution_state() {
local update_attempt body current_body next_body post_update_body state_dir
local body_ledgers desired_conversation desired_reviews desired_repairs
local ledger_marker_present ledgers_json update_ok=0 update_delay
state_dir="$(mktemp -d)"
desired_conversation="${CONVERSATION_LEDGER_JSON}"
desired_reviews="${REVIEW_LEDGER_JSON}"
desired_repairs="${REPAIR_ATTEMPTS_JSON}"
printf '%s' "${desired_conversation}" >"${state_dir}/desired-conversation.json"
printf '%s' "${desired_reviews}" >"${state_dir}/desired-reviews.json"
printf '%s' "${desired_repairs}" >"${state_dir}/desired-repairs.json"
for update_attempt in 1 2 3; do
body="$(gh pr view <P> --repo "${REPO}" --json body --jq .body)" ||
{ sleep "$((update_attempt * 5))"; continue; }
validate_managed_ledger "${body}" || {
printf 'Malformed or duplicate managed ledger block\n' >&2
rm -rf "${state_dir}"
return 1
}
ledger_marker_present="$(
printf '%s\n' "${body}" |
awk '/^<!-- resolve-pr-ledgers:v1$/ { count++ } END { print count + 0 }'
)"
body_ledgers='{"conversation":[],"reviews":[],"repair_attempts":{}}'
if printf '%s\n' "${body}" |
grep -q '^<!-- resolve-pr-ledgers:v1$'; then
body_ledgers="$(
printf '%s\n' "${body}" |
awk '
/^<!-- resolve-pr-ledgers:v1$/ { capture = 1; next }
capture && /^-->$/ { exit }
capture { print }
'
)"
fi
printf '%s' "${body_ledgers}" >"${state_dir}/body-ledgers.json"
CONVERSATION_LEDGER_JSON="$(
jq -cn --slurpfile current "${state_dir}/body-ledgers.json" \
--slurpfile desired "${state_dir}/desired-conversation.json" \
--arg authoritative "${LEDGER_INVENTORY_AUTHORITATIVE}" '
if $authoritative == "1" then
$desired[0] | sort_by(.id)
else
([$current[0].conversation[] |
select(.id as $id | all($desired[0][]; .id != $id))] +
$desired[0]) |
sort_by(.id)
end
'
)"
printf '%s' "${CONVERSATION_LEDGER_JSON}" \
>"${state_dir}/merged-conversation.json"
REVIEW_LEDGER_JSON="$(
jq -cn --slurpfile current "${state_dir}/body-ledgers.json" \
--slurpfile desired "${state_dir}/desired-reviews.json" \
--arg authoritative "${LEDGER_INVENTORY_AUTHORITATIVE}" '
if $authoritative == "1" then
$desired[0] | sort_by(.id)
else
([$current[0].reviews[] |
select(.id as $id | all($desired[0][]; .id != $id))] +
$desired[0]) |
sort_by(.id)
end
'
)"
printf '%s' "${REVIEW_LEDGER_JSON}" >"${state_dir}/merged-reviews.json"
REPAIR_ATTEMPTS_JSON="$(
jq -cn --slurpfile current "${state_dir}/body-ledgers.json" \
--slurpfile desired "${state_dir}/desired-repairs.json" '
reduce ((($current[0].repair_attempts // {}) + $desired[0]) |
keys_unsorted[]) as $key
({}; .[$key] = ([($current[0].repair_attempts[$key] // 0),
($desired[0][$key] // 0)] | max))
'
)"
printf '%s' "${REPAIR_ATTEMPTS_JSON}" >"${state_dir}/merged-repairs.json"
ledgers_json="$(
jq -cn \
--slurpfile conversation "${state_dir}/merged-conversation.json" \
--slurpfile reviews "${state_dir}/merged-reviews.json" \
--slurpfile repair_attempts "${state_dir}/merged-repairs.json" \
'{conversation: $conversation[0], reviews: $reviews[0],
repair_attempts: $repair_attempts[0]}'
)"
printf '%s' "${ledgers_json}" >"${state_dir}/ledgers.json"
next_body="$(
printf '%s\n' "${body}" |
LEDGERS_PATH_FOR_AWK="${state_dir}/ledgers.json" \
LEDGER_MARKER_PRESENT_FOR_AWK="${ledger_marker_present}" awk '
BEGIN {
replaced = 0
skipping = 0
header_seen = 0
getline ledgers < ENVIRON["LEDGERS_PATH_FOR_AWK"]
close(ENVIRON["LEDGERS_PATH_FOR_AWK"])
}
/^## Comment Ledger$/ {
header_seen = 1
print
if (ENVIRON["LEDGER_MARKER_PRESENT_FOR_AWK"] == "0") {
print ""
print "<!-- resolve-pr-ledgers:v1"
print ledgers
print "-->"
replaced = 1
}
next
}
/^<!-- resolve-pr-ledgers:v1$/ {
print "<!-- resolve-pr-ledgers:v1"
print ledgers
print "-->"
replaced = 1
skipping = 1
next
}
skipping && /^-->$/ { skipping = 0; next }
skipping { next }
{ print }
END {
if (!replaced) {
if (!header_seen) {
print ""
print "## Comment Ledger"
print ""
}
print "<!-- resolve-pr-ledgers:v1"
print ledgers
print "-->"
}
}
'
)"
validate_managed_ledger "${next_body}" || {
rm -rf "${state_dir}"
return 1
}
current_body="$(gh pr view <P> --repo "${REPO}" --json body --jq .body)" ||
{ sleep "$((update_attempt * 5))"; continue; }
if test "${current_body}" = "${body}" &&
printf '%s\n' "${next_body}" |
gh pr edit <P> --repo "${REPO}" --body-file - >/dev/null; then
post_update_body="$(gh pr view <P> --repo "${REPO}" --json body --jq .body)" ||
{ sleep "$((update_attempt * 5))"; continue; }
if test "${post_update_body}" = "${next_body}"; then
update_ok=1
break
fi
fi
update_delay="$((update_attempt * 5))"
sleep "${update_delay}"
done
rm -rf "${state_dir}"
test "${update_ok}" -eq 1
}
ensure_session_receipt() {
local attempt body current_body next_body post_update_body
local session_present update_ok=0
for attempt in 1 2 3; do
body="$(gh pr view <P> --repo "${REPO}" --json body --jq .body)" ||
{ sleep "$((attempt * 5))"; continue; }
validate_managed_ledger "${body}" || return 1
session_present=0
printf '%s\n' "${body}" |
grep -Fqx -- "${SESSION_LINE}" && session_present=1
if test "${session_present}" -eq 1; then
return 0
fi
next_body="$(
printf '%s\n' "${body}" |
SESSION_FOR_AWK="${SESSION_LINE}" awk '
BEGIN { sessions_seen = 0 }
/^## Codex sessions$/ {
sessions_seen = 1
print
print ""
print ENVIRON["SESSION_FOR_AWK"]
next
}
{ print }
END {
if (!sessions_seen) {
print ""
print "## Codex sessions"
print ""
print ENVIRON["SESSION_FOR_AWK"]
}
}
'
)"
current_body="$(gh pr view <P> --repo "${REPO}" --json body --jq .body)" ||
{ sleep "$((attempt * 5))"; continue; }
if test "${current_body}" = "${body}" &&
printf '%s\n' "${next_body}" |
gh pr edit <P> --repo "${REPO}" --body-file - >/dev/null; then
post_update_body="$(gh pr view <P> --repo "${REPO}" --json body --jq .body)" ||
{ sleep "$((attempt * 5))"; continue; }
if printf '%s\n' "${post_update_body}" |
grep -Fqx -- "${SESSION_LINE}"; then
update_ok=1
break
fi
fi
sleep "$((attempt * 5))"
done
test "${update_ok}" -eq 1
}
CODEX_SESSION_ID="<SESSION_ID>"
[[ "${CODEX_SESSION_ID}" =~ ^[0-9a-f-]+$ ]] ||
{ printf 'Invalid Codex session ID\n' >&2; exit 1; }
SESSION_LINE="- \`${CODEX_SESSION_ID}\`"
ensure_session_receipt || {
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: Codex session receipt could not be persisted safely."
exit 1
}
If CI is pending, wait 60 seconds and reinspect it until terminal or until the
end-to-end budget in SCENARIOCRAFT_CI_WAIT_SECONDS expires. Default the budget to 1,800
seconds, which covers runner queue time separately from the job's own timeout; the
operator may override it with a positive integer. Validate it before use:
SCENARIOCRAFT_CI_WAIT_SECONDS="${SCENARIOCRAFT_CI_WAIT_SECONDS:-1800}"
[[ "${SCENARIOCRAFT_CI_WAIT_SECONDS}" =~ ^[1-9][0-9]*$ ]] ||
{ printf 'Invalid CI wait seconds\n' >&2; exit 1; }
Escalate if the budget expires. If CI is red, read the failing job's logs and fix the
cause rather than the symptom. Run
make ci-fast locally, commit, push, then return to step 2 so the replacement head's
checks are inspected. Track repair attempts by failing check and root cause. Increment
the matching counter when the replacement head fails for the same cause; on the third
failure, post an escalation comment with the check name, root cause, and three attempted
fixes, then stop. The escalation may contain only the check name, job URL, and a redacted
one-line cause; never paste raw logs, environment dumps, tokens, or credentials. Reset a
counter only when that check becomes green or the diagnosed root cause changes.
Treat append-only resolver evidence comments as the authoritative strike count; the
PR-body repair ledger is only a cache and cannot reset that history. Use a redacted,
stable <CHECK>:<ROOT_CAUSE> key:
# Run this counter block only when a pushed repair's replacement head has
# failed for the same root cause, never on the initial pre-repair failure.
REPAIR_KEY="<CHECK>:<REDACTED_ROOT_CAUSE>"
REPAIR_MARKER_PREFIX="resolve-pr evidence: CI repair ${REPAIR_KEY}, attempt "
REPAIR_INVENTORY_OK=0
for REPAIR_INVENTORY_DELAY in 0 5 15 45; do
if test "${REPAIR_INVENTORY_DELAY}" -gt 0; then
sleep "${REPAIR_INVENTORY_DELAY}"
fi
if REPAIR_COMMENTS_JSON="$(
gh api --paginate \
"repos/${REPO}/issues/<P>/comments?per_page=100" |
jq -s -e '
if all(.[]; type == "array") then add // []
else error("invalid repair comment page")
end'
)"; then
REPAIR_INVENTORY_OK=1
break
fi
done
test "${REPAIR_INVENTORY_OK}" -eq 1 || {
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: authoritative CI repair history could not be fetched."
exit 1
}
COMPLETED_FAILED_REPAIR_COUNT="$(
printf '%s' "${REPAIR_COMMENTS_JSON}" |
jq --arg resolver "${RESOLVER_LOGIN}" \
--arg prefix "${REPAIR_MARKER_PREFIX}" '
[.[] |
select(.user.login == $resolver) |
.body as $body |
select($body | startswith($prefix)) |
($body[($prefix | length):] |
select(test("^[1-3]/3$")) |
split("/")[0] |
tonumber)
] | unique | max // 0'
)"
NEXT_REPAIR_ATTEMPT="$((COMPLETED_FAILED_REPAIR_COUNT + 1))"
test "${NEXT_REPAIR_ATTEMPT}" -le 3
printf '%s%s/3\n' "${REPAIR_MARKER_PREFIX}" "${NEXT_REPAIR_ATTEMPT}" |
gh pr comment <P> --repo "${REPO}" --body-file -
REPAIR_ATTEMPTS_JSON="$(
printf '%s' "${REPAIR_ATTEMPTS_JSON}" |
jq --arg key "${REPAIR_KEY}" --argjson count "${NEXT_REPAIR_ATTEMPT}" \
'.[$key] = $count'
)"
persist_resolution_state || {
printf '%s\n' \
"Escalation: CI repair counter could not be persisted safely." |
gh pr comment <P> --repo "${REPO}" --body-file -
exit 1
}
test "${NEXT_REPAIR_ATTEMPT}" -lt 3 || {
printf 'Escalation: %s failed after three repair attempts.\n' \
"${REPAIR_KEY}" |
gh pr comment <P> --repo "${REPO}" --body-file -
exit 1
}
Fetch the complete feedback inventory. Page top-level conversation comments, formal reviews, and inline comments:
GRAPHQL_THREADS_JSON='[]'
GRAPHQL_REVIEWS_JSON='[]'
THREAD_COMMENTS_BY_ID_JSON='{}'
THREAD_PAGE_COUNT=0
REVIEW_PAGE_COUNT=0
PR_BODY="$(gh pr view <P> --repo "${REPO}" --json body --jq .body)"
if printf '%s\n' "${PR_BODY}" |
grep -q '^<!-- resolve-pr-ledgers:v1$'; then
LEDGERS_JSON="$(
printf '%s\n' "${PR_BODY}" |
awk '
/^<!-- resolve-pr-ledgers:v1$/ { capture = 1; next }
capture && /^-->$/ { exit }
capture { print }
'
)"
printf '%s' "${LEDGERS_JSON}" |
jq -e '.conversation | type == "array"' >/dev/null
printf '%s' "${LEDGERS_JSON}" |
jq -e '.reviews | type == "array"' >/dev/null
printf '%s' "${LEDGERS_JSON}" |
jq -e '(.repair_attempts // {}) | type == "object"' >/dev/null
CONVERSATION_LEDGER_JSON="$(
printf '%s' "${LEDGERS_JSON}" | jq '.conversation'
)"
REVIEW_LEDGER_JSON="$(
printf '%s' "${LEDGERS_JSON}" | jq '.reviews'
)"
REPAIR_ATTEMPTS_JSON="$(
printf '%s' "${LEDGERS_JSON}" | jq '.repair_attempts // {}'
)"
else
CONVERSATION_LEDGER_JSON='[]'
REVIEW_LEDGER_JSON='[]'
REPAIR_ATTEMPTS_JSON='{}'
fi
RATE_LIMIT_JSON="$(gh api rate_limit)"
GRAPHQL_REMAINING="$(
printf '%s' "${RATE_LIMIT_JSON}" | jq -r .resources.graphql.remaining
)"
test "${GRAPHQL_REMAINING}" -ge 100 || {
GRAPHQL_RESET="$(
printf '%s' "${RATE_LIMIT_JSON}" |
jq -r '.resources.graphql.reset | todateiso8601'
)"
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: GraphQL rate limit is below 100; resets at ${GRAPHQL_RESET}."
exit 1
}
REST_PAGES_FILE="$(mktemp)"
trap 'rm -f "${REST_PAGES_FILE}"' EXIT HUP INT TERM
fetch_rest_collection() {
local endpoint="$1" page=1 page_length
: >"${REST_PAGES_FILE}"
while test "${page}" -le 50; do
PAGE_OK=0
for PAGE_DELAY in 0 5 15 45; do
if test "${PAGE_DELAY}" -gt 0; then
sleep $((PAGE_DELAY + $(awk 'BEGIN { srand(); print int(rand() * 5) }')))
fi
if PAGE_JSON="$(gh api "${endpoint}&page=${page}")" &&
printf '%s' "${PAGE_JSON}" |
jq -e 'type == "array"' >/dev/null; then
PAGE_OK=1
break
fi
done
test "${PAGE_OK}" -eq 1 || return 1
page_length="$(printf '%s' "${PAGE_JSON}" | jq 'length')"
printf '%s' "${PAGE_JSON}" | jq -c . >>"${REST_PAGES_FILE}"
test "${page_length}" -eq 100 || return 0
page=$((page + 1))
done
return 1
}
fetch_rest_collection \
"repos/${REPO}/issues/<P>/comments?per_page=100" || {
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: conversation-comment inventory exceeded 50 pages."
exit 1
}
REST_COLLECTION_JSON="$(jq -s 'add // []' "${REST_PAGES_FILE}")"
CONVERSATION_COMMENTS_JSON="${REST_COLLECTION_JSON}"
CONVERSATION_LEDGER_JSON="$(
jq -cn --argjson ledger "${CONVERSATION_LEDGER_JSON}" \
--argjson comments "${CONVERSATION_COMMENTS_JSON}" \
--arg resolver "${RESOLVER_LOGIN}" '
[$comments[] as $comment |
if $comment.user.login == $resolver and
($comment.body | startswith("resolve-pr evidence:"))
then {id: $comment.id, updated_at: $comment.updated_at,
status: "ADDRESSED", system_evidence: true}
else
([$ledger[] |
select((.id | tonumber) == ($comment.id | tonumber) and
.updated_at == $comment.updated_at)][0] //
{id: $comment.id, updated_at: $comment.updated_at,
status: "UNADDRESSED"}) |
del(.system_evidence)
end
]'
)"
fetch_rest_collection \
"repos/${REPO}/pulls/<P>/reviews?per_page=100" || {
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: formal-review inventory exceeded 50 pages."
exit 1
}
REST_COLLECTION_JSON="$(jq -s 'add // []' "${REST_PAGES_FILE}")"
FORMAL_REVIEWS_JSON="${REST_COLLECTION_JSON}"
REVIEW_LEDGER_JSON="$(
jq -cn --argjson ledger "${REVIEW_LEDGER_JSON}" \
--argjson reviews "${FORMAL_REVIEWS_JSON}" '
[$reviews[] as $review |
([$ledger[] |
select((.id | tonumber) == ($review.id | tonumber) and
.submitted_at == $review.submitted_at)][0] //
{id: $review.id, submitted_at: $review.submitted_at,
status: "UNADDRESSED"})
]'
)"
LEDGER_INVENTORY_AUTHORITATIVE=1
fetch_rest_collection \
"repos/${REPO}/pulls/<P>/comments?per_page=100" || {
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: inline-comment inventory exceeded 50 pages."
exit 1
}
INLINE_COMMENTS_JSON="$(jq -s 'add // []' "${REST_PAGES_FILE}")"
Check review threads with GraphQL because REST does not report resolution state:
gh api graphql -f query='query($o:String!,$n:String!,$p:Int!,$after:String){repository(owner:$o,name:$n){pullRequest(number:$p){reviewThreads(first:50,after:$after){pageInfo{hasNextPage endCursor} nodes{id isResolved isOutdated path line comments(first:100){pageInfo{hasNextPage endCursor} nodes{databaseId author{login} body}}}}}}}' -f o="${OWNER}" -f n="${NAME}" -F p=<P>
Use -F for the PR number. -f sends a string and fails the GraphQL integer
validation. Omit the cursor flag entirely on the first call; never pass a literal
null.
If reviewThreads.pageInfo.hasNextPage is true, repeat the query with
-f after=<END_CURSOR> using the returned cursor string and continue until it is false.
Before every follow-up, derive END_CURSOR with
jq -er '.data.repository.pullRequest.reviewThreads.pageInfo.endCursor | select(type == "string" and length > 0)'; if that fails, retry the page or escalate
instead of issuing after=.
Increment a THREAD_PAGE_COUNT for every fetched page and escalate if it exceeds 50.
Accumulate every page's nodes in a running set keyed by thread id; never replace an
earlier page with a later one. After each successful page fetch, execute:
THREAD_PAGE_NODES="$(
printf '%s' "${PAGE_JSON}" |
jq -e '.data.repository.pullRequest.reviewThreads.nodes'
)"
GRAPHQL_THREADS_JSON="$(
jq -cn --argjson accumulated "${GRAPHQL_THREADS_JSON}" \
--argjson page "${THREAD_PAGE_NODES}" \
'$accumulated + $page | unique_by(.id)'
)"
THREAD_COMMENTS_BY_ID_JSON="$(
printf '%s' "${GRAPHQL_THREADS_JSON}" |
jq 'reduce .[] as $thread
({}; .[$thread.id] = ($thread.comments.nodes // []))'
)"
Separately page the GraphQL reviews connection. Unlike a submitted-review-only REST
inventory, this can expose a visible PENDING draft review that must block merge:
gh api graphql -f query='query($o:String!,$n:String!,$p:Int!,$after:String){repository(owner:$o,name:$n){pullRequest(number:$p){reviews(first:100,after:$after){pageInfo{hasNextPage endCursor} nodes{id state submittedAt author{login} commit{oid}}}}}}' -f o="${OWNER}" -f n="${NAME}" -F p=<P>
Page with -f after=<END_CURSOR> and accumulate every page's nodes in a separate
running set keyed by review id. An inventory is complete only after both connections
independently report hasNextPage: false and all accumulated pages are retained. For
either connection, when hasNextPage is true, require a nonempty endCursor; an empty
cursor is an incomplete response that must be retried or escalated, never passed as
after=. Increment a separate REVIEW_PAGE_COUNT for every fetched review page and
escalate if it exceeds 50.
# Run only after a review-thread page fetch.
THREAD_PAGE_COUNT=$((THREAD_PAGE_COUNT + 1))
test "${THREAD_PAGE_COUNT}" -le 50 || {
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: review-thread inventory exceeded 50 pages."
exit 1
}
# Run only after a formal-review page fetch.
REVIEW_PAGE_COUNT=$((REVIEW_PAGE_COUNT + 1))
test "${REVIEW_PAGE_COUNT}" -le 50 || {
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: formal-review inventory exceeded 50 pages."
exit 1
}
REVIEW_PAGE_NODES="$(
printf '%s' "${PAGE_JSON}" |
jq -e '.data.repository.pullRequest.reviews.nodes'
)"
GRAPHQL_REVIEWS_JSON="$(
jq -cn --argjson accumulated "${GRAPHQL_REVIEWS_JSON}" \
--argjson page "${REVIEW_PAGE_NODES}" \
'$accumulated + $page | unique_by(.id)'
)"
Page every thread's comments before classifying it. When
comments.pageInfo.hasNextPage is true, use the thread id and comment cursor:
[[ "${THREAD_ID}" =~ ^[A-Za-z0-9_-]+$ ]] ||
{ printf 'Invalid review-thread node ID\n' >&2; exit 1; }
gh api graphql -f query='query($id:ID!,$after:String!){node(id:$id){... on PullRequestReviewThread{comments(first:100,after:$after){pageInfo{hasNextPage endCursor} nodes{databaseId author{login} body}}}}}' -f id=<THREAD_ID> -f after=<END_CURSOR>
Repeat until comments.pageInfo.hasNextPage is false so every comment author is
considered. Accumulate comment nodes across pages and retain the first comment's
databaseId as the thread's reply target. Merge every comment page into a map keyed by
thread ID, then classify authors from that complete map:
COMMENT_PAGE_NODES="$(
printf '%s' "${PAGE_JSON}" |
jq -e '.data.node.comments.nodes'
)"
THREAD_COMMENTS_BY_ID_JSON="$(
jq -cn --argjson by_thread "${THREAD_COMMENTS_BY_ID_JSON}" \
--arg thread_id "${THREAD_ID}" \
--argjson page "${COMMENT_PAGE_NODES}" '
$by_thread +
{($thread_id):
((($by_thread[$thread_id] // []) + $page) | unique_by(.databaseId))}
'
)"
After an initial REST or GraphQL failure,
retry at most three times. Use base delays of 5, 15, and 45 seconds plus 0–4 seconds of
random jitter so concurrent agents do not synchronize retries.
If a complete inventory still cannot be fetched, post an escalation comment and stop.
Never continue with a partial response. When repeated throttling is suspected, inspect
gh api rate_limit before retrying more work.
The following concrete wrapper is the GraphQL-page implementation. REST collections use
the equivalent bounded retry inside fetch_rest_collection; both paths must retain the
same attempt limit, backoff, payload validation, and escalation behavior.
fetch_page_with_retry() {
local page_attempt
for page_attempt in 1 2 3 4; do
if PAGE_CANDIDATE="$("$@")" &&
printf '%s' "${PAGE_CANDIDATE}" |
jq -e '
if type == "object" then
((.errors // []) | length == 0) and .data != null
else
type == "array"
end' >/dev/null; then
PAGE_JSON="${PAGE_CANDIDATE}"
return 0
fi
case "${page_attempt}" in
1) sleep $((5 + $(awk 'BEGIN { srand(); print int(rand() * 5) }'))) ;;
2) sleep $((15 + $(awk 'BEGIN { srand(); print int(rand() * 5) }'))) ;;
3) sleep $((45 + $(awk 'BEGIN { srand(); print int(rand() * 5) }'))) ;;
4) break ;;
esac
done
return 1
}
fetch_page_with_retry gh api graphql \
-f query='<QUERY_FROM_ABOVE>' -f o="${OWNER}" -f n="${NAME}" -F p=<P> || {
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: complete feedback inventory failed after three retries."
exit 1
}
Classify every feedback item:
CHANGES_REQUESTED review gates merge even when it has no inline thread.
Address it and confirm that it has been dismissed or superseded before merging.Address every thread with either a fix and push or a factual reply explaining why the
finding does not apply. Use the root comment's databaseId from step 4 to post a factual
reply:
printf '%s' "${FACTUAL_REPLY}" |
jq -Rs '{body: .}' |
gh api --method POST \
"repos/${REPO}/pulls/<P>/comments/<COMMENT_ID>/replies" \
--input -
For a code fix, run local CI, commit and push it, and verify the PR headRefOid equals the
fix commit before resolving. A factual-reply-only resolution may be resolved immediately
after the reply is visible. Resolve the thread explicitly:
gh api graphql -f query='mutation($id:ID!){resolveReviewThread(input:{threadId:$id}){thread{id isResolved}}}' -f id=<THREAD_ID>
"Never silently resolve" means never resolve without a visible fix or factual reply; it
does not mean leaving an addressed thread unresolved. Verify isResolved after the
mutation. If it remains false after three attempts, post an escalation comment naming
the thread and stop. Before pushing any fix, run make ci-fast; after pushing, return to
step 2 for checks and a fresh inventory.
For an actionable top-level conversation comment, push the fix first, refresh
REVIEWED_SHA from the PR, verify it equals local HEAD, and then post a
top-level reply containing resolve-pr evidence: comment <ID>, head <SHA>. For a
non-actionable comment, post the same marker with the factual assessment. Record the
resulting GitHub comment ID as evidence_comment_id and the head as evidence_sha.
ADDRESSED is valid only while that evidence comment still exists, was authored by the
authenticated resolver, and names the source ID and current fixing SHA; PR-body status
alone is never authoritative.
Derive UNADDRESSED_CONVERSATION_COMMENT_COUNT from the complete ledger and require zero
at the merge gate; GitHub provides no resolved flag for this comment type.
REVIEWED_SHA="$(gh pr view <P> --repo "${REPO}" \
--json headRefOid --jq .headRefOid)"
[[ "${REVIEWED_SHA}" =~ ^[0-9a-f]{40}$ ]] ||
{ printf 'GitHub returned an invalid full head OID\n' >&2; exit 1; }
test "$(git rev-parse HEAD)" = "${REVIEWED_SHA}"
COMMENT_ID=<ASSESSED_COMMENT_ID>
EVIDENCE_COMMENT_ID=<POSTED_EVIDENCE_COMMENT_ID>
CONVERSATION_LEDGER_JSON="$(
printf '%s' "${CONVERSATION_LEDGER_JSON}" |
jq --argjson id "${COMMENT_ID}" \
--argjson evidence_id "${EVIDENCE_COMMENT_ID}" \
--arg sha "${REVIEWED_SHA}" '
map(if .id == $id then
.status = "ADDRESSED" |
.evidence_comment_id = $evidence_id |
.evidence_sha = $sha
else . end)'
)"
test "$(printf '%s' "${CONVERSATION_LEDGER_JSON}" | jq 'length')" -eq \
"$(printf '%s' "${CONVERSATION_COMMENTS_JSON}" | jq 'length')"
UNADDRESSED_CONVERSATION_COMMENT_COUNT="$(
printf '%s' "${CONVERSATION_LEDGER_JSON}" |
jq '[.[] | select(.status != "ADDRESSED")] | length'
)"
persist_resolution_state || {
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: durable conversation assessment could not be persisted safely."
exit 1
}
Assess every formal review body too, including a COMMENTED summary with no inline
thread. After any fix push, refresh and verify REVIEWED_SHA exactly as above. Fix or
factually acknowledge each finding in a top-level evidence comment containing the exact
marker resolve-pr evidence: review <ID>, head <SHA>, then make that review's ledger
transition explicit:
REVIEW_ID=<ASSESSED_REVIEW_ID>
EVIDENCE_COMMENT_ID=<POSTED_EVIDENCE_COMMENT_ID>
REVIEW_LEDGER_JSON="$(
printf '%s' "${REVIEW_LEDGER_JSON}" |
jq --argjson id "${REVIEW_ID}" \
--argjson evidence_id "${EVIDENCE_COMMENT_ID}" \
--arg sha "${REVIEWED_SHA}" '
map(if .id == $id then
.status = "ADDRESSED" |
.evidence_comment_id = $evidence_id |
.evidence_sha = $sha
else . end)'
)"
persist_resolution_state || {
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: durable formal-review assessment could not be persisted safely."
exit 1
}
persist_resolution_state is the validated, merge-on-retry helper defined in step 2.
Execute it immediately after the transition and verify the just-written body before
continuing.
Do not defer this call until a review wait: a completed current-head review can bypass
the polling path, and the next fresh inventory must still be able to reconstruct the
assessment.
Before accepting either ADDRESSED state at the merge gate, fetch its
evidence_comment_id from the complete conversation inventory and verify the resolver
author plus exact evidence marker. Reset missing or mismatched evidence to UNADDRESSED.
Persist both ledgers in the PR description's ## Comment Ledger section as a JSON object
between exact <!-- resolve-pr-ledgers:v1 and --> lines, using IDs and statuses only.
On resume, reconstruct both variables with step 4's parser; if the marker exists but does
not parse, stop instead of defaulting to empty ledgers. Re-sync the persisted ledgers
against each fresh inventory as shown in step 4. Persist REPAIR_ATTEMPTS_JSON in the
same object so same-root-cause CI failure counts survive waits and resumed sessions.
Run /review against code_review.md and fix every P1 introduced by this PR. For every
fix, run make ci-fast, commit, push, and return to step 2 for a fresh CI and review pass;
never enter the merge gate with an unpushed local fix. If this PR has an ExecPlan, update
its Progress, Decision Log, and Surprises & Discoveries for material review-driven
decisions or failed repair attempts before pushing the fix.
On entry and after any push, record the current headRefOid. Fetch every formal-review
page and filter it to that SHA:
REVIEWED_SHA="$(gh pr view <P> --repo "${REPO}" \
--json headRefOid --jq .headRefOid)"
REVIEW_INVENTORY_OK=0
for REVIEW_DELAY in 0 5 15 45; do
if test "${REVIEW_DELAY}" -gt 0; then
sleep $((REVIEW_DELAY + $(awk 'BEGIN { srand(); print int(rand() * 5) }')))
fi
if ALL_REVIEWS_JSON="$(
gh api --paginate "repos/${REPO}/pulls/<P>/reviews?per_page=100" |
jq -s -e '
if all(.[]; type == "array") then add // []
else error("invalid review page")
end'
)"; then
REVIEW_INVENTORY_OK=1
break
fi
done
test "${REVIEW_INVENTORY_OK}" -eq 1 || {
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: complete formal-review inventory failed after three retries."
exit 1
}
printf '%s' "${ALL_REVIEWS_JSON}" |
jq --arg sha "${REVIEWED_SHA}" \
'map(select(.commit_id == $sha))
| group_by(.user.login // "deleted")
| map(max_by(.submitted_at))
| map({user: (.user.login // "deleted"), state, body})'
Reject PENDING, DISMISSED, and CHANGES_REQUESTED as completion signals. A visible
GraphQL PENDING review whose commit.oid matches the head means a reviewer is still
composing feedback; return to the bounded polling path even when reviewRequests is
empty. APPROVED or COMMENTED means the pass posted, but every finding in its body
still must be addressed. Use the latest same-SHA submitted review per reviewer to decide
whether the current head received a completed pass.
Separately carry change requests across head changes. For each reviewer, inspect all
reviews across all commits. A CHANGES_REQUESTED review remains gating after a fix push
until GitHub marks it DISMISSED or that reviewer posts a later APPROVED review on the
current head. A COMMENTED review does not clear a change request, and a review on an
intermediate or older head does not clear it. This cross-head gate applies even when
reviewDecision is empty.
Compute the outstanding count from the complete REST review inventory:
OUTSTANDING_CHANGES_REQUESTED_COUNT="$(
printf '%s' "${ALL_REVIEWS_JSON}" |
jq --arg sha "${REVIEWED_SHA}" '
def author: (.user.login // "deleted");
. as $reviews |
[$reviews[] |
select(.state == "CHANGES_REQUESTED") as $change |
select([
$reviews[] |
select(author == ($change | author) and
(.submitted_at |
gsub("\\.[0-9]+Z$"; "Z") | fromdateiso8601) >
($change.submitted_at |
gsub("\\.[0-9]+Z$"; "Z") | fromdateiso8601) and
.commit_id == $sha and
.state == "APPROVED")
] | length == 0)
] | length'
)"
A nonempty reviewRequests list means review is pending. Because GitHub hides another
author's draft review, absence of a visible GraphQL PENDING review is not clearance.
Require at least one submitted APPROVED or COMMENTED review whose commit is the
current head and whose author is exactly REVIEW_APP_LOGIN. An arbitrary bot, app,
PR author, or resolver review cannot satisfy completion. Apply this rule even when
reviewRequests is empty. If
no qualifying review posts after three wait cycles, escalate the unfinished current-head
review instead of merging.
After every wait or newly posted current-SHA review, return to step 4 and rebuild the complete thread and comment inventory before considering the merge gate.
Before each wait, report the head SHA and cycle number so the operator can see progress and cancel the sleep with an interrupt:
RESOLVE_PR_POLL_INTERVAL_SECONDS="${RESOLVE_PR_POLL_INTERVAL_SECONDS:-${RESOLVE_PR_DEFAULT_POLL_INTERVAL_SECONDS}}"
[[ "${RESOLVE_PR_POLL_INTERVAL_SECONDS}" =~ ^[1-9][0-9]*$ ]] ||
{ printf 'Invalid review poll interval\n' >&2; exit 1; }
printf 'Waiting for review of %s (cycle %s/3; interrupt to cancel)\n' \
"${REVIEWED_SHA}" "<CYCLE>"
sleep "${RESOLVE_PR_POLL_INTERVAL_SECONDS}"
The default interval is the observed 600-second reviewer latency. The operator may
override it with a positive integer. Before each wait, replace a single full line in the
PR description using this versioned marker:
<!-- resolve-pr-checkpoint:v1 head=<SHA> cycle=<N> timestamp=<ISO-8601> -->. Match only
a line anchored from ^<!-- resolve-pr-checkpoint:v1 through -->$; if none exists,
append one. Never use an unanchored or greedy match, and preserve all other description
content. Use an exact line-oriented update:
CHECKPOINT_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
[[ "${CHECKPOINT_TIMESTAMP}" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$ ]] ||
{ printf 'Unsupported UTC timestamp format\n' >&2; exit 1; }
CHECKPOINT="<!-- resolve-pr-checkpoint:v1 head=${REVIEWED_SHA} cycle=<CYCLE> timestamp=${CHECKPOINT_TIMESTAMP} -->"
persist_resolution_state || {
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: durable state could not be persisted before review wait."
exit 1
}
BODY_UPDATE_OK=0
for BODY_UPDATE_ATTEMPT in 1 2 3; do
BODY="$(gh pr view <P> --repo "${REPO}" --json body --jq .body)" ||
{ sleep "$((BODY_UPDATE_ATTEMPT * 5))"; continue; }
validate_managed_ledger "${BODY}" || {
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: PR description contains a malformed or duplicate managed ledger."
exit 1
}
SESSION_PRESENT=0
printf '%s\n' "${BODY}" |
grep -Fqx -- "${SESSION_LINE}" && SESSION_PRESENT=1
NEXT_BODY="$(
printf '%s\n' "${BODY}" |
CHECKPOINT_FOR_AWK="${CHECKPOINT}" \
SESSION_FOR_AWK="${SESSION_LINE}" \
SESSION_PRESENT_FOR_AWK="${SESSION_PRESENT}" awk '
BEGIN {
checkpoint_replaced = 0
sessions_seen = 0
}
/^## Codex sessions$/ {
sessions_seen = 1
print
if (ENVIRON["SESSION_PRESENT_FOR_AWK"] != "1") {
print ""
print ENVIRON["SESSION_FOR_AWK"]
}
next
}
/^<!-- resolve-pr-checkpoint:v1 .* -->$/ {
if (!checkpoint_replaced) {
print ENVIRON["CHECKPOINT_FOR_AWK"]
checkpoint_replaced = 1
}
next
}
{ print }
END {
if (!sessions_seen) {
print ""
print "## Codex sessions"
print ""
print ENVIRON["SESSION_FOR_AWK"]
}
if (!checkpoint_replaced) print ENVIRON["CHECKPOINT_FOR_AWK"]
}
'
)"
validate_managed_ledger "${NEXT_BODY}" || {
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: combined PR-description update produced an invalid ledger."
exit 1
}
CURRENT_BODY="$(gh pr view <P> --repo "${REPO}" --json body --jq .body)" ||
{ sleep "$((BODY_UPDATE_ATTEMPT * 5))"; continue; }
if test "${CURRENT_BODY}" = "${BODY}" &&
printf '%s\n' "${NEXT_BODY}" |
gh pr edit <P> --repo "${REPO}" --body-file - >/dev/null; then
POST_UPDATE_BODY="$(gh pr view <P> --repo "${REPO}" --json body --jq .body)" ||
{ sleep "$((BODY_UPDATE_ATTEMPT * 5))"; continue; }
if test "${POST_UPDATE_BODY}" = "${NEXT_BODY}"; then
BODY_UPDATE_OK=1
break
fi
fi
sleep "$((BODY_UPDATE_ATTEMPT * 5))"
done
test "${BODY_UPDATE_OK}" -eq 1 || {
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: PR description changed during three combined update attempts."
exit 1
}
Persist and merge the ledger from fresh state first, then apply only the checkpoint and
session-line replacement to the freshly read BODY in the second update. Confirm the
body is unchanged immediately before each edit; if another writer changed it, discard
NEXT_BODY, re-read, and recompute the replacement. Never carry a stale ledger snapshot
into the checkpoint update.
The wait may be taken by ending the turn and resuming after 600 seconds rather than
blocking an agent session. On resume, read the checkpoint, verify the head is unchanged,
rerun all step 1 authentication, permission, worktree, head, and repository-contract
checks, then repeat step 2 before returning to step 4. If the head changed, reset to step
2 and cycle one. The checkpoint timestamp format is fixed to whole-second UTC
YYYY-MM-DDTHH:MM:SSZ; changing it requires updating the anchored parser in the same
commit. A long-lived terminal may use sleep directly.
Wait at most three cycles for the same head SHA, for a default total timeout of 1,800
seconds. If a required or requested reviewer is known to be unavailable, or remains
pending after the third cycle, post an escalation comment naming the head SHA and
reviewer, then stop.
Squash-merge only when every reported check is successful or intentionally skipped on
the head SHA, no gating thread is unresolved, every P1 is fixed, no visible current-SHA
review is PENDING or CHANGES_REQUESTED, no review request is pending, and
reviewDecision is neither CHANGES_REQUESTED nor REVIEW_REQUIRED. A DISMISSED
review does not count as a completed pass but does not itself gate merge. Confirm every
change request on that SHA was dismissed or superseded by a later approving review.
Immediately before merging, rerun all of step 4 and rebuild its complete accumulated
inventory. Derive UNRESOLVED_THREAD_COUNT and
CURRENT_HEAD_PENDING_REVIEW_COUNT from the fresh GraphQL result. Derive
CURRENT_HEAD_COMPLETED_REVIEW_COUNT from that result only for the configured review
app:
UNRESOLVED_THREAD_COUNT="$(
printf '%s' "${GRAPHQL_THREADS_JSON}" |
jq '[.[] | select(.isResolved | not)] | length'
)"
CURRENT_HEAD_PENDING_REVIEW_COUNT="$(
printf '%s' "${GRAPHQL_REVIEWS_JSON}" |
jq --arg sha "${REVIEWED_SHA}" '
[.[] |
select(.state == "PENDING" and
(.commit.oid // "") == $sha)
] | length'
)"
CURRENT_HEAD_COMPLETED_REVIEW_COUNT="$(
printf '%s' "${GRAPHQL_REVIEWS_JSON}" |
jq --arg sha "${REVIEWED_SHA}" \
--arg review_app "${REVIEW_APP_LOGIN}" '
[.[] |
(.author.login // "") as $login |
select($login == $review_app and
.commit.oid == $sha and
(.state == "APPROVED" or .state == "COMMENTED"))
] | length'
)"
Separately refresh the complete paginated REST review inventory and derive
OUTSTANDING_CHANGES_REQUESTED_COUNT with step 8's REST-shaped jq. Do not apply that jq
to GraphQL nodes, whose field names differ, and do not rely on reviewDecision, which can
be empty without branch protection. Then verify all reported checks, the head, review
requests, and review decision. Pin the merge to the reviewed SHA:
CONVERSATION_LEDGER_JSON="$(
jq -cn --argjson ledger "${CONVERSATION_LEDGER_JSON}" \
--argjson comments "${CONVERSATION_COMMENTS_JSON}" \
--arg resolver "${RESOLVER_LOGIN}" \
--arg reviewed_sha "${REVIEWED_SHA}" '
$ledger | map(
if .status == "ADDRESSED" then
. as $entry |
("resolve-pr evidence: comment " + ($entry.id | tostring) +
", head " + ($entry.evidence_sha // "")) as $marker |
if .system_evidence == true then
if [$comments[] |
select((.id | tonumber) == ($entry.id | tonumber) and
.user.login == $resolver and
(.body | startswith("resolve-pr evidence:")))] | length == 1
then . else (.status = "UNADDRESSED" | del(.system_evidence)) end
elif ($entry.evidence_sha // "") != $reviewed_sha then
.status = "UNADDRESSED"
elif [$comments[] |
select(.id == $entry.evidence_comment_id and
.user.login == $resolver and
(.body | contains($marker)))] | length == 1
then . else .status = "UNADDRESSED" end
else . end)'
)"
REVIEW_LEDGER_JSON="$(
jq -cn --argjson ledger "${REVIEW_LEDGER_JSON}" \
--argjson comments "${CONVERSATION_COMMENTS_JSON}" \
--arg resolver "${RESOLVER_LOGIN}" \
--arg reviewed_sha "${REVIEWED_SHA}" '
$ledger | map(
if .status == "ADDRESSED" then
. as $entry |
("resolve-pr evidence: review " + ($entry.id | tostring) +
", head " + ($entry.evidence_sha // "")) as $marker |
if ($entry.evidence_sha // "") != $reviewed_sha then
.status = "UNADDRESSED"
elif [$comments[] |
select(.id == $entry.evidence_comment_id and
.user.login == $resolver and
(.body | contains($marker)))] | length == 1
then . else .status = "UNADDRESSED" end
else . end)'
)"
test "$(printf '%s' "${CONVERSATION_LEDGER_JSON}" | jq 'length')" -eq \
"$(printf '%s' "${CONVERSATION_COMMENTS_JSON}" | jq 'length')"
UNADDRESSED_CONVERSATION_COMMENT_COUNT="$(
printf '%s' "${CONVERSATION_LEDGER_JSON}" |
jq '[.[] | select(.status != "ADDRESSED")] | length'
)"
test "$(printf '%s' "${REVIEW_LEDGER_JSON}" | jq 'length')" -eq \
"$(printf '%s' "${FORMAL_REVIEWS_JSON}" | jq 'length')"
UNADDRESSED_FORMAL_REVIEW_COUNT="$(
printf '%s' "${REVIEW_LEDGER_JSON}" |
jq '[.[] | select(.status != "ADDRESSED")] | length'
)"
test "${UNRESOLVED_THREAD_COUNT}" -eq 0
test "${UNADDRESSED_CONVERSATION_COMMENT_COUNT}" -eq 0
test "${UNADDRESSED_FORMAL_REVIEW_COUNT}" -eq 0
test "${CURRENT_HEAD_PENDING_REVIEW_COUNT}" -eq 0
test "${CURRENT_HEAD_COMPLETED_REVIEW_COUNT}" -gt 0
test "${OUTSTANDING_CHANGES_REQUESTED_COUNT}" -eq 0
CHECKS_STATUS=0
CHECKS_JSON="$(gh pr checks <P> --repo "${REPO}" --json name,bucket)" ||
CHECKS_STATUS=$?
test -n "${CHECKS_JSON}" ||
{ printf 'Empty checks response; merge gate is incomplete\n' >&2; exit 1; }
if ! printf '%s' "${CHECKS_JSON}" |
jq -e 'type == "array" and length > 0' >/dev/null; then
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: checks API returned empty or invalid JSON."
exit 1
fi
CHECK_ACTION="$(
printf '%s' "${CHECKS_JSON}" |
jq -r '
if any(.[]; .bucket == "pending") then "wait"
elif any(.[]; .bucket == "fail" or .bucket == "cancel") then "repair"
elif any(.[]; .bucket != "pass" and .bucket != "skipping") then "escalate"
else "merge"
end'
)"
case "${CHECK_ACTION}" in
wait)
printf 'Checks are pending; return to step 3.\n'
;;
repair)
printf 'Checks failed or were cancelled; return to the repair path in step 3.\n'
;;
escalate)
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: an unknown check bucket blocked the merge gate."
exit 1
;;
merge)
test "${CHECKS_STATUS}" -eq 0
MERGEABLE="UNKNOWN"
# This loop only waits for GitHub to compute mergeability. A merge API
# retry is a new full step-9 pass, as required below.
for MERGEABLE_ATTEMPT in 1 2 3; do
MERGEABLE="$(gh pr view <P> --repo "${REPO}" \
--json mergeable --jq .mergeable)"
test "${MERGEABLE}" = "UNKNOWN" || break
test "${MERGEABLE_ATTEMPT}" -eq 3 || sleep 10
done
case "${MERGEABLE}" in
MERGEABLE)
;;
CONFLICTING)
test -z "$(git status --porcelain)"
test "$(git rev-parse HEAD)" = "${REVIEWED_SHA}"
BASE_SHA="$(gh pr view <P> --repo "${REPO}" \
--json baseRefOid --jq .baseRefOid)"
PR_REMOTE_NAME="$(
git remote -v |
awk -v repo="${REPO}" '
$3 == "(fetch)" {
url = $2
sub(/\.git$/, "", url)
suffix = "/" repo
if (length(url) >= length(suffix) &&
substr(url, length(url) - length(suffix) + 1) == suffix) {
print $1
exit
}
}
'
)"
test -n "${PR_REMOTE_NAME}" || {
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: no authenticated repository remote was available for conflict diagnosis."
exit 1
}
git fetch "${PR_REMOTE_NAME}" "${BASE_SHA}"
CONFLICT_FILES="$(
git merge-tree --write-tree --name-only \
HEAD "${BASE_SHA}" 2>&1 || true
)"
printf 'Escalation: PR is conflicting. Merge-tree output: %s\n' \
"${CONFLICT_FILES}" |
gh pr comment <P> --repo "${REPO}" --body-file -
exit 1
;;
*)
gh pr comment <P> --repo "${REPO}" \
--body "Escalation: mergeability remained ${MERGEABLE} after three checks."
exit 1
;;
esac
test "$(gh pr view <P> --repo "${REPO}" \
--json headRefOid --jq .headRefOid)" = "${REVIEWED_SHA}"
test "$(gh pr view <P> --repo "${REPO}" \
--json reviewRequests --jq '.reviewRequests | length')" -eq 0
REVIEW_DECISION="$(gh pr view <P> --repo "${REPO}" \
--json reviewDecision --jq .reviewDecision)"
test "${REVIEW_DECISION}" != "CHANGES_REQUESTED"
test "${REVIEW_DECISION}" != "REVIEW_REQUIRED"
GH_PR_MERGE_HELP="$(gh pr merge --help)"
grep -q -- '--match-head-commit' <<<"${GH_PR_MERGE_HELP}"
gh pr merge <P> --repo "${REPO}" --squash \
--match-head-commit "${REVIEWED_SHA}"
;;
esac
gh pr checks exits nonzero for pending and failing checks, so capture its status before
classifying the complete JSON response; an empty or invalid response is an API failure,
not a clean result. Every reported check is intentionally gating. Accept pass and
skipping; if any bucket is pending, return to step 3; on fail or cancel, inspect
and fix the check; escalate an unknown bucket rather than guessing. If mergeable is
UNKNOWN, use the dedicated three-attempt, 10-second polling loop above. If it is
CONFLICTING, report the conflicting files in an escalation comment and stop. Merge
only when it is MERGEABLE. Retry only a transient merge API failure, at most three
attempts with a 10-second delay. Before each retry, return to the start of step 9 and
rerun the complete gate, including the fresh step 4 inventory and unchanged-head
assertion; stop immediately for a non-transient policy or authorization failure. After
the third transient failure, post
Escalation: squash merge failed three times for <REVIEWED_SHA>. and stop.
Do not put gh pr merge in a tight shell loop. A transient failure starts a new step 9
pass: after the 10-second delay, rederive REVIEWED_SHA with gh pr view; if it differs
from the failed attempt's SHA, return to step 2. Otherwise rebuild both complete
inventories and rerun every gate command above before issuing the next merge attempt.
Comment on the PR with the evidence and the decision a human must make, then stop, when:
gh cannot resolve PR state after retries.REPO explicitly on every repository-scoped gh call. The global
gh api user and gh api rate_limit probes are the only exceptions. For
gh api graphql, bind its OWNER and NAME variables explicitly as shown above.