code-review

name	code-review
description	Systematically retrieve and address PR code review comments using make pr-comments. Use when handling code review feedback or addressing PR comments.

Code Review Workflow Skill

Context (Input)

• PR has unresolved code review comments
• Need systematic approach to address feedback
• Ready to implement reviewer suggestions
• Need to maintain quality standards during review implementation

Task (Function)

Systematically retrieve, categorize, and address all PR code review comments while maintaining quality standards and PR readiness.

Success Criteria:

• Direct GitHub GraphQL review-thread query shows 0 unresolved review comments, and PR_COMMENT_EVIDENCE records SNAPSHOT_STARTED_AT=<auto-captured ISO time>, SNAPSHOT_CAPTURED_BY=code-review-skill, PR_HEAD=<sha>, plus every review-thread, top-level PR issue, and review body comment from that snapshot as COMMENT_META|url|updatedAt|body_sha256 and COMMENT|url|commit|sha, COMMENT|url|reply|url, or COMMENT|url|decline|url; reply/decline evidence comments must be posted by the PR author or a login in PR_COMMENT_TRUSTED_EVIDENCE_ACTORS and include structured EVIDENCE_SOURCE, EVIDENCE_ACTION, and decline EVIDENCE_REASON; non-evidence comments created or edited after the snapshot block completion until the snapshot and evidence are restarted, except an otherwise qualifying approval review on pushed HEAD whose body is empty or exactly FINAL_APPROVAL_NO_ACTION: true
• make ci shows "✅ CI checks successfully passed!"
• Final make ai-review-loop runs after make ci and reports PASS on the same commit; if it applies fixes, repeat make ci and make ai-review-loop until both pass without new changes
• Local HEAD is pushed and matches gh pr view <number> --repo "$PR_REPO" --json headRefOid
• Commit-scoped status/check rollup for local HEAD is queried from the base PR repository, is non-empty, non-required contexts have only allowed terminal states (SUCCESS, SKIPPED, or NEUTRAL), every trusted check name/type/source in the trusted base .github/required-pr-checks.txt or externally validated bootstrap manifest and every live base-branch protection required status/check is present with state SUCCESS on that pushed head, source-less branch-protection contexts resolve through trusted manifest type/source mappings, and GitHub Actions check URLs point at the base PR repository
• Final direct GitHub GraphQL review-thread query after the pushed-head verification still shows 0 unresolved review comments
• gh pr view <number> --repo "$PR_REPO" --json state,mergeStateStatus,mergeable,reviewDecision,isDraft,reviewRequests shows the PR is open, not draft, not conflicting, reviewDecision is APPROVED, reviewRequests is empty, and a direct review query shows an APPROVED review on the pushed HEAD submitted after the latest addressed comment evidence by a non-author reviewer with OWNER, MEMBER, or COLLABORATOR association

Workflow Overview

AI Review Loop → PR Comments → Categorize → Apply by Priority → Verify → Run CI → Final AI Review Loop → Push → GitHub Readiness → Done

Quick Start

set -euo pipefail
command -v jq >/dev/null || { echo "jq is required" >&2; exit 1; }
command -v rg >/dev/null || { echo "rg is required" >&2; exit 1; }
command -v unzip >/dev/null || { echo "unzip is required" >&2; exit 1; }
command -v sha256sum >/dev/null || { echo "sha256sum is required" >&2; exit 1; }
command -v base64 >/dev/null || { echo "base64 is required" >&2; exit 1; }

GATE_DEFINITION_CORE_FILE_PATTERN='^(AGENTS\.md|Makefile|\.claude/skills/.*|\.agents/skills/.*|deptrac\.yaml|composer\.(json|lock)|phpunit.*\.xml\.dist|psalm\.xml(\.dist)?|phpstan\.(neon|neon\.dist)|phpmd.*\.xml(\.dist)?|phpinsights.*\.php|infection\.(json|json5)(\.dist)?|phpcs\.xml(\.dist)?|\.php-cs-fixer\.dist\.php|docker-compose.*\.ya?ml|Dockerfile.*|scripts/.*|\.github/workflows/.*|\.github/actions/.*|\.github/linters/.*|\.github/required-pr-checks\.txt|\.prettierrc(\..*)?|\.prettierignore|(.*/)?prettier\.config\.(js|mjs|cjs|ts|json|ya?ml)|(.*/)?\.markdownlint(\..*)?|(.*/)?markdownlint\.config\.(js|mjs|cjs|json|ya?ml)|(.*/)?\.yamllint(\..*)?|(\.codecov|codecov)\.ya?ml|\.coderabbit\.ya?ml|\.qlty/.*|(\.qlty|qlty)\.toml|\.snyk|(\.spectral|spectral)\.ya?ml|(.*/)?spectral\.config\.(js|mjs|cjs|ts|json|ya?ml)|(.*/)?eslint\.config\.(js|mjs|cjs|ts)|(.*/)?\.eslintrc(\..*)?|(.*/)?package(-lock)?\.json|(.*/)?pnpm-lock\.yaml|(.*/)?yarn\.lock|(.*/)?\.graphqlrc(\..*)?|(.*/)?graphql\.config\.(js|mjs|cjs|ts|json|ya?ml)|(.*/)?graphql-inspector(\.config)?\.(js|mjs|cjs|ts|json|ya?ml)|(.*/)?(\.openapi-diff|openapi-diff)(\.config)?\.(js|mjs|cjs|ts|json|ya?ml))$'
GATE_DEFINITION_VALIDATION_SUPPORT_FILE_PATTERN='^(docs/onboarding\.md|tests/CLI/bats/make_ai_review_loop_tests\.bats|specs/autonomous/[0-9]{8}-[0-9]{6}-(ai-review-loop|bmad-fr-nfr-review-gate|bmad-fr-nfr-reviewer-system-design-patterns|ci-gate|gate-definition|required-pr-checks-gate|review-loop)/(architecture|epics|implementation-readiness|manual-evidence|prd|product-brief-distillate|product-brief|research|run-summary|skill-sweep)\.md)$'
GATE_DEFINITION_FILE_PATTERN=
GATE_DEFINITION_CHANGES_PRESENT=
GATE_DEFINITION_EXTERNAL_VALIDATION_PASSED=
PR_COMMENT_TIMELINE=
VALIDATED_COMMENT_EVIDENCE_URLS=

