@openhands/extensions 0.27.0 → 0.28.0

package/scripts/sync_openhands_sdk_skill.py

@@ -25,6 +25,7 @@ from pathlib import Path
 
 SKILL_PATH = Path(__file__).resolve().parent.parent / "skills" / "openhands-sdk" / "SKILL.md"
 LLMS_TXT_URL = "https://docs.openhands.dev/llms.txt"
+SDK_URL_PREFIX = "https://docs.openhands.dev/sdk/"
 GH_API = "https://api.github.com/repos/OpenHands/software-agent-sdk/contents/examples"
 GH_RAW = "https://raw.githubusercontent.com/OpenHands/software-agent-sdk/main"
 GH_BROWSE = "https://github.com/OpenHands/software-agent-sdk/blob/main/examples"
@@ -90,18 +91,20 @@ def _fetch_or(url: str, fallback, **kw):
 # -- llms.txt parsing --
 
 def parse_sdk_entries(llms_txt: str) -> list[dict]:
-    """Extract entries from the 'OpenHands Software Agent SDK' section."""
-    entries, in_section = [], False
-    for line in llms_txt.splitlines():
-        stripped = line.strip()
-        if stripped == "## OpenHands Software Agent SDK":
-            in_section = True
-            continue
-        if in_section and line.startswith("## "):
-            break
-        if in_section and (m := _ENTRY_RE.match(stripped)):
-            entries.append(m.groupdict())
-    return entries
+    """Extract entries for the OpenHands Software Agent SDK.
+
+    The docs index (llms.txt) no longer groups entries under an
+    "OpenHands Software Agent SDK" heading, so select entries by their
+    canonical URL prefix instead. Sort by title (case-insensitively) to
+    keep the generated skill stable across runs.
+    """
+    entries = [
+        m.groupdict()
+        for line in llms_txt.splitlines()
+        if (m := _ENTRY_RE.match(line.strip()))
+        and m.group("url").startswith(SDK_URL_PREFIX)
+    ]
+    return sorted(entries, key=lambda e: e["title"].lower())
 
 
 # -- content builders --
@@ -123,7 +126,7 @@ def build_classes_table(entries: list[dict]) -> str:
 def build_api_refs(entries: list[dict]) -> str:
     return ", ".join(
         f"[`{e['title']}`]({e['url']})"
-        for e in entries if "/api-reference/" in e["url"]
+        for e in entries if "/sdk/api-reference/" in e["url"]
     )
 
 

package/skills/azure-devops/README.md

@@ -11,6 +11,8 @@ This skill is activated by the following keywords:
 
 ## Details
 
+Use authenticated Azure DevOps MCP tools first when they are available in the agent's environment. Detect the connection through tool availability rather than a particular server name. Fall back to the documented `AZURE_DEVOPS_TOKEN` and direct API flow when those tools are unavailable or raw API or `curl` access is explicitly needed.
+
 You have access to an environment variable, `AZURE_DEVOPS_TOKEN`, which allows you to interact with
 the Azure DevOps API.
 
@@ -52,4 +54,4 @@ Common API endpoints:
 - List repositories: `https://dev.azure.com/{organization}/{project}/_apis/git/repositories?api-version=7.1`
 - Get repository details: `https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}?api-version=7.1`
 - List pull requests: `https://dev.azure.com/{organization}/{project}/_apis/git/pullrequests?api-version=7.1`
-- Create pull request: `https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}/pullrequests?api-version=7.1` (POST)
+- Create pull request: `https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}/pullrequests?api-version=7.1` (POST)

package/skills/azure-devops/SKILL.md

@@ -6,6 +6,10 @@ triggers:
 - azure
 ---
 
+## Connection selection
+
+Use authenticated Azure DevOps MCP tools first when they are available in the agent's environment. Detect this by tool availability, without depending on a particular MCP server name. Use the token and direct API instructions below only when Azure DevOps MCP tools are unavailable or when raw API or `curl` access is explicitly needed.
+
 You have access to an environment variable, `AZURE_DEVOPS_TOKEN`, which allows you to interact with
 the Azure DevOps API.
 

package/skills/bitbucket/README.md

@@ -3,6 +3,8 @@
 Bitbucket integration **hub** skill. It detects whether the repository is on Bitbucket
 Cloud or Bitbucket Data Center and directs the agent to the matching detailed skill.
 
