@olegkoval/agent-skills 1.24.0 → 1.26.0

package/.kiro/steering/pr-finalize-complete.md

@@ -0,0 +1,187 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+inclusion: manual
+description: "Confirms a PR is genuinely merge-ready when the work is already believed done: re-checks every review-bot and human finding against the current code, separates stale comments from fixed ones, runs the repo's real lint and test gates, and reports the evidence rather than the assumption."
+---
+
+# PR Finalize Complete
+
+Confirm a PR is genuinely merge-ready -- even when all issues were already addressed -- by verifying the evidence, not trusting the assumption.
+
+## When to use this vs pr-finalize
+
+Use pr-finalize-complete when:
+- The branch owner says "it should be fixed already" and you need to confirm
+- Review bot findings may be stale (comments on old file paths, already-changed code)
+- You need to produce a verification report, not just drive fixes
+-- CI was green before but you need to re-confirm after a rebase
+
+Use pr-finalize when starting from scratch on an unaddressed PR.
+
+## Inputs
+
+- **PR number or URL** (optional): detect from the current branch if not given.
+- `--no-push` (optional): run all verification steps but skip the final push.
+
+## Non-negotiables
+
+- **Never claim a test passed without running it.** Report the actual exit code and test count.
+- **Never resolve a bot comment without checking whether the issue still exists in the current code.** Stale comments are common and silently resolving them is wrong.
+- **Never git add -A.** Start with a clean tree; stage only files your fixes actually touched.
+- **Stale comments are not done -- they are no longer applicable.** Distinguish the two in your report.
+
+## Instructions
+
+### 1. Establish ground truth
+
+```bash
+gh pr view <PR> --json number,title,body,state,isDraft,headRefName,baseRefName,mergeable,mergeStateStatus,reviews,statusCheckRollup,url
+```
+
+Record before touching anything:
+
+- Is the branch **clean** (`git status --porcelain` empty)?
+- Is the branch **behind** `origin/<base>`?
+- What **checks are currently failing**, and which are required?
+- Which bots have actually posted (completed, not just triggered)?
+
+### 2. Rebase only if needed
+
+If mergeable is CONFLICTING or the branch is behind its base:
+
+```bash
+git fetch origin <base>
+git rebase origin/<base>
+```
+
+Resolve conflicts by understanding both sides. After resolving, run tests before continuing.
+If there is no conflict, skip this step -- do not rebase speculatively.
+
+### 3. Triage existing review comments
+
+Collect all findings:
+
+```bash
+gh api repos/{owner}/{repo}/pulls/<PR>/comments --paginate
+gh api repos/{owner}/{repo}/issues/<PR>/comments --paginate
+gh pr view <PR> --json reviews
+```
+
+For each unresolved finding, determine its actual current status in the code:
+
+| Status | Meaning | Action |
+|---|---|---|
+| Already fixed | Code the comment targets has been changed and issue no longer exists | Verify in code, reply confirming fix, resolve |
+| Stale | Comment targets a file/line/symbol that no longer exists | Verify, reply noting it is stale, resolve |
+| Still present | Issue exists in current code | Fix it, commit, reply, resolve |
+| False positive | Bot diagnosis is wrong for this codebase | Reply with specific rebuttal, leave open |
+| Needs human | Product/architecture decision required | Reply, leave open, surface in report |
+
+A comment is stale if the file it targets has been deleted or
+renamed, the function or class it names no longer exists, or the
+issue was flagged on an old line that has since been rewritten.
+
+Check for staleness before any fix attempt:
+
+```bash
+gh api repos/{owner}/{repo}/pulls/<PR>/files --paginate
+git diff origin/<base>...HEAD =- <file>
+```
+
+For stale comments: verify in current HEAD, reply explaining what changed, then resolve.
+
+### 4. Verify test coverage
+
+Find changed files:
+
+```bash
+gh pr view <PR> --json files -q '.files[].path'
+```
+
+For each changed module: check for a direct unit test file, confirm
+it exercises the specific code paths changed, and run it to verify
+impasses.
+
+If a module has no direct unit tests but is only indirectly covered,
+that is a real gap. Add direct tests unless the coverage gap is
+explicitly justified.
+
+### 5. Run the real gates
+
+Discover from the repo -- do not guess target names:
+
+```bash
+cat package.json | jq '.scripts'
+```
+
+Run in order: lint, format check, full test suite. Capture the actual
+exit code and output. Do not push if any required gate is red.
+
+### 6. Push and report
+
+If there were changes to commit:
+
+```bash
+git add <only files you touched>
+git commit -m "address review feedback and verify tests"
+git push --force-with-lease
+```
+
+Post one PR comment with a verifiable summary: rebase status, each
+finding and its disposition, test coverage decision, and verbatim
+gate output with real numbers.
+
+### 7. Verify final state
+
+```bash
+gh pr view <PR> --json mergeable,mergeStateStatus,statusCheckRollup
+```
+
+Poll until checks complete. If anything that was green went red,
+diagnose and fix before declaring done.
+
+## Common patterns
+
+### Pattern: All issues already fixed
+
+When a bot shows open findings but the branch owner believes they
+are all resolved:
+1. Do not trust the assertion -- verify each one in the current code.
+2. Stale comments are the most common case: the code was refactored
+   and the bot finding path no longer exists.
+3. Distinguish "already fixed before bot ran" from "fixed in a later
+   commit the bot has not re-reviewed yet".
+4. Re-trigger the bot if it has not reviewed current HEAD.
+
+### Pattern: Direct unit tests missing
+
+Bots frequently flag helper functions exercised only through callers.
+Add a direct test for the helper itself -- do not rely on indirect
+coverage through a caller integration test.
+
+### Pattern: Branch conflict with rewritten shared file
+
+When rebase hits a conflict in a file both branches modified:
+1. Run git log to understand what main changed and why.
+2. Read the purpose of the main-side hunk -- it is usually an invariant
+   your branch is unaware of.
+3. Apply main's change to your version of the file, then re-run
+   the affected tests.
+4. Document which invariant you preserved in your PR comment.
+
+### Pattern: CI flaky on first push
+
+Before declaring a gate failure real:
+1. Check if the failure is in a known flaky test.
+2. Check if the failure is in a linter with a stale cache from a
+   different worktree.
+3. Re-run the specific failing check once before fixing.
+4. Only fix if the failure reproduces on re-run.
+
+## Related skills
+
+- pr-finalize -- drive a PR from scratch to merge-ready when comments are unaddressed.
+- qodoloop -- full Qodo thread protocol (per-finding Agent Prompts, resolve mutations).
+- coderabbitloop -- full CodeRabbit thread protocol.
+- ci-fix-loop -- when the blocker is a failing CI pipeline, not review feedback.

