Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/cursor-review/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -435,6 +435,7 @@ All optional except `workflows_ref` (required, no default) — pass them under
| `approve_only_max_runs` | `10` | Re-checks per panel round, read off the re-check sentinel, which names the round it counts for; clamped to `card.RECHECK_HEADS_KEPT` (50), past which the count could not grow. |
| `carry_forward_unchanged_diff` | `false` | Opt-in: `dismiss-stale-approval` re-approves the live head before dismissing when the PR's own changes (compare API, merge base → head, hunk line numbers ignored, headings and inter-hunk distances kept) equal the ones the approving round reviewed under a threshold no looser than today's — the stacked-PR rebase, re-merge or retarget. What the round reviewed comes only from the approver's own records: the merge base the approval recorded (`approval_merge_base`, when the compare API and the round's sentinel agree — the sentinel can veto a record, never supply one) or what a carried approval copied forward (`carry_baseline`), and the compare API must show it as an ancestor of the reviewed commit; an approval with neither never carries. Only under `pull_request_target`, only for the approver's latest verdict, failing closed (dismissing as before) on anything it cannot compare (`try_carry_forward`); `mark_card_stale` leaves the card alone while such an approval stands. See [the setup guide](../../docs/callers/cursor-review.md#auto-approve). |
| `max_rounds` | `5` | Per-PR review-round cap; `0` → none. Counts the posting identity's consolidated reviews since `needs-human-review` was last removed, except a round whose own decision found the PR head had moved (a push superseded it), at most once per reviewed commit and at most `max_rounds` times; at or over the cap the panel is skipped, the PR is labelled `needs-human-review`, one comment lists the latest round's open findings above the threshold, and the `approve_gate` output is `capped`. Fails open on a read error. See [the setup guide](../../docs/callers/cursor-review.md#round-cap-and-the-approve_gate-output). |
| `handoff_after_cap` | `false` | After the last allowed delivered review, recount and hand off in the same run. Requires a positive cap and `fail_closed_round_cap`; concurrent and undelivered runs are not serialized. |
| `preserve_round_count` | `false` | Keep counting prior delivered reviews after the human handoff label is removed. Does not count undelivered panels or serialize runs. |
| `count_superseded_rounds` | `false` | Count delivered reviews even when a later decision found the head moved. Does not count undelivered panels or change resets. |
| `fail_closed_round_cap` | `false` | Stop the panel if cap evaluation or handoff fails. Requires a positive `max_rounds`; does not change resets, superseded-round exemptions or concurrency. |
Expand Down
42 changes: 34 additions & 8 deletions .github/cursor-review/auto-approve.py
Original file line number Diff line number Diff line change
Expand Up @@ -281,6 +281,7 @@
VETO_LABELS = (SKIP_REVIEW_LABEL,)
ROUND_CAP_MARKER = "<!-- cursor-review-round-cap -->"
PRESERVED_CAP_MARKER = "<!-- cursor-review-round-cap:preserved -->"
AFTER_REVIEW_CAP_MARKER = "<!-- cursor-review-round-cap:after-review -->"
# post-review.py opens two bodies with CONSOLIDATED_MARKER that report a round
# which reviewed NOTHING — the "Review failed" error review and the
# all-panel-cells-failed review (both `delivers=False`). Neither spent a panel's
Expand Down Expand Up @@ -4077,13 +4078,15 @@ def superseded_by_push(panel: dict, reviews: list, login: str, marker: str) -> s
return ""


def cap_comment_posted(comments: list, poster_login: str, since, preserve: bool = False) -> bool:
def cap_comment_posted(comments: list, poster_login: str, since, preserve: bool = False,
after_review: bool = False) -> bool:
"""True when this cap's comment is already on the PR (posted after `since`)."""
return any(
isinstance(c, dict)
and ((c.get("user") or {}).get("login") or "").lower() == poster_login.lower()
and (PRESERVED_CAP_MARKER if preserve else ROUND_CAP_MARKER) in (c.get("body") or "")
and (preserve or PRESERVED_CAP_MARKER not in (c.get("body") or ""))
and ((AFTER_REVIEW_CAP_MARKER in (c.get("body") or "")) == after_review)
and _after(c.get("created_at"), since)
for c in comments
)
Expand Down Expand Up @@ -4111,19 +4114,22 @@ def cap_findings(review_comments: list, open_ids, threshold: str) -> list:


def render_cap_comment(rounds: int, max_rounds: int, findings: list, threshold: str, review_url: str,
preserve: bool = False) -> str:
preserve: bool = False, after_review: bool = False) -> str:
render_code_ref = _load_post_review().render_code_ref
scope = f"above `{threshold}`" if threshold else "still open"
lines = [
ROUND_CAP_MARKER,
"### 🛑 Cursor Review — round cap reached",
f"This PR has had {rounds} review round(s) (`max_rounds: {max_rounds}`), so no new "
f"panel ran and it is labelled `{HUMAN_REVIEW_LABEL}`. Auto-approve will not "
f"This PR has had {rounds} review round(s) (`max_rounds: {max_rounds}`); "
+ ("the latest review was delivered" if after_review else "no new panel ran")
+ f" and it is labelled `{HUMAN_REVIEW_LABEL}`. Auto-approve will not "
"approve it while the label is on; " + ("removing the label does not reset the round count."
if preserve else "removing the label resets the round count."),
]
if preserve:
lines.insert(1, PRESERVED_CAP_MARKER)
if after_review:
lines.insert(1, AFTER_REVIEW_CAP_MARKER)
if findings:
lines.append(f"\nFindings from the latest round {scope}:")
for sev, path, line in findings[:30]:
Expand Down Expand Up @@ -4222,8 +4228,19 @@ def parse_max_rounds(value) -> int:
return int(number)