+Authenticated Bitbucket MCP tools are preferred when available, detected generically by tool availability rather than a particular server name. The hub still routes to Cloud or Data Center, and the documented token and direct API paths remain the fallback when MCP tools are unavailable or raw API or `curl` access is explicitly needed.
+
 ## Triggers
 
 This skill is activated by the following keywords:
@@ -30,4 +32,4 @@ when the words "data center" never appear. It then:
 The hub also carries a small quick-reference table as a fallback in case the detailed skill
 cannot be loaded.
 
-See [`SKILL.md`](SKILL.md) for the full content.
+See [`SKILL.md`](SKILL.md) for the full content.

package/skills/bitbucket/SKILL.md

@@ -5,6 +5,8 @@ triggers:
 - bitbucket
 ---
 
+Use authenticated Bitbucket MCP tools first when they are available in the agent's environment. Detect this by tool availability, without depending on a particular MCP server name. Still identify Cloud versus Data Center and load the matching detailed skill. Use the token and direct API instructions only when Bitbucket MCP tools are unavailable or when raw API or `curl` access is explicitly needed.
+
 You are working with **Bitbucket**, which ships as two distinct products that behave
 differently:
 
@@ -19,7 +21,7 @@ detailed skill for full instructions.
 
 ## Step 1 — Detect which Bitbucket you are on
 
-Check which token environment variable is present. Environment variable names are
+First use the repository host or available Bitbucket MCP tool context to identify the product. For the token fallback, check which token environment variable is present. Environment variable names are
 case-sensitive, so look for it case-insensitively:
 
 ```bash
@@ -53,4 +55,4 @@ Bitbucket API (not a web browser) and always use the listed PR tool to open a pu
 | Host | `bitbucket.org` | self-hosted domain |
 | REST API base | `https://api.bitbucket.org/2.0` | `https://<host>/rest/api/1.0` |
 | Repository identifier | `workspace/repo_slug` | `PROJECT/repo_slug` (project key) |
-| Pull request tool | `create_bitbucket_pr` | `create_bitbucket_data_center_pr` |
+| Pull request tool | `create_bitbucket_pr` | `create_bitbucket_data_center_pr` |

package/skills/bitbucket-cloud/README.md

@@ -11,5 +11,7 @@ it detects a Bitbucket Cloud environment (i.e. `BITBUCKET_TOKEN` is set).
 
 ## Details
 
+Use authenticated Bitbucket Cloud MCP tools first when they are available, detected by tool availability rather than a particular server name. Fall back to the documented `BITBUCKET_TOKEN` and direct REST API flow when those tools are unavailable or raw API or `curl` access is explicitly needed.
+
 See [`SKILL.md`](SKILL.md) for the full content, including authenticated git remote
 construction and pull request instructions.

package/skills/bitbucket-cloud/SKILL.md

@@ -3,6 +3,8 @@ name: bitbucket-cloud
 description: Bitbucket Cloud (bitbucket.org) specifics — authenticate with BITBUCKET_TOKEN, use the REST API v2, workspace/repo_slug repositories, and the create_bitbucket_pr tool. Loaded on demand by the bitbucket skill once a Cloud environment is detected.
 ---
 
+Use authenticated Bitbucket Cloud MCP tools first when they are available in the agent's environment. Detect this by tool availability, without depending on a particular MCP server name. Use the token and direct REST API instructions below only when those tools are unavailable or when raw API or `curl` access is explicitly needed.
+
 You are working with **Bitbucket Cloud** (`bitbucket.org`). You have access to an
 environment variable, `BITBUCKET_TOKEN`, which allows you to interact with the Bitbucket
 Cloud API.

package/skills/bitbucket-data-center/README.md

