@olegkoval/agent-skills 1.51.0 → 1.51.2

package/adapters/claude/olko-github-pr/skills/codexloop/SKILL.md

@@ -3,12 +3,12 @@ name: codexloop
 description: >
   Iteratively satisfy OpenAI Codex's code review on a GitHub PR, but treat every Codex comment
   SKEPTICALLY: verify each finding against the real code first, fix ONLY the genuinely-correct
-  ones, and rebut + resolve false positives WITHOUT changing correct code. Repeat until no
-  unresolved Codex comments remain. Use when the user says "satisfy codex", "clear the codex
+  ones, and rebut + resolve false positives WITHOUT changing correct code. Repeat until Codex
+  has reviewed the latest push and nothing is left unresolved. Use when the user says "satisfy codex", "clear the codex
   review", "fix codex comments", "codex loop", or wants to iterate on Codex PR review feedback.
 compatibility: GitHub only (Codex code review is a GitHub app). Requires git + jq + gh (GitHub CLI) authenticated, and the Codex / ChatGPT connector app installed on the repo with code review enabled.
 metadata:
-  version: "1.2"
+  version: "1.3"
 allowed-tools: Bash(gh:*) Bash(git:*)
 ---
 <!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
@@ -23,7 +23,8 @@ suggestion applied is worse than the comment itself.
 
 - **No check-run, no score.** Codex does not publish an `X/5` confidence or a named check. It posts
   a **PR review** (state `COMMENTED`) plus inline review comments. Detection is by polling the
-  *reviews* endpoint. "Satisfied" = zero unresolved comments (each either fixed or rebutted).
+  *reviews* endpoint. "Satisfied" = Codex has reviewed the latest push and no bot comment is left unresolved (each
+  either fixed or rebutted).
 - **Trigger phrase is `@codex review`.** Codex reviews automatically when a PR opens or gets new
   commits if auto-review is enabled on the repo; the mention forces a fresh pass. Other useful
   mentions: `@codex review focus on <area>` for a scoped re-review.