def uncertain_after_review_handoff(args, reason: str) -> int:
"""Stop a later review while the delivered round's count is uncertain."""
try:
ensure_label(args.repo, args.pr_number)
except RuntimeError as e:
print(f"::error::Could not apply the human handoff label: {e}")
print(f"::error::{reason}; the handoff needs human verification.")
return 1


def cmd_round_cap(args) -> int:
strict = getattr(args, "fail_closed_round_cap", False)
after_review = getattr(args, "after_review", False)
strict = getattr(args, "fail_closed_round_cap", False) or after_review
set_output("capped", "false")
set_output("labelled", "false")
# The EFFECTIVE cap, for the workflow's `max_rounds` output: an invalid value
Expand Down Expand Up @@ -4256,6 +4273,8 @@ def cmd_round_cap(args) -> int:
set_output("labelled", "true")
except (RuntimeError, ValueError) as e:
print(f"::warning::Could not read this PR's labels: {e}")
if after_review:
return uncertain_after_review_handoff(args, "Could not read the PR labels after delivery")
if strict:
return 1
try:
Expand All @@ -4267,6 +4286,8 @@ def cmd_round_cap(args) -> int:
0 if getattr(args, "count_superseded_rounds", False) else max_rounds)
except (RuntimeError, ValueError) as e:
# Legacy callers fail open; strict callers stop the panel.
if after_review:
return uncertain_after_review_handoff(args, "Could not count review rounds after delivery")
if strict:
print(f"::error::Could not count review rounds; stopping the panel: {e}")
return 1
Expand All @@ -4278,6 +4299,8 @@ def cmd_round_cap(args) -> int:
# than a guess.
set_output("next_round", len(rounds) + 1)
if len(rounds) < max_rounds:
if after_review:
return uncertain_after_review_handoff(args, "The delivered review is not yet reflected in the count")
emit(f"Round cap: {len(rounds)}/{max_rounds} round(s) so far — running the panel.")
return 0