package/.kiro/steering/pr-finalize.md

@@ -0,0 +1,140 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+inclusion: manual
+description: "Drives one GitHub PR to genuinely merge-ready: rebases and resolves conflicts, sweeps every review bot and human comment to zero unaddressed findings, verifies unit and E2E coverage actually exists, runs the repo's real lint/format/test gates before pushing, and reports what still needs a human."
+---
+
+# PR Finalize
+
+One PR, taken all the way to merge-ready. The job is not "make the bots stop talking" — it is **land the change in a state a careful reviewer would sign off on**, with evidence for every claim.
+
+## Inputs
+
+- **PR number or URL** (optional): detect from the current branch if not given.
+- `--no-push` (optional): do everything except the final push. Use when the repo auto-merges and the user wants to eyeball first.
+
+## Non-negotiables
+
+These are the failure modes this skill exists to prevent. Violating one makes the whole run worthless:
+
+- **Never report a gate as passing without having run it.** Paste the real output. "Tests should pass" is not a result.
+- **Never resolve or claim-fix a finding you didn't actually fix.** Blocked is an honest outcome; a false "done" is not.
+- **Never `git add -A`.** Stage only the files your fixes touched. Start from a clean tree so that's safe.
+- **Never invent test coverage.** If the change has no browser-reachable surface, say so explicitly and name the suite that *is* the real gate. Do not add a hollow E2E test to look thorough.
+- **A green CI badge is not proof.** Many repos split their required check from the full suite (browser-free half only, etc.). Find out what the required check actually runs.
+
+## Instructions
+
+### 1. Establish the ground truth
+
+```bash
+gh pr view <PR> --json number,title,body,state,isDraft,headRefName,baseRefName,mergeable,mergeStateStatus,labels,reviewDecision,statusCheckRollup,url
+```
+
+Record four things before touching code:
+
+- **`mergeable`** — `CONFLICTING` means step 2 is mandatory.
+- **Which checks are failing**, and for each, whether it is *required*. Check branch protection (`gh api repos/{owner}/{repo}/branches/<base>/protection`) rather than assuming — a red optional job (a flaky bot-review runner, a nightly) is not a blocker, and burning the run waiting on one is a classic waste.
+- **Whether the repo auto-merges.** Look for a shepherd/automerge workflow in `.github/workflows/` and read its *gating conditions* (required labels, required checks). If pushing could trigger an immediate merge, decide deliberately: either satisfy the review sweep first, or tell the user before you push. Never let an auto-merge race a review you were asked to complete.
+- **Whether a bot review actually ran.** A `SUCCESS` status from a review bot can still mean "rate-limited, never reviewed" — read its comment body, not just the check state.
+
+### 2. Rebase onto the base branch
+
+Require a clean tree first (`git status --porcelain` empty), then:
+
+```bash
+git fetch origin <base>
+git rebase origin/<base>
+```
+
+Resolve conflicts by **understanding both sides**, not by picking one. Read the base-side commit that introduced the conflicting hunk (`git log -1 --format=%s <base> -- <file>`, then the diff) — a conflict usually means main changed an invariant your branch is unaware of, and blindly keeping "your" side silently reverts it. State in the PR comment which invariant you preserved and why.
+
+After resolving, re-run the tests before continuing — a rebase that compiles is not a rebase that works.
+
+### 3. Sweep every review source
+
+Collect findings from all of these; do not stop at the first:
+
+```bash
+# inline review threads (all bots + humans), with resolution state
+gh api repos/{owner}/{repo}/pulls/<PR>/comments --paginate
+# rollup issue comments (where CodeRabbit/Qodo post summaries and rate-limit notices)
+gh api repos/{owner}/{repo}/issues/<PR>/comments --paginate
+# formal reviews
+gh pr view <PR> --json reviews
+```
+
+**Delegate to the dedicated loop skill when one exists** rather than reimplementing its bot's protocol — `qodoloop` for Qodo, `coderabbitloop` for CodeRabbit, `greploop` for Greptile. Each already encodes that bot's posting shape, its ready-made per-finding fix prompt, and its real terminal states. Use this skill's own sweep for human comments and for bots without a dedicated loop.
+
+Triage every finding into exactly one bucket:
+
+| Bucket | Action |
+|---|---|
+| **Real defect** | Fix it. This is the point of the exercise. |
+| **Legitimate improvement** | Fix it if it's in scope for this PR. |
+| **False positive** | Reply explaining *specifically* why the bot is wrong. Do not resolve silently. |
+| **Needs a human call** | Reply, leave open, surface in the final report. |
+
+Bot findings are suggestions from something that has not run the code. A "🐞 Bug" label is a hypothesis — verify it against the actual source before fixing, and against the actual behavior before dismissing.
+
+### 4. Close the coverage gap
+
+Ask, for the change as a whole, what would catch a regression here — then check whether the PR actually has it.
+
+- **Unit / integration tests:** does every new branch have a test that fails if you invert it? Bots frequently and correctly flag helper functions exercised only *indirectly* through a caller. A direct test per branch is cheap and is usually the right response.
+- **Browser / E2E tests:** determine whether the repo supports them (`playwright.config.*`, `cypress.config.*`, a `test:e2e` script) **and** whether this change has any surface they can reach. Then do one of exactly two things:
+  - it has a reachable surface → add or extend the E2E spec;
+  - it does not → **say so explicitly in the PR comment**, name why (e.g. "this is entirely inside a Durable Object alarm loop; the E2E harness only serves static assets"), and name the suite that is the real gate.
+
+  Silence here reads as an oversight. An explicit "not applicable, because X" reads as diligence — and is checkable.
+
+### 5. Run the real gates
+
+Discover them from the repo (`Makefile`, `package.json` scripts, CI workflow) — do not guess target names. Run, at minimum, the equivalents of:
+
+```bash
+<lint>        # e.g. make lint / npm run lint
+<format>      # check mode first; only write if it reports drift
+<tests>       # the suite covering the changed package
+```
+
+Capture exit codes, not just output. Repo-specific traps worth checking for before you burn a cycle: linters whose cache replays findings from deleted sibling worktrees, formatters whose local toolchain version outruns CI's (churning unrelated files), and test runners that hang when two runs overlap.
+
+If a gate fails, fix it. Do not push red.
+
+### 6. Push and explain
+
+Stage only the files you touched, commit, and push (`--force-with-lease` after a rebase — never bare `--force`).
+
+Then post **one** PR comment that a reviewer can audit without re-reading the diff:
+
+- what the rebase conflict was and which side won, with the reason;
+- each finding, and what you did about it (including the ones you rejected, with the argument);
+- the coverage decision from step 4, including the explicit not-applicable if that's the answer;
+- **verbatim** gate output — real numbers (`# pass 480 / # fail 0`, `0 issues.`), not adjectives.
+
+Re-trigger any bot that never actually reviewed (e.g. `@coderabbitai review`) so the PR gets the pass it was owed.
+
+### 7. Verify and report
+
+Re-read the PR state after the push — confirm `mergeable` flipped, checks went green, and clear now-stale labels (`needs-rebase`, etc.). Poll re-triggered bots for their new pass and handle anything it raises.
+
+```text
+PR #965 finalized.
+  Rebase:      1 conflict resolved (kept main's #834 D1-first ordering)
+  Findings:    2 addressed, 0 rejected, 0 blocked
+  Coverage:    +5 unit tests; E2E not applicable (no browser surface) — stated on the PR
+  Gates:       tests 480/480, lint 0 issues, format clean
+  State:       MERGEABLE, checks green
+  Needs human: none
+```
+
+If anything is left, say precisely what and why — an honest "blocked on X" is the deliverable when X is genuinely a human call.
+
+## Related skills
+
+- `qodoloop` — full Qodo thread protocol (per-finding Agent Prompts, resolve mutations).
+- `coderabbitloop` — full CodeRabbit protocol.
+- `greploop` — drives a PR to a 5/5 Greptile confidence score.
+- `ci-fix-loop` — when the blocker is a failing pipeline rather than review feedback.

package/.windsurf/rules/codexloop.md

@@ -0,0 +1,253 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Iteratively drives a GitHub PR to zero unresolved OpenAI Codex review comments — but verifies every finding against the real code first, fixes only the correct ones, and rebuts false positives without changing correct code."
+---
+
+# Codexloop
+
+Drive a GitHub PR until Codex has no unresolved review comments — **but do not cargo-cult its
+suggestions.** Every comment is a *claim to verify*, not an instruction to obey. A wrong
+suggestion applied is worse than the comment itself.
+
+## How Codex differs from Greptile / Gemini
+
+- **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).
+- **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.
+- **Priority, not confidence.** Codex findings usually lead with a severity/priority word (`P1`,
+  `P2`, `P3` or `critical`/`major`/`minor`) or a short titled heading. Weight the top tier
+  seriously; treat the bottom tier as usually-skippable nits unless clearly correct.
+- **Codex is terse and often reasons from the diff alone.** Its characteristic failure is
+  confidently asserting a bug based only on the changed hunk, without the surrounding file or the
+  call sites. That makes "read the whole file before believing it" the single highest-value check.
+
+## Not for
+
+- GitLab / Perforce (Codex code review is a GitHub app). For other review bots this catalog ships
+  `geminiloop`, `coderabbitloop`, and `qodoloop`; for CI failures rather than review comments, use
+  `ci-fix-loop`.
+
+## 0. Resolve the Codex bot login (do this first, do not hardcode)
+
+The connector's bot login varies by installation, so discover it from the PR rather than
+assuming it:
+
+```bash
+gh api repos/{owner}/{repo}/pulls/<PR>/reviews --paginate --jq '.[].user.login' | sort -u
+gh api repos/{owner}/{repo}/pulls/<PR>/comments --paginate --jq '.[].user.login' | sort -u
+```
+
+Pick the login matching `*codex*` (commonly `chatgpt-codex-connector[bot]`, sometimes
+`codex[bot]`) and export it as `BOT`.
+
+**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;
+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
+then say so and stop, rather than looping against nothing.
+
+## 1. Identify the PR
+
+```bash
+gh pr view --json number,headRefName,headRefOid -q '{number,branch:.headRefName,head:.headRefOid}'
+```
+
+Switch to the PR branch if not already on it. Capture `OWNER`/`REPO` (`gh repo view --json owner,name`).
+
+## 2. The loop (max 5 iterations)
+
+Keep an explicit iteration counter and stop at 5 — the cap is a real bound to enforce, not a
+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:
+HAVE=$(gh api repos/{owner}/{repo}/pulls/<PR>/reviews --paginate \
+  --jq "[.[] | select(.user.login==\"$BOT\" and .commit_id==\"$HEAD_SHA\")] | length")
+if [ "$HAVE" = "0" ]; then gh pr comment <PR> --body "@codex review"; fi
+```
+
+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.
+
+```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 "[.[] | select(.user.login==\"$BOT\" and .commit_id==\"$HEAD_SHA\")] | 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
+```
+
+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.
+
+### B. Fetch the findings
+
+- **Summary**: the review `.body` from the object above — read the overall take and the priority
+  spread.
+- **Unresolved inline comments** on the current head:
+
+```bash
+gh api repos/{owner}/{repo}/pulls/<PR>/comments --paginate \
+  --jq ".[] | select(.user.login==\"$BOT\") | {id, path, line, body}"
+```
+
+Also pull the review threads + their resolved state via GraphQL (see step F) so you only act on
+unresolved ones.
+
+### C. Critically evaluate EACH comment (the core of this skill)
+
+For every comment, **verify the claim against the actual code and repo conventions before touching
+anything.** Read the whole file — not just the diff hunk Codex saw — plus the types and the call
+sites. Then classify:
+
+1. **CORRECT + actionable** — the finding is real and the fix improves the code. → fix it (step D).
+2. **FALSE POSITIVE / technically wrong** — the claim doesn't hold. → do **NOT** change code; write a
+   specific, evidence-based reply (cite the exact code/line/behavior that disproves it), then resolve.
+3. **Valid but out-of-scope / stylistic nit** that conflicts with repo convention or the PR's intent
+   → briefly decline with a reason, then resolve. Do not expand the PR's scope to satisfy a nit.
+
+**Hard rules:**
+- **Never modify correct code just to silence Codex.** Prefer a reasoned rebuttal.
+- When uncertain whether a claim holds, **investigate** (read more code, run the type-checker / tests)
+  rather than assume Codex is right. Default to skepticism.
+- If a suggested change would break other call sites, alter public behavior, or contradict a verified
+  repo convention, it is a category-2 rebuttal, not a fix.
+- Never fabricate identifiers to satisfy a comment (e.g. a Linear/ticket prefix). If Codex asks for a
+  ticket reference and none exists, say so; do not invent one.
+
+**Codex's common failure modes to watch for (default these to category 2):**
+- Diff-local reasoning: asserts a bug that the unchanged surrounding code already handles.
+- "This can be null/undefined here" where the type or an earlier guard already rules it out.
+- Invented race conditions or error paths with no actual trigger.
+- Suggestions that compile-break or break other callers.
+- Security/perf warnings with no exploit path or measurable cost.
+- Restating library/framework semantics incorrectly.
+- Style demands that contradict the repo's existing, consistent pattern.
+
+### D. Apply fixes — category 1 only
+
+Make the minimal correct change. Re-run the local gate if the repo has one (typecheck/tests) before
+moving on.
+
+### E. Commit and push FIRST, before resolving anything
+
+Order matters. A resolved thread is a claim that the fix is on the branch, so the push has to
+succeed before the claim is made — otherwise a failed commit or push leaves the PR unfixed with the
+finding marked resolved, and nobody looks at it again.
+
+If step D changed code:
+
+```bash
+# Stage ONLY the files your fixes touched — never `git add -A`, which sweeps up
+# unrelated work and untracked secrets sitting in the worktree.
+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)"
+git push
+```
+
+Author the commit per the repo's norms (e.g. the user's identity; no AI attribution if that is the
+convention). Confirm the push actually landed before continuing:
+
+```bash
+git rev-parse HEAD
+gh pr view <PR> --json headRefOid -q .headRefOid   # must match
+```
+
+If they differ, stop: the fix is not on the PR, so nothing may be resolved yet.
+
+### 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
+```
+
+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:
+
+```bash
+gh api graphql -f query='mutation { resolveReviewThread(input: {threadId: "THREAD_ID"}) { thread { isResolved } } }'
+```
+
+Resolve a thread only for comments authored by `$BOT` that you have fixed or rebutted — never
+blanket-resolve, and never resolve a human reviewer's thread.
+
+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
+
+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.
+
+## 3. Exit conditions
+
+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.
+
+## 4. Report
+
+```text
+Codexloop complete.
+  PR:                 #<n>
+  Bot login:          <resolved $BOT>
+  Iterations:         N
+  Comments fixed:     N   (genuinely-correct findings)
+  Comments rebutted:  N   (false positives / nits, resolved with rationale)
+  Remaining:          0
+```
+
+If it stopped at max iterations, list the remaining threads with your current assessment
+(fix-pending vs disputed) so a human can arbitrate.