() {
  REVIEW_COMMENT_SNAPSHOT_STARTED_AT=
   REVIEW_COMMENT_SNAPSHOT_STARTED_AT
  PR_COMMENT_TIMELINE=
}

() {
  : 
     | rg -q 
  : 
   -r 
  rg -q  
  rg -q  
}

() {
   -u -d  +%s
}

() {
     |  --decode |  | awk 
}

() {
   owner= repo= comparison= query thread_query page_json page_items has_next cursor thread_refs thread_id thread_cursor thread_has_next thread_json
  query=
  cursor=
   :; 
     [ -n  ]; 
      page_json=
    
      page_json=
    
    page_items=beforeafter\(.url)|\(.createdAt)|\(.updatedAt)|\((.bodyText // "") | @base64)"')"
    printf '%s\n' ""
    thread_refs="$(printf '%s\n' "" | jq -r '.data.repository.pullRequest.reviewThreads.nodes[] | select(.comments.pageInfo.hasNextPage == true) | "\(.id)|\(.comments.pageInfo.endCursor)"')"
    while IFS='|' read -r thread_id thread_cursor; do
      [ -n "" ] || continue
      thread_query='query(:ID!,:String){node(id:){... on PullRequestReviewThread{comments(first:,after:){pageInfo{hasNextPage endCursor} nodes{url createdAt updatedAt bodyText}}}}}'
      while :; do
        thread_json="$(gh api graphql -f threadId="" -f cursor="" -f query="")"
        page_items="$(printf '%s\n' "" | jq -r --arg snapshot "" --arg comparison "" 'def effectiveAt: if ((.updatedAt // .createdAt) > .createdAt) then (.updatedAt // .createdAt) else .createdAt end; .data.node.comments.nodes[] | select((if  == "before" then effectiveAt <=  elif  == "after" then effectiveAt >  else true end) and ((.bodyText // "") | length > )) | %s\n%s\n.data.node.comments.pageInfo.hasNextPage%s\n.data.node.comments.pageInfo.endCursor%s\n.data.repository.pullRequest.reviewThreads.pageInfo.hasNextPage%s\n.data.repository.pullRequest.reviewThreads.pageInfo.endCursorquery(:String!,:String!,:Int!,:String){repository(owner:,name:){pullRequest(number:){comments(first:100,after:){pageInfo{hasNextPage endCursor} nodes{url createdAt updatedAt bodyText}}}}}%s\n.data.repository.pullRequest.comments.nodes[] | ((.bodyText // "") | length > ) | "\(.url)|\(.createdAt)|\(.updatedAt)|\((.bodyText // "") | @base64)"')"
    PR_COMMENT_TIMELINE=""$'\n'""
    has_next="$(printf '%s\n' "" | jq -r '.data.repository.pullRequest.comments.pageInfo.hasNextPage')"
    [ "" = "true" ] || break
    cursor="$(printf '%s\n' "" | jq -r '.data.repository.pullRequest.comments.pageInfo.endCursor')"
    test -n "" && test "" != "null"
  done

  query='query(:String!,:String!,:Int!,:String){repository(owner:,name:){pullRequest(number:){reviews(first:,after:){pageInfo{hasNextPage endCursor} nodes{url createdAt updatedAt bodyText}}}}}'
  cursor=''
  while :; do
    if [ -n "" ]; then
      page_json="$(gh api graphql -f owner="" -f repo="" -F pr="" -f cursor="" -f query="")"
    else
      page_json="$(gh api graphql -f owner="" -f repo="" -F pr="" -f query="")"
    fi
    page_items="$(printf '%s\n' "" | jq -r '.data.repository.pullRequest.reviews.nodes[] | select((.bodyText // "") | length > ) | "\(.url)|\(.createdAt)|\(.updatedAt)|\((.bodyText // "") | @base64)"')"
    PR_COMMENT_TIMELINE=""$'\n'""
    has_next="$(printf '%s\n' "" | jq -r '.data.repository.pullRequest.reviews.pageInfo.hasNextPage')"
    [ "" = "true" ] || break
    cursor="$(printf '%s\n' "" | jq -r '.data.repository.pullRequest.reviews.pageInfo.endCursor')"
    test -n "" && test "" != "null"
  done

  PR_COMMENT_TIMELINE=""$'\n'"$(review_thread_comment_items "" "" all)"
  PR_COMMENT_TIMELINE="$(printf '%s\n' "" | sed '/^[[:space:]]*$/d' | sort -u)"
}

comment_time_for_url() {
  load_pr_comment_timeline
  printf '%s\n' "" | awk -F'|' -v url="" ' == url { print ( >  ?  : ); exit }'
}

assert_pr_commit_evidence() {
  local source_url="" source_time="" commit="" commit_time
  git rev-parse --verify "^{commit}" >/dev/null
  git merge-base --is-ancestor "" ""
  ! git merge-base --is-ancestor "" ""
  commit_time="$(git show -s --format=%cI "")"
  test "$(iso_time_epoch "")" -gt "$(iso_time_epoch "")"
  git log - --format=%B "" | rg -Fq ""
}

comment_json_for_url() {
  local url="" comment_id
  case "" in
    *"#issuecomment-"*)
      comment_id=""
      gh api "repos//issues/comments/"
      ;;
    *"#discussion_r"*)
      comment_id=""
      gh api "repos//pulls/comments/"
      ;;
    *)
      return 
      ;;
  esac
}

comment_body_for_url() {
  comment_json_for_url "" | jq -r .body
}

comment_author_for_url() {
  comment_json_for_url "" | jq -r .user.login
}

assert_evidence_comment_actor() {
  local reply_url="" pr_author reply_author trusted_actors
  pr_author="$(gh pr view "" --repo "" --json author --jq .author.login)"
  reply_author="$(comment_author_for_url "")"
  if [ "" = "" ]; then
    return 
  fi
  : ""
  trusted_actors=",,"
  printf '%s\n' "" | rg -Fq ",,"
}

assert_pr_reply_evidence() {
  local source_url="" source_time="" reply_url="" reply_time reply_body
  case "" in
    "https://github.com//pull/"#*) ;;
    *) return  ;;
  esac
  [ "" != "" ]
  reply_time="$(comment_time_for_url "")"
  test -n "" && test -n ""
  test "$(iso_time_epoch "")" -gt "$(iso_time_epoch "")"
  assert_evidence_comment_actor ""
  reply_body="$(comment_body_for_url "")"
  printf '%s\n' "" | rg -Fq "EVIDENCE_SOURCE: "
  printf '%s\n' "" | rg -iq '^EVIDENCE_ACTION:[[:space:]]*(addressed|resolved|fixed|implemented|updated|changed|applied)[[:space:]]*$'
}

assert_pr_decline_evidence() {
  local source_url="" source_time="" reply_url="" reply_time reply_body
  case "" in
    "https://github.com//pull/"#*) ;;
    *) return  ;;
  esac
  [ "" != "" ]
  reply_time="$(comment_time_for_url "")"
  test -n "" && test -n ""
  test "$(iso_time_epoch "")" -gt "$(iso_time_epoch "")"
  assert_evidence_comment_actor ""
  reply_body="$(comment_body_for_url "")"
  printf '%s\n' "" | rg -Fq "EVIDENCE_SOURCE: "
  printf '%s\n' "" | rg -iq '^EVIDENCE_ACTION:[[:space:]]*(declined|stale|duplicate|not applicable|not needed|won.t fix|will not fix)[[:space:]]*$'
  printf '%s\n' "" | rg -iq '^EVIDENCE_REASON:[[:space:]].+'
}

latest_addressed_evidence_time() {
  local entry_type source_url entry_action entry_evidence source_time evidence_time source_epoch evidence_epoch latest
  latest=
  [ -r "" ] || return 
  while IFS='|' read -r entry_type source_url entry_action entry_evidence; do
    [ "" = "COMMENT" ] || continue
    source_time="$(comment_time_for_url "")"
    if [ -n "" ]; then
      source_epoch="$(iso_time_epoch "")"
      if [ "" -gt "" ]; then
        latest=""
      fi
    fi
    evidence_time=''
    case "" in
      commit) evidence_time="$(git show -s --format=%cI "" >/dev/null || true)" ;;
      reply|decline) evidence_time="$(comment_time_for_url "")" ;;
    esac
    if [ -n "" ]; then
      evidence_epoch="$(iso_time_epoch "")"
      if [ "" -gt "" ]; then
        latest=""
      fi
    fi
  done < ""
  printf '%s\n' ""
}

