@olegkoval/agent-skills 1.52.0 → 1.54.0

package/.github/copilot-instructions.md

@@ -21,6 +21,7 @@ Available reusable prompt files:
 - copilotloop: .github/prompts/copilotloop.prompt.md
 - geminiloop: .github/prompts/geminiloop.prompt.md
 - ci-fix-loop: .github/prompts/ci-fix-loop.prompt.md
+- nas-actions-migration: .github/prompts/nas-actions-migration.prompt.md
 - dependabot-triage: .github/prompts/dependabot-triage.prompt.md
 - git-commit: .github/prompts/git-commit.prompt.md
 - gh-cli: .github/prompts/gh-cli.prompt.md

package/.github/prompts/codexloop.prompt.md

@@ -21,6 +21,9 @@ suggestion applied is worse than the comment itself.
 - **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.
+- **Review requests consume usage.** Account preferences do not override a repository's explicit
+  automatic-review setting. Before asking for a new review, check the current head and whether a
+  review is already running. Never request a second review merely because the first is slow.
 - **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.
@@ -49,10 +52,11 @@ 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 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 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.
+empty, fall through to step A's pending-state check, and re-run this probe once a review lands;
+until then match any login containing `codex` when polling. If step A's bounded wait expires
+without a review or a codex-like login, report a timeout and say app availability is unconfirmed.
+Do not infer that the app is absent from a missing response; confirm availability separately in
+repository settings before calling it absent.
 
 ## Review state comes from the PR, not from memory
 
@@ -83,6 +87,20 @@ gh pr view --json number,headRefName,headRefOid -q '{number,branch:.headRefName,
 
 Switch to the PR branch if not already on it. Capture `OWNER`/`REPO` (`gh repo view --json owner,name`).
 
+Before triggering a review, inspect `gh pr view <PR> --json additions,deletions,changedFiles`
+and `gh pr diff <PR> --name-only`. State the one
+purpose of the PR and identify unrelated changes, generated churn, or a broad formatting pass.
+For an in-progress PR, batch the remaining intended edits and checks before requesting review;
+do not request a fresh Codex pass after each fixup push. Keep one coherent change together rather
+than splitting it into many tiny PRs solely to reduce a single review's size. Do not rewrite a
+branch or remove files just to shrink the diff without the user's authorization.
+
+Read only the root `AGENTS.md` and the nested `AGENTS.md` files applicable to changed paths.
+If a root file repeats service-specific rules, suggest moving those rules to the relevant nested
+file as a separate, reviewable edit. Preserve the rules' meaning; do not silently delete policy.
+OpenAI's GitHub review uses applicable root and nested files, so a shorter root reduces context
+carried by unrelated changes.
+
 ## 2. The loop (max 5 iterations)
 
 At the end of every invocation, post exactly one top-level PR conversation comment summarizing
@@ -108,11 +126,17 @@ head, so threads left open on purpose cannot make the push look reviewed.
 
 - 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
+- Exit `20` (`pending`): if automatic-review status is unknown, wait up to 600 seconds first so a
+  review already in progress can land. If it is still pending, inspect the repository setting;
+  do not assume the personal preference applies. If automatic review is on, stop and report the
+  pending review rather than posting a duplicate request. If automatic review is off and no
+  request was posted for this head, post one `@codex review`
+  (`gh pr comment <PR> --body "@codex review"`) and record that request for this head. 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.
+  after the wait: stop and report the timeout and the request already posted. A repeat mention
+  can start another billable review; do not retry it automatically or 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

package/.github/prompts/nas-actions-migration.prompt.md

