From 5e12caed8c0e28ed67d0186afd0dbfefdcc31bba Mon Sep 17 00:00:00 2001 From: Matt Miller Date: Fri, 9 Oct 2026 00:15:38 -0700 Subject: [PATCH 1/2] fix(cursor-approve): keep a red panel cell from skipping the axes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit cursor-review's called job goes red whenever a panel cell errors — the leg fails by design and `Panel integrity` fails alongside it — and `approve_max_failed_reviewers` does not change that: it governs the `approve_gate` verdict, not the job's conclusion. The published caller pattern chained `approve-start` and every axis off that job with a bare `needs:`, so GitHub's default rule skipped them on the red job, and decide — which runs on `always()` — reported every axis as "no result" and withheld. A caller that set `approve_max_failed_reviewers: 1` precisely to tolerate one dead cell therefore never got the tolerance: one errored cell out of six withheld every round, and nothing on the card said why. Observed on Comfy-Org/cloud#12668: the `edge-case (kimi-k3-high)` cell died on Cursor-side `resource_exhausted` after three reconnects, `Panel integrity` reported 3 of 4 cells, and `approve-start` plus both axes skipped while decide rendered two `no result` rows. `approve_gate` was `pass` throughout — decide's own `if:` requires it — so the gate had already tolerated the cell exactly as configured. Across the 81 preceding panel runs on that repo the axes had never once run. Guard the start phase and every axis with `!cancelled()` (not `always()`, so a superseded run never decides), and restate `needs.approve-start.result == 'success'` on the axes, which `!cancelled()` would otherwise drop — a start phase that failed to withdraw cursor-review's standing approval must still skip them. `approve_gate` stays the only authority on whether a round may be decided, and it already fails closed to `untrusted` on a degraded judge, more errored cells than the caller tolerates, an undelivered review, a moved head, or any upstream decision job that did not succeed. `test_caller_doc_pattern.py` pins the guards: a bare `if:` in the snippet parses, lints and silently withholds, so it cannot be a style question. The page joins this suite's path filter so a docs-only revert runs it. Also corrects two comments that made the trap invisible: `Panel integrity` called itself "advisory — red here fails no other job", true of check-runs and of this workflow but not of a caller's `needs:`, and `approve_max_failed_reviewers` promised a round "decided normally" without saying what the caller must do for that to hold. No runtime behaviour in this repo changes; the fix each caller needs is the `if:` guards above. Co-Authored-By: Claude Opus 5 --- .../tests/test_caller_doc_pattern.py | 165 ++++++++++++++++++ .github/workflows/cursor-review.yml | 24 ++- .../workflows/test-cursor-review-scripts.yml | 16 ++ docs/callers/cursor-approve.md | 60 ++++++- 4 files changed, 255 insertions(+), 10 deletions(-) create mode 100644 .github/cursor-approve/tests/test_caller_doc_pattern.py diff --git a/.github/cursor-approve/tests/test_caller_doc_pattern.py b/.github/cursor-approve/tests/test_caller_doc_pattern.py new file mode 100644 index 00000000..f1bc6085 --- /dev/null +++ b/.github/cursor-approve/tests/test_caller_doc_pattern.py @@ -0,0 +1,165 @@ +#!/usr/bin/env python3 +"""Pins the `if:` guards on the caller pattern in docs/callers/cursor-approve.md. + +cursor-review's called job goes RED whenever a panel cell errors: the leg fails +by design ("Fail the leg when the cell did not submit") and `Panel integrity` +fails alongside it. Neither is affected by `approve_max_failed_reviewers`, which +governs the `approve_gate` VERDICT and not the job's conclusion. So a caller +that chains the start phase and the axes off that job with a bare `needs:` has +them skipped by GitHub's default rule, and decide — which runs on `always()` — +reports every axis as "no result" and withholds. + +That is not hypothetical: it is what the published pattern did. One errored +`edge-case` cell out of six took the axes out of a real run on a caller that had +set `approve_max_failed_reviewers: 1` precisely to tolerate it, and across the +81 preceding panel runs on that repo the axes had never once run. + +A copied caller is as good as its snippet, and `!cancelled()` reads like a +stylistic flourish to anyone editing it later — a bare `if:` here parses, lints, +and silently withholds every approval. So the guards are pinned. + +Deliberately parsed WITHOUT PyYAML, like its sibling suites: this repo is +stdlib-only and CI installs no requirements for these tests. + +Run: python3 .github/cursor-approve/tests/test_caller_doc_pattern.py +""" + +import os +import re +import unittest + +DOC = os.path.normpath( + os.path.join( + os.path.dirname(__file__), "..", "..", "..", "docs", "callers", "cursor-approve.md" + ) +) + +YAML_BLOCK = re.compile(r"^```yaml$(.*?)^```$", re.M | re.S) +JOB_HEADER = re.compile(r"^ ([A-Za-z0-9_-]+):\s*$") +# `if:` through to the next key at the same indent (or the next job). +IF_KEY = re.compile(r"^ if:\s*(.*)$") +SAME_LEVEL_KEY = re.compile(r"^ [A-Za-z0-9_-]+:") + +# Every job id the pattern documents that must not be skipped by a red +# cursor-review. Named explicitly rather than matched by prefix so a renamed or +# deleted block fails loudly instead of passing vacuously. +START = "approve-start" +AXES = ( + "axis-correctness", + "axis-conformance", + "axis-business", + "axis-design", + "axis-completeness", +) +DECIDE = "cursor-approve" + + +def _jobs(): + """{job_id: flattened `if:` expression} over every yaml block in the doc.""" + with open(DOC, encoding="utf-8") as fh: + text = fh.read() + out = {} + for block in YAML_BLOCK.findall(text): + lines = block.splitlines() + job = None + for i, line in enumerate(lines): + header = JOB_HEADER.match(line) + if header: + job = header.group(1) + continue + if job is None: + continue + key = IF_KEY.match(line) + if not key: + continue + parts = [key.group(1)] + for cont in lines[i + 1:]: + if SAME_LEVEL_KEY.match(cont) or JOB_HEADER.match(cont): + break + parts.append(cont.strip()) + # `>-` / `|` block scalars fold to one line; comments are not part + # of the expression. + expr = " ".join( + p for p in parts if p and not p.startswith("#") and p not in (">-", ">", "|", "|-") + ) + out[job] = re.sub(r"\s+", " ", expr).strip() + return out + + +class CallerPattern(unittest.TestCase): + def setUp(self): + self.jobs = _jobs() + + def test_every_documented_job_is_present(self): + for job in (START, DECIDE) + AXES: + self.assertIn( + job, + self.jobs, + f"{job} has no `if:` in any yaml block of {DOC} — the pattern was " + "renamed or deleted, so the guards below assert nothing.", + ) + + def test_start_phase_survives_a_red_cursor_review(self): + expr = self.jobs[START] + self.assertIn( + "!cancelled()", + expr, + f"{START} must carry `!cancelled()`: a red panel cell puts the " + f"caller's cursor-review job in `failure` and GitHub's default " + f"`needs:` rule would skip this job, taking the axes with it. Got: {expr}", + ) + self.assertNotIn( + "always()", + expr, + f"{START} must use `!cancelled()`, not `always()` — a superseded " + f"(cancelled) run must never go on to decide. Got: {expr}", + ) + + def test_axes_survive_a_red_cursor_review(self): + for job in AXES: + expr = self.jobs[job] + self.assertIn( + "!cancelled()", + expr, + f"{job} must carry `!cancelled()` for the same reason as " + f"{START}. Got: {expr}", + ) + + def test_axes_still_require_a_successful_start_phase(self): + # `!cancelled()` also lifts the implicit "approve-start succeeded" + # requirement, so that half has to be restated. A start phase that + # failed to withdraw cursor-review's standing approval must still skip + # the axes, which decide reads as "no result". + for job in AXES: + expr = self.jobs[job] + self.assertRegex( + expr, + r"needs\.approve-start\.result\s*==\s*'success'", + f"{job} carries `!cancelled()`, which drops the implicit " + f"requirement that {START} succeeded, so it must restate it as " + f"`needs.approve-start.result == 'success'`. Got: {expr}", + ) + + def test_every_guarded_job_still_gates_on_approve_gate(self): + # `approve_gate` is the only authority on whether a round may be + # decided; it already fails closed (`untrusted`) on a degraded judge, + # more errored cells than the caller tolerates, an undelivered review, + # a moved head, or any upstream decision job that did not succeed. + # Dropping it while keeping `!cancelled()` is what would actually + # loosen the gate. + for job in (START, DECIDE) + AXES: + self.assertIn( + "needs.cursor-review.outputs.approve_gate", + self.jobs[job], + f"{job} must still gate on cursor-review's `approve_gate` " + f"output. Got: {self.jobs[job]}", + ) + + def test_decide_still_runs_on_always(self): + # Unchanged by this pattern, and the reason a withheld round still + # leaves a card: decide must run even when the axes skipped. + self.assertIn("always()", self.jobs[DECIDE]) + + +if __name__ == "__main__": + unittest.main() diff --git a/.github/workflows/cursor-review.yml b/.github/workflows/cursor-review.yml index 4437bd25..bcb945e1 100644 --- a/.github/workflows/cursor-review.yml +++ b/.github/workflows/cursor-review.yml @@ -439,7 +439,12 @@ on: metadata is missing, or a review type (`adversarial` or `edge-case`) has no reviewer that completed. Applies to the decision `defer_approval` hands to cursor-approve too. No effect unless `approve_max_severity` - is set. + is set. A tolerated errored cell still turns THIS WORKFLOW's called job + red (the leg itself, and `Panel integrity` with it), so a caller that + chains jobs off it — the cursor-approve axes above all — must guard + them with `!cancelled()` or GitHub's default `needs:` rule skips them + and the tolerance buys nothing. See docs/callers/cursor-approve.md + ("A red panel cell must not skip the axes"). type: number required: false default: 0 @@ -4382,9 +4387,20 @@ jobs: # `edge-case (kimi-k3-high)` bricks every PR the day that pin moves. # # ADVISORY by default, exactly like `Blocking gate`: red here fails no other - # job, gates no merge, and does not gate `post-review` — a caller that wants - # it to block marks ` / Panel integrity` a required check in - # its own ruleset. See docs/callers/cursor-review.md. + # job IN THIS WORKFLOW, gates no merge, and does not gate `post-review` — a + # caller that wants it to block marks ` / Panel integrity` a + # required check in its own ruleset. See docs/callers/cursor-review.md. + # + # "Advisory" stops at this workflow's edge, and the distinction is not + # academic. Red here puts the CALLER's `uses:` job in `failure`, so any + # caller job chained off it with a bare `needs:` is skipped by GitHub's + # default rule — which is how one errored cell silently stopped the + # cursor-approve axes from running at all, and withheld every approval, on a + # caller that had set `approve_max_failed_reviewers: 1` precisely to tolerate + # it. A red matrix leg does this on its own too, so dropping the check would + # not have helped. Downstream caller jobs must be guarded with `!cancelled()` + # and gated on `approve_gate`, which already fails closed; see + # docs/callers/cursor-approve.md ("A red panel cell must not skip the axes"). # # `always()`, and the same four gate conditions `consolidate` uses, so this # reports on exactly the runs where a panel was supposed to happen and stays diff --git a/.github/workflows/test-cursor-review-scripts.yml b/.github/workflows/test-cursor-review-scripts.yml index 777bf0d3..414b6ae3 100644 --- a/.github/workflows/test-cursor-review-scripts.yml +++ b/.github/workflows/test-cursor-review-scripts.yml @@ -23,6 +23,12 @@ name: Test cursor-review scripts # deliberately NOT listed below — no suite this workflow runs reads it, and a # docs-only PR that deletes the `blocking` row (the #31 scenario) still fires # the alarm, over there. +# +# docs/callers/cursor-approve.md IS listed, for the opposite reason: a suite +# here does read it. test_caller_doc_pattern.py pins the `if:` guards on the +# caller snippet, because a copied caller is only as good as the snippet and +# dropping `!cancelled()` from it silently withholds every approval (see that +# file's docstring). on: pull_request: @@ -36,6 +42,11 @@ on: - '.github/workflows/cursor-approve.yml' - '.github/workflows/cursor-axis-base.yml' - '.github/workflows/axis-*.yml' + # test_caller_doc_pattern.py reads the caller snippet out of this page and + # pins its `if:` guards. Unlike docs/callers/cursor-review.md (see the + # note above), a suite HERE parses it, and the regression it guards is a + # docs-only edit — dropping `!cancelled()` from a snippet a caller copies. + - 'docs/callers/cursor-approve.md' - '.github/workflows/test-cursor-review-scripts.yml' push: branches: [main] @@ -49,6 +60,11 @@ on: - '.github/workflows/cursor-approve.yml' - '.github/workflows/cursor-axis-base.yml' - '.github/workflows/axis-*.yml' + # test_caller_doc_pattern.py reads the caller snippet out of this page and + # pins its `if:` guards. Unlike docs/callers/cursor-review.md (see the + # note above), a suite HERE parses it, and the regression it guards is a + # docs-only edit — dropping `!cancelled()` from a snippet a caller copies. + - 'docs/callers/cursor-approve.md' - '.github/workflows/test-cursor-review-scripts.yml' permissions: diff --git a/docs/callers/cursor-approve.md b/docs/callers/cursor-approve.md index f72fcdcb..4706bef9 100644 --- a/docs/callers/cursor-approve.md +++ b/docs/callers/cursor-approve.md @@ -228,7 +228,13 @@ jobs: approve-start: needs: cursor-review - if: needs.cursor-review.outputs.approve_gate == 'pass' || needs.cursor-review.outputs.approve_gate == 'capped' + # `!cancelled()`, not a bare condition: cursor-review's called job goes red + # on any errored panel cell, which would otherwise skip this job. See + # "A red panel cell must not skip the axes" below. + if: >- + !cancelled() + && (needs.cursor-review.outputs.approve_gate == 'pass' + || needs.cursor-review.outputs.approve_gate == 'capped') uses: Comfy-Org/github-workflows/.github/workflows/cursor-approve.yml@ # v1 with: workflows_ref: @@ -243,7 +249,10 @@ jobs: axis-correctness: needs: [cursor-review, approve-start] - if: needs.cursor-review.outputs.approve_gate == 'pass' + if: >- + !cancelled() + && needs.approve-start.result == 'success' + && needs.cursor-review.outputs.approve_gate == 'pass' uses: Comfy-Org/github-workflows/.github/workflows/axis-correctness.yml@ # v1 with: commit_sha: ${{ github.event.pull_request.head.sha }} @@ -252,7 +261,10 @@ jobs: axis-conformance: needs: [cursor-review, approve-start] - if: needs.cursor-review.outputs.approve_gate == 'pass' + if: >- + !cancelled() + && needs.approve-start.result == 'success' + && needs.cursor-review.outputs.approve_gate == 'pass' uses: Comfy-Org/github-workflows/.github/workflows/axis-conformance.yml@ # v1 with: commit_sha: ${{ github.event.pull_request.head.sha }} @@ -298,6 +310,33 @@ leaving an earlier approval standing. The axes `needs: approve-start` so they never start while cursor-review's approval still stands; a start phase that fails to withdraw it skips them, which decide reads as "no result". +### A red panel cell must not skip the axes + +`!cancelled()` on the start phase and the axes is load-bearing. cursor-review's +called job goes **red whenever a panel cell errors** — the leg fails by design +and `Panel integrity` fails alongside it — and `approve_max_failed_reviewers` +does not change that. That input governs the `approve_gate` verdict, not the +job's conclusion, so a tolerated errored cell still leaves the called job in +`failure`. + +Without `!cancelled()`, GitHub's default `needs:` rule skips the start phase on +that red job; the axes skip with it; and decide, which runs on `always()`, +reports every axis as ⚠️ no result and withholds. A caller that sets +`approve_max_failed_reviewers` above 0 and omits `!cancelled()` therefore never +gets the tolerance it configured — one errored cell out of six withholds every +round, and nothing on the card says why. + +This does not widen what may be approved. `approve_gate` stays the only +authority on whether a round may be decided, and reading it off a red +cursor-review job cannot approve a round the gate itself rejected: it is already +`untrusted` when the judge was degraded, when more cells errored than the caller +tolerates, when the review did not land as threads or when the head moved, and +it falls back to `untrusted` whenever an upstream decision job did not succeed — +which is every Panel integrity failure that is not simply a short panel. The +axes keep an explicit `needs.approve-start.result == 'success'` rather than a +blanket `!cancelled()` so the invariant above is unchanged: a start phase that +failed to withdraw cursor-review's standing approval still skips them. + ## Inputs `cursor-approve.yml`: @@ -401,7 +440,10 @@ Business and design fetch the change from the GitHub compare API, which ```yaml axis-business: needs: [cursor-review, approve-start] - if: needs.cursor-review.outputs.approve_gate == 'pass' + if: >- + !cancelled() + && needs.approve-start.result == 'success' + && needs.cursor-review.outputs.approve_gate == 'pass' uses: Comfy-Org/github-workflows/.github/workflows/axis-business.yml@ # v1 with: commit_sha: ${{ github.event.pull_request.head.sha }} @@ -412,7 +454,10 @@ Business and design fetch the change from the GitHub compare API, which axis-design: needs: [cursor-review, approve-start] - if: needs.cursor-review.outputs.approve_gate == 'pass' + if: >- + !cancelled() + && needs.approve-start.result == 'success' + && needs.cursor-review.outputs.approve_gate == 'pass' uses: Comfy-Org/github-workflows/.github/workflows/axis-design.yml@ # v1 with: commit_sha: ${{ github.event.pull_request.head.sha }} @@ -423,7 +468,10 @@ Business and design fetch the change from the GitHub compare API, which axis-completeness: needs: [cursor-review, approve-start] - if: needs.cursor-review.outputs.approve_gate == 'pass' + if: >- + !cancelled() + && needs.approve-start.result == 'success' + && needs.cursor-review.outputs.approve_gate == 'pass' uses: Comfy-Org/github-workflows/.github/workflows/axis-completeness.yml@ # v1 with: commit_sha: ${{ github.event.pull_request.head.sha }} From b3db43e878218348960d97e851b72ba55a490c8c Mon Sep 17 00:00:00 2001 From: Matt Miller Date: Fri, 9 Oct 2026 08:44:59 +0000 Subject: [PATCH 2/2] fix(cursor-approve): pin the caller guards as exact conjuncts, and say what `!cancelled()` gives up Review round on the red-panel-cell fix: - test_caller_doc_pattern.py now splits each `if:` on top-level `&&` and asserts the exact conjuncts, rejecting a top-level `||`, `!= 'pass'`, a bare truthy approve_gate, and a stray `#` line inside the block scalar. Every occurrence of a job across all yaml blocks is checked, not just the last one parsed. - docs/callers/cursor-review.md's `next:` approve_gate example gets the same `!cancelled()` guard and is pinned by the same suite (so it joins the test workflow's path filter). - cursor-approve.md no longer claims the guard widens nothing: it names the incidental backstop a red leg used to give against a cell forging another cell's findings artifact. Step 1 of "What it does" no longer says a failed run skips the start phase. - approve_max_failed_reviewers' description says `!cancelled()` drops the implicit success requirement on other needs, which must be restated. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_caller_doc_pattern.py | 214 +++++++++++------- .github/workflows/cursor-review.yml | 7 +- .../workflows/test-cursor-review-scripts.yml | 29 ++- docs/callers/cursor-approve.md | 43 ++-- docs/callers/cursor-review.md | 5 +- 5 files changed, 191 insertions(+), 107 deletions(-) diff --git a/.github/cursor-approve/tests/test_caller_doc_pattern.py b/.github/cursor-approve/tests/test_caller_doc_pattern.py index f1bc6085..841e12d7 100644 --- a/.github/cursor-approve/tests/test_caller_doc_pattern.py +++ b/.github/cursor-approve/tests/test_caller_doc_pattern.py @@ -18,6 +18,15 @@ stylistic flourish to anyone editing it later — a bare `if:` here parses, lints, and silently withholds every approval. So the guards are pinned. +The guards are pinned as EXACT top-level conjuncts, not substrings: a `||` in +place of an `&&`, an `approve_gate != 'pass'`, or a bare truthy +`approve_gate` (which `fail`/`untrusted` would satisfy) all keep every +substring and all fail open. Every occurrence of a job across every yaml block +is checked, so a stale second copy cannot hide behind a fixed first one. + +docs/callers/cursor-review.md's `next:` example is pinned too: it is the +canonical "chain a job off approve_gate" snippet and fails the same way. + Deliberately parsed WITHOUT PyYAML, like its sibling suites: this repo is stdlib-only and CI installs no requirements for these tests. @@ -28,17 +37,15 @@ import re import unittest -DOC = os.path.normpath( - os.path.join( - os.path.dirname(__file__), "..", "..", "..", "docs", "callers", "cursor-approve.md" - ) +DOCS_DIR = os.path.normpath( + os.path.join(os.path.dirname(__file__), "..", "..", "..", "docs", "callers") ) +APPROVE_DOC = os.path.join(DOCS_DIR, "cursor-approve.md") +REVIEW_DOC = os.path.join(DOCS_DIR, "cursor-review.md") YAML_BLOCK = re.compile(r"^```yaml$(.*?)^```$", re.M | re.S) JOB_HEADER = re.compile(r"^ ([A-Za-z0-9_-]+):\s*$") -# `if:` through to the next key at the same indent (or the next job). IF_KEY = re.compile(r"^ if:\s*(.*)$") -SAME_LEVEL_KEY = re.compile(r"^ [A-Za-z0-9_-]+:") # Every job id the pattern documents that must not be skipped by a red # cursor-review. Named explicitly rather than matched by prefix so a renamed or @@ -52,11 +59,28 @@ "axis-completeness", ) DECIDE = "cursor-approve" - - -def _jobs(): - """{job_id: flattened `if:` expression} over every yaml block in the doc.""" - with open(DOC, encoding="utf-8") as fh: +NEXT = "next" + +GATE = "needs.cursor-review.outputs.approve_gate" +START_CONJUNCTS = [ + "!cancelled()", + f"({GATE} == 'pass' || {GATE} == 'capped')", +] +AXIS_CONJUNCTS = [ + "!cancelled()", + "needs.approve-start.result == 'success'", + f"{GATE} == 'pass'", +] +NEXT_CONJUNCTS = ["!cancelled()", f"{GATE} == 'pass'"] + + +def _jobs(path): + """{job_id: [flattened `if:` expression, ...]} over every yaml block. + + A list per job, one entry per occurrence, so a job documented in two blocks + is checked in both rather than the later copy silently winning. + """ + with open(path, encoding="utf-8") as fh: text = fh.read() out = {} for block in YAML_BLOCK.findall(text): @@ -72,93 +96,131 @@ def _jobs(): key = IF_KEY.match(line) if not key: continue - parts = [key.group(1)] - for cont in lines[i + 1:]: - if SAME_LEVEL_KEY.match(cont) or JOB_HEADER.match(cont): - break - parts.append(cont.strip()) - # `>-` / `|` block scalars fold to one line; comments are not part - # of the expression. - expr = " ".join( - p for p in parts if p and not p.startswith("#") and p not in (">-", ">", "|", "|-") - ) - out[job] = re.sub(r"\s+", " ", expr).strip() + first = key.group(1).strip() + parts = [] + if first in (">-", ">", "|", "|-"): + # A block scalar's content is everything indented deeper than + # the key. A `#` line in there is CONTENT, not a comment, so it + # is kept and then fails the exact-conjunct checks below. + for cont in lines[i + 1:]: + if cont.strip() and len(cont) - len(cont.lstrip()) <= 4: + break + parts.append(cont.strip()) + else: + parts.append(first) + expr = re.sub(r"\s+", " ", " ".join(p for p in parts if p)).strip() + wrapped = re.fullmatch(r"\$\{\{(.*)\}\}", expr) + if wrapped: + expr = wrapped.group(1).strip() + out.setdefault(job, []).append(expr) + return out + + +def _conjuncts(expr): + """Split on top-level `&&`; a top-level `||` is returned as a failure marker. + + Parenthesised groups are kept whole, so `a && (b || c)` is two conjuncts. + """ + out, depth, cur, i = [], 0, "", 0 + while i < len(expr): + ch = expr[i] + if ch == "(": + depth += 1 + elif ch == ")": + depth -= 1 + if depth == 0 and expr.startswith("&&", i): + out.append(cur.strip()) + cur, i = "", i + 2 + continue + if depth == 0 and expr.startswith("||", i): + return None + cur += ch + i += 1 + out.append(cur.strip()) return out class CallerPattern(unittest.TestCase): def setUp(self): - self.jobs = _jobs() + self.jobs = _jobs(APPROVE_DOC) + + def _assert_conjuncts(self, job, exprs, expected): + for expr in exprs: + got = _conjuncts(expr) + self.assertIsNotNone( + got, + f"{job}: a top-level `||` in its `if:` lets any one side run it " + f"on its own, which fails open. Got: {expr}", + ) + self.assertEqual( + sorted(got), + sorted(expected), + f"{job}: `if:` must be exactly the conjunction of {expected}. " + f"`!cancelled()` keeps a red panel cell from skipping it; the " + f"rest restate what `!cancelled()` drops and keep the " + f"`approve_gate` comparison exact. Got: {expr}", + ) def test_every_documented_job_is_present(self): for job in (START, DECIDE) + AXES: self.assertIn( job, self.jobs, - f"{job} has no `if:` in any yaml block of {DOC} — the pattern was " - "renamed or deleted, so the guards below assert nothing.", + f"{job} has no `if:` in any yaml block of {APPROVE_DOC} — the " + "pattern was renamed or deleted, so the guards below assert nothing.", ) def test_start_phase_survives_a_red_cursor_review(self): - expr = self.jobs[START] - self.assertIn( - "!cancelled()", - expr, - f"{START} must carry `!cancelled()`: a red panel cell puts the " - f"caller's cursor-review job in `failure` and GitHub's default " - f"`needs:` rule would skip this job, taking the axes with it. Got: {expr}", - ) - self.assertNotIn( - "always()", - expr, - f"{START} must use `!cancelled()`, not `always()` — a superseded " - f"(cancelled) run must never go on to decide. Got: {expr}", - ) + # `!cancelled()`, never `always()`: a superseded (cancelled) run must + # never go on to decide. The exact-conjunct check rejects both a + # missing guard and an `always()` in its place. + self._assert_conjuncts(START, self.jobs[START], START_CONJUNCTS) - def test_axes_survive_a_red_cursor_review(self): - for job in AXES: - expr = self.jobs[job] - self.assertIn( - "!cancelled()", - expr, - f"{job} must carry `!cancelled()` for the same reason as " - f"{START}. Got: {expr}", - ) - - def test_axes_still_require_a_successful_start_phase(self): + def test_axes_survive_a_red_cursor_review_and_still_need_start(self): # `!cancelled()` also lifts the implicit "approve-start succeeded" # requirement, so that half has to be restated. A start phase that # failed to withdraw cursor-review's standing approval must still skip - # the axes, which decide reads as "no result". - for job in AXES: - expr = self.jobs[job] - self.assertRegex( - expr, - r"needs\.approve-start\.result\s*==\s*'success'", - f"{job} carries `!cancelled()`, which drops the implicit " - f"requirement that {START} succeeded, so it must restate it as " - f"`needs.approve-start.result == 'success'`. Got: {expr}", - ) - - def test_every_guarded_job_still_gates_on_approve_gate(self): - # `approve_gate` is the only authority on whether a round may be - # decided; it already fails closed (`untrusted`) on a degraded judge, - # more errored cells than the caller tolerates, an undelivered review, - # a moved head, or any upstream decision job that did not succeed. - # Dropping it while keeping `!cancelled()` is what would actually + # the axes, which decide reads as "no result". And `approve_gate` is + # the only authority on whether a round may be decided; dropping or + # loosening it while keeping `!cancelled()` is what would actually # loosen the gate. - for job in (START, DECIDE) + AXES: - self.assertIn( - "needs.cursor-review.outputs.approve_gate", - self.jobs[job], - f"{job} must still gate on cursor-review's `approve_gate` " - f"output. Got: {self.jobs[job]}", - ) + for job in AXES: + self._assert_conjuncts(job, self.jobs[job], AXIS_CONJUNCTS) - def test_decide_still_runs_on_always(self): + def test_decide_still_runs_on_always_and_gates_on_pass(self): # Unchanged by this pattern, and the reason a withheld round still # leaves a card: decide must run even when the axes skipped. - self.assertIn("always()", self.jobs[DECIDE]) + self._assert_conjuncts( + DECIDE, self.jobs[DECIDE], ["always()", f"{GATE} == 'pass'"] + ) + + def test_cursor_review_doc_next_example_survives_a_red_cursor_review(self): + jobs = _jobs(REVIEW_DOC) + self.assertIn( + NEXT, + jobs, + f"the `{NEXT}:` approve_gate example is gone from {REVIEW_DOC}; " + "update this test to follow it rather than letting it pass vacuously.", + ) + self._assert_conjuncts(NEXT, jobs[NEXT], NEXT_CONJUNCTS) + + +class Parser(unittest.TestCase): + """The parser has to see the fail-open shapes the guards exist to catch.""" + + def test_top_level_or_is_rejected(self): + self.assertIsNone(_conjuncts(f"!cancelled() || {GATE} == 'pass'")) + + def test_parenthesised_or_stays_one_conjunct(self): + self.assertEqual( + _conjuncts(START_CONJUNCTS[0] + " && " + START_CONJUNCTS[1]), + START_CONJUNCTS, + ) + + def test_bare_truthy_gate_is_not_the_comparison(self): + self.assertNotEqual( + sorted(_conjuncts(f"!cancelled() && {GATE}")), sorted(NEXT_CONJUNCTS) + ) if __name__ == "__main__": diff --git a/.github/workflows/cursor-review.yml b/.github/workflows/cursor-review.yml index bcb945e1..93a2522f 100644 --- a/.github/workflows/cursor-review.yml +++ b/.github/workflows/cursor-review.yml @@ -443,8 +443,11 @@ on: red (the leg itself, and `Panel integrity` with it), so a caller that chains jobs off it — the cursor-approve axes above all — must guard them with `!cancelled()` or GitHub's default `needs:` rule skips them - and the tolerance buys nothing. See docs/callers/cursor-approve.md - ("A red panel cell must not skip the axes"). + and the tolerance buys nothing. `!cancelled()` also drops the implicit + success requirement on EVERY other `needs:` entry, so restate those + explicitly (the axes keep `needs.approve-start.result == 'success'`). + See docs/callers/cursor-approve.md ("A red panel cell must not skip + the axes"). type: number required: false default: 0 diff --git a/.github/workflows/test-cursor-review-scripts.yml b/.github/workflows/test-cursor-review-scripts.yml index 414b6ae3..41c22e73 100644 --- a/.github/workflows/test-cursor-review-scripts.yml +++ b/.github/workflows/test-cursor-review-scripts.yml @@ -19,16 +19,15 @@ name: Test cursor-review scripts # into the table-driven harness at # .github/workflow-pins/tests/test_inputs_docs_drift.py, which reads BOTH # docs/callers/cursor-review.md and .github/cursor-review/README.md. Both paths -# are in test-workflow-pins.yml's filters, so docs/callers/cursor-review.md is -# deliberately NOT listed below — no suite this workflow runs reads it, and a -# docs-only PR that deletes the `blocking` row (the #31 scenario) still fires -# the alarm, over there. +# are in test-workflow-pins.yml's filters, and a docs-only PR that deletes the +# `blocking` row (the #31 scenario) still fires the alarm, over there. # -# docs/callers/cursor-approve.md IS listed, for the opposite reason: a suite -# here does read it. test_caller_doc_pattern.py pins the `if:` guards on the -# caller snippet, because a copied caller is only as good as the snippet and -# dropping `!cancelled()` from it silently withholds every approval (see that -# file's docstring). +# docs/callers/cursor-approve.md and docs/callers/cursor-review.md ARE listed +# below anyway, because a suite here reads them too: test_caller_doc_pattern.py +# pins the `if:` guards on the cursor-approve caller snippet and on +# cursor-review's `next:` approve_gate example. A copied caller is only as good +# as the snippet, and dropping `!cancelled()` from it silently withholds every +# approval (see that file's docstring). on: pull_request: @@ -42,11 +41,11 @@ on: - '.github/workflows/cursor-approve.yml' - '.github/workflows/cursor-axis-base.yml' - '.github/workflows/axis-*.yml' - # test_caller_doc_pattern.py reads the caller snippet out of this page and - # pins its `if:` guards. Unlike docs/callers/cursor-review.md (see the - # note above), a suite HERE parses it, and the regression it guards is a + # test_caller_doc_pattern.py reads the caller snippets out of these + # pages and pins their `if:` guards; the regression it guards is a # docs-only edit — dropping `!cancelled()` from a snippet a caller copies. - 'docs/callers/cursor-approve.md' + - 'docs/callers/cursor-review.md' - '.github/workflows/test-cursor-review-scripts.yml' push: branches: [main] @@ -60,11 +59,11 @@ on: - '.github/workflows/cursor-approve.yml' - '.github/workflows/cursor-axis-base.yml' - '.github/workflows/axis-*.yml' - # test_caller_doc_pattern.py reads the caller snippet out of this page and - # pins its `if:` guards. Unlike docs/callers/cursor-review.md (see the - # note above), a suite HERE parses it, and the regression it guards is a + # test_caller_doc_pattern.py reads the caller snippets out of these + # pages and pins their `if:` guards; the regression it guards is a # docs-only edit — dropping `!cancelled()` from a snippet a caller copies. - 'docs/callers/cursor-approve.md' + - 'docs/callers/cursor-review.md' - '.github/workflows/test-cursor-review-scripts.yml' permissions: diff --git a/docs/callers/cursor-approve.md b/docs/callers/cursor-approve.md index 4706bef9..7828e87f 100644 --- a/docs/callers/cursor-approve.md +++ b/docs/callers/cursor-approve.md @@ -14,9 +14,12 @@ the context axes (business, design, completeness) are not available yet. resolving any thread), and withdraws the approving identity's own earlier 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 - then skipped. With it, this workflow's decide phase is the only approver. + start phase withdraws it — and stays standing if the cursor-review run is + cancelled after approving, or if its `approve_gate` comes out `untrusted`, + because the start phase and the axes are then skipped. (A run that merely + went red on an errored panel cell does NOT skip them while the gate reads + `pass` or `capped`; see "A red panel cell must not skip the axes".) 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 — a backstop: with `defer_approval: true` there is none from this round, but a caller that does not set it has one standing @@ -326,16 +329,30 @@ reports every axis as ⚠️ no result and withholds. A caller that sets gets the tolerance it configured — one errored cell out of six withholds every round, and nothing on the card says why. -This does not widen what may be approved. `approve_gate` stays the only -authority on whether a round may be decided, and reading it off a red -cursor-review job cannot approve a round the gate itself rejected: it is already -`untrusted` when the judge was degraded, when more cells errored than the caller -tolerates, when the review did not land as threads or when the head moved, and -it falls back to `untrusted` whenever an upstream decision job did not succeed — -which is every Panel integrity failure that is not simply a short panel. The -axes keep an explicit `needs.approve-start.result == 'success'` rather than a -blanket `!cancelled()` so the invariant above is unchanged: a start phase that -failed to withdraw cursor-review's standing approval still skips them. +`approve_gate` stays the only authority on whether a round may be decided, and +reading it off a red cursor-review job cannot approve a round the gate itself +rejected: it is already `untrusted` when the judge was degraded, when more cells +errored than the caller tolerates, when the review did not land as threads or +when the head moved, and it falls back to `untrusted` whenever an upstream +decision job did not succeed — which is every Panel integrity failure that is +not simply a short panel. The axes keep an explicit +`needs.approve-start.result == 'success'` rather than a blanket `!cancelled()` +so the invariant above is unchanged: a start phase that failed to withdraw +cursor-review's standing approval still skips them. + +What the guard does give up is an *incidental* backstop. The gate counts each +cell by the `status` that cell's own findings artifact reports, not by its +leg's conclusion — that is how a tolerated errored cell still passes — and +cursor-review documents that status as an availability signal, not an +attestation: a prompt-injected cell can write a clean `ok` record, and because +artifact names are run-global it can claim another cell's name first, so that +cell's real upload fails and its leg goes red while consolidate reads the +forgery. A bare `needs:` used to skip the axes on that red leg. With +`!cancelled()` the round goes on to the axes, which still review the change +independently, and decide still withholds on any red axis (or more yellow +than `max_yellow_axes`). Treat the panel count +as tamper-evident only in the rollup (the red leg stays visible), not in the +gate. ## Inputs diff --git a/docs/callers/cursor-review.md b/docs/callers/cursor-review.md index 6148a5d7..55a68e35 100644 --- a/docs/callers/cursor-review.md +++ b/docs/callers/cursor-review.md @@ -870,7 +870,10 @@ jobs: secrets: { CURSOR_API_KEY: "${{ secrets.CURSOR_API_KEY }}" } next: needs: cursor-review - if: needs.cursor-review.outputs.approve_gate == 'pass' + # `!cancelled()`: an errored panel cell turns the called job red even when + # `approve_max_failed_reviewers` tolerates it, and a bare `if:` is then + # skipped by GitHub's default `needs:` rule. + if: ${{ !cancelled() && needs.cursor-review.outputs.approve_gate == 'pass' }} ``` | Value | Meaning |