Skip to content
Merged
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
23 changes: 15 additions & 8 deletions .github/cursor-approve/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,20 +36,27 @@ Each verdict carries two strings, with different jobs and different audiences:

| Field | Cap | Where it goes |
|---|---|---|
| `headline` | 100 chars, **required** | the PR card — ONE line, the reason for the verdict |
| `summary` | 1200 chars | the run's job summary, behind the card's "workflow run" link |
| `headline` | 240 chars, **required** | the PR card's Why cell — ONE sentence, the reason for the verdict, shown whole |
| `summary` | 1200 chars | a collapsed "full reasoning" block under the card's table, and the run's job summary |

The split exists because one field could not do both. The card used to show the
first sentence of `summary`, and `summary` is where a model writes its process
("Checked the only changed file…", "I read root AGENTS.md and CLAUDE.md…") — so
the card said what the axis *did* and never why it ruled as it did, which is
unreadable on a yellow. `headline` must state what decided the verdict, and a
missing one makes the axis untrusted. An over-long one is clamped to the cap at
a word boundary with "…", not rejected: the model's length is not
deterministic, and rejecting turned a sound verdict's axis job red on length
alone. The opening words carry the reason, so the clamp keeps it — falling
back to a hard cut when the last fitting space is in the first half, and
rejecting one that leaves nothing but punctuation before the "…".
missing one makes the axis untrusted. An over-long one is clamped, not
rejected: the model's length is not deterministic, and rejecting turned a sound
verdict's axis job red on length alone. The clamp keeps every whole sentence
that fits, with no "…" (a `.`, `!` or `?` before whitespace ends a sentence,
after any closing quote or bracket, except after "e.g." and similar
abbreviations, an initialism like "U.S.", a one-character initial or list
number, or an ellipsis), because the card exists to show a reason and a
sentence stopped mid-thought does not (BE-20249: at the old 100-character cap
it cut ordinary one-sentence reasons). A sentence cut that keeps fewer than
four words ("OK.") is not taken. Otherwise, as when the first sentence alone
is longer than the cap, the cut is at a word boundary with "…" — falling back
to a hard cut when the last fitting space is in the first half. A headline with
no word character at all, at any length, is rejected.

Placeholders — `{{pr_number}}`, `{{repo}}`, `{{head_sha}}`,
`{{merge_base_sha}}`, `{{base_ref}}`, `{{context_file}}` — are filled by
Expand Down
71 changes: 65 additions & 6 deletions .github/cursor-approve/aggregate.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
Five reviewers each judge one axis of a PR (business, design, correctness,
completeness, conformance) and answer with one JSON object:
``{"verdict": "red"|"yellow"|"green"|"n/a", "confidence": 0..1,
"headline": "<=100 chars", "summary": "..."}``.
"headline": "<=240 chars", "summary": "..."}``.
Three subcommands, all pure — nothing here writes to GitHub:

``render``
Expand Down Expand Up @@ -67,7 +67,23 @@
# does not block). See `decide` for the one case where it still withholds.
VERDICTS = ("red", "yellow", "green", "n/a")
NA = "n/a"
HEADLINE_MAX = 100
# The card's Why cell shows the headline whole, so the cap is sized for one
# full sentence (the prompt asks for about 120 characters). At 100 it cut the
# models' ordinary 110-140 character reasons mid-sentence (BE-20249).
HEADLINE_MAX = 240
# A `.`/`!`/`?` before whitespace ends a sentence — after any closing quotes or
# brackets, so `returns "ok." Then` ends at the quote — unless the word it
# closes is an abbreviation, an initialism (`U.S.`, `a.k.a.`), a one-character
# initial or list number (`J.`, `2.`), or an ellipsis: "e.g. the retry" is one
# thought, and cutting there is the mid-sentence cut the clamp exists to avoid.
# `etc.` does end a sentence when a capital follows it.
_SENTENCE_END_RE = re.compile(r"[.!?][\"')\]}\u201d\u2019]*(?=\s)")
_ABBREVIATIONS = frozenset(("e.g.", "i.e.", "vs.", "etc.", "cf.", "approx.", "incl.", "esp.", "resp.", "no.",
"dr.", "mr.", "mrs.", "ms.", "st.", "fig."))
_OPENERS = "([{\"'\u201c\u2018"
# A sentence cut that keeps fewer words than this ("OK.", "Red.") keeps no
# reason; the clamp word-cuts the long sentence behind it instead.
_MIN_SENTENCE_CUT_WORDS = 4
MAX_YELLOW_LIMIT = 3
SUMMARY_LIMIT = 1200
# An axis output is one small JSON object; the cap is what decide will read of
Expand Down Expand Up @@ -368,16 +384,59 @@ def validate_output(data):
return verdict, confidence, summary, headline