@@ -12,6 +12,8 @@ it detects a Bitbucket Data Center environment (i.e. `BITBUCKET_DATA_CENTER_TOKE
 
 ## Details
 
+Use authenticated Bitbucket Data Center MCP tools first when they are available, detected by tool availability rather than a particular server name. Fall back to the documented `BITBUCKET_DATA_CENTER_TOKEN` and direct REST API flow when those tools are unavailable or raw API or `curl` access is explicitly needed.
+
 See [`SKILL.md`](SKILL.md) for the full content, including authenticated `scm/` git remote
 construction and pull request instructions. Note the key differences from Bitbucket Cloud:
 the REST API is version `1.0` under `https://{domain}/rest/api/1.0`, repositories are

package/skills/bitbucket-data-center/SKILL.md

@@ -3,6 +3,8 @@ name: bitbucket-data-center
 description: Bitbucket Data Center (self-hosted Bitbucket Server) specifics — authenticate with BITBUCKET_DATA_CENTER_TOKEN, use the REST API 1.0, PROJECT/repo_slug repositories, scm/ git remotes, and the create_bitbucket_data_center_pr tool. Loaded on demand by the bitbucket skill once a Data Center environment is detected.
 ---
 
+Use authenticated Bitbucket Data Center MCP tools first when they are available in the agent's environment. Detect this by tool availability, without depending on a particular MCP server name. Use the token and direct REST API instructions below only when those tools are unavailable or when raw API or `curl` access is explicitly needed.
+
 You are working with **Bitbucket Data Center** (self-hosted Bitbucket Server). You have
 access to an environment variable, `BITBUCKET_DATA_CENTER_TOKEN`, which contains a basic
 auth token in the format `username:your-token` that allows you to interact with the git

package/skills/github/README.md

@@ -11,6 +11,8 @@ This skill is activated by the following keywords:
 
 ## Details
 
+Use authenticated GitHub MCP tools first when they are available in the agent's environment. Detect the connection through tool availability rather than a particular server name. Fall back to the documented `GITHUB_TOKEN` and direct API flow when those tools are unavailable or raw API or `curl` access is explicitly needed.
+
 You have access to an environment variable, `GITHUB_TOKEN`, which allows you to interact with
 the GitHub API.
 
@@ -39,4 +41,6 @@ Here are some instructions for pushing, but ONLY do this if the user asks you to
 ```bash
 git remote -v && git branch # to find the current org, repo and branch
 git checkout -b create-widget && git add . && git commit -m "Create widget" && git push -u origin create-widget
-```
+```
+
+When asked to merge a pull request, the skill uses GitHub's async merge API (`PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge-async`, then poll the returned UUID). It supports stacked PRs and merge queues. Docs: https://docs.github.com/en/rest/pulls/pulls#merge-a-pull-request-asynchronously

package/skills/github/SKILL.md

@@ -5,6 +5,10 @@ triggers:
 - github
 ---
 
+## Connection selection
+
+Use authenticated GitHub MCP tools first when they are available in the agent's environment. Detect this by tool availability, without depending on a particular MCP server name. Use the token and direct API instructions below only when GitHub MCP tools are unavailable or when raw API or `curl` access is explicitly needed.
+
 You have access to an environment variable, `GITHUB_TOKEN`, which allows you to interact with
 the GitHub API.
 
@@ -37,6 +41,29 @@ git remote -v && git branch # to find the current org, repo and branch
 git checkout -b create-widget && git add . && git commit -m "Create widget" && git push -u origin create-widget
 ```
 
+## Merging Pull Requests (async merge API)
+
+IMPORTANT:
+Only merge if the user asks you to, without ambiguity.
+
+GitHub released an async merge API in October 2026; it is now the
+recommended way to merge PRs programmatically, and the only merge API that supports stacked PRs. It can also add a PR to a merge queue.
+Prefer it over `PUT .../pulls/{n}/merge` and the GraphQL `mergePullRequest` mutation.
+A GitHub MCP merge tool may still use the older synchronous endpoint; for stacked PRs or merge queues, use the calls below.
+Docs: https://docs.github.com/en/rest/pulls/pulls#merge-a-pull-request-asynchronously
+
+1. Request the merge (`merge_action`: `default` uses the merge queue if the branch has one, else merges directly; or `direct_merge` / `merge_queue`). `merge_method`, `commit_title` and `commit_message` apply only to direct merges:
+```bash
+gh api -X PUT repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/merge-async -f merge_method=squash -f sha=<HEAD_SHA>
+```
+2. A `202` returns `details.uuid`; poll it every few seconds until `status` is no longer `pending`:
+```bash
+gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/merge-async/<UUID>
+```
+
+Final `status` is `merged`, `enqueued` (added to the merge queue, NOT merged yet), or `failed` (see `details.message`).
+A `200` on the PUT means the PR is already merged or queued; a `409` means a merge request is already pending (its UUID is returned).
+
 ## Handling Review Comments
 
 - Critically evaluate each review comment before acting on it. Not all feedback is worth implementing:

package/skills/github/scripts/agent_conversation.py

@@ -32,6 +32,11 @@ _CLOUD_START_GRACE_SECONDS = 10 * 60
 # How long to wait for a paused conversation's sandbox to come back up.
 _CLOUD_RESUME_TIMEOUT_SECONDS = 120
 _CLOUD_POLL_SECONDS = 3
+# How many times a matched delivery whose conversation ended in ERROR is sent
+# again. The delivery key never changes for a stable subject, so without a
+# retry its work is stranded; without a bound, a conversation that fails the
+# same way every time would be re-run on every scan.
+_MAX_ERROR_RETRIES = 2
 
 
 def _register_tools() -> None:
@@ -204,14 +209,23 @@ class AgentConversationDispatcher:
 
         same_delivery = record.get("delivery") == delivery
         same_head = bool(head) and record.get("head") == head
+        # Error retries count against one delivery; a new delivery starts over.
+        error_retries = int(record.get("error_retries") or 0) if same_delivery else 0
+        can_retry = error_retries < _MAX_ERROR_RETRIES
 
         if self._cloud:
             disposition, conversation_id = self._deliver_cloud(
-                record, conversation_id, subject, prompt, same_delivery, same_head
+                record,
+                conversation_id,
+                subject,
+                prompt,
+                same_delivery,
+                same_head,
+                can_retry,
             )
         else:
             disposition = self._deliver_local(
-                conversation_id, prompt, same_delivery, same_head
+                conversation_id, prompt, same_delivery, same_head, can_retry
             )
 
         if disposition in ("deduplicated", "in_progress"):
@@ -228,6 +242,10 @@ class AgentConversationDispatcher:
         }
         if disposition == "created" and self._cloud:
             new_record["started_at"] = time.time()
