fix(742): inherit an h10 verdict only from an allow-listed reviewer #850

Merged
timothy merged 16 commits from fix/742-verdict-allowlist into main 2026-08-27 04:52:03 +02:00
10 changed files with 987 additions and 84 deletions
+229 -29
View File
@@ -232,6 +232,41 @@ jobs:
# row, so the post-write check stayed silent and the rejection went green a second time.
# Found by cold review. Refusing here can only ever withhold an exemption, never grant one.
REPAIR_DESC="Human verdict raced this exemption write — re-post the verdict"
# WHOSE verdict may be INHERITED (ersatztv#742). Space-separated logins, compared exactly.
#
# The test this replaces was "the status has a non-null `.creator.login`", which only proves
# it was POSTed with SOME user credential. This repo stores credentials for accounts that are
# not reviewers: `RENOVATE_TOKEN` is a `write:repository` PAT of the `renovate` bot, it
# CANNOT be scoped down the way `#697` scoped the registry credential (Renovate genuinely
# needs repo write to push branches and open PRs), and secrets are a per-repo STORE rather
# than a per-workflow grant — so a status POSTed with it reads back `creator: renovate`,
# non-null, and would be inherited as a human verdict.
#
# CONDITIONAL VOICE ON PURPOSE. The asymmetry it rests on IS measured (a user credential
# posts with a real creator, an Actions job with `creator: null`), but it has not been
# measured FOR THIS TOKEN: every status row on all six Renovate-authored PR heads in this
# repo carries `creator: null` — `renovate` has never posted a commit status here. So the
# route is a sound inference from a measurement, not an observed event, and an earlier
# draft's past tense ("was inherited") described something nobody saw.
#
# Membership keeps the POSITIVE direction the description test already uses: short-circuit
# only on something identified as a REVIEWER's verdict; every other creator, recognised or
# not, is RE-DERIVED, exactly as an Actions-token status already is.
#
# A LITERAL in this base-resolved definition, deliberately — not a repo `vars:` entry and not
# a secret. Those are settable without a PR, i.e. without this gate; editing this file takes
# a PR to `main`, and `.gitea/` is on the PROTECTED path list below, so the change cannot
# ride a docs-only exemption either.
#
# NO GLOB METACHARACTERS: the membership loop below word-splits this value, so pathname
# expansion would apply to an entry containing `*`, `?` or `[`. Machine-checked by
# `test_pr_changed_files.py::test_the_H10_REVIEWERS_list_is_glob_free_and_non_empty`.
#
# What this is NOT: authentication. An allow-listed collaborator's own write-scoped token can
# still POST a verdict they did not form, and branch protection binds the CONTEXT name, not
# its issuer. It removes the accounts that are not reviewers at all — provenance, not
# identity proof (`ci.exemption-provenance`).
H10_REVIEWERS="timothy"
# Accounts whose PRs may merge without a human verdict. Renovate only — keep this list
# minimal and explicit; every entry is an account that can land code unreviewed.
BOTS="renovate"
@@ -364,7 +399,8 @@ jobs:
# and the POST at the end of this job are not atomic, so a human verdict posted in between is
# still overwritten. The re-read immediately before the POST narrows that window; it does not
# close it. Tracked as ersatztv#706 rather than claimed as solved.
# Reads the CONTEXT row for $SHA and sets ex_state / ex_creator / ex_desc / ex_human.
# Reads the CONTEXT row for $SHA and sets ex_state / ex_creator / ex_desc / ex_repair and the
# two provenance flags ex_attributable / ex_human (see the flag split below, ersatztv#742).
# Factored into a function because it is now called TWICE — once here, and once immediately
# before the POST (see below). An unreadable/unparseable response must NOT be read as "no
# verdict exists": the job dies WITHOUT posting, so a transient API error can never overwrite
@@ -379,7 +415,7 @@ jobs:
# (not per context) and pages at 50, so a head with a few CI reruns can push an earlier verdict
# off the first page.
read_existing_verdict() {
local json row
local json row rv
json=$(gh "$BASE_URL/repos/$REPO/commits/$SHA/status?limit=100") || json=""
# `.statuses` IS `null`, NOT `[]`, ON A HEAD WITH NO STATUSES YET — the same nil-slice
# serialization as the timeline terminator, found by cold review of the fix for that one
@@ -480,17 +516,36 @@ jobs:
# An ABSENT base is deliberately NOT treated as a mismatch: verdicts predating #632 carry
# no `(base: …)`, and re-deriving over one would un-approve a genuinely reviewed head. Only
# a base that is PRESENT and DIFFERENT is rejected, which is exactly the escape above.
# TWO FLAGS, BECAUSE THIS FUNCTION ANSWERS TWO DIFFERENT QUESTIONS (ersatztv#742).
# It is called TWICE, and the callers want opposite widths:
#
# ex_attributable — "is this an attributable verdict for THIS base, whoever wrote it?"
# Used by the LAST-MOMENT RE-READ, which asks "did a reviewer post a
# verdict while we were classifying". Narrowing THAT does not make it
# stricter, it makes the job stop abstaining and post its exemption
# success straight over the row.
# ex_human — ex_attributable AND the creator is in `$H10_REVIEWERS`. Used by the
# INHERITANCE short-circuit, where narrowing is safe because an
# unrecognised account falls through to re-derivation.
#
# GATING ONE FLAG NARROWS BOTH SITES, which is the mistake this split exists to prevent,
# and the post-write repair does NOT cover it: that repair is skipped entirely whenever
# the high-water mark could not be established (`max_id_before=-1`). Pinned by
# `test_the_MID_RUN_abstain_still_fires_for_a_NON_allowlisted_creator`.
ex_human=no
ex_attributable=no
ex_repair=no
case "$ex_desc" in
"$REPAIR_DESC"*) ex_repair=yes ;;
esac
case "$ex_desc" in
"Review-verdict:"*)
if [ -n "$ex_creator" ]; then ex_human=yes; fi
# ATTRIBUTABLE, not yet "inheritable" — the allow-list is applied below, after the
# base check, so the two flags cannot diverge on the base.
if [ -n "$ex_creator" ]; then ex_attributable=yes; fi
;;
esac
if [ "$ex_human" = yes ]; then
if [ "$ex_attributable" = yes ]; then
# COMPARE, NEVER PARSE. Two earlier attempts both extracted the base out of the
# description and both were defeated, the second in a way that looked like a fix for the
# first:
@@ -522,15 +577,32 @@ jobs:
esac
fi
if [ "$ex_base_ok" != yes ]; then
ex_human=no
echo "${CONTEXT} on ${SHA:0:7} is a human verdict, but its recorded base does not match this PR's base '${BASE_REF}' (description: ${ex_desc}) — the reviewed diff is not this PR's diff, so it is NOT treated as a verdict for this base."
ex_attributable=no
echo "${CONTEXT} on ${SHA:0:7} is an attributable verdict, but its recorded base does not match this PR's base '${BASE_REF}' (description: ${ex_desc}) — the reviewed diff is not this PR's diff, so it is NOT treated as a verdict for this base."
fi
fi
fi
# DERIVED LAST, so the base check above governs both flags and cannot be bypassed by
# membership.
#
# THE INVARIANT IS THE QUOTING, NOT THE BRACKET FORM. The tempting rule — "never
# `[[ == ]]`, it makes the RHS a PATTERN" — is FALSE as usually written: probed on bash
# 5.3, `[[ "$rv" == "$ex_creator" ]]` with a QUOTED right-hand side is a literal
# comparison and does NOT match `ex_creator='*'`. Only an UNQUOTED RHS globs. So the rule
# is: keep both sides quoted. POSIX `[ = ]` is used because it cannot glob at all.
#
# Never `grep -xF` either: it would read a newline-bearing `$ex_creator` as SEVERAL
# patterns, any one of which could match an allow-listed line.
if [ "$ex_attributable" = yes ]; then
for rv in $H10_REVIEWERS; do
if [ "$rv" = "$ex_creator" ]; then ex_human=yes; break; fi
done
fi
}
# --- The retarget fence (ersatztv#706 race 1) ----------------------------------------
# THE PROBLEM THIS SOLVES. Two `pull_request_target` runs for one PR overlap, and the OLDER
# THE PROBLEM THIS NARROWS — not solves, and the difference is #849's. Two
# `pull_request_target` runs for one PR overlap, and the OLDER
# one can finish LAST — so a run that classified against a base the PR no longer targets can
# post its stale answer over a fresher run's correct one, permanently. Measured on this
# instance rather than assumed: probe PR #722 run 7520 (`opened`) ran to completion 20s AFTER
@@ -663,19 +735,100 @@ jobs:
# we do not recognise, is RE-DERIVED. Written the other way round ("skip if it looks
# machine-written") an unrecognised shape would be trusted — the fail-open this issue is about.
#
# What this does NOT claim: the test asks "was this POSTed by a user credential", NOT "by a
# reviewer". `ETV_STATUS_AUTH`'s registry credential can no longer POST a status at all (#697,
# fixed by scoping it off `write:repository` — see `ci.actions-credential-scoping`), but any
# OTHER user credential — a collaborator's own token, `RENOVATE_TOKEN` — can still POST a
# success with a non-null creator AND an attacker-chosen `Review-verdict:` description, which
# this guard then preserves. That is provenance, not authentication.
# SINCE ersatztv#742 the creator must additionally be in `$H10_REVIEWERS`, not merely
# non-null. "Non-null" was satisfied by ANY account's credential, `RENOVATE_TOKEN` included —
# a `write:repository` PAT that cannot be scoped down the way `#697` scoped the registry
# credential, and reachable from any workflow because secrets are a per-repo store.
#
# What this STILL does not claim: the test asks "was this POSTed by an account we accept
# verdicts from", NOT "by someone who actually reviewed it". `ETV_STATUS_AUTH`'s registry
# credential can no longer POST a status at all (#697, fixed by scoping it off
# `write:repository` — see `ci.actions-credential-scoping`), and `RENOVATE_TOKEN` is now
# re-derived rather than inherited; but an ALLOW-LISTED collaborator's own token can still
# POST a success with an attacker-chosen `Review-verdict:` description, which this guard then
# preserves. That is provenance, not authentication — branch protection binds the context
# NAME, not its issuer, and Gitea offers no way to restrict who may post a context.
#
# THE ALLOW-LIST APPLIES TO `success` ONLY — the two states are not symmetric, and treating
# them alike is a FAIL-OPEN (ersatztv#742). Trace the symmetric version on an off-list
# `failure`: the head carries
# `h10=failure` from `alice`, a real reviewer left off the literal. `ex_human=no`, so the
# short-circuit declines; the PR is docs-only, so the classifier grants an exemption; the
# re-read triple is unchanged, so the mid-run abstain declines; alice's row predates the
# high-water mark, so the post-write repair cannot see it. The job posts `success` over an
# explicit human rejection — reached by the very misconfiguration the allow-list's own
# diagnostic is about.
#
# Splitting by state costs NOTHING that #742 bought. Inheriting a `failure` cannot green
# anything: the worst an off-list or forged `failure` achieves is a STALL, and a stall is
# clearable in one command by any human — `post-review-verdict.sh` POSTs unconditionally,
# with no read-modify-write, so there is nothing to be locked out of. Inheriting a `success`
# is the durable forgery #742 exists to stop. So `success` requires membership and `failure`
# requires only attributability.
#
# "ONLY ATTRIBUTABILITY" IS STILL A REQUIREMENT, not a synonym for "any failure": a `failure`
# whose description is not `Review-verdict:`-shaped, or whose creator is null, or which
# records a DIFFERENT base, is re-derived like any other unattributable row. Widening this to
# a bare `[ "$ex_state" = failure ]` would be safe by the argument above, and is deliberately
# NOT done — it would quietly opt `failure` out of the base binding (`ci.exemption-provenance`
# input 1), which exists because a verdict earned against another base is not a verdict for
# this diff. None of the excluded shapes is producible by `post-review-verdict.sh`.
read_existing_verdict
if [ "$ex_human" = yes ] && { [ "$ex_state" = "success" ] || [ "$ex_state" = "failure" ]; }; then
echo "${CONTEXT} is already '${ex_state}' on ${SHA:0:7}, written by '${ex_creator}' as a human verdict — leaving it alone."
if [ "$ex_human" = yes ] && [ "$ex_state" = "success" ]; then
echo "${CONTEXT} is already 'success' on ${SHA:0:7}, written by '${ex_creator}', an allow-listed reviewer — leaving it alone."
exit 0
fi
if [ "$ex_attributable" = yes ] && [ "$ex_state" = "failure" ]; then
echo "${CONTEXT} is already 'failure' on ${SHA:0:7}, written by '${ex_creator}' — an ATTRIBUTABLE rejection for this base is left alone whichever account recorded it, because honouring it can only ever withhold an exemption, never grant one."
exit 0
fi
# SNAPSHOT THE ROW WE DECIDED AGAINST (ersatztv#742). The last-moment re-read below asks
# "did a verdict land WHILE WE WERE CLASSIFYING", and before #742 it got that for free: the
# two reads computed an IDENTICAL predicate, so anything that fired at the second and not
# the first must have arrived in between. Splitting `ex_human` from `ex_attributable` broke
# that — a pre-existing row this job declined to INHERIT is still attributable, so the
# re-read would abstain on the very row the classification just decided to overwrite, leave
# the forged success standing untouched, and post nothing. Ever. (Measured, not reasoned:
# the inheritance tests went red on exactly that.)
#
# So "changed" is made explicit instead of implied. Compare the whole row we saw, not just
# its presence: a REPLACEMENT (same context, new state/creator/description) is as much a
# mid-run event as an arrival, and the combined endpoint gives one row per context, so a
# newer POST replaces rather than adds.
#
# MEASURED on this instance 2026-08-26, not assumed: two POSTs of context `probe742/combined-newest` to one sha, `pending`
# then `success`. `/commits/{sha}/status` returned ONE row for that context, the newest
# (`success`); `/statuses/{sha}` returned BOTH. Reproduce with two POSTs to
# `/repos/{o}/{r}/statuses/{sha}` and a read of each endpoint. `main` depended on none of
# this — presence alone sufficed there — so the claim became load-bearing with the
# changed-row comparison, and is measured rather than inherited.
#
# ONE ORDERING CHANGES BEHAVIOUR AND IT IS AN IMPROVEMENT, recorded so it is not read later
# as an accident: an attributable row in a state OTHER than `success`/`failure` — a
# `pending`- or `error`-state row whose description happens to start `Review-verdict:`. On
# `main` neither short-circuit fired for it (they test the state) and the old unconditional
# abstain then fired at the re-read, so the job posted NOTHING, on that run and on every
# later one: a permanent stall with no diagnostic. The changed-row comparison removes it —
# the triple is unchanged, so the job falls through and posts.
pre_state=$ex_state
pre_creator=$ex_creator
pre_desc=$ex_desc
if [ -n "$ex_state" ]; then
echo "${CONTEXT} is '${ex_state}' on ${SHA:0:7} but is NOT an attributable human verdict (creator='${ex_creator:-null}', description='${ex_desc}') — re-deriving it from the PR's current state rather than inheriting it."
# STATE-NEUTRAL WORDING. Control also reaches here for an ALLOW-LISTED creator whose row is
# in some state other than `success`/`failure`, so this must not assert the row is
# unattributable.
#
# THE ALLOW-LIST IS NAMED HERE ON PURPOSE. If a reviewer is ever added to the repo and
# forgotten from `H10_REVIEWERS`, their verdicts are re-derived rather than honoured, and
# this line — creator, allow-list and description together — is what says so. A separate
# `::warning::` annotation was tried and WITHDRAWN: it duplicated all three values from
# this line, its only delta was a severity whose rendering could not be probed, and it
# produced three defects across three review rounds (a message that read "from 'timothy',
# which is NOT in H10_REVIEWERS ('timothy')", an unescaped API value interpolated into a
# workflow command, and a test that asserted its absence on a path that exits two guards
# earlier and so could never fail). One line that is always right beats two where the
# second needs a guard to stop contradicting the first.
echo "${CONTEXT} is '${ex_state}' on ${SHA:0:7} and is not being inherited as a reviewer verdict for this base (creator='${ex_creator:-null}', allow-list='${H10_REVIEWERS}', description='${ex_desc}') — re-deriving it from the PR's current state. If '${ex_creator:-that account}' is a reviewer, add them to H10_REVIEWERS in .gitea/workflows/review-verdict.yml."
fi
# --- Changed files: the SHARED enumeration, or no exemption. -------------------------
@@ -823,8 +976,9 @@ jobs:
# when the mark is taken are below it and stay invisible either way.
#
# Presence alone would be the wrong test, and wrong in the direction that breaks the gate: the
# short-circuit deliberately does NOT stop for a human verdict whose recorded base does not
# match this PR's (`ex_human` is reset to `no` — see `read_existing_verdict`). Such a row stays
# short-circuit deliberately does NOT stop for a verdict whose recorded base does not match this
# PR's (`ex_attributable` is cleared, and `ex_human` is derived from it afterwards, so both
# flags go with it — see `read_existing_verdict`). Such a row stays
# in the history forever, so a presence test would fire on EVERY later run of that PR,
# downgrade every exemption to `pending`, and deadlock it permanently.
#
@@ -844,8 +998,13 @@ jobs:
*) max_id_before=$mark ;;
esac
else
# Not fatal: the POST below is still correct, only the after-the-fact verification is
# weakened. Recorded so a silent degradation is visible in the log.
# NOT FATAL, BUT NOT HARMLESS EITHER, and an earlier comment here overstated it by
# calling the POST "still correct": without a mark the post-write race check is skipped
# entirely, so a verdict landing in the write window is neither detected nor repaired.
# Recorded so the degradation is visible in the log. A fix was attempted on this branch
# and WITHDRAWN — withholding the exemption writes a GENERIC `pending`, which a later run
# re-derives into `success` anyway, and this workflow has no retry trigger, so it stalls
# exempt PRs instead. It needs a sticky unverified-write sentinel: ersatztv#849.
echo "::warning::Could not establish a status high-water mark for ${SHA:0:7}; the post-write race check will be skipped."
max_id_before=-1
fi
@@ -856,9 +1015,16 @@ jobs:
# first read cannot see that; this one can. It NARROWS the window, it does not close it: there
# is no compare-and-set on Gitea's status API, so a verdict landing between this read and the
# POST below is still lost — which is what the post-write repair below is for.
#
# `ex_attributable`, NOT `ex_human` (ersatztv#742). The allow-list narrows INHERITANCE; this
# site asks the opposite question and must stay broad, for the same reason the post-write
# raced check does. Narrowing it would make the job stop abstaining and post its exemption
# over the row — and the post-write repair does not cover that, because it is skipped
# whenever the high-water mark could not be established.
read_existing_verdict
if [ "$ex_human" = yes ]; then
echo "::notice::A human verdict ('${ex_state}' by '${ex_creator}') landed on ${SHA:0:7} while this job was classifying — leaving it alone and posting nothing."
if [ "$ex_attributable" = yes ] \
&& { [ "$ex_state" != "$pre_state" ] || [ "$ex_creator" != "$pre_creator" ] || [ "$ex_desc" != "$pre_desc" ]; }; then
echo "::notice::An attributable verdict ('${ex_state}' by '${ex_creator}') landed on ${SHA:0:7} while this job was classifying — leaving it alone and posting nothing."
exit 0
fi
@@ -904,10 +1070,16 @@ jobs:
#
# An UNTRUSTED count on either side (`rt_ok=no`: paging never reached a validated empty
# page, a page was unreadable, the cap was hit) is NOT treated as "no retarget". It blocks
# the exemption `success` only, and lets `pending` through: `pending` cannot turn a rejection
# or an unreviewed head green, so withholding it would strand PRs for no safety gain, while
# a `success` written on a count we could not verify is exactly the forged-green outcome
# this fence exists to prevent.
# the exemption `success` only, and lets `pending` through — because a `success` written on a
# count we could not verify is exactly the forged-green outcome this fence exists to
# prevent, while `pending` blocks the merge immediately.
#
# "FOR NO SAFETY GAIN" WAS TOO STRONG and is retracted (ersatztv#742 review, #849). A
# GENERIC `pending` is not inert: it masks a rejection landing in its own write window, and
# post-write verification never runs for it, so a LATER run re-derives it into an exemption
# `success` with that rejection below the new mark. Letting it through is still right — the
# alternative strands every PR whenever the timeline is unreadable — but the trade is
# "immediate block, later re-derivation risk", not "free".
count_retargets
if [ "$retargets_before_ok" = yes ] && [ "$rt_ok" = yes ] && [ "$rt_count" -ne "$retargets_before" ]; then
echo "::notice::PR #${PR} was retargeted while this job was classifying (${retargets_before} -> ${rt_count} retarget events). This run's classification was computed against a base the PR may no longer target, so it posts NOTHING. The retarget fired an 'edited' event, so a successor run is already queued and will write the authoritative status for ${SHA:0:7}."
@@ -933,9 +1105,14 @@ jobs:
# produce and strictly worse than any stall.
#
# So verify AFTERWARDS and repair in the safe direction. This runs ONLY on the `success`
# path, and that restriction is the point rather than an optimisation: `pending` cannot
# turn a rejection green — it already blocks the merge — so the only write that can cause
# the damage is the exemption `success`.
# path — and THAT RESTRICTION IS A KNOWN HOLE, not the optimisation an earlier comment here
# claimed. The claim was "`pending` cannot turn a rejection green, so the only write that
# can cause the damage is the exemption `success`". False: a GENERIC `pending` (the one a
# run writes after a transient enumeration failure) masks a raced rejection just as well,
# and because it is not the sticky sentinel, the NEXT run re-derives it into an exemption
# `success` — with the human's row now below that run's high-water mark, invisible. The
# damage arrives one event later instead of immediately. Tracked as ersatztv#849; the fix
# is to verify every write, not to widen this condition alone.
#
# WHY A DIFFERENT ENDPOINT. Everywhere else this job reads the COMBINED endpoint
# (`/commits/{sha}/status`), which returns the LATEST status per context — and that is now
@@ -986,6 +1163,29 @@ jobs:
# (a) a HUMAN verdict — non-null creator, `Review-verdict:` description;
# (b) a machine SENTINEL — null creator, description exactly `$REPAIR_DESC`.
#
# (a) IS DELIBERATELY BROADER THAN THE INHERITANCE TEST (ersatztv#742), and the reason
# is NOT the obvious one. "Narrowing it would let a rejection go green" does not hold:
# a genuine reviewer is on `$H10_REVIEWERS` by construction, so membership here would
# still count every real verdict, and an off-list row is one this job deliberately
# overwrote a few lines earlier. That reason is stated here only to be refused, because
# it is the one that looks obviously right.
#
# THE REASON is the misconfiguration case, which is the only way an off-list row is
# ever a real verdict: a second human account added to the repo and forgotten from the
# literal. It is the last net on THIS path — not the last net overall, which an earlier
# comment claimed: a rejection already on the head sits below the mark and is invisible
# here, and the `pending` route above bypasses this block entirely (ersatztv#849). The
# two errors within its reach are not
# symmetric — repairing to `pending` is recoverable by re-posting the verdict, while a
# wrongly-standing `success` on a head nobody reviewed is not. So it counts any
# attributable row.
#
# THE COST, stated rather than implied: any `Review-verdict:`-shaped row from any
# account landing inside the write window triggers the STICKY `$REPAIR_DESC` sentinel,
# and that head loses its exemption until a human runs `post-review-verdict.sh`. The
# window is the gap between the last-moment re-read and the POST, so this is narrow, but
# it is a permanent per-sha loss and not an inconvenience.
#
# (b) is not decoration. With two overlapping runs A and B, the human row can land BELOW
# A's mark (so (a) cannot see it) while B masks it with an exemption success and only
# afterwards writes the sentinel. A then finds nothing human above its mark, does not
+1 -1
View File
@@ -83,7 +83,7 @@ main in) and re-run the local gate whenever the fetch shows movement.
Every task that closes a Gitea issue MUST complete ALL of these before it is considered done. Use `/done <issue>` to run through this automatically.
**Merge-consent is derived from state, not asserted (`## Done-when` convention — ersatztv#303 H6 + H10).** Any issue whose PR will merge to `main` should carry a `## Done-when` section in its **issue body** — a checklist of completion criteria (always include an "adversarial review passed" box; add per-issue criteria like tests-green, docs-updated, live-E2E). Two hooks derive merge-consent from it so a premature merge is blocked *by construction*, not by memory:
- `pretooluse-merge-consent.sh` (Claude PreToolUse on the Gitea merge tool) — **auto-grants** a merge (emits `permissionDecision: allow`, so **no** redundant mechanical prompt fires) only when the PR's CI is green **and** every `## Done-when` box on the linked issue (`fixes #N`) is ticked **and** a `Review-verdict:` comment references the PR's *current head sha* (**H10**); **denies** on an unticked box, red CI, or a stale/negative review verdict; **asks** (falls back to a human prompt) when it can't derive state (no linked issue, no `## Done-when` section, no `Review-verdict:` comment yet, no creds, Gitea down). On the auto-grant (satisfied) path the derived state **is** the consent — do not also ask conversationally to merge; a separate human confirmation is warranted only when the gate **asks** (ersatztv#314). **The H10 review-verdict convention**: after an adversarial/Codex review of a PR (or its latest fix commit), run **`scripts/post-review-verdict.sh <pr> <MERGEABLE|APPROVED|LGTM|BLOCKED|NOT-MERGEABLE> [note]`** — it posts both the `Review-verdict: … @ <head-sha>` comment and the sha-bound `review-verdict/h10` commit status, proving the *latest* commit was reviewed rather than a stale earlier diff (ersatztv#242). Do not hand-write the comment: the **status** is the required check branch protection enforces, and a comment alone leaves it absent.
- `pretooluse-merge-consent.sh` (Claude PreToolUse on the Gitea merge tool) — **auto-grants** a merge (emits `permissionDecision: allow`, so **no** redundant mechanical prompt fires) only when the PR's CI is green **and** every `## Done-when` box on the linked issue (`fixes #N`) is ticked **and** a `Review-verdict:` comment references the PR's *current head sha* (**H10**); **denies** on an unticked box, red CI, or a stale/negative review verdict; **asks** (falls back to a human prompt) when it can't derive state (no linked issue, no `## Done-when` section, no `Review-verdict:` comment yet, no creds, Gitea down). On the auto-grant (satisfied) path the derived state **is** the consent — do not also ask conversationally to merge; a separate human confirmation is warranted only when the gate **asks** (ersatztv#314). **The H10 review-verdict convention**: after an adversarial/Codex review of a PR (or its latest fix commit), run **`scripts/post-review-verdict.sh <pr> <MERGEABLE|APPROVED|LGTM|BLOCKED|NOT-MERGEABLE> [note]`** — it posts both the `Review-verdict: … @ <head-sha>` comment and the sha-bound `review-verdict/h10` commit status, proving the *latest* commit was reviewed rather than a stale earlier diff (ersatztv#242). Do not hand-write the comment: the **status** is the required check branch protection enforces, and a comment alone leaves it absent. **The credential you post with must be an account on `H10_REVIEWERS` in `.gitea/workflows/review-verdict.yml`** (`timothy` today) — since ersatztv#742 the gate inherits an existing `success` only from an allow-listed creator (an existing `failure` is left alone on a weaker attributability test, so an attributable rejection VISIBLE AT THE FIRST READ is not re-derived into a green — a rejection landing later, inside a run's own write window, is a separate and still-open route, ersatztv#849), so a verdict posted with any other account is written, reported as success by the script, and then silently re-derived on the next PR event (ersatztv#845).
- **The gate is enforced server-side, per sha (ersatztv#622).** `review-verdict/h10` is a required status check on `main`. Because a commit status belongs to one sha, a commit pushed *after* an auto-merge is scheduled clears it and blocks the merge — closing the hole where `merge_when_checks_succeed` froze consent at scheduling time and Gitea later merged an unreviewed head. Renovate-authored and docs-only PRs are auto-passed by `.gitea/workflows/review-verdict.yml`, **except** when they touch `.claude/`, `.codex/`, `.gitea/`, `.husky/`, `scripts/` or `docker/ci/`. See `docs/ci-cd.md` → Review-verdict gate.
- `.husky/pre-push` → `prepush-donewhen.sh` — a fail-open backstop that blocks a direct `git push origin main` whose commits `fix #N` an issue with unticked boxes. **Since ersatztv#743 that push can no longer happen at all** (see below), so this hook is now belt-and-braces for a path the server refuses.
+85 -22
View File
@@ -1293,24 +1293,83 @@ dependency PR is unexpectedly asking for a verdict, this is why**; the status de
The two exemptions are evaluated as **independent predicates**, never as an `elif` chain: a Renovate
PR touching only `docs/` still gets the docs-only exemption on its own merits.
An existing `review-verdict/h10` on the head is **only** left alone when it is positively identifiable
as a human verdict — a non-null `.creator.login` **and** a `Review-verdict:` description, which is what
`post-review-verdict.sh` writes. Anything else, including any shape the workflow does not recognise, is
**re-derived** rather than inherited. (Measured: a status POSTed with a user credential carries a
creator; one POSTed by an Actions job carries `"creator": null`.) Without this, an exemption obtained
once was accepted unchanged on every later run. This is a *provenance* check, not an authentication
one — someone who can POST statuses directly can still impersonate a verdict (ersatztv#697). That
provenance asymmetry is *why* the credential scoping in `ci.actions-credential-scoping` mattered: a
forgery through a **user** credential inherits as a human verdict, while one through a job's
`GITEA_TOKEN` carries `creator: null` and is re-derived, so it must win a race. CI's registry secret
was a user credential — the admin account — and no longer carries status-write. **`RENOVATE_TOKEN`
still is one** (`write:repository`, a real bot account), and secrets are a per-repo store any
PR-added workflow can reference, so that route is narrowed rather than closed; tightening this check
from "non-null creator" to an allow-list of approved reviewers is what would close it
(ersatztv#742). A collaborator's own personal token still can, and no repo-side change closes that.
Note also that re-derivation is **not** a race the attacker can lose: it fires only on the trigger's
`types`, and posting a status is not one of them, so a POST timed after the last PR event stands
until the next one.
An existing `review-verdict/h10` **`success`** on the head is **only** left alone when it is positively
identifiable as a verdict from an approved reviewer — a `.creator.login` in the workflow's
`H10_REVIEWERS` allow-list **and** a `Review-verdict:` description, which is what
`post-review-verdict.sh` writes. Anything else, including any shape the workflow does not recognise,
is **re-derived** rather than inherited. An existing **`failure`** is left alone on a weaker test —
attributable (`Review-verdict:`, a non-null creator, and a base matching this PR's) but **not**
necessarily allow-listed — see the state asymmetry below. (Measured: a status POSTed with a user credential carries a creator; one POSTed by an
Actions job carries `"creator": null`.) Without this, an exemption obtained once was accepted
unchanged on every later run.
**The allow-list replaced a "non-null creator" test (ersatztv#742), and how wide that old test
really was is the point.**
Non-null proved only that *some* user credential POSTed the status, and this repo stores credentials
for accounts that are not reviewers. `RENOVATE_TOKEN` is a `write:repository` PAT of the `renovate`
bot; unlike the registry credential it **cannot be scoped down** (Renovate needs repo write to push
branches and open PRs), and secrets are a per-repo *store* rather than a per-workflow grant, so a
PR-added workflow can reference it and POST a `Review-verdict:` success that reads back
`creator: renovate` — non-null, and therefore inheritable. (Inferred, not observed: `renovate` has
never actually posted a commit status in this repo — every row on all six Renovate-authored PR heads
carries `creator: null`. The user-credential-vs-Actions-token asymmetry underneath it IS measured.)
Membership makes every non-reviewer account's
**`success`** re-derive exactly as an Actions-token status does. The list is a **literal in the workflow**, not a
repo `vars:` entry or a secret: those are settable without a PR, i.e. without this gate, while
`.gitea/` is on the PROTECTED path list so the edit cannot ride a docs-only exemption either.
**The allow-list governs an inherited `success`. It does NOT govern a `failure`**, and the asymmetry is
deliberate: an off-list `failure` is left alone, because inheriting a rejection can only ever withhold
an exemption while re-deriving one can turn it green on an exempt PR. The worst a forged `failure`
achieves is a stall, and `post-review-verdict.sh` POSTs unconditionally, so any human clears it in one
command.
**Beyond that, two other readers of `.creator` stay broad, and the split is load-bearing.** `read_existing_verdict` carries two flags: `ex_attributable` (an attributable
`Review-verdict:` row for this base, whoever wrote it) and `ex_human` (`ex_attributable` **plus**
membership).
- The **inheritance short-circuit** reads `ex_human`. Narrowing is safe there: an unrecognised account
falls through to re-derivation.
- The **last-moment re-read** reads `ex_attributable`, because it asks the opposite question — "did a
reviewer post a verdict while we were classifying". Narrowing it makes the job stop abstaining and
post its exemption over the row, and the post-write repair does not cover that: it is skipped
whenever the high-water mark could not be established. It additionally requires the
state/creator/description triple to have *changed* since the first read, because the two calls no
longer compute an identical predicate and "changed" can no longer be inferred from "fired".
- The **post-write raced check** stays broad on `creator != null`. Not because narrowing it would let
a rejection go green — a real reviewer is on the list by construction — but for the
misconfiguration case, a second human account added to the repo and forgotten from the literal.
Its reach is narrower than it looks: it covers such a verdict landing inside the **write window**
and nothing else, since a verdict already on the head sits below the high-water mark and is
invisible to it. Within that window the errors are asymmetric — a repair to `pending` is
recoverable, a wrongly-standing `success` is not — so it stays broad. The cost: any verdict-shaped
row landing in that window trips the sticky repair sentinel and costs that head its exemption until
a human clears it.
Pinned by `test_the_MID_RUN_abstain_still_fires_for_a_NON_allowlisted_creator` and
`test_the_RACED_verdict_check_still_counts_a_NON_allowlisted_creator`.
**If a reviewer's verdicts stop being honoured, this is why.** Whenever the job declines to inherit an
existing status it logs the creator, the allow-list and the description together, and says to add the
account to `H10_REVIEWERS` in `.gitea/workflows/review-verdict.yml`. (A separate `::warning::`
annotation carrying the same three values was tried and withdrawn: its only delta was a severity whose
rendering could not be probed, and it needed a guard of its own to stop contradicting the line above
it.) `post-review-verdict.sh` posts
with whatever account owns `ETV_GITEA_TOKEN`/`ETV_GITEA_BASICAUTH` and does **not** check that it is an
allow-listed one (ersatztv#845). A changed writer credential does not fail loudly — it reports success,
and each *subsequent* PR event re-derives the status: to `pending` on a PR that needs a verdict, or to
an exemption **`success`** on a docs-only or Renovate-manifest one, which is the quieter and worse
half. A verdict posted after the last event stands until the next one, so the symptom is a PR that
keeps losing its verdict rather than an immediate refusal.
This remains a *provenance* check, not an authentication one — an **allow-listed** collaborator's own
write-scoped token can still POST a verdict they did not form, branch protection binds the context
*name* rather than its issuer, and no repo-side change closes that (ersatztv#697). That provenance
asymmetry is *why* the credential scoping in `ci.actions-credential-scoping` mattered: a forgery
through an allow-listed **user** credential inherits, while one through a job's `GITEA_TOKEN` carries
`creator: null` and is re-derived, so it must win a race. Note also that re-derivation is **not** a
race the attacker can lose: it fires only on the trigger's `types`, and posting a status is not one of
them, so a POST timed after the last PR event stands until the next one.
Deciding either exemption requires the PR's **complete** changed-file list, which the workflow does
not compute itself: it calls `scripts/pr-changed-files.sh`, the single shared implementation also
@@ -1336,7 +1395,7 @@ payload, which a retarget cannot rewrite, and `edited` is in `types:` so a retar
`edited` gives **detection, not atomicity**: runs are not serialized, so a stale run could still post
`success` after the reclassifying run posted `pending`.
**That residual is now fenced (ersatztv#706).** Runs are still not serialized — instead a run that was
**That residual is now fenced — NARROWED, not resolved (ersatztv#706; correction ersatztv#849).** The fence never re-counts *after* the POST, so a retarget landing between its final pre-write count and the write still yields a **permanent** forged green: the successor run consumes the `edited` event and exits on the existing status, and the stale run then posts last with nothing left to correct it. Runs are still not serialized — instead a run that was
overtaken *declines to write*. The job counts `change_target_branch` events on the PR's issue timeline
at start and again immediately before its POST, and posts **nothing** if the count moved. The count is
the key precisely because the branch *name* is ABA-vulnerable: `main → scratch → main` reads `main` at
@@ -1345,8 +1404,10 @@ a PR, because every retarget fires `edited` — the event that makes one run abs
its successor.
If the count can't be established (unreadable timeline, paging that never reached a validated empty
page), only the exemption `success` is withheld; `pending` still posts, since `pending` cannot turn an
unreviewed head green and withholding it would strand ordinary PRs for nothing. **If an exempt PR is
page), only the exemption `success` is withheld; `pending` still posts, since it blocks the merge
immediately and withholding it would strand ordinary PRs whenever the timeline is unreadable. That is
the right trade but not a free one — a generic `pending` can mask a rejection landing in its own write
window and be re-derived into an exemption `success` later (ersatztv#849). **If an exempt PR is
unexpectedly missing its status after a retarget, this is why** — the job log names the counts.
Worth knowing before reaching for the obvious alternative: **a concurrency group does not work here**,
@@ -1359,7 +1420,9 @@ statusless with nothing left to re-trigger it. Full measurements and the two sur
Separately, after posting an exemption `success` the job re-reads the per-POST status history and, if
a human `Review-verdict:` row appeared during the write window, overwrites its own status with
`pending` and logs an error — so a human `BLOCKED` can never be silently turned green. The repair is
`pending` and logs an error. **That check runs only for a `success` write**, so "a human `BLOCKED` can
never be silently turned green" is too strong and is retracted: a generic `pending` write is not
verified, and a rejection it masks is re-derived green by a later run (ersatztv#849). The repair is
`pending`, never a copy of the human's verdict, which would attribute a human decision to the job.
Three properties of this workflow are security-relevant and are **structurally** asserted by tests in
+3 -3
View File
@@ -46,10 +46,10 @@ the link for rationale. Superseded/retired history lives in `archive/`. Regenera
| `ci.decisions-lifecycle-flake` | When `decisions lifecycle` is the **only** red job, do not investigate and do not create a new run to clear it — no rebase, no `--amend`, no no-op push; the operator reruns that single job from the Gitea UI. | 2026-07-21 | [link](records/ci/decisions-lifecycle-flake.md) |
| `ci.docs-only-detect-shallow-safe` | The docs-only detect script must diff against `FETCH_HEAD` (always resolves after `git fetch`, even shallow) using a two-dot tree diff — not `origin/<base>` with three-dot — because a `fetch-depth: 1` shallow clone has no remote-tracking ref and no merge-base, which silently fails the original detect into `docs_only=false` (full matrix, no functional error). A CI-behavior change must be verified by measuring the effect (job durations), not just a green check. | 2026-07-17 | [link](records/ci/docs-only-detect-shallow-safe.md) |
| `ci.docs-only-skip-steps` | A docs-only change must still run every required job (`test`, `migrations`) so their commit-status contexts always report; each heavy job runs `scripts/ci-detect-docs-only.sh` first and gates its real STEPS on `if: steps.detect.outputs.docs_only != 'true'`, never `if:`-skips the whole job (an `if:`-skipped job reports `skipped`, not `success`, which branch protection may never unblock on). Detection biases toward running more on any doubt. | 2026-07-17 | [link](records/ci/docs-only-skip-steps.md) |
| `ci.exemption-provenance` | The three inputs the exemption decision rests on must each be bound to something the judged PR cannot mutate. (1) BASE — `scripts/pr-changed-files.sh` takes the expected base BRANCH as a REQUIRED 5th argument and re-reads it before and after paging, because `/pulls/{n}/files` diffs against the PR's live base and retargeting moves the answer without moving the head sha; the workflow passes `github.event.pull_request.base.ref` from the `pull_request_target` payload, which a retarget cannot rewrite. (2) BOT EXEMPTION — an author match is necessary but never sufficient: `pull_request.user.login` is the PR's immutable CREATOR while its head is not, so the exemption additionally requires EVERY changed path to be a dependency manifest (`Directory.Packages.props` or `.config/dotnet-tools.json`, and ONLY those — the npm manifests are excluded because `package.json` `scripts` are executed by CI). (3) INHERITED SUCCESS — the never-overwrite short-circuit fires only for a status POSITIVELY identified as a human verdict for THIS base, meaning a non-null `.creator.login` AND a `Review-verdict:` description AND, when that description records a base (`(base: …)`, `release.verdict-status-check`), a base matching the PR's — tested by requiring the description to END with the exact literal `(base: <base>)` and to contain exactly ONE such marker, never by extracting a value (see below); a present-but-different base is rejected, an absent one is not, since verdicts predating that convention carry none; every other shape, including any unrecognised one, is re-derived rather than trusted. The bot and docs-only exemptions are evaluated as INDEPENDENT predicates and the decision made afterwards, never as an `elif` chain. `edited` is in the workflow's `types:` so a retarget reclassifies — which gives DETECTION, not atomicity: status writes are not serialized, so a stale run can still post over a fresher one. That residual is now FENCED rather than merely tracked — the job refuses to write at all if the PR's timeline retarget COUNT moved while it was classifying (`ci.verdict-write-retarget-fence`, #706) — leaving only the sub-round-trip window that no API without compare-and-set can close. The PROTECTED path list additionally covers `CLAUDE.md` and `AGENTS.md` (#751) — they are not prose but the documents DEFINING the completion protocol, the merge-consent convention and the H10 rule, so protecting `.claude/` while the file specifying what it enforces stayed docs-only-exempt was the same self-exemption one directory over; driving the real classify body with a lone `CLAUDE.md` change produced an exemption `success`. `README.md` is deliberately not listed. It also covers `.codex/` (#711), which mirrors `.claude/hooks/` byte for byte including the merge-consent hook — latent while that directory is untracked, live the moment it is tracked; the list stays ENUMERATIVE rather than derived, because a derived rule would have to be evaluated against the very file list being classified. Reading the CURRENT status for input (3) must tolerate `statuses: null`: `GET /commits/{sha}/status` serialises a nil slice as `null`, not `[]`, on a head with no statuses yet, and an `array`-only gate made `read_existing_verdict` `exit 1` and post nothing at all (#751, `ci.workflow-run-body-no-expressions`) — `null` is accepted only when `total_count` is 0, so a body that merely lost its array is still refused. Path predicates are evaluated by COUNTING with `grep -c`, never `\| grep -q` (SIGPIPE inversion) and never a here-string (temp-space failure) — see `ci.grep-q-pipefail-inversion`. | 2026-07-29 | [link](records/ci/exemption-provenance.md) |
| `ci.exemption-provenance` | The three inputs the exemption decision rests on must each be bound to something the judged PR cannot mutate. (1) BASE — `scripts/pr-changed-files.sh` takes the expected base BRANCH as a REQUIRED 5th argument and re-reads it before and after paging, because `/pulls/{n}/files` diffs against the PR's live base and retargeting moves the answer without moving the head sha; the workflow passes `github.event.pull_request.base.ref` from the `pull_request_target` payload, which a retarget cannot rewrite. (2) BOT EXEMPTION — an author match is necessary but never sufficient: `pull_request.user.login` is the PR's immutable CREATOR while its head is not, so the exemption additionally requires EVERY changed path to be a dependency manifest (`Directory.Packages.props` or `.config/dotnet-tools.json`, and ONLY those — the npm manifests are excluded because `package.json` `scripts` are executed by CI). (3) INHERITED SUCCESS — the never-overwrite short-circuit fires for a `success` only when it is POSITIVELY identified as an APPROVED REVIEWER's verdict for THIS base, meaning a `.creator.login` that is a member of the workflow's `H10_REVIEWERS` allow-list (an existing `failure` takes the weaker ATTRIBUTABLE test and needs no membership, because inheriting a rejection can only withhold an exemption while re-deriving one can turn it green on an exempt PR) — non-null was too weak, since any account's credential satisfies it and `RENOVATE_TOKEN` is one that cannot be scoped down (#742) — AND a `Review-verdict:` description AND, when that description records a base (`(base: …)`, `release.verdict-status-check`), a base matching the PR's — tested by requiring the description to END with the exact literal `(base: <base>)` and to contain exactly ONE such marker, never by extracting a value (see below); a present-but-different base is rejected, an absent one is not, since verdicts predating that convention carry none; every other shape, including any unrecognised one, is re-derived rather than trusted. The bot and docs-only exemptions are evaluated as INDEPENDENT predicates and the decision made afterwards, never as an `elif` chain. `edited` is in the workflow's `types:` so a retarget reclassifies — which gives DETECTION, not atomicity: status writes are not serialized, so a stale run can still post over a fresher one. That residual is now FENCED rather than merely tracked (NARROWED, not resolved — a retarget between the fence's final count and the POST still leaves a PERMANENT forged green, #849) — the job refuses to write at all if the PR's timeline retarget COUNT moved while it was classifying (`ci.verdict-write-retarget-fence`, #706) — leaving TWO windows, not one: the sub-round-trip window that no API without compare-and-set can close, AND the post-final-count/pre-POST window, which is not sub-round-trip and yields a PERMANENT green because the successor can consume the `edited` event and exit before the stale run posts last (#849). The PROTECTED path list additionally covers `CLAUDE.md` and `AGENTS.md` (#751) — they are not prose but the documents DEFINING the completion protocol, the merge-consent convention and the H10 rule, so protecting `.claude/` while the file specifying what it enforces stayed docs-only-exempt was the same self-exemption one directory over; driving the real classify body with a lone `CLAUDE.md` change produced an exemption `success`. `README.md` is deliberately not listed. It also covers `.codex/` (#711), which mirrors `.claude/hooks/` byte for byte including the merge-consent hook — latent while that directory is untracked, live the moment it is tracked; the list stays ENUMERATIVE rather than derived, because a derived rule would have to be evaluated against the very file list being classified. Reading the CURRENT status for input (3) must tolerate `statuses: null`: `GET /commits/{sha}/status` serialises a nil slice as `null`, not `[]`, on a head with no statuses yet, and an `array`-only gate made `read_existing_verdict` `exit 1` and post nothing at all (#751, `ci.workflow-run-body-no-expressions`) — `null` is accepted only when `total_count` is 0, so a body that merely lost its array is still refused. Path predicates are evaluated by COUNTING with `grep -c`, never `\| grep -q` (SIGPIPE inversion) and never a here-string (temp-space failure) — see `ci.grep-q-pipefail-inversion`. | 2026-07-29 | [link](records/ci/exemption-provenance.md) |
| `ci.format-gate-folder-mode` | The blocking `format` CI job (and matching pre-commit hook) runs `dotnet format whitespace . --folder --include <files>` instead of loading the full MSBuild/Roslyn solution, cutting the gate from ~480s to ~0.5s with unchanged whitespace/charset coverage. | 2026-07-19 | [link](records/ci/format-gate-folder-mode.md) |
| `ci.functional-e2e-harness` | The `functional-e2e` CI job boots the PR's own code from source via `dotnet run` (`scripts/e2e-local.sh`) and runs deterministic assertions (`scripts/e2e-functional.sh`) as an advisory (non-blocking) job, not a `build` dependency or required check. Originally curl-only; since #445 the same job carries a second, headless-browser step for the contracts curl cannot express — see `ci.ui-e2e-harness`. | 2026-07-16 | [link](records/ci/functional-e2e-harness.md) |
| `ci.gate-trigger-base-resolved` | The workflow that writes the branch-protection-required `review-verdict/h10` status triggers on `pull_request_target` with `branches: [main]`, never on plain `pull_request`. Gitea resolves a `pull_request` workflow DEFINITION from the PR's own head commit, so under that trigger a PR editing `.gitea/workflows/review-verdict.yml` ran its own rewritten copy and could post `h10=success` for itself; `pull_request_target` resolves the definition from the base instead. The `branches: [main]` filter is part of the rule, not a refinement of it: base resolution only relocates the rewrite from the head to the base, so without the filter a PR opened into an attacker-pushed base branch runs that branch's gate. `pull_request_target` is safe HERE only because this job never checks out or executes head-supplied code — it checks out `base.sha` and runs only that tree's scripts (`ci.shared-pr-file-enumeration`); reintroducing a head checkout under this trigger would be worse than the bug it fixed. This closes the rewrite route through THIS workflow and does NOT close the class: Gitea injects a write-capable `GITEA_TOKEN` into EVERY job, so any ref-resolved workflow — and a collaborator's own API token, since branch protection binds the context and not its issuer — can still forge `review-verdict/h10`. The credential half is now RESOLVED in `ci.actions-credential-scoping` (#697): CI's registry secret was the ADMIN account's basic auth and is now a PAT that cannot post a status, which removes the ADMIN escalation and that credential's route (a user credential's forgery carries a real `creator` and is inherited as a human verdict; an Actions job's carries `creator: null` and is re-derived — but do NOT read that asymmetry as protection: re-derivation fires only on the trigger's `types`, and posting a status is not one of them, so a POST timed after the last PR event simply stands). It does not remove EVERY route: `RENOVATE_TOKEN` is a `write:repository` bot PAT in the same secret store, reachable by any PR-added workflow. The injected token stays write-capable until Gitea >=1.26 with a Restricted default (server-management#714), and a collaborator's own token remains unfixable; the exemption path has its own separate defects in #698. | 2026-07-28 | [link](records/ci/gate-trigger-base-resolved.md) |
| `ci.gate-trigger-base-resolved` | The workflow that writes the branch-protection-required `review-verdict/h10` status triggers on `pull_request_target` with `branches: [main]`, never on plain `pull_request`. Gitea resolves a `pull_request` workflow DEFINITION from the PR's own head commit, so under that trigger a PR editing `.gitea/workflows/review-verdict.yml` ran its own rewritten copy and could post `h10=success` for itself; `pull_request_target` resolves the definition from the base instead. The `branches: [main]` filter is part of the rule, not a refinement of it: base resolution only relocates the rewrite from the head to the base, so without the filter a PR opened into an attacker-pushed base branch runs that branch's gate. `pull_request_target` is safe HERE only because this job never checks out or executes head-supplied code — it checks out `base.sha` and runs only that tree's scripts (`ci.shared-pr-file-enumeration`); reintroducing a head checkout under this trigger would be worse than the bug it fixed. This closes the rewrite route through THIS workflow and does NOT close the class: Gitea injects a write-capable `GITEA_TOKEN` into EVERY job, so any ref-resolved workflow — and a collaborator's own API token, since branch protection binds the context and not its issuer — can still forge `review-verdict/h10`. The credential half is now RESOLVED in `ci.actions-credential-scoping` (#697): CI's registry secret was the ADMIN account's basic auth and is now a PAT that cannot post a status, which removes the ADMIN escalation and that credential's route (an ALLOW-LISTED user credential's forgery carries a matching `creator` and is inherited as a verdict; an Actions job's carries `creator: null` and is re-derived, as since #742 is every account outside `H10_REVIEWERS` — but do NOT read that asymmetry as protection: re-derivation fires only on the trigger's `types`, and posting a status is not one of them, so a POST timed after the last PR event simply stands). It does not remove EVERY route: `RENOVATE_TOKEN` is a `write:repository` bot PAT in the same secret store, reachable by any PR-added workflow. The injected token stays write-capable until Gitea >=1.26 with a Restricted default (server-management#714), and a collaborator's own token remains unfixable; the exemption path has its own separate defects in #698. | 2026-07-28 | [link](records/ci/gate-trigger-base-resolved.md) |
| `ci.gitea-milestone-filter-noop` | Never filter issues with the server-side `?milestones=<name>` parameter — fetch all open issues once and filter LOCALLY on each issue's `.milestone.title`. | 2026-07-21 | [link](records/ci/gitea-milestone-filter-noop.md) |
| `ci.grep-q-pipefail-inversion` | In any script running under `set -o pipefail`, a security or classification predicate of the form `producer \| grep -q…` is FORBIDDEN: `grep -q` exits at its first match, the producer then takes SIGPIPE and exits 141 once the data exceeds the pipe buffer (~64K), so `pipefail` reports the pipeline as FAILED even though grep MATCHED — inverting the predicate exactly when the input is large. A here-string (`grep -q… <<< "$data"`) is ALSO forbidden: bash materialises a large here-string via temporary storage, so it fails when temp space is full or unwritable, and inside an `if`/`!` that failure flips the predicate the same way. COUNT instead — `n=$(printf '%s\n' "$data" \| grep -cE "$re")` — because `grep -c` drains stdin (no early exit, no SIGPIPE) over an ordinary pipe (no temp file). Read grep's status honestly: exit 1 means a zero count and is a legitimate answer, anything >1 is a real error. Evaluate the counts ONCE at TOP LEVEL, never inline inside an `if`/`elif` condition: inside `$( )` an `exit` leaves only the subshell and `set -e` does not fire, so an error silently reads as "no match". Validate that each result is numeric and fail closed if not. This applies to both the enforced gate `.gitea/workflows/review-verdict.yml` and the advisory hook `.claude/hooks/pretooluse-merge-consent.sh`. | 2026-07-29 | [link](records/ci/grep-q-pipefail-inversion.md) |
| `ci.infra-shaped-red-under-load` | When a job dies inside a setup/cache step before your code compiles, check the runner host's load before diagnosing the diff, and never file a CI bug off one sample under pressure. | 2026-07-21 | [link](records/ci/infra-shaped-red-under-load.md) |
@@ -66,7 +66,7 @@ the link for rationale. Superseded/retired history lives in `archive/`. Regenera
| `ci.shared-pr-file-enumeration` | A PR's complete set of changed file paths is computed by exactly one implementation, `scripts/pr-changed-files.sh`, called by both `.claude/hooks/pretooluse-merge-consent.sh` (advisory — a failure falls through to a human prompt) and `.gitea/workflows/review-verdict.yml` (enforced — a failure must fail closed, because a match here posts the branch-protection-required `review-verdict/h10` status with nobody in the loop). The script owns exhaustiveness (pagination, rename/path validation, head-sha binding, base-ref binding — see `ci.exemption-provenance` — and base-TIP binding, #707: the ref answers "did this PR RETARGET", the tip answers "did the base ADVANCE mid-enumeration", and only the second can see `/pulls/{n}/files` recomputing each offset-paged page against a moved base and dropping a path out of an already-consumed range; both ends of the window are bound, and an advance BEFORE the window is deliberately not an error, or ordinary churn on `main` would fail every open PR) and returns exit 0 only for a verified-complete list; it does NOT classify paths — each caller keeps its own docs-only allow-list, and the two allow-lists differ on purpose and stay separate. | 2026-07-26 | [link](records/ci/shared-pr-file-enumeration.md) |
| `ci.small-lane-git-only` | `runs-on: small` is defined by what a job does (git-only), not its usual runtime; the two `docker build` jobs (docker-build.yml, ci-image.yml) move to `ubuntu-latest` because their worst-case memory, not median runtime, was pinning the small lane's per-slot cap. | 2026-07-20 | [link](records/ci/small-lane-git-only.md) |
| `ci.ui-e2e-harness` | The UI-interactive E2E flows run as headless Playwright specs (`web/e2e/*.spec.ts`, driven by `scripts/e2e-ui.sh`) in a **second step of the existing advisory `functional-e2e` job**, never their own job; the browser is `chromium-headless-shell` **baked into the CI toolchain image** (`docker/ci/Dockerfile`, `PLAYWRIGHT_VERSION` kept equal to `web/package.json`'s EXACT `@playwright/test` pin), never installed per run; specs are `serial` with `retries: 0` and assert only contracts the curl harness structurally cannot reach. | 2026-07-25 | [link](records/ci/ui-e2e-harness.md) |
| `ci.verdict-write-retarget-fence` | The `review-verdict/h10` job counts `change_target_branch` events on the PR's issue timeline at run start and again immediately before its POST, and writes NOTHING if the count moved. The COUNT is the key because the branch NAME is ABA-vulnerable — `main -> S -> main` reads `main` at both ends, which is how #698 route 1 obtained a forged exemption — while the event count is monotonic and cannot alias. Abstaining is a handoff, not a stall, and that is the property the design rests on: every retarget fires `edited`, which is in this workflow's `types:`, so the event that makes a run abstain has already queued a successor whose window opens after it; the induction terminates when retargeting stops and the last run writes the final answer. `updated_at` was REJECTED as the key because it also moves for comments and labels, which fire none of this workflow's `types:` — a run could abstain with no successor coming, which is a real stall. The count is trusted only when paging reached a validated EMPTY page; an untrusted count (unreadable page, non-array body, non-numeric length, page cap hit) blocks the exemption `success` ONLY and still lets `pending` through, because `pending` cannot turn an unreviewed head green while withholding it would strand ordinary PRs for no safety gain. SEPARATELY, and for the human-verdict race the fence does nothing about: after posting an exemption `success` the job re-reads `/statuses/{sha}` and, if a human `Review-verdict:` row appeared with an id ABOVE a high-water mark taken just before the POST, overwrites its own status with `pending` and logs an error. The repair is `pending`, NEVER a copy of the human's state, since re-posting their `failure` under the machine credential would attribute a human verdict to the job; its description is a SENTINEL that the classification refuses to grant an exemption over AND re-writes verbatim on every later run, so the block is a FIXED POINT rather than decaying — writing the generic `pending` description there instead erases the marker and the exemption simply returns one event later. The mark is captured BEFORE the last-moment re-read, not merely before the POST — a later mark leaves a multi-round-trip blind gap in which a verdict is neither seen by the re-read nor repaired afterwards. The id comparison is load-bearing: a mere presence test would fire forever on a base-mismatched verdict that `read_existing_verdict` deliberately declines to honour, deadlocking that PR's exemption permanently. Finally, a run whose last-moment re-read finds a sentinel it did not see at its FIRST read ABSTAINS instead of posting: that can only mean an overlapping run repaired a raced verdict mid-flight, and this run's `success` — frozen at classification time, with the human row below its own mark, so neither the fence nor the post-write check would catch it — would otherwise bury the rejection. That is the one path in this design that failed toward SUCCESS rather than `pending`. The post-write check counts TWO row shapes above the mark, not one — a human `Review-verdict:` row AND a machine sentinel — because with two overlapping runs the human row can sit BELOW the second run's mark while the first masks it and only then writes the sentinel, leaving the second to post its own `success` on top; counting the sentinel converges both runs on the fixed point instead. | 2026-08-03 | [link](records/ci/verdict-write-retarget-fence.md) |
| `ci.verdict-write-retarget-fence` | The `review-verdict/h10` job counts `change_target_branch` events on the PR's issue timeline at run start and again immediately before its POST, and writes NOTHING if the count moved. The COUNT is the key because the branch NAME is ABA-vulnerable — `main -> S -> main` reads `main` at both ends, which is how #698 route 1 obtained a forged exemption — while the event count is monotonic and cannot alias. This NARROWS the residual, it does not resolve it — a retarget between the FINAL pre-write count and the POST still yields a PERMANENT forged green, because the successor run can consume the `edited` event and exit before the stale run posts last (corrected 2026-08-27, #849). Abstaining is a handoff, not a stall, and that is the property the design rests on — for a run that ABSTAINS; it says nothing about one that already passed its final count and then posts (see the residual, corrected #849): every retarget fires `edited`, which is in this workflow's `types:`, so the event that makes a run abstain has already queued a successor whose window opens after it; the induction terminates when retargeting stops — but ONLY over runs that ABSTAIN. A run that already passed its final count is outside it: it writes whenever it gets there, so the run that writes LAST is not necessarily the one that classified last, and that is the permanent residual (#849). `updated_at` was REJECTED as the key because it also moves for comments and labels, which fire none of this workflow's `types:` — a run could abstain with no successor coming, which is a real stall. The count is trusted only when paging reached a validated EMPTY page; an untrusted count (unreadable page, non-array body, non-numeric length, page cap hit) blocks the exemption `success` ONLY and still lets `pending` through, because `pending` blocks the merge immediately while withholding it would strand ordinary PRs whenever the timeline is unreadable — the right trade, but NOT a free one ("for no safety gain" retracted 2026-08-27): a GENERIC `pending` masks a rejection landing in its own write window, post-write verification does not run for it, and a later run re-derives it into an exemption `success` (#849). SEPARATELY, and for the human-verdict race the fence does nothing about: after posting an exemption `success` the job re-reads `/statuses/{sha}` and, if a human `Review-verdict:` row appeared with an id ABOVE a high-water mark taken just before the POST, overwrites its own status with `pending` and logs an error. The repair is `pending`, NEVER a copy of the human's state, since re-posting their `failure` under the machine credential would attribute a human verdict to the job; its description is a SENTINEL that the classification refuses to grant an exemption over AND re-writes verbatim on every later run, so the block is a FIXED POINT rather than decaying — writing the generic `pending` description there instead erases the marker and the exemption simply returns one event later. The mark is captured BEFORE the last-moment re-read, not merely before the POST — a later mark leaves a multi-round-trip blind gap in which a verdict is neither seen by the re-read nor repaired afterwards. The id comparison is load-bearing: a mere presence test would fire forever on a base-mismatched verdict that `read_existing_verdict` deliberately declines to honour, deadlocking that PR's exemption permanently. Finally, a run whose last-moment re-read finds a sentinel it did not see at its FIRST read ABSTAINS instead of posting: that can only mean an overlapping run repaired a raced verdict mid-flight, and this run's `success` — frozen at classification time, with the human row below its own mark, so neither the fence nor the post-write check would catch it — would otherwise bury the rejection. That is the one path in this design that failed toward SUCCESS rather than `pending`. The post-write check counts TWO row shapes above the mark, not one — a human `Review-verdict:` row AND a machine sentinel — because with two overlapping runs the human row can sit BELOW the second run's mark while the first masks it and only then writes the sentinel, leaving the second to post its own `success` on top; counting the sentinel converges both runs on the fixed point instead. | 2026-08-03 | [link](records/ci/verdict-write-retarget-fence.md) |
| `ci.verify-locally-ci-confirms` | Treat the local build/verify/review pass as the decision point and CI as confirmation — don't idle waiting on a run you have no reason to doubt. | 2026-07-21 | [link](records/ci/verify-locally-ci-confirms.md) |
| `ci.web-test-per-test-timeouts` | Give heavy-render web tests an explicit per-test vitest timeout (e.g. 15s); never raise the global default to fix one slow test. | 2026-07-21 | [link](records/ci/web-test-per-test-timeouts.md) |
| `ci.workflow-run-body-no-expressions` | A `run:` body is not shell when the runner reads it: the runner scans the whole scalar for the expression opener and, on finding one, rewrites the ENTIRE body into a single `format(...)` call. That rewrite is all-or-nothing, so a payload that does not evaluate fails the interpolation of the whole scalar — and the runner then DROPS THE STEP AND CONCLUDES THE JOB `success`. A shell comment is therefore NOT inert. In `.gitea/workflows/review-verdict.yml` no expression delimiter may appear in ANY `run:` body, in code or in prose, because a dropped step there is a dead merge gate rather than a failed build; pass values in through the step's `env:` block, which is interpolated per value so a bad payload cannot take the body with it, and describe an expression in prose by NAMING it (`a github.event.pull_request.number expression`) rather than quoting the delimiters. Repo-wide the rule is weaker and its reach must be stated precisely rather than generously: every expression payload in every workflow field must have a HEAD TOKEN naming a context or function the runner can resolve. That catches the defect above and a nonexistent context; it does NOT catch a syntactically invalid payload whose tokens are all known (`${{ github.ref == }}`), a renamed output (every token after the first is skipped), or an unclosed opener — those need an expression parser, and the guard is kept permissive on purpose because a red here blocks every merge through the combined status. In `review-verdict.yml` specifically, any step whose non-execution is consequential is paired with a start-marker guard that FAILS the job when the marker is absent, and that guard's own body must be expression-free — a guard the guarded mechanism can silently delete is worse than none. That pairing now also covers `docker-build.yml`'s `test` and `migrations` jobs, where a dropped step is fail-OPEN (the required check goes green having done no work) rather than fail-closed as it is here — see `ci.required-job-step-execution-markers`, which adds per-STEP markers there and extends this file's delimiter ban to those two jobs. It is still not a repo-wide property, but the remaining exceptions are narrower than this record originally said: `build` was brought into the ban too (its `Smoke + IPTV E2E` runs AFTER the image is pushed, so a drop there ships an unsmoked release candidate — its two payloads moved to `env:`, so the ban was free), leaving only `api-docs` and `format`, whose one `github.base_ref` each sits in a detect step that gates nothing that ships. | 2026-08-06 | [link](records/ci/workflow-run-body-no-expressions.md) |
@@ -40,9 +40,24 @@ this, but is not free: packages live in a user namespace only its owner and admi
halves INFERRED, neither probed.
**Provenance, corrected.** `review-verdict.yml` leaves an existing `h10` alone only when it is
positively identifiable as human — non-null `.creator.login` plus a `Review-verdict:` description
(`release.verdict-status-check`). A user credential posts with a real creator and is INHERITED; an
Actions job posts `creator: null` and is re-derived. **That asymmetry is not protection.** Re-derivation
positively identifiable as an approved reviewer's verdict — a `.creator.login` in the workflow's
`H10_REVIEWERS` allow-list plus a `Review-verdict:` description (`release.verdict-status-check`,
`ci.exemption-provenance`). An allow-listed user credential posts with a matching creator and is
INHERITED; an Actions job posts `creator: null` and is re-derived, and so now is every other account.
**The `RENOVATE_TOKEN` INHERITANCE route is closed by the allow-list, not by scoping (#742),
because scoping was not available — and inheritance is the only half it closes.** A status POSTed
with that token still satisfies branch protection if it is timed after the last PR event; what it can
no longer do is survive as a verdict across every later run of the workflow. That token needs `write:repository` to do its job — pushing branches and opening PRs
— so there is no `write:package`-shaped separation to exploit the way there was for the registry
credential, and secrets are a per-repo store any workflow can reference. The test was therefore
tightened at the *reader* instead: `creator IN <allow-list>` rather than `creator != null`, which
re-derives a `renovate`-posted verdict exactly as it re-derives an Actions-token one. Scoping and
allow-listing close the same class from opposite ends; where a credential cannot be narrowed, narrow
what the consumer will accept from it. **The creator-shape asymmetry — an ALLOW-LISTED creator's `success` INHERITED, everything else
re-derived — is not protection.** (Since #742 "a real creator" is no longer the test: only
`H10_REVIEWERS` membership inherits a `success`, while a `failure` inherits on attributability
alone.) Re-derivation
fires only on `opened|reopened|synchronize|ready_for_review|edited`, and posting a status is none of
them, so a POST timed after the last event stands until the attacker merges. The gain here is that PR
code can no longer escalate to instance admin — NOT that the durable forgery route is closed.
@@ -96,15 +111,18 @@ date and are the best evidence available, but do not cite them as current behavi
re-probing. Re-verification of the 1.25.4-pinned claims across the CI docs is tracked separately.
**Surviving routes — this record is not a mitigation for any of them.** `RENOVATE_TOKEN` is a
`write:repository` bot PAT in the same store, posting with a real creator, and cannot be scoped down
because Renovate needs repo write (#742). The injected `GITEA_TOKEN` is write-capable in every job;
`write:repository` bot PAT in the same store and still cannot be scoped down, because Renovate needs
repo write; what changed is that a verdict posted with it is no longer *inherited* — `renovate` is not
in `H10_REVIEWERS`, so `review-verdict.yml` re-derives it (#742). It remains status-capable, so it can
still overwrite a status; it can no longer impersonate a reviewer. The injected `GITEA_TOKEN` is write-capable in every job;
only Gitea >=1.26 with the Actions default set to **Restricted** binds it (server-management#714).
Both halves of that condition have now been checked and it does not hold, because of the second one:
the version half IS satisfied (1.27.1), while the default was set to Restricted, verified, and
reverted to `permissive` on 2026-08-05 because this repo is not ready for it (#748). So the route is
open, and open for a known reason rather than an unprobed one — waiting on a further Gitea upgrade
would be waiting on the wrong thing. A
collaborator's own token always can. `docker-build.yml` publishes `:prod` from a `v*` tag push and a tag
collaborator's own token always can — and after #742 an ALLOW-LISTED collaborator's still is
inherited, which is the residual the allow-list explicitly does not touch. `docker-build.yml` publishes `:prod` from a `v*` tag push and a tag
may point at ANY commit — a prod image with no PR, review or status (tag protections are empty).
**And none of it was necessary: direct pushes to `main` were server-side permitted, so the gate was
bypassable with no forgery at all (#743).** That route is now closed — `main` carries
@@ -5,9 +5,9 @@ status: active
since: '2026-07-29'
supersedes: none
superseded-by: none
rule: 'The three inputs the exemption decision rests on must each be bound to something the judged PR cannot mutate. (1) BASE — `scripts/pr-changed-files.sh` takes the expected base BRANCH as a REQUIRED 5th argument and re-reads it before and after paging, because `/pulls/{n}/files` diffs against the PR''s live base and retargeting moves the answer without moving the head sha; the workflow passes `github.event.pull_request.base.ref` from the `pull_request_target` payload, which a retarget cannot rewrite. (2) BOT EXEMPTION — an author match is necessary but never sufficient: `pull_request.user.login` is the PR''s immutable CREATOR while its head is not, so the exemption additionally requires EVERY changed path to be a dependency manifest (`Directory.Packages.props` or `.config/dotnet-tools.json`, and ONLY those — the npm manifests are excluded because `package.json` `scripts` are executed by CI). (3) INHERITED SUCCESS — the never-overwrite short-circuit fires only for a status POSITIVELY identified as a human verdict for THIS base, meaning a non-null `.creator.login` AND a `Review-verdict:` description AND, when that description records a base (`(base: …)`, `release.verdict-status-check`), a base matching the PR''s — tested by requiring the description to END with the exact literal `(base: <base>)` and to contain exactly ONE such marker, never by extracting a value (see below); a present-but-different base is rejected, an absent one is not, since verdicts predating that convention carry none; every other shape, including any unrecognised one, is re-derived rather than trusted. The bot and docs-only exemptions are evaluated as INDEPENDENT predicates and the decision made afterwards, never as an `elif` chain. `edited` is in the workflow''s `types:` so a retarget reclassifies — which gives DETECTION, not atomicity: status writes are not serialized, so a stale run can still post over a fresher one. That residual is now FENCED rather than merely tracked — the job refuses to write at all if the PR''s timeline retarget COUNT moved while it was classifying (`ci.verdict-write-retarget-fence`, #706) — leaving only the sub-round-trip window that no API without compare-and-set can close. The PROTECTED path list additionally covers `CLAUDE.md` and `AGENTS.md` (#751) — they are not prose but the documents DEFINING the completion protocol, the merge-consent convention and the H10 rule, so protecting `.claude/` while the file specifying what it enforces stayed docs-only-exempt was the same self-exemption one directory over; driving the real classify body with a lone `CLAUDE.md` change produced an exemption `success`. `README.md` is deliberately not listed. It also covers `.codex/` (#711), which mirrors `.claude/hooks/` byte for byte including the merge-consent hook — latent while that directory is untracked, live the moment it is tracked; the list stays ENUMERATIVE rather than derived, because a derived rule would have to be evaluated against the very file list being classified. Reading the CURRENT status for input (3) must tolerate `statuses: null`: `GET /commits/{sha}/status` serialises a nil slice as `null`, not `[]`, on a head with no statuses yet, and an `array`-only gate made `read_existing_verdict` `exit 1` and post nothing at all (#751, `ci.workflow-run-body-no-expressions`) — `null` is accepted only when `total_count` is 0, so a body that merely lost its array is still refused. Path predicates are evaluated by COUNTING with `grep -c`, never `| grep -q` (SIGPIPE inversion) and never a here-string (temp-space failure) — see `ci.grep-q-pipefail-inversion`.'
signals: 'forged review-verdict exemption, retarget race against the docs-only classifier, PR base changed mid-run, hijacked Renovate branch, bot exemption on a code change, machine-written success inherited as a verdict, status creator null vs user, never overwrite a human verdict, exemption chain skips docs-only for bots, why is my Renovate PR asking for a verdict, base ref binding on pr-changed-files.sh · paths: `.gitea/workflows/review-verdict.yml`, `scripts/pr-changed-files.sh`, `.claude/hooks/pretooluse-merge-consent.sh`, `scripts/tests/test_pr_changed_files.py` · issues: #698, #697, #672, #663, #649, #632'
mechanics: '`scripts/pr-changed-files.sh <owner> <repo> <pr> <expected-head-sha> <expected-base-ref>` (5 args; a 4-arg call exits 2); workflow env `BASE_REF: ${{ github.event.pull_request.base.ref }}`; `BOT_MANIFESTS` anchored allow-list; short-circuit requires `.creator.login` non-null AND description matching `^Review-verdict:`; `types: [opened, reopened, synchronize, ready_for_review, edited]`'
rule: 'The three inputs the exemption decision rests on must each be bound to something the judged PR cannot mutate. (1) BASE — `scripts/pr-changed-files.sh` takes the expected base BRANCH as a REQUIRED 5th argument and re-reads it before and after paging, because `/pulls/{n}/files` diffs against the PR''s live base and retargeting moves the answer without moving the head sha; the workflow passes `github.event.pull_request.base.ref` from the `pull_request_target` payload, which a retarget cannot rewrite. (2) BOT EXEMPTION — an author match is necessary but never sufficient: `pull_request.user.login` is the PR''s immutable CREATOR while its head is not, so the exemption additionally requires EVERY changed path to be a dependency manifest (`Directory.Packages.props` or `.config/dotnet-tools.json`, and ONLY those — the npm manifests are excluded because `package.json` `scripts` are executed by CI). (3) INHERITED SUCCESS — the never-overwrite short-circuit fires for a `success` only when it is POSITIVELY identified as an APPROVED REVIEWER''s verdict for THIS base, meaning a `.creator.login` that is a member of the workflow''s `H10_REVIEWERS` allow-list (an existing `failure` takes the weaker ATTRIBUTABLE test and needs no membership, because inheriting a rejection can only withhold an exemption while re-deriving one can turn it green on an exempt PR) — non-null was too weak, since any account''s credential satisfies it and `RENOVATE_TOKEN` is one that cannot be scoped down (#742) — AND a `Review-verdict:` description AND, when that description records a base (`(base: …)`, `release.verdict-status-check`), a base matching the PR''s — tested by requiring the description to END with the exact literal `(base: <base>)` and to contain exactly ONE such marker, never by extracting a value (see below); a present-but-different base is rejected, an absent one is not, since verdicts predating that convention carry none; every other shape, including any unrecognised one, is re-derived rather than trusted. The bot and docs-only exemptions are evaluated as INDEPENDENT predicates and the decision made afterwards, never as an `elif` chain. `edited` is in the workflow''s `types:` so a retarget reclassifies — which gives DETECTION, not atomicity: status writes are not serialized, so a stale run can still post over a fresher one. That residual is now FENCED rather than merely tracked (NARROWED, not resolved — a retarget between the fence''s final count and the POST still leaves a PERMANENT forged green, #849) — the job refuses to write at all if the PR''s timeline retarget COUNT moved while it was classifying (`ci.verdict-write-retarget-fence`, #706) — leaving TWO windows, not one: the sub-round-trip window that no API without compare-and-set can close, AND the post-final-count/pre-POST window, which is not sub-round-trip and yields a PERMANENT green because the successor can consume the `edited` event and exit before the stale run posts last (#849). The PROTECTED path list additionally covers `CLAUDE.md` and `AGENTS.md` (#751) — they are not prose but the documents DEFINING the completion protocol, the merge-consent convention and the H10 rule, so protecting `.claude/` while the file specifying what it enforces stayed docs-only-exempt was the same self-exemption one directory over; driving the real classify body with a lone `CLAUDE.md` change produced an exemption `success`. `README.md` is deliberately not listed. It also covers `.codex/` (#711), which mirrors `.claude/hooks/` byte for byte including the merge-consent hook — latent while that directory is untracked, live the moment it is tracked; the list stays ENUMERATIVE rather than derived, because a derived rule would have to be evaluated against the very file list being classified. Reading the CURRENT status for input (3) must tolerate `statuses: null`: `GET /commits/{sha}/status` serialises a nil slice as `null`, not `[]`, on a head with no statuses yet, and an `array`-only gate made `read_existing_verdict` `exit 1` and post nothing at all (#751, `ci.workflow-run-body-no-expressions`) — `null` is accepted only when `total_count` is 0, so a body that merely lost its array is still refused. Path predicates are evaluated by COUNTING with `grep -c`, never `| grep -q` (SIGPIPE inversion) and never a here-string (temp-space failure) — see `ci.grep-q-pipefail-inversion`.'
signals: 'verdict inherited from a bot token, RENOVATE_TOKEN posts a review verdict, who may post an h10 verdict, H10_REVIEWERS allow-list, forged review-verdict exemption, retarget race against the docs-only classifier, PR base changed mid-run, hijacked Renovate branch, bot exemption on a code change, machine-written success inherited as a verdict, status creator null vs user, never overwrite a human verdict, exemption chain skips docs-only for bots, why is my Renovate PR asking for a verdict, base ref binding on pr-changed-files.sh · paths: `.gitea/workflows/review-verdict.yml`, `scripts/pr-changed-files.sh`, `.claude/hooks/pretooluse-merge-consent.sh`, `scripts/tests/test_pr_changed_files.py` · issues: #849, #845, #742, #698, #697, #672, #663, #649, #632'
mechanics: '`scripts/pr-changed-files.sh <owner> <repo> <pr> <expected-head-sha> <expected-base-ref>` (5 args; a 4-arg call exits 2); workflow env `BASE_REF: ${{ github.event.pull_request.base.ref }}`; `BOT_MANIFESTS` anchored allow-list; `H10_REVIEWERS="timothy"` declared as a literal in the classify body (a repo `vars:` entry or secret is settable without a PR); membership by exact POSIX `[ = ]` comparison over word-split entries, never an UNQUOTED right-hand side — `[[ $rv == $ex_creator ]]` makes it a pattern, while a quoted RHS under `[[ ]]` is literal (probed, bash 5.3); POSIX `[ = ]` cannot glob at all, which is why it is used and never `grep -xF` (an API-supplied creator containing a newline reads as several patterns); `read_existing_verdict` sets `ex_attributable` (creator non-null AND `^Review-verdict:` AND base OK) and derives `ex_human` from it by membership; the INHERITANCE short-circuit reads `ex_human`, the LAST-MOMENT RE-READ reads `ex_attributable` plus a change against the state/creator/description triple snapshotted at the first read, and the post-write raced `jq` stays broad on `creator != null`; `types: [opened, reopened, synchronize, ready_for_review, edited]`'
---
`ci.gate-trigger-base-resolved` stopped a PR supplying the gate's own *definition*. This closes the
@@ -36,7 +36,7 @@ than described as fixed. `edited` and re-derivation remain one fix — `edited`
on the existing `success`; re-derivation alone never gets a second run — but together they are
mitigation, not a guarantee.
**Resolved 2026-08-03 (#706), and worth recording that the guarantee finally came from somewhere else
**Narrowed 2026-08-03 (#706) — an earlier heading here said RESOLVED, corrected 2026-08-27 (#849): the fence never re-counts after its final pre-write read, so the post-final-count/pre-POST window remains, and is PERMANENT rather than transient. Worth recording that the narrowing finally came from somewhere else
entirely.** The missing piece was never ordering: `ci.verdict-write-retarget-fence` leaves the runs as
unserialized as they ever were and instead makes a run that was overtaken decline to write, keyed on
the timeline's monotonic retarget COUNT — the one signal the `main → scratch → main` ABA cannot make
@@ -45,7 +45,10 @@ overlap live (probe PR #722, the older run finishing 20s after the newer one sta
non-cancelling concurrency group — the fix this record's residual implied and #706 proposed — was
measured doing nothing at all. The paragraph above stands as written; only its last sentence is
overtaken, and the sub-round-trip window it describes survives, because Gitea's status API has no
compare-and-set.
compare-and-set. **That is not the only window** — see the correction to
`ci.verdict-write-retarget-fence` (2026-08-27, #849): the fence never re-counts after its final
pre-write read, so a retarget landing between that read and the POST leaves a PERMANENT forged green
rather than a transient one, whenever the successor run consumes the `edited` event and exits first.
**Route 2 — a bot ACCOUNT does not attribute the CODE.** `pull_request.user.login` is the PR's
immutable *creator*; its head is not. Push application code onto an open Renovate branch and the PR is
@@ -117,5 +120,127 @@ page-2 rows are assumed raced. It could not have happened on the probe head —
the `exempt=yes` path, which a Route-2 refusal never reaches. That is the blunt-instrument case `#763`
already predicts, now with a live instance of it; see that issue.
**Tightened 2026-08-26 (#742): non-null creator -> an allow-list.** The route-3 test asked "was this
POSTed with a user credential", and *any* account's credential answered yes. `RENOVATE_TOKEN` is a
`write:repository` PAT of the `renovate` bot: unlike `#697`'s registry credential it **cannot** be
scoped off status-write, because Renovate genuinely needs repo write to push branches and open PRs,
and secrets are a per-repo *store* rather than a per-workflow grant — so a workflow can reference it
and POST a `Review-verdict:` success that reads back `creator: renovate` — non-null, and therefore
inheritable. **Inferred from a measurement, not an observed event:** the user-credential-vs-Actions-token
asymmetry is measured, but `renovate` has never actually posted a commit status in this repo — every
status row on all six Renovate-authored PR heads carries `creator: null`. An earlier draft's past tense
("was inherited") described something nobody saw.
Membership in `H10_REVIEWERS` restores the intended set for an inherited `success`: every other
account's, recognised or not, re-derives exactly as an Actions-token status already does. (An existing
`failure` is governed by the weaker attributability test instead — see the state asymmetry below.) The list is a literal in this
base-resolved definition rather than a repo `vars:` entry, because a `vars:` entry is settable without
a PR — i.e. without this gate — while `.gitea/` sits on the PROTECTED path list, so editing the
allow-list cannot ride a docs-only exemption.
**`read_existing_verdict` answers TWO questions and therefore carries TWO flags.** It is called
twice, and the callers want opposite widths. `ex_attributable` — an attributable `Review-verdict:` row
for THIS base, whoever wrote it — is what the LAST-MOMENT RE-READ uses, because that site asks "did a
reviewer post a verdict while we were classifying"; narrowing it does not make it stricter, it makes
the job stop abstaining and post its exemption straight over the row, and the post-write repair does
NOT cover that, being skipped whenever the high-water mark could not be established. `ex_human` is
`ex_attributable` plus membership, and only the INHERITANCE short-circuit uses it. The first draft
gated the single flag and so narrowed both sites; cold review caught it, and
`test_the_MID_RUN_abstain_still_fires_for_a_NON_allowlisted_creator` pins it.
**The two calls must compute a predicate that "changed" is measurable against.** Before the split they
were identical, so anything firing at the second call and not the first had arrived in between — the
mid-run test got that for free. Splitting the flags broke it: a pre-existing row the job declined to
INHERIT is still attributable, so the re-read abstained on the very row the classification had just
decided to overwrite, left the forgery standing and posted nothing at all. The state/creator/
description triple seen at the first read is therefore snapshotted and compared, making "changed"
explicit. A REPLACEMENT counts as a mid-run event, not only an arrival: the combined endpoint returns
one row per context, so a newer POST replaces rather than adds — MEASURED on this instance 2026-08-26, not assumed, because the
comparison made that load-bearing where presence alone had not: two POSTs of context
`probe742/combined-newest` to one sha (`pending`, then `success`) came back as ONE row on
`/commits/{sha}/status`, the newest, and as BOTH rows on `/statuses/{sha}`.
**The allow-list governs `success` ONLY. Treating the two states alike is a fail-open.** Trace an off-list `failure` under a symmetric rule: a real reviewer left off
the literal posts `BLOCKED`; `ex_human=no`, so the short-circuit declines; the PR is docs-only, so the
classifier exempts it; the re-read triple never changed, so the mid-run abstain declines; the row
predates the high-water mark, so the post-write repair cannot see it — and the job posts `success` over
an explicit rejection, reached by the very misconfiguration the allow-list's own diagnostic is about.
The asymmetry costs nothing the allow-list bought: inheriting a `failure` cannot green anything, the
worst a forged one achieves is a stall, and `post-review-verdict.sh` POSTs unconditionally so any human
clears it in one command. Pinned by `test_an_off_list_FAILURE_is_LEFT_ALONE_even_on_an_EXEMPT_PR`,
which uses a DOCS-ONLY file list on purpose — with a code file the job posts `pending` anyway and the
test would pass measuring nothing.
**Why the post-write raced check stays broad — and NOT for the reason first written.** The first draft
justified it as "narrowing it would leave an exemption success standing over a rejection". That is not a checked reason: a genuine reviewer is on `H10_REVIEWERS` by construction, so
membership there would still count every real verdict, and an off-list row is one the job deliberately
overwrote a few lines earlier. What is left once `failure` is handled at the short-circuit is a
NARROWER net than an earlier draft claimed: it covers a misconfigured reviewer's verdict landing inside
the WRITE WINDOW, and nothing else — a verdict already on the head when the job starts sits below the
high-water mark and is structurally invisible to it. Saying it is "the last net before a green stands"
overstated that, and the sentence is corrected rather than kept. It stays broad because within its
window the errors are not symmetric: a repair to `pending` is recoverable by re-posting, a
wrongly-standing `success` on an unreviewed head is not. The cost is stated at the site rather than
implied: any verdict-shaped row landing inside that window trips the STICKY `REPAIR_DESC` sentinel and
costs that head its exemption until a human clears it.
Both directions are mutation-proven against the shipped file — reverting the membership clause reddens
`test_a_verdict_shaped_SUCCESS_from_a_NON_allowlisted_account_is_RE_DERIVED` and
`test_an_account_that_merely_RESEMBLES_an_allowlisted_login_is_RE_DERIVED`; pointing the mid-run
abstain back at `ex_human`, or dropping the changed-row comparison, reddens the mid-run and
inheritance cases respectively. Counts are deliberately not quoted: `test_pr_changed_files.py` is
graded `PROOF | NONE`, so nothing re-executes a number written here and one added `parametrize` case
would falsify it silently.
**A guard being byte-identical does not make its REACHABILITY unchanged — the post-write residuals
are #849, and this change makes them reachable from a new class.** Before this change, an attributable
`success` from ANY account short-circuited and the job wrote NOTHING. Re-deriving an off-list `success`
is the POINT of the change, and it turns "no write" into "a write" — which is what reaches the paths
where post-write verification cannot verify. The guards themselves are untouched here; their
reachability is not, and "pre-existing" was the wrong answer to that.
**Two of them were fixed on this branch and then WITHDRAWN, which is the more useful record.** The fix
withheld the exemption when no high-water mark could be established, and repaired to the sentinel when
the post-write history was unreadable. Re-review found both wanting, on grounds that generalise:
- The withheld exemption wrote a GENERIC `pending`, and a generic `pending` is exactly what a later run
re-derives into `success`. It did not close the burial route, it moved which run greens it. Closing it
properly needs a distinct sticky "unverified write" sentinel, which is a new state in a state machine
that already has three.
- That `pending` also has NO RETRY PATH. The workflow triggers only on `pull_request_target` types —
no schedule, no `workflow_dispatch` — so a transient API failure on a PR's LAST event leaves an
exempt PR stalled until a human nudges it. Trading a race that needs BOTH a read failure and a
reviewer posting inside the write window, for a stall that needs only the read failure, is not
obviously the safe direction, and it was described as a "one-run cost" when it is not.
So the whole of post-write verification stays in #849, where it can be designed once: every write
verified when a mark exists, a sticky sentinel when it does not, and a CHAINED test feeding run N's
real output into run N+1. Two lines inside a provenance change was the wrong size for it — the attempt
is recorded because the next reader will otherwise re-attempt it the same way.
**A coupling this record does NOT assert, tracked as #845 instead.** `post-review-verdict.sh` posts with
whatever account owns `ETV_GITEA_TOKEN`/`ETV_GITEA_BASICAUTH` and never checks whose it is. If that
ever stops being an allow-listed account, every verdict silently stops being inheritable and each
later event re-derives it — to `pending` on a PR that needs a verdict, or to an exemption `success` on
a docs-only or Renovate-manifest one, which is the quieter and worse half. Either way the verdict is
gone, and the only diagnostic is a line in a job log.
Correct today — verified live 2026-08-26, reproduce with `GET /api/v1/user` (login `timothy`) and
`GET /api/v1/admin/users?limit=50` (exactly `renovate`, `timothy`) — but nothing keeps it correct
(#845). The job DOES name the creator and the allow-list whenever it declines to inherit — but in the
WORKFLOW RUN, while the mistake is made at the terminal running `post-review-verdict.sh`, which
reports success either way. That gap is what #845 is about, and it is why a louder annotation was not
the answer: an earlier draft added a `::warning::` alongside that line, and it was withdrawn after
producing three defects in three rounds (a message that contradicted itself for an allow-listed
creator, an unescaped API value interpolated into a workflow command, and a test asserting its absence
on a path that exits two guards earlier and so could never fail). The signal has to reach the WRITER,
not be repeated more loudly to the reader.
**What #742 does NOT close, restated because the allow-list invites the wrong reading.** An
allow-listed collaborator's own write-scoped token can still POST a verdict nobody formed. Branch
protection binds the context NAME, not its issuer, and Gitea offers no way to restrict who may post a
context. `h10` remains a process guard against mistakes and drift, not a security boundary against
push access. The advisory hook `.claude/hooks/pretooluse-merge-consent.sh` checks no identity at all
and is deliberately left that way: it runs as the operator, on the operator's machine, and its
strictest outcome is a human prompt.
**Separate defect found reviewing this change:** `ci.grep-q-pipefail-inversion` — a pre-existing
SIGPIPE inversion that let a large PR skip the `PROTECTED` guard entirely. Fixed in the same PR.
@@ -5,7 +5,7 @@ status: active
since: '2026-07-28'
supersedes: none
superseded-by: none
rule: 'The workflow that writes the branch-protection-required `review-verdict/h10` status triggers on `pull_request_target` with `branches: [main]`, never on plain `pull_request`. Gitea resolves a `pull_request` workflow DEFINITION from the PR''s own head commit, so under that trigger a PR editing `.gitea/workflows/review-verdict.yml` ran its own rewritten copy and could post `h10=success` for itself; `pull_request_target` resolves the definition from the base instead. The `branches: [main]` filter is part of the rule, not a refinement of it: base resolution only relocates the rewrite from the head to the base, so without the filter a PR opened into an attacker-pushed base branch runs that branch''s gate. `pull_request_target` is safe HERE only because this job never checks out or executes head-supplied code — it checks out `base.sha` and runs only that tree''s scripts (`ci.shared-pr-file-enumeration`); reintroducing a head checkout under this trigger would be worse than the bug it fixed. This closes the rewrite route through THIS workflow and does NOT close the class: Gitea injects a write-capable `GITEA_TOKEN` into EVERY job, so any ref-resolved workflow — and a collaborator''s own API token, since branch protection binds the context and not its issuer — can still forge `review-verdict/h10`. The credential half is now RESOLVED in `ci.actions-credential-scoping` (#697): CI''s registry secret was the ADMIN account''s basic auth and is now a PAT that cannot post a status, which removes the ADMIN escalation and that credential''s route (a user credential''s forgery carries a real `creator` and is inherited as a human verdict; an Actions job''s carries `creator: null` and is re-derived — but do NOT read that asymmetry as protection: re-derivation fires only on the trigger''s `types`, and posting a status is not one of them, so a POST timed after the last PR event simply stands). It does not remove EVERY route: `RENOVATE_TOKEN` is a `write:repository` bot PAT in the same secret store, reachable by any PR-added workflow. The injected token stays write-capable until Gitea >=1.26 with a Restricted default (server-management#714), and a collaborator''s own token remains unfixable; the exemption path has its own separate defects in #698.'
rule: 'The workflow that writes the branch-protection-required `review-verdict/h10` status triggers on `pull_request_target` with `branches: [main]`, never on plain `pull_request`. Gitea resolves a `pull_request` workflow DEFINITION from the PR''s own head commit, so under that trigger a PR editing `.gitea/workflows/review-verdict.yml` ran its own rewritten copy and could post `h10=success` for itself; `pull_request_target` resolves the definition from the base instead. The `branches: [main]` filter is part of the rule, not a refinement of it: base resolution only relocates the rewrite from the head to the base, so without the filter a PR opened into an attacker-pushed base branch runs that branch''s gate. `pull_request_target` is safe HERE only because this job never checks out or executes head-supplied code — it checks out `base.sha` and runs only that tree''s scripts (`ci.shared-pr-file-enumeration`); reintroducing a head checkout under this trigger would be worse than the bug it fixed. This closes the rewrite route through THIS workflow and does NOT close the class: Gitea injects a write-capable `GITEA_TOKEN` into EVERY job, so any ref-resolved workflow — and a collaborator''s own API token, since branch protection binds the context and not its issuer — can still forge `review-verdict/h10`. The credential half is now RESOLVED in `ci.actions-credential-scoping` (#697): CI''s registry secret was the ADMIN account''s basic auth and is now a PAT that cannot post a status, which removes the ADMIN escalation and that credential''s route (an ALLOW-LISTED user credential''s forgery carries a matching `creator` and is inherited as a verdict; an Actions job''s carries `creator: null` and is re-derived, as since #742 is every account outside `H10_REVIEWERS` — but do NOT read that asymmetry as protection: re-derivation fires only on the trigger''s `types`, and posting a status is not one of them, so a POST timed after the last PR event simply stands). It does not remove EVERY route: `RENOVATE_TOKEN` is a `write:repository` bot PAT in the same secret store, reachable by any PR-added workflow. The injected token stays write-capable until Gitea >=1.26 with a Restricted default (server-management#714), and a collaborator''s own token remains unfixable; the exemption path has its own separate defects in #698.'
signals: 'workflow definition resolved from head, PR rewrites the gate that judges it, self-approve a required status check, pull_request_target vs pull_request, gate trigger branches filter, attacker-supplied base branch, how to test a change to review-verdict.yml, workflow not exercised by its own PR, gate edit goes live only on merge, required_approvals 0 does not bind an author, forged commit status inherited by sha · paths: `.gitea/workflows/review-verdict.yml`, `scripts/tests/test_pr_changed_files.py` · issues: #672, #663, #649, #622'
mechanics: '`on: pull_request_target: {branches: [main], types: [opened, reopened, synchronize, ready_for_review, edited]}` (`edited` added by `ci.exemption-provenance` so a retarget reclassifies); asserted by `test_the_workflow_trigger_is_pull_request_TARGET_scoped_to_main` in `scripts/tests/test_pr_changed_files.py`; the job''s own context is renamed to `... (pull_request_target)` and must stay OUT of branch protection''s required list'
---
@@ -56,8 +56,11 @@ read/**write**, so head-resolved, `push`-triggered and `workflow_dispatch` workf
route with no workflow at all — branch protection binds the *context*, not its issuer. Full inventory
in `#697`, whose credential half is resolved in `ci.actions-credential-scoping` — the registry secret
no longer carries status-write. That does NOT leave the workflow routes provenance-free: any
PR-added workflow can reference `RENOVATE_TOKEN`, a `write:repository` bot PAT in the same store,
whose status carries a real creator and IS inherited (`#742`). The exemption path's
PR-added workflow can reference `RENOVATE_TOKEN`, a `write:repository` bot PAT in the same store. Its
status carries a real creator, and until `#742` that alone made it INHERITED as a verdict; the
provenance test is now membership in `H10_REVIEWERS`, so a `renovate`-posted verdict is re-derived
like an Actions-token one. The token still writes statuses — what it lost is durability, not the
ability to POST. The exemption path's
own defects are `#698`. No in-repository test can establish
status-authority isolation: the sibling guard added here catches only plain-text naming of the
context.
@@ -5,7 +5,7 @@ status: active
since: '2026-08-03'
supersedes: none
superseded-by: none
rule: 'The `review-verdict/h10` job counts `change_target_branch` events on the PR''s issue timeline at run start and again immediately before its POST, and writes NOTHING if the count moved. The COUNT is the key because the branch NAME is ABA-vulnerable — `main -> S -> main` reads `main` at both ends, which is how #698 route 1 obtained a forged exemption — while the event count is monotonic and cannot alias. Abstaining is a handoff, not a stall, and that is the property the design rests on: every retarget fires `edited`, which is in this workflow''s `types:`, so the event that makes a run abstain has already queued a successor whose window opens after it; the induction terminates when retargeting stops and the last run writes the final answer. `updated_at` was REJECTED as the key because it also moves for comments and labels, which fire none of this workflow''s `types:` — a run could abstain with no successor coming, which is a real stall. The count is trusted only when paging reached a validated EMPTY page; an untrusted count (unreadable page, non-array body, non-numeric length, page cap hit) blocks the exemption `success` ONLY and still lets `pending` through, because `pending` cannot turn an unreviewed head green while withholding it would strand ordinary PRs for no safety gain. SEPARATELY, and for the human-verdict race the fence does nothing about: after posting an exemption `success` the job re-reads `/statuses/{sha}` and, if a human `Review-verdict:` row appeared with an id ABOVE a high-water mark taken just before the POST, overwrites its own status with `pending` and logs an error. The repair is `pending`, NEVER a copy of the human''s state, since re-posting their `failure` under the machine credential would attribute a human verdict to the job; its description is a SENTINEL that the classification refuses to grant an exemption over AND re-writes verbatim on every later run, so the block is a FIXED POINT rather than decaying — writing the generic `pending` description there instead erases the marker and the exemption simply returns one event later. The mark is captured BEFORE the last-moment re-read, not merely before the POST — a later mark leaves a multi-round-trip blind gap in which a verdict is neither seen by the re-read nor repaired afterwards. The id comparison is load-bearing: a mere presence test would fire forever on a base-mismatched verdict that `read_existing_verdict` deliberately declines to honour, deadlocking that PR''s exemption permanently. Finally, a run whose last-moment re-read finds a sentinel it did not see at its FIRST read ABSTAINS instead of posting: that can only mean an overlapping run repaired a raced verdict mid-flight, and this run''s `success` — frozen at classification time, with the human row below its own mark, so neither the fence nor the post-write check would catch it — would otherwise bury the rejection. That is the one path in this design that failed toward SUCCESS rather than `pending`. The post-write check counts TWO row shapes above the mark, not one — a human `Review-verdict:` row AND a machine sentinel — because with two overlapping runs the human row can sit BELOW the second run''s mark while the first masks it and only then writes the sentinel, leaving the second to post its own `success` on top; counting the sentinel converges both runs on the fixed point instead.'
rule: 'The `review-verdict/h10` job counts `change_target_branch` events on the PR''s issue timeline at run start and again immediately before its POST, and writes NOTHING if the count moved. The COUNT is the key because the branch NAME is ABA-vulnerable — `main -> S -> main` reads `main` at both ends, which is how #698 route 1 obtained a forged exemption — while the event count is monotonic and cannot alias. This NARROWS the residual, it does not resolve it — a retarget between the FINAL pre-write count and the POST still yields a PERMANENT forged green, because the successor run can consume the `edited` event and exit before the stale run posts last (corrected 2026-08-27, #849). Abstaining is a handoff, not a stall, and that is the property the design rests on — for a run that ABSTAINS; it says nothing about one that already passed its final count and then posts (see the residual, corrected #849): every retarget fires `edited`, which is in this workflow''s `types:`, so the event that makes a run abstain has already queued a successor whose window opens after it; the induction terminates when retargeting stops — but ONLY over runs that ABSTAIN. A run that already passed its final count is outside it: it writes whenever it gets there, so the run that writes LAST is not necessarily the one that classified last, and that is the permanent residual (#849). `updated_at` was REJECTED as the key because it also moves for comments and labels, which fire none of this workflow''s `types:` — a run could abstain with no successor coming, which is a real stall. The count is trusted only when paging reached a validated EMPTY page; an untrusted count (unreadable page, non-array body, non-numeric length, page cap hit) blocks the exemption `success` ONLY and still lets `pending` through, because `pending` blocks the merge immediately while withholding it would strand ordinary PRs whenever the timeline is unreadable — the right trade, but NOT a free one ("for no safety gain" retracted 2026-08-27): a GENERIC `pending` masks a rejection landing in its own write window, post-write verification does not run for it, and a later run re-derives it into an exemption `success` (#849). SEPARATELY, and for the human-verdict race the fence does nothing about: after posting an exemption `success` the job re-reads `/statuses/{sha}` and, if a human `Review-verdict:` row appeared with an id ABOVE a high-water mark taken just before the POST, overwrites its own status with `pending` and logs an error. The repair is `pending`, NEVER a copy of the human''s state, since re-posting their `failure` under the machine credential would attribute a human verdict to the job; its description is a SENTINEL that the classification refuses to grant an exemption over AND re-writes verbatim on every later run, so the block is a FIXED POINT rather than decaying — writing the generic `pending` description there instead erases the marker and the exemption simply returns one event later. The mark is captured BEFORE the last-moment re-read, not merely before the POST — a later mark leaves a multi-round-trip blind gap in which a verdict is neither seen by the re-read nor repaired afterwards. The id comparison is load-bearing: a mere presence test would fire forever on a base-mismatched verdict that `read_existing_verdict` deliberately declines to honour, deadlocking that PR''s exemption permanently. Finally, a run whose last-moment re-read finds a sentinel it did not see at its FIRST read ABSTAINS instead of posting: that can only mean an overlapping run repaired a raced verdict mid-flight, and this run''s `success` — frozen at classification time, with the human row below its own mark, so neither the fence nor the post-write check would catch it — would otherwise bury the rejection. That is the one path in this design that failed toward SUCCESS rather than `pending`. The post-write check counts TWO row shapes above the mark, not one — a human `Review-verdict:` row AND a machine sentinel — because with two overlapping runs the human row can sit BELOW the second run''s mark while the first masks it and only then writes the sentinel, leaving the second to post its own `success` on top; counting the sentinel converges both runs on the fixed point instead.'
signals: 'stale review-verdict run overwrites a fresher one, retarget ABA against the docs-only classifier, concurrency group does not serialize pull_request_target, gitea auto-cancel push vs pull_request_target, forged exemption restored after reclassification, human BLOCKED silently turned green, post-write status verification, change_target_branch timeline count, why does my PR post no verdict status after a retarget · paths: `.gitea/workflows/review-verdict.yml`, `scripts/tests/test_pr_changed_files.py` · issues: #706, #698, #672, #663, #622'
mechanics: '`count_retargets()` pages `GET /repos/{repo}/issues/{pr}/timeline?limit=50&page=N` (cap 20) setting `rt_count`/`rt_ok`, trusted only on a validated empty page, which is a page of EITHER `null` (what this endpoint really returns past the end) or `[]` — an `array`-only type gate read the real terminator as unreadable and withheld every exemption (#751); `retargets_before`/`retargets_before_ok` captured before enumeration, re-counted immediately before the POST; `max_id_before` from `GET /repos/{repo}/statuses/{sha}` (a BARE ARRAY, unlike the combined `/commits/{sha}/status` object); repair POST is `pending`; tests `test_a_RETARGET_DURING_the_run_posts_NOTHING`, `test_a_PR_retargeted_BEFORE_the_run_but_QUIET_during_it_is_STILL_exempt`, `test_an_UNTRUSTED_retarget_count_withholds_the_EXEMPTION`, `test_an_UNTRUSTED_retarget_count_STILL_LETS_PENDING_THROUGH`, `test_a_human_verdict_landing_AFTER_the_POST_is_repaired_to_pending`, `test_a_PRE_EXISTING_human_row_does_NOT_trigger_a_repair`'
---
@@ -58,9 +58,20 @@ marker, so the exemption returned two events later instead of one. Only a re-pos
## What is NOT closed
1. A retarget between the final timeline read and the POST. Gitea's status API has no conditional
write, so without compare-and-set this cannot reach zero. The magnitude changed: a *permanent*
forged green became a *transient* one of about one round-trip, and that retarget still fires
`edited`, so a later run re-derives it.
write, so without compare-and-set this cannot reach zero.
**The "transient" claim here was WRONG and is corrected (2026-08-27, found by cross-family review
of ersatztv#742; tracked as #849).** It read: a permanent forged green became a transient one of
about one round-trip, because the retarget fires `edited` and a later run re-derives it. That
assumes the successor run finishes LAST. It need not. Ordering: run S classifies against scratch
base S′ and passes its final fence; the PR is retargeted back to `main`; successor M starts,
sees the base-matching `failure`, short-circuits and writes NOTHING; **S then resumes and posts
its stale `success` last**. The `edited` event has already been consumed by M, so no event
remains — the forged green is permanent, not transient. The fence narrows *writing while
overtaken*; it does nothing about *being overtaken after the final pre-write count*, because it
never re-counts
after the POST. That is the shape of the fix (#849), and until it lands this residual is a
permanent green, stated as such.
2. The repair is itself a read-then-write and can be raced; it fails toward `pending`. A transport
failure on its POST is retried once then fails the job loudly. A human re-posting a BASE-MISMATCHED
verdict after a repair does bury the sentinel — that needs a user credential, so it is #697's.
@@ -185,8 +185,12 @@ described as one:
`docker-build.yml` demonstrably could, and must stay head-resolved because it builds the PR's own
code — so #697 scoped its credential instead (`ci.actions-credential-scoping`), leaving AT LEAST
these: the injected `GITEA_TOKEN` (posts with `creator: null`), `RENOVATE_TOKEN` (a
`write:repository` bot PAT in the same secret store, so it posts with a real creator and IS
inherited, #742), a collaborator's own token, and the `v*` tag push — which matters less for
`write:repository` bot PAT in the same secret store, so it posts with a real creator — it is no
longer *inherited* as a verdict, since #742 replaced the "non-null creator" test with membership in
the workflow's `H10_REVIEWERS` allow-list and `renovate` is not on it, but it can still overwrite
the status), an ALLOW-LISTED collaborator's own token — which #742 deliberately does not address,
because branch protection binds the context NAME rather than its issuer and Gitea offers no way to
restrict who may post a context — and the `v*` tag push — which matters less for
forging this status than for what else it does: `docker-build.yml` publishes `:prod` from a tagged
ref, and a tag may point at any commit, so it ships a prod image with no PR, review or status.
None of which used to be even required — direct pushes to `main` were server-side permitted, so
+488 -9
View File
@@ -1061,8 +1061,12 @@ if "/statuses/" in url:
seen = int(ctr.read_text()) if ctr.exists() else 0
ctr.write_text(str(seen + 1))
if seen > 0:
# Configurable creator (ersatztv#742). The RACED test must stay broader than the
# INHERITANCE test: a verdict from an account off `$H10_REVIEWERS` still counts as
# "something human landed while we were writing", because narrowing it here would leave
# the exemption green over that row instead of repairing to pending.
rows = [{"id": 5000, "context": "review-verdict/h10", "status": "failure",
"creator": {"login": "timothy"},
"creator": {"login": os.environ.get("STUB_HISTORY_CREATOR", "timothy")},
"description": "Review-verdict: BLOCKED @ a9e3e23 (base: main)"}]
elif mode == "sentinel-after-post":
# Another overlapping run repaired mid-flight: its SENTINEL lands above this run's mark, while
@@ -1140,12 +1144,48 @@ if "/status" in url:
n = int(ctr.read_text()) if ctr.exists() else 0
ctr.write_text(str(n + 1))
if n + 1 < nth:
# STUB_PRE_ROW makes the earlier reads return a PRE-EXISTING row instead of an empty
# head (ersatztv#742). Without it every mid-run test starts from "no status at all", so
# only the ARRIVAL case is exercised and a presence-only abstain (`[ -z "$pre_state" ]`)
# is indistinguishable from a changed-row abstain. The REPLACEMENT case is the one that
# co-occurs with #742's own scenario: the head already carries an off-list verdict — that
# is WHY the job is re-deriving — and a real reviewer posts over it mid-run.
pre = os.environ.get("STUB_PRE_ROW", "")
if pre:
pre_creator, pre_state, pre_desc = pre.split("|", 2)
# DECOY CONTEXT + `total_count`, matching the shape the `existing:` modes model and the
# server actually returns. Without a decoy a dropped `select(.context == $c)` is
# invisible; without `total_count` the emptiness cross-check is never exercised.
rows = [
{"context": "ci/decoy", "status": "pending", "creator": None,
"description": "unrelated"},
{"context": "review-verdict/h10", "status": pre_state,
"creator": ({"login": pre_creator} if pre_creator else None),
"description": pre_desc},
]
print(json.dumps({"state": "pending", "total_count": len(rows), "statuses": rows}))
sys.exit(0)
print(empty_statuses())
sys.exit(0)
print(json.dumps({"statuses": [
{"context": "review-verdict/h10", "status": "failure",
"creator": {"login": "timothy"},
"description": "Review-verdict: BLOCKED @ a9e3e23 (base: main)"}]}))
# Configurable creator (ersatztv#742). This site asks "did anything human land while we were
# classifying", NOT "may this be inherited", so it must stay broad: an off-allow-list account
# posting BLOCKED here still has to make the job abstain.
# STUB_MIDRUN_ROW overrides the whole row, so a test can make the mid-run row differ from
# STUB_PRE_ROW in exactly ONE field of the state/creator/description triple. Without that,
# every mid-run test moves all three at once and no single clause of the comparison is pinned.
mid = os.environ.get("STUB_MIDRUN_ROW", "")
if mid:
mid_creator, mid_state, mid_desc = mid.split("|", 2)
else:
mid_creator = os.environ.get("STUB_MIDRUN_CREATOR", "timothy")
mid_state, mid_desc = "failure", "Review-verdict: BLOCKED @ a9e3e23 (base: main)"
mid_rows = [
{"context": "ci/decoy", "status": "pending", "creator": None, "description": "unrelated"},
{"context": "review-verdict/h10", "status": mid_state,
"creator": ({"login": mid_creator} if mid_creator else None),
"description": mid_desc},
]
print(json.dumps({"state": "pending", "total_count": len(mid_rows), "statuses": mid_rows}))
sys.exit(0)
if mode.startswith("sentinel-appears-on-read:"):
# A repair sentinel written by ANOTHER, overlapping run between this job's first read and its
@@ -1228,6 +1268,11 @@ def _run_classify(
status_desc: str = "Review-verdict: MERGEABLE @ a9e3e23 (base: main)",
timeline_mode: str = "none",
history_mode: str = "none",
history_creator: str = "timothy",
midrun_creator: str = "timothy",
pre_row: str = "",
midrun_row: str = "",
reviewers: str | None = None,
timeline_terminator: str = "null",
status_empty_shape: str = "null",
):
@@ -1265,6 +1310,10 @@ def _run_classify(
env["STUB_TIMELINE_TERMINATOR"] = timeline_terminator
env["STUB_STATUS_EMPTY_SHAPE"] = status_empty_shape
env["STUB_HISTORY_MODE"] = history_mode
env["STUB_HISTORY_CREATOR"] = history_creator
env["STUB_MIDRUN_CREATOR"] = midrun_creator
env["STUB_PRE_ROW"] = pre_row
env["STUB_MIDRUN_ROW"] = midrun_row
env.update(
{
"GITEA_TOKEN": "stub",
@@ -1284,7 +1333,20 @@ def _run_classify(
)
script = tmp_path / "step.sh"
script.write_text(_classify_step()["run"])
body = _classify_step()["run"]
if reviewers is not None:
# Substitute the allow-list into the REAL step body so the shipped membership loop runs
# against a multi-entry value. Every other test runs the singleton `timothy`, under which a
# loop that can only ever match its LAST entry is indistinguishable from a correct one — and
# the workflow's own diagnostic tells operators to add a second entry.
body, n = re.subn(
r'^(\s*)H10_REVIEWERS="[^"]*"$',
lambda m: f'{m.group(1)}H10_REVIEWERS="{reviewers}"',
body,
flags=re.MULTILINE,
)
assert n == 1, f"expected exactly one H10_REVIEWERS assignment to override, substituted {n}"
script.write_text(body)
r = subprocess.run(["bash", str(script)], cwd=tmp_path, env=env, capture_output=True, text=True)
# Assert the WIRING, not only the classification. The stub accepts every POST, so a status aimed
# at the wrong endpoint, sha, host or repo would otherwise leave these tests green while the real
@@ -1606,7 +1668,8 @@ def test_a_BOT_pr_touching_a_protected_path_is_still_NOT_exempt(tmp_path):
assert posted["state"] == "pending"
# --- Route 3: an inherited `success` is re-derived unless it is an attributable human verdict ----
# --- Route 3: an inherited `success` is re-derived unless it is an ALLOW-LISTED reviewer's verdict
# (ersatztv#742; `attributable` alone is the weaker test that governs an inherited `failure`) -------
#
# The short-circuit used to exit on ANY existing `success`, so an exemption this job wrote was
# indistinguishable from a verdict a human wrote. Obtained once, a forged success was thereafter
@@ -1668,6 +1731,410 @@ def test_a_success_with_a_creator_but_an_EXEMPT_description_is_re_derived(tmp_pa
assert posted["state"] == "pending"
# --- ersatztv#742: WHOSE creator counts -------------------------------------------------------
#
# "Non-null creator" proved only that a status was POSTed with SOME user credential. `RENOVATE_TOKEN`
# is a `write:repository` PAT of the `renovate` bot; it cannot be scoped down the way #697 scoped the
# registry credential, and secrets are a per-repo STORE, so any workflow can reference it. A status
# POSTed with it reads back `creator: renovate` — non-null, and therefore inherited as a verdict.
@pytest.mark.parametrize("creator", ["renovate", "someone-else"])
def test_a_verdict_shaped_SUCCESS_from_a_NON_allowlisted_account_is_RE_DERIVED(tmp_path, creator):
"""The route this issue closes. Everything else about the row is a perfect verdict: a real
creator, a `Review-verdict:` description recording THIS base. Only the account is wrong.
Paired with a C# file so re-deriving is visible as a downgrade to `pending`; inheriting would
leave the forgery standing on every later run, which is the property that made route 3 durable.
`success` ONLY — see the `failure` test below, which pins the opposite behaviour deliberately.
"""
posted, r = _run_classify(
tmp_path,
_emitting("ErsatzTV/Program.cs"),
status_mode="existing:success",
status_creator=creator,
status_desc="Review-verdict: MERGEABLE @ a9e3e23 (base: main)",
)
assert posted is not None, (
f"a verdict-shaped success written by '{creator}' was inherited — non-null creator is being "
f"read as 'a reviewer wrote this'. Log:\n{r.stdout[-900:]}"
)
assert posted["state"] == "pending"
# THE DIAGNOSTIC IS PART OF THE CONTRACT, not decoration. It is the only thing that says so when
# a reviewer has been added to the repo and forgotten from `H10_REVIEWERS`, and a tidy-up that
# drops any of its three values must redden something. Asserted on the LOG LINE the job always
# reaches, not on a separate annotation: the annotation that used to carry this was withdrawn
# after cold review measured that deleting it left the whole suite green.
assert creator in r.stdout, (
f"the diagnostic does not name the account whose verdict was discarded. Log:\n{r.stdout[-1200:]}"
)
# The VALUE, not the word. An earlier draft asserted `"H10_REVIEWERS" in stdout`, which the
# remediation sentence satisfies on its own — so deleting the allow-list from the diagnostic left
# it green. Derived from the shipped literal rather than restated here.
assert f"allow-list='{_h10_reviewers_literal()}'" in r.stdout, (
"the diagnostic does not print the accepted set, so a reviewer left off it cannot tell why "
f"their verdict was re-derived. Log:\n{r.stdout[-1200:]}"
)
assert "add them to H10_REVIEWERS" in r.stdout, (
f"the diagnostic does not say how to fix it. Log:\n{r.stdout[-1200:]}"
)
@pytest.mark.parametrize("creator", ["renovate", "someone-else"])
def test_an_off_list_FAILURE_is_LEFT_ALONE_even_on_an_EXEMPT_PR(tmp_path, creator):
"""THE FAIL-OPEN A SYMMETRIC ALLOW-LIST SHIPS, and the reason `failure` is treated differently.
Scenario: a real reviewer (`alice`) was added to the repo and forgotten from `H10_REVIEWERS`.
They post `Review-verdict: BLOCKED`. The PR is docs-only, so it is EXEMPT. If the allow-list
governed `failure` too, every guard downstream declines in turn — the short-circuit
(`ex_human=no`), the mid-run abstain (the triple never changed), and the post-write repair (the
row predates the high-water mark) — and the job posts an exemption `success` over an explicit
human rejection.
Deliberately paired with a DOCS-ONLY file list: with a C# file the job would post `pending`
anyway and the test would pass for the wrong reason, measuring nothing.
The asymmetry costs nothing #742 bought. An inherited `failure` cannot green anything; the worst
a forged one achieves is a stall, and `post-review-verdict.sh` POSTs unconditionally, so any
human clears it in one command.
"""
posted, r = _run_classify(
tmp_path,
_emitting("docs/a.md"),
status_mode="existing:failure",
status_creator=creator,
status_desc="Review-verdict: BLOCKED @ a9e3e23 (base: main)",
)
assert r.returncode == 0, r.stderr
assert posted is None, (
f"an exemption was posted over a BLOCKED verdict from '{creator}' — the allow-list is "
f"governing `failure`, which turns a rejection green. Posted: {posted}. "
f"Log:\n{r.stdout[-900:]}"
)
@pytest.mark.parametrize("creator", ["timothy2", "xtimothy", "TIMOTHY", "timoth", " timothy"])
def test_an_account_that_merely_RESEMBLES_an_allowlisted_login_is_RE_DERIVED(tmp_path, creator):
"""Membership must be whole-value equality, not a substring, prefix or case-folded test.
Gitea logins are first-come, so `timothy2` is registerable by anyone; a containment test would
hand them the gate. `TIMOTHY` is the case arm — Gitea logins are case-insensitive for LOGIN but
the API returns the stored form, and accepting a fold would widen the set to whatever Gitea
happens to consider equal rather than to what this file lists.
"""
posted, _ = _run_classify(
tmp_path,
_emitting("ErsatzTV/Program.cs"),
status_mode="existing:success",
status_creator=creator,
status_desc="Review-verdict: MERGEABLE @ a9e3e23 (base: main)",
)
assert posted is not None, f"'{creator}' was accepted as the allow-listed reviewer"
assert posted["state"] == "pending"
def test_the_RACED_verdict_check_still_counts_a_NON_allowlisted_creator(tmp_path):
"""THE POLARITY TEST, and the reason the allow-list was not applied everywhere `creator` is read.
NOT for the obvious reason, which cold review showed to be unchecked: a genuine reviewer is on
`$H10_REVIEWERS` by construction, so membership here would still count every real verdict, and an
off-list row is one the job deliberately overwrote a few lines earlier.
The reason is the MISCONFIGURATION case — a second human account added to the repo and forgotten
from the literal — which is the only way an off-list row is ever a real verdict. This is the last
net before a green stands, and the errors are not symmetric: a repair to `pending` is recoverable
by re-posting, a wrongly-standing `success` on an unreviewed head is not. The cost of being broad
is real and is documented at the site: any verdict-shaped row landing in the write window trips
the sticky sentinel and costs that head its exemption until a human clears it.
"""
posted, r = _run_classify(
tmp_path,
_emitting("docs/a.md"),
history_mode="human-after-post",
history_creator="renovate",
)
assert r.returncode == 0, r.stderr
seq = _posted_sequence(tmp_path)
assert len(seq) == 2, (
"the exemption was not repaired after a non-allow-listed account raced the write — the "
f"allow-list has been applied to the raced check too. Posts: {seq}. Log:\n{r.stdout[-900:]}"
)
assert seq[0]["state"] == "success"
assert seq[1]["state"] == "pending"
assert posted is not None and posted["state"] == "pending"
def test_the_MID_RUN_abstain_still_fires_for_a_NON_allowlisted_creator(tmp_path):
"""The SECOND mirror-image site, and the one the first draft of #742 got wrong.
`read_existing_verdict` is called twice. The first call decides "may this be INHERITED" and is
correctly allow-list-gated. The second — the last-moment re-read immediately before the POST —
asks the OTHER question: "did a reviewer post a verdict while we were classifying?" Narrowing
that one does not make it stricter, it makes the job stop abstaining: it posts its exemption
`success` straight over the row instead.
The post-write repair usually catches that, but it is skipped entirely whenever the high-water
mark could not be established (`max_id_before=-1`, a `::warning::` and nothing more), so the
green would stand over a `BLOCKED`. Fail-toward-SUCCESS, at the exact site the design says must
stay broad.
"""
posted, r = _run_classify(
tmp_path,
_emitting("docs/a.md"),
status_mode="appears-on-read:2",
midrun_creator="renovate",
)
assert r.returncode == 0, r.stderr
assert posted is None, (
"the job posted over a verdict that landed mid-run from a non-allow-listed account — the "
f"allow-list has been applied to the mid-run abstain as well. Posted: {posted}. "
f"Log:\n{r.stdout[-900:]}"
)
def test_a_verdict_REPLACING_a_pre_existing_row_mid_run_still_makes_the_job_ABSTAIN(tmp_path):
"""The REPLACEMENT half of the mid-run abstain, and the clause a presence test cannot reach.
The abstain used to be free: both reads computed an identical predicate, so "fired at the second
and not the first" meant "arrived in between". Splitting `ex_human` from `ex_attributable` broke
that, and the repair is an explicit comparison against the state/creator/description triple
snapshotted at the first read. `[ -z "$pre_state" ]` — abstain only when the first read saw
NOTHING — is the plausible wrong version, and every other mid-run test starts from an empty head,
so nothing distinguishes the two.
This is the ordering that actually co-occurs with #742: the head ALREADY carries an off-list
`Review-verdict:` success (which is why the job is re-deriving at all), and a real reviewer posts
`BLOCKED` over it while the job classifies. Under the presence-only version `pre_state` is
non-empty, the abstain is skipped, and the docs-only exemption is posted straight over the
rejection — with the post-write repair blind to it whenever the high-water mark is unestablished.
"""
posted, r = _run_classify(
tmp_path,
_emitting("docs/a.md"),
status_mode="appears-on-read:2",
pre_row="renovate|success|Review-verdict: MERGEABLE @ a9e3e23 (base: main)",
midrun_creator="timothy",
)
assert r.returncode == 0, r.stderr
assert posted is None, (
"the job posted an exemption over a verdict that REPLACED a pre-existing row mid-run — the "
"abstain is testing presence ('was the head empty before?') rather than change. "
f"Posted: {posted}. Log:\n{r.stdout[-1200:]}"
)
def test_every_test_name_cited_by_the_exemption_provenance_record_EXISTS():
"""A record that names a test as its mutation proof must name one that can be run.
This is not hypothetical: renaming a test while splitting the `success`/`failure` cases left
`ci.exemption-provenance` citing `..._status_from_...` when the tree had `..._SUCCESS_from_...`,
found by cold review. A citation that cannot be resolved is worse than none — it reads as a
checked proof and sends the next reader looking for a test that does not exist.
Deliberately scoped to the ONE record that carries this change's proofs, and derived from the
record's own text rather than from a list restated here, so a newly cited name is covered the
moment it is written.
"""
record = REPO_ROOT / "docs" / "decisions" / "records" / "ci" / "exemption-provenance.md"
assert record.exists(), f"{record} is missing — the record this suite is the proof for"
cited = set(re.findall(r"`(test_[A-Za-z0-9_]+)`", record.read_text()))
assert cited, "the record cites no test by name; if that is deliberate, delete this guard"
defined = set(re.findall(r"^def (test_[A-Za-z0-9_]+)", Path(__file__).read_text(), re.MULTILINE))
for other in sorted(Path(__file__).parent.glob("test_*.py")):
defined |= set(re.findall(r"^def (test_[A-Za-z0-9_]+)", other.read_text(), re.MULTILINE))
missing = sorted(cited - defined)
assert not missing, (
f"ci.exemption-provenance cites {missing}, which no test in scripts/tests defines — the "
"record names a mutation proof nobody can run"
)
_PRE = "renovate|success|Review-verdict: MERGEABLE @ a9e3e23 (base: main)"
@pytest.mark.parametrize(
"clause,midrun_row",
[
("description", "renovate|success|Review-verdict: BLOCKED @ a9e3e23 (base: main)"),
("creator", "timothy|success|Review-verdict: MERGEABLE @ a9e3e23 (base: main)"),
("state", "renovate|failure|Review-verdict: MERGEABLE @ a9e3e23 (base: main)"),
],
)
def test_EACH_clause_of_the_changed_row_comparison_is_load_bearing(tmp_path, clause, midrun_row):
"""One case per field, because a triple whose cases all move all three fields pins none of them.
The mid-run row here differs from the pre-existing one in EXACTLY the named field, so dropping
that field's comparison makes the job miss the change, skip the abstain, and post its docs-only
exemption over the row. Reviewed cold: with only the two "everything moves at once" cases, three
single-clause deletions and a reduction of the whole triple to one comparison all shipped green.
The pre-existing row is an OFF-LIST `success` so the first read does not short-circuit — which is
also the realistic setup, since an off-list row is exactly why the job would be re-deriving.
"""
posted, r = _run_classify(
tmp_path,
_emitting("docs/a.md"),
status_mode="appears-on-read:2",
pre_row=_PRE,
midrun_row=midrun_row,
)
assert r.returncode == 0, r.stderr
assert posted is None, (
f"the mid-run row differed from the pre-existing one only in its {clause}, and the job did "
f"not notice — that clause of the changed-row comparison is not being evaluated. "
f"Posted: {posted}. Log:\n{r.stdout[-1200:]}"
)
def test_an_allow_list_with_SEVERAL_entries_honours_the_FIRST_one(tmp_path):
"""Multi-entry semantics, which every other test leaves unexercised.
All the behavioural cases run the singleton `H10_REVIEWERS="timothy"`, under which a loop that
can only ever match its LAST entry — drop the `break`, add an `else ex_human=no` — behaves
identically to a correct one. That matters more than it looks: the `::warning::` this change adds
tells an operator whose reviews are being discarded to ADD THEMSELVES to the list, so a
two-entry list is the first thing the fix produces, and the first entry is the one that breaks.
Docs-only on purpose: if the verdict is inherited the job posts nothing, and if it is not, the
exemption `success` is posted. So `posted is None` IS the inheritance.
"""
posted, r = _run_classify(
tmp_path,
_emitting("docs/a.md"),
status_mode="existing:success",
status_creator="alice",
status_desc="Review-verdict: MERGEABLE @ a9e3e23 (base: main)",
reviewers="alice timothy",
)
assert r.returncode == 0, r.stderr
assert posted is None, (
"a verdict from the FIRST entry of a two-entry H10_REVIEWERS was not inherited — membership "
f"is not scanning the whole list. Posted: {posted}. Log:\n{r.stdout[-900:]}"
)
def test_the_multi_entry_control_the_LAST_entry_is_honoured_too(tmp_path):
"""Without this, the test above could pass for any reason unrelated to list position."""
posted, _ = _run_classify(
tmp_path,
_emitting("docs/a.md"),
status_mode="existing:success",
status_creator="timothy",
status_desc="Review-verdict: MERGEABLE @ a9e3e23 (base: main)",
reviewers="alice timothy",
)
assert posted is None, "the positive control failed, so the first-entry test proves nothing"
def test_an_account_on_NEITHER_entry_is_still_re_derived(tmp_path):
"""The negative control for the two above: widening the list must not widen it to everyone."""
posted, _ = _run_classify(
tmp_path,
_emitting("ErsatzTV/Program.cs"),
status_mode="existing:success",
status_creator="mallory",
status_desc="Review-verdict: MERGEABLE @ a9e3e23 (base: main)",
reviewers="alice timothy",
)
assert posted is not None and posted["state"] == "pending", (
"an account absent from a two-entry allow-list was inherited"
)
@pytest.mark.parametrize(
"shape,creator,desc",
[
("a null creator (an Actions-token write)", None, "Review-verdict: BLOCKED @ a9e3e23 (base: main)"),
("a description that is not a verdict", "timothy", "blocked by hand"),
("a verdict recorded against ANOTHER base", "timothy", "Review-verdict: BLOCKED @ a9e3e23 (base: other)"),
],
)
def test_an_UNATTRIBUTABLE_failure_is_still_RE_DERIVED(tmp_path, shape, creator, desc):
"""`failure` needs only attributability — but "only attributability" is still a REQUIREMENT.
The clause is `[ "$ex_attributable" = yes ] && [ "$ex_state" = "failure" ]`, and the comment at
the site says plainly that widening it to a bare `[ "$ex_state" = failure ]` is deliberately NOT
done: that would quietly opt `failure` out of the base binding, which exists because a verdict
earned against another base is not a verdict for this diff. Cold cross-family review pointed out
that every existing `failure` case supplied a well-formed, base-matching, non-null-creator row,
so the bare-widening mutation passed the whole suite.
Docs-only on purpose: re-deriving is then visible as an exemption `success` being posted, where
short-circuiting would post nothing at all.
"""
posted, r = _run_classify(
tmp_path,
_emitting("docs/a.md"),
status_mode="existing:failure",
status_creator=creator,
status_desc=desc,
)
assert r.returncode == 0, r.stderr
assert posted is not None, (
f"a `failure` with {shape} was left alone — the failure short-circuit has been widened past "
f"attributability, taking the base binding with it. Log:\n{r.stdout[-1200:]}"
)
assert posted["state"] == "success"
def _h10_reviewers_literal():
"""The allow-list as the workflow actually declares it — read from the shipped file, never
restated here, so a test cannot pass against a value the gate does not use."""
body = _classify_step()["run"]
# findall + a SINGLE-ASSIGNMENT assertion, not `search`. `search` returns the FIRST assignment
# while the shell runs the LAST one executed, so a later or conditional reassignment would leave
# this guard validating a value the gate does not use — the same extractor-vs-classifier gap
# ersatztv#774 hit on `POS_RE`.
found = re.findall(r'^\s*H10_REVIEWERS="([^"]*)"\s*$', body, re.MULTILINE)
assert found, "review-verdict.yml no longer declares H10_REVIEWERS as a double-quoted literal"
assert len(found) == 1, (
f"H10_REVIEWERS is assigned {len(found)} times ({found}); the shell uses the last one "
"executed, so this guard can no longer tell which value the gate runs with"
)
return found[0]
def test_the_H10_REVIEWERS_list_is_glob_free_and_non_empty():
"""The membership loop word-splits `$H10_REVIEWERS`, so pathname expansion applies to each entry.
An entry containing `*`, `?` or `[` would be expanded against the runner's CWD before the
comparison — normally to itself (no match leaves the word alone), but to a FILENAME whenever one
happens to match, which silently changes who the gate accepts. Cheaper to forbid the characters
than to reason about the working directory.
Empty is checked too: `for rv in ""` iterates zero times, so an emptied list would make every
verdict non-inheritable and re-post `pending` over real human verdicts forever.
A FILE-TEXT LINT, deliberately, and it claims nothing more. It reads the literal out of the
shipped workflow so it cannot drift from the gate, but it does not execute the membership loop;
the behavioural consequences above are argued from the shell's semantics, not measured here.
"""
reviewers = _h10_reviewers_literal()
assert reviewers.strip(), "H10_REVIEWERS is empty — no verdict could ever be inherited"
for entry in reviewers.split():
assert re.fullmatch(r"[A-Za-z0-9._-]+", entry), (
f"H10_REVIEWERS entry {entry!r} is not a plain login; `*`, `?` and `[` are glob "
"metacharacters in the membership loop's word-splitting"
)
def test_the_allowlisted_reviewer_in_the_TESTS_is_the_one_the_WORKFLOW_ships():
"""De-shadowing, not a safety net — and the distinction was a review finding.
The BEHAVIOURAL tests do not need this: change the literal to `alice` and
`test_a_REAL_human_verdict_is_still_NEVER_overwritten` reddens on its own, because a `timothy`
verdict would stop being inherited. What this pins is the set of tests that use
`status_creator="timothy"` to reach a DIFFERENT clause — the base-marker cases below. If the
literal drifted they would start failing via the membership clause instead, still green, while
the clause they were written for went unexercised.
"""
assert "timothy" in _h10_reviewers_literal().split(), (
"the tests' allow-listed account is no longer in the workflow's H10_REVIEWERS, so every "
"inheritance test above is asserting against a value the gate does not use"
)
def test_an_UNRECOGNISED_success_shape_is_re_derived_rather_than_trusted(tmp_path):
"""The direction-of-test check. Written as 'skip if it looks machine-written', anything novel
would fall through to TRUSTED. Written as 'skip only if positively identified as human', novel
@@ -1683,6 +2150,10 @@ def test_an_UNRECOGNISED_success_shape_is_re_derived_rather_than_trusted(tmp_pat
def test_a_REAL_human_verdict_is_still_NEVER_overwritten(tmp_path, existing):
"""The property the short-circuit exists for, which the fix must not break.
SCOPE, because the test name says NEVER: this is about a verdict already VISIBLE AT THE FIRST
READ. A verdict landing later, inside this run's own write window, is a different route with its
own (incomplete) guard — see ersatztv#849.
`failure` is the sharp case: that is a human saying NO, and an exemption posted over it would
turn a rejection into a merge. Deliberately paired with a docs-only file list, so the job WOULD
have posted an exemption `success` had it not short-circuited — without that, a passing test
@@ -1700,6 +2171,11 @@ def test_a_REAL_human_verdict_is_still_NEVER_overwritten(tmp_path, existing):
f"overwrote a human '{existing}' verdict written by timothy — the never-overwrite property "
"has been lost while fixing route 3"
)
# NO "the diagnostic did not fire" ASSERTION HERE. An earlier version of this test carried one,
# captioned as pinning a guard on the annotation — but both parametrizations exit at a
# short-circuit two guards earlier and never reach the diagnostic at all, so the assertion was
# true by construction and could not fail. The annotation it guarded has since been withdrawn;
# the lesson is kept because a caption claiming a proof is worse than no assertion.
def test_a_PENDING_status_from_a_previous_run_is_replaced_normally(tmp_path):
@@ -2081,8 +2557,11 @@ def test_an_UNTRUSTED_retarget_count_withholds_the_EXEMPTION(tmp_path, mode):
def test_an_UNTRUSTED_retarget_count_STILL_LETS_PENDING_THROUGH(tmp_path, mode):
"""The other half, and the one that keeps a timeline outage from taking every PR down with it.
`pending` cannot turn an unreviewed head green — it is what blocks the merge — so withholding it
buys no safety and would strand ordinary PRs with no status at all. Only the exemption is gated.
`pending` blocks the merge, so letting it through is the right anti-stranding trade — withholding
it would leave ordinary PRs with no status at all. NOT because it is inert: a generic `pending`
masks a rejection landing in its own write window, gets no post-write verification, and a later
run re-derives it green (ersatztv#849). Immediate block versus later re-derivation risk, not
"buys no safety". Only the exemption is gated.
"""
posted, r = _run_classify(tmp_path, _emitting("ErsatzTV/Program.cs"), timeline_mode=mode)
assert posted is not None and posted["state"] == "pending", (