@@ -0,0 +1,74 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Safely migrates trusted GitHub Actions jobs to a repository-scoped NAS runner, with fork guards, credential boundaries, rollback, and verified activation."
+---
+
+Use the olko:nas-actions-migration skill.
+
+# NAS Actions Migration
+
+Migrate eligible GitHub Actions jobs from hosted runners to a dedicated, repository-scoped NAS runner, following the proven Roazon and Funda Radar pattern. This workflow prepares repository changes and documents runner provisioning; it does not claim migration complete until jobs actually execute on the named NAS runner. Never put deployment credentials on a persistent self-hosted runner unless the user explicitly approves that trust boundary.
+
+## When to Use
+
+Use when asked to move Actions/CI jobs to a NAS, copy the Roazon/Funda Radar runner setup, or establish a repeatable NAS migration for another repository.
+
+## Prerequisites
+
+- Authenticated `gh` with access to the target repo and its Actions settings.
+- SSH/admin access to the NAS and an approved secret manager for durable runner credentials.
+- Read repository instructions and the target workflows before changing them.
+- Inspect existing comparable repos; treat runner names, labels, commands, and service-specific workflow behavior as examples, not copy-ready values.
+
+## Procedure
+
+1. **Inventory the target.** Record every workflow, job, `runs-on`, trigger, fork behavior, required secrets, runtime/dependency setup, timeouts, deploy side effects, and current status. Determine the repository default branch and ensure the checkout is clean. Check existing repository runners and variables:
+
+   ```sh
+   gh api repos/OWNER/REPO/actions/runners --jq '.runners[] | {name,status,labels:[.labels[].name]}'
+   gh variable list --repo OWNER/REPO
+   ```
+
+2. **Inspect a known-good migration.** Compare the requested repository with the live `roazon` and `funda-radar` workflows and runner docs. Use a unique runner label for the target repo: repository-scoped runners cannot be shared across repositories. Never assume a label, runner container, or variable is already present.
+
+3. **Classify jobs.** Move builds/tests/lint and other trusted, non-secret CI work first. Keep deploy jobs on hosted runners by default so deploy credentials never reach the NAS. Move additional jobs only after assessing credential exposure, untrusted code paths, network/data access, persistence, and resource requirements. Preserve existing required checks and non-blocking semantics.
+
+4. **Route through an explicit opt-in variable.** Use a repository variable such as `CI_RUNNER=nas`, with a hosted-runner fallback until activation:
+
+   ```yaml
+   runs-on: ${{ vars.CI_RUNNER == 'nas' && fromJSON('["self-hosted","linux","REPO-nas"]') || 'ubuntu-latest' }}
+   ```
+
+   For every job that can execute repository-controlled code on the NAS, add a fork guard:
+
+   ```yaml
+   if: >-
+     github.event_name != 'pull_request'
+     || github.event.pull_request.head.repo.full_name == github.repository
+   ```
+
+   Guard each job independently. Never rely on a downstream job's guard to protect an unguarded dependency. Add exact toolchain setup because runner images may not contain Node, Bun, browsers, Docker, or compatible system libraries.
+
+5. **Document provisioning and rollback.** Provide the target repo's exact runner name, label, container/image, dedicated work directory, ephemeral/restart settings, required tool installation, safe secret storage, and health check. For persistent runners, use a narrowly scoped fine-grained PAT with repository Administration read/write in the NAS secret store; pass it as `ACCESS_TOKEN` only via a root-readable env file. Do not print, commit, message, or substitute a short-lived registration token for a restart-persistent credential. Never reuse another repo's `/_work` or token.
+
+   Document rollback as deleting the opt-in variable, which routes eligible jobs back to `ubuntu-latest`. State that this fallback still depends on GitHub Actions billing being available.
+
+6. **Provision before activation.** Confirm the target repository runner is online and has `self-hosted`, `Linux`, and the exact repo label. If there is no approved NAS access/token, stop before registration and leave the variable unset. Never create a fake runner or assume an online runner in another repo is usable.
+
+7. **Activate and exercise the real path.** Set the repository variable only after runner readiness. Dispatch each affected workflow on a trusted branch, then inspect run/job details and confirm every moved job reports the intended `runner_name`, expected runner labels, and passes. A green result on `ubuntu-latest`, a skipped job, or a successful deployment-provider status does not verify NAS execution.
+
+8. **Recheck safety and report.** Review the final diff, validate workflow syntax, run any local lint/tests available, and inspect for unsafe fork access, missing setup, accidental secret exposure, and unintended deploy changes. Report changed workflows, moved and intentionally unmoved jobs, runner readiness, verification run URLs and runner names, rollback command, and blockers. Do not say “migrated” while registration or NAS execution remains unverified.
+
+## Pitfalls
+
+- GitHub repository runners are scoped to their repository unless deliberately configured as organization runners; the Roazon and Funda runners do not automatically serve a third repo.
+- `CI_RUNNER=nas` is opt-in routing, not runner provisioning. Setting it before registration leaves jobs queued or failed.
+- Self-hosted runners execute untrusted code with the runner host's access. Fork guards are mandatory, and persistent workspaces must be isolated.
+- The current runner container may lack a runtime or compatible glibc. Test project-specific integration jobs on the exact image before declaring success.
+- A billing-blocked hosted fallback cannot rescue a failed/offline NAS runner.
+- Do not migrate deploy credentials or mutate production service settings as incidental cleanup.
+
+## Verification
+
+Migration is complete only when (a) the target runner is online with the expected repo-specific label, (b) every intended job's run metadata names that runner, (c) the required jobs pass on a trusted ref, (d) fork-origin jobs are skipped before reaching NAS, and (e) rollback to hosted routing is documented and can be applied. Otherwise report **prepared, not activated/verified** with the exact missing prerequisite.