def _last_sentence_end(text: str, limit: int) -> int:
"""The index just past the last sentence that ends within `text[:limit]`,
or -1 when none does. A cut that would keep no word at all ("-. …") is
not a sentence end."""
best = -1
for match in _SENTENCE_END_RE.finditer(text):
end = match.end()
if end > limit:
break
if _ends_sentence(text, match.start()) and re.search(r"\w", text[:end]):
best = end
return best


def _ends_sentence(text: str, mark: int) -> bool:
"""Whether the `.`/`!`/`?` at `text[mark]` closes a sentence rather than an
abbreviation, initialism, initial, list number or ellipsis."""
if text[mark] != ".":
return True
token = text[:mark + 1].rsplit(None, 1)[-1].lstrip(_OPENERS).lower()
if token.endswith(".."):
return False
if token == "etc.":
rest = text[mark + 1:].lstrip("\"')]}\u201d\u2019").lstrip()
return rest[:1].isupper()
# An initialism is all one-letter parts ("u.s", "a.k.a"); "store.go" is a
# file name, and its closing dot can end a sentence.
initialism = all(len(part) <= 1 for part in token[:-1].split("."))
return token not in _ABBREVIATIONS and not initialism


def clamp_headline(headline: str) -> str:
"""`headline` cut to HEADLINE_MAX characters, at a word boundary, with "…".
"""`headline` cut to HEADLINE_MAX characters.

Falls back to a hard cut when the last space that fits sits in the first
A headline within the cap is returned whole. Past it, the cut keeps every
complete sentence that fits, with no "…": the card shows a whole sentence
rather than one stopped mid-thought (BE-20249). Only when the FIRST
sentence alone runs past the cap is it cut at a word boundary, with "…" —
falling back to a hard cut when the last space that fits sits in the first
half (one long token, or "Fix: <long path>"), so the clamp never throws
away most of the reason. Raises ValueError when nothing but separators
survives: a bare "…" is the reason-free row the headline exists to prevent.
away most of the reason. Raises ValueError when the headline holds no word
at all, at any length, or nothing but separators survives the cut: a bare
"…" is the reason-free row the headline exists to prevent. The sentence cut is taken only when it keeps at least
_MIN_SENTENCE_CUT_WORDS words: "OK. <one long sentence>" must not clamp to
a reason-free "OK.", so a token-length lead falls through to the word cut.
"""
if not re.search(r"\w", headline):
raise ValueError("headline holds no reason to keep")
if len(headline) <= HEADLINE_MAX:
Comment thread
mattmillerai marked this conversation as resolved.
Resolved
return headline
sentence_end = _last_sentence_end(headline, HEADLINE_MAX)
if sentence_end > 0 and len(re.findall(r"\w+", headline[:sentence_end])) >= _MIN_SENTENCE_CUT_WORDS:
return headline[:sentence_end]
hard = headline[:HEADLINE_MAX - 1]
space = headline.rfind(" ", 0, HEADLINE_MAX)
candidates = [headline[:space], hard] if space >= HEADLINE_MAX // 2 else [hard]
Expand Down
99 changes: 79 additions & 20 deletions .github/cursor-approve/card.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,12 @@
``decide`` (after auto-approve.py ``approve-external``)
The per-axis verdicts from ``aggregate.py decide``, the overall result and
the rule applied — or "Superseded by a newer commit" when the head moved.
Each axis shows its `headline` only — ONE line naming what decided the
verdict. The same phase writes ``render_job_summary`` to
``GITHUB_STEP_SUMMARY``: the full summaries and confidences, which is what
the card's "workflow run" link now leads to. The card is the glance; the
job summary is the record.
Each axis's row shows its whole `headline` — the sentence naming what
decided the verdict — and under the result sits one collapsed
``<details>`` block per axis with its full `summary` and confidence
(BE-20249), so the reasoning is one click away on the PR itself. The same
phase writes ``render_job_summary`` to ``GITHUB_STEP_SUMMARY``, the run's
own record of the same detail.

cursor-review's ``auto-approve.py decide`` writes it too, through
``render_round`` and ``upsert``, on every round it decides for an author
Expand Down Expand Up @@ -66,8 +67,12 @@

CARD_MARKER = "<!-- cursor-approve-card -->"
SUMMARY_LIMIT = 200
# The job summary behind the run link is the detail surface, so an axis
# summary is not cut to one table cell there.
# The Why cell holds a whole headline, so it is exactly aggregate.py's
# HEADLINE_MAX (a test pins the two equal): any lower and the cell would cut a
# headline aggregate.py had already let through whole.
WHY_LIMIT = 240
# The detail surfaces — the collapsed per-axis blocks on the card and the job
# summary — carry an axis summary whole rather than cut to one table cell.
SUMMARY_DETAIL_LIMIT = 2000
AXES = ("business", "design", "correctness", "completeness", "conformance")
VERDICT_ICONS = {"green": "🟢 green", "yellow": "🟡 yellow", "red": "🔴 red",
Expand Down Expand Up @@ -302,6 +307,56 @@ def sanitize(text, limit: int = SUMMARY_LIMIT) -> str:
return _ESCAPE_RE.sub(r"\\\1", text)


def why_text(entry: dict) -> str:
"""One axis's Why cell: its whole headline, sanitised.

