@openhands/extensions 0.23.0 → 0.25.0

package/skills/github-pr-reviewer/README.md

@@ -12,9 +12,49 @@ This skill is activated by:
 ## Features
 
 - Reviews PRs on demand from a GitHub reviewer request or label event
+- Gates each scheduled review on the current head's GitHub-required checks
+  before starting an agent, read through the `isRequired` signal, so an optional
+  workflow that fails cannot block a mergeable head: a completed `failure`,
+  `cancelled`, or `timed_out` required check blocks the review, and a `queued`,
+  `in_progress`, or not-yet-reported required check exits with a clear
+  waiting-on-checks outcome instead of holding a slot. If the required-check
+  signal is unavailable the gate falls back to every current-head check run and
+  workflow run, including a workflow that fails before creating any check run
+- Dispatches an explicit `all-hands-bot` review request even when required CI is
+  red or pending; the CI gate applies to scheduled discovery
+- Ignores checks and workflow runs recorded for an obsolete head, so a stale
+  failure cannot block the push that fixed it
+- Resumes an outstanding reviewer request on the next scheduled scan once the
+  requested head's checks are green, so a request that arrives during CI is not
+  lost; the explicit-request event path is kept for event-only deployments
+- Reviews open, non-draft PRs that nobody requested on a scheduled scan once
+  their current head is green and carries no review yet, keyed by
+  repository/PR/head so a repeat scan never duplicates a conversation or review
+  and a changed head becomes eligible again
+- Examines a bounded, rotating window of that unrequested backlog per scan
+  (10 PRs per repository), remembering its position in the Automation KV store so
+  the next scan resumes past it; explicit requests and trigger labels are always
+  examined, never skipped behind the window
+- Posts no managed gate comment for an unrequested PR that is merely red or
+  pending - the comment answers an explicit request, so a scan over a large
+  backlog cannot storm the PRs with comments
+- Names the retry the deployment actually has in the waiting comment: a
+  scheduled scan where a cron trigger exists, and removing and re-requesting the
+  bot where only the event trigger does
+- Rewrites its own managed gate comment in place when the retry wording changes,
+  so switching a deployment from the event trigger to a cron scan updates the
+  outstanding-request explanation instead of leaving the old instruction
 - Watches several repositories from a single automation, each with its own state
+- Bounds a scheduled scan to a small, configurable number of new review
+  conversations across all repositories (default 2), draining the oldest
+  outstanding reviewer requests first and reaching the rest on later scans
 - Processes each review request or label application idempotently
-- Supports re-review by requesting the bot again or re-applying the label
+- Supports re-review by requesting the bot again or re-applying the label. Each
+  explicit request refreshes mutable GitHub state (head, PR body, reviews,
+  comments, review requests, linked issues, and current-head checks) instead of
+  trusting what an earlier turn observed, so a same-head re-review sees a linked
+  issue that has since gained or lost readiness, or a check that has since moved.
+  Repository analysis already done, such as reading `AGENTS.md`, is retained
 - Suppresses stale reviews when the PR head commit changes mid-review
 - Hands the agent the reviewed commit already checked out, and removes that
   checkout when the review ends, so nothing accumulates between runs

package/skills/github-pr-reviewer/SKILL.md

@@ -25,9 +25,178 @@ once per label event, and publishes the AI review to GitHub.
 Windows PowerShell equivalents for the setup, packaging, upload, and API-check shell snippets are in `references/windows.md`.
 
 The automation script is deterministic: PR discovery, label-event tracking,