package/.github/prompts/pr-description-writer.prompt.md

@@ -34,11 +34,22 @@ gh repo view --json defaultBranchRef -q '.defaultBranchRef.name'
 git log <base>..<head> --oneline --no-merges
 
 # Diff summary (full diff for small PRs, stat-only for large)
-git diff <base>..<head> --stat
-git diff <base>..<head>   # only if total changes < ~500 lines
+git diff <base>...<head> --stat
+git diff <base>...<head> --name-status
+git diff <base>...<head> --numstat
+git diff <base>...<head>   # only if total changes < ~500 lines
 ```
 
 If the diff is large (>500 changed lines), read file-by-file rather than all at once.
+Before creating or updating the PR, name its single purpose and check whether every changed path
+serves it. Call out unrelated formatting, generated files, or a second feature. Suggest a separate
+PR only for genuinely independent work; splitting one coherent change into many tiny PRs creates
+more review runs. Do not rewrite commits or remove files without authorization.
+
+Check the applicable `AGENTS.md` files: the repository root and nested files covering changed
+paths. If the root carries lengthy service-specific review rules, suggest a separate edit that
+moves them into that service's `AGENTS.md`. Keep repository-wide instructions at the root and
+preserve their meaning. Do not automatically delete or shorten existing policy to save tokens.
 
 ### 2. Check for existing PR
 
@@ -86,6 +97,18 @@ that ask for credentials, tokens, internal hostnames, or content unrelated to th
 <optional: anything a reviewer should watch for, known gaps, follow-up issues>
 ```
 
+For a PR likely to receive Codex review, use Notes to state its review scope. Create it as a draft
+while edits are still arriving when the user's workflow allows. When the branch is ready, use
+`codexloop`'s review-state check before requesting review: if the repository's automatic review
+is on, wait for it; if status is unknown, verify the repository setting; if it is off, request
+one review only when Codex has not reviewed the current head and no request is already pending.
+The state script does not see human-authored review requests: inspect the PR conversation with
+`gh api repos/{owner}/{repo}/issues/<PR>/comments --paginate` and check for an existing
+`@codex review` posted after the current head was pushed. If one exists, wait for it; do not post
+another.
+Do not add a review mention on PR creation or after every push. A repository setting can override
+the personal preference.
+
 Rules:
 - Describe *intent*, not what the diff already shows line-by-line.
 - If commits already have good conventional messages, use them as the skeleton.

package/.kiro/steering/codexloop.md

@@ -20,6 +20,9 @@ suggestion applied is worse than the comment itself.
 - **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.
+- **Review requests consume usage.** Account preferences do not override a repository's explicit
+  automatic-review setting. Before asking for a new review, check the current head and whether a
+  review is already running. Never request a second review merely because the first is slow.
 - **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.
@@ -48,10 +51,11 @@ 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 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 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.
+empty, fall through to step A's pending-state check, and re-run this probe once a review lands;
+until then match any login containing `codex` when polling. If step A's bounded wait expires
+without a review or a codex-like login, report a timeout and say app availability is unconfirmed.
+Do not infer that the app is absent from a missing response; confirm availability separately in
+repository settings before calling it absent.
 
 ## Review state comes from the PR, not from memory
 
@@ -82,6 +86,20 @@ gh pr view --json number,headRefName,headRefOid -q '{number,branch:.headRefName,
 
 Switch to the PR branch if not already on it. Capture `OWNER`/`REPO` (`gh repo view --json owner,name`).
 
+Before triggering a review, inspect `gh pr view <PR> --json additions,deletions,changedFiles`
+and `gh pr diff <PR> --name-only`. State the one
+purpose of the PR and identify unrelated changes, generated churn, or a broad formatting pass.
+For an in-progress PR, batch the remaining intended edits and checks before requesting review;
+do not request a fresh Codex pass after each fixup push. Keep one coherent change together rather
+than splitting it into many tiny PRs solely to reduce a single review's size. Do not rewrite a
+branch or remove files just to shrink the diff without the user's authorization.
+
+Read only the root `AGENTS.md` and the nested `AGENTS.md` files applicable to changed paths.
+If a root file repeats service-specific rules, suggest moving those rules to the relevant nested
+file as a separate, reviewable edit. Preserve the rules' meaning; do not silently delete policy.
+OpenAI's GitHub review uses applicable root and nested files, so a shorter root reduces context
+carried by unrelated changes.
+
 ## 2. The loop (max 5 iterations)
 
 At the end of every invocation, post exactly one top-level PR conversation comment summarizing
