From 77585ca13ab01fcacbcc0f56a842b3a54e120978 Mon Sep 17 00:00:00 2001 From: Timothy Date: Wed, 26 Aug 2026 21:25:06 +0200 Subject: [PATCH 01/16] fix(742): inherit an h10 verdict only from an allow-listed reviewer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `review-verdict.yml` left an existing `review-verdict/h10` alone when it was "positively identifiable as a human verdict" — a non-null `.creator.login` plus a `Review-verdict:` description. Non-null only proves SOME user credential posted it, and this repo stores credentials for accounts that are not reviewers. `RENOVATE_TOKEN` is a `write:repository` PAT of the `renovate` bot; unlike #697's registry credential it cannot be scoped off status-write (Renovate needs repo write to push branches and open PRs), and secrets are a per-repo store any workflow can reference — so a status posted with it read back `creator: renovate`, non-null, and was inherited as a verdict. The test is now membership in `H10_REVIEWERS="timothy"`, a literal in the base-resolved definition. 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. Membership is an exact `[ = ]` comparison over word-split entries, never `grep -xF` — an API-supplied creator containing a newline would be read as several patterns, any one of which could match an allow-listed line. The allow-list is applied to INHERITANCE ONLY. The post-write raced-verdict check reads the same `.creator` field for the opposite purpose — "did anything human land while we were writing" — so narrowing it would not make it stricter, it would make it count fewer rows, and a raced verdict from an off-list account would leave the exemption `success` standing over a rejection. That is the one path in this job whose failure direction is toward SUCCESS, so it stays broad on `creator != null` and the repair is allowed to be over-eager. Both directions are mutation-proven against the shipped file, not a hand-written mutant: reverting the membership clause to `[ -n "$ex_creator" ]` reddens the seven new inheritance cases; narrowing the raced jq to `.creator.login == "timothy"` reddens `test_the_RACED_verdict_check_still_counts_a_NON_allowlisted_creator` alone; `H10_REVIEWERS` set to `tim*`, empty, or `bob` reddens the two list-shape tests. `scripts/tests`: 965 passed, 2 skipped. What this does NOT close, unchanged: 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. fixes #742 Decisions-Edit: yes --- .gitea/workflows/review-verdict.yml | 79 +++++++++-- docs/ci-cd.md | 51 ++++--- docs/decisions/README.md | 2 +- .../records/ci/actions-credential-scoping.md | 25 +++- .../records/ci/exemption-provenance.md | 36 ++++- .../records/release/verdict-status-check.md | 8 +- scripts/tests/test_pr_changed_files.py | 125 +++++++++++++++++- 7 files changed, 286 insertions(+), 40 deletions(-) diff --git a/.gitea/workflows/review-verdict.yml b/.gitea/workflows/review-verdict.yml index dd32be129..aa55190d1 100644 --- a/.gitea/workflows/review-verdict.yml +++ b/.gitea/workflows/review-verdict.yml @@ -232,6 +232,34 @@ 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 was inherited as a human verdict. + # + # 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" @@ -379,7 +407,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 @@ -487,7 +515,23 @@ jobs: esac case "$ex_desc" in "Review-verdict:"*) - if [ -n "$ex_creator" ]; then ex_human=yes; fi + # POLARITY — DO NOT "MAKE THIS CONSISTENT" WITH THE RACED-VERDICT TEST BELOW. This one + # guards INHERITANCE, so narrowing it is safe: an account it does not recognise falls + # through to re-derivation. The raced test in the post-write repair is the MIRROR + # IMAGE — it asks "did anything human land while we were writing", and narrowing THAT + # one would stop counting a raced row and leave an exemption `success` standing over a + # human rejection, the one path in this job whose failure direction is toward SUCCESS. + # The two tests read the same field for opposite purposes and must stay different + # widths. + # + # Exact string comparison, not `grep -xF`: `$ex_creator` is API-supplied, and a value + # containing a newline would be read by `grep` as SEVERAL patterns, any one of which + # could match an allow-listed line. `[ = ]` compares the whole value. + if [ -n "$ex_creator" ]; then + for rv in $H10_REVIEWERS; do + if [ "$rv" = "$ex_creator" ]; then ex_human=yes; break; fi + done + fi ;; esac if [ "$ex_human" = yes ]; then @@ -663,19 +707,26 @@ 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. 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." + echo "${CONTEXT} is already '${ex_state}' on ${SHA:0:7}, written by '${ex_creator}', an allow-listed reviewer — leaving it alone." exit 0 fi 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." + echo "${CONTEXT} is '${ex_state}' on ${SHA:0:7} but is NOT an attributable reviewer verdict (creator='${ex_creator:-null}', allow-list='${H10_REVIEWERS}', description='${ex_desc}') — re-deriving it from the PR's current state rather than inheriting it." fi # --- Changed files: the SHARED enumeration, or no exemption. ------------------------- @@ -986,6 +1037,14 @@ 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 and must stay that way + # (ersatztv#742). `read_existing_verdict` requires `$H10_REVIEWERS` membership before it + # will INHERIT a verdict; here the question is the opposite one — "did anything human + # land while we were writing" — and a narrower test would simply stop counting rows, so + # a raced verdict from an account off the allow-list would leave the exemption `success` + # standing. This is the one path in this job whose failure direction is toward SUCCESS, + # so it counts any attributable row and lets the repair be over-eager instead. + # # (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 diff --git a/docs/ci-cd.md b/docs/ci-cd.md index 66155d615..670a0d2e2 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -1294,23 +1294,40 @@ The two exemptions are evaluated as **independent predicates**, never as an `eli 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. +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. (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 that widening 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 inherited. Membership makes every non-reviewer account +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 is applied to inheritance ONLY, deliberately.** The post-write raced-verdict check +reads the same `.creator` field for the opposite purpose — "did anything human land while we were +writing" — and narrowing *that* one would stop it counting a raced row, leaving an exemption +`success` standing over a rejection. It is the one path in the job whose failure direction is toward +success, so it stays broad on `creator != null` and the repair is allowed to be over-eager. Pinned by +`test_pr_changed_files.py::test_the_RACED_verdict_check_still_counts_a_NON_allowlisted_creator`, which +fails the moment someone makes the two consistent. + +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 diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 5e8938a3f..095e3daf5 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -46,7 +46,7 @@ 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/` 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: )` 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 only for a status 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 — 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: )` 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.format-gate-folder-mode` | The blocking `format` CI job (and matching pre-commit hook) runs `dotnet format whitespace . --folder --include ` 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) | diff --git a/docs/decisions/records/ci/actions-credential-scoping.md b/docs/decisions/records/ci/actions-credential-scoping.md index 8196605db..6d0ce209b 100644 --- a/docs/decisions/records/ci/actions-credential-scoping.md +++ b/docs/decisions/records/ci/actions-credential-scoping.md @@ -40,9 +40,19 @@ 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` route is closed by the allow-list, not by scoping (#742), because scoping was +not available.** 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 ` 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. **That asymmetry is not protection.** 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 +106,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 diff --git a/docs/decisions/records/ci/exemption-provenance.md b/docs/decisions/records/ci/exemption-provenance.md index f51bf8b8b..5c5e79590 100644 --- a/docs/decisions/records/ci/exemption-provenance.md +++ b/docs/decisions/records/ci/exemption-provenance.md @@ -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: )` 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 ` (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 only for a status 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 — 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: )` 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: '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: #742, #698, #697, #672, #663, #649, #632' +mechanics: '`scripts/pr-changed-files.sh ` (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 `[ = ]` comparison over word-split entries, never `grep -xF` (an API-supplied creator containing a newline reads as several patterns); short-circuit requires that membership AND description matching `^Review-verdict:`; `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 @@ -117,5 +117,35 @@ 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 was inherited. +Membership in `H10_REVIEWERS` restores the intended set: every other account, recognised or not, +re-derives exactly as an Actions-token status already does. 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. + +**The allow-list is NOT applied everywhere `.creator` is read, and that asymmetry is load-bearing.** +The post-write raced-verdict check asks the opposite question — "did anything human land while we were +writing" — so narrowing it does not make it stricter, it makes it *count fewer rows*: a raced verdict +from an off-list account would go unnoticed and the exemption `success` would stand over it. That is +the one path in the job whose failure direction is toward SUCCESS, so it stays broad on +`creator != null` and the repair is allowed to be over-eager instead. +`test_pr_changed_files.py::test_the_RACED_verdict_check_still_counts_a_NON_allowlisted_creator` fails +the moment the two are "made consistent", and both directions are mutation-proven: reverting the +membership clause reddens seven inheritance tests, narrowing the raced clause reddens that one. + +**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. diff --git a/docs/decisions/records/release/verdict-status-check.md b/docs/decisions/records/release/verdict-status-check.md index ee7d5d805..c74ceec93 100644 --- a/docs/decisions/records/release/verdict-status-check.md +++ b/docs/decisions/records/release/verdict-status-check.md @@ -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 diff --git a/scripts/tests/test_pr_changed_files.py b/scripts/tests/test_pr_changed_files.py index 0ab7da9c1..003152f6e 100644 --- a/scripts/tests/test_pr_changed_files.py +++ b/scripts/tests/test_pr_changed_files.py @@ -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 @@ -1228,6 +1232,7 @@ def _run_classify( status_desc: str = "Review-verdict: MERGEABLE @ a9e3e23 (base: main)", timeline_mode: str = "none", history_mode: str = "none", + history_creator: str = "timothy", timeline_terminator: str = "null", status_empty_shape: str = "null", ): @@ -1265,6 +1270,7 @@ 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.update( { "GITEA_TOKEN": "stub", @@ -1668,6 +1674,123 @@ 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: `success`, 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. + """ + 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" + + +@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. + + `read_existing_verdict` asks "may this be INHERITED", so narrowing it is safe — an unrecognised + account falls through to re-derivation. The post-write check asks the OPPOSITE question, "did + anything human land while we were writing", and narrowing THAT one stops it counting rows: a + raced verdict from an account off the allow-list would be ignored and the exemption `success` + would stand over it. That is the one path in this job whose failure direction is toward SUCCESS. + + So this test fails the moment someone "makes the two consistent". + """ + 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 _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"] + m = re.search(r'^\s*H10_REVIEWERS="([^"]*)"\s*$', body, re.MULTILINE) + assert m, "review-verdict.yml no longer declares H10_REVIEWERS as a double-quoted literal" + return m.group(1) + + +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. + """ + 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(): + """Verify the verifier. Every test above hardcodes `timothy` as the accepted account and some + other string as the rejected one; if the workflow's literal changed, those tests would keep + passing while measuring nothing about the shipped gate.""" + 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 -- 2.47.3 From 61222fc3a5d0702a4f813c4f1db4ff37237c97ca Mon Sep 17 00:00:00 2001 From: Timothy Date: Wed, 26 Aug 2026 21:44:14 +0200 Subject: [PATCH 02/16] fix(742): split ex_attributable from ex_human; correct the raced-check rationale MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cold review round 1 (two independent agents) found the first draft narrowed BOTH readers of the verdict row, not just inheritance. * `read_existing_verdict` is called twice. The second call is the last-moment re-read, which asks "did a reviewer post a verdict while we were classifying" — the mirror-image question. Gating the single flag made the job stop abstaining and post its exemption straight over a mid-run row, and the post-write repair does NOT cover that: it is skipped whenever the high-water mark could not be established. Reproduced red first, then fixed: `test_the_MID_RUN_abstain_still_fires_for_a_NON_allowlisted_creator`. * Splitting the flags broke the invariant that made the re-read work at all — the two calls used to compute an IDENTICAL predicate, so anything firing at the second and not the first had arrived in between. A pre-existing row declined for inheritance is still attributable, so the re-read abstained on the very row the classification had decided to overwrite and posted nothing. Seven tests went red on exactly that. The state/creator/description triple from the first read is now snapshotted and compared, making "changed" explicit. * The stated reason for keeping the post-write raced check broad was asserted, not checked: a genuine reviewer is on the list by construction, so membership there would still count every real verdict. Replaced with the real reason (the misconfiguration case — a second human account forgotten from the literal) and the real cost (a verdict-shaped row landing in the write window trips the sticky sentinel and costs that head its exemption). * A `::warning::` now names the creator whenever the job re-derives over a verdict-shaped status from an off-list account, so a reviewer left off the list is not discarded silently. * The list guard uses `findall` + a single-assignment assertion: `search` validates the FIRST assignment while the shell runs the LAST executed one. * Mutation counts dropped from the decision record in favour of test names — nothing re-executes a number written there. Mutation-proven: mid-run site back to `ex_human` reddens the mid-run test; dropping the changed-row comparison reddens the inheritance cases; `if false` at the abstain reddens both mid-run tests. fixes #742 Decisions-Edit: yes --- .gitea/workflows/review-verdict.yml | 119 +++++++++++++----- docs/ci-cd.md | 38 ++++-- .../records/ci/actions-credential-scoping.md | 9 +- .../records/ci/exemption-provenance.md | 55 ++++++-- scripts/tests/test_pr_changed_files.py | 92 +++++++++++--- 5 files changed, 246 insertions(+), 67 deletions(-) diff --git a/.gitea/workflows/review-verdict.yml b/.gitea/workflows/review-verdict.yml index aa55190d1..bcfe0407f 100644 --- a/.gitea/workflows/review-verdict.yml +++ b/.gitea/workflows/review-verdict.yml @@ -508,33 +508,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. + # + # The first draft of #742 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 post-write repair does NOT cover that regression, because it is skipped + # whenever the high-water mark could not be established (`max_id_before=-1`). 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:"*) - # POLARITY — DO NOT "MAKE THIS CONSISTENT" WITH THE RACED-VERDICT TEST BELOW. This one - # guards INHERITANCE, so narrowing it is safe: an account it does not recognise falls - # through to re-derivation. The raced test in the post-write repair is the MIRROR - # IMAGE — it asks "did anything human land while we were writing", and narrowing THAT - # one would stop counting a raced row and leave an exemption `success` standing over a - # human rejection, the one path in this job whose failure direction is toward SUCCESS. - # The two tests read the same field for opposite purposes and must stay different - # widths. - # - # Exact string comparison, not `grep -xF`: `$ex_creator` is API-supplied, and a value - # containing a newline would be read by `grep` as SEVERAL patterns, any one of which - # could match an allow-listed line. `[ = ]` compares the whole value. - if [ -n "$ex_creator" ]; then - for rv in $H10_REVIEWERS; do - if [ "$rv" = "$ex_creator" ]; then ex_human=yes; break; fi - done - 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: @@ -566,11 +569,25 @@ 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. + # + # POSIX `[ = ]`, NEVER `[[ == ]]` and never `grep -xF`. `[[ == ]]` makes its right-hand + # side a PATTERN, which would reintroduce the glob exposure the literal is linted against; + # `grep` would read a newline-bearing `$ex_creator` as SEVERAL patterns, any one of which + # could match an allow-listed line. `[ = ]` compares the whole value, literally. (No test + # can see a `[ = ]` -> `[[ == ]]` regression, because Gitea logins cannot contain a glob + # metacharacter — hence this comment rather than a test that would pass either way.) + 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) ---------------------------------------- @@ -725,8 +742,33 @@ jobs: echo "${CONTEXT} is already '${ex_state}' on ${SHA:0:7}, written by '${ex_creator}', an allow-listed reviewer — leaving it alone." 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 seven 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. + 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 reviewer verdict (creator='${ex_creator:-null}', allow-list='${H10_REVIEWERS}', description='${ex_desc}') — re-deriving it from the PR's current state rather than inheriting it." + # ANNOTATE, do not merely log, when the row we are about to overwrite LOOKS like a verdict + # from a real account that is simply not on the list (ersatztv#742). On today's account + # set that is only `renovate`, whose "verdict" is by definition not one — but the day a + # second human account is added to the repo and forgotten from the literal, this is the + # ONLY signal that their reviews are being silently discarded, and an ordinary `echo` + # buried in a job log is not a signal. `::warning::` surfaces on the run summary. + if [ -n "$ex_creator" ] && [ "$ex_attributable" = yes ]; then + echo "::warning::${CONTEXT} on ${SHA:0:7} carries a verdict-shaped status from '${ex_creator}', which is NOT in H10_REVIEWERS ('${H10_REVIEWERS}') — it is being re-derived, not honoured. If '${ex_creator}' is a reviewer, add them to H10_REVIEWERS in .gitea/workflows/review-verdict.yml; otherwise this is the intended refusal." + fi fi # --- Changed files: the SHARED enumeration, or no exemption. ------------------------- @@ -907,9 +949,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 @@ -1037,13 +1086,25 @@ 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 and must stay that way - # (ersatztv#742). `read_existing_verdict` requires `$H10_REVIEWERS` membership before it - # will INHERIT a verdict; here the question is the opposite one — "did anything human - # land while we were writing" — and a narrower test would simply stop counting rows, so - # a raced verdict from an account off the allow-list would leave the exemption `success` - # standing. This is the one path in this job whose failure direction is toward SUCCESS, - # so it counts any attributable row and lets the repair be over-eager instead. + # (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. Cold review caught that as an asserted-but-unchecked + # reason and it is not repeated. + # + # THE REAL 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. This is the LAST net before a green stands, and the two errors 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 diff --git a/docs/ci-cd.md b/docs/ci-cd.md index 670a0d2e2..c98b6c948 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -1301,7 +1301,8 @@ inherited. (Measured: a status POSTed with a user credential carries a creator; 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 that widening is the point.** +**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 @@ -1312,13 +1313,34 @@ re-derive exactly as an Actions-token status does. The list is a **literal in th 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 is applied to inheritance ONLY, deliberately.** The post-write raced-verdict check -reads the same `.creator` field for the opposite purpose — "did anything human land while we were -writing" — and narrowing *that* one would stop it counting a raced row, leaving an exemption -`success` standing over a rejection. It is the one path in the job whose failure direction is toward -success, so it stays broad on `creator != null` and the repair is allowed to be over-eager. Pinned by -`test_pr_changed_files.py::test_the_RACED_verdict_check_still_counts_a_NON_allowlisted_creator`, which -fails the moment someone makes the two consistent. +**The allow-list is applied to INHERITANCE only — 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. + It is the last net before a green stands, and repairing to `pending` is recoverable while a + wrongly-standing `success` is not. The cost: any verdict-shaped row landing inside the write 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.** The job emits a `::warning::` naming the +creator whenever it re-derives over a verdict-shaped status from an account that is not on the list; +add them to `H10_REVIEWERS` in `.gitea/workflows/review-verdict.yml`. `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, so a changed writer credential deadlocks PRs rather than failing loudly. 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 diff --git a/docs/decisions/records/ci/actions-credential-scoping.md b/docs/decisions/records/ci/actions-credential-scoping.md index 6d0ce209b..1a90ea00e 100644 --- a/docs/decisions/records/ci/actions-credential-scoping.md +++ b/docs/decisions/records/ci/actions-credential-scoping.md @@ -45,14 +45,17 @@ positively identifiable as an approved reviewer's verdict — a `.creator.login` `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` route is closed by the allow-list, not by scoping (#742), because scoping was -not available.** That token needs `write:repository` to do its job — pushing branches and opening PRs +**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 ` 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. **That asymmetry is not protection.** Re-derivation +what the consumer will accept from it. **The creator-shape asymmetry — real creator INHERITED, `creator: null` re-derived — is not +protection.** 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. diff --git a/docs/decisions/records/ci/exemption-provenance.md b/docs/decisions/records/ci/exemption-provenance.md index 5c5e79590..ad2ddde28 100644 --- a/docs/decisions/records/ci/exemption-provenance.md +++ b/docs/decisions/records/ci/exemption-provenance.md @@ -7,7 +7,7 @@ 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 an APPROVED REVIEWER''s verdict for THIS base, meaning a `.creator.login` that is a member of the workflow''s `H10_REVIEWERS` allow-list — 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: )` 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: '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: #742, #698, #697, #672, #663, #649, #632' -mechanics: '`scripts/pr-changed-files.sh ` (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 `[ = ]` comparison over word-split entries, never `grep -xF` (an API-supplied creator containing a newline reads as several patterns); short-circuit requires that membership AND description matching `^Review-verdict:`; `types: [opened, reopened, synchronize, ready_for_review, edited]`' +mechanics: '`scripts/pr-changed-files.sh ` (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 `[[ == ]]` (RHS becomes a pattern) 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 @@ -129,15 +129,50 @@ base-resolved definition rather than a repo `vars:` entry, because a `vars:` ent 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. -**The allow-list is NOT applied everywhere `.creator` is read, and that asymmetry is load-bearing.** -The post-write raced-verdict check asks the opposite question — "did anything human land while we were -writing" — so narrowing it does not make it stricter, it makes it *count fewer rows*: a raced verdict -from an off-list account would go unnoticed and the exemption `success` would stand over it. That is -the one path in the job whose failure direction is toward SUCCESS, so it stays broad on -`creator != null` and the repair is allowed to be over-eager instead. -`test_pr_changed_files.py::test_the_RACED_verdict_check_still_counts_a_NON_allowlisted_creator` fails -the moment the two are "made consistent", and both directions are mutation-proven: reverting the -membership clause reddens seven inheritance tests, narrowing the raced clause reddens that one. +**`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. + +**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". Cold review +showed 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. The real 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. It 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 is stated at the site rather than implied: any verdict-shaped row landing inside the write 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_status_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 coupling this record does NOT assert, tracked 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-posts `pending` over it — a deadlocked PR whose only diagnostic is a line in a job log. +Correct today (verified live: the token's `/user` login is `timothy`, and the instance has exactly the +accounts `timothy` and `renovate`), but nothing keeps it correct. **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 diff --git a/scripts/tests/test_pr_changed_files.py b/scripts/tests/test_pr_changed_files.py index 003152f6e..4e0810970 100644 --- a/scripts/tests/test_pr_changed_files.py +++ b/scripts/tests/test_pr_changed_files.py @@ -1146,9 +1146,12 @@ if "/status" in url: if n + 1 < nth: print(empty_statuses()) sys.exit(0) + # 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. print(json.dumps({"statuses": [ {"context": "review-verdict/h10", "status": "failure", - "creator": {"login": "timothy"}, + "creator": {"login": os.environ.get("STUB_MIDRUN_CREATOR", "timothy")}, "description": "Review-verdict: BLOCKED @ a9e3e23 (base: main)"}]})) sys.exit(0) if mode.startswith("sentinel-appears-on-read:"): @@ -1233,6 +1236,7 @@ def _run_classify( timeline_mode: str = "none", history_mode: str = "none", history_creator: str = "timothy", + midrun_creator: str = "timothy", timeline_terminator: str = "null", status_empty_shape: str = "null", ): @@ -1271,6 +1275,7 @@ def _run_classify( 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.update( { "GITEA_TOKEN": "stub", @@ -1682,18 +1687,22 @@ def test_a_success_with_a_creator_but_an_EXEMPT_description_is_re_derived(tmp_pa # POSTed with it reads back `creator: renovate` — non-null, and therefore inherited as a verdict. +@pytest.mark.parametrize("existing", ["success", "failure"]) @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: `success`, a - real creator, a `Review-verdict:` description recording THIS base. Only the account is wrong. +def test_a_verdict_shaped_status_from_a_NON_allowlisted_account_is_RE_DERIVED(tmp_path, creator, existing): + """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. + + BOTH states, because the short-circuit branches on `success` OR `failure` and an off-list + `failure` is the case that would otherwise deadlock a PR nobody can clear. """ posted, r = _run_classify( tmp_path, _emitting("ErsatzTV/Program.cs"), - status_mode="existing:success", + status_mode=f"existing:{existing}", status_creator=creator, status_desc="Review-verdict: MERGEABLE @ a9e3e23 (base: main)", ) @@ -1727,13 +1736,16 @@ def test_an_account_that_merely_RESEMBLES_an_allowlisted_login_is_RE_DERIVED(tmp 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. - `read_existing_verdict` asks "may this be INHERITED", so narrowing it is safe — an unrecognised - account falls through to re-derivation. The post-write check asks the OPPOSITE question, "did - anything human land while we were writing", and narrowing THAT one stops it counting rows: a - raced verdict from an account off the allow-list would be ignored and the exemption `success` - would stand over it. That is the one path in this job whose failure direction is toward SUCCESS. + 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. - So this test fails the moment someone "makes the two consistent". + 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, @@ -1752,13 +1764,49 @@ def test_the_RACED_verdict_check_still_counts_a_NON_allowlisted_creator(tmp_path 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 _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"] - m = re.search(r'^\s*H10_REVIEWERS="([^"]*)"\s*$', body, re.MULTILINE) - assert m, "review-verdict.yml no longer declares H10_REVIEWERS as a double-quoted literal" - return m.group(1) + # 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(): @@ -1771,6 +1819,10 @@ def test_the_H10_REVIEWERS_list_is_glob_free_and_non_empty(): 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" @@ -1782,9 +1834,15 @@ def test_the_H10_REVIEWERS_list_is_glob_free_and_non_empty(): def test_the_allowlisted_reviewer_in_the_TESTS_is_the_one_the_WORKFLOW_ships(): - """Verify the verifier. Every test above hardcodes `timothy` as the accepted account and some - other string as the rejected one; if the workflow's literal changed, those tests would keep - passing while measuring nothing about the shipped gate.""" + """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" -- 2.47.3 From 54de64f76b33a81010412bc31ed2d6328ddf8879 Mon Sep 17 00:00:00 2001 From: Timothy Date: Wed, 26 Aug 2026 21:46:31 +0200 Subject: [PATCH 03/16] docs(742): correct stale creator claims in ci.gate-trigger-base-resolved; track #845 Sweeping for the OLD wording rather than only the sites the change touched turned up `ci.gate-trigger-base-resolved`, which stated in both its rule and its body that a RENOVATE_TOKEN-posted status 'carries a real creator and IS inherited'. True until this change, and a record that reads as a checked fact is worse than none. Also files #845 for the coupling the shell/polarity review raised and this change does not close: post-review-verdict.sh posts with whatever account owns the credential and never checks it is one the gate accepts, so a changed writer credential deadlocks PRs rather than failing loudly. Recorded as a residual with the live verification behind it, not asserted away. Decisions-Edit: yes --- docs/decisions/README.md | 2 +- docs/decisions/records/ci/exemption-provenance.md | 8 ++++---- docs/decisions/records/ci/gate-trigger-base-resolved.md | 9 ++++++--- 3 files changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 095e3daf5..ef0f0184e 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -49,7 +49,7 @@ the link for rationale. Superseded/retired history lives in `archive/`. Regenera | `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 an APPROVED REVIEWER's verdict for THIS base, meaning a `.creator.login` that is a member of the workflow's `H10_REVIEWERS` allow-list — 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: )` 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.format-gate-folder-mode` | The blocking `format` CI job (and matching pre-commit hook) runs `dotnet format whitespace . --folder --include ` 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=` 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) | diff --git a/docs/decisions/records/ci/exemption-provenance.md b/docs/decisions/records/ci/exemption-provenance.md index ad2ddde28..ce8bf43cd 100644 --- a/docs/decisions/records/ci/exemption-provenance.md +++ b/docs/decisions/records/ci/exemption-provenance.md @@ -6,7 +6,7 @@ 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 an APPROVED REVIEWER''s verdict for THIS base, meaning a `.creator.login` that is a member of the workflow''s `H10_REVIEWERS` allow-list — 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: )` 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: '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: #742, #698, #697, #672, #663, #649, #632' +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: #845, #742, #698, #697, #672, #663, #649, #632' mechanics: '`scripts/pr-changed-files.sh ` (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 `[[ == ]]` (RHS becomes a pattern) 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]`' --- @@ -167,12 +167,12 @@ inheritance cases respectively. Counts are deliberately not quoted: `test_pr_cha graded `PROOF | NONE`, so nothing re-executes a number written here and one added `parametrize` case would falsify it silently. -**A coupling this record does NOT assert, tracked instead.** `post-review-verdict.sh` posts with +**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-posts `pending` over it — a deadlocked PR whose only diagnostic is a line in a job log. -Correct today (verified live: the token's `/user` login is `timothy`, and the instance has exactly the -accounts `timothy` and `renovate`), but nothing keeps it correct. +Correct today (verified live 2026-08-26: the token's `/user` login is `timothy`, and the instance has +exactly the accounts `timothy` and `renovate`), but nothing keeps it correct — #845. **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 diff --git a/docs/decisions/records/ci/gate-trigger-base-resolved.md b/docs/decisions/records/ci/gate-trigger-base-resolved.md index f3a8c81f5..1df318d2c 100644 --- a/docs/decisions/records/ci/gate-trigger-base-resolved.md +++ b/docs/decisions/records/ci/gate-trigger-base-resolved.md @@ -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. -- 2.47.3 From 9ed30a6b7c31329a6b1d5d236be2f1684516d21a Mon Sep 17 00:00:00 2001 From: Timothy Date: Wed, 26 Aug 2026 22:24:46 +0200 Subject: [PATCH 04/16] fix(742): the allow-list governs an inherited success, NOT a failure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Round-2 cold review (two independent agents) returned BLOCKED. Both found the same class of hole from different angles. FAIL-OPEN, and a regression against main. The short-circuit branched on success OR failure under one membership test, so an off-list `failure` was re-derived. Trace it: 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. The job posts success over an explicit rejection — reached by the very misconfiguration the allow-list's own diagnostic is about. `failure` now needs only attributability, which costs nothing the allow-list bought: inheriting a rejection cannot green anything, and the worst a forged one achieves is a stall that any human clears in one command (post-review-verdict.sh POSTs unconditionally). THE CHANGED-ROW COMPARISON WAS NOT PINNED. A presence-only version (`[ -z "$pre_state" ]`) passed all 158 tests, because every mid-run test started from an empty head and exercised only the ARRIVAL case. The REPLACEMENT case is the one that co-occurs with #742's own scenario. Stub knob STUB_PRE_ROW plus a test; the presence-only mutant now reddens. Also from the round: the ::warning:: fired with a self-contradictory message for an allow-listed creator in a non-terminal state, and interpolated an API-supplied value into a workflow command unstripped; a quoted test count that no longer matched the tree; the function's own contract line omitted the flag this change adds; a comment naming ex_human where it is now ex_attributable; and an unprobed claim about how Gitea renders ::warning::, now withdrawn rather than restated. MEASURED rather than asserted: 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 on /statuses/{sha}. That claim became load-bearing with the changed-row comparison; main depended on presence alone. The probe left the sha's combined state `success`. Recorded, not silently gained: an attributable row in a state other than success/failure used to stall a PR forever on main (neither short-circuit fired, the old unconditional abstain did). The changed-row comparison removes that stall. scripts/tests: 969 passed, 2 skipped. fixes #742 Decisions-Edit: yes --- .gitea/workflows/review-verdict.yml | 73 ++++++++++++--- docs/ci-cd.md | 25 ++++-- .../records/ci/exemption-provenance.md | 38 ++++++-- scripts/tests/test_pr_changed_files.py | 88 +++++++++++++++++-- 4 files changed, 194 insertions(+), 30 deletions(-) diff --git a/.gitea/workflows/review-verdict.yml b/.gitea/workflows/review-verdict.yml index bcfe0407f..a61bac58e 100644 --- a/.gitea/workflows/review-verdict.yml +++ b/.gitea/workflows/review-verdict.yml @@ -392,7 +392,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 @@ -737,9 +738,30 @@ jobs: # 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 this branch carried for one round before cold review caught it + # (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. 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}', an allow-listed reviewer — 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 explicit rejection is left alone whoever 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 @@ -749,12 +771,27 @@ jobs: # 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 seven inheritance tests went red on exactly that.) + # 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 @@ -764,10 +801,25 @@ jobs: # from a real account that is simply not on the list (ersatztv#742). On today's account # set that is only `renovate`, whose "verdict" is by definition not one — but the day a # second human account is added to the repo and forgotten from the literal, this is the - # ONLY signal that their reviews are being silently discarded, and an ordinary `echo` - # buried in a job log is not a signal. `::warning::` surfaces on the run summary. - if [ -n "$ex_creator" ] && [ "$ex_attributable" = yes ]; then - echo "::warning::${CONTEXT} on ${SHA:0:7} carries a verdict-shaped status from '${ex_creator}', which is NOT in H10_REVIEWERS ('${H10_REVIEWERS}') — it is being re-derived, not honoured. If '${ex_creator}' is a reviewer, add them to H10_REVIEWERS in .gitea/workflows/review-verdict.yml; otherwise this is the intended refusal." + # ONLY signal that their reviews are being silently discarded. Emitted as a workflow + # WARNING rather than a bare `echo` so it carries a severity and is greppable; how Gitea + # 1.27 RENDERS a `::warning::` is deliberately NOT claimed — an earlier draft asserted it + # surfaces on the run summary and never probed it. + # + # `ex_human != yes` is REQUIRED, not belt-and-braces: control also reaches here for an + # ALLOW-LISTED creator whose row is in some state other than `success`/`failure`, and + # without it the annotation reads "from 'timothy', which is NOT in H10_REVIEWERS + # ('timothy')" — a diagnostic that contradicts itself trains the reader to ignore it. + # (`[ -n "$ex_creator" ]` is NOT also tested: `ex_attributable=yes` is reachable only + # through a branch that already required it.) + # + # CR/LF stripped before interpolation. The value is API-supplied, and the untrustedness + # this file argues for the membership comparison has a sharper edge here: a newline inside + # a `::warning::` line would start a SECOND workflow command. Unreachable through Gitea's + # username validation; stripped anyway, because the cost is one parameter expansion. + if [ "$ex_attributable" = yes ] && [ "$ex_human" != yes ]; then + ex_creator_1line=${ex_creator//[$'\r\n']/ } + echo "::warning::${CONTEXT} on ${SHA:0:7} carries a verdict-shaped status from '${ex_creator_1line}', which is NOT in H10_REVIEWERS ('${H10_REVIEWERS}') — it is being re-derived, not honoured. If '${ex_creator_1line}' is a reviewer, add them to H10_REVIEWERS in .gitea/workflows/review-verdict.yml; otherwise this is the intended refusal." fi fi @@ -916,8 +968,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. # diff --git a/docs/ci-cd.md b/docs/ci-cd.md index c98b6c948..6719ec395 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -1313,8 +1313,13 @@ re-derive exactly as an Actions-token status does. The list is a **literal in th 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 is applied to INHERITANCE only — two other readers of `.creator` stay broad, and the -split is load-bearing.** `read_existing_verdict` carries two flags: `ex_attributable` (an attributable +**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). @@ -1329,9 +1334,12 @@ membership). - 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. - It is the last net before a green stands, and repairing to `pending` is recoverable while a - wrongly-standing `success` is not. The cost: any verdict-shaped row landing inside the write window - trips the sticky repair sentinel and costs that head its exemption until a human clears it. + 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`. @@ -1339,8 +1347,11 @@ Pinned by `test_the_MID_RUN_abstain_still_fires_for_a_NON_allowlisted_creator` a **If a reviewer's verdicts stop being honoured, this is why.** The job emits a `::warning::` naming the creator whenever it re-derives over a verdict-shaped status from an account that is not on the list; add them to `H10_REVIEWERS` in `.gitea/workflows/review-verdict.yml`. `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, so a changed writer credential deadlocks PRs rather than failing loudly. +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 verdict to `pending`; 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 diff --git a/docs/decisions/records/ci/exemption-provenance.md b/docs/decisions/records/ci/exemption-provenance.md index ce8bf43cd..770f1163a 100644 --- a/docs/decisions/records/ci/exemption-provenance.md +++ b/docs/decisions/records/ci/exemption-provenance.md @@ -146,18 +146,36 @@ INHERIT is still attributable, so the re-read abstained on the very row the clas 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. +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, and this branch +carried it for a round.** 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". Cold review showed 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. The real 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. It 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 is stated at the site rather than implied: any verdict-shaped row landing inside the write window -trips the STICKY `REPAIR_DESC` sentinel and costs that head its exemption until a human clears it. +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_status_from_a_NON_allowlisted_account_is_RE_DERIVED` and @@ -172,7 +190,11 @@ whatever account owns `ETV_GITEA_TOKEN`/`ETV_GITEA_BASICAUTH` and never checks w ever stops being an allow-listed account, every verdict silently stops being inheritable and each later event re-posts `pending` over it — a deadlocked PR whose only diagnostic is a line in a job log. Correct today (verified live 2026-08-26: the token's `/user` login is `timothy`, and the instance has -exactly the accounts `timothy` and `renovate`), but nothing keeps it correct — #845. +exactly the accounts `timothy` and `renovate`), but nothing keeps it correct — #845. There IS a +diagnostic, contrary to an earlier draft of this paragraph: the job emits a `::warning::` naming the +off-list creator whenever it re-derives over a verdict-shaped status. What #845 is about is that the +warning fires in the WORKFLOW RUN, while the mistake is made at the terminal running +`post-review-verdict.sh`, which reports success either way. **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 diff --git a/scripts/tests/test_pr_changed_files.py b/scripts/tests/test_pr_changed_files.py index 4e0810970..a627b5cc4 100644 --- a/scripts/tests/test_pr_changed_files.py +++ b/scripts/tests/test_pr_changed_files.py @@ -1144,6 +1144,20 @@ 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) + print(json.dumps({"statuses": [ + {"context": "review-verdict/h10", "status": pre_state, + "creator": ({"login": pre_creator} if pre_creator else None), + "description": pre_desc}]})) + sys.exit(0) print(empty_statuses()) sys.exit(0) # Configurable creator (ersatztv#742). This site asks "did anything human land while we were @@ -1237,6 +1251,7 @@ def _run_classify( history_mode: str = "none", history_creator: str = "timothy", midrun_creator: str = "timothy", + pre_row: str = "", timeline_terminator: str = "null", status_empty_shape: str = "null", ): @@ -1276,6 +1291,7 @@ def _run_classify( 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.update( { "GITEA_TOKEN": "stub", @@ -1687,22 +1703,20 @@ def test_a_success_with_a_creator_but_an_EXEMPT_description_is_re_derived(tmp_pa # POSTed with it reads back `creator: renovate` — non-null, and therefore inherited as a verdict. -@pytest.mark.parametrize("existing", ["success", "failure"]) @pytest.mark.parametrize("creator", ["renovate", "someone-else"]) -def test_a_verdict_shaped_status_from_a_NON_allowlisted_account_is_RE_DERIVED(tmp_path, creator, existing): +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. - BOTH states, because the short-circuit branches on `success` OR `failure` and an off-list - `failure` is the case that would otherwise deadlock a PR nobody can clear. + `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=f"existing:{existing}", + status_mode="existing:success", status_creator=creator, status_desc="Review-verdict: MERGEABLE @ a9e3e23 (base: main)", ) @@ -1713,6 +1727,39 @@ def test_a_verdict_shaped_status_from_a_NON_allowlisted_account_is_RE_DERIVED(tm assert posted["state"] == "pending" +@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. @@ -1792,6 +1839,37 @@ def test_the_MID_RUN_abstain_still_fires_for_a_NON_allowlisted_creator(tmp_path) ) +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 _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.""" -- 2.47.3 From 2ed3e1895a687130e0d27df746d207aa567afede Mon Sep 17 00:00:00 2001 From: Timothy Date: Wed, 26 Aug 2026 22:53:02 +0200 Subject: [PATCH 05/16] fix(742): state-neutral re-derivation log; qualify the failure clause; guard cited test names MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Round-3 cold state-machine review returned MERGEABLE (no fail-open, no permanent stall, all five clause mutations pinned) with three LOWs, all measured rather than argued. * The re-derivation `echo` asserted 'is NOT an attributable reviewer verdict' on a path also reached by an ALLOW-LISTED creator whose row is in a state other than success/failure — printing "creator='timothy', allow-list='timothy'". The ::warning:: below it was already guarded against exactly that contradiction and the echo was not, which is the same defect one line up. Now state-neutral. * The failure short-circuit's message said an explicit rejection is left alone 'whoever recorded it', but the guard requires attributability: a failure with a non-verdict description, a null creator, or a DIFFERENT recorded base is still re-derived. Message qualified rather than the guard widened — a bare [ state = failure ] would be safe by the clause's own argument, but it would quietly opt `failure` out of the base binding, and none of the excluded shapes is producible by post-review-verdict.sh. Written down so the next reader does not 'simplify' it. * ci.exemption-provenance cited a test that the success/failure split had renamed — a mutation proof nobody could run. Fixed, and the class is now guarded: a new test derives the cited names from the record's own text and asserts each is defined in scripts/tests. Mutation-proven against the pre-fix wording. scripts/tests: 970 passed, 2 skipped. fixes #742 Decisions-Edit: yes --- .gitea/workflows/review-verdict.yml | 16 ++++++++++-- .../records/ci/exemption-provenance.md | 2 +- scripts/tests/test_pr_changed_files.py | 26 +++++++++++++++++++ 3 files changed, 41 insertions(+), 3 deletions(-) diff --git a/.gitea/workflows/review-verdict.yml b/.gitea/workflows/review-verdict.yml index a61bac58e..319aafa00 100644 --- a/.gitea/workflows/review-verdict.yml +++ b/.gitea/workflows/review-verdict.yml @@ -755,13 +755,21 @@ jobs: # 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" ]; 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 explicit rejection is left alone whoever recorded it, because honouring it can only ever withhold an exemption, never grant one." + 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 @@ -796,7 +804,11 @@ jobs: 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 reviewer verdict (creator='${ex_creator:-null}', allow-list='${H10_REVIEWERS}', 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 `::warning::` below is guarded against exactly that contradiction + # and this line was not, which is the same defect one line up. + 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." # ANNOTATE, do not merely log, when the row we are about to overwrite LOOKS like a verdict # from a real account that is simply not on the list (ersatztv#742). On today's account # set that is only `renovate`, whose "verdict" is by definition not one — but the day a diff --git a/docs/decisions/records/ci/exemption-provenance.md b/docs/decisions/records/ci/exemption-provenance.md index 770f1163a..65ccc6723 100644 --- a/docs/decisions/records/ci/exemption-provenance.md +++ b/docs/decisions/records/ci/exemption-provenance.md @@ -178,7 +178,7 @@ implied: any verdict-shaped row landing inside that window trips the STICKY `REP 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_status_from_a_NON_allowlisted_account_is_RE_DERIVED` and +`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 diff --git a/scripts/tests/test_pr_changed_files.py b/scripts/tests/test_pr_changed_files.py index a627b5cc4..ff73c55ec 100644 --- a/scripts/tests/test_pr_changed_files.py +++ b/scripts/tests/test_pr_changed_files.py @@ -1870,6 +1870,32 @@ def test_a_verdict_REPLACING_a_pre_existing_row_mid_run_still_makes_the_job_ABST ) +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" + ) + + 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.""" -- 2.47.3 From 51338b3cb3f6de6b60f6d95caa06f331f434d61a Mon Sep 17 00:00:00 2001 From: Timothy Date: Wed, 26 Aug 2026 23:12:53 +0200 Subject: [PATCH 06/16] test(742): pin the annotation, each triple clause, and multi-entry membership MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Round-3 cold tests/prose review returned BLOCKED. Its findings were all of one shape: the clauses are correct, but the suite could not tell. Measured green with the mechanism DELETED, now each reddens on exactly one test: * deleting the ::warning:: entirely — 166 green. It is not decoration: docs/ci-cd.md heads a paragraph with 'If a reviewer's verdicts stop being honoured, this is why', and ci.exemption-provenance uses its existence to soften the #845 residual. Asserted present in the off-list case, and ABSENT for an allow-listed reviewer, which also pins the ex_human != yes conjunct. * dropping any ONE clause of the changed-row triple, or reducing the triple to a single comparison. Both mid-run tests moved all three fields at once, so 'compare the whole row' was argued, not measured. STUB_MIDRUN_ROW plus one parametrised case per field. * a membership loop that can only ever match its LAST entry. Every behavioural test ran the singleton list, under which that is indistinguishable from a correct loop — and the annotation this change adds tells an operator to ADD a second entry, so the two-entry path is the first one exercised in anger. A reviewers= override substitutes a two-entry literal into the real step body; first-entry, last-entry control and absent-account control. Prose, all measured by the reviewer rather than argued: * 'was inherited as a human verdict' described an event nobody observed — renovate has never posted a commit status in this repo (every row on all six Renovate-authored PR heads carries creator: null). The asymmetry underneath IS measured; the ROUTE is an inference. Conditional voice in all three places, with the distinction stated. * the ::warning:: does not fire for a row recording a DIFFERENT base — the base binding re-derives it before the annotation is reached. 'whenever' was false. * a credential drift re-derives to an exemption success on an exempt PR, not only to pending — the quieter and worse half. * the live account-set measurement now carries its two curl paths. * CLAUDE.md states the H10 convention and now carries the constraint: the credential you post with must be an allow-listed account, or the verdict is written, reported as success, and silently re-derived (#845). * residual session chronology trimmed from the record. STUB_PRE_ROW now emits the measured shape (total_count, a decoy context) rather than a minimal one. scripts/tests: 976 passed, 2 skipped. fixes #742 Decisions-Edit: yes --- .gitea/workflows/review-verdict.yml | 9 +- CLAUDE.md | 2 +- docs/ci-cd.md | 16 +- .../records/ci/exemption-provenance.md | 18 ++- scripts/tests/test_pr_changed_files.py | 153 +++++++++++++++++- 5 files changed, 176 insertions(+), 22 deletions(-) diff --git a/.gitea/workflows/review-verdict.yml b/.gitea/workflows/review-verdict.yml index 319aafa00..8f8ab8452 100644 --- a/.gitea/workflows/review-verdict.yml +++ b/.gitea/workflows/review-verdict.yml @@ -240,7 +240,14 @@ jobs: # 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 was inherited as a human verdict. + # 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 diff --git a/CLAUDE.md b/CLAUDE.md index b53a5fa3a..ae64c44ae 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 ` 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 [note]`** — it posts both the `Review-verdict: … @ ` 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 [note]`** — it posts both the `Review-verdict: … @ ` 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, 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. diff --git a/docs/ci-cd.md b/docs/ci-cd.md index 6719ec395..cce7dacb1 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -1308,7 +1308,10 @@ for accounts that are not reviewers. `RENOVATE_TOKEN` is a `write:repository` PA 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 inherited. Membership makes every non-reviewer account +`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 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. @@ -1345,13 +1348,16 @@ Pinned by `test_the_MID_RUN_abstain_still_fires_for_a_NON_allowlisted_creator` a `test_the_RACED_verdict_check_still_counts_a_NON_allowlisted_creator`. **If a reviewer's verdicts stop being honoured, this is why.** The job emits a `::warning::` naming the -creator whenever it re-derives over a verdict-shaped status from an account that is not on the list; +creator whenever it re-derives over a verdict-shaped status **for this base** from an account not on +the list — a row recording a *different* base is re-derived by the base binding before the annotation +is reached, and gets no warning; add them to `H10_REVIEWERS` in `.gitea/workflows/review-verdict.yml`. `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 verdict to `pending`; 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. +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 diff --git a/docs/decisions/records/ci/exemption-provenance.md b/docs/decisions/records/ci/exemption-provenance.md index 65ccc6723..763c9e1b9 100644 --- a/docs/decisions/records/ci/exemption-provenance.md +++ b/docs/decisions/records/ci/exemption-provenance.md @@ -122,7 +122,11 @@ POSTed with a user credential", and *any* account's credential answered yes. `RE `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 was inherited. +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: every other account, recognised or not, re-derives exactly as an Actions-token status already does. The list is a literal in this base-resolved definition rather than a repo `vars:` entry, because a `vars:` entry is settable without @@ -151,8 +155,7 @@ comparison made that load-bearing where presence alone had not: two POSTs of con `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, and this branch -carried it for a round.** Trace an off-list `failure` under a symmetric rule: a real reviewer left off +**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 @@ -164,8 +167,7 @@ which uses a DOCS-ONLY file list on purpose — with a code file the job posts ` 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". Cold review -showed that is not a checked reason: a genuine reviewer is on `H10_REVIEWERS` by construction, so +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 @@ -189,9 +191,9 @@ would falsify it silently. 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-posts `pending` over it — a deadlocked PR whose only diagnostic is a line in a job log. -Correct today (verified live 2026-08-26: the token's `/user` login is `timothy`, and the instance has -exactly the accounts `timothy` and `renovate`), but nothing keeps it correct — #845. There IS a -diagnostic, contrary to an earlier draft of this paragraph: the job emits a `::warning::` naming the +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). There IS a diagnostic: the job emits a `::warning::` naming the off-list creator whenever it re-derives over a verdict-shaped status. What #845 is about is that the warning fires in the WORKFLOW RUN, while the mistake is made at the terminal running `post-review-verdict.sh`, which reports success either way. diff --git a/scripts/tests/test_pr_changed_files.py b/scripts/tests/test_pr_changed_files.py index ff73c55ec..efbf9107e 100644 --- a/scripts/tests/test_pr_changed_files.py +++ b/scripts/tests/test_pr_changed_files.py @@ -1153,20 +1153,39 @@ if "/status" in url: pre = os.environ.get("STUB_PRE_ROW", "") if pre: pre_creator, pre_state, pre_desc = pre.split("|", 2) - print(json.dumps({"statuses": [ + # 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}]})) + "description": pre_desc}, + ] + print(json.dumps({"state": "pending", "total_count": len(rows), "statuses": rows})) sys.exit(0) print(empty_statuses()) sys.exit(0) # 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. - print(json.dumps({"statuses": [ - {"context": "review-verdict/h10", "status": "failure", - "creator": {"login": os.environ.get("STUB_MIDRUN_CREATOR", "timothy")}, - "description": "Review-verdict: BLOCKED @ a9e3e23 (base: main)"}]})) + # 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 @@ -1252,6 +1271,8 @@ def _run_classify( 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", ): @@ -1292,6 +1313,7 @@ def _run_classify( 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", @@ -1311,7 +1333,16 @@ 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 @@ -1725,6 +1756,15 @@ def test_a_verdict_shaped_SUCCESS_from_a_NON_allowlisted_account_is_RE_DERIVED(t f"read as 'a reviewer wrote this'. Log:\n{r.stdout[-900:]}" ) assert posted["state"] == "pending" + # THE ANNOTATION IS PART OF THE CONTRACT, not decoration. `docs/ci-cd.md` heads a paragraph with + # "If a reviewer's verdicts stop being honoured, this is why", and `ci.exemption-provenance` uses + # its existence to soften the #845 residual — so a tidy-up that deletes it must redden something. + # Cold review measured that deleting it left the whole suite green. + assert "::warning::" in r.stdout and "NOT in H10_REVIEWERS" in r.stdout, ( + "no ::warning:: was emitted while re-deriving over a verdict-shaped status from an off-list " + f"account — the only signal a real reviewer's reviews are being discarded. Log:\n{r.stdout[-1200:]}" + ) + assert creator in r.stdout, "the annotation does not name the account whose verdict was discarded" @pytest.mark.parametrize("creator", ["renovate", "someone-else"]) @@ -1896,6 +1936,98 @@ def test_every_test_name_cited_by_the_exemption_provenance_record_EXISTS(): ) +_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" + ) + + 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.""" @@ -1985,6 +2117,13 @@ 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" ) + # The MIRROR of the annotation assertion in the off-list test: it must NOT fire for an + # allow-listed reviewer. This is what pins the `ex_human != yes` conjunct — without it the + # annotation reads "from 'timothy', which is NOT in H10_REVIEWERS ('timothy')", a diagnostic that + # contradicts itself and trains the reader to ignore it. + assert "NOT in H10_REVIEWERS" not in r.stdout, ( + f"the off-list annotation fired for an ALLOW-LISTED creator. Log:\n{r.stdout[-1200:]}" + ) def test_a_PENDING_status_from_a_previous_run_is_replaced_normally(tmp_path): -- 2.47.3 From 10e3cba4869b6803101dabc2121048fb7a7ec041 Mon Sep 17 00:00:00 2001 From: Timothy Date: Thu, 27 Aug 2026 00:07:43 +0200 Subject: [PATCH 07/16] fix(742): withdraw the ::warning:: annotation; correct the bash quoting claim MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Round-4 cold review found the annotation's `ex_human != yes` conjunct was the diff's only GREEN mutation, and that the assertion captioned as pinning it could not fail: both parametrizations of that test exit at a short-circuit two guards earlier and never reach the block at all. A caption claiming a proof is worse than no assertion. WITHDRAWN rather than patched a third time. That mechanism produced three defects in three rounds — a message reading "from 'timothy', which is NOT in H10_REVIEWERS ('timothy')", an unescaped API value interpolated into a workflow command, and now a vacuous pin — and it duplicated all three values from the plain log line one line above it. Its only delta was a severity whose rendering could not be probed. Deleting it removes the green mutation, ~28 comment lines, the vacuous assertion and a docs paragraph that had promoted it to a contract. The log line keeps the whole diagnostic and gains the remediation sentence, and its three parts are now asserted on a path the job always reaches. Both halves mutation-proven: dropping the remediation reddens, and so does dropping the allow-list VALUE — an earlier assertion tested for the WORD `H10_REVIEWERS`, which the remediation sentence satisfies on its own, so that deletion had stayed green. Also: the comment justifying POSIX `[ = ]` claimed `[[ == ]]` makes its RHS a pattern. Probed on bash 5.3 — with a QUOTED RHS it does not; only an unquoted one globs. The invariant is the quoting, and it is now stated as that, with the untestability claim (which rested on the false premise) dropped. Round-by-round narrative trimmed out of the code comments per docs.no-session-narrative; the rules those blocks carry stay, the chronology moves to the PR. fixes #742 Decisions-Edit: yes --- .gitea/workflows/review-verdict.yml | 70 ++++++++----------- docs/ci-cd.md | 11 +-- .../records/ci/exemption-provenance.md | 12 ++-- scripts/tests/test_pr_changed_files.py | 38 ++++++---- 4 files changed, 66 insertions(+), 65 deletions(-) diff --git a/.gitea/workflows/review-verdict.yml b/.gitea/workflows/review-verdict.yml index 8f8ab8452..6b91a9210 100644 --- a/.gitea/workflows/review-verdict.yml +++ b/.gitea/workflows/review-verdict.yml @@ -528,10 +528,10 @@ jobs: # INHERITANCE short-circuit, where narrowing is safe because an # unrecognised account falls through to re-derivation. # - # The first draft of #742 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 post-write repair does NOT cover that regression, because it is skipped - # whenever the high-water mark could not be established (`max_id_before=-1`). + # 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 @@ -585,12 +585,14 @@ jobs: # DERIVED LAST, so the base check above governs both flags and cannot be bypassed by # membership. # - # POSIX `[ = ]`, NEVER `[[ == ]]` and never `grep -xF`. `[[ == ]]` makes its right-hand - # side a PATTERN, which would reintroduce the glob exposure the literal is linted against; - # `grep` would read a newline-bearing `$ex_creator` as SEVERAL patterns, any one of which - # could match an allow-listed line. `[ = ]` compares the whole value, literally. (No test - # can see a `[ = ]` -> `[[ == ]]` regression, because Gitea logins cannot contain a glob - # metacharacter — hence this comment rather than a test that would pass either way.) + # 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 @@ -747,8 +749,8 @@ jobs: # 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 this branch carried for one round before cold review caught it - # (ersatztv#742). Trace the symmetric version on an off-list `failure`: the head carries + # 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 @@ -813,33 +815,19 @@ jobs: if [ -n "$ex_state" ]; then # 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 `::warning::` below is guarded against exactly that contradiction - # and this line was not, which is the same defect one line up. - 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." - # ANNOTATE, do not merely log, when the row we are about to overwrite LOOKS like a verdict - # from a real account that is simply not on the list (ersatztv#742). On today's account - # set that is only `renovate`, whose "verdict" is by definition not one — but the day a - # second human account is added to the repo and forgotten from the literal, this is the - # ONLY signal that their reviews are being silently discarded. Emitted as a workflow - # WARNING rather than a bare `echo` so it carries a severity and is greppable; how Gitea - # 1.27 RENDERS a `::warning::` is deliberately NOT claimed — an earlier draft asserted it - # surfaces on the run summary and never probed it. + # unattributable. # - # `ex_human != yes` is REQUIRED, not belt-and-braces: control also reaches here for an - # ALLOW-LISTED creator whose row is in some state other than `success`/`failure`, and - # without it the annotation reads "from 'timothy', which is NOT in H10_REVIEWERS - # ('timothy')" — a diagnostic that contradicts itself trains the reader to ignore it. - # (`[ -n "$ex_creator" ]` is NOT also tested: `ex_attributable=yes` is reachable only - # through a branch that already required it.) - # - # CR/LF stripped before interpolation. The value is API-supplied, and the untrustedness - # this file argues for the membership comparison has a sharper edge here: a newline inside - # a `::warning::` line would start a SECOND workflow command. Unreachable through Gitea's - # username validation; stripped anyway, because the cost is one parameter expansion. - if [ "$ex_attributable" = yes ] && [ "$ex_human" != yes ]; then - ex_creator_1line=${ex_creator//[$'\r\n']/ } - echo "::warning::${CONTEXT} on ${SHA:0:7} carries a verdict-shaped status from '${ex_creator_1line}', which is NOT in H10_REVIEWERS ('${H10_REVIEWERS}') — it is being re-derived, not honoured. If '${ex_creator_1line}' is a reviewer, add them to H10_REVIEWERS in .gitea/workflows/review-verdict.yml; otherwise this is the intended refusal." - fi + # 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. ------------------------- @@ -1162,10 +1150,10 @@ jobs: # 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. Cold review caught that as an asserted-but-unchecked - # reason and it is not repeated. + # overwrote a few lines earlier. That reason is stated here only to be refused, because + # it is the one that looks obviously right. # - # THE REAL REASON is the misconfiguration case, which is the only way an off-list row is + # 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. This is the LAST net before a green stands, and the two errors are not # symmetric — repairing to `pending` is recoverable by re-posting the verdict, while a diff --git a/docs/ci-cd.md b/docs/ci-cd.md index cce7dacb1..46ba87adf 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -1347,11 +1347,12 @@ membership). 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.** The job emits a `::warning::` naming the -creator whenever it re-derives over a verdict-shaped status **for this base** from an account not on -the list — a row recording a *different* base is re-derived by the base binding before the annotation -is reached, and gets no warning; -add them to `H10_REVIEWERS` in `.gitea/workflows/review-verdict.yml`. `post-review-verdict.sh` posts +**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 diff --git a/docs/decisions/records/ci/exemption-provenance.md b/docs/decisions/records/ci/exemption-provenance.md index 763c9e1b9..1602bfe19 100644 --- a/docs/decisions/records/ci/exemption-provenance.md +++ b/docs/decisions/records/ci/exemption-provenance.md @@ -193,10 +193,14 @@ ever stops being an allow-listed account, every verdict silently stops being inh later event re-posts `pending` over it — a deadlocked PR whose 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). There IS a diagnostic: the job emits a `::warning::` naming the -off-list creator whenever it re-derives over a verdict-shaped status. What #845 is about is that the -warning fires in the WORKFLOW RUN, while the mistake is made at the terminal running -`post-review-verdict.sh`, which reports success either way. +(#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 diff --git a/scripts/tests/test_pr_changed_files.py b/scripts/tests/test_pr_changed_files.py index efbf9107e..14b0c35f8 100644 --- a/scripts/tests/test_pr_changed_files.py +++ b/scripts/tests/test_pr_changed_files.py @@ -1756,15 +1756,25 @@ def test_a_verdict_shaped_SUCCESS_from_a_NON_allowlisted_account_is_RE_DERIVED(t f"read as 'a reviewer wrote this'. Log:\n{r.stdout[-900:]}" ) assert posted["state"] == "pending" - # THE ANNOTATION IS PART OF THE CONTRACT, not decoration. `docs/ci-cd.md` heads a paragraph with - # "If a reviewer's verdicts stop being honoured, this is why", and `ci.exemption-provenance` uses - # its existence to soften the #845 residual — so a tidy-up that deletes it must redden something. - # Cold review measured that deleting it left the whole suite green. - assert "::warning::" in r.stdout and "NOT in H10_REVIEWERS" in r.stdout, ( - "no ::warning:: was emitted while re-deriving over a verdict-shaped status from an off-list " - f"account — the only signal a real reviewer's reviews are being discarded. Log:\n{r.stdout[-1200:]}" + # 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, ( + "the diagnostic does not name the account whose verdict was discarded. " + f"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:]}" ) - assert creator in r.stdout, "the annotation does not name the account whose verdict was discarded" @pytest.mark.parametrize("creator", ["renovate", "someone-else"]) @@ -2117,13 +2127,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" ) - # The MIRROR of the annotation assertion in the off-list test: it must NOT fire for an - # allow-listed reviewer. This is what pins the `ex_human != yes` conjunct — without it the - # annotation reads "from 'timothy', which is NOT in H10_REVIEWERS ('timothy')", a diagnostic that - # contradicts itself and trains the reader to ignore it. - assert "NOT in H10_REVIEWERS" not in r.stdout, ( - f"the off-list annotation fired for an ALLOW-LISTED creator. Log:\n{r.stdout[-1200:]}" - ) + # 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): -- 2.47.3 From 59fc9c9607423136b4ccf276575d5994c0f0e9b5 Mon Sep 17 00:00:00 2001 From: Timothy Date: Thu, 27 Aug 2026 00:30:27 +0200 Subject: [PATCH 08/16] fix(742): pin the failure clause's attributability; scope the docs to an inherited success MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cold CROSS-FAMILY review (Codex/GPT-5.6), the first this branch has had — the earlier four rounds were all one model family. * The `failure` short-circuit's attributability requirement was NOT pinned. Every existing `failure` case supplied a well-formed, base-matching, non-null-creator row, so widening the clause to a bare [ "$ex_state" = failure ] passed the whole suite — the exact widening the comment at the site says is deliberately not done, because it would opt `failure` out of the base binding. Three cases now cover a null creator, a non-verdict description and a verdict recorded against ANOTHER base; all three redden on that mutation. * The docs described the allow-list more broadly than the code implements it: an existing `failure` is left alone on the weaker attributability test and needs no membership. Scoped to an inherited `success` in docs/ci-cd.md, ci.exemption-provenance (rule + body) and CLAUDE.md, with the exception stated rather than left implicit. Its three BLOCKERs are REAL but PRE-EXISTING, and filed as #849 rather than fixed here: an unestablished high-water mark skips the post-write race check; an unreadable post-write history leaves the green; and the check runs only for state=success, so a generic `pending` write can bury a rejection a later run then greens. Verified by diff against origin/main — those three guards are byte-identical and this change touches none of them. #742 is a provenance change; those are the post-write verification's own residuals, and burying them in a passing review would be the worst outcome. Recorded in the record, not just the issue. scripts/tests: 1012 passed, 2 skipped. fixes #742 Decisions-Edit: yes --- CLAUDE.md | 2 +- docs/ci-cd.md | 16 ++++---- docs/decisions/README.md | 2 +- .../records/ci/exemption-provenance.md | 18 +++++++-- scripts/tests/test_pr_changed_files.py | 38 +++++++++++++++++++ 5 files changed, 63 insertions(+), 13 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index ae64c44ae..84f8f0e21 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 ` 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 [note]`** — it posts both the `Review-verdict: … @ ` 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, 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). +- `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 [note]`** — it posts both the `Review-verdict: … @ ` 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 a rejection is never re-derived into a green), 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. diff --git a/docs/ci-cd.md b/docs/ci-cd.md index 46ba87adf..7c0b9a507 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -1293,11 +1293,13 @@ 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 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. (Measured: a status POSTed with a user credential carries a creator; one POSTed by an +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. @@ -1311,8 +1313,8 @@ PR-added workflow can reference it and POST a `Review-verdict:` success that rea `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 -re-derive exactly as an Actions-token status does. The list is a **literal in the workflow**, not a +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. diff --git a/docs/decisions/README.md b/docs/decisions/README.md index ef0f0184e..a99fa1d33 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -46,7 +46,7 @@ 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/` 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 an APPROVED REVIEWER's verdict for THIS base, meaning a `.creator.login` that is a member of the workflow's `H10_REVIEWERS` allow-list — 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: )` 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: )` 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.format-gate-folder-mode` | The blocking `format` CI job (and matching pre-commit hook) runs `dotnet format whitespace . --folder --include ` 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 (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) | diff --git a/docs/decisions/records/ci/exemption-provenance.md b/docs/decisions/records/ci/exemption-provenance.md index 1602bfe19..3515b5f50 100644 --- a/docs/decisions/records/ci/exemption-provenance.md +++ b/docs/decisions/records/ci/exemption-provenance.md @@ -5,8 +5,8 @@ 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 an APPROVED REVIEWER''s verdict for THIS base, meaning a `.creator.login` that is a member of the workflow''s `H10_REVIEWERS` allow-list — 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: )` 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: '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: #845, #742, #698, #697, #672, #663, #649, #632' +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: )` 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: '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 ` (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 `[[ == ]]` (RHS becomes a pattern) 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]`' --- @@ -127,8 +127,9 @@ inheritable. **Inferred from a measurement, not an observed event:** the user-cr 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: every other account, recognised or not, -re-derives exactly as an Actions-token status already does. The list is a literal in this +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. @@ -187,6 +188,15 @@ inheritance cases respectively. Counts are deliberately not quoted: `test_pr_cha graded `PROOF | NONE`, so nothing re-executes a number written here and one added `parametrize` case would falsify it silently. +**Three post-write residuals this change does NOT touch, tracked as #849.** A cold cross-family review +of the #742 branch found three routes by which an exemption `success` ends up standing over a human +`failure`: an unestablished high-water mark SKIPS the post-write race check entirely; an unreadable +post-write history leaves the green explicitly ("The exemption … stands"); and the check runs only for +`state = success`, so a generic `pending` write can bury a rejection that a later run then greens. +Verified PRE-EXISTING — those three guards are byte-identical to the tree before this change, which +touches none of them. Filed rather than fixed here because #742 is a provenance change and these are +the post-write verification's own residuals; the fence's post-POST gap is in the same issue. + **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 diff --git a/scripts/tests/test_pr_changed_files.py b/scripts/tests/test_pr_changed_files.py index 14b0c35f8..084615591 100644 --- a/scripts/tests/test_pr_changed_files.py +++ b/scripts/tests/test_pr_changed_files.py @@ -2038,6 +2038,44 @@ def test_an_account_on_NEITHER_entry_is_still_re_derived(tmp_path): ) +@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.""" -- 2.47.3 From 1b90e32687eaec0adc9be353ca28498799133855 Mon Sep 17 00:00:00 2001 From: Timothy Date: Thu, 27 Aug 2026 00:51:08 +0200 Subject: [PATCH 09/16] fix(742): an exemption whose write cannot be verified is not granted MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cross-family RE-review of the previous fix round. Its sharpest point: my claim that the three post-write residuals were 'pre-existing, #742 touches none of them' was only TEXTUALLY true. The guards are byte-identical to main, but this change alters their REACHABILITY — before it, an attributable `success` from ANY account short-circuited and the job wrote NOTHING, so the unverified-write paths were unreachable for that whole class of head. Re-deriving an off-list `success` is the POINT of #742, and it turns 'no write' into 'a write'. Two of the three therefore belong here, not in the follow-up: * An UNESTABLISHED high-water mark now WITHHOLDS the exemption. The post-write race check is the only thing between 'a reviewer posted failure during our write window' and a green over a rejection, and it is skipped outright when the mark is missing — so the run asks for a verdict instead of posting a green it cannot verify. * An UNREADABLE post-write history now REPAIRS to the sticky sentinel instead of logging 'The exemption … stands' and doing so. Same uncertainty the page-2 probe already resolves to raced=1; which of the two reads failed is not a difference in what is KNOWN. The repair `case` is hoisted out of the readable branch so both converge on it. Both cost the run its exemption on a transient API failure — the price this file already pays for the same reason in #751's page-2 rule, recoverable in one command, where a green over a rejection is not. Mutation-proven: restoring either old behaviour reddens its test. The withholding guard sits AFTER the mark is established, not with the classification. $max_id_before does not exist there and referencing it early is an unbound variable under set -u — the step dies and every PR is stranded with no status. My first placement did exactly that: 39 tests red. Found by running it, not by reading it. #849 keeps the third route (post-write verification runs only for state=success, so a generic pending write can bury a rejection) and the fence's post-POST gap, with its reachability from this change's class stated rather than dismissed. scripts/tests: 1014 passed, 2 skipped. fixes #742 Decisions-Edit: yes --- .gitea/workflows/review-verdict.yml | 91 ++++++++++++++----- .../records/ci/exemption-provenance.md | 33 +++++-- scripts/tests/test_pr_changed_files.py | 60 ++++++++++++ 3 files changed, 151 insertions(+), 33 deletions(-) diff --git a/.gitea/workflows/review-verdict.yml b/.gitea/workflows/review-verdict.yml index 6b91a9210..f2c40d8a3 100644 --- a/.gitea/workflows/review-verdict.yml +++ b/.gitea/workflows/review-verdict.yml @@ -1003,6 +1003,32 @@ jobs: max_id_before=-1 fi + # AN EXEMPTION IS ONLY GRANTED WHEN THE WRITE CAN BE VERIFIED AFTERWARDS (ersatztv#742). + # Placed HERE, not with the classification above, because that is where `$max_id_before` + # first exists — referencing it earlier is an unbound variable under `set -u`, which kills + # the step and strands every PR with no status. (Found by execution, not by reading.) + # + # The post-write race check is the only thing between "a reviewer posted `failure` during + # our write window" and a green over a rejection, and it is SKIPPED whenever the mark could + # not be established. So an exemption whose write cannot be verified is not granted at all. + # + # WHY THIS BECAME THIS CHANGE'S PROBLEM though the skip is older than it: before #742 an + # attributable `success` from ANY account short-circuited and this job wrote NOTHING, so the + # unverifiable-write path was unreachable for that whole class of head. Re-deriving an + # off-list `success` is the POINT of #742, and it turns "no write" into "a write" — which is + # what exposes the residual. A guard being byte-identical to the previous tree does not make + # its REACHABILITY unchanged; cross-family review made that argument and it is correct. + # + # The cost is the one this file already accepts for the same reason (#751's page-2 rule): a + # transient history-read failure costs that run its exemption and asks for a verdict. + # Recoverable in one command; a green over a rejection is not. It does NOT touch the + # `$REPAIR_DESC` sentinel path, which is already `pending`. + if [ "$state" = "success" ] && [ "$max_id_before" -lt 0 ]; then + echo "::warning::${CONTEXT} on ${SHA:0:7} qualified for an exemption, but no status high-water mark could be established, so a verdict landing during the write window could not be detected afterwards. Withholding the exemption and asking for a verdict instead." + state=pending + desc="Awaiting review verdict for ${SHA:0:7}" + fi + # LAST-MOMENT RE-READ (ersatztv#706). Classification takes several API round-trips, and a # reviewer can post a verdict during them — most dangerously a `failure`, which this job would # then overwrite with an exemption `success`, turning an explicit human rejection green. The @@ -1134,8 +1160,18 @@ jobs: # It is reported loudly and left alone — the residual is the read/POST gap either way. if [ "$state" = "success" ] && [ "$max_id_before" -ge 0 ]; then post_hist=$(gh "$BASE_URL/repos/$REPO/statuses/$SHA?limit=100") || post_hist="" + raced=0 if [ -z "${post_hist//[[:space:]]/}" ] || ! printf '%s' "$post_hist" | jq -e 'type == "array"' >/dev/null 2>&1; then - echo "::warning::Could not re-read the status history for ${SHA:0:7} after posting, so a human verdict landing during the write window would not be detected. The exemption ${CONTEXT}=success stands." + # AN UNREADABLE HISTORY IS "COULD NOT TELL", AND COULD-NOT-TELL MUST NOT RESOLVE TO GREEN + # (ersatztv#742). This branch used to log "The exemption … stands" and do exactly that — + # an unverified green over a possible rejection, on the one path whose failure direction + # is toward SUCCESS. It is the same uncertainty the page-2 probe below already resolves + # to `raced=1`; which of the two reads failed is not a difference in what is known. + # + # Reachability again: before #742 an attributable off-list `success` short-circuited and + # no write happened, so this branch was unreachable for that class of head. + echo "::warning::Could not re-read the status history for ${SHA:0:7} after posting, so a verdict landing during the write window cannot be ruled out. Repairing to pending rather than leaving an unverified exemption green." + raced=1 else # `.id > $since` is what confines this to the write window. Our OWN row is excluded twice # over — it carries `creator: null` (an Actions-token POST, measured; see the provenance @@ -1218,34 +1254,39 @@ jobs: esac fi fi - case "$raced" in - ''|*[!0-9]*) - echo "::warning::Post-write verification for ${SHA:0:7} returned '${raced}' instead of a count; not acting on it." - ;; - *) - if [ "$raced" -gt 0 ]; then - # The last-moment re-read found no human verdict, so any row present now was - # written during the window and has just been masked by the exemption above. - echo "::error::A human ${CONTEXT} verdict landed on ${SHA:0:7} while this job was writing its exemption, and was overwritten. Downgrading to 'pending' so an explicit human decision cannot be silently green. Re-post it with: scripts/post-review-verdict.sh ${PR} " - repair=$(jq -n --arg c "$CONTEXT" --arg u "$PR_URL" --arg d "$REPAIR_DESC" \ - '{state:"pending", context:$c, description:$d, target_url:$u}') - # A failure HERE leaves the forged green standing, so it is retried once and then - # screams. `set -e` would otherwise kill the job silently, after the success was - # written and with nothing left to re-attempt. + fi + # THE REPAIR IS SHARED BY BOTH BRANCHES (ersatztv#742). It used to sit inside the `else`, + # so the unreadable-history branch could not reach it however it set `raced` — which is + # why that branch had nothing to do but log and leave the green. The read-shape `if` now + # closes first, so "the history says a verdict raced us" and "the history could not be + # read" converge on the same sticky `pending`. + case "$raced" in + ''|*[!0-9]*) + echo "::warning::Post-write verification for ${SHA:0:7} returned '${raced}' instead of a count; not acting on it." + ;; + *) + if [ "$raced" -gt 0 ]; then + # The last-moment re-read found no human verdict, so any row present now was + # written during the window and has just been masked by the exemption above. + echo "::error::A human ${CONTEXT} verdict landed on ${SHA:0:7} while this job was writing its exemption, and was overwritten. Downgrading to 'pending' so an explicit human decision cannot be silently green. Re-post it with: scripts/post-review-verdict.sh ${PR} " + repair=$(jq -n --arg c "$CONTEXT" --arg u "$PR_URL" --arg d "$REPAIR_DESC" \ + '{state:"pending", context:$c, description:$d, target_url:$u}') + # A failure HERE leaves the forged green standing, so it is retried once and then + # screams. `set -e` would otherwise kill the job silently, after the success was + # written and with nothing left to re-attempt. + if ! gh -X POST -H 'Content-Type: application/json' -d "$repair" \ + "$BASE_URL/repos/$REPO/statuses/$SHA" >/dev/null 2>&1; then if ! gh -X POST -H 'Content-Type: application/json' -d "$repair" \ "$BASE_URL/repos/$REPO/statuses/$SHA" >/dev/null 2>&1; then - if ! gh -X POST -H 'Content-Type: application/json' -d "$repair" \ - "$BASE_URL/repos/$REPO/statuses/$SHA" >/dev/null 2>&1; then - echo "::error::COULD NOT REPAIR ${CONTEXT} on ${SHA:0:7}. An exemption 'success' is standing on a head whose human verdict was overwritten. Post the verdict again immediately: scripts/post-review-verdict.sh ${PR} " - exit 1 - fi + echo "::error::COULD NOT REPAIR ${CONTEXT} on ${SHA:0:7}. An exemption 'success' is standing on a head whose human verdict was overwritten. Post the verdict again immediately: scripts/post-review-verdict.sh ${PR} " + exit 1 fi - echo "Repaired ${CONTEXT} to pending on ${SHA:0:7}." - state=pending fi - ;; - esac - fi + echo "Repaired ${CONTEXT} to pending on ${SHA:0:7}." + state=pending + fi + ;; + esac fi if [ "$state" = "pending" ]; then diff --git a/docs/decisions/records/ci/exemption-provenance.md b/docs/decisions/records/ci/exemption-provenance.md index 3515b5f50..eea8e040e 100644 --- a/docs/decisions/records/ci/exemption-provenance.md +++ b/docs/decisions/records/ci/exemption-provenance.md @@ -188,14 +188,31 @@ inheritance cases respectively. Counts are deliberately not quoted: `test_pr_cha graded `PROOF | NONE`, so nothing re-executes a number written here and one added `parametrize` case would falsify it silently. -**Three post-write residuals this change does NOT touch, tracked as #849.** A cold cross-family review -of the #742 branch found three routes by which an exemption `success` ends up standing over a human -`failure`: an unestablished high-water mark SKIPS the post-write race check entirely; an unreadable -post-write history leaves the green explicitly ("The exemption … stands"); and the check runs only for -`state = success`, so a generic `pending` write can bury a rejection that a later run then greens. -Verified PRE-EXISTING — those three guards are byte-identical to the tree before this change, which -touches none of them. Filed rather than fixed here because #742 is a provenance change and these are -the post-write verification's own residuals; the fence's post-POST gap is in the same issue. +**A guard being byte-identical does not make its REACHABILITY unchanged, and two post-write residuals +had to be fixed here because of it.** Cold cross-family review found three routes by which an exemption +`success` ends up standing over a human `failure`, and the first response — "pre-existing, filed as +#849" — was only *textually* right. 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 unverified-write paths. So: + +- **An unestablished high-water mark now WITHHOLDS the exemption** rather than posting it and skipping + verification. The post-write race check is the only thing between "a reviewer posted `failure` during + our write window" and a green over a rejection, and it is skipped outright when the mark is missing. +- **An unreadable post-write history now REPAIRS to the sticky sentinel** rather than logging "The + exemption … stands" and doing so. It is the same uncertainty the page-2 probe already resolves to + `raced=1`; which of the two reads failed is not a difference in what is known. The repair `case` was + hoisted out of the readable branch so both converge on it. + +Both cost the run its exemption on a transient API failure — the price this file already pays for the +same reason in #751's page-2 rule, and recoverable in one command, where a green over a rejection is +not. The guard is placed after the mark is established, not with the classification: `$max_id_before` +does not exist there, and referencing it early is an unbound variable under `set -u` that kills the +step and strands every PR with no status (found by execution, not by reading). + +**The third route stays in #849**, with its reachability stated rather than dismissed: post-write +verification runs only for `state = success`, so a generic `pending` write can bury a rejection a later +run then greens — reachable from this change's class too. The retarget fence's post-POST gap is in the +same issue. **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 diff --git a/scripts/tests/test_pr_changed_files.py b/scripts/tests/test_pr_changed_files.py index 084615591..6601201ba 100644 --- a/scripts/tests/test_pr_changed_files.py +++ b/scripts/tests/test_pr_changed_files.py @@ -1013,6 +1013,21 @@ if "/timeline" in url: if "/statuses/" in url: mode = os.environ.get("STUB_HISTORY_MODE", "none") + # TRANSPORT FAILURES ON THIS ENDPOINT, placed ahead of the page logic because they apply to every + # page (ersatztv#742). `unreadable` fails EVERY read, so no high-water mark can be established; + # `post-read-unreadable` lets the mark be taken and then fails the POST-WRITE read, which is a + # different branch with a different safe answer. + if mode == "unreadable": + sys.exit(22) + if mode == "post-read-unreadable": + ctr = out / "history_reads.txt" + seen = int(ctr.read_text()) if ctr.exists() else 0 + ctr.write_text(str(seen + 1)) + if seen > 0: + sys.exit(22) + print(json.dumps([])) + sys.exit(0) + # PAGE, honoured. THE REASON IS THE TERMINATOR, NOT THE COUNTERS — and that distinction was itself # a finding (#751 round 5). An earlier version of this comment said the guard sits ahead of the # read-counting modes "so the page-2 probe cannot shift 'raced row appears on read N'", by analogy @@ -2076,6 +2091,51 @@ def test_an_UNATTRIBUTABLE_failure_is_still_RE_DERIVED(tmp_path, shape, creator, assert posted["state"] == "success" +def test_an_UNESTABLISHED_high_water_mark_WITHHOLDS_the_exemption(tmp_path): + """An exemption whose write cannot be VERIFIED afterwards is not granted (ersatztv#742). + + The post-write race check is the only thing between "a reviewer posted `failure` during our write + window" and a green over a rejection, and it is skipped outright when no high-water mark could be + established. Before #742 that was unreachable for a head carrying an attributable off-list + `success` — the job short-circuited and wrote nothing at all. Re-deriving that row is the POINT of + #742, and it turns "no write" into "a write", which is what exposes the residual. + + Docs-only, so the run WOULD have posted an exemption `success` had the mark been available; + without that pairing a passing test would prove only that nothing was exempted for some other + reason. + """ + posted, r = _run_classify(tmp_path, _emitting("docs/a.md"), history_mode="unreadable") + assert r.returncode == 0, r.stderr + assert posted is not None, f"the job posted no status at all: {r.stderr}" + assert posted["state"] == "pending", ( + "an exemption `success` was granted on a head where the post-write race check could not be " + f"armed, so a raced rejection could not have been detected. Log:\n{r.stdout[-1200:]}" + ) + + +def test_an_UNREADABLE_post_write_history_REPAIRS_rather_than_leaving_the_green(tmp_path): + """"Could not tell" must not resolve to green — the other half of the same rule. + + Here the mark IS established, the exemption IS posted, and then the post-write read fails. That + branch used to log "The exemption … stands" and do exactly that: an unverified green over a + possible rejection, on the one path whose failure direction is toward SUCCESS. It is the same + uncertainty the page-2 probe already resolves to `raced=1`; which of the two reads failed is not a + difference in what is known. + """ + posted, r = _run_classify(tmp_path, _emitting("docs/a.md"), history_mode="post-read-unreadable") + assert r.returncode == 0, r.stderr + seq = _posted_sequence(tmp_path) + assert len(seq) == 2, ( + "expected the exemption write followed by a repair; the unreadable post-write history left " + f"the green standing. Posts: {seq}. Log:\n{r.stdout[-1200:]}" + ) + assert seq[0]["state"] == "success" + assert seq[1]["state"] == "pending" + assert seq[1]["description"].startswith("Human verdict raced"), ( + f"the repair did not write the sticky sentinel, so a later run would re-derive it: {seq[1]}" + ) + + 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.""" -- 2.47.3 From ae8279e375d12111b0a09daef0f55f2afc14a82c Mon Sep 17 00:00:00 2001 From: Timothy Date: Thu, 27 Aug 2026 01:10:17 +0200 Subject: [PATCH 10/16] revert(742): withdraw the post-write fixes; correct the retarget fence's transient claim MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Seventh review round. The previous commit's two post-write fixes are WITHDRAWN — re-review showed the fix was worse than the gap on both counts, and my own rule applies: two defects from one mechanism means withdraw, not patch a third time. * 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 needs a distinct STICKY 'unverified write' sentinel — a new state in a machine that already has three. * That pending has NO RETRY PATH. Verified: review-verdict.yml triggers only on pull_request_target types, with no schedule and no workflow_dispatch. A transient API failure on a PR's LAST event therefore stalls an exempt PR 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 I called it a one-run cost, which it is not. The workflow and its tests are restored byte-for-byte to the previous commit's state; the whole of post-write verification goes back to #849, which now also carries two further routes the same round found (a malformed status row makes the verifier's jq error out under set -e, skipping the repair; and an unreadable combined-status read leaves a pre-existing off-list success standing, with the job's own red not being a required check). Also corrects ci.verdict-write-retarget-fence, whose 'What is NOT closed' said the post-POST gap yields only a TRANSIENT forged green because the retarget fires an `edited` event. That assumes the successor finishes last. It need not: the successor can start, see the base-matching failure, short-circuit and write nothing, CONSUMING the event — after which the stale run posts its success last and nothing remains to correct it. Permanent, not transient, and now stated so. What #742 itself does is unbroken after seven rounds. What it changes is the REACHABILITY of these residuals, and that is recorded in ci.exemption-provenance rather than left implicit. scripts/tests: 1012 passed, 2 skipped. fixes #742 Decisions-Edit: yes --- .gitea/workflows/review-verdict.yml | 91 +++++-------------- .../records/ci/exemption-provenance.md | 44 ++++----- .../ci/verdict-write-retarget-fence.md | 16 +++- scripts/tests/test_pr_changed_files.py | 60 ------------ 4 files changed, 60 insertions(+), 151 deletions(-) diff --git a/.gitea/workflows/review-verdict.yml b/.gitea/workflows/review-verdict.yml index f2c40d8a3..6b91a9210 100644 --- a/.gitea/workflows/review-verdict.yml +++ b/.gitea/workflows/review-verdict.yml @@ -1003,32 +1003,6 @@ jobs: max_id_before=-1 fi - # AN EXEMPTION IS ONLY GRANTED WHEN THE WRITE CAN BE VERIFIED AFTERWARDS (ersatztv#742). - # Placed HERE, not with the classification above, because that is where `$max_id_before` - # first exists — referencing it earlier is an unbound variable under `set -u`, which kills - # the step and strands every PR with no status. (Found by execution, not by reading.) - # - # The post-write race check is the only thing between "a reviewer posted `failure` during - # our write window" and a green over a rejection, and it is SKIPPED whenever the mark could - # not be established. So an exemption whose write cannot be verified is not granted at all. - # - # WHY THIS BECAME THIS CHANGE'S PROBLEM though the skip is older than it: before #742 an - # attributable `success` from ANY account short-circuited and this job wrote NOTHING, so the - # unverifiable-write path was unreachable for that whole class of head. Re-deriving an - # off-list `success` is the POINT of #742, and it turns "no write" into "a write" — which is - # what exposes the residual. A guard being byte-identical to the previous tree does not make - # its REACHABILITY unchanged; cross-family review made that argument and it is correct. - # - # The cost is the one this file already accepts for the same reason (#751's page-2 rule): a - # transient history-read failure costs that run its exemption and asks for a verdict. - # Recoverable in one command; a green over a rejection is not. It does NOT touch the - # `$REPAIR_DESC` sentinel path, which is already `pending`. - if [ "$state" = "success" ] && [ "$max_id_before" -lt 0 ]; then - echo "::warning::${CONTEXT} on ${SHA:0:7} qualified for an exemption, but no status high-water mark could be established, so a verdict landing during the write window could not be detected afterwards. Withholding the exemption and asking for a verdict instead." - state=pending - desc="Awaiting review verdict for ${SHA:0:7}" - fi - # LAST-MOMENT RE-READ (ersatztv#706). Classification takes several API round-trips, and a # reviewer can post a verdict during them — most dangerously a `failure`, which this job would # then overwrite with an exemption `success`, turning an explicit human rejection green. The @@ -1160,18 +1134,8 @@ jobs: # It is reported loudly and left alone — the residual is the read/POST gap either way. if [ "$state" = "success" ] && [ "$max_id_before" -ge 0 ]; then post_hist=$(gh "$BASE_URL/repos/$REPO/statuses/$SHA?limit=100") || post_hist="" - raced=0 if [ -z "${post_hist//[[:space:]]/}" ] || ! printf '%s' "$post_hist" | jq -e 'type == "array"' >/dev/null 2>&1; then - # AN UNREADABLE HISTORY IS "COULD NOT TELL", AND COULD-NOT-TELL MUST NOT RESOLVE TO GREEN - # (ersatztv#742). This branch used to log "The exemption … stands" and do exactly that — - # an unverified green over a possible rejection, on the one path whose failure direction - # is toward SUCCESS. It is the same uncertainty the page-2 probe below already resolves - # to `raced=1`; which of the two reads failed is not a difference in what is known. - # - # Reachability again: before #742 an attributable off-list `success` short-circuited and - # no write happened, so this branch was unreachable for that class of head. - echo "::warning::Could not re-read the status history for ${SHA:0:7} after posting, so a verdict landing during the write window cannot be ruled out. Repairing to pending rather than leaving an unverified exemption green." - raced=1 + echo "::warning::Could not re-read the status history for ${SHA:0:7} after posting, so a human verdict landing during the write window would not be detected. The exemption ${CONTEXT}=success stands." else # `.id > $since` is what confines this to the write window. Our OWN row is excluded twice # over — it carries `creator: null` (an Actions-token POST, measured; see the provenance @@ -1254,39 +1218,34 @@ jobs: esac fi fi - fi - # THE REPAIR IS SHARED BY BOTH BRANCHES (ersatztv#742). It used to sit inside the `else`, - # so the unreadable-history branch could not reach it however it set `raced` — which is - # why that branch had nothing to do but log and leave the green. The read-shape `if` now - # closes first, so "the history says a verdict raced us" and "the history could not be - # read" converge on the same sticky `pending`. - case "$raced" in - ''|*[!0-9]*) - echo "::warning::Post-write verification for ${SHA:0:7} returned '${raced}' instead of a count; not acting on it." - ;; - *) - if [ "$raced" -gt 0 ]; then - # The last-moment re-read found no human verdict, so any row present now was - # written during the window and has just been masked by the exemption above. - echo "::error::A human ${CONTEXT} verdict landed on ${SHA:0:7} while this job was writing its exemption, and was overwritten. Downgrading to 'pending' so an explicit human decision cannot be silently green. Re-post it with: scripts/post-review-verdict.sh ${PR} " - repair=$(jq -n --arg c "$CONTEXT" --arg u "$PR_URL" --arg d "$REPAIR_DESC" \ - '{state:"pending", context:$c, description:$d, target_url:$u}') - # A failure HERE leaves the forged green standing, so it is retried once and then - # screams. `set -e` would otherwise kill the job silently, after the success was - # written and with nothing left to re-attempt. - if ! gh -X POST -H 'Content-Type: application/json' -d "$repair" \ - "$BASE_URL/repos/$REPO/statuses/$SHA" >/dev/null 2>&1; then + case "$raced" in + ''|*[!0-9]*) + echo "::warning::Post-write verification for ${SHA:0:7} returned '${raced}' instead of a count; not acting on it." + ;; + *) + if [ "$raced" -gt 0 ]; then + # The last-moment re-read found no human verdict, so any row present now was + # written during the window and has just been masked by the exemption above. + echo "::error::A human ${CONTEXT} verdict landed on ${SHA:0:7} while this job was writing its exemption, and was overwritten. Downgrading to 'pending' so an explicit human decision cannot be silently green. Re-post it with: scripts/post-review-verdict.sh ${PR} " + repair=$(jq -n --arg c "$CONTEXT" --arg u "$PR_URL" --arg d "$REPAIR_DESC" \ + '{state:"pending", context:$c, description:$d, target_url:$u}') + # A failure HERE leaves the forged green standing, so it is retried once and then + # screams. `set -e` would otherwise kill the job silently, after the success was + # written and with nothing left to re-attempt. if ! gh -X POST -H 'Content-Type: application/json' -d "$repair" \ "$BASE_URL/repos/$REPO/statuses/$SHA" >/dev/null 2>&1; then - echo "::error::COULD NOT REPAIR ${CONTEXT} on ${SHA:0:7}. An exemption 'success' is standing on a head whose human verdict was overwritten. Post the verdict again immediately: scripts/post-review-verdict.sh ${PR} " - exit 1 + if ! gh -X POST -H 'Content-Type: application/json' -d "$repair" \ + "$BASE_URL/repos/$REPO/statuses/$SHA" >/dev/null 2>&1; then + echo "::error::COULD NOT REPAIR ${CONTEXT} on ${SHA:0:7}. An exemption 'success' is standing on a head whose human verdict was overwritten. Post the verdict again immediately: scripts/post-review-verdict.sh ${PR} " + exit 1 + fi fi + echo "Repaired ${CONTEXT} to pending on ${SHA:0:7}." + state=pending fi - echo "Repaired ${CONTEXT} to pending on ${SHA:0:7}." - state=pending - fi - ;; - esac + ;; + esac + fi fi if [ "$state" = "pending" ]; then diff --git a/docs/decisions/records/ci/exemption-provenance.md b/docs/decisions/records/ci/exemption-provenance.md index eea8e040e..ca9ab90e5 100644 --- a/docs/decisions/records/ci/exemption-provenance.md +++ b/docs/decisions/records/ci/exemption-provenance.md @@ -188,31 +188,31 @@ inheritance cases respectively. Counts are deliberately not quoted: `test_pr_cha 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, and two post-write residuals -had to be fixed here because of it.** Cold cross-family review found three routes by which an exemption -`success` ends up standing over a human `failure`, and the first response — "pre-existing, filed as -#849" — was only *textually* right. 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 unverified-write paths. So: +**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. -- **An unestablished high-water mark now WITHHOLDS the exemption** rather than posting it and skipping - verification. The post-write race check is the only thing between "a reviewer posted `failure` during - our write window" and a green over a rejection, and it is skipped outright when the mark is missing. -- **An unreadable post-write history now REPAIRS to the sticky sentinel** rather than logging "The - exemption … stands" and doing so. It is the same uncertainty the page-2 probe already resolves to - `raced=1`; which of the two reads failed is not a difference in what is known. The repair `case` was - hoisted out of the readable branch so both converge on it. +**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: -Both cost the run its exemption on a transient API failure — the price this file already pays for the -same reason in #751's page-2 rule, and recoverable in one command, where a green over a rejection is -not. The guard is placed after the mark is established, not with the classification: `$max_id_before` -does not exist there, and referencing it early is an unbound variable under `set -u` that kills the -step and strands every PR with no status (found by execution, not by reading). +- 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. -**The third route stays in #849**, with its reachability stated rather than dismissed: post-write -verification runs only for `state = success`, so a generic `pending` write can bury a rejection a later -run then greens — reachable from this change's class too. The retarget fence's post-POST gap is in the -same issue. +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 diff --git a/docs/decisions/records/ci/verdict-write-retarget-fence.md b/docs/decisions/records/ci/verdict-write-retarget-fence.md index ef95fcbe1..f7f5eb7a6 100644 --- a/docs/decisions/records/ci/verdict-write-retarget-fence.md +++ b/docs/decisions/records/ci/verdict-write-retarget-fence.md @@ -58,9 +58,19 @@ 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 writing*, 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. diff --git a/scripts/tests/test_pr_changed_files.py b/scripts/tests/test_pr_changed_files.py index 6601201ba..084615591 100644 --- a/scripts/tests/test_pr_changed_files.py +++ b/scripts/tests/test_pr_changed_files.py @@ -1013,21 +1013,6 @@ if "/timeline" in url: if "/statuses/" in url: mode = os.environ.get("STUB_HISTORY_MODE", "none") - # TRANSPORT FAILURES ON THIS ENDPOINT, placed ahead of the page logic because they apply to every - # page (ersatztv#742). `unreadable` fails EVERY read, so no high-water mark can be established; - # `post-read-unreadable` lets the mark be taken and then fails the POST-WRITE read, which is a - # different branch with a different safe answer. - if mode == "unreadable": - sys.exit(22) - if mode == "post-read-unreadable": - ctr = out / "history_reads.txt" - seen = int(ctr.read_text()) if ctr.exists() else 0 - ctr.write_text(str(seen + 1)) - if seen > 0: - sys.exit(22) - print(json.dumps([])) - sys.exit(0) - # PAGE, honoured. THE REASON IS THE TERMINATOR, NOT THE COUNTERS — and that distinction was itself # a finding (#751 round 5). An earlier version of this comment said the guard sits ahead of the # read-counting modes "so the page-2 probe cannot shift 'raced row appears on read N'", by analogy @@ -2091,51 +2076,6 @@ def test_an_UNATTRIBUTABLE_failure_is_still_RE_DERIVED(tmp_path, shape, creator, assert posted["state"] == "success" -def test_an_UNESTABLISHED_high_water_mark_WITHHOLDS_the_exemption(tmp_path): - """An exemption whose write cannot be VERIFIED afterwards is not granted (ersatztv#742). - - The post-write race check is the only thing between "a reviewer posted `failure` during our write - window" and a green over a rejection, and it is skipped outright when no high-water mark could be - established. Before #742 that was unreachable for a head carrying an attributable off-list - `success` — the job short-circuited and wrote nothing at all. Re-deriving that row is the POINT of - #742, and it turns "no write" into "a write", which is what exposes the residual. - - Docs-only, so the run WOULD have posted an exemption `success` had the mark been available; - without that pairing a passing test would prove only that nothing was exempted for some other - reason. - """ - posted, r = _run_classify(tmp_path, _emitting("docs/a.md"), history_mode="unreadable") - assert r.returncode == 0, r.stderr - assert posted is not None, f"the job posted no status at all: {r.stderr}" - assert posted["state"] == "pending", ( - "an exemption `success` was granted on a head where the post-write race check could not be " - f"armed, so a raced rejection could not have been detected. Log:\n{r.stdout[-1200:]}" - ) - - -def test_an_UNREADABLE_post_write_history_REPAIRS_rather_than_leaving_the_green(tmp_path): - """"Could not tell" must not resolve to green — the other half of the same rule. - - Here the mark IS established, the exemption IS posted, and then the post-write read fails. That - branch used to log "The exemption … stands" and do exactly that: an unverified green over a - possible rejection, on the one path whose failure direction is toward SUCCESS. It is the same - uncertainty the page-2 probe already resolves to `raced=1`; which of the two reads failed is not a - difference in what is known. - """ - posted, r = _run_classify(tmp_path, _emitting("docs/a.md"), history_mode="post-read-unreadable") - assert r.returncode == 0, r.stderr - seq = _posted_sequence(tmp_path) - assert len(seq) == 2, ( - "expected the exemption write followed by a repair; the unreadable post-write history left " - f"the green standing. Posts: {seq}. Log:\n{r.stdout[-1200:]}" - ) - assert seq[0]["state"] == "success" - assert seq[1]["state"] == "pending" - assert seq[1]["description"].startswith("Human verdict raced"), ( - f"the repair did not write the sticky sentinel, so a later run would re-derive it: {seq[1]}" - ) - - 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.""" -- 2.47.3 From 6f8679181a7c586112b4d4429d9922e02bd91ee3 Mon Sep 17 00:00:00 2001 From: Timothy Date: Thu, 27 Aug 2026 02:10:10 +0200 Subject: [PATCH 11/16] docs(742): retract the safety claims the deferred #849 routes disprove MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cross-family review of the withdrawal. It confirmed the revert is exact (both blobs match the pre-attempt commit, no withdrawn stub modes or tests left behind) and found no BLOCKER or MEDIUM — but four documentation defects, two of them contradictions this branch itself introduced by correcting a record's body and leaving its summary alone. Retracted in the workflow, where the claims are load-bearing for the next maintainer: * "the POST below is still correct, only the verification is weakened" — without a mark the race check is skipped entirely, so a verdict in the write window is neither detected nor repaired. Now says so, and names the withdrawn attempt so it is not re-attempted the same way. * "pending cannot turn a rejection green, so the only write that can cause the damage is the exemption success" — FALSE. A generic pending masks a raced rejection just as well, and because it is not the sticky sentinel the next run re-derives it into success with the human's row now below that run's mark. The damage arrives one event later, not never. * "the LAST net before a green stands" — it is the last net on THAT path only; a rejection already on the head is below the mark, and the pending route bypasses the block entirely. Record summaries brought into line with their own bodies: * ci.verdict-write-retarget-fence and ci.exemption-provenance both still promised the fence RESOLVES the retarget residual. It narrows it: a retarget between the final pre-write count and the POST leaves a PERMANENT forged green, because the successor can consume the edited event and exit before the stale run posts last. Also "overtaken after writing" -> "after the final pre-write count", which is where the window actually is. * ci.exemption-provenance said a lost verdict is re-posted as pending; on an exempt PR it is re-derived to an exemption success, the quieter and worse half. * ci.actions-credential-scoping still described the pre-742 rule (any real creator inherited). * The rule frontmatter said [[ == ]] makes its RHS a pattern. Only an UNQUOTED RHS does; the workflow comment already had this right after being probed on bash 5.3. No behaviour change. scripts/tests: 1012 passed, 2 skipped. fixes #742 Decisions-Edit: yes --- .gitea/workflows/review-verdict.yml | 25 ++++++++++++++----- docs/decisions/README.md | 4 +-- .../records/ci/actions-credential-scoping.md | 6 +++-- .../records/ci/exemption-provenance.md | 8 +++--- .../ci/verdict-write-retarget-fence.md | 5 ++-- 5 files changed, 33 insertions(+), 15 deletions(-) diff --git a/.gitea/workflows/review-verdict.yml b/.gitea/workflows/review-verdict.yml index 6b91a9210..1944b9ace 100644 --- a/.gitea/workflows/review-verdict.yml +++ b/.gitea/workflows/review-verdict.yml @@ -997,8 +997,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 @@ -1093,9 +1098,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 @@ -1155,7 +1165,10 @@ jobs: # # 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. This is the LAST net before a green stands, and the two errors are not + # 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. diff --git a/docs/decisions/README.md b/docs/decisions/README.md index a99fa1d33..295a3c162 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -46,7 +46,7 @@ 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/` 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 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: )` 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: )` 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 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.format-gate-folder-mode` | The blocking `format` CI job (and matching pre-commit hook) runs `dotnet format whitespace . --folder --include ` 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 (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) | @@ -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: 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.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) | diff --git a/docs/decisions/records/ci/actions-credential-scoping.md b/docs/decisions/records/ci/actions-credential-scoping.md index 1a90ea00e..542df3f1c 100644 --- a/docs/decisions/records/ci/actions-credential-scoping.md +++ b/docs/decisions/records/ci/actions-credential-scoping.md @@ -54,8 +54,10 @@ credential, and secrets are a per-repo store any workflow can reference. The tes tightened at the *reader* instead: `creator IN ` 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 — real creator INHERITED, `creator: null` re-derived — is not -protection.** Re-derivation +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. diff --git a/docs/decisions/records/ci/exemption-provenance.md b/docs/decisions/records/ci/exemption-provenance.md index ca9ab90e5..f4d9415b6 100644 --- a/docs/decisions/records/ci/exemption-provenance.md +++ b/docs/decisions/records/ci/exemption-provenance.md @@ -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 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: )` 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`.' +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: )` 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 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: '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 ` (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 `[[ == ]]` (RHS becomes a pattern) 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]`' +mechanics: '`scripts/pr-changed-files.sh ` (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 @@ -217,7 +217,9 @@ 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-posts `pending` over it — a deadlocked PR whose only diagnostic is a line in a job log. +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 diff --git a/docs/decisions/records/ci/verdict-write-retarget-fence.md b/docs/decisions/records/ci/verdict-write-retarget-fence.md index f7f5eb7a6..300389b37 100644 --- a/docs/decisions/records/ci/verdict-write-retarget-fence.md +++ b/docs/decisions/records/ci/verdict-write-retarget-fence.md @@ -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: 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.' 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`' --- @@ -68,7 +68,8 @@ marker, so the exemption returned two events later instead of one. Only a re-pos 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 writing*, because it never re-counts + 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 -- 2.47.3 From e3f1cb2303c4a6eb7bcd08b95b624c043bfb6ff2 Mon Sep 17 00:00:00 2001 From: Timothy Date: Thu, 27 Aug 2026 02:16:30 +0200 Subject: [PATCH 12/16] docs(742): my own retraction left two "only one window" clauses standing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sweeping for the RETRACTED wording rather than only the files I had edited — the rule this repo records as "stale comments: sweep by subject, not verb" — caught two clauses that the previous commit's own correction contradicts. ci.exemption-provenance's rule: now says the retarget residual is "NARROWED, not resolved", and then ended the same sentence with "leaving only the sub-round-trip window that no API without compare-and-set can close". Both cannot be true. There are TWO windows: the sub-round-trip one, and the post-final-count/pre-POST one, 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. The same record's #706 paragraph carried the same "the sub-round-trip window it describes survives" framing, with no pointer to the correction. It now points at it. A retraction that only edits the sentence you remembered writing is the failure mode here: the previous commit corrected three claims and left two paraphrases of one of them in place, in the same file. No behaviour change, and this time MEASURED rather than asserted: the classify step's executable content (comments and blank lines stripped) is 323 lines at HEAD~1 and 323 identical lines at HEAD. scripts/tests: 1012 passed, 2 skipped. fixes #742 Decisions-Edit: yes --- docs/decisions/README.md | 2 +- docs/decisions/records/ci/exemption-provenance.md | 7 +++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 295a3c162..98ef719e8 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -46,7 +46,7 @@ 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/` 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 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: )` 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 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: )` 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 ` 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 (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) | diff --git a/docs/decisions/records/ci/exemption-provenance.md b/docs/decisions/records/ci/exemption-provenance.md index f4d9415b6..1290fddc6 100644 --- a/docs/decisions/records/ci/exemption-provenance.md +++ b/docs/decisions/records/ci/exemption-provenance.md @@ -5,7 +5,7 @@ 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 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: )` 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 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`.' +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: )` 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 ` (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]`' --- @@ -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 -- 2.47.3 From 18b9b3e6543cef27db3854b6cfc1893cd27950f5 Mon Sep 17 00:00:00 2001 From: Timothy Date: Thu, 27 Aug 2026 02:33:14 +0200 Subject: [PATCH 13/16] docs(742): close both retracted claim families by CONCEPT, not by phrase MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Third sweep, and the third time the same mistake: I grepped for the exact wording I had written and missed the same claim in PARAPHRASE at sites I never opened. Cross-family review enumerated them. This closes both families by concept. Family 1 — "the retarget fence resolved the race". Corrected at every site, not just the two I remembered: the fence record's own rule and its "handoff, not a stall" induction (which is a property of a run that ABSTAINS and says nothing about one that already passed its final count and then posts), ci.exemption-provenance's "Resolved 2026-08-03" heading, and docs/ci-cd.md's "That residual is now fenced". It NARROWS: a retarget between the final pre-write count and the POST leaves a PERMANENT forged green, because the successor consumes the edited event and exits before the stale run posts last. Family 2 — "a pending write is harmless". Retracted in the workflow's untrusted-count rationale ("for no safety gain"), in the same phrase inside the fence record's rule, and in docs/ci-cd.md twice, including the absolute "a human BLOCKED can never be silently turned green". A generic pending blocks the merge IMMEDIATELY, which is what makes letting it through the right trade — but it is not inert: it 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 with that rejection below the new mark. Letting it through is still right; the trade is "immediate block, later re-derivation risk", not "free". Every retraction names #849, which carries the behaviour work. No behaviour change: the classify step's executable content is identical across all three docs commits (323 lines, comments and blanks stripped, compared via the YAML-extracted step rather than line ranges). scripts/tests: 1012 passed, 2 skipped. fixes #742 Decisions-Edit: yes --- .gitea/workflows/review-verdict.yml | 14 ++++++++++---- docs/ci-cd.md | 12 ++++++++---- docs/decisions/README.md | 2 +- docs/decisions/records/ci/exemption-provenance.md | 2 +- .../records/ci/verdict-write-retarget-fence.md | 2 +- 5 files changed, 21 insertions(+), 11 deletions(-) diff --git a/.gitea/workflows/review-verdict.yml b/.gitea/workflows/review-verdict.yml index 1944b9ace..f7b597ed2 100644 --- a/.gitea/workflows/review-verdict.yml +++ b/.gitea/workflows/review-verdict.yml @@ -1069,10 +1069,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}." diff --git a/docs/ci-cd.md b/docs/ci-cd.md index 7c0b9a507..28a4d3621 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -1395,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 @@ -1404,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**, @@ -1418,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 diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 98ef719e8..0ea0b6ba7 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.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. 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: 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 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` 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) | diff --git a/docs/decisions/records/ci/exemption-provenance.md b/docs/decisions/records/ci/exemption-provenance.md index 1290fddc6..fd0c4fc24 100644 --- a/docs/decisions/records/ci/exemption-provenance.md +++ b/docs/decisions/records/ci/exemption-provenance.md @@ -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 diff --git a/docs/decisions/records/ci/verdict-write-retarget-fence.md b/docs/decisions/records/ci/verdict-write-retarget-fence.md index 300389b37..9120fa9a8 100644 --- a/docs/decisions/records/ci/verdict-write-retarget-fence.md +++ b/docs/decisions/records/ci/verdict-write-retarget-fence.md @@ -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. 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: 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 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` 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`' --- -- 2.47.3 From 056f048afcda81eb5dae03ae8ff70750e85af099 Mon Sep 17 00:00:00 2001 From: Timothy Date: Thu, 27 Aug 2026 03:02:26 +0200 Subject: [PATCH 14/16] docs(742): close the named sites, and record the sweep boundary in #849 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fourth prose round. Three of the four sites it named are real and fixed; one is a false positive, recorded so it is not "fixed" later. Fixed: * the classify comment heading "THE PROBLEM THIS SOLVES" -> NARROWS, with #849 named; * ci.verdict-write-retarget-fence's induction, which ended "the induction terminates when retargeting stops and the last run writes the final answer". That holds 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; * CLAUDE.md's "so a rejection is never re-derived into a green", which is MY sentence from this branch and is overbroad: it is true of a rejection VISIBLE AT THE FIRST READ, not of one landing inside a run's own write window; * two test docstrings carrying the retracted "withholding pending buys no safety", and a scope note on test_a_REAL_human_verdict_is_still_NEVER_overwritten, whose NAME asserts a guarantee wider than what it measures. NOT fixed, deliberately: process.check-and-use-pins-a-version's title says "the gap is stated and fenced". That is the generic check/action version-binding rule and has nothing to do with the retarget fence. Matching on the word rather than the concept is what put it on the list. AND THE BOUNDARY, recorded in #849 rather than left to the next round to rediscover. Each round corrected the sites it could see and the next found more, because these claims exist in paraphrase across corpus prose written before #742. #742 has now corrected every site that is its own text or directly about the allow-list, plus the fence/pending claims in the four docs and the classify comments. Remaining corpus prose describing the #706 fence's or the post-write verification's guarantees belongs to #849 — those sentences are wrong only because of the residual analysis in that issue, so they should be corrected when the behaviour lands, rather than leaving prose that promises a property no code yet has. #849 has a Done-when box for it. No behaviour change. scripts/tests: 1012 passed, 2 skipped. fixes #742 Decisions-Edit: yes --- .gitea/workflows/review-verdict.yml | 3 ++- CLAUDE.md | 2 +- docs/decisions/README.md | 2 +- .../records/ci/verdict-write-retarget-fence.md | 2 +- scripts/tests/test_pr_changed_files.py | 11 +++++++++-- 5 files changed, 14 insertions(+), 6 deletions(-) diff --git a/.gitea/workflows/review-verdict.yml b/.gitea/workflows/review-verdict.yml index f7b597ed2..024ffb82b 100644 --- a/.gitea/workflows/review-verdict.yml +++ b/.gitea/workflows/review-verdict.yml @@ -601,7 +601,8 @@ jobs: } # --- 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 diff --git a/CLAUDE.md b/CLAUDE.md index 84f8f0e21..bc8ae1f44 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 ` 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 [note]`** — it posts both the `Review-verdict: … @ ` 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 a rejection is never re-derived into a green), 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). +- `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 [note]`** — it posts both the `Review-verdict: … @ ` 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. diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 0ea0b6ba7..05fd2adee 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.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. 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 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` 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.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) | diff --git a/docs/decisions/records/ci/verdict-write-retarget-fence.md b/docs/decisions/records/ci/verdict-write-retarget-fence.md index 9120fa9a8..71f67e12b 100644 --- a/docs/decisions/records/ci/verdict-write-retarget-fence.md +++ b/docs/decisions/records/ci/verdict-write-retarget-fence.md @@ -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. 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 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` 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.' +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`' --- diff --git a/scripts/tests/test_pr_changed_files.py b/scripts/tests/test_pr_changed_files.py index 084615591..684c79506 100644 --- a/scripts/tests/test_pr_changed_files.py +++ b/scripts/tests/test_pr_changed_files.py @@ -2148,6 +2148,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 @@ -2551,8 +2555,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", ( -- 2.47.3 From 3817414366a7de205a9eecd2eedf46237e206bd3 Mon Sep 17 00:00:00 2001 From: Timothy Date: Thu, 27 Aug 2026 04:15:19 +0200 Subject: [PATCH 15/16] test(742): the Route 3 section header names the allow-list, not attributability MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Last finding from a clean cold round (VERDICT: MERGEABLE, nine mutations applied and every one reddened). The banner said an inherited success is re-derived unless it is an 'attributable human verdict' — since this change, attributable alone is the weaker test that governs an inherited FAILURE; a success additionally needs allow-list membership. In scope by this branch's own boundary rule: it is prose about a property this change alters. scripts/tests: 1012 passed, 2 skipped. --- scripts/tests/test_pr_changed_files.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/tests/test_pr_changed_files.py b/scripts/tests/test_pr_changed_files.py index 684c79506..66af69415 100644 --- a/scripts/tests/test_pr_changed_files.py +++ b/scripts/tests/test_pr_changed_files.py @@ -1664,7 +1664,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 -- 2.47.3 From 586577c6f6035778cd232c88444674c1b43bc6c0 Mon Sep 17 00:00:00 2001 From: Timothy Date: Thu, 27 Aug 2026 04:25:10 +0200 Subject: [PATCH 16/16] style(742): ruff format the new tests with the CI-pinned version MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CI's 'Script lint and tests' went red on `ruff format --check`. `ruff check` was clean and the suite was green throughout — this was purely formatting of lines this branch added, and it is a gap in MY local gate: I ran pytest and the decisions validator every round and never ran the formatter. Formatted with ruff 0.12.11, the version pr-checks.yml pins, rather than the local install — the pin exists precisely so the verdict is not a function of whoever ran it, and a different version could have reformatted lines this branch never touched. The diff is confined to blocks added here (a re.subn call, two assertion strings, two parametrize entries). Verified over the whole CI population, not just the file I edited: git ls-files '*.py' | xargs ruff check -> All checks passed git ls-files '*.py' | xargs ruff format --check -> 43 files already formatted scripts/tests: 1012 passed, 2 skipped. --- scripts/tests/test_pr_changed_files.py | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/scripts/tests/test_pr_changed_files.py b/scripts/tests/test_pr_changed_files.py index 66af69415..5f685c971 100644 --- a/scripts/tests/test_pr_changed_files.py +++ b/scripts/tests/test_pr_changed_files.py @@ -1339,8 +1339,12 @@ def _run_classify( # 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) + 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) @@ -1763,8 +1767,7 @@ def test_a_verdict_shaped_SUCCESS_from_a_NON_allowlisted_account_is_RE_DERIVED(t # 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, ( - "the diagnostic does not name the account whose verdict was discarded. " - f"Log:\n{r.stdout[-1200:]}" + 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 @@ -2042,11 +2045,9 @@ def test_an_account_on_NEITHER_entry_is_still_re_derived(tmp_path): @pytest.mark.parametrize( "shape,creator,desc", [ - ("a null creator (an Actions-token write)", None, - "Review-verdict: BLOCKED @ a9e3e23 (base: main)"), + ("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)"), + ("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): -- 2.47.3