-state persistence, stale-result suppression, the repository checkout, and its
-removal are all handled in Python. The LLM is invoked only for the review
-itself.
+head eligibility, state persistence, stale-result suppression, the repository
+checkout, and its removal are all handled in Python. The LLM is invoked only for
+the review itself.
+
+Before any review conversation is created, a scheduled scan evaluates the
+current head's GitHub-required checks, read through the GraphQL `isRequired`
+signal for the pull request. That signal is the merge policy's own source of
+truth and is pull-request-scoped, so it stays correct for a stacked PR whose
+symbolic base branch carries no branch rules of its own:
+
+- Only checks GitHub reports as required decide the scheduled gate. An optional
+  workflow that fails - including one that fails before creating any check run -
+  does not block a head whose required checks pass.
+- A completed required run on the exact head whose conclusion is `failure`,
+  `cancelled`, or `timed_out` blocks the review. Any other unrecognized
+  conclusion fails closed as a block rather than silently approving.
+- A completed required run whose conclusion is `success`, `neutral`, or
+  `skipped` does not block. A required `commit status` context is classified
+  alongside required check runs.
+- A `queued` or `in_progress` required run on the exact head, and a required
+  context that has not reported a current-head check run at all, make the run
+  exit with a **waiting on checks** outcome. Unfulfilled is never approval. The
+  worker does not hold a slot polling; the next scheduled scan or explicit
+  review request retries.
+- When the required-check signal cannot be read or is empty, the gate falls back
+  to every current-head check run and workflow run, so a red head still blocks.
+  In that fallback, workflow runs are read as well as check runs, because a
+  workflow can fail before creating any check run - a workflow-level error, or a
+  `pull_request` run whose jobs never start. Such a run leaves a failed check
+  suite with no check runs under it, so the commit's check-run rollup and
+  `gh pr checks` both report success and only the workflow run reveals the red
+  CI. A workflow run whose check suite already reported check runs is left to
+  those runs, so a workflow is never counted twice.
+- A scheduled scan considers the trigger label **and** every open, non-draft PR
+  that still holds an outstanding `all-hands-bot` review request. That is what
+  resumes a request made while CI was running: the request is keyed by its own
+  `review_requested` event, so repeated scans reuse one conversation and one
+  review instead of creating duplicates, and a PR whose request was answered or
+  withdrawn simply drops out of `requested_reviewers`.
+- The scheduled scan also reviews open, non-draft PRs that **nobody requested**
+  and that carry no trigger label, once their current head has no completed
+  review by this account. That is what keeps reviewing PRs after the outstanding
+  requests are exhausted. The delivery key is the stable
+  `scan:{repository}:{number}:{head}`, so repeated scans reuse one conversation
+  and one native review, and a changed head becomes eligible again under its new
+  SHA.
+- The unrequested part of a scan is a **bounded, rotating window**, not the whole
+  backlog. Classifying one unrequested head costs a review read plus the
+  exact-head check and workflow reads, so examining every open PR in one scan
+  spent the run's API budget in the largest repository and announced every red or
+  pending head. A scan examines at most `SCAN_WINDOW` (10) unrequested PRs per
+  repository and stores where the window ended in the automation service's own
+  KV store, under a per-repository `review-scan:{owner}__{repo}` key, so the next
+  scan resumes past that point and the backlog is covered fairly over several
+  scans. The window wraps at the end of the backlog. When the KV store is not
+  available (a local run) the position is kept in memory, so the scan still
+  rotates within the run.
+- An explicit `all-hands-bot` review request or a trigger label is **never**
+  subject to the window: every explicit candidate is examined on every scan,
+  whatever the stored position is, so a request is not delayed behind the
+  rotation.
+- A gate stop on an **unrequested** head posts no managed comment. A PR nobody
+  asked about that is merely red or pending is simply skipped without starting an
+  agent, which is what keeps a scan over a large backlog from posting a gate
+  comment on every PR. The managed comment is the answer to an explicit request,
+  so a requested or labeled head that is red or pending still gets its
+  explanation.
+- Workflow runs are read as well as check runs, because a workflow can fail
+  before creating any check run - a workflow-level error, or a `pull_request`
+  run whose jobs never start. Such a run leaves a failed check suite with no
+  check runs under it, so the commit's check-run rollup and `gh pr checks` both
+  report success and only the workflow run reveals the red CI. A workflow run
+  whose check suite already reported check runs is left to those runs, so a
+  workflow is never counted twice.
+- Runs attributed to any other (obsolete) head SHA are ignored, so a stale
+  failure cannot block the push that fixed it. This applies to workflow runs
+  too.
+- Only the latest run of each logical check or workflow counts. A logical check
+  is its name plus the reporting app identity, and a logical workflow is its
+  name plus workflow ID. The latest is chosen by the run ID (the reliable
+  creation sequence) with the start time as a tie-break, so a re-run that fixed
+  a check supersedes its earlier failure on the same SHA while a newer queued or
+  in-progress re-run supersedes an earlier success and makes the head wait.
+  Ordering by the run ID keeps a run whose start time is still absent in its
+  true creation position in both directions.
+
+An explicit `all-hands-bot` review request is the intake-policy exception: the
+caller asked for that head by name, so the request dispatches even when required
+CI is red or pending, and the gate leaves no explanatory comment. Draft, scope,
+exact-head, and delivery-deduplication safeguards still apply. A blocked or
+waiting scheduled stop consumes no trigger: once the head's required checks are
+non-blocking, the scheduled scan, or a new `all-hands-bot` review request,
+starts the normal review.
+
+The gate needs no configured list of check names. When it stops a review it
+leaves one concise explanation on the PR, identified by a hidden marker carrying
+the head SHA and gate category, so a later run for a different head updates that
+comment instead of posting another. Only a marker this reviewer account authored
+counts as its own comment; every other PR comment is untrusted and can neither
+suppress the explanation nor be edited. If the repository's own workflow already
+posted a deterministic remediation comment that names the same current-head
+checks, the gate adds nothing; a disclosure about some other check does not
+suppress it. The gate applies to scheduled label scans; an explicit
+`all-hands-bot` review request bypasses it by design.
+
+Each explicit review request - a re-applied trigger label, or a new reviewer
+request in event mode - is a fresh review. The conversation for a PR is reused,
+but its earlier turns must not be trusted as current: before deciding a verdict
+the reviewer re-fetches the mutable GitHub state (the exact head, the PR body,
+review comments and threads, review requests, the linked issues' bodies and
+labels, and the current-head Actions results) and ignores any earlier finding,
+verdict, or label/priority claim that state no longer supports. Repository
+analysis the conversation already did, such as reading `AGENTS.md`, stays
+useful and is not repeated.
+
+The waiting and blocked explanations name the retry the deployment actually has.
+A scheduled run proves a scan is configured, so it says the next scan will
+retry. An event-only run does not, so it tells the reader to remove the
+outstanding `all-hands-bot` request and request `all-hands-bot` again instead of
+promising a scan that does not exist: GitHub will not accept a second request
+while the first is still outstanding.
+
+The gate leaves only one explanation per head. When the same head keeps the same
+hidden marker but the retry wording changes -- an event-only comment on a head
+whose automation is later switched to a cron scan -- the scheduled run rewrites
+that managed comment in place, so the comment always names the retry that is
+actually deployed, and an unchanged body is left untouched.
+
+## Bounded intake per scheduled scan
+
+A scheduled scan drains outstanding reviewer requests fairly, but starting an
+agent for every eligible pull request at once would overload the deployment, so
+the scan starts at most `MAX_NEW_PER_RUN` new review conversations, counted
+**across every configured repository** rather than per repository. The default
+is `2`, and the rendered `config.json` overrides it through the
+`max_new_per_run` key that `github-issue-to-pr` and `gitlab-issue-to-mr` already
+use.
+
+- Eligible candidates are ordered deterministically: an explicit `all-hands-bot`
+  request (or a trigger label) is ordered before an unrequested PR, then by the
+  oldest `all-hands-bot` `review_requested` event for a requested PR or the PR's
+  own creation time (oldest first) for an unrequested one, then by repository,
+  then by pull-request number, so the oldest work drains first and a later scan
+  reaches the remainder.
+- The bound counts the conversations a scan **starts**. A delivery that only
+  deduplicates or reports an already-running conversation reuses a runtime and
+  consumes no slot, so repeated scans make progress on the backlog instead of
+  re-spending the bound on work already in flight.
+- Reaching the bound never cuts the scan short. The scan still evaluates the
+  exact-head checks of the remaining candidates, reconciles completed reviews,
+  and runs the maintainer handoff. A candidate whose checks are pending or
+  failing starts no conversation and consumes no slot, so it cannot block a later
+  green candidate. Only an explicit request or a trigger label gets a waiting or
+  blocked gate comment; an unrequested head that is merely red or pending is
+  skipped silently.
+- A dispatch that raises is reported and does not consume a slot or abort the
+  scan, so the candidates behind it are still considered.
+- The explicit `review_requested` event path and the trigger-label scan are
+  unchanged: an explicit request still starts its conversation immediately, and
+  only the scheduled scan's new conversations are bounded.
+
+The review prompt starts with a scope gate: using the repository's own guidance
+(its scope categories and ownership boundaries, not a list of individual PR
+numbers), the reviewer decides whether the change belongs in this repository
+and has the product/architecture direction it needs. When it does not, the review
+stops with a single `event: COMMENT` review that says whether the change should
+move repositories, close, or receive a maintainer decision, and ends with the
+`🛑 MAINTAINER DECISION REQUIRED` verdict. That outcome is **neither an approval
+nor a change request**: it does not approve or merge the PR. The completion
+handler recognizes the verdict and requests one configured maintainer through the
+same handoff used after an approval. An in-scope change continues the existing
+review unchanged.
 
 The script prepares each review's workspace before the agent starts: the pull
 request's head commit is downloaded as a tarball and extracted to a directory of