aggregate.py already clamped the headline to whole sentences within
HEADLINE_MAX; the same clamp runs again here because the card is the last
stop before the PR and must not depend on its input being well-formed. A
missing headline, or one the clamp rejects as reason-free (aggregate.py
rejects both, so this is defence only), falls back to the summary's first
sentence rather than an empty cell.
"""
headline = entry.get("headline")
candidates = [headline] if isinstance(headline, str) else []
candidates.append(first_sentence(entry.get("summary")))
for text in candidates:
text = " ".join(str(text or "").split())
try:
text = _clamp_headline(text) if text else ""
except ValueError:
text = ""
if text:
return sanitize(text, WHY_LIMIT)
return ""


def reasoning_blocks(axes: list, detail: dict) -> list:
"""Card lines: one collapsed ``<details>`` block per axis that reported a
summary — the full reasoning behind its row, one click away on the PR
itself rather than behind the run link (BE-20249).

They sit below the table and the result, so the contract markers and the
`| Axis | Verdict | Why |` rows agents parse are exactly as before. The
summary goes through `sanitize` like every model string on the card, which
folds it to one line and backslash-escapes every `|` and `<`: no line here
can open a table row, an HTML comment or a forged marker. The blank lines
around it are what make GitHub render it as markdown inside the block.
"""
lines = []
for axis in axes:
entry = detail.get(axis)
if not isinstance(entry, dict) or entry.get("verdict") not in VERDICT_ICONS:
continue
summary = sanitize(entry.get("summary"), SUMMARY_DETAIL_LIMIT)
Comment thread
mattmillerai marked this conversation as resolved.
Resolved
if not summary:
continue
confidence = _confidence(entry.get("confidence"))
label = f"{axis} — full reasoning" + (f" (confidence {confidence})" if confidence else "")
lines += ["", "<details>", f"<summary>{label}</summary>", "", summary, "", "</details>"]
Comment thread
mattmillerai marked this conversation as resolved.
Resolved
return lines


def parse_axes(value: str) -> list:
axes = []
for name in (value or "").split(","):
Expand Down Expand Up @@ -389,7 +444,9 @@ def render_job_summary(round_no, max_rounds, sha: str, axes: list, decision, out
icon = VERDICT_ICONS.get(verdict, NO_RESULT)
confidence = _confidence(entry.get("confidence"))
lines += ["", f"#### {axis} — {icon}" + (f" (confidence {confidence})" if confidence else "")]
headline = sanitize(entry.get("headline"))
# The card's Why cell, word for word: the same clamp and fallback, so
# the two surfaces never show a different headline for one axis.
headline = why_text(entry)
if headline:
lines.append(f"**{headline}**")
summary = sanitize(entry.get("summary"), SUMMARY_DETAIL_LIMIT)
Expand All @@ -412,34 +469,36 @@ def render_decide(round_no, max_rounds, sha: str, axes: list, decision, outcome:
return "\n".join(lines) + "\n"
detail = decision.get("axes") if isinstance(decision, dict) else None
detail = detail if isinstance(detail, dict) else {}
# Three columns, and the third is the axis's `headline` — ONE line stating
# what decided the verdict. It used to be the first sentence of `summary`,
# which is where the models put their process log ("Checked the only
# changed file...", "I read root AGENTS.md and CLAUDE.md..."), so the card
# showed what the axis DID and never why it ruled as it did. The full
# summary and the confidence now live in the run's job summary, one click
# behind the link below — this card is the glance, not the record.
# Three columns, and the third is the axis's `headline` — the sentence
# stating what decided the verdict, shown whole (BE-20249: at 100
# characters it was cut mid-sentence). It used to be the first sentence of
# `summary`, which is where the models put their process log ("Checked the
# only changed file...", "I read root AGENTS.md and CLAUDE.md..."), so the
# card showed what the axis DID and never why it ruled as it did. The full
# summary and the confidence sit in the collapsed blocks under the result.
lines += ["| Axis | Verdict | Why |", "|---|---|---|"]
for axis in axes:
entry = detail.get(axis)
verdict = entry.get("verdict") if isinstance(entry, dict) else None
if verdict not in VERDICT_ICONS:
lines.append(f"| {axis} | {NO_RESULT} | |")
continue
why = sanitize(entry.get("headline") or first_sentence(entry.get("summary")))
lines.append(f"| {axis} | {VERDICT_ICONS[verdict]} | {why} |")
lines.append(f"| {axis} | {VERDICT_ICONS[verdict]} | {why_text(entry)} |")
lines.append("")
if outcome == OUTCOME_APPROVED:
lines.append("**Result: ✅ Approved.**")
else:
lines.append("**Result: ❌ Not approved.**")
lines += [f"- {r}" for r in decide_reasons(outcome, decision)]
lines += ["", f"**Next step:** {next_text}"]
lines += reasoning_blocks(axes, detail)
limit = _int_or_q(max_yellow)
# The run link sits on the reviewed-commit line, as on every other card;
# it used to close the rule line instead, leaving this line's "workflow
# run" as unlinked text right under a linked one.
lines += ["", f"_Rule: no red, at most {limit} yellow; every axis must report "
f"(⚪ n/a counts as reporting and does not block, but all-n/a withholds). "
f"{_run_link(run_url)}_",
"", _reviewed_line(sha, "")]
f"(⚪ n/a counts as reporting and does not block, but all-n/a withholds)._",
"", _reviewed_line(sha, run_url)]
return "\n".join(lines) + "\n"


Expand Down
13 changes: 7 additions & 6 deletions .github/cursor-approve/prompt-common.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,10 +71,11 @@ the merge base.

- `verdict`: one of `red`, `yellow`, `green`, `n/a`.
- `confidence`: a number from 0 to 1 — how sure you are of the verdict.
- `headline`: **the one line a human reads.** Plain text, at most 100
characters, no markdown. State WHAT DECIDED THE VERDICT, not what you did
to decide it. It is the only part of your answer shown on the PR; the
`summary` sits behind a link that most readers will not open.
- `headline`: **the one line a human reads.** Plain text, ONE sentence,
no markdown — aim for about 120 characters, never more than 240. State
WHAT DECIDED THE VERDICT, not what you did to decide it. It is the line
the PR card's table shows for your axis; the `summary` sits in a
collapsed block under it that most readers will not open.

A reader who sees only this line must understand why the verdict is what
it is. Write it so that is true:
Expand All @@ -91,7 +92,7 @@ the merge base.
finding.
- `summary`: plain text, at most 1200 characters, no markdown. The detail
behind the headline — what you checked, where you looked, and what decided
the verdict. For `red` or `yellow`, name the files and the concern. This
goes to the run's job summary, not the PR comment.
the verdict. For `red` or `yellow`, name the files and the concern. It is
shown collapsed under the card's table and in the run's job summary.

## Your axis
Loading
Loading