+        if disposition == "retried":
+            error_retries += 1
+        if error_retries:
+            new_record["error_retries"] = error_retries
         _kv_request(state_key, "PUT", new_record)
         return {
             "disposition": disposition,
@@ -235,7 +253,14 @@ class AgentConversationDispatcher:
         }
 
     def _deliver_cloud(
-        self, record, conversation_id, subject, prompt, same_delivery, same_head
+        self,
+        record,
+        conversation_id,
+        subject,
+        prompt,
+        same_delivery,
+        same_head,
+        can_retry,
     ):
         """Deliver through the OpenHands API; return the disposition and the id.
 
@@ -272,11 +297,21 @@ class AgentConversationDispatcher:
             if status in ("idle", "paused"):
                 self._cloud.run(conversation)
                 return "resumed", current_id
+            if status == "error" and can_retry:
+                # The delivery matched but its conversation died before the work
+                # finished, so send the revision again rather than strand it.
+                # The API reports an execution status only while the sandbox
+                # runs, so an errored conversation whose sandbox was already
+                # paused is not seen here and keeps reporting deduplicated.
+                self._cloud.send(conversation, prompt)
+                return "retried", current_id
             return "deduplicated", current_id
         self._cloud.send(conversation, prompt)
         return "resumed", current_id
 
-    def _deliver_local(self, conversation_id, prompt, same_delivery, same_head) -> str:
+    def _deliver_local(
+        self, conversation_id, prompt, same_delivery, same_head, can_retry
+    ) -> str:
         if self._workspace is None:
             raise RuntimeError("AgentConversationDispatcher must be used as a context")
 
@@ -321,6 +356,18 @@ class AgentConversationDispatcher:
                     ):
                         conversation.update_secrets(self._secrets)
                         conversation.run(blocking=False)
+                    elif (
+                        conversation.state.execution_status
+                        == ConversationExecutionStatus.ERROR
+                        and can_retry
+                    ):
+                        # The delivery matched but its conversation died before
+                        # the work finished, so send the revision again rather
+                        # than strand it.
+                        conversation.update_secrets(self._secrets)
+                        conversation.send_message(prompt)
+                        conversation.run(blocking=False)
+                        disposition = "retried"
                     else:
                         disposition = "deduplicated"
                 else:

package/skills/github-issue-to-pr/scripts/agent_conversation.py

@@ -32,6 +32,11 @@ _CLOUD_START_GRACE_SECONDS = 10 * 60
 # How long to wait for a paused conversation's sandbox to come back up.
 _CLOUD_RESUME_TIMEOUT_SECONDS = 120
 _CLOUD_POLL_SECONDS = 3
+# How many times a matched delivery whose conversation ended in ERROR is sent
+# again. The delivery key never changes for a stable subject, so without a
+# retry its work is stranded; without a bound, a conversation that fails the
+# same way every time would be re-run on every scan.
+_MAX_ERROR_RETRIES = 2
 
 
 def _register_tools() -> None:
@@ -204,14 +209,23 @@ class AgentConversationDispatcher:
 
         same_delivery = record.get("delivery") == delivery
         same_head = bool(head) and record.get("head") == head
+        # Error retries count against one delivery; a new delivery starts over.
+        error_retries = int(record.get("error_retries") or 0) if same_delivery else 0
+        can_retry = error_retries < _MAX_ERROR_RETRIES
 
         if self._cloud:
             disposition, conversation_id = self._deliver_cloud(
-                record, conversation_id, subject, prompt, same_delivery, same_head
+                record,
+                conversation_id,
+                subject,
+                prompt,
+                same_delivery,
+                same_head,
+                can_retry,
             )
         else:
             disposition = self._deliver_local(
-                conversation_id, prompt, same_delivery, same_head
+                conversation_id, prompt, same_delivery, same_head, can_retry
             )
 
         if disposition in ("deduplicated", "in_progress"):
@@ -228,6 +242,10 @@ class AgentConversationDispatcher:
         }
         if disposition == "created" and self._cloud:
             new_record["started_at"] = time.time()
+        if disposition == "retried":
+            error_retries += 1
+        if error_retries:
+            new_record["error_retries"] = error_retries
         _kv_request(state_key, "PUT", new_record)
         return {
             "disposition": disposition,
@@ -235,7 +253,14 @@ class AgentConversationDispatcher:
         }
 
     def _deliver_cloud(
-        self, record, conversation_id, subject, prompt, same_delivery, same_head
+        self,
+        record,
+        conversation_id,
+        subject,
+        prompt,
+        same_delivery,
+        same_head,
+        can_retry,
     ):
         """Deliver through the OpenHands API; return the disposition and the id.
 