@@ -154,7 +323,7 @@ Record as `CRON_SCHEDULE`.
 
 ### Step 6 - Generate the automation script
 
-Read `scripts/main.py` from this skill's directory. Apply exactly six constant
+Read `scripts/main.py` from this skill's directory. Apply exactly seven constant
 substitutions near the top of the file:
 
 > The script also reads a `config.json` shipped beside it, if there is one, over
@@ -170,6 +339,7 @@ substitutions near the top of the file:
 | `REVIEW_TONE = "thorough"` | `REVIEW_TONE = "{review_tone}"` |
 | `REVIEW_STYLE_INSTRUCTIONS = ""` | `REVIEW_STYLE_INSTRUCTIONS = "{style_instructions}"` |
 | `REPO_REVIEW_GUIDE_PATH = ".agents/skills/custom-codereview-guide.md"` | leave unchanged to auto-load a repo review guide at this path, or set to `""` to disable |
+| `MAX_NEW_PER_RUN = 2` | leave unchanged to bound a scheduled scan to two new review conversations across all repositories, or raise it if the deployment can hold more agents at once |
 | `DEFAULT_OPENHANDS_URL = "http://localhost:8000"` | leave unchanged unless the user has a preference |
 
 Use a safe string writer such as `json.dumps(value)` when inserting user-provided