assert_comment_evidence_items() {
  local evidence_items="" source_url source_time source_updated_at source_effective_time source_body_b64 source_body_hash meta_line meta_type meta_url meta_updated_at meta_body_hash evidence_line entry_type entry_url entry_action entry_evidence missing_count
  assert_review_comment_snapshot_valid
  : ""
  test -r ""
  rg -Fqx "PR_HEAD=" ""
  evidence_items="$(printf '%s\n' "" | sed '/^[[:space:]]*$/d' | sort -u)"
  [ -n "" ] || return 
  missing_count=
  while IFS='|' read -r source_url source_time source_updated_at source_body_b64; do
    source_effective_time=""
    if [ -n "" ] && [ "" \> "" ]; then
      source_effective_time=""
    fi
    source_body_hash="$(body_hash_from_b64 "")"
    meta_line="$(awk -F'|' -v url="" ' == "COMMENT_META" &&  == url { print; found = ; exit } END { if (!found) exit  }' "" || true)"
    if [ -z "" ]; then
      printf 'Missing comment metadata evidence: %s\n' "" >&
      missing_count=$((missing_count + ))
      
    
    IFS=  -r meta_type meta_url meta_updated_at meta_body_hash <<
     [  !=  ] || [  !=  ] || [  !=  ] || [  !=  ]; 
         >&2
      missing_count=$((missing_count + ))
      
    
    evidence_line=
     [ -z  ]; 
         >&2
      missing_count=$((missing_count + ))
      
    
    IFS=  -r entry_type entry_url entry_action entry_evidence <<
     [  !=  ] || [  !=  ] || [ -z  ]; 
         >&2
      missing_count=$((missing_count + ))
      
    
      
      commit) assert_pr_commit_evidence    || missing_count=$((missing_count + )) ;;
      reply)
         assert_pr_reply_evidence   ; 
          VALIDATED_COMMENT_EVIDENCE_URLS=$
        
          missing_count=$((missing_count + ))
        
        ;;
      decline)
         assert_pr_decline_evidence   ; 
          VALIDATED_COMMENT_EVIDENCE_URLS=$
        
          missing_count=$((missing_count + ))
        
        ;;
      *) missing_count=$((missing_count + )) ;;
    
   <<< 
    -eq 0
}

() {
   owner repo query page_json page_count total_count has_next cursor
  owner=
  repo=
  query=
  total_count=0
  cursor=
   :; 
     [ -n  ]; 
      page_json=
    
      page_json=
    
    page_count=
    total_count=$((total_count + page_count))
    has_next=
    [  =  ] || 
    cursor=
     -n  &&   != 
  
    -eq 0
}

