fix(787): derive the dropped-step guard's scope, and reconcile its snapshot against the server #861

Merged
timothy merged 1 commits from fix/787-dropped-step-scope into main 2026-08-28 00:37:05 +02:00
1 Commits
Author SHA1 Message Date
timothy b1b9c1a9d4 fix(787): derive the dropped-step guard's scope, and reconcile its snapshot against the server
Build ErsatzTV Image / CI toolchain image resolves (pull_request) Successful in 11s
Build ErsatzTV Image / Delimiter ban (release path) (pull_request) Successful in 23s
PR Gates / CI image pin matches docker/ci (pull_request) Successful in 17s
PR Gates / Docs update reminder (pull_request) Successful in 17s
review-verdict/h10 Review-verdict: MERGEABLE @ b1b9c1a (base: main)
PR Gates / Fix proofs (Proves trailers) (pull_request) Successful in 11s
PR Gates / decisions lifecycle (pull_request) Successful in 21s
Review verdict / Set review-verdict status (pull_request_target) Successful in 9s
PR Gates / Script lint and tests (ruff + pytest) (pull_request) Successful in 6m36s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 8m38s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 6m15s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Skipped
Build ErsatzTV Image / Functional E2E (curl + UI contracts) (pull_request) Successful in 5m51s
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Successful in 10s
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Successful in 6s
`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>
2026-08-27 23:33:59 +02:00