@@ -278,7 +448,8 @@ For each repository:
      paths, and symlinks skipped rather than materialised.
    - Starts an OpenHands conversation **whose working directory is that
      checkout**, with a review prompt carrying PR metadata, the exact head SHA,
-     and label event details.
+     label event details, and the requirement to re-fetch the current mutable
+     GitHub state before deciding a verdict.
    - Posts an acknowledgement comment with the label event, head SHA, and
      conversation link.
    - Records the review in state with `status: "active"` and the checkout path.
@@ -325,6 +496,10 @@ The completion callback fires once for the whole run.
 | 404 on repo access | Repo name wrong or no access | Re-check the entry in `REPOS` and the token's permissions |
 | One repository is skipped, others work | That repository failed its access check | Read the `=== owner/repo ===` block in the run log |
 | Same PR not reviewed after new commits | Label event was already processed | Remove and re-apply the trigger label |
+| Review paused with a failing-check comment | A current-head required check reported `failure`, `cancelled`, or `timed_out` | Fix the named checks and push; the review starts on the new head, or request `all-hands-bot` to review immediately |
+| Review reported waiting on checks | A current-head required check is `queued` or `in_progress`, or has not reported yet | No action; a later scan or a new review request retries |
+| Optional workflow failed but no review was paused | The failed workflow is not required, so the required-only scheduled gate ignored it | No action; only GitHub-required checks gate scheduled discovery |
+| Only a few reviews start on a large backlog | The per-scan `max_new_per_run` bound (default 2) reached | No action; later scans drain the remaining oldest requests and the bounded rotating window of unrequested PRs, or raise `max_new_per_run` if the deployment can hold more agents |
 | Review result never posts | Conversation still running or stuck | Open the conversation link from the acknowledgement comment |
 | Stale review suppressed | PR head SHA changed while the agent was reviewing | Re-apply the trigger label after the latest commit |
 | Review arrives as a plain comment, not a review | Publishing failed, so the script posted the text as a fallback | Check that the token has Pull requests: Read and Write |