() {
   owner= repo= comparison= query page_json page_items has_next cursor
  query=
  cursor=
   :; 
     [ -n  ]; 
      page_json=
    
      page_json=
    
    page_items=beforeafter\(.url)|\(.createdAt)|\(.updatedAt)|\((.bodyText // "") | @base64)"')"
    printf '%s\n' ""
    has_next="$(printf '%s\n' "" | jq -r '.data.repository.pullRequest.comments.pageInfo.hasNextPage')"
    [ "" = "true" ] || break
    cursor="$(printf '%s\n' "" | jq -r '.data.repository.pullRequest.comments.pageInfo.endCursor')"
    test -n "" && test "" != "null"
  done

  query='query(:String!,:String!,:Int!,:String){repository(owner:,name:){pullRequest(number:){reviews(first:,after:){pageInfo{hasNextPage endCursor} nodes{url createdAt updatedAt bodyText}}}}}'
  cursor=''
  while :; do
    if [ -n "" ]; then
      page_json="$(gh api graphql -f owner="" -f repo="" -F pr="" -f cursor="" -f query="")"
    else
      page_json="$(gh api graphql -f owner="" -f repo="" -F pr="" -f query="")"
    fi
    page_items="$(printf '%s\n' "" | jq -r --arg snapshot "" --arg comparison "" 'def effectiveAt: if ((.updatedAt // .createdAt) > .createdAt) then (.updatedAt // .createdAt) else .createdAt end; .data.repository.pullRequest.reviews.nodes[] | select((if  == "before" then effectiveAt <=  elif  == "after" then effectiveAt >  else true end) and ((.bodyText // "") | length > )) | %s\n%s\n.data.repository.pullRequest.reviews.pageInfo.hasNextPage%s\n.data.repository.pullRequest.reviews.pageInfo.endCursor/^[[:space:]]*$/d| ==  {  }SNAPSHOT_STARTED_AT=%s\nSNAPSHOT_CAPTURED_BY=code-review-skill\nPR_HEAD=%s\n|COMMENT_META|%s|%s|%s\n%s\nquery(:String!,:String!,:Int!,:String){repository(owner:,name:){pullRequest(number:){comments(first:100,after:){pageInfo{hasNextPage endCursor} nodes{url createdAt updatedAt bodyText}}}}}%s\ndef effectiveAt:  ((.updatedAt // .createdAt) > .createdAt) then (.updatedAt // .createdAt) else .createdAt end; .data.repository.pullRequest.comments.nodes[] | select(effectiveAt <=  and ((.bodyText // "") | length > )) | \n%s\n.data.repository.pullRequest.comments.pageInfo.hasNextPage%s\n.data.repository.pullRequest.comments.pageInfo.endCursorquery(:String!,:String!,:Int!,:String){repository(owner:,name:){pullRequest(number:){reviews(first:100,after:){pageInfo{hasNextPage endCursor} nodes{url createdAt updatedAt bodyText}}}}}%s\ndef effectiveAt:  ((.updatedAt // .createdAt) > .createdAt) then (.updatedAt // .createdAt) else .createdAt end; .data.repository.pullRequest.reviews.nodes[] | select(effectiveAt <=  and ((.bodyText // "") | length > )) | \n%s\n.data.repository.pullRequest.reviews.pageInfo.hasNextPage%s\n.data.repository.pullRequest.reviews.pageInfo.endCursorquery(:String!,:String!,:Int!,:String){repository(owner:,name:){pullRequest(number:){reviews(first:100,after:){pageInfo{hasNextPage endCursor} nodes{url state submittedAt author{login} authorAssociation commit{oid}}}}}}}%s\n.data.repository.pullRequest.reviews.nodes[] | (.state ==  and .commit.oid ==  and (.author.login // ) !=  and (.authorAssociation | IN(, , )) and ( == 0 or (.submittedAt | fromdateiso8601) > )) | .url%s\n%s\n.data.repository.pullRequest.reviews.pageInfo.hasNextPage%s\n.data.repository.pullRequest.reviews.pageInfo.endCursorquery(:String!,:String!,:Int!,:String){repository(owner:,name:){pullRequest(number:){reviews(first:100,after:){pageInfo{hasNextPage endCursor} nodes{url state submittedAt author{login} authorAssociation commit{oid} bodyText}}}}}}}%s\n.data.repository.pullRequest.reviews.nodes[] | (.state ==  and .commit.oid ==  and (.author.login // ) !=  and (.authorAssociation | IN(, , )) and ( == 0 or (.submittedAt | fromdateiso8601) > ) and (((.bodyText // "") | length) ==  or ((.bodyText // "") | gsub("\\r"; "") | gsub("^[[:space:]]+|[[:space:]]+$"; "") | test("^FINAL_APPROVAL_NO_ACTION:[[:space:]]*true$"; "i")))) | .url%s\n%s\n.data.repository.pullRequest.reviews.pageInfo.hasNextPage%s\n.data.repository.pullRequest.reviews.pageInfo.endCursorquery(:String!,:String!,:Int!,:String){repository(owner:,name:){pullRequest(number:){comments(first:100,after:){pageInfo{hasNextPage endCursor} nodes{url createdAt updatedAt bodyText}}}}}%s\ndef effectiveAt:  ((.updatedAt // .createdAt) > .createdAt) then (.updatedAt // .createdAt) else .createdAt end; .data.repository.pullRequest.comments.nodes[] | select(effectiveAt >  and ((.bodyText // "") | length > )) | \n%s\n.data.repository.pullRequest.comments.pageInfo.hasNextPage%s\n.data.repository.pullRequest.comments.pageInfo.endCursorquery(:String!,:String!,:Int!,:String){repository(owner:,name:){pullRequest(number:){reviews(first:100,after:){pageInfo{hasNextPage endCursor} nodes{url createdAt updatedAt bodyText}}}}}%s\ndef effectiveAt:  ((.updatedAt // .createdAt) > .createdAt) then (.updatedAt // .createdAt) else .createdAt end; .data.repository.pullRequest.reviews.nodes[] | select(effectiveAt >  and ((.bodyText // "") | length > )) | \n%s\n.data.repository.pullRequest.reviews.pageInfo.hasNextPage%s\n.data.repository.pullRequest.reviews.pageInfo.endCursor\n%s\n/^[[:space:]]*$/d|%s\nNew PR comment after snapshot requires restarting comment evidence: %s\n%s\n/^[[:space:]]*$/d%s\n^\+[^+](^|/)(.*baseline.*|psalm\.xml(\.dist)?|phpstan\.(neon|neon\.dist)|phpmd.*\.xml(\.dist)?|phpinsights.*\.php|infection\.(json|json5)(\.dist)?|phpcs\.xml(\.dist)?|\.php-cs-fixer\.dist\.php)$%s\n%s\n@SuppressWarnings|@psalm-suppress|@phpstan-ignore|phpstan-ignore|phpcs:(ignore|)|@infection-ignore|@codeCoverageIgnore|@phpinsights-ignore|@codingStandardsIgnore|codingStandardsIgnore%s\n%s\n%s\n%s\n%s\ns/^VALIDATION_MODE=//ps/^IMMUTABLE_RUN_URL=//p%s\ns#^https://github.com/([^/]+/[^/]+)/actions/runs/[0-9]+\1#%s\n%s\n.status ==  and .conclusion ==  and .repository.full_name ==  and ((.path // "") | test("^\\.github/workflows/"))%s\n%s\n%s\n%s\n%s\n%s\n| == repo &&  == path {  ;  }%s\n.artifacts[] | (.name ==  and .expired == ) | .[:space:]/^[[:space:]]*$/dquery(:String!,:String!,:GitObjectID!,:String){repository(owner:,name:){object(oid:){... on Commit{statusCheckRollup{contexts(first:100,after:){pageInfo{hasNextPage endCursor} nodes{__typename ... on CheckRun{name conclusion status detailsUrl checkSuite{app{slug}}} ... on StatusContext{context state targetUrl creator{login}}}}}}}}}[]%s\n[.data.repository.object.statusCheckRollup.contexts.nodes[] |  .__typename ==   {: , name: .name, state: (.conclusion // .status), : (.checkSuite.app.slug // ), url: (.detailsUrl // )}  {: , name: .context, state: .state, : (.creator.login // ), url: (.targetUrl // )} end] + %s\n.data.repository.object.statusCheckRollup.contexts.pageInfo.hasNextPage%s\n.data.repository.object.statusCheckRollup.contexts.pageInfo.endCursor%s\nlength > 0 and all(.[]; .state | IN(, , ))%s\nall(.[];  . ==  and . ==   ((.url // "") | startswith( + "actions/runs/"))   end)|%s\n[.[] | (. ==  and .name ==  and . == )] as  | ( | length) > 0 and all([]; .state == )query(:String!,:String!,:String!){repository(owner:,name:){ref(qualifiedName:){branchProtectionRule{requiredStatusCheckContexts requiredStatusChecks{context app{slug}}}}}}%s\n
        (.data.repository.ref.branchProtectionRule // {}) as  |
        ((.requiredStatusCheckContexts // [])[] | "legacy|" + .),
        ((.requiredStatusChecks // [])[] | "app|" + .context + "|" + (.app.slug // ""))
      |%s\n[.[] | (.name ==  and . == )] as  | ( | length) > 0 and all([]; .state == )%s\n| !~ /^[[:space:]]*(#|$)/ && NF == 3 &&  == name {  }|%s\n[.[] | (. ==  and .name ==  and . == )] as  | ( | length) > 0 and all([]; .state == )%s\n
      .headRefOid ==  and
      .baseRefOid ==  and
      .baseRefName ==  and
      .state ==  and
      .isDraft ==  and
      .mergeable ==  and
      (.mergeStateStatus | IN(, )) and
      .reviewDecision ==  and
      ([.reviewRequests[]?] | length) == 0
    %s\n%s\n/^[[:space:]]*$/d%s\n%s\n/^[[:space:]]*$/d%s\n%s\n%s\n%s\n%s\n%s\n/^[[:space:]]*$/dSNAPSHOT_STARTED_AT=%s\nSNAPSHOT_CAPTURED_BY=code-review-skill\n%s\n%s\n/^[[:space:]]*$/d%s\n%s\n/^[[:space:]]*$/d%s\n%s\n%s\n
  .headRefOid ==  and
  .baseRefOid ==  and
  .baseRefName ==  and
  .state ==  and
  .isDraft ==  and
  .mergeable ==  and
  (.mergeStateStatus | IN(, )) and
  .reviewDecision ==  and
  ([.reviewRequests[]?] | length) == 0
%s\n
  .headRefOid ==  and
  .baseRefOid ==  and
  .baseRefName ==  and
  .state ==  and
  .isDraft ==  and
  .mergeable ==  and
  (.mergeStateStatus | IN(, )) and
  .reviewDecision ==  and
  ([.reviewRequests[]?] | length) == 0

Execution Steps

Step 0: Run Autonomous AI Review Loop

Before addressing PR comments manually, fetch the PR base and run the autonomous review loop against that base:

set -euo pipefail

: "${PR:?Set PR to the pull request number}"
case "$PR" in
  ''|*[!0-9]*) echo "PR must be numeric" >&2; exit 1 ;;
esac
: "${PR_REPO:?Set PR_REPO=owner/repo for the base PR repository}"
PR_META="$(gh pr view "$PR" --repo "$PR_REPO" --json baseRefName,baseRefOid)"
BASE_REF="$(printf '%s\n' "$PR_META" | jq -r .baseRefName)"
BASE_OID="$(printf '%s\n' "$PR_META" | jq -r .baseRefOid)"
TRUSTED_BASE_REF="refs/remotes/pr-base/$PR"
git fetch "[e-mail]:${PR_REPO}.git" "$BASE_REF:$TRUSTED_BASE_REF"
test "$(git rev-parse "$TRUSTED_BASE_REF")" = "$BASE_OID"
AI_REVIEW_OUTPUT="$(AI_REVIEW_BASE="$TRUSTED_BASE_REF" make ai-review-loop 2>&1)"
printf '%s\n' "$AI_REVIEW_OUTPUT"
AI_REVIEW_LAST_LINE="$(printf '%s\n'  | sed '/^[[:space:]]*$/d' | tail -n 1)"
  = 

This executes scripts/ai-review-loop.sh, which:

1. Runs an AI review agent against the current diff (base: AI_REVIEW_BASE, or main by default)
2. If issues are found (STATUS: FAIL), runs a fix agent to auto-remediate
3. Verifies fixes with make ci
4. Repeats up to AI_REVIEW_MAX_ITER times (default: 3)

The reviewer prompt in scripts/ai-review-prompts/review.md checks both FR/NFR coverage and code health for supported local review agents. It explicitly includes system design tradeoffs, appropriate design pattern use, code smells, SOLID/DRY/KISS, DDD/CQRS, Hexagonal Architecture, and repository rules. Review failures must stay concrete and scoped to changed code or directly affected behavior.

Codex consumes the reviewer prompt directly. Claude keeps its built-in /review invocation and receives the same repository review policy through the loop's appended system prompt.

Configuration (all overridable via environment):

Variable	Default	Description
AI_REVIEW_AGENTS	codex	Agent(s) to use (codex, claude)
AI_REVIEW_BASE	main	Base branch for diff comparison
AI_REVIEW_MAX_ITER	3	Max review/fix iterations (0=∞)
AI_REVIEW_VERIFY_CMD	make ci	Verification command after each fix
AI_REVIEW_LOG_DIR	var/ai-review	Directory for review/fix logs

Examples:

# Use Claude instead of Codex
AI_REVIEW_BASE="$TRUSTED_BASE_REF" AI_REVIEW_AGENTS=claude make ai-review-loop

# Limit to 1 iteration, custom base branch
AI_REVIEW_BASE=develop AI_REVIEW_MAX_ITER=1 make ai-review-loop

# Run both agents
AI_REVIEW_BASE="$TRUSTED_BASE_REF" AI_REVIEW_AGENTS=codex,claude make ai-review-loop

Prompt templates: scripts/ai-review-prompts/review.md (reviewer) and scripts/ai-review-prompts/fix.md (fixer).

Step 1: Get PR Comments

make pr-comments              # Auto-detect from current branch
make pr-comments PR=62       # Specify PR number
make pr-comments FORMAT=json  # JSON output

Output: All unresolved comments with file/line, author, timestamp, URL

Step 2: Categorize Comments

Type	Identifier	Priority	Action
Committable Suggestion	Code block, "```suggestion"	Highest	Apply immediately, commit separately
LLM Prompt	"🤖 Prompt for AI Agents"	High	Execute prompt, implement changes
Architecture Concern	Class naming, file location	High	Invoke appropriate skill
Question	Ends with "?"	Medium	Answer inline or via code change
General Feedback	Discussion, recommendation	Low	Consider and improve
Resolved/Stale	Outdated or already fixed	None	Do not change code; record reason

Step 3: Verify Architecture & Organization

For code changes (suggestions, prompts, new files), invoke verification skills:

Concern Type	Skill to Invoke
Class placement/naming	code-organization
DDD patterns	implementing-ddd-architecture
Layer violations	deptrac-fixer (if deptrac fails)

Quick verification: Run make phpcsfixer && make psalm && make deptrac && make unit-tests

Step 4: Apply Changes Systematically

For Committable Suggestions

1. Verify the suggestion still applies to current code

2. Apply the suggestion exactly when it is still valid and compatible with repository rules

3. If the suggestion is stale, implement the current equivalent fix or record why no change is needed

4. Commit with reference:

   git commit -m "Apply review suggestion: [brief description]
   
   Ref: [comment URL]"
   

For LLM Prompts

1. Copy prompt from comment
2. Verify every finding against current code before changing files
3. Execute still-valid instructions
4. Skip stale, duplicate, or contradicted findings with a brief reason
5. Verify output meets requirements
6. Commit with reference

For Architecture/Organization Concerns

1. Invoke appropriate skill (code-organization or implementing-ddd-architecture)
2. Implement recommended changes
3. Verify: make phpcsfixer && make psalm && make deptrac && make unit-tests
4. Commit with reference

For Questions

1. Determine if code change or reply needed
2. If code: implement + commit
3. If reply: respond on GitHub

For General Feedback

1. Evaluate suggestion merit
2. Implement if beneficial
3. Document reasoning if declined

Step 5: Verify All Addressed

set -euo pipefail

: "${PR:?Set PR to the pull request number}"
case "$PR" in
  ''|*[!0-9]*) echo "PR must be numeric" >&2; exit 1 ;;
esac
: "${PR_REPO:?Set PR_REPO=owner/repo for the base PR repository}"
owner="${PR_REPO%%/*}"
repo="${PR_REPO#*/}"
query='query($owner:String!,$repo:String!,$pr:Int!,$cursor:String){repository(owner:$owner,name:$repo){pullRequest(number:$pr){reviewThreads(first:100,after:$cursor){pageInfo{hasNextPage endCursor} nodes{isResolved comments(first:1){nodes{id}}}}}}}'
total_count=0
cursor=''
while :; do
  if [ -n "$cursor" ]; then
    page_json="$(gh api graphql -f owner="$owner" -f repo="$repo" -F pr="$PR" -f cursor="$cursor" -f query="$query")"
  else
    page_json="$(gh api graphql -f owner="$owner" -f repo="$repo" -F pr="$PR" -f query="$query")"
  fi
  page_count=")] | length')"
  total_count=$((total_count + page_count))
  has_next=
  [  =  ] || 
  cursor=
   -n  &&   != 

  -eq 0

If unresolved comments remain, repeat categorization and implementation. If a remaining thread is stale, duplicate, or answer-only, respond or resolve it according to the review workflow before continuing. Run capture_review_comment_snapshot before handling comments and write SNAPSHOT_STARTED_AT=<timestamp> plus SNAPSHOT_CAPTURED_BY=code-review-skill to PR_COMMENT_EVIDENCE; do not supply or backdate the timestamp manually. Before final verification, record every review-thread comment, top-level PR issue comment, and review body comment URL from that snapshot in PR_COMMENT_EVIDENCE using PR_HEAD=<sha>, COMMENT_META|url|updatedAt|body_sha256, and COMMENT|url|commit|sha, COMMENT|url|reply|url, or COMMENT|url|decline|url; comment timing uses the later of createdAt and updatedAt, commit messages must reference the source URL, reply/decline comments must be posted by the PR author or a login in PR_COMMENT_TRUSTED_EVIDENCE_ACTORS, reply bodies must include EVIDENCE_SOURCE: <source URL> and positive EVIDENCE_ACTION: <action>, decline bodies must include EVIDENCE_SOURCE: <source URL>, no-change EVIDENCE_ACTION: <action>, and EVIDENCE_REASON: <reason>, and only reply/decline URLs validated against snapshotted source comments may be treated as evidence comments after the snapshot. Any later created or edited non-evidence PR/review comment requires restarting the snapshot and evidence ledger, except an otherwise qualifying approval review on pushed HEAD whose body is empty or exactly FINAL_APPROVAL_NO_ACTION: true.

Step 6: Run Quality Checks

MANDATORY: Run comprehensive CI checks after implementing all changes:

set -euo pipefail
command -v rg >/dev/null || { echo "rg is required" >&2; exit 1; }
CI_OUTPUT="$(make ci 2>&1)"
printf '%s\n' "$CI_OUTPUT"
CI_LAST_LINE="$(printf '%s\n' "$CI_OUTPUT" | sed '/^[[:space:]]*$/d' | tail -n 1)"
test "$CI_LAST_LINE" = "✅ CI checks successfully passed!"

After make ci, scan the current PR diff for forbidden suppression or ignore directives. Changes to quality-tool baselines or suppression/config files block product PR completion; isolated dedicated gate-definition PRs may include those files only when external trusted-base validation passes. Changes to CI/review gate definitions (AGENTS.md, Makefile, .claude/skills/**, .agents/skills/**, review scripts, CI workflows, architecture/quality gate configs, lint/formatter configs, external quality/check service configs, package-manager check configs, GraphQL/OpenAPI check configs, required-check manifests, AI review-loop Bats coverage, gate-specific onboarding guidance, or timestamped autonomous spec evidence whose slug exactly matches the validation-support allowlist) must be isolated in a dedicated gate-definition PR after the trusted base already has a required-check manifest. Initial gate-definition bootstrap PRs that introduce .github/required-pr-checks.txt may proceed only through the externally validated bootstrap path, and product PRs must not validate with gate definitions supplied only by that same PR.

command -v rg >/dev/null || { echo "rg is required for suppression scan" >&2; exit 1; }
set -o pipefail
diff_output="$(git diff --unified=0 "$TRUSTED_BASE_REF"...HEAD)" || {
  echo "Unable to compute PR diff for suppression scan" >&2
  exit 1
}

forbidden_suppression_pattern() {
  printf '%s\n' '@Suppress''Warnings|@psalm-''suppress|@phpstan-''ignore|phpstan-''ignore|phpcs:(''ignore|disable)|@infection-''ignore|@codeCoverage''Ignore|@phpinsights-''ignore|@codingStandards''Ignore|codingStandards''Ignore'
}

if printf '%s\n' "$diff_output" | rg '^\+[^+]' | rg -n "$(forbidden_suppression_pattern)"; then
  echo "Forbidden suppression/ignore directive found in PR diff" >&2
  exit 1
fi

gate_definition_core_file_pattern='^(AGENTS\.md|Makefile|\.claude/skills/.*|\.agents/skills/.*|deptrac\.yaml|composer\.(json|lock)|phpunit.*\.xml\.dist|psalm\.xml(\.dist)?|phpstan\.(neon|neon\.dist)|phpmd.*\.xml(\.dist)?|phpinsights.*\.php|infection\.(json|json5)(\.dist)?|phpcs\.xml(\.dist)?|\.php-cs-fixer\.dist\.php|docker-compose.*\.ya?ml|Dockerfile.*|scripts/.*|\.github/workflows/.*|\.github/actions/.*|\.github/linters/.*|\.github/required-pr-checks\.txt|\.prettierrc(\..*)?|\.prettierignore|(.*/)?prettier\.config\.(js|mjs|cjs|ts|json|ya?ml)|(.*/)?\.markdownlint(\..*)?|(.*/)?markdownlint\.config\.(js|mjs|cjs|json|ya?ml)|(.*/)?\.yamllint(\..*)?|(\.codecov|codecov)\.ya?ml|\.coderabbit\.ya?ml|\.qlty/.*|(\.qlty|qlty)\.toml|\.snyk|(\.spectral|spectral)\.ya?ml|(.*/)?spectral\.config\.(js|mjs|cjs|ts|json|ya?ml)|(.*/)?eslint\.config\.(js|mjs|cjs|ts)|(.*/)?\.eslintrc(\..*)?|(.*/)?package(-lock)?\.json|(.*/)?pnpm-lock\.yaml|(.*/)?yarn\.lock|(.*/)?\.graphqlrc(\..*)?|(.*/)?graphql\.config\.(js|mjs|cjs|ts|json|ya?ml)|(.*/)?graphql-inspector(\.config)?\.(js|mjs|cjs|ts|json|ya?ml)|(.*/)?(\.openapi-diff|openapi-diff)(\.config)?\.(js|mjs|cjs|ts|json|ya?ml))$'
gate_definition_validation_support_file_pattern=
gate_definition_file_pattern=
GATE_DEFINITION_CHANGES_PRESENT=
() {
  [  =  ] &&
    ! git cat-file -e  2>/dev/null &&
     -r .github/required-pr-checks.txt
}
all_changes=
gate_definition_changes=
 [ -n  ]; 
  GATE_DEFINITION_CHANGES_PRESENT=
  non_gate_definition_changes=
    
   [ -n  ]; 
      
     gate_definition_bootstrap_required; 
        >&2
    
        >&2
       1
    
  


quality_config_changes=
 [ -n  ] && [  !=  ]; 
    
    >&2
   1

If CI fails, invoke appropriate skill:

Failure Type	Skill to Use
Architecture violations	deptrac-fixer
Complexity issues	complexity-management
Test failures	testing-workflow
Mutation testing issues	testing-workflow
Code style	Run make phpcsfixer
Static analysis	Run make psalm

DO NOT finish the task until make ci shows: ✅ CI checks successfully passed!

Dedicated gate-definition PRs may complete only when all of the following are true:

1. assert_gate_definition_change_scope reports only gate-definition files and explicitly classified validation-support files changed against TRUSTED_BASE_REF, except for the initial externally validated bootstrap PR that introduces .github/required-pr-checks.txt when the trusted base has no manifest.
2. Step 8 reruns make ci and final make ai-review-loop on the same clean local HEAD before push; caller-supplied BASE_OID or VERIFIED_HEAD variables are not trusted as proof.
3. GATE_DEFINITION_VALIDATION_EVIDENCE points to a readable ledger outside the PR worktree with PR_HEAD=<HEAD>, TRUSTED_BASE=<baseRefOid>, VALIDATION_MODE=trusted-base or VALIDATION_MODE=immutable-external, TRUSTED_BASE_GATE=PASS, TRUSTED_MANIFEST_CHECKS=PASS, and an immutable GitHub Actions run URL whose repository is the base PR repository for trusted-base mode or is listed in GATE_DEFINITION_TRUSTED_VALIDATOR_REPOS for immutable-external mode; the run must complete successfully while validating pushed HEAD from the canonical artifact, execute from the trusted base commit for trusted-base mode or from a repo|head_sha listed in GATE_DEFINITION_TRUSTED_VALIDATOR_HEAD_SHAS for immutable-external mode, come from a workflow path allowed by GATE_DEFINITION_TRUSTED_BASE_WORKFLOWS or GATE_DEFINITION_TRUSTED_VALIDATOR_WORKFLOWS, use a trusted workflow SHA from the trusted base or GATE_DEFINITION_TRUSTED_VALIDATOR_WORKFLOW_SHAS, and expose exactly one non-expired trusted-base-gate-evidence artifact file named trusted-base-gate-evidence.env with exact full-line records for the same PR_HEAD, TRUSTED_BASE, TRUSTED_BASE_GATE=PASS, TRUSTED_MANIFEST_CHECKS=PASS, exact VALIDATION_MODE, RUN_REPO, RUN_ID, WORKFLOW_PATH, and WORKFLOW_SHA.
4. Direct review-thread query shows zero unresolved review threads.
5. PR_COMMENT_EVIDENCE maps every review-thread, top-level PR issue, and review body comment URL from the auto-captured snapshot to matching metadata and to a later PR-range commit whose message references the source URL, or to a later same-PR reply/decline URL whose trusted-author body includes , , and decline ; comment ordering uses the later of and , only validated snapshotted evidence URLs may whitelist post-snapshot evidence comments, and later created or edited non-evidence comments force the snapshot/evidence loop to restart except for an otherwise qualifying approval review on pushed whose body is empty or exactly .

Step 7: Run Final AI Review Loop

After the final successful make ci, capture CI_HEAD="$(git rev-parse HEAD)" and run the autonomous review loop again before any push or ready-for-review action:

set -euo pipefail

CI_HEAD="$(git rev-parse HEAD)"
AI_REVIEW_OUTPUT="$(AI_REVIEW_BASE="$TRUSTED_BASE_REF" make ai-review-loop 2>&1)"
printf '%s\n' "$AI_REVIEW_OUTPUT"
AI_REVIEW_LAST_LINE="$(printf '%s\n' "$AI_REVIEW_OUTPUT" | sed '/^[[:space:]]*$/d' | tail -n 1)"
test "$AI_REVIEW_LAST_LINE" = "AI review PASS."
test "$CI_HEAD" = "$(git rev-parse HEAD)"
test -z "$(git status --short)"
VERIFIED_HEAD="$CI_HEAD"
CURRENT_BASE_JSON="$(gh pr view "$PR" --repo "$PR_REPO" --json baseRefName,baseRefOid)"
test "$BASE_OID" = "$(printf '%s\n' "$CURRENT_BASE_JSON" | jq -r .baseRefOid)"
test "$BASE_REF" = "$(printf '%s\n' "$CURRENT_BASE_JSON" | jq -r .baseRefName)"

If the AI review loop applies fixes or changes any tracked file, repeat:

1. Review git status --short
2. Commit intentional tracked changes with the relevant review or AI-loop reference
3. make ci
4. forbidden suppression scan and gate-definition change scan
5. capture CI_HEAD="$(git rev-parse HEAD)"
6. capture AI_REVIEW_OUTPUT, print it, and require the last nonblank output line from make ai-review-loop to equal AI review PASS.