@@ -272,11 +297,21 @@ class AgentConversationDispatcher:
             if status in ("idle", "paused"):
                 self._cloud.run(conversation)
                 return "resumed", current_id
+            if status == "error" and can_retry:
+                # The delivery matched but its conversation died before the work
+                # finished, so send the revision again rather than strand it.
+                # The API reports an execution status only while the sandbox
+                # runs, so an errored conversation whose sandbox was already
+                # paused is not seen here and keeps reporting deduplicated.
+                self._cloud.send(conversation, prompt)
+                return "retried", current_id
             return "deduplicated", current_id
         self._cloud.send(conversation, prompt)
         return "resumed", current_id
 
-    def _deliver_local(self, conversation_id, prompt, same_delivery, same_head) -> str:
+    def _deliver_local(
+        self, conversation_id, prompt, same_delivery, same_head, can_retry
+    ) -> str:
         if self._workspace is None:
             raise RuntimeError("AgentConversationDispatcher must be used as a context")
 
@@ -321,6 +356,18 @@ class AgentConversationDispatcher:
                     ):
                         conversation.update_secrets(self._secrets)
                         conversation.run(blocking=False)
+                    elif (
+                        conversation.state.execution_status
+                        == ConversationExecutionStatus.ERROR
+                        and can_retry
+                    ):
+                        # The delivery matched but its conversation died before
+                        # the work finished, so send the revision again rather
+                        # than strand it.
+                        conversation.update_secrets(self._secrets)
+                        conversation.send_message(prompt)
+                        conversation.run(blocking=False)
+                        disposition = "retried"
                     else:
                         disposition = "deduplicated"
                 else:

package/skills/github-issue-triage/scripts/agent_conversation.py

@@ -32,6 +32,11 @@ _CLOUD_START_GRACE_SECONDS = 10 * 60
 # How long to wait for a paused conversation's sandbox to come back up.
 _CLOUD_RESUME_TIMEOUT_SECONDS = 120
 _CLOUD_POLL_SECONDS = 3
+# How many times a matched delivery whose conversation ended in ERROR is sent
+# again. The delivery key never changes for a stable subject, so without a
+# retry its work is stranded; without a bound, a conversation that fails the
+# same way every time would be re-run on every scan.
+_MAX_ERROR_RETRIES = 2
 
 
 def _register_tools() -> None:
@@ -204,14 +209,23 @@ class AgentConversationDispatcher:
 
         same_delivery = record.get("delivery") == delivery
         same_head = bool(head) and record.get("head") == head