package/skills/github-pr-reviewer/references/state-schema.md

@@ -18,6 +18,21 @@ store under the key `state:{owner}__{repo}` — for example
 `AUTOMATION_KV_TOKEN` is injected into the run environment. Each automation has
 its own isolated namespace.
 
+The scheduled worker (`worker.py`) uses the same store for one more document, the
+**unrequested-scan cursor**, under the key `review-scan:{owner}__{repo}`:
+
+```json
+{ "cursor": 20 }
+```
+
+`cursor` is the position in the repository's unrequested-PR backlog at which the
+next scheduled scan's bounded window starts. Each scan examines at most
+`SCAN_WINDOW` (10) unrequested PRs from that position, then writes the position
+after the window, so successive scans rotate through the whole backlog instead of
+reading one pull request per open PR. A cursor past the end wraps to the start.
+This document is separate from `main.py`'s per-repository review state; a missing
+or unreadable cursor simply starts the window at the beginning.
+
 **Fallback (local/dev):** When the KV store is not available, the state is
 written to a local JSON file at:
 

package/skills/github-pr-reviewer/scripts/github_client.py

@@ -165,6 +165,122 @@ class GitHubRepository:
             result.setdefault(item["context"], item["state"])
         return result
 
+    def check_runs(self, sha):
+        """Return every check run GitHub reported for one commit SHA.
+
+        Reading check runs needs no branch-protection or ruleset access, so this
+        is the head-eligibility signal the automation's own token can always
+        see. The endpoint answers with an object rather than a list, so it
+        paginates through ``gh`` instead of ``gh_pages``.
+        """
+        runs = []
+        for page in range(1, 101):
+            data = self.gh(
+                "GET", f"/commits/{sha}/check-runs?per_page=100&page={page}"
+            )
+            batch = data.get("check_runs") or []
+            runs.extend(batch)
+            if len(runs) >= int(data.get("total_count") or 0) or not batch:
+                return runs
+        raise RuntimeError("GitHub check-run pagination exceeded limit")
+
+    def required_check_contexts(self, number):
+        """Return the status contexts GitHub marks required on one pull request.
+
+        `isRequired` is the merge-policy source of truth and is PR-scoped, so it
+        is correct for a stacked PR whose symbolic base branch carries no branch
+        rules of its own. It is a field on each context in the head's status
+        check rollup and takes the pull request number, so a single GraphQL query
+        answers with the required check runs and any required commit statuses,
+        each already attributed to the exact head. Only contexts GitHub itself
+        reports as required are returned, so an optional workflow that fails
+        before creating any check run is not present.
+        """
+        owner, name = self.repository.split("/", 1)
+        query = (
+            "query($owner:String!,$name:String!,$number:Int!){"
+            "repository(owner:$owner,name:$name){"
+            "pullRequest(number:$number){"
+            "commits(last:1){"
+            "nodes{"
+            "commit{"
+            "statusCheckRollup{"
+            "contexts(first:100){"
+            "pageInfo{hasNextPage}"
+            "nodes{"
+            "__typename"
+            " ... on CheckRun{name isRequired(pullRequestNumber:$number)}"
+            " ... on StatusContext{context isRequired(pullRequestNumber:$number)}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+            "}"
+        )
+        data = self.api(
+            "POST",
+            "/graphql",
+            body={
+                "query": query,
+                "variables": {"owner": owner, "name": name, "number": number},
+            },
+        )
+        if data.get("errors"):
+            raise RuntimeError(
+                f"GitHub required-check query failed: {data['errors'][0].get('message')}"
+            )
+        nodes = (
+            (((data.get("data") or {}).get("repository") or {}).get("pullRequest") or {})
+            .get("commits", {})
+            .get("nodes")
+        ) or []
+        contexts = (
+            ((nodes[0].get("commit") or {}).get("statusCheckRollup") or {}).get(
+                "contexts", {}
+            )
+            if nodes
+            else {}
+        )
+        if (contexts.get("pageInfo") or {}).get("hasNextPage"):
+            raise RuntimeError(
+                "GitHub required-check rollup exceeds one page; the required "
+                "set may be incomplete"
+            )
+        return [
+            {
+                "name": node.get("name") or node.get("context"),
+                "kind": node.get("__typename"),
+            }
+            for node in (contexts.get("nodes") or [])
+            if node.get("isRequired") and (node.get("name") or node.get("context"))
+        ]
+
+    def workflow_runs(self, sha):
+        """Return every Actions workflow run GitHub reported for one commit SHA.
+
+        A workflow that fails before any job starts - a workflow-level error, or
+        a `pull_request` run whose jobs never materialize - still records a
+        failed check suite, but it contributes no check runs, so the commit's
+        check-run rollup and `gh pr checks` both report success. Reading the
+        workflow runs directly is the only way the gate can see that failure.
+        Like the check-run endpoint this answers with an object, so it paginates
+        manually.
+        """
+        runs = []
+        for page in range(1, 101):
+            data = self.gh(
+                "GET", f"/actions/runs?head_sha={sha}&per_page=100&page={page}"
+            )
+            batch = data.get("workflow_runs") or []
+            runs.extend(batch)
+            if len(runs) >= int(data.get("total_count") or 0) or not batch:
+                return runs
+        raise RuntimeError("GitHub workflow-run pagination exceeded limit")
+
     def completed_dependency(self, number):
         if number in self._completed_dependencies:
             return self._completed_dependencies[number]

