From 0ef425e38b9ac678f962a17cbbbb549903fe3cd9 Mon Sep 17 00:00:00 2001 From: Matt Miller Date: Wed, 7 Oct 2026 02:20:51 +0000 Subject: [PATCH 1/2] feat(cursor-review): add defer_approval so only cursor-approve's decide approves A caller that runs cursor-approve's axes after cursor-review had two approvers in sequence: cursor-review's `decide` APPROVED on severity alone, then cursor-approve's start phase withdrew it. In between, the approval satisfied code-owner review (a merge-race window), and a cursor-review run that failed or was cancelled after approving skipped the start phase, leaving the approval standing until the next push. `defer_approval: true` keeps `approve_gate` exactly as before but, on an APPROVE outcome, posts no review and resolves no thread; it withdraws the approver's own earlier marked approvals instead, as a no-decision round does. REQUEST_CHANGES is unchanged. Default false: existing callers see no change. The cursor-approve guide now sets it on the cursor-review call. Co-Authored-By: Claude Opus 5.5 --- .github/cursor-review/README.md | 1 + .github/cursor-review/auto-approve.py | 28 ++++++- .../cursor-review/tests/test_auto_approve.py | 77 +++++++++++++++++++ .github/workflows/cursor-approve.yml | 8 +- .github/workflows/cursor-review.yml | 21 ++++- docs/callers/cursor-approve.md | 17 +++- docs/callers/cursor-review.md | 3 +- 7 files changed, 142 insertions(+), 13 deletions(-) diff --git a/.github/cursor-review/README.md b/.github/cursor-review/README.md index 1993c755..8a3ba775 100644 --- a/.github/cursor-review/README.md +++ b/.github/cursor-review/README.md @@ -287,6 +287,7 @@ All optional except `workflows_ref` (required, no default) — pass them under | `run_without_label` | `false` | Run on plain PR events instead of requiring the trigger label. Also requires widening the caller's `types:` — see [the setup guide](../../docs/callers/cursor-review.md). | | `blocking` | `false` | Adds the fail-closed **Blocking gate** check: red while any cursor-review finding thread is unresolved and non-outdated, and red when the round that should have produced those threads did not land (including an over-cap skip). Blocking the merge additionally requires marking that check required in the caller's ruleset — see [the blocking section above](#optional-make-the-review-blocking). | | `approve_max_severity` | `''` (off) | Opt-in auto-approve: `medium`, `low` or `nit` → the bot approves (pinned to the reviewed commit) when every finding is at or below it and requests changes when any is above; anything else fails the run. Read the trust model in [the setup guide](../../docs/callers/cursor-review.md#auto-approve) first — the approval is no stronger than push access. | +| `defer_approval` | `false` | For a caller that runs cursor-approve after this workflow: an APPROVE outcome still reports `approve_gate` = `pass` but posts no approval and resolves no thread, and withdraws the approver's own earlier auto-approvals, so cursor-approve's decide is the only approver. | | `max_rounds` | `5` | Per-PR review-round cap; `0` → none. Counts the posting identity's consolidated reviews since `needs-human-review` was last removed; 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). | | `runs_on` | `'"ubuntu-latest"'` | JSON-encoded `runs-on` (same shape as `cursor-review-auto-label.yml`'s) for the four credential-free heavy jobs only: `diff-size`, `preflight`, the `review` panel and `consolidate`. The gate, ledger, Slack notices and every job holding the App token or `pull-requests: write` stay on GitHub-hosted `ubuntu-latest`. Those four run models with unsandboxed shell over PR code, so use a self-hosted pool only if each job gets a fresh pod (fresh filesystem and `$HOME`), holds no cloud identity or token, and can't reach private networks or the metadata server. The image must be linux/x64 with bash, git, curl, jq, python3, gh, tar and GNU coreutils. | diff --git a/.github/cursor-review/auto-approve.py b/.github/cursor-review/auto-approve.py index 046b184f..03e1c181 100644 --- a/.github/cursor-review/auto-approve.py +++ b/.github/cursor-review/auto-approve.py @@ -114,6 +114,15 @@ reviewer's most recent review, so a round-1 APPROVED would otherwise keep counting through a degraded re-run at the same head. +``--defer-approval true`` (the workflow's `defer_approval`, for a caller that +runs cursor-approve's axes after this round): an APPROVE outcome still reports +``pass``, but posts NO review and resolves NO thread — it withdraws this +identity's own earlier marked approvals instead, exactly as a no-decision round +does, so cursor-approve's ``approve-external`` is the only thing that ever +approves and no severity-only approval can satisfy branch protection while the +axes judge (or after a failed run that never reaches them). REQUEST_CHANGES is +unaffected: it approves nothing. + Trust model: every signal here — findings, panel status, judge status — is model output over the PR's own content, so a diff that prompt-injects the panel and judge can steer the round to an approval. The recorded SHA is mutable too — a @@ -742,6 +751,12 @@ def cmd_decide(args) -> int: if event == NONE: emit(f"ℹ️ **Auto-approve: no decision** — {'; '.join(reasons)}.") return withdraw_own_approvals(args) + if event == APPROVE and getattr(args, "defer_approval", "") == "true": + # The gate stays `pass` for cursor-approve, whose decide approves (and + # resolves threads) only once its axes agree. Withdrawing here also + # clears an approval this identity posted before defer was switched on. + emit(f"ℹ️ **Auto-approve: deferred** — {reasons[0]}; approval is left to cursor-approve.") + return withdraw_own_approvals(args, DEFERRED_MESSAGE) body = render_body(event, reasons, threshold, blocking, args.commit_sha, args.base_ref) if event == APPROVE and not REVIEWED_SHA_RE.search(body): @@ -1035,6 +1050,7 @@ def withdraw_own_approvals(args, message: str = "", head_sha=None, live_base=Non STALE_MESSAGE = "New commits pushed — cursor-review auto-approve withdrawn until the next review round." BASE_CHANGED_MESSAGE = "The base branch changed — cursor-review auto-approve withdrawn until the next review round." UNTRUSTED_MESSAGE = "The latest cursor-review round could not be trusted to approve — auto-approve withdrawn until a round that can." +DEFERRED_MESSAGE = "cursor-review defers approval to cursor-approve — auto-approve withdrawn until its axes agree." HUMAN_REVIEW_MESSAGE = f"The PR was labelled `{HUMAN_REVIEW_LABEL}` — cursor-review auto-approve withdrawn." @@ -1604,10 +1620,12 @@ def cmd_approve_external(args) -> int: def cmd_withdraw(args) -> int: """cursor-approve.yml's start phase: withdraw this identity's own marked - approvals before the axes run. cursor-review's `decide` has ALREADY approved - when it reports `approve_gate == 'pass'`, so without this the axes would - judge a PR that is approved for their whole run, and branch protection or - auto-merge could land it before a red axis withdrew the approval.""" + approvals before the axes run. Unless the caller passes cursor-review + `defer_approval: true` (``--defer-approval``), its `decide` has ALREADY + approved when it reports `approve_gate == 'pass'`, so without this the axes + would judge a PR that is approved for their whole run, and branch protection + or auto-merge could land it before a red axis withdrew the approval. With + defer on it is a backstop.""" if not (args.approver_login or "").strip(): print("::error::--approver-login is empty; refusing to run without an identity to withdraw approvals for") return 2 @@ -1634,6 +1652,8 @@ def main() -> int: # `[bot]`, else github-actions[bot]). On APPROVE, only threads it # started are auto-resolved; empty = resolve nothing. d.add_argument("--poster-login", default="") + # `true` = report the gate but never post an APPROVE (see the docstring). + d.add_argument("--defer-approval", default="") s = sub.add_parser("dismiss-stale") s.add_argument("--repo", required=True) s.add_argument("--pr-number", required=True) diff --git a/.github/cursor-review/tests/test_auto_approve.py b/.github/cursor-review/tests/test_auto_approve.py index a2f1137a..ffacb715 100644 --- a/.github/cursor-review/tests/test_auto_approve.py +++ b/.github/cursor-review/tests/test_auto_approve.py @@ -1724,6 +1724,83 @@ def test_counts_are_logged(self): self.assertIn("resolved 1, skipped-human 1, skipped-unbadged 1, skipped-above-threshold 1", lines[-1]) +class DeferApprovalTest(unittest.TestCase): + """`--defer-approval true`: the gate is reported, but only cursor-approve approves.""" + + def run_decide(self, defer, findings=(), reviews=()): + self.writes = [] + self.resolved = [] + + def fake_gh(args, payload=None): + if args[:2] == ["api", "-X"]: + self.writes.append((args[2], args[3], payload)) + return '{"id": 99}' if args[2] == "POST" else "{}" + if args[:2] == ["api", "graphql"]: + return graphql_reviews(list(reviews)) + return json.dumps({"head": {"sha": SHA}, "base": {"ref": "main"}}) + + with tempfile.TemporaryDirectory() as d: + fpath, dpath, out = (os.path.join(d, n) for n in ("c.json", "pr.patch", "out")) + with open(fpath, "w") as f: + json.dump({"findings": list(findings), "panel": PANEL_OK}, f) + with open(dpath, "w") as f: + f.write(DIFF) + open(out, "w").close() + args = argparse.Namespace(threshold="low", findings=fpath, repo="o/r", pr_number="1", + commit_sha=SHA, judge_status="ok", delivered="true", + ungated="0", approver_login="cursor-approver", + reviewed_diff=dpath, base_ref="main", poster_login=POSTER) + if defer is not None: + args.defer_approval = defer + with mock.patch.dict(os.environ, {"GITHUB_OUTPUT": out}), \ + mock.patch.object(AA, "gh", fake_gh), \ + mock.patch.object(AA, "open_thread_severities", lambda *a: []), \ + mock.patch.object(AA, "resolve_eligible_threads", lambda *a: self.resolved.append(a)), \ + mock.patch.object(AA, "emit", lambda *a: None): + rc = AA.cmd_decide(args) + return rc, read_outputs(out).get("approve_gate") + + def test_a_passing_round_posts_nothing_and_resolves_nothing(self): + rc, gate = self.run_decide("true") + self.assertEqual((rc, gate, self.writes, self.resolved), (0, AA.GATE_PASS, [], [])) + + def test_earlier_marked_approvals_by_the_approver_are_withdrawn(self): + own = {"id": 7, "user": {"login": "cursor-approver"}, "state": "APPROVED", + "commit_id": SHA, "body": AA.APPROVE_MARKER} + human = {"id": 8, "user": {"login": "alice"}, "state": "APPROVED", "commit_id": SHA, "body": "lgtm"} + rc, gate = self.run_decide("true", reviews=[own, human]) + self.assertEqual((rc, gate), (0, AA.GATE_PASS)) + self.assertEqual([(m, path) for m, path, _ in self.writes], + [("PUT", "repos/o/r/pulls/1/reviews/7/dismissals")]) + self.assertEqual(self.writes[0][2]["message"], AA.DEFERRED_MESSAGE) + self.assertEqual(self.resolved, []) + + def test_request_changes_is_still_posted(self): + rc, gate = self.run_decide("true", findings=[finding("high")]) + self.assertEqual((rc, gate), (0, AA.GATE_FAIL)) + self.assertEqual([(m, p["event"]) for m, _, p in self.writes], [("POST", AA.REQUEST_CHANGES)]) + + def test_off_still_approves_and_resolves(self): + for defer in (None, "", "false"): + with self.subTest(defer=defer): + rc, gate = self.run_decide(defer) + self.assertEqual((rc, gate), (0, AA.GATE_PASS)) + self.assertEqual([(m, p["event"]) for m, _, p in self.writes], [("POST", AA.APPROVE)]) + self.assertEqual(len(self.resolved), 1) + + def test_the_workflow_passes_the_input_to_decide(self): + with open(WORKFLOW_PATH, encoding="utf-8") as f: + src = f.read() + declared = src[src.index("\n defer_approval:\n"):] + declared = declared[: declared.index("\n max_rounds:\n")] + self.assertIn("type: boolean", declared) + self.assertIn("default: false", declared) + step = src[src.index("- name: Auto-approve decision"):] + step = step[: step.index("\n\n dismiss-stale-approval:")] + self.assertIn("DEFER_APPROVAL: ${{ inputs.defer_approval }}", step) + self.assertIn('--defer-approval "$DEFER_APPROVAL"', step) + + class AutoResolveWiringTest(unittest.TestCase): """The workflow passes the findings poster's login to `decide`.""" diff --git a/.github/workflows/cursor-approve.yml b/.github/workflows/cursor-approve.yml index 7db11ba1..e1226332 100644 --- a/.github/workflows/cursor-approve.yml +++ b/.github/workflows/cursor-approve.yml @@ -5,9 +5,11 @@ name: Cursor approve # passed (`approve_gate == 'pass'`), then call this TWICE: # # phase: start — before the axis jobs (they `needs:` it): withdraws this -# identity's own approvals — cursor-review's decide has -# ALREADY approved when it reports approve_gate == pass, and -# that approval must not stand while the axes judge — then +# identity's own approvals — unless cursor-review ran with +# `defer_approval: true` (recommended: then this phase's +# decide is the only approver), its decide has ALREADY +# approved when it reports approve_gate == pass, and that +# approval must not stand while the axes judge — then # writes the status card (every axis pending, or "Round # limit reached" when cursor-review reported # approve_gate == capped). diff --git a/.github/workflows/cursor-review.yml b/.github/workflows/cursor-review.yml index aa95c57c..a6c9e1db 100644 --- a/.github/workflows/cursor-review.yml +++ b/.github/workflows/cursor-review.yml @@ -338,6 +338,20 @@ on: type: string required: false default: '' + defer_approval: + description: >- + For a caller that runs cursor-approve's per-axis approval after this + workflow. false (default) → no change. true → a round that would + APPROVE still reports `approve_gate` = `pass`, but posts no review and + auto-resolves no thread; it withdraws the approver identity's own + earlier auto-approvals instead, so cursor-approve's `phase: decide` + is the only approver and no severity-only approval stands while the + axes judge — nor after a run that fails before they start. + REQUEST_CHANGES is still posted. No effect unless + `approve_max_severity` is set. See docs/callers/cursor-approve.md. + type: boolean + required: false + default: false max_rounds: description: >- Cap on review rounds per PR. Before the panel starts, the run counts @@ -403,7 +417,8 @@ on: description: >- The round's severity-gate verdict, for a downstream workflow that must run only after a round passed. Exactly one of: `pass` (the - auto-approve decision was APPROVE), `fail` (REQUEST_CHANGES, or an + auto-approve decision was APPROVE — posted, unless `defer_approval` + left it to cursor-approve), `fail` (REQUEST_CHANGES, or an open thread above the threshold withheld approval), `untrusted` (the judge was degraded, a panel cell failed, the review was not delivered, the head moved — or no round was delivered by this run at all, e.g. a @@ -3260,6 +3275,7 @@ jobs: # event's too): decide refuses if the live base differs, and records # it in the review so a later retarget is caught from live state. BASE_REF: ${{ github.event.pull_request.base.ref }} + DEFER_APPROVAL: ${{ inputs.defer_approval }} run: | # Same identity precedence as `Dismiss stale auto-approval`: the login # passed here is the one whose earlier approvals an untrusted round @@ -3290,7 +3306,8 @@ jobs: --approver-login "$LOGIN" \ --reviewed-diff /tmp/pr-diff.patch \ --base-ref "$BASE_REF" \ - --poster-login "$POSTER" + --poster-login "$POSTER" \ + --defer-approval "$DEFER_APPROVAL" dismiss-stale-approval: # Companion to `Auto-approve decision`. A ruleset with diff --git a/docs/callers/cursor-approve.md b/docs/callers/cursor-approve.md index 54a779d4..49ee40ca 100644 --- a/docs/callers/cursor-approve.md +++ b/docs/callers/cursor-approve.md @@ -9,10 +9,19 @@ the context axes (business, design, completeness) are not available yet. ## What it does 1. `cursor-review` runs a round and exposes `approve_gate`, `round` and `max_rounds`. + Call it with `defer_approval: true`: a passing round then reports + `approve_gate == 'pass'` **without** posting an approval (and without + resolving any thread), and withdraws the approving identity's own earlier + approvals. Without it, cursor-review's `decide` APPROVES first, and that + severity-only approval satisfies branch protection or auto-merge until the + start phase withdraws it — and stays standing if the cursor-review run fails + or is cancelled after approving, because the start phase and the axes are + then skipped. With it, this workflow's decide phase is the only approver. 2. `cursor-approve` with `phase: start` first withdraws the approving - identity's own approvals — cursor-review's `decide` has already APPROVED - when it reports `approve_gate == 'pass'`, and that approval must not stand - (and satisfy branch protection or auto-merge) while the axes judge. It then + identity's own approvals — a backstop: with `defer_approval: true` there is + none from this round, but a caller that does not set it has one standing + from cursor-review's `decide`, which must not satisfy branch protection or + auto-merge while the axes judge. It then writes the **status card** — one PR comment, found by `` and edited in place — with every axis pending. When cursor-review reports `approve_gate == 'capped'` it writes @@ -44,6 +53,7 @@ heading, fire a mention or forge the card marker. | `secrets.CURSOR_API_KEY` | The axes bill through it. The only secret an axis receives. | | `secrets.APPROVER_TOKEN` | Token of the approving identity (needs `pull-requests: write` on the repo, and to be allowed to dismiss reviews if branch protection restricts that). Empty → both phases warn and do nothing; there is deliberately no fallback to an App or `GITHUB_TOKEN`. | | cursor-review with `approve_max_severity` set | Without it `approve_gate` is `off` and no axis runs. | +| cursor-review with `defer_approval: true` | Without it cursor-review approves on severity alone before any axis has judged the PR (see step 1). | ## Caller @@ -63,6 +73,7 @@ jobs: with: workflows_ref: approve_max_severity: low + defer_approval: true # only cursor-approve's decide approves secrets: inherit approve-start: diff --git a/docs/callers/cursor-review.md b/docs/callers/cursor-review.md index caacdd78..8f897550 100644 --- a/docs/callers/cursor-review.md +++ b/docs/callers/cursor-review.md @@ -119,6 +119,7 @@ pull-requests: write # posting the consolidated review (and, at the round cap, | `run_without_label` | `false` | Run on every PR rather than waiting for the label. **Also requires widening your caller's `types:`** — see the gotcha. | | `blocking` | `false` | Adds the fail-closed **Blocking gate** check: red while any cursor-review finding thread is unresolved and non-outdated, and red when the round that should have produced those threads did not land (including an over-cap skip). Turning red into a merge block is a second, separate switch — see [the blocking-gate gotchas](#blocking-gate-gotchas). | | `approve_max_severity` | `''` (off) | `medium`, `low` or `nit`: after each round the bot **approves** (pinned to the reviewed commit) when every finding is at or below that severity, and **requests changes** when any is above it. See [auto-approve](#auto-approve). | +| `defer_approval` | `false` | Only for a caller that runs [cursor-approve](cursor-approve.md) after this workflow: a round that would approve still reports `approve_gate` = `pass`, but posts **no** approval and resolves no thread, and withdraws the approver's own earlier auto-approvals instead — so cursor-approve's decide is the only approver. Requests changes as usual. No effect without `approve_max_severity`. | | `max_rounds` | `5` | Cap on review rounds per PR (`0` → no cap). At or over it, no panel runs: 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`. Removing the label resets the count. See [round cap](#round-cap-and-the-approve_gate-output). | | `runs_on` | `'"ubuntu-latest"'` | JSON-encoded `runs-on` for `diff-size`, `preflight`, the `review` panel and `consolidate` only — the jobs that hold no write credential. Every other job stays on GitHub-hosted `ubuntu-latest`. A self-hosted pool is fine only if it is one-job-per-fresh-pod, identity-free and private-network-isolated (those jobs run models with shell over PR code), on linux/x64 with bash, git, curl, jq, python3, gh, tar and GNU coreutils. Empty falls back to the default, so `${{ vars.CURSOR_REVIEW_RUNS_ON }}` is safe while the variable is unset; e.g. `'["self-hosted", "linux", "x64"]'`. | @@ -582,7 +583,7 @@ jobs: | Value | Meaning | |---|---| -| `pass` | The auto-approve decision was APPROVE. | +| `pass` | The auto-approve decision was APPROVE (posted, unless `defer_approval` left it to cursor-approve). | | `fail` | REQUEST_CHANGES, or an earlier round's open thread above the threshold withheld approval. | | `untrusted` | The judge was degraded, a panel cell failed, the review was not delivered, or the head moved — and also any run that delivered no round at all (an unrelated event, an already-reviewed head, an over-cap diff). | | `capped` | The round cap was hit by this run, or the PR carries `needs-human-review` (while `max_rounds` or `approve_max_severity` is set). Wins over `off`. | From c8d24406c4b8263545545d14e96c0fa061811094 Mon Sep 17 00:00:00 2001 From: Matt Miller Date: Wed, 7 Oct 2026 02:49:36 +0000 Subject: [PATCH 2/2] fix(cursor-review): make a deferred approval downgrade the gate like the posting path Addresses the cursor-review panel on #352: - a failed withdrawal of an earlier approval now reports approve_gate=untrusted instead of pass (the approval would otherwise keep satisfying protection); - a deferred pass dismisses the identity's own marked, unedited REQUEST_CHANGES, which a posted APPROVE would have superseded; - the post-decision head/base/needs-human-review re-check now also runs on the deferred path; - --defer-approval is read case- and whitespace-insensitively; - docs: poster_login must match cursor-review's poster under bot_app_id. Co-Authored-By: Claude Opus 5.5 --- .github/cursor-review/README.md | 2 +- .github/cursor-review/auto-approve.py | 82 +++++++++++++++++-- .../cursor-review/tests/test_auto_approve.py | 52 +++++++++++- .github/workflows/cursor-review.yml | 2 +- docs/callers/cursor-approve.md | 11 ++- docs/callers/cursor-review.md | 2 +- 6 files changed, 136 insertions(+), 15 deletions(-) diff --git a/.github/cursor-review/README.md b/.github/cursor-review/README.md index 8a3ba775..011ee366 100644 --- a/.github/cursor-review/README.md +++ b/.github/cursor-review/README.md @@ -287,7 +287,7 @@ All optional except `workflows_ref` (required, no default) — pass them under | `run_without_label` | `false` | Run on plain PR events instead of requiring the trigger label. Also requires widening the caller's `types:` — see [the setup guide](../../docs/callers/cursor-review.md). | | `blocking` | `false` | Adds the fail-closed **Blocking gate** check: red while any cursor-review finding thread is unresolved and non-outdated, and red when the round that should have produced those threads did not land (including an over-cap skip). Blocking the merge additionally requires marking that check required in the caller's ruleset — see [the blocking section above](#optional-make-the-review-blocking). | | `approve_max_severity` | `''` (off) | Opt-in auto-approve: `medium`, `low` or `nit` → the bot approves (pinned to the reviewed commit) when every finding is at or below it and requests changes when any is above; anything else fails the run. Read the trust model in [the setup guide](../../docs/callers/cursor-review.md#auto-approve) first — the approval is no stronger than push access. | -| `defer_approval` | `false` | For a caller that runs cursor-approve after this workflow: an APPROVE outcome still reports `approve_gate` = `pass` but posts no approval and resolves no thread, and withdraws the approver's own earlier auto-approvals, so cursor-approve's decide is the only approver. | +| `defer_approval` | `false` | For a caller that runs cursor-approve after this workflow: an APPROVE outcome still reports `approve_gate` = `pass` but posts no approval and resolves no thread, and withdraws the approver's own earlier auto-approvals and requests for changes, so cursor-approve's decide is the only approver. | | `max_rounds` | `5` | Per-PR review-round cap; `0` → none. Counts the posting identity's consolidated reviews since `needs-human-review` was last removed; 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). | | `runs_on` | `'"ubuntu-latest"'` | JSON-encoded `runs-on` (same shape as `cursor-review-auto-label.yml`'s) for the four credential-free heavy jobs only: `diff-size`, `preflight`, the `review` panel and `consolidate`. The gate, ledger, Slack notices and every job holding the App token or `pull-requests: write` stay on GitHub-hosted `ubuntu-latest`. Those four run models with unsandboxed shell over PR code, so use a self-hosted pool only if each job gets a fresh pod (fresh filesystem and `$HOME`), holds no cloud identity or token, and can't reach private networks or the metadata server. The image must be linux/x64 with bash, git, curl, jq, python3, gh, tar and GNU coreutils. | diff --git a/.github/cursor-review/auto-approve.py b/.github/cursor-review/auto-approve.py index 03e1c181..5ec10e98 100644 --- a/.github/cursor-review/auto-approve.py +++ b/.github/cursor-review/auto-approve.py @@ -120,8 +120,11 @@ identity's own earlier marked approvals instead, exactly as a no-decision round does, so cursor-approve's ``approve-external`` is the only thing that ever approves and no severity-only approval can satisfy branch protection while the -axes judge (or after a failed run that never reaches them). REQUEST_CHANGES is -unaffected: it approves nothing. +axes judge (or after a failed run that never reaches them). It also dismisses +this identity's own earlier REQUEST_CHANGES, which a posted APPROVE would have +superseded. A withdrawal that fails, or a head/base/label change since the read, +downgrades the gate as on the posting path. REQUEST_CHANGES is unaffected: it +approves nothing. Trust model: every signal here — findings, panel status, judge status — is model output over the PR's own content, so a diff that prompt-injects the panel and @@ -751,12 +754,8 @@ def cmd_decide(args) -> int: if event == NONE: emit(f"ℹ️ **Auto-approve: no decision** — {'; '.join(reasons)}.") return withdraw_own_approvals(args) - if event == APPROVE and getattr(args, "defer_approval", "") == "true": - # The gate stays `pass` for cursor-approve, whose decide approves (and - # resolves threads) only once its axes agree. Withdrawing here also - # clears an approval this identity posted before defer was switched on. - emit(f"ℹ️ **Auto-approve: deferred** — {reasons[0]}; approval is left to cursor-approve.") - return withdraw_own_approvals(args, DEFERRED_MESSAGE) + if event == APPROVE and (getattr(args, "defer_approval", "") or "").strip().lower() == "true": + return defer_to_cursor_approve(args, reasons[0]) body = render_body(event, reasons, threshold, blocking, args.commit_sha, args.base_ref) if event == APPROVE and not REVIEWED_SHA_RE.search(body): @@ -836,6 +835,72 @@ def cmd_decide(args) -> int: return 0 +def defer_to_cursor_approve(args, reason: str) -> int: + """`--defer-approval true` on an APPROVE outcome: post nothing, keep the gate. + + The gate stays `pass` for cursor-approve, whose decide approves (and resolves + threads) only once its axes agree — unless one of the steps below says this + round can no longer stand behind it, exactly as the posting path would. + """ + emit(f"ℹ️ **Auto-approve: deferred** — {reason}; approval is left to cursor-approve.") + # Also clears an approval this identity posted before defer was switched on. + # One that cannot be withdrawn keeps satisfying branch protection while the + # axes judge, so the gate must not read `pass` over it (same as a failed POST). + rc = withdraw_own_approvals(args, DEFERRED_MESSAGE) + if rc: + set_output("approve_gate", GATE_UNTRUSTED) + # Posting path: the APPROVE event supersedes this identity's earlier + # REQUEST_CHANGES. Nothing is posted here, so dismiss those instead — else a + # fixed High keeps vetoing the merge until cursor-approve approves, which it + # never does on a red axis. Failing to is red but withholds nothing. + if dismiss_own_change_requests(args): + rc = 1 + # Same post-decision re-check the posting path runs: a push, retarget or + # `needs-human-review` label landing since the read must not leave `pass`. + try: + pr_now = read_pr(args.repo, args.pr_number) + head_now, base_now = pr_head_base(pr_now) + labelled_now = has_label(pr_now, HUMAN_REVIEW_LABEL) + except (RuntimeError, ValueError): + head_now = base_now = None # unknown → treat as moved + labelled_now = False + if head_now != args.commit_sha or base_now != args.base_ref: + set_output("approve_gate", GATE_UNTRUSTED) + emit("ℹ️ **Auto-approve: deferred round superseded** — the PR head or base moved.") + elif labelled_now: + set_output("approve_gate", GATE_CAPPED) + emit(f"ℹ️ **Auto-approve: deferred round superseded** — the PR was labelled `{HUMAN_REVIEW_LABEL}`.") + return rc + + +def dismiss_own_change_requests(args) -> int: + """Dismiss this identity's own unedited, marked REQUEST_CHANGES reviews. + An edited one is someone else's words (see _stale_approvals) and stays.""" + login = (args.approver_login or "").strip().lower() + if not login: + return 0 + try: + ids = [r["id"] for r in list_reviews(args.repo, args.pr_number) + if r.get("state") == "CHANGES_REQUESTED" and not r.get("edited") + and APPROVE_MARKER in (r.get("body") or "") + and (r.get("user") or {}).get("login", "").lower() == login] + except (RuntimeError, ValueError) as e: + print(f"::warning::Could not list reviews to withdraw an earlier request for changes: {annotation_cause(e, 'unknown error')}") + return 1 + failed = [] + for rid in ids: + try: + dismiss(args.repo, args.pr_number, rid, PASSED_MESSAGE) + except RuntimeError as e: + failed.append(f"{rid}: {annotation_cause(e, 'unknown error')}") + if ids: + emit(f"Auto-approve: withdrew {len(ids) - len(failed)}/{len(ids)} earlier request(s) for changes by {args.approver_login}.") + if failed: + print(f"::warning::Could not withdraw {len(failed)} earlier request(s) for changes ({'; '.join(failed)}). {DISMISS_PERMISSION_HINT}") + return 1 + return 0 + + DISMISS_PERMISSION_HINT = ( "Dismissing a review needs an identity allowed to dismiss reviews on this branch: " "pull-requests: write is not enough when branch protection restricts dismissals " @@ -1051,6 +1116,7 @@ def withdraw_own_approvals(args, message: str = "", head_sha=None, live_base=Non BASE_CHANGED_MESSAGE = "The base branch changed — cursor-review auto-approve withdrawn until the next review round." UNTRUSTED_MESSAGE = "The latest cursor-review round could not be trusted to approve — auto-approve withdrawn until a round that can." DEFERRED_MESSAGE = "cursor-review defers approval to cursor-approve — auto-approve withdrawn until its axes agree." +PASSED_MESSAGE = "The latest cursor-review round passed its severity threshold — request for changes withdrawn; approval is left to cursor-approve." HUMAN_REVIEW_MESSAGE = f"The PR was labelled `{HUMAN_REVIEW_LABEL}` — cursor-review auto-approve withdrawn." diff --git a/.github/cursor-review/tests/test_auto_approve.py b/.github/cursor-review/tests/test_auto_approve.py index ffacb715..871215cc 100644 --- a/.github/cursor-review/tests/test_auto_approve.py +++ b/.github/cursor-review/tests/test_auto_approve.py @@ -1727,17 +1727,24 @@ def test_counts_are_logged(self): class DeferApprovalTest(unittest.TestCase): """`--defer-approval true`: the gate is reported, but only cursor-approve approves.""" - def run_decide(self, defer, findings=(), reviews=()): + def run_decide(self, defer, findings=(), reviews=(), fail_put=False, pr_reads=()): self.writes = [] self.resolved = [] + later_reads = list(pr_reads) # PR payloads after the first read, in order def fake_gh(args, payload=None): if args[:2] == ["api", "-X"]: self.writes.append((args[2], args[3], payload)) + if args[2] == "PUT" and fail_put: + raise RuntimeError("gh api failed: 403 dismissals restricted") return '{"id": 99}' if args[2] == "POST" else "{}" if args[:2] == ["api", "graphql"]: return graphql_reviews(list(reviews)) - return json.dumps({"head": {"sha": SHA}, "base": {"ref": "main"}}) + pr = {"head": {"sha": SHA}, "base": {"ref": "main"}} + if getattr(fake_gh, "read", False) and later_reads: + pr = later_reads.pop(0) + fake_gh.read = True + return json.dumps(pr) with tempfile.TemporaryDirectory() as d: fpath, dpath, out = (os.path.join(d, n) for n in ("c.json", "pr.patch", "out")) @@ -1775,6 +1782,47 @@ def test_earlier_marked_approvals_by_the_approver_are_withdrawn(self): self.assertEqual(self.writes[0][2]["message"], AA.DEFERRED_MESSAGE) self.assertEqual(self.resolved, []) + def test_a_failed_withdrawal_downgrades_the_gate(self): + own = {"id": 7, "user": {"login": "cursor-approver"}, "state": "APPROVED", + "commit_id": SHA, "body": AA.APPROVE_MARKER} + rc, gate = self.run_decide("true", reviews=[own], fail_put=True) + self.assertEqual((rc, gate), (1, AA.GATE_UNTRUSTED)) + + def test_own_marked_change_requests_are_dismissed(self): + own = {"id": 5, "user": {"login": "cursor-approver"}, "state": "CHANGES_REQUESTED", + "commit_id": SHA, "body": AA.APPROVE_MARKER} + edited = dict(own, id=6, edited=True) + unmarked = dict(own, id=9, body="please fix") + other = dict(own, id=10, user={"login": "alice"}) + rc, gate = self.run_decide("true", reviews=[own, edited, unmarked, other]) + self.assertEqual((rc, gate), (0, AA.GATE_PASS)) + self.assertEqual([(m, path) for m, path, _ in self.writes], + [("PUT", "repos/o/r/pulls/1/reviews/5/dismissals")]) + self.assertEqual(self.writes[0][2]["message"], AA.PASSED_MESSAGE) + + def test_a_failed_change_request_dismissal_is_red_but_keeps_the_gate(self): + own = {"id": 5, "user": {"login": "cursor-approver"}, "state": "CHANGES_REQUESTED", + "commit_id": SHA, "body": AA.APPROVE_MARKER} + rc, gate = self.run_decide("true", reviews=[own], fail_put=True) + self.assertEqual((rc, gate), (1, AA.GATE_PASS)) + + def test_a_change_since_the_read_downgrades_the_gate(self): + moved = {"head": {"sha": "b" * 40}, "base": {"ref": "main"}} + retargeted = {"head": {"sha": SHA}, "base": {"ref": "dev"}} + labelled = {"head": {"sha": SHA}, "base": {"ref": "main"}, + "labels": [{"name": AA.HUMAN_REVIEW_LABEL}]} + for pr, want in ((moved, AA.GATE_UNTRUSTED), (retargeted, AA.GATE_UNTRUSTED), + (labelled, AA.GATE_CAPPED), ("not a dict", AA.GATE_UNTRUSTED)): + with self.subTest(pr=pr): + rc, gate = self.run_decide("true", pr_reads=[pr]) + self.assertEqual((rc, gate, self.writes), (0, want, [])) + + def test_defer_is_read_case_and_whitespace_insensitively(self): + for defer in ("True", " true ", "TRUE"): + with self.subTest(defer=defer): + rc, gate = self.run_decide(defer) + self.assertEqual((rc, gate, self.writes, self.resolved), (0, AA.GATE_PASS, [], [])) + def test_request_changes_is_still_posted(self): rc, gate = self.run_decide("true", findings=[finding("high")]) self.assertEqual((rc, gate), (0, AA.GATE_FAIL)) diff --git a/.github/workflows/cursor-review.yml b/.github/workflows/cursor-review.yml index a6c9e1db..a338f09d 100644 --- a/.github/workflows/cursor-review.yml +++ b/.github/workflows/cursor-review.yml @@ -344,7 +344,7 @@ on: workflow. false (default) → no change. true → a round that would APPROVE still reports `approve_gate` = `pass`, but posts no review and auto-resolves no thread; it withdraws the approver identity's own - earlier auto-approvals instead, so cursor-approve's `phase: decide` + earlier auto-approvals (and requests for changes) instead, so cursor-approve's `phase: decide` is the only approver and no severity-only approval stands while the axes judge — nor after a run that fails before they start. REQUEST_CHANGES is still posted. No effect unless diff --git a/docs/callers/cursor-approve.md b/docs/callers/cursor-approve.md index 49ee40ca..5e942f96 100644 --- a/docs/callers/cursor-approve.md +++ b/docs/callers/cursor-approve.md @@ -12,7 +12,7 @@ the context axes (business, design, completeness) are not available yet. Call it with `defer_approval: true`: a passing round then reports `approve_gate == 'pass'` **without** posting an approval (and without resolving any thread), and withdraws the approving identity's own earlier - approvals. Without it, cursor-review's `decide` APPROVES first, and that + approvals and requests for changes. Without it, cursor-review's `decide` APPROVES first, and that severity-only approval satisfies branch protection or auto-merge until the start phase withdraws it — and stays standing if the cursor-review run fails or is cancelled after approving, because the start phase and the axes are @@ -122,11 +122,18 @@ jobs: round: ${{ needs.cursor-review.outputs.round }} max_rounds: ${{ needs.cursor-review.outputs.max_rounds }} approve_max_severity: low - poster_login: github-actions[bot] + poster_login: github-actions[bot] # `[bot]` if cursor-review runs with bot_app_id secrets: APPROVER_TOKEN: ${{ secrets.APPROVER_TOKEN }} ``` +With `defer_approval: true`, thread auto-resolution moves here too: this +phase's decide resolves cursor-review's at-or-below-threshold threads only when +`approve_max_severity` and `poster_login` are both set, and `poster_login` must +be the login cursor-review posts findings under — `[bot]` when +cursor-review runs with `bot_app_id`, else `github-actions[bot]`. A wrong login +resolves nothing, so a "require conversation resolution" ruleset still blocks. + Pass secrets explicitly to the axes — never `secrets: inherit` — so each axis receives `CURSOR_API_KEY` and nothing else. `always()` on the decide job makes a failed axis read as "no result" (withheld) instead of skipping the decision and diff --git a/docs/callers/cursor-review.md b/docs/callers/cursor-review.md index 8f897550..bd2bd2d5 100644 --- a/docs/callers/cursor-review.md +++ b/docs/callers/cursor-review.md @@ -119,7 +119,7 @@ pull-requests: write # posting the consolidated review (and, at the round cap, | `run_without_label` | `false` | Run on every PR rather than waiting for the label. **Also requires widening your caller's `types:`** — see the gotcha. | | `blocking` | `false` | Adds the fail-closed **Blocking gate** check: red while any cursor-review finding thread is unresolved and non-outdated, and red when the round that should have produced those threads did not land (including an over-cap skip). Turning red into a merge block is a second, separate switch — see [the blocking-gate gotchas](#blocking-gate-gotchas). | | `approve_max_severity` | `''` (off) | `medium`, `low` or `nit`: after each round the bot **approves** (pinned to the reviewed commit) when every finding is at or below that severity, and **requests changes** when any is above it. See [auto-approve](#auto-approve). | -| `defer_approval` | `false` | Only for a caller that runs [cursor-approve](cursor-approve.md) after this workflow: a round that would approve still reports `approve_gate` = `pass`, but posts **no** approval and resolves no thread, and withdraws the approver's own earlier auto-approvals instead — so cursor-approve's decide is the only approver. Requests changes as usual. No effect without `approve_max_severity`. | +| `defer_approval` | `false` | Only for a caller that runs [cursor-approve](cursor-approve.md) after this workflow: a round that would approve still reports `approve_gate` = `pass`, but posts **no** approval and resolves no thread, and withdraws the approver's own earlier auto-approvals and requests for changes instead — so cursor-approve's decide is the only approver. Requests changes as usual. No effect without `approve_max_severity`. | | `max_rounds` | `5` | Cap on review rounds per PR (`0` → no cap). At or over it, no panel runs: 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`. Removing the label resets the count. See [round cap](#round-cap-and-the-approve_gate-output). | | `runs_on` | `'"ubuntu-latest"'` | JSON-encoded `runs-on` for `diff-size`, `preflight`, the `review` panel and `consolidate` only — the jobs that hold no write credential. Every other job stays on GitHub-hosted `ubuntu-latest`. A self-hosted pool is fine only if it is one-job-per-fresh-pod, identity-free and private-network-isolated (those jobs run models with shell over PR code), on linux/x64 with bash, git, curl, jq, python3, gh, tar and GNU coreutils. Empty falls back to the default, so `${{ vars.CURSOR_REVIEW_RUNS_ON }}` is safe while the variable is unset; e.g. `'["self-hosted", "linux", "x64"]'`. |