+        # Error retries count against one delivery; a new delivery starts over.
+        error_retries = int(record.get("error_retries") or 0) if same_delivery else 0
+        can_retry = error_retries < _MAX_ERROR_RETRIES
 
         if self._cloud:
             disposition, conversation_id = self._deliver_cloud(
-                record, conversation_id, subject, prompt, same_delivery, same_head
+                record,
+                conversation_id,
+                subject,
+                prompt,
+                same_delivery,
+                same_head,
+                can_retry,
             )
         else:
             disposition = self._deliver_local(
-                conversation_id, prompt, same_delivery, same_head
+                conversation_id, prompt, same_delivery, same_head, can_retry
             )
 
         if disposition in ("deduplicated", "in_progress"):
@@ -228,6 +242,10 @@ class AgentConversationDispatcher:
         }
         if disposition == "created" and self._cloud:
             new_record["started_at"] = time.time()
+        if disposition == "retried":
+            error_retries += 1
+        if error_retries:
+            new_record["error_retries"] = error_retries
         _kv_request(state_key, "PUT", new_record)
         return {
             "disposition": disposition,
@@ -235,7 +253,14 @@ class AgentConversationDispatcher:
         }
 
     def _deliver_cloud(
-        self, record, conversation_id, subject, prompt, same_delivery, same_head
+        self,
+        record,
+        conversation_id,
+        subject,
+        prompt,
+        same_delivery,
+        same_head,
+        can_retry,
     ):
         """Deliver through the OpenHands API; return the disposition and the id.
 
@@ -272,11 +297,21 @@ class AgentConversationDispatcher:
             if status in ("idle", "paused"):
                 self._cloud.run(conversation)
                 return "resumed", current_id
+            if status == "error" and can_retry:
+                # The delivery matched but its conversation died before the work
+                # finished, so send the revision again rather than strand it.
+                # The API reports an execution status only while the sandbox
+                # runs, so an errored conversation whose sandbox was already
+                # paused is not seen here and keeps reporting deduplicated.
+                self._cloud.send(conversation, prompt)
+                return "retried", current_id
             return "deduplicated", current_id
         self._cloud.send(conversation, prompt)
         return "resumed", current_id
 
-    def _deliver_local(self, conversation_id, prompt, same_delivery, same_head) -> str:
+    def _deliver_local(
+        self, conversation_id, prompt, same_delivery, same_head, can_retry
+    ) -> str:
         if self._workspace is None:
             raise RuntimeError("AgentConversationDispatcher must be used as a context")
 
@@ -321,6 +356,18 @@ class AgentConversationDispatcher:
                     ):
                         conversation.update_secrets(self._secrets)
                         conversation.run(blocking=False)
+                    elif (
+                        conversation.state.execution_status
+                        == ConversationExecutionStatus.ERROR
+                        and can_retry
+                    ):
+                        # The delivery matched but its conversation died before
+                        # the work finished, so send the revision again rather
+                        # than strand it.
+                        conversation.update_secrets(self._secrets)
+                        conversation.send_message(prompt)
+                        conversation.run(blocking=False)
+                        disposition = "retried"
                     else:
                         disposition = "deduplicated"
                 else:

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

@@ -61,6 +61,11 @@ This skill is activated by:
   checkout when the review ends, so nothing accumulates between runs
 - Publishes a real pull request review, with inline comments where a finding
   maps to a changed line, and verifies on GitHub that it landed
+- Requires live evidence from the real app before approving a user-visible UI
+  change when the repository's guidance demands it: unit tests, CSS-token
+  assertions, generated mockups, and reconstructed captures cannot substitute.
+  Missing evidence yields a COMMENT review that names the gap, so no approval
+  and no maintainer handoff
 - Posts acknowledgement comments with AI disclosure
 - Configurable review tone and polling schedule
 - Optional human handoff after an exact-head approval. The scanner ranks the

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

@@ -189,6 +189,18 @@ handler recognizes the verdict and requests one configured maintainer through th
 same handoff used after an approval. An in-scope change continues the existing
 review unchanged.
 
+Before approving a change to user-visible UI behavior, the prompt requires live
+evidence from a real running application when the repository's guidance demands
+it: a screenshot, screen recording, or equivalent capture of the running app
+that exercises the production-facing path. Unit tests, CSS-token or contract
+assertions, generated mockups, and reconstructed captures may support the review
+but cannot substitute for that evidence. When the required evidence is missing,
+the reviewer publishes one `event: COMMENT` review naming exactly what is
+missing and ends with `🔄 CHANGES REQUESTED`, so approval is withheld and the
+deterministic maintainer handoff does not fire. Non-UI changes keep the existing
+requirement of the real command and its observed output, with tests insufficient
+as sole proof.
+
 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
 its own, which becomes the conversation's working directory. The agent is told