package/skills/github-pr-reviewer/scripts/main.py

@@ -51,6 +51,18 @@ REVIEW_STYLE_INSTRUCTIONS = ""
 # than relying on the spawned agent's skill activation. Set to "" to disable.
 REPO_REVIEW_GUIDE_PATH = ".agents/skills/custom-codereview-guide.md"
 DEFAULT_OPENHANDS_URL = "http://localhost:8000"
+# The most new review conversations one scheduled scan may start, counted across
+# every configured repository rather than per repository. The scheduled scan
+# drains outstanding reviewer requests in oldest-request order, so a small bound
+# keeps a first scan over a large backlog from starting an agent for every
+# eligible pull request at once.
+MAX_NEW_PER_RUN = 2
+
+# A review that ends with this marker is a scope stop: the reviewer found the
+# change out of scope, or needing a product/architecture decision, before the
+# technical review. The completion handler hands it to a maintainer without
+# approving or merging the PR.
+MAINTAINER_DECISION_VERDICT = "🛑 MAINTAINER DECISION REQUIRED"
 
 CONFIG_FILENAME = "config.json"
 
@@ -63,6 +75,7 @@ _CONFIG_TYPES: dict[str, type] = {
     "review_tone": str,
     "review_style_instructions": str,
     "repo_review_guide_path": str,
+    "max_new_per_run": int,
     "openhands_url": str,
 }
 