Expand All @@ -4296,19 +4319,21 @@ def cmd_round_cap(args) -> int:
return 0
set_output("capped", "true")
set_output("labelled", "true")
emit(f"🛑 **Round cap reached** — {len(rounds)}/{max_rounds} round(s); skipped the panel and labelled `{HUMAN_REVIEW_LABEL}`.")
emit(f"🛑 **Round cap reached** — {len(rounds)}/{max_rounds} round(s); "
+ ("review delivered" if after_review else "skipped the panel")
+ f" and labelled `{HUMAN_REVIEW_LABEL}`.")
failed = []
try:
comments = _paginate(f"repos/{args.repo}/issues/{args.pr_number}/comments?per_page=100")
if cap_comment_posted(comments, args.poster_login, since, preserve):
if cap_comment_posted(comments, args.poster_login, since, preserve, after_review):
emit("Round cap: the cap comment is already on this PR — not posting it again.")
else:
latest = rounds[-1]
review_comments = _paginate(
f"repos/{args.repo}/pulls/{args.pr_number}/reviews/{latest['id']}/comments?per_page=100"
)
findings = cap_findings(review_comments, open_thread_ids(args.repo, int(args.pr_number)), threshold)
body = render_cap_comment(len(rounds), max_rounds, findings, threshold, latest.get("html_url") or "", preserve)
body = render_cap_comment(len(rounds), max_rounds, findings, threshold, latest.get("html_url") or "", preserve, after_review)
gh(["api", "-X", "POST", f"repos/{args.repo}/issues/{args.pr_number}/comments", "--input", "-"], {"body": body})
except (RuntimeError, ValueError, KeyError) as e:
failed.append(f"comment: {e}")
Expand Down Expand Up @@ -4744,6 +4769,7 @@ def main() -> int:
c.add_argument("--fail-closed-round-cap", action="store_true")
c.add_argument("--count-superseded-rounds", action="store_true")
c.add_argument("--preserve-round-count", action="store_true")
c.add_argument("--after-review", action="store_true")
e = sub.add_parser("approve-external")
e.add_argument("--repo", required=True)
e.add_argument("--pr-number", required=True)
Expand Down
70 changes: 66 additions & 4 deletions .github/cursor-review/tests/test_auto_approve.py
Original file line number Diff line number Diff line change
Expand Up @@ -1823,14 +1823,14 @@ def test_comment_neutralises_model_paths(self):


class StrictRoundCapPrerequisiteTest(unittest.TestCase):
def run_prerequisite(self, limit, configured, token, slug):
def run_prerequisite(self, limit, configured, token, slug, handoff="false", fail_closed="false"):
with open(WORKFLOW_PATH, encoding="utf-8") as f:
workflow = f.read()
step = workflow.split("- name: Validate strict cap prerequisites", 1)[1].split("\n - name:", 1)[0]
script = step.split("run: |\n", 1)[1]
script = "\n".join(line[10:] for line in script.splitlines())
env = {"PATH": os.environ["PATH"], "MAX_ROUNDS": limit, "BOT_CONFIGURED": configured,
"BOT_TOKEN": token, "BOT_SLUG": slug}
"BOT_TOKEN": token, "BOT_SLUG": slug, "HANDOFF_AFTER_CAP": handoff, "FAIL_CLOSED": fail_closed}
return subprocess.run(["bash", "-e", "-c", script], env=env, capture_output=True).returncode

def test_no_bot_allows_a_positive_limit(self):
Expand All @@ -1842,6 +1842,10 @@ def test_configured_bot_needs_both_token_and_identity(self):
self.assertNotEqual(self.run_prerequisite("3", "true", token, slug), 0)
self.assertEqual(self.run_prerequisite("3", "true", "token", "bot"), 0)

def test_immediate_handoff_requires_fail_closed_counting(self):
self.assertNotEqual(self.run_prerequisite("3", "false", "", "", handoff="true"), 0)
self.assertEqual(self.run_prerequisite("3", "false", "", "", handoff="true", fail_closed="true"), 0)

def test_zero_and_negative_limits_are_rejected(self):
for limit in ("0", "-1"):
with self.subTest(limit=limit):
Expand Down Expand Up @@ -1869,11 +1873,41 @@ def test_count_step_passes_the_opt_in_to_the_real_entrypoint(self):



class ImmediateHandoffStepTest(unittest.TestCase):
def test_step_runs_after_post_and_before_approval_with_policy_flags(self):
with open(WORKFLOW_PATH, encoding="utf-8") as f:
workflow = f.read()
post = workflow.split(" post-review:\n", 1)[1].split("\n dismiss-stale-approval:", 1)[0]
self.assertLess(post.index("- name: Post review"), post.index("- name: Hand off after the last delivered review"))
self.assertLess(post.index("- name: Hand off after the last delivered review"), post.index("- name: Auto-approve decision"))
step = post.split("- name: Hand off after the last delivered review", 1)[1].split("\n - name:", 1)[0]
self.assertIn("steps.post.outputs.delivered == 'true'", step)
self.assertIn("needs.round-cap.outputs.next_round == inputs.max_rounds", step)
script = "\n".join(line[10:] for line in step.split("run: |\n", 1)[1].splitlines())
with tempfile.TemporaryDirectory() as d:
with open(os.path.join(d, "auto-approve.py"), "w", encoding="utf-8") as f:
f.write("import json, os, sys\nopen(os.environ['ARGS'], 'w').write(json.dumps(sys.argv[1:]))\n")
path = os.path.join(d, "args")
env = {"PATH": os.environ["PATH"], "CURSOR_REVIEW_ASSETS": d, "ARGS": path,
"APP_SLUG": "review", "BOT_TOKEN": "token", "BOT_APP_ID": "1",
"COUNT_SUPERSEDED_ROUNDS": "true", "PRESERVE_ROUND_COUNT": "true",
"REPO": "o/r", "PR_NUMBER": "1", "MAX_ROUNDS": "3", "THRESHOLD": ""}
subprocess.run(["bash", "-e", "-c", script], env=env, check=True, capture_output=True)
with open(path, encoding="utf-8") as f:
args = json.load(f)
for flag in ("--after-review", "--count-superseded-rounds", "--preserve-round-count"):
self.assertIn(flag, args)
self.assertEqual(args[args.index("--poster-login") + 1], "review[bot]")
env["BOT_TOKEN"] = ""
self.assertNotEqual(subprocess.run(["bash", "-e", "-c", script], env=env,
capture_output=True).returncode, 0)