@@ -55,11 +56,32 @@ Pick the login matching `*codex*` (commonly `chatgpt-codex-connector[bot]`, some
 
 **Finding nothing here is NOT a stop condition.** On a PR Codex has never reviewed there is no bot
 login to find yet: that is the normal starting state, not a missing app. When the probe comes back
-empty, fall through to step 2A, post `@codex review`, and re-run this probe once a review lands;
+empty, fall through to step A, post `@codex review`, and re-run this probe once a review lands;
 until then match any login containing `codex` when polling. Only conclude the app is absent after
-step 2A's bounded wait has expired with no review and no codex-like login anywhere on the PR, and
+step A's bounded wait has expired with no review and no codex-like login anywhere on the PR, and
 then say so and stop, rather than looping against nothing.
 
+## Review state comes from the PR, not from memory
+
+`scripts/pr-review-state.sh` reads the PR and prints one JSON object: the current head, whether
+Codex has acted on that head (a review of it, or any comment after it was pushed), and every
+unresolved review thread with its author. Every "is there work / are we done" decision in this
+loop comes from its exit code, never from what you remember resolving. The script lives in this
+skill's directory, `SKILL_ROOT`: the directory holding this `SKILL.md` (Claude Code prints it as the
+skill's base directory when the skill loads; in Codex, derive it from the selected `SKILL.md` path).
+
+| Exit | `verdict`  | Meaning                                                             | Do                                   |
+|------|------------|---------------------------------------------------------------------|--------------------------------------|
+| 0    | `clean`    | Codex acted on the current head and no bot thread is unresolved    | exit check: done                     |
+| 10   | `findings` | unresolved threads from Codex **or any other review bot**          | run an iteration                     |
+| 20   | `pending`  | Codex has not acted on the current head yet                        | trigger if needed, then wait         |
+| 30   | `limited`  | a rate-limit or paused notice from Codex after the current head    | stop, report `blocked: rate-limited` |
+
+Resolving the last thread does not make a PR clean: Codex has not reviewed your push yet. Earlier
+versions of this loop exited at exactly that moment, while the next round of comments was still on
+its way. Human threads are listed in `.unresolved` (`is_bot: false`) and counted in `.counts.humans`;
+they never block `clean`, and this loop never resolves them.
+
 ## 1. Identify the PR
 
 ```bash
@@ -80,66 +102,50 @@ Keep an explicit iteration counter and stop at 5: the cap is a real bound to enf
 figure of speech. Each pass through A–G is one iteration; on hitting the cap, go straight to the
 report and list what is still unresolved rather than starting a sixth.
 
-### A. Ensure a fresh Codex review on the current head
-
-```bash
-HEAD_SHA=$(gh pr view <PR> --json headRefOid -q .headRefOid)
-# Only trigger if no Codex review already exists for this exact SHA.
-# gh cannot combine --slurp with --jq, so pipe to `jq -s`: it folds every page
-# into one array. Without it the filter runs once per page and HAVE becomes a
-# multi-line count that never equals "0", silently skipping the trigger.
-HAVE=$(gh api repos/{owner}/{repo}/pulls/<PR>/reviews --paginate |
-  jq -s --arg bot "$BOT" --arg head "$HEAD_SHA" \
-    '[.[][] | select(.user.login==$bot and .commit_id==$head)] | length')
-if [ "$HAVE" = "0" ]; then gh pr comment <PR> --body "@codex review"; fi
-```
+### A. Read the PR state; wait for Codex's review of the current head
 
-Poll for the review of THIS head to land. No check-run exists, so poll the reviews endpoint, and
-poll it on a **deadline**, never `while true`: a review that never arrives must end the skill with
-an honest timeout, not hang it.
+One read answers both "is there work?" and "has Codex seen my last push?". `SINCE` is the
+timestamp you took right before your last push (step E); leave it empty on iteration 1. Right
+after a push, add `--wait 600` straight away: the wait ends only once the bot has acted on the new
+head, so threads left open on purpose cannot make the push look reviewed.
 
 ```bash
-# 10-minute deadline, one retry, then give up. DEADLINE/RETRIES are the
-# enforcement of the bounds this skill claims: do not drop them.
-wait_for_review() {                       # $1 = attempt label
-  local deadline=$(( SECONDS + 600 ))
-  while [ "$SECONDS" -lt "$deadline" ]; do
-    R=$(gh api repos/{owner}/{repo}/pulls/<PR>/reviews --paginate |
-      jq -s --arg bot "$BOT" --arg head "$HEAD_SHA" \
-        '[.[][] | select(.user.login==$bot and .commit_id==$head)] | sort_by(.submitted_at, .id) | last')
-    if [ -n "$R" ] && [ "$R" != "null" ]; then return 0; fi
-    echo "waiting for Codex review of $HEAD_SHA ($1)..."; sleep 15
-  done
-  return 1
-}
-
-if ! wait_for_review "first wait"; then
-  echo "no Codex review after 10m, retrying once"     # say the retry out loud
-  gh pr comment <PR> --body "@codex review"
-  if ! wait_for_review "after retry"; then
-    echo "Codex did not review $HEAD_SHA after a retry; stopping and reporting."
-    exit 1                                # honest timeout, never a success claim
-  fi
-fi
+"$SKILL_ROOT/scripts/pr-review-state.sh" --repo OWNER/REPO --pr <PR> --bot codex --since "$SINCE"
 ```
 
-Codex can take several minutes on a large diff, which is why the deadline is generous. Report the
-retry in the final summary; two silent timeouts are the failure mode this guard exists to prevent.
+- Exit `10` (`findings`): go to B. On iteration 1 this is whatever Codex (or another bot)
+  already posted.
+- Exit `20` (`pending`): post `@codex review` (`gh pr comment <PR> --body "@codex review"`). Then wait with the same command plus `--wait 600`. Run the
+  wait in the background where the host allows it (Claude Code: Bash `run_in_background`; you are
+  re-invoked when it exits) so ten minutes of polling never sits in the conversation. Still `20`
+  after the wait: say so out loud, post `@codex review` once more, and wait once more. Still `20` after that: stop and
+  report the timeout honestly; never claim success.
+- Exit `0` (`clean`): go to the exit check. A `--wait` call returns `clean` only after a settle
+  re-read 60 seconds later, so a comment landing right behind the review is still caught. A bare
+  read (no `--wait`) that says `clean` is good enough only when you have not pushed since Codex's
+  last review.
+- Exit `30` (`limited`): stop now and report `blocked: rate-limited`; nothing more is coming.
+- Exit `1`: the read itself failed (often a transient GitHub 502). Retry once; if it fails again,
+  stop and report it. An unknown state is not a clean one.
 
 ### B. Fetch the findings
 
-- **Summary**: the review `.body` from the object above: read the overall take and the priority
+The working set is every unresolved thread in the state JSON with `is_bot: true`: Codex's
+own (`is_target: true`) **and any other review bot's** (Greptile, for example). A
+fix for one bot often draws a comment from another, and leaving those open is how a "finished" loop
+leaves a PR that is not clean. Treat another bot's thread with exactly the same verify-first rules
+below. Never act on a human's thread (`is_bot: false`); list it in the report.
+
+- **Summary**: the latest review `.body` from this bot (`gh pr view <PR> --json reviews`): read the overall take and the priority
   spread.
-- **Unresolved inline comments** on the current head:
+- **Unresolved inline comments**: `.unresolved[] | select(.is_bot)` in step A's state JSON lists
+  each thread's `thread_id`, `comment_id`, `path`, `line` and a short excerpt, across every page of
+  threads. Read the full comment before judging it:
 
 ```bash
-gh api repos/{owner}/{repo}/pulls/<PR>/comments --paginate \
-  --jq ".[] | select(.user.login==\"$BOT\") | {id, path, line, body}"
+gh api repos/{owner}/{repo}/pulls/comments/<COMMENT_ID> --jq '{user: .user.login, path, line, body}'
 ```
 
-Also pull the review threads + their resolved state via GraphQL (see step F) so you only act on
-unresolved ones.
-
 Mark each unresolved comment as seen, so the bot and a watching human can tell it is being handled.
 GitHub's reaction set is fixed; `eyes` is the only "looking at it" value:
 
@@ -196,6 +202,7 @@ If step D changed code:
 git status --short                     # look before you stage
 git add <path> [<path>...]             # the files named in the findings you fixed
 git commit -m "address codex review feedback (codexloop iteration N)"
+SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ)   # step A reads bot activity after this
 git push
 ```
 
@@ -215,31 +222,8 @@ to and resolved without a push.
 
 ### F. Reply to and resolve every addressed thread
 
-Only now, with the fixes pushed, reply and resolve. Fetch unresolved threads, **following
-pagination**: a PR with more than 100 threads will otherwise look clean while unresolved findings
-sit on page two:
-
-```bash
-# Loop until hasNextPage is false, passing endCursor back in as $cursor.
-CURSOR=null
-while : ; do
-  PAGE=$(gh api graphql -F cursor="$CURSOR" -f query='
-  query($cursor: String) {
-    repository(owner: "OWNER", name: "REPO") {
-      pullRequest(number: PR_NUMBER) {
-        reviewThreads(first: 100, after: $cursor) {
-          pageInfo { hasNextPage endCursor }
-          nodes { id isResolved comments(first: 1) { nodes { databaseId author { login } path body } } }
-        }
-      }
-    }
-  }')
-  echo "$PAGE"          # collect nodes from every page before deciding the PR is clean
-  PI='.data.repository.pullRequest.reviewThreads.pageInfo'
-  [ "$(echo "$PAGE" | jq -r "$PI.hasNextPage")" = "true" ] || break
-  CURSOR=$(echo "$PAGE" | jq -r "$PI.endCursor")
-done
-```
+Only now, with the fixes pushed, reply and resolve. Take thread and comment ids from step A's state
+JSON (`.unresolved[]`): the script already follows pagination, so do not hand-roll a threads query.
 
 Reply on a thread's comment via `gh api repos/{owner}/{repo}/pulls/<PR>/comments -f body="..." -F in_reply_to=<comment_id>`,
 then resolve:
@@ -263,7 +247,8 @@ gh api --method POST repos/{owner}/{repo}/pulls/comments/<COMMENT_ID>/reactions
 Reply first, then react, then resolve: the reaction is not a substitute for the reply, and a
 resolved thread with no reply loses the reasoning.
 
-Resolve a thread only for comments authored by `$BOT` that you have fixed or rebutted: never
+Resolve a thread only for a bot comment in your working set (this bot's or another
+review bot's) that you have fixed or rebutted: never
 blanket-resolve, and never resolve a human reviewer's thread. For each fixed comment, verify the
 push first, reply with the change made, then resolve the thread and verify `isResolved: true`.
 For each rebutted comment, reply with the evidence and verify resolution. Do not report a comment
@@ -272,19 +257,34 @@ as fixed or rebutted until its thread is confirmed resolved.
 Threads you are **rebutting** need no push, so they may be replied to and resolved regardless of
 whether step D changed code.
 
-### G. Re-review
+### G. Back to A
 
-Pushing re-triggers Codex when auto-review is on; otherwise post `@codex review`. Go back to **A**
-with the new head SHA. If step D changed nothing (all comments were rebutted), skip the push,
-ensure all threads are resolved, and exit.
+Go back to **A**. After a push, A waits for Codex's review of the new head (pushing re-triggers
+it when auto-review is on; otherwise A triggers it). If this iteration changed no code (every finding
+rebutted), there is no new head to wait for: A's fresh read says `clean` or shows what is still open.
 
 ## 3. Exit conditions
 
+Decide from a fresh state read, never from what you remember resolving.
+
 Stop when **any** is true:
-- Zero unresolved `$BOT` comments remain, and every comment this round was fixed or
-  rebutted+resolved. (There is no score to hit: this is "done".)
-- Max iterations (5) reached: report what remains.
-- Codex never responded after one retry: report the timeout honestly; do not claim success.
+- **Done**: the latest `pr-review-state.sh --wait 600` call, made after your last push, exited `0`
+  (`clean`); with no push since the bot's last review, a bare read that exits `0` is enough. Open human threads do not block this; list them in the report.
+- **Max iterations (5)** reached: report what remains.
+- **Timeout**: still `pending` after the retry in step A. Report it honestly; do not claim success.
+- **Rate limited**: exit `30`. Report `blocked: rate-limited`.
+
+## Keep the context small; resume instead of restarting
+
+- Carry only three things between iterations: the iteration counter, the latest state JSON, and a
+  ledger of each thread you handled (fixed with its commit, rebutted, or blocked). Re-read files
+  fresh each iteration; do not re-paste earlier rounds' comment bodies.
+- All loop state lives on the PR, so the loop is resumable. If the session has grown long or slow,
+  or a bot commented after the loop ended, run this skill again in a fresh session: step A picks up
+  from the PR as it is now. Starting fresh is cheaper than dragging a long session through more
+  rounds.
+- After reporting done, if the host can schedule a follow-up (Claude Code: `/loop` or a scheduled
+  wakeup), offer one re-check about 20 minutes later for bots that comment late.
 
 ## 4. Report
 
@@ -295,7 +295,9 @@ Codexloop complete.
   Iterations:         N
   Comments fixed:     N   (genuinely-correct findings)
   Comments rebutted:  N   (false positives / nits, resolved with rationale)
-  Remaining:          0
+  Remaining:          N   (bot threads still open)
+  Human threads:      N   (open, listed below; this loop never resolves them)
+  Final state:        clean | timeout | rate-limited | iteration cap
 ```
 
 If it stopped at max iterations, list the remaining threads with your current assessment

package/adapters/claude/olko-github-pr/skills/codexloop/scripts/pr-review-state.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+# pr-review-state.sh: read a PR's review-bot state once (or until it settles) and print it as JSON.
+#
+# Shared by every review loop in olko-github-pr (codexloop, geminiloop, copilotloop,
+# coderabbitloop, qodoloop). Each skill ships its own copy so it works on every adapter;
+# tests/test-pr-review-state.sh fails if the copies drift apart.
+#
+# The loops decide "done" from this output, never from their own memory of what they resolved:
+#   clean     every --bot has acted on the current head AND no bot thread is unresolved
+#   findings  at least one unresolved thread from any bot (target or not): work to do
+#   pending   some --bot has not acted on the current head yet
+#
+# "Acted on the head" = a review of the head commit, or after the head was pushed: a
+# comment that is not a progress notice, or a PR reaction other than 👀 (Codex signals a clean
+# review with only a 👍 on the PR, and edits a "**Running**" summary comment while it works).
+#   limited   a --bot posted a rate-limit / paused notice after the current head
+set -euo pipefail
+
+usage() {
+  cat >&2 <<'EOF'
+usage: pr-review-state.sh --repo OWNER/REPO --pr N --bot REGEX [--bot REGEX ...]
+                          [--since ISO8601] [--wait SECONDS] [--settle SECONDS] [--interval SECONDS]
+
+  --bot       case-insensitive regex matched against the bare bot login (GraphQL drops "[bot]"),
+              e.g. codex, gemini-code-assist, copilot, coderabbitai, qodo-code-review. Repeatable:
+              every --bot must have acted on the current head before the verdict can be "clean".
+  --since     when the current head was pushed (date -u +%Y-%m-%dT%H:%M:%SZ, taken before the push).
+              Bot activity counts for the head only if it happened after max(head commit date, since).
+  --wait      poll until every --bot has acted on the current head (or posted a limit notice), or
+              SECONDS pass (default 0: read once). Open threads do not end the wait early, so threads
+              left open on purpose cannot make a fresh push look reviewed.
+  --settle    once "clean", wait SECONDS and read again, so a late comment is not missed
+              (default 60 when --wait is set, else 0).
+  --interval  seconds between polls (default 20).
+
+exit: 0 clean, 10 findings, 20 pending, 30 limited, 2 usage, 1 error
+EOF
+  exit 2
+}
+
+REPO="" PR="" SINCE="" WAIT=0 SETTLE="" INTERVAL=20
+BOTS=()
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --repo) REPO="${2:-}"; shift 2 ;;
+    --pr) PR="${2:-}"; shift 2 ;;
+    --bot) BOTS+=("${2:-}"); shift 2 ;;
+    --since) SINCE="${2:-}"; shift 2 ;;
+    --wait) WAIT="${2:-}"; shift 2 ;;
+    --settle) SETTLE="${2:-}"; shift 2 ;;
+    --interval) INTERVAL="${2:-}"; shift 2 ;;
+    -h|--help) usage ;;
+    *) echo "unknown argument: $1" >&2; usage ;;
+  esac
+done
+[ -n "$REPO" ] && [ -n "$PR" ] && [ "${#BOTS[@]}" -gt 0 ] || usage
+case "$REPO" in */*) ;; *) usage ;; esac
+[ -n "$SETTLE" ] || { [ "$WAIT" -gt 0 ] && SETTLE=60 || SETTLE=0; }
+OWNER="${REPO%%/*}" NAME="${REPO#*/}"
+BOTS_JSON=$(printf '%s\n' "${BOTS[@]}" | jq -R . | jq -s .)
+
+QUERY='query($owner:String!,$name:String!,$pr:Int!,$cursor:String){
+  repository(owner:$owner,name:$name){ pullRequest(number:$pr){
+    headRefOid
+    commits(last:1){ nodes{ commit{ oid committedDate } } }
+    reviews(last:100){ nodes{ author{ login __typename } commit{ oid } submittedAt body } }
+    comments(last:100){ nodes{ author{ login __typename } createdAt updatedAt body } }
+    reactions(last:50){ nodes{ content createdAt user{ login } } }
+    reviewThreads(first:100, after:$cursor){
+      pageInfo{ hasNextPage endCursor }
+      nodes{ id isResolved isOutdated path line
+        comments(first:1){ nodes{ databaseId url author{ login __typename } body } } }
+    }
+  } }
+}'
+
+# One full read: first page carries head/reviews/comments; every page carries threads.
+read_state() {
+  local cursor=null page first="" threads="[]"
+  while :; do
+    page=$(gh api graphql -f query="$QUERY" -f owner="$OWNER" -f name="$NAME" \
+      -F pr="$PR" -F cursor="$cursor")
+    [ -n "$first" ] || first="$page"
+    threads=$(jq -c --argjson acc "$threads" \
+      '$acc + .data.repository.pullRequest.reviewThreads.nodes' <<<"$page")
+    [ "$(jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.hasNextPage' <<<"$page")" = "true" ] || break
+    cursor=$(jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.endCursor' <<<"$page")
+  done
+
+  jq -c --argjson bots "$BOTS_JSON" --argjson threads "$threads" --arg since "$SINCE" '
+    .data.repository.pullRequest as $p
+    | $p.headRefOid as $head
+    | ([$p.commits.nodes[0].commit.committedDate // "", $since] | max) as $after
+    | def matches($login): any($bots[]; . as $re | ($login // "") | test($re; "i"));
+      def isbot($a): ($a.__typename // "User") != "User";
+      def progress: test("busy working|in progress|currently processing|currently reviewing|\\*\\*(running|queued)\\*\\*"; "i");
+      def limited: test("review limit reached|reached your (pr )?review limit|reviews are paused|rate limit (exceeded|reached)|been rate[- ]limited"; "i");
+    [ $bots[] as $re
+      | ($p.reviews.nodes  | map(select((.author.login // "") | test($re; "i")))) as $revs
+      | ($p.comments.nodes | map(select((.author.login // "") | test($re; "i")))) as $coms
+      | ($coms | map(select(.updatedAt >= $after))) as $fresh
+      | ($p.reactions.nodes | map(select(((.user.login // "") | test($re; "i"))
+                                         and .content != "EYES" and .createdAt >= $after))) as $reacts
+      | {
+          bot: $re,
+          reviewed_head: any($revs[]; .commit.oid == $head),
+          activity_after_head: (any($fresh[]; (.body | progress) | not)
+                                or ($reacts | length) > 0),
+          limited: any($fresh[]; .body | limited)
+        }
+      | .acted_on_head = (.reviewed_head or .activity_after_head)
+    ] as $per_bot
+    | [ $threads[] | select(.isResolved | not)
+        | .comments.nodes[0] as $c
+        | {
+            thread_id: .id, comment_id: $c.databaseId, url: $c.url,
+            author: $c.author.login, is_bot: isbot($c.author), is_target: matches($c.author.login),
+            path, line, outdated: .isOutdated,
+            excerpt: (($c.body // "") | gsub("\\s+"; " ") | .[0:160])
+          } ] as $open
+    | ($open | map(select(.is_bot))) as $open_bot
+    | {
+        head: $head,
+        head_after: $after,
+        bots: $per_bot,
+        unresolved: $open,
+        counts: {
+          target: ($open_bot | map(select(.is_target)) | length),
+          other_bots: ($open_bot | map(select(.is_target | not)) | length),
+          humans: ($open | map(select(.is_bot | not)) | length)
+        },
+        verdict: (
+          if any($per_bot[]; .limited) then "limited"
+          elif ($open_bot | length) > 0 then "findings"
+          elif any($per_bot[]; .acted_on_head | not) then "pending"
+          else "clean" end)
+      }' <<<"$first"
+}
+
+exit_for() {
+  case "$1" in clean) echo 0 ;; findings) echo 10 ;; pending) echo 20 ;; limited) echo 30 ;; *) echo 1 ;; esac
+}
+
+deadline=$(( SECONDS + WAIT ))
+state=$(read_state)
+verdict=$(jq -r .verdict <<<"$state")
+waiting() { jq -e '.verdict != "limited" and any(.bots[]; .acted_on_head | not)' >/dev/null <<<"$state"; }
+while :; do
+  if waiting && [ "$SECONDS" -lt "$deadline" ]; then
+    sleep "$INTERVAL"
+  elif [ "$verdict" = "clean" ] && [ "$SETTLE" -gt 0 ]; then
+    # Clean once is not clean: bots post a review, then a second bot or a follow-up lands.
+    sleep "$SETTLE"
+    SETTLE=0
+  else
+    break
+  fi
+  state=$(read_state)
+  verdict=$(jq -r .verdict <<<"$state")
+done
+
+printf '%s\n' "$state"
+exit "$(exit_for "$verdict")"