@@ -89,7 +102,11 @@ def load_config(directory: Path | None = None) -> dict:
         if key not in raw:
             continue
         value = raw[key]
-        if not isinstance(value, expected):
+        # bool is an int in Python, so an unguarded int check would accept
+        # `"max_new_per_run": true` and then start `True` conversations.
+        if not isinstance(value, expected) or (
+            expected is int and isinstance(value, bool)
+        ):
             raise SystemExit(
                 f"{CONFIG_FILENAME}: {key} must be {expected.__name__}, "
                 f"got {type(value).__name__}"
@@ -100,6 +117,10 @@ def load_config(directory: Path | None = None) -> dict:
             raise SystemExit(
                 f'{CONFIG_FILENAME}: repos must be a non-empty list of "owner/repo" strings'
             )
+        if key == "max_new_per_run" and value < 1:
+            raise SystemExit(
+                f"{CONFIG_FILENAME}: max_new_per_run must be at least 1"
+            )
         config[key] = value
     return config
 
@@ -144,6 +165,7 @@ TRIGGER_LABEL = _CONFIG.get("trigger_label", TRIGGER_LABEL)
 REVIEW_TONE = _CONFIG.get("review_tone", REVIEW_TONE)
 REVIEW_STYLE_INSTRUCTIONS = _CONFIG.get("review_style_instructions", REVIEW_STYLE_INSTRUCTIONS)
 REPO_REVIEW_GUIDE_PATH = _CONFIG.get("repo_review_guide_path", REPO_REVIEW_GUIDE_PATH)
+MAX_NEW_PER_RUN = _CONFIG.get("max_new_per_run", MAX_NEW_PER_RUN)
 DEFAULT_OPENHANDS_URL = _CONFIG.get("openhands_url", DEFAULT_OPENHANDS_URL)
 
 DONE_DEBOUNCE = 15
@@ -787,22 +809,45 @@ def _build_review_prompt(
         f"\nPR Description:\n---\n{body}\n---\n\n"
         "Required workflow:\n"
         f"1. {workspace}\n"
-        "2. Before reviewing, you MUST read the repository's own guidance to understand the repo first.\n"
+        "2. CURRENT STATE - treat this request as a fresh review, never a continuation of "
+        "earlier observations. Before the scope gate and before deciding any verdict, re-fetch "
+        "the current mutable GitHub state for this pull request and act only on what you read "
+        "now: whether the exact head still matches the Head SHA above, the current PR title and "
+        "body, the current review comments and threads, the current review requests, the current "
+        "GitHub Actions check results for that head, and the current body and labels of every "
+        "linked issue the PR references - a linked issue may have gained or lost a readiness "
+        "label (for example `ready-for-dev`) or changed priority since an earlier turn. If an "
+        "earlier turn in this conversation reviewed this PR or its linked issues, that analysis "
+        "and the repository guidance you read remain useful background, but every mutable fact "
+        "above must be re-established now; never repeat an earlier finding, verdict, or "
+        "label/priority claim that the state you just read does not support.\n"
+        f"   Use `gh` or GitHub REST API calls with `{github_token_secret}`; never print secret values.\n"
+        "3. Before reviewing, you MUST read the repository's own guidance to understand the repo first.\n"
         "   Read `AGENTS.md` at the repository root (and any nested `AGENTS.md` covering the "
         "changed files), plus other relevant docs when present - e.g. `CONTRIBUTING.md`, "
         "`CLAUDE.md`, `.cursorrules`, and any review or coding-guideline docs. Apply that "
         "guidance to your review.\n"
-        "   Then inspect the PR discussion, existing review comments, changed files, and the diff, "
-        "together with the surrounding code in the workspace.\n"
-        f"   Use `gh` or GitHub REST API calls with `{github_token_secret}`; never print secret values.\n"
-        "3. Ground every finding in the workspace code. Before using an inline location, verify that "
+        "4. SCOPE GATE - before inspecting changed files, reading the diff, or running any test, "
+        "use the repository guidance above (its scope categories and ownership boundaries) to decide "
+        "whether this change belongs in this repository and has the product/architecture direction "
+        "it needs. If it does, continue the technical review unchanged. If it does not, or needs a "
+        "product/architecture decision, stop here and publish exactly one review with "
+        f"`POST /repos/{repo}/pulls/{number}/reviews`, using `commit_id` equal to the Head SHA above "
+        "and `event: COMMENT`. Briefly say whether the change should move repositories, close, or "
+        "receive a maintainer decision; when it belongs elsewhere, name the likely owning repository "
+        "only if the evidence supports it. Do not run tests or report implementation findings. This "
+        "outcome is not an approval, and its body ends with the verdict on its own line: "
+        f"`{MAINTAINER_DECISION_VERDICT}`.\n"
+        "5. Otherwise continue the technical review. Inspect the PR discussion, existing review "
+        "comments, changed files, and the diff, together with the surrounding code in the workspace.\n"
+        "6. Ground every finding in the workspace code. Before using an inline location, verify that "
         "the path and line are part of this pull request's diff. Compare every changed branch with "
         "the base behavior, including side effects outside the reported bug; a revision, event, or "
         "delivery identifier proves only the inputs it actually includes, not that unrelated profile, "
         "credential, configuration, or external state stayed unchanged. Do not add speculative or "
         "out-of-scope notes: every blocking or non-blocking observation must identify demonstrated "
         "behavior on the current head and explain why it matters to the merge decision.\n"
-        f"4. Publish one review with `POST /repos/{repo}/pulls/{number}/reviews`, using "
+        f"7. Publish one review with `POST /repos/{repo}/pulls/{number}/reviews`, using "
         "`commit_id` equal to the Head SHA above. Use `event: APPROVE` when there are "
         "no material findings; otherwise use `event: COMMENT`. Never use "
         "`REQUEST_CHANGES`.\n"
@@ -813,19 +858,19 @@ def _build_review_prompt(
         "   Put the overall assessment in `body`, and each line-specific finding in the `comments` "
         "array with `path`, `line`, `side: RIGHT`, and `body`.\n"
         "   Only create inline comments for actionable findings; do not open praise or nitpick threads.\n"
-        "5. If a finding cannot be attached to a changed line, put it in the review body instead. "
+        "8. If a finding cannot be attached to a changed line, put it in the review body instead. "
         "If the API rejects the inline positions, retry with every finding in the body and no `comments` array. "
         "If GitHub forbids the configured bot from approving its own PR, retry the clean review with "
         "`event: COMMENT` and keep the approved verdict.\n"
-        "6. Begin the review body with this disclosure: "
+        "9. Begin the review body with this disclosure: "
         "`_This review was posted by an AI agent (OpenHands)._`\n"
-        "7. End the review body with a verdict on its own line: either `✅ APPROVED` "
+        "10. End the review body with a verdict on its own line: either `✅ APPROVED` "
         "or `🔄 CHANGES REQUESTED`.\n"
-        "8. If there are no material issues, still publish a review saying so, with the "
+        "11. If there are no material issues, still publish a review saying so, with the "
         "disclosure and the verdict.\n"
         f"\nReview instructions:\n{tone}{extra}{guide_section}\n\n"
         "After GitHub accepts the review, output exactly `GITHUB_REVIEW_POSTED`. "
-        "If publishing still fails after the fallback in step 5, output the complete review text "
+        "If publishing still fails after the fallback in step 8, output the complete review text "
         "so it can be posted as a comment instead."
     )