class RoundCapCommandTest(unittest.TestCase):
"""The cap path end to end, with gh stubbed by endpoint."""

def run_cap(self, reviews, max_rounds="5", timeline=(), comments=(), label_exists=True, fail=(), labels=(),
probe_error="HTTP 404", strict=False, count_superseded=False, preserve=False):
probe_error="HTTP 404", strict=False, count_superseded=False, preserve=False, after_review=False):
writes = []

def fake_gh(args, payload=None):
Expand Down Expand Up @@ -1911,7 +1945,7 @@ def fake_gh(args, payload=None):
open(out, "w").close()
args = argparse.Namespace(repo="o/r", pr_number="1", max_rounds=max_rounds, threshold="medium",
poster_login=BOT, fail_closed_round_cap=strict, count_superseded_rounds=count_superseded,
preserve_round_count=preserve)
preserve_round_count=preserve, after_review=after_review)
with mock.patch.dict(os.environ, {"GITHUB_OUTPUT": out}), \
mock.patch.object(AA, "gh", fake_gh), \
mock.patch.object(AA, "open_thread_ids", lambda *a: {"11", "12"}), \
Expand Down Expand Up @@ -2001,6 +2035,34 @@ def test_opt_in_counts_a_delivered_review_superseded_by_a_push(self):
self.assertEqual((default["capped"], default["rounds"]), ("false", "2"))
self.assertEqual((counted["capped"], counted["rounds"]), ("true", "3"))

def test_after_third_review_hands_off_and_describes_completed_round(self):
rc, out, writes = self.run_cap(self.FIVE[:3], max_rounds="3", strict=True,
preserve=True, after_review=True)
self.assertEqual((rc, out["capped"]), (0, "true"))
bodies = [payload["body"] for _, path, payload in writes if path.endswith("/comments")]
self.assertEqual(len(bodies), 1)
self.assertIn("the latest review was delivered", bodies[0])
self.assertNotIn("no new panel ran", bodies[0])

def test_after_review_does_not_reuse_a_pre_review_handoff_notice(self):
prior = {"user": {"login": BOT}, "body": AA.ROUND_CAP_MARKER + "\n" + AA.PRESERVED_CAP_MARKER,
"created_at": "2026-01-06T00:00:00Z"}
_, _, writes = self.run_cap(self.FIVE[:3], max_rounds="3", preserve=True, after_review=True,
comments=[prior])
bodies = [payload["body"] for _, path, payload in writes if path.endswith("/comments")]
self.assertEqual(len(bodies), 1)
self.assertIn("the latest review was delivered", bodies[0])

def test_after_review_fails_if_delivered_round_is_not_visible_yet(self):
rc, _, writes = self.run_cap(self.FIVE[:2], max_rounds="3", strict=True, after_review=True)
self.assertNotEqual(rc, 0)
self.assertIn(("POST", "repos/o/r/issues/1/labels"), [(m, p) for m, p, _ in writes])

def test_after_review_marks_handoff_if_history_cannot_be_read(self):
rc, _, writes = self.run_cap(self.FIVE[:3], max_rounds="3", after_review=True, fail=("/reviews",))
self.assertNotEqual(rc, 0)
self.assertIn(("POST", "repos/o/r/issues/1/labels"), [(m, p) for m, p, _ in writes])

def test_strict_cap_allows_two_and_hands_off_at_three(self):
rc, out, _ = self.run_cap(self.FIVE[:2], max_rounds="3", strict=True)
self.assertEqual((rc, out["capped"], out["rounds"]), (0, "false", "2"))
Expand Down
Loading
Loading