scripts/tests/test_ci_dropped_step_guard.py decided which jobs must carry per-step execution
markers from MARKED_JOBS = ("test", "migrations") — a hand-written mirror of the required status
contexts on main, annotated Read live on 2026-08-10 and compared against the server by nothing.
Add a fourth required context and it acquired no dropped-step guard, silently, in the file testing.guard-derives-population-from-source names as its own model.
The constraint that made this its own issue: pr-checks.yml::script-tests checks out with persist-credentials: false, so it cannot ask Gitea — and the issue's own candidate fixes were each
unsatisfying (a snapshot "just moves the hand-maintenance"; a credentialed check that skips without
creds is the #756 fail-open).
The mechanism, and its fail mode
Split the invariant at the credential boundary, so each half is checked where it can be:
Half
Where it runs
What it asserts
.gitea/required-status-contexts.json
committed
the mirror, verbatim from the API
derivation of MARKED_JOBS from it
offline, script-tests
every required context resolves to a marked job or a stated disposition
scripts/check-required-contexts.sh
the merge-consent hook
the mirror still equals the live effective required set
test_ci_status_context_uniqueness.py
script-tests
no two jobs synthesize the same context string
Fail mode, stated. Every non-match class asks — drift, no rule, undecidable, unreadable, a
read failure, a missing checker, a missing classifier, and any word the contract does not define.
Nothing skips. Ask rather than deny because drift does not make that merge unsafe (Gitea enforces
the live set server-side); what is stale is a guard's scope. The arm runs last, so it can only
downgrade an otherwise-clean auto-grant, on both merge paths, and only for the repo the
snapshot names.
Residual, stated rather than implied: the reconciliation is one client-side hook, so a web-UI
merge or a session without it never reconciles — bounded staleness, not none. And the asymmetry is
real: adding a context to the snapshot reddens CI until the job is marked; hand-narrowing it stays
green, exactly as the literal it replaced did.
Two things worth a reviewer's eye
Rule selection was EXTRACTED, not copied.scripts/lib/branch-rule-classifier.jq is loaded by
both the hook and the checker. The extracted program is byte-identical to the inline original,
independently verified two ways (1115/1116 bytes, exact equality) and behaviourally identical across
29 payloads under both jq 1.8 and CI's pinned jq 1.6.
The scope index is built from docker-build.yml alone, not the git index — the release-path scan job runs that guard inside a non-git copy. A narrow index is safe because an unresolvable
context is a hard error, so the guard gets louder, never quieter. The cross-workflow half that
genuinely needs the whole population lives in the separate guard above, which script-tests runs.
Verification
The #787 defect caught live: adding functional-e2e's context to the snapshot makes the guard
name all 8 of its unmarked steps and go red — and now grows DELIMITER_BAN_JOBS with it.
Vacuity: an empty/missing/malformed snapshot is a loud collection ERROR, never zero collected.
Mutations witnessed, not asserted: the checker's comparison clause disarmed reports match
instead of drift; a workflow job renamed to collide reddens the uniqueness guard.
Checker exercised against the livebranch_protections payload plus every declared class.
scripts/tests: 1057 passed, 2 skipped. ruff check + format clean. decisions_validate OK.
Review
Four cold rounds across two model families, each round re-reviewing the previous round's fixes:
Every finding is fixed or explicitly deferred to a filed issue, and each fix's red was witnessed
by disarming the exact clause it names.
The recurring pattern, worth naming: six of this change's own tests were caught passing for the
wrong reason, and every single one asserted the absence of something — a mutant that never ran,
an earlier arm answering, a != deny a grant also satisfies, a stub serving a matching payload
either way, a substring the catch-all arm also contains, and a clause with no coverage at all. They
now assert specific positive outcomes. Most consequential: the assert not unaccounted line — the
mechanism this whole issue turns on — had no proof at all until round 3, and disarming it left 51
tests green.
Deferred, with issues rather than silence:#858 (the hook's verdict classifier resolves from $CLAUDE_PROJECT_DIR — pre-existing, and this PR's own arm does it the safe way) and #859 (a
malformed branch-protection rule states a cause that did not happen, plus the now-double branch_protections fetch).
Docs updated
docs/guard-inventory.md (three rows + asserted counts), docs/remote-state-inventory.md (scope +
two rows), docs/ci-cd.md, and the two decision records that named this gap as open — including, by
clause, the rule's "or a dated staleness marker" alternative, which the new guidance rejects.
`scripts/tests/test_ci_dropped_step_guard.py` decided which jobs must carry per-step execution
markers from `MARKED_JOBS = ("test", "migrations")` — a hand-written mirror of the required status
contexts on `main`, annotated `Read live on 2026-08-10` and compared against the server by nothing.
Add a fourth required context and it acquired no dropped-step guard, silently, in the file
`testing.guard-derives-population-from-source` names as its own model.
The constraint that made this its own issue: `pr-checks.yml::script-tests` checks out with
`persist-credentials: false`, so it cannot ask Gitea — and the issue's own candidate fixes were each
unsatisfying (a snapshot "just moves the hand-maintenance"; a credentialed check that skips without
creds is the #756 fail-open).
## The mechanism, and its fail mode
**Split the invariant at the credential boundary**, so each half is checked where it can be:
| Half | Where it runs | What it asserts |
|---|---|---|
| `.gitea/required-status-contexts.json` | committed | the mirror, verbatim from the API |
| derivation of `MARKED_JOBS` from it | offline, `script-tests` | every required context resolves to a marked job or a stated disposition |
| `scripts/check-required-contexts.sh` | the merge-consent hook | the mirror still equals the live **effective** required set |
| `test_ci_status_context_uniqueness.py` | `script-tests` | no two jobs synthesize the same context string |
**Fail mode, stated.** Every non-`match` class **asks** — drift, no rule, undecidable, unreadable, a
read failure, a missing checker, a missing classifier, and any word the contract does not define.
Nothing skips. Ask rather than deny because drift does not make *that* merge unsafe (Gitea enforces
the live set server-side); what is stale is a guard's scope. The arm runs **last**, so it can only
downgrade an otherwise-clean auto-grant, on **both** merge paths, and **only for the repo the
snapshot names**.
**Residual, stated rather than implied:** the reconciliation is one client-side hook, so a web-UI
merge or a session without it never reconciles — bounded staleness, not none. And the asymmetry is
real: adding a context to the snapshot reddens CI until the job is marked; hand-*narrowing* it stays
green, exactly as the literal it replaced did.
## Two things worth a reviewer's eye
**Rule selection was EXTRACTED, not copied.** `scripts/lib/branch-rule-classifier.jq` is loaded by
both the hook and the checker. The extracted program is **byte-identical** to the inline original,
independently verified two ways (1115/1116 bytes, exact equality) and behaviourally identical across
29 payloads under both jq 1.8 and CI's pinned **jq 1.6**.
**The scope index is built from `docker-build.yml` alone, not the git index** — the release-path
`scan` job runs that guard inside a non-git copy. A narrow index is safe because an unresolvable
context is a hard error, so the guard gets *louder*, never quieter. The cross-workflow half that
genuinely needs the whole population lives in the separate guard above, which `script-tests` runs.
## Verification
- **The #787 defect caught live:** adding `functional-e2e`'s context to the snapshot makes the guard
name all 8 of its unmarked steps and go red — and now grows `DELIMITER_BAN_JOBS` with it.
- **Vacuity:** an empty/missing/malformed snapshot is a loud collection ERROR, never zero collected.
- **Mutations witnessed, not asserted:** the checker's comparison clause disarmed reports `match`
instead of `drift`; a workflow job renamed to collide reddens the uniqueness guard.
- Checker exercised against the **live** `branch_protections` payload plus every declared class.
- `scripts/tests`: **1057 passed, 2 skipped**. ruff check + format clean. `decisions_validate` OK.
## Review
Four cold rounds across two model families, each round re-reviewing the previous round's fixes:
| Round | Verdict | Findings |
|---|---|---|
| 1 | BLOCKED | 1 Blocker, 2 High, 3 Medium, 1 Low |
| 2 (re-review) | BLOCKED | 1 High, 4 Low |
| 2 (second reviewer, cold) | BLOCKED | 4 Medium, 10 Low/Nit |
| 3 (re-review) | BLOCKED | 1 Blocker (already fixed), 1 High, 3 Medium, 4 Low |
Every finding is fixed or explicitly deferred to a filed issue, and **each fix's red was witnessed**
by disarming the exact clause it names.
The recurring pattern, worth naming: **six of this change's own tests were caught passing for the
wrong reason**, and every single one asserted the *absence* of something — a mutant that never ran,
an earlier arm answering, a `!= deny` a grant also satisfies, a stub serving a matching payload
either way, a substring the catch-all arm also contains, and a clause with no coverage at all. They
now assert specific positive outcomes. Most consequential: the `assert not unaccounted` line — the
mechanism this whole issue turns on — had no proof at all until round 3, and disarming it left 51
tests green.
**Deferred, with issues rather than silence:** #858 (the hook's verdict classifier resolves from
`$CLAUDE_PROJECT_DIR` — pre-existing, and this PR's own arm does it the safe way) and #859 (a
malformed branch-protection rule states a cause that did not happen, plus the now-double
`branch_protections` fetch).
## Docs updated
`docs/guard-inventory.md` (three rows + asserted counts), `docs/remote-state-inventory.md` (scope +
two rows), `docs/ci-cd.md`, and the two decision records that named this gap as open — including, by
clause, the rule's "or a dated staleness marker" alternative, which the new guidance rejects.
fixes #787
`scripts/tests/test_ci_dropped_step_guard.py` decides which jobs must carry per-step execution
markers from `MARKED_JOBS = ("test", "migrations")` — a hand-written mirror of the required status
contexts on `main`, annotated `Read live on 2026-08-10` and compared against the server by nothing.
A dated comment is a claim about the past. Add a fourth required context and it acquired no
dropped-step guard, silently, in the file the decision record names as its own model.
The constraint that made this its own issue: `pr-checks.yml::script-tests` checks out with
`persist-credentials: false`, so it cannot ask Gitea, and the issue's own candidate fixes were each
unsatisfying — a snapshot "just moves the hand-maintenance", a credentialed check that skips without
creds is the #756 fail-open.
SPLIT THE INVARIANT AT THE CREDENTIAL BOUNDARY and check each half where it can be checked:
* `.gitea/required-status-contexts.json` — the mirror, committed verbatim from the API.
* The guard DERIVES `MARKED_JOBS` from it offline. Each candidate context string is SYNTHESIZED from
the workflow (`<workflow name> / <job name> (<event>)`) and matched by equality, never parsed —
the delimiters occur inside the names they delimit (`Build & test (.NET)` ends in a parenthesis of
its own). A required context mapping to neither a job nor an explicit `ACCOUNTED_ELSEWHERE`
disposition is a HARD failure at import, which is what makes a fourth required check impossible to
add in silence. Both directions are asserted, so a disposition that stops being required is
reported too.
* `scripts/check-required-contexts.sh` reconciles the mirror against live `status_check_contexts`,
called from `pretooluse-merge-consent.sh`.
So the maintenance is now a verbatim copy with an equality check on each side, and updating it to
match the server makes CI red until the newly required job is marked.
Three decisions worth keeping:
* The hook arm ASKS, never denies. Drift does not make that merge unsafe — Gitea enforces the live
required set server-side — so a deny would state something false about the change in front of the
reader. What is stale is a guard's scope.
* It runs LAST, so it can only downgrade an otherwise-satisfied auto-grant and never masks a more
serious refusal (asserted, not described).
* It runs on BOTH merge paths. The pre-existing branch-protection read sits inside the
`merge_when_checks_succeed` branch and never fires on an immediate merge — the common case. This
hook already records that exact shape once: the base re-read "first landed inside the
scheduled-auto-merge branch only", and cold review found scheduled+retarget denied while
immediate+retarget auto-GRANTED.
The scope index is built from `docker-build.yml` alone and deliberately NOT from the git index. An
earlier draft derived it with `tracked_paths` and broke the RELEASE PATH: `docker-build.yml`'s `scan`
job runs this guard inside a poisoned COPY of the tree where `git ls-files` exits 128, which is the
trap `test_ci_release_path_scan_job.py` documents in the very paragraph this change edits. A narrow
index is safe here because the failure direction is: the completeness claim is over the SNAPSHOT's
contexts, so a missing workflow makes a context UNRESOLVABLE and the guard strictly louder, never
quieter. That harness now stages the snapshot into its copy, named explicitly rather than by glob.
Rule selection was EXTRACTED, not copied. `scripts/lib/branch-rule-classifier.jq` is now loaded by
both the hook and the checker: this is a security predicate, and the hook's own history is the
argument — the docs-only file enumeration was written twice, four rounds of hardening landed on one
copy and never reached the other, and the copy with real authority ended up strictly weaker.
An earlier draft of the checker had its own blanket "any glob metacharacter anywhere" test, which
called a rule named `a[b` undecidable for `main`; the shared classifier's `superset` test does not.
A structural test now pins that both callers reach the one file, replacing a first attempt that
banned the token "gobwas" and flagged the comment saying the logic is DELEGATED.
Cold cross-family review (Codex) returned BLOCKED with seven findings; all are fixed and each fix's
red was witnessed:
* THE MUTATION PROOF WAS VACUOUS. The mutant was copied without the classifier it loads beside
itself, so it exited 2 with EMPTY stdout — and the assertion `stdout != "drift"` was satisfied by
that empty string. The proof never reached the clause, so the `MUTATION` grade was unsupported. It
now asserts the mutant's EXACT verdict `(0, "match")` and ships a positive control proving the tmp
layout reproduces the real one.
* Duplicate synthesized contexts silently overwrote in a dict. Two jobs sharing a `name:` collide on
one context string, the later wins, and the other's steps go unguarded — branch protection cannot
tell them apart either. Now a multimap with a uniqueness assertion.
* `enable_status_check: false` was type-checked and its VALUE ignored, so protection with checks
DISABLED certified as `match`. The comparison is now against the EFFECTIVE required set.
* The checker and snapshot were resolved through `$CLAUDE_PROJECT_DIR`. An env var is not a sound
input to a security decision — a wrong value pointing at a tree containing an executable checker
returns `match` about a different checkout. Both now bind to the hook-derived `$repo_root`, and the
missing-checker test runs a COPY of the hook, the only way to move that root.
* `unreadable` is a DECLARED class that fell to the catch-all, which told the operator the checker
had returned a word the hook did not understand. It has its own arm. Its test asserts on the
IMMEDIATE path: on the scheduled path the h10 arm answers first, and the first draft passed
without reaching the code it names.
* `scripts/lib/*.jq` was outside the remote-state population, whose claim is that it has no content
filter. Scope widened and the classifier given an `N/A` row.
* The release-path Blocker it raised was already fixed in this branch before the review landed.
A second cold review round (a different model family, and a re-review of the fix commit) returned
BLOCKED on two findings, both fixed:
* THE STATED INVARIANT WENT UNENFORCED THE MOMENT ONE SIDE STARTED MOVING. The file says "the
delimiter ban is WIDER than the marker set", and while both were literals edited together that
held. `MARKED_JOBS` now DERIVES, so on the day a fourth required context arrives the marker half
goes red, the author adds markers, CI greens — and that job's `run:` bodies were never checked for
the `${{` delimiter that CAUSES the drop the markers detect. `DELIMITER_BAN_JOBS` is now derived
from `MARKED_JOBS`, and the property is asserted so a future edit back to a literal cannot
re-open it silently. Measured: a planted 4th context grows both sets together.
* `docs/guard-inventory.md`'s row claimed the context index came from the git index — true of the
reverted draft, false of the shipped code, and in the artifact whose job is to be trusted about
exactly that. Nothing asserts that column, so it would not have self-corrected.
The cross-workflow half moved to its own guard, `scripts/tests/test_ci_status_context_uniqueness.py`.
It has to be separate: a cross-workflow claim needs the whole workflow population, whose authoritative
source is the git index, and the dropped-step guard cannot touch the index because the release-path
`scan` job runs it in a non-git copy. Split, each half gets the right source. It is MUTATION-graded
via the checker-guard shape — the guard IS a test, so disarming its own assertion makes it absent
rather than red, and the declared mutation goes into the guarded ARTIFACT instead: a workflow job
renamed to collide with the required `Build & test (.NET)` context, which is precisely the evasion.
Folded in from the same round: the arm now runs only for the repo the snapshot NAMES (it was
comparing any repo's live contexts against this repo's mirror — `server-management` returns `[]`,
which classified as `nomatch` and would have reported a flatly false finding about it); the hook
guards the shared classifier's readability itself, rather than inheriting a `jq -f` failure that
blamed the payload for a missing local file; `unreadable` and the usage exits match their stated
contracts; and `docs/ci-cd.md` records that the immediate merge path now needs a repo-admin-scoped
credential, which it did not before.
A fifth cold round returned MERGEABLE — no Blocker, no High, no Medium. It independently re-ran
round 4's exact re-inlining attack and confirmed the suite now reddens on it, disarmed twelve further
clauses and found each reddened only its own named test, and verified #857 survived the rebase
intact. Its one Low and two nits were fixed rather than deferred, because the first made a claim in
this message false: the sweep of the retracted "or a dated staleness marker" wording had covered
`docs/` but missed a quoting site in `scripts/tests/test_optional_request_members.py`. The checker's
stderr is no longer discarded either — a usage error used to reach the operator as "returned
'nothing'", naming no cause.
Two prose overclaims of my own were corrected rather than defended: "neither half is checkable
alone; composed, they are" now names the reconciliation as ONE bypassable client-side hook, and
"updating it to match the server makes CI RED" now says ADD, because hand-NARROWING the snapshot
narrows the derived scope and stays green exactly as the literal it replaced did.
A third cold round (the cross-family reviewer had hit a usage limit, so this was the strongest
available reasoning on a cold brief) returned BLOCKED. Its findings, all fixed and each red
witnessed:
* THE CENTRAL CLAUSE OF THIS CHANGE SHIPPED WITH NO PROOF. `assert not unaccounted` is what makes a
fourth required check impossible to add in silence, and the decision record sells it as exactly
that — but disarming it and planting a fourth context left the derived scope silently behind with
51 tests still green. `_derive_marked_jobs` now takes an injectable context list SOLELY so that
clause and the anti-vacuity clause beside it can be proven; production calls it with no argument.
* The `enable_status_check:false` fix from round 2 had ZERO coverage: removing that one clause
returned `match` for disabled protection and all 71 tests stayed green, because the `rule()`
helper's `enabled=` parameter had no call site that ever passed False — this repo's own recorded
"a fixture that omits a field tests only the default".
* A FIFTH test passing for the wrong reason: the missing-checker test asserted the substring
`check-required-contexts.sh`, which the CATCH-ALL arm's reason also contains, so deleting the
`[ ! -x ]` clause left it green — two guards masking each other (#685). It now asserts wording
unique to the arm AND that no branch-protection fetch happened, which only the early clause
prevents.
* The repo gate was byte-exact while Gitea resolves owner/repo case-insensitively (verified live:
`/repos/TIMOTHY/ErsatzTV` answers 200), so a case variant would skip the freshness arm entirely —
the gate failing open on a spelling.
* The new `branch_protections` read had no `docs/remote-state-inventory.md` row, and the checker's
row delegated its fetch to "the caller's row" that did not exist. Added, graded `UNSAFE-KNOWN`
with what it authorizes (nothing: every outcome is `ask` or silence).
A fourth cold round returned BLOCKED on two independent grounds, both fixed:
* THE SEVENTH TEST PASSING FOR THE WRONG REASON, and the one that mattered most: the "one classifier,
two callers" property was asserted with a SUBSTRING over source text, which a COMMENT satisfies.
Review proved it by re-inlining a byte-identical copy of the classifier into the hook with a
comment naming the shared file — the entire suite stayed green at exactly 1062. The byte-identical
inline is the refactor that matters, precisely because it agrees on day one; a weakened copy would
have been caught behaviourally. Both callers are now proven by SWAPPING the shared file for a
sentinel that can only answer `undecidable` and requiring their behaviour to change. Re-running
review's exact attack against the fixed suite now reddens it.
* THE HEAD WAS STALE AND THE REBASE WAS RED. `origin/main` had moved to #857, which touches five of
the same files; this branch did not apply cleanly, and the guard-inventory counts were computed off
the dead base. Rebased onto `45b17e58e`, counts resolved to 42/6/21 and 20/6/16, the generated
catalog REGENERATED rather than hand-resolved. The earlier green vouched for a tree that no longer
existed.
Also fixed from that round: the required-`branch` clause was masked by the mismatch guard one line
below it, so its test could not see it (#685 again — it now asserts the arm-unique stderr); three of
the four freshness arms had no proof and were carried by the catch-all; the checker's own
classifier-readability guard was the untested twin of a fix the hook made loudly; and the
unaccounted-context diagnostic offered a remediation that is impossible for a context produced by
another workflow.
Two coverage overclaims were corrected rather than defended: the arm does NOT run for a docs/process
-only PR, so a PR editing only the snapshot — the narrowing direction — never triggers it, and it
could not have judged one anyway, since it compares the live server against the snapshot in the local
checkout rather than the version the PR proposes.
So SEVEN of this change's own tests were caught passing for the wrong reason across four rounds, and
the pattern is one class — the mutation proof (a mutant that never ran), the `unreadable` arm (an earlier arm answering), the
never-deny assertion, and the repo gate (a stub serving a matching payload either way). Every one
asserted the ABSENCE of something. They now assert a specific positive outcome, and each fix's red
was witnessed by disarming the clause it names.
Self-found in the same round: the snapshot names its own `branch`, and a mismatch against `--branch`
is now a usage error rather than a class — comparing one branch's live contexts against another's
mirror would otherwise produce a confident verdict about a pair never meant to be compared.
Verified: the mutation is witnessed, not asserted — unmutated reports `drift` on an added context,
the mutant with the set comparison disarmed reports `match`, a permanent no-op. The checker was run
against the LIVE branch_protections payload (`match`) and every other class exercised. Full
`scripts/tests` suite green; ruff check + format clean.
Sweep by subject: every site claiming this gap is open was updated — `docs/guard-inventory.md`,
`test_ci_release_path_scan_job.py`, `test_guard_populations_derive_from_git.py`,
`test_ci_image_pin_population.py` (whose remaining `TOOLCHAIN_JOBS` literal is #789), and by clause,
the rule's "or a dated staleness marker" alternative, which the new guidance rejects.
fixes#787
Decisions-Edit: yes
Co-authored-by: Timothy <timothy@noreply.gitea.tblindustries.be>
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
scripts/tests/test_ci_dropped_step_guard.pydecided which jobs must carry per-step executionmarkers from
MARKED_JOBS = ("test", "migrations")— a hand-written mirror of the required statuscontexts on
main, annotatedRead live on 2026-08-10and compared against the server by nothing.Add a fourth required context and it acquired no dropped-step guard, silently, in the file
testing.guard-derives-population-from-sourcenames as its own model.The constraint that made this its own issue:
pr-checks.yml::script-testschecks out withpersist-credentials: false, so it cannot ask Gitea — and the issue's own candidate fixes were eachunsatisfying (a snapshot "just moves the hand-maintenance"; a credentialed check that skips without
creds is the #756 fail-open).
The mechanism, and its fail mode
Split the invariant at the credential boundary, so each half is checked where it can be:
.gitea/required-status-contexts.jsonMARKED_JOBSfrom itscript-testsscripts/check-required-contexts.shtest_ci_status_context_uniqueness.pyscript-testsFail mode, stated. Every non-
matchclass asks — drift, no rule, undecidable, unreadable, aread failure, a missing checker, a missing classifier, and any word the contract does not define.
Nothing skips. Ask rather than deny because drift does not make that merge unsafe (Gitea enforces
the live set server-side); what is stale is a guard's scope. The arm runs last, so it can only
downgrade an otherwise-clean auto-grant, on both merge paths, and only for the repo the
snapshot names.
Residual, stated rather than implied: the reconciliation is one client-side hook, so a web-UI
merge or a session without it never reconciles — bounded staleness, not none. And the asymmetry is
real: adding a context to the snapshot reddens CI until the job is marked; hand-narrowing it stays
green, exactly as the literal it replaced did.
Two things worth a reviewer's eye
Rule selection was EXTRACTED, not copied.
scripts/lib/branch-rule-classifier.jqis loaded byboth the hook and the checker. The extracted program is byte-identical to the inline original,
independently verified two ways (1115/1116 bytes, exact equality) and behaviourally identical across
29 payloads under both jq 1.8 and CI's pinned jq 1.6.
The scope index is built from
docker-build.ymlalone, not the git index — the release-pathscanjob runs that guard inside a non-git copy. A narrow index is safe because an unresolvablecontext is a hard error, so the guard gets louder, never quieter. The cross-workflow half that
genuinely needs the whole population lives in the separate guard above, which
script-testsruns.Verification
functional-e2e's context to the snapshot makes the guardname all 8 of its unmarked steps and go red — and now grows
DELIMITER_BAN_JOBSwith it.matchinstead of
drift; a workflow job renamed to collide reddens the uniqueness guard.branch_protectionspayload plus every declared class.scripts/tests: 1057 passed, 2 skipped. ruff check + format clean.decisions_validateOK.Review
Four cold rounds across two model families, each round re-reviewing the previous round's fixes:
Every finding is fixed or explicitly deferred to a filed issue, and each fix's red was witnessed
by disarming the exact clause it names.
The recurring pattern, worth naming: six of this change's own tests were caught passing for the
wrong reason, and every single one asserted the absence of something — a mutant that never ran,
an earlier arm answering, a
!= denya grant also satisfies, a stub serving a matching payloadeither way, a substring the catch-all arm also contains, and a clause with no coverage at all. They
now assert specific positive outcomes. Most consequential: the
assert not unaccountedline — themechanism this whole issue turns on — had no proof at all until round 3, and disarming it left 51
tests green.
Deferred, with issues rather than silence: #858 (the hook's verdict classifier resolves from
$CLAUDE_PROJECT_DIR— pre-existing, and this PR's own arm does it the safe way) and #859 (amalformed branch-protection rule states a cause that did not happen, plus the now-double
branch_protectionsfetch).Docs updated
docs/guard-inventory.md(three rows + asserted counts),docs/remote-state-inventory.md(scope +two rows),
docs/ci-cd.md, and the two decision records that named this gap as open — including, byclause, the rule's "or a dated staleness marker" alternative, which the new guidance rejects.
fixes #787
`scripts/tests/test_ci_dropped_step_guard.py` decides which jobs must carry per-step execution markers from `MARKED_JOBS = ("test", "migrations")` — a hand-written mirror of the required status contexts on `main`, annotated `Read live on 2026-08-10` and compared against the server by nothing. A dated comment is a claim about the past. Add a fourth required context and it acquired no dropped-step guard, silently, in the file the decision record names as its own model. The constraint that made this its own issue: `pr-checks.yml::script-tests` checks out with `persist-credentials: false`, so it cannot ask Gitea, and the issue's own candidate fixes were each unsatisfying — a snapshot "just moves the hand-maintenance", a credentialed check that skips without creds is the #756 fail-open. SPLIT THE INVARIANT AT THE CREDENTIAL BOUNDARY and check each half where it can be checked: * `.gitea/required-status-contexts.json` — the mirror, committed verbatim from the API. * The guard DERIVES `MARKED_JOBS` from it offline. Each candidate context string is SYNTHESIZED from the workflow (`<workflow name> / <job name> (<event>)`) and matched by equality, never parsed — the delimiters occur inside the names they delimit (`Build & test (.NET)` ends in a parenthesis of its own). A required context mapping to neither a job nor an explicit `ACCOUNTED_ELSEWHERE` disposition is a HARD failure at import, which is what makes a fourth required check impossible to add in silence. Both directions are asserted, so a disposition that stops being required is reported too. * `scripts/check-required-contexts.sh` reconciles the mirror against live `status_check_contexts`, called from `pretooluse-merge-consent.sh`. So the maintenance is now a verbatim copy with an equality check on each side, and updating it to match the server makes CI red until the newly required job is marked. Three decisions worth keeping: * The hook arm ASKS, never denies. Drift does not make that merge unsafe — Gitea enforces the live required set server-side — so a deny would state something false about the change in front of the reader. What is stale is a guard's scope. * It runs LAST, so it can only downgrade an otherwise-satisfied auto-grant and never masks a more serious refusal (asserted, not described). * It runs on BOTH merge paths. The pre-existing branch-protection read sits inside the `merge_when_checks_succeed` branch and never fires on an immediate merge — the common case. This hook already records that exact shape once: the base re-read "first landed inside the scheduled-auto-merge branch only", and cold review found scheduled+retarget denied while immediate+retarget auto-GRANTED. The scope index is built from `docker-build.yml` alone and deliberately NOT from the git index. An earlier draft derived it with `tracked_paths` and broke the RELEASE PATH: `docker-build.yml`'s `scan` job runs this guard inside a poisoned COPY of the tree where `git ls-files` exits 128, which is the trap `test_ci_release_path_scan_job.py` documents in the very paragraph this change edits. A narrow index is safe here because the failure direction is: the completeness claim is over the SNAPSHOT's contexts, so a missing workflow makes a context UNRESOLVABLE and the guard strictly louder, never quieter. That harness now stages the snapshot into its copy, named explicitly rather than by glob. Rule selection was EXTRACTED, not copied. `scripts/lib/branch-rule-classifier.jq` is now loaded by both the hook and the checker: this is a security predicate, and the hook's own history is the argument — the docs-only file enumeration was written twice, four rounds of hardening landed on one copy and never reached the other, and the copy with real authority ended up strictly weaker. An earlier draft of the checker had its own blanket "any glob metacharacter anywhere" test, which called a rule named `a[b` undecidable for `main`; the shared classifier's `superset` test does not. A structural test now pins that both callers reach the one file, replacing a first attempt that banned the token "gobwas" and flagged the comment saying the logic is DELEGATED. Cold cross-family review (Codex) returned BLOCKED with seven findings; all are fixed and each fix's red was witnessed: * THE MUTATION PROOF WAS VACUOUS. The mutant was copied without the classifier it loads beside itself, so it exited 2 with EMPTY stdout — and the assertion `stdout != "drift"` was satisfied by that empty string. The proof never reached the clause, so the `MUTATION` grade was unsupported. It now asserts the mutant's EXACT verdict `(0, "match")` and ships a positive control proving the tmp layout reproduces the real one. * Duplicate synthesized contexts silently overwrote in a dict. Two jobs sharing a `name:` collide on one context string, the later wins, and the other's steps go unguarded — branch protection cannot tell them apart either. Now a multimap with a uniqueness assertion. * `enable_status_check: false` was type-checked and its VALUE ignored, so protection with checks DISABLED certified as `match`. The comparison is now against the EFFECTIVE required set. * The checker and snapshot were resolved through `$CLAUDE_PROJECT_DIR`. An env var is not a sound input to a security decision — a wrong value pointing at a tree containing an executable checker returns `match` about a different checkout. Both now bind to the hook-derived `$repo_root`, and the missing-checker test runs a COPY of the hook, the only way to move that root. * `unreadable` is a DECLARED class that fell to the catch-all, which told the operator the checker had returned a word the hook did not understand. It has its own arm. Its test asserts on the IMMEDIATE path: on the scheduled path the h10 arm answers first, and the first draft passed without reaching the code it names. * `scripts/lib/*.jq` was outside the remote-state population, whose claim is that it has no content filter. Scope widened and the classifier given an `N/A` row. * The release-path Blocker it raised was already fixed in this branch before the review landed. A second cold review round (a different model family, and a re-review of the fix commit) returned BLOCKED on two findings, both fixed: * THE STATED INVARIANT WENT UNENFORCED THE MOMENT ONE SIDE STARTED MOVING. The file says "the delimiter ban is WIDER than the marker set", and while both were literals edited together that held. `MARKED_JOBS` now DERIVES, so on the day a fourth required context arrives the marker half goes red, the author adds markers, CI greens — and that job's `run:` bodies were never checked for the `${{` delimiter that CAUSES the drop the markers detect. `DELIMITER_BAN_JOBS` is now derived from `MARKED_JOBS`, and the property is asserted so a future edit back to a literal cannot re-open it silently. Measured: a planted 4th context grows both sets together. * `docs/guard-inventory.md`'s row claimed the context index came from the git index — true of the reverted draft, false of the shipped code, and in the artifact whose job is to be trusted about exactly that. Nothing asserts that column, so it would not have self-corrected. The cross-workflow half moved to its own guard, `scripts/tests/test_ci_status_context_uniqueness.py`. It has to be separate: a cross-workflow claim needs the whole workflow population, whose authoritative source is the git index, and the dropped-step guard cannot touch the index because the release-path `scan` job runs it in a non-git copy. Split, each half gets the right source. It is MUTATION-graded via the checker-guard shape — the guard IS a test, so disarming its own assertion makes it absent rather than red, and the declared mutation goes into the guarded ARTIFACT instead: a workflow job renamed to collide with the required `Build & test (.NET)` context, which is precisely the evasion. Folded in from the same round: the arm now runs only for the repo the snapshot NAMES (it was comparing any repo's live contexts against this repo's mirror — `server-management` returns `[]`, which classified as `nomatch` and would have reported a flatly false finding about it); the hook guards the shared classifier's readability itself, rather than inheriting a `jq -f` failure that blamed the payload for a missing local file; `unreadable` and the usage exits match their stated contracts; and `docs/ci-cd.md` records that the immediate merge path now needs a repo-admin-scoped credential, which it did not before. A fifth cold round returned MERGEABLE — no Blocker, no High, no Medium. It independently re-ran round 4's exact re-inlining attack and confirmed the suite now reddens on it, disarmed twelve further clauses and found each reddened only its own named test, and verified #857 survived the rebase intact. Its one Low and two nits were fixed rather than deferred, because the first made a claim in this message false: the sweep of the retracted "or a dated staleness marker" wording had covered `docs/` but missed a quoting site in `scripts/tests/test_optional_request_members.py`. The checker's stderr is no longer discarded either — a usage error used to reach the operator as "returned 'nothing'", naming no cause. Two prose overclaims of my own were corrected rather than defended: "neither half is checkable alone; composed, they are" now names the reconciliation as ONE bypassable client-side hook, and "updating it to match the server makes CI RED" now says ADD, because hand-NARROWING the snapshot narrows the derived scope and stays green exactly as the literal it replaced did. A third cold round (the cross-family reviewer had hit a usage limit, so this was the strongest available reasoning on a cold brief) returned BLOCKED. Its findings, all fixed and each red witnessed: * THE CENTRAL CLAUSE OF THIS CHANGE SHIPPED WITH NO PROOF. `assert not unaccounted` is what makes a fourth required check impossible to add in silence, and the decision record sells it as exactly that — but disarming it and planting a fourth context left the derived scope silently behind with 51 tests still green. `_derive_marked_jobs` now takes an injectable context list SOLELY so that clause and the anti-vacuity clause beside it can be proven; production calls it with no argument. * The `enable_status_check:false` fix from round 2 had ZERO coverage: removing that one clause returned `match` for disabled protection and all 71 tests stayed green, because the `rule()` helper's `enabled=` parameter had no call site that ever passed False — this repo's own recorded "a fixture that omits a field tests only the default". * A FIFTH test passing for the wrong reason: the missing-checker test asserted the substring `check-required-contexts.sh`, which the CATCH-ALL arm's reason also contains, so deleting the `[ ! -x ]` clause left it green — two guards masking each other (#685). It now asserts wording unique to the arm AND that no branch-protection fetch happened, which only the early clause prevents. * The repo gate was byte-exact while Gitea resolves owner/repo case-insensitively (verified live: `/repos/TIMOTHY/ErsatzTV` answers 200), so a case variant would skip the freshness arm entirely — the gate failing open on a spelling. * The new `branch_protections` read had no `docs/remote-state-inventory.md` row, and the checker's row delegated its fetch to "the caller's row" that did not exist. Added, graded `UNSAFE-KNOWN` with what it authorizes (nothing: every outcome is `ask` or silence). A fourth cold round returned BLOCKED on two independent grounds, both fixed: * THE SEVENTH TEST PASSING FOR THE WRONG REASON, and the one that mattered most: the "one classifier, two callers" property was asserted with a SUBSTRING over source text, which a COMMENT satisfies. Review proved it by re-inlining a byte-identical copy of the classifier into the hook with a comment naming the shared file — the entire suite stayed green at exactly 1062. The byte-identical inline is the refactor that matters, precisely because it agrees on day one; a weakened copy would have been caught behaviourally. Both callers are now proven by SWAPPING the shared file for a sentinel that can only answer `undecidable` and requiring their behaviour to change. Re-running review's exact attack against the fixed suite now reddens it. * THE HEAD WAS STALE AND THE REBASE WAS RED. `origin/main` had moved to #857, which touches five of the same files; this branch did not apply cleanly, and the guard-inventory counts were computed off the dead base. Rebased onto `45b17e58e`, counts resolved to 42/6/21 and 20/6/16, the generated catalog REGENERATED rather than hand-resolved. The earlier green vouched for a tree that no longer existed. Also fixed from that round: the required-`branch` clause was masked by the mismatch guard one line below it, so its test could not see it (#685 again — it now asserts the arm-unique stderr); three of the four freshness arms had no proof and were carried by the catch-all; the checker's own classifier-readability guard was the untested twin of a fix the hook made loudly; and the unaccounted-context diagnostic offered a remediation that is impossible for a context produced by another workflow. Two coverage overclaims were corrected rather than defended: the arm does NOT run for a docs/process -only PR, so a PR editing only the snapshot — the narrowing direction — never triggers it, and it could not have judged one anyway, since it compares the live server against the snapshot in the local checkout rather than the version the PR proposes. So SEVEN of this change's own tests were caught passing for the wrong reason across four rounds, and the pattern is one class — the mutation proof (a mutant that never ran), the `unreadable` arm (an earlier arm answering), the never-deny assertion, and the repo gate (a stub serving a matching payload either way). Every one asserted the ABSENCE of something. They now assert a specific positive outcome, and each fix's red was witnessed by disarming the clause it names. Self-found in the same round: the snapshot names its own `branch`, and a mismatch against `--branch` is now a usage error rather than a class — comparing one branch's live contexts against another's mirror would otherwise produce a confident verdict about a pair never meant to be compared. Verified: the mutation is witnessed, not asserted — unmutated reports `drift` on an added context, the mutant with the set comparison disarmed reports `match`, a permanent no-op. The checker was run against the LIVE branch_protections payload (`match`) and every other class exercised. Full `scripts/tests` suite green; ruff check + format clean. Sweep by subject: every site claiming this gap is open was updated — `docs/guard-inventory.md`, `test_ci_release_path_scan_job.py`, `test_guard_populations_derive_from_git.py`, `test_ci_image_pin_population.py` (whose remaining `TOOLCHAIN_JOBS` literal is #789), and by clause, the rule's "or a dated staleness marker" alternative, which the new guidance rejects. fixes #787 Decisions-Edit: yes Co-authored-by: Timothy <timothy@noreply.gitea.tblindustries.be>Review-verdict: MERGEABLE @
b1b9c1a5 cold rounds (2 model families); round 5 clean. Every declared clause witnessed red by disarming it.