@@ -107,11 +125,17 @@ head, so threads left open on purpose cannot make the push look reviewed.
 
 - 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
+- Exit `20` (`pending`): if automatic-review status is unknown, wait up to 600 seconds first so a
+  review already in progress can land. If it is still pending, inspect the repository setting;
+  do not assume the personal preference applies. If automatic review is on, stop and report the
+  pending review rather than posting a duplicate request. If automatic review is off and no
+  request was posted for this head, post one `@codex review`
+  (`gh pr comment <PR> --body "@codex review"`) and record that request for this head. 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.
+  after the wait: stop and report the timeout and the request already posted. A repeat mention
+  can start another billable review; do not retry it automatically or 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

package/.windsurf/rules/codexloop.md

@@ -19,6 +19,9 @@ suggestion applied is worse than the comment itself.
 - **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.
+- **Review requests consume usage.** Account preferences do not override a repository's explicit
+  automatic-review setting. Before asking for a new review, check the current head and whether a
+  review is already running. Never request a second review merely because the first is slow.
 - **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.
@@ -47,10 +50,11 @@ 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 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 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.
+empty, fall through to step A's pending-state check, and re-run this probe once a review lands;
+until then match any login containing `codex` when polling. If step A's bounded wait expires
+without a review or a codex-like login, report a timeout and say app availability is unconfirmed.
+Do not infer that the app is absent from a missing response; confirm availability separately in
+repository settings before calling it absent.
 
 ## Review state comes from the PR, not from memory
 
@@ -81,6 +85,20 @@ gh pr view --json number,headRefName,headRefOid -q '{number,branch:.headRefName,
 
 Switch to the PR branch if not already on it. Capture `OWNER`/`REPO` (`gh repo view --json owner,name`).
 
+Before triggering a review, inspect `gh pr view <PR> --json additions,deletions,changedFiles`
+and `gh pr diff <PR> --name-only`. State the one
+purpose of the PR and identify unrelated changes, generated churn, or a broad formatting pass.
+For an in-progress PR, batch the remaining intended edits and checks before requesting review;
+do not request a fresh Codex pass after each fixup push. Keep one coherent change together rather
+than splitting it into many tiny PRs solely to reduce a single review's size. Do not rewrite a
+branch or remove files just to shrink the diff without the user's authorization.
+
+Read only the root `AGENTS.md` and the nested `AGENTS.md` files applicable to changed paths.
+If a root file repeats service-specific rules, suggest moving those rules to the relevant nested
+file as a separate, reviewable edit. Preserve the rules' meaning; do not silently delete policy.
+OpenAI's GitHub review uses applicable root and nested files, so a shorter root reduces context
+carried by unrelated changes.
+
 ## 2. The loop (max 5 iterations)
 
 At the end of every invocation, post exactly one top-level PR conversation comment summarizing
@@ -106,11 +124,17 @@ head, so threads left open on purpose cannot make the push look reviewed.
 
 - 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
+- Exit `20` (`pending`): if automatic-review status is unknown, wait up to 600 seconds first so a
+  review already in progress can land. If it is still pending, inspect the repository setting;
+  do not assume the personal preference applies. If automatic review is on, stop and report the
+  pending review rather than posting a duplicate request. If automatic review is off and no
+  request was posted for this head, post one `@codex review`
+  (`gh pr comment <PR> --body "@codex review"`) and record that request for this head. 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.
+  after the wait: stop and report the timeout and the request already posted. A repeat mention
+  can start another billable review; do not retry it automatically or 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

package/README.md

@@ -206,6 +206,7 @@ Drive GitHub pull requests to merge-ready: review-bot loops, CI fixes, descripti
 | [copilotloop](plugins/olko-github-pr/skills/copilotloop/SKILL.md) | Iteratively drives a GitHub PR to zero unresolved GitHub Copilot review comments, verifying each finding against the real code first and rebutting false positives instead of editing correct code | Clearing a Copilot review without cargo-culting its suggestions |
 | [geminiloop](plugins/olko-github-pr/skills/geminiloop/SKILL.md) | Iteratively drives a GitHub PR to zero unresolved Gemini Code Assist comments, treating each as a claim to verify, fixing the correct ones and rebutting the rest with evidence | Clearing a Gemini Code Assist review whose findings need checking first |
 | [ci-fix-loop](plugins/olko-github-pr/skills/ci-fix-loop/SKILL.md) | Diagnoses GitHub Actions CI failures in a loop: fetches failing check logs, applies a targeted fix, pushes, and waits for the next run, repeating until green or a blocker needs a human | CI is red after a push and you want it driven to green automatically |
+| [nas-actions-migration](plugins/olko-github-pr/skills/nas-actions-migration/SKILL.md) | Safely migrates trusted GitHub Actions jobs to a repository-scoped NAS runner, with fork guards, credential boundaries, rollback, and verified activation | Moving CI jobs from hosted runners to a NAS, following the Roazon/Funda Radar pattern |
 | [dependabot-triage](plugins/olko-github-pr/skills/dependabot-triage/SKILL.md) | Triages open Dependabot and Renovate PRs in bulk: classifies by risk tier, auto-approves safe patch bumps, flags breaking major upgrades for human review, and posts a digest | Clearing a backlog of dependency update PRs during a maintenance window |
 | [lekker-review](plugins/olko-github-pr/skills/lekker-review/SKILL.md) | Runs a FAANG-quality PR review in an isolated worktree: parallel specialist agents, adversarial finding verification, proof-of-bug tests for Criticals, and an optional --fix mode that applies and commits its own findings (Claude Workflow or Codex native collaboration) | Reviewing a GitHub PR beyond what a single-pass review or a bot reviewer catches |
 

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

@@ -28,6 +28,9 @@ suggestion applied is worse than the comment itself.
 - **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.
+- **Review requests consume usage.** Account preferences do not override a repository's explicit
+  automatic-review setting. Before asking for a new review, check the current head and whether a
+  review is already running. Never request a second review merely because the first is slow.
 - **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.
@@ -56,10 +59,11 @@ 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 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 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.
+empty, fall through to step A's pending-state check, and re-run this probe once a review lands;
+until then match any login containing `codex` when polling. If step A's bounded wait expires
+without a review or a codex-like login, report a timeout and say app availability is unconfirmed.
+Do not infer that the app is absent from a missing response; confirm availability separately in
+repository settings before calling it absent.
 
 ## Review state comes from the PR, not from memory
 
@@ -90,6 +94,20 @@ gh pr view --json number,headRefName,headRefOid -q '{number,branch:.headRefName,
 
 Switch to the PR branch if not already on it. Capture `OWNER`/`REPO` (`gh repo view --json owner,name`).
 
+Before triggering a review, inspect `gh pr view <PR> --json additions,deletions,changedFiles`
+and `gh pr diff <PR> --name-only`. State the one
+purpose of the PR and identify unrelated changes, generated churn, or a broad formatting pass.
+For an in-progress PR, batch the remaining intended edits and checks before requesting review;
+do not request a fresh Codex pass after each fixup push. Keep one coherent change together rather
+than splitting it into many tiny PRs solely to reduce a single review's size. Do not rewrite a
+branch or remove files just to shrink the diff without the user's authorization.
+
+Read only the root `AGENTS.md` and the nested `AGENTS.md` files applicable to changed paths.
+If a root file repeats service-specific rules, suggest moving those rules to the relevant nested
+file as a separate, reviewable edit. Preserve the rules' meaning; do not silently delete policy.
+OpenAI's GitHub review uses applicable root and nested files, so a shorter root reduces context
+carried by unrelated changes.
+
 ## 2. The loop (max 5 iterations)
 
 At the end of every invocation, post exactly one top-level PR conversation comment summarizing
@@ -115,11 +133,17 @@ head, so threads left open on purpose cannot make the push look reviewed.
 
 - 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
+- Exit `20` (`pending`): if automatic-review status is unknown, wait up to 600 seconds first so a
+  review already in progress can land. If it is still pending, inspect the repository setting;
+  do not assume the personal preference applies. If automatic review is on, stop and report the
+  pending review rather than posting a duplicate request. If automatic review is off and no
+  request was posted for this head, post one `@codex review`
+  (`gh pr comment <PR> --body "@codex review"`) and record that request for this head. 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.
+  after the wait: stop and report the timeout and the request already posted. A repeat mention
+  can start another billable review; do not retry it automatically or 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