ci: add a single aggregate required-check job to unit-tests.yml

[JarryShaw]

Please follow the guide below

• Searched for similar pull requests
• Followed the coding style (make pylint, make mypy, make isort)
• make test passes, and a test case covers the change — N/A, workflow-only; no library code changes
• Added a changelog entry — N/A — changelog centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

• ci — workflows or build tooling

---

Description of your pull request and other information

The problem

Ruleset 23497679's required_status_checks names 22 exact check contexts by literal
string, and GitHub rulesets support no wildcard: 5 for test, 5 for integration, 5 for
Compat Python 3.10..3.14, 5 for the old single-cell Engines Python <version> name, and
2 for pypcap-parity. Only the 5 Engines names are actually dead — engine-tests
stopped producing them once it became a Python × engine matrix. The 5 Compat names are
live, emitted by python-compatibility.yml's own compatibility job on the same
push/pull_request triggers, confirmed by reading that file — a needs: in this file can
never stand in for a job in a different workflow file, so those 5 must stay required as-is.
Growing or shrinking the matrix still means hand-editing the required list — the owner's
framing: "CI all passed but russet gates not getting their expected results? Actually are
those ruleset things necessary? We can already gate on CI passing."

What this adds

One new job, required-checks, emitting a single stable check context:

Required checks passed

That is the exact string to add to ruleset 23497679, in place of the 17 test/
integration/Engines/pypcap-parity entries — not the 5 Compat ones, which stay.
It needs: [test, integration, engine-tests, pypcap-parity]; not gate (release-only,
permanently skipped on a PR) and not changelog (a drift check, not currently one of the
22, left for a separate call).

Why it isn't just a plain needs: job

A job with a bare needs: list is skipped, not failed, the moment a dependency fails —
and GitHub's own "Troubleshooting required status
checks"
page lists skipped as a passing status, and says a job skipped because it depends on a
failed job "may not block merging." Its own recommended fix is this job's shape:
if: always() plus an explicit per-dependency check, printing every needs.<job>.result
and failing loudly (naming the job) on anything but success. engine-tests's 6
unsupported + 4 not-installable cells don't need special-casing: that job's own install
step exits 0 for a cell that declined exactly as expected, so those cells still report
success at the job level, never skipped.

One risk is flagged rather than resolved: engine-tests also carries
continue-on-error for its 3.15 legs (non-blocking, per #845), and GitHub's docs don't say
whether a real 3.15 failure is neutralised to success in needs.engine-tests.result the
way it is for the run's own conclusion. See the job's own comment for why splitting 3.15
into its own job was judged too much churn to close a single undocumented edge.

Verified: yaml.safe_load parses the file; git diff --numstat against origin/main shows
one file, 167 insertions, 0 deletions. Unverified: the run itself — GitHub Actions can't be
exercised locally.

[JarryShaw]

NEEDS CHANGES on 2dbc790fa — cross-review (opus, a different model from the sonnet author). The job's
mechanism is sound and verified. Its comment is not, and in this PR the comment is the deliverable: it is
what the owner acts on when editing the ruleset.

1. The five Compat Python 3.10–3.14 contexts are NOT stale, and this was my error, not the author's. I
briefed the reviewer that no job emits them. It refuted that, and I reproduced it:

.github/workflows/python-compatibility.yml:31   name: Compat Python ${{ matrix.python-version }}   (push, pull_request)
gh pr checks 856  ->  Compat Python 3.10..3.14  all pass, 13-15s each

A different workflow file, which needs: cannot reach. So of the 22 contexts only the five Engines Python 3.10–3.14 are genuinely stale, and this job covers 17 of 22. The comment at lines 805–812 calls the
Compat five stale and tells the reader to drop them — following that would silently stop gating Python
3.10–3.14 import coverage. Correct the comment, and state that the ruleset must retain those five alongside
Required checks passed.

2. engine-tests carries continue-on-error: ${{ matrix.python-version == '3.15' }} (unit-tests.yml:331,
pre-existing, per #845's ruling that 3.15 is experimental). The new comment asserts "there is no path in this
workflow where a real dependency legitimately reports anything other than success on a PR run" — a failing
3.15 engine cell is exactly that path, by design. Whether needs.engine-tests.result reads success or
failure when only a continue-on-error cell fails is undocumented and UNVERIFIED. If it reads failure, a
3.15 regression turns the sole required context red and blocks every merge — worse than the gate it replaces, and
against #845's ruling. Preferred fix: split the 3.15 legs into their own job that required-checks does not
depend on. Minimum: say so in the comment and stop claiming the path does not exist.

What is confirmed, and the sharp one went the author's way. I flagged inputs.gate-only != true as likely to
make the condition false on a pull_request event and silently remove the gate. It does not. The four
dependencies already carry the identical sub-expression on main (unit-tests.yml:51,131,325,603) and all ran
on this PR's own run, while gate — whose if: is == true — reports skipping. The input is declared
workflow_call-only with type: boolean, default: false, and no parse error occurs.

Also confirmed: context string Required checks passed is unique across all 8 workflow files and carries no
matrix interpolation; all four needs: names resolve, with gate correctly excluded (release-only) and
changelog correctly excluded (never among the 22, so including it would widen the merge requirement — the
reviewer attacked this on my instruction and came down on the author's side); the diff is a single pure insertion
@@ -803,0 +804,96 @@, triggers/permissions/concurrency byte-identical to main; 36 cells, 6 unsupported, 4
not-installable, no exclude:, and no declined cell yields a job-level skipped.

The result-checking step was exercised, not eyeballed — eight fabricated needs.*.result combinations under
bash -e: all-success exits 0; failure, cancelled, skipped, empty and neutral each exit 1 naming the
offending job; multiple breakages all reported. set -eu present, failed=1 set in a brace group so it survives,
no continue-on-error on the aggregate itself.

One latent trap worth recording: under workflow_call the context becomes <caller job> / Required checks passed and would not match the ruleset — harmless only because the sole caller (create-release.yml:85-87)
passes gate-only: true, which skips this job.

[JarryShaw]

NEEDS CHANGES on a0fc15699 — second cross-review (opus). Both defects are one line, both in the comment,
and in this PR the comment is the deliverable: it is what you read while editing the ruleset.

1. The cell count contradicts its own quantifier. unit-tests.yml:818 reads "re-list every engine-tests
matrix cell name (30 of them, growing or shrinking with the matrix)". Measured from the parsed matrix:

versions: 3.10 3.11 3.12 3.13 3.14 3.15  ×  6 engines
cells = 36        gating (3.10-3.14) = 30

36 cell names exist; 30 is the gating subset. "every" and "30" cannot both be true. Either the number
becomes 36 or "every" becomes "every gating (3.10–3.14)". Carried over unflagged from round 1.

2. "Splitting the 3.15 legs is the only alternative" is overstated. :900-902 justifies not splitting by
"duplicating this job's ~150 lines". The ~150 figure is honest — if anything understated: the three things it
names measure 182 raw lines (:403-442 system packages 40, :443-539 per-engine install 97, :556-600 test
invocation 45), and GitHub Actions has no YAML anchors, so a split is literal copy-paste. So the split is
correctly rejected on cost.

But it is not the only route. Moving continue-on-error from the job level to the failing steps inside
engine-tests removes the dependence on undocumented behaviour too, at ~2 lines — and it lands on documented
ground where the job-level form does not. I am not asking you to change the mechanism: step-level would make
a 3.15 leg read green rather than red, weakening the "a regression stays visible" half of #845's ruling, which is
a real trade-off. Only the clause claiming a 182-line duplication is the sole alternative needs to go.

The documentation finding is the valuable part of this round, and it cuts toward the risk being real. GitHub
documents the neutralisation precisely where it applies to steps and nowhere for jobs —
contexts.md:540-541: "steps.<step_id>.conclusion — The result of a completed step after
continue-on-error is applied … the outcome is failure, but the final conclusion is success." There is
no outcome/conclusion pair for a job reached through needs: contexts.md:779 gives only
needs.<job_id>.result with values success/failure/cancelled/skipped and no mention of
continue-on-error. Evidence, not proof — so it stays UNVERIFIED until a real run — but the comment's claim
that the docs do not state it is accurate.

Confirmed this round: the 17/22 arithmetic is exact in both comment and body (5+5+5+2 = 17, 5 Compat
retained); Compat is live — all five pass on this PR from run 36330247160, workflow Python
Compatibility, whose on: filters are byte-identical to unit-tests.yml:3-7; Engines Python <version> is
genuinely dead — a real run on main emits 36 rows of Engines Python 3.1x (<engine>) and zero bare
Engines Python 3.1x; the diff is one hunk @@ -803,0 +804,140 @@, zero deletions, so triggers/permissions/
concurrency are unchanged by construction; the 44 new lines are all comment and the job body is
byte-identical to round 1, so round 1's eight-combination shell exercise still stands.

The workflow_call trap was confirmed empirically, not just by reading: create-release.yml:80-87 does pass
gate-only: true, and a real create-release run emits Release test gate / Changelog drift — so the prefix is
the caller job's name:, exactly as the comment says.

[JarryShaw]

NEEDS CHANGES on aa5d7acd7 — third cross-review (opus). Two wrong numbers, nothing else. Both re-measured
by me.

1. The comment says the continue-on-error reference "has three sentences". It has four. unit-tests.yml:894
and :896 ("none of the three"). The page reads:

`jobs.<job_id>.continue-on-error` applies to a single job.            <- 1, silently dropped
If ... is `true`, other jobs in the matrix will continue running ...  <- 2
Prevents a workflow run from failing when a job fails.               <- 3
Set to `true` to allow a workflow run to pass when this job fails.   <- 4

The omitted sentence is the scoping one — the sentence a checking reader notices first, because it is the one
most adjacent to the question being asked. This is a fresh factual error about the same docs page whose
mischaracterisation round 2 flagged, in the paragraph rewritten to fix that. The conclusion survives verbatim
(sentence 1 says nothing about needs.<job>.result either), so it is an enumeration fix, not an argument fix.

2. The PR body asserts "140 insertions" under "Verified:". Actual at this head is +166/−0
(gh api .../pulls/856/files). A stated verification that is no longer true.

Two cosmetics worth taking in the same pass: :820 is an orphan # something that does — the paragraph was
edited without re-flowing; and the clause "this is evidence for that reading, not proof of it" is ambiguous
about what "this" refers to, reading as a contradiction if taken to mean the asymmetry. One word fixes it.

Everything substantive is confirmed, and the numbers I asked to be attacked all held exactly:

• The narrowed quantifier's premise holds. Ruleset 23497679 (enforcement: active, 22 contexts) names no
  3.15 or 3.16 context, so only the gating names could ever be listed. And 30 is exact, derived by parsing
  rather than multiplying: 36 cross-product cells, 10 include entries of which 0 create new cells (they only
  attach expect:), leaving 30 gating cells and 30 distinct check names.
• 182 raw lines confirmed to the line: :403 40 + :443 97 + :556 45. Non-comment equivalent is 82, and the
  comment says "raw lines", so it is honestly labelled rather than inflated.
• The step-level rejection is documented, not rhetorical. contexts.md: a continue-on-error step's outcome
  is failure but its conclusion is success → the leg goes green and the regression is hidden. The job-level
  contrast is equally supported: "Prevents a workflow run from failing" — the job itself still reads red, which
  is ci: engines not exercised across their claimed Python ranges — PyShark has no real-capture coverage, PyPCAPFile dark on 3 of 5 legs #845's "stays visible" half.
• The asymmetry does not overstate. needs.<job_id>.result lists exactly the four values the comment names,
  with no outcome/conclusion pair anywhere in the needs table. Hedging intact throughout — "suggestive, not
  conclusive", "one open, unverified risk".
• The job body is byte-identical to round 2 at 1763 bytes, and every non-comment line in the whole file is
  unchanged (425 both rounds), so round 2's eight-combination shell exercise carries forward untouched. One hunk,
  @@ -801,3 +801,169 @@, pure append.

One caveat recorded, not a required change: "growing or shrinking with the matrix" over-claims in exactly one
case — adding 3.16 as a second prerelease leg without graduating 3.15 would take the matrix 36→42 while the
gating count stays 30. Not this repo's version pattern, and it misdirects the ruleset edit in no direction.

[JarryShaw]

GOOD TO GO on 28e4b8834. Both required changes from round 3 are done, and only comment lines moved — so
the three rounds of verification on the job itself carry forward unchanged.

Verified by me:

comment now reads "four sentences" (:894) and "none of the four" (:897)
the ambiguous "this" is now "that argument is evidence for that reading" (:909)
body Verified: line -> 167 insertions        gh api .../pulls/856/files -> +167/-0   agree
non-comment, non-blank lines of the whole file:
  aa5d7acd7 -> e50699059a2cc0207c2518c4a5497405
  28e4b8834 -> e50699059a2cc0207c2518c4a5497405      identical

That last one is the load-bearing check: the required-checks job body — name:, needs:, if:, runs-on:,
timeout-minutes: and every line inside the run: | block — has been byte-identical since round 2, whose
eight-combination bash -e exercise of the result-checking logic therefore still applies. The orphaned short
lines are re-wrapped and the paragraph now flows at a consistent ~74-78 columns.

Three cross-review rounds on opus against a sonnet author. What each round cost, for the record: round 1 caught
my own wrong claim that the five Compat contexts were stale; round 2 caught the 30-vs-36 quantifier and the
overstated "splitting is the only alternative"; round 3 caught a miscount of the continue-on-error reference's
sentences and a stale insertion count. Every defect across all three was prose, never the job.

---

Your step once this merges

Edit ruleset 23497679's required-check list:

• Add Required checks passed — exactly that string.
• Remove the 17 it replaces: Python 3.10–3.14 (5), Integration Python 3.10–3.14 (5),
  Engines Python 3.10–3.14 (5), PyPCAP/PyPCAPFile parity Python 3.10 and 3.11 (2).
• Keep the five Compat Python 3.10–3.14. They are emitted by python-compatibility.yml, a different
  workflow file that a needs: can never reach, and they pass on every PR. Dropping them silently ends Python
  3.10–3.14 import gating.

Net: 22 contexts → 6.

One open risk, stated plainly because it is unverifiable without a real run. engine-tests carries
continue-on-error for 3.15 per #845's ruling. Whether needs.engine-tests.result reads failure or success
when only a 3.15 cell fails is undocumented — GitHub documents the neutralisation for steps
(conclusion vs outcome) and says nothing for jobs reached through needs. If it reads failure, a 3.15-only
regression would turn this single context red and block every merge. The comment says so, and says what to do:
re-run to confirm before treating it as real, and revisit the split then.

[JarryShaw]

Merged — here is the exact ruleset edit I owed you, now that this is on main.

Ruleset 23497679, required-check list:

Add — exactly this string:

Required checks passed

Remove these 17:

Python 3.10   Python 3.11   Python 3.12   Python 3.13   Python 3.14
Integration Python 3.10   Integration Python 3.11   Integration Python 3.12
Integration Python 3.13   Integration Python 3.14
Engines Python 3.10   Engines Python 3.11   Engines Python 3.12
Engines Python 3.13   Engines Python 3.14
PyPCAP/PyPCAPFile parity Python 3.10   PyPCAP/PyPCAPFile parity Python 3.11

Keep these 5 — do not remove them:

Compat Python 3.10   Compat Python 3.11   Compat Python 3.12
Compat Python 3.13   Compat Python 3.14

They come from .github/workflows/python-compatibility.yml:31, a different workflow file that a needs: can never
reach, and they pass on every PR. This was my error earlier — I first told you all 22 could go. Net: 22 contexts
→ 6.

The one open risk, restated so it is not a surprise. engine-tests carries
continue-on-error for 3.15 per #845. Whether needs.engine-tests.result reads failure when only a 3.15 cell
fails is undocumented — GitHub documents the neutralisation for steps (conclusion vs outcome) and says
nothing for jobs reached through needs. If it reads failure, a 3.15-only regression would turn this single
context red and block every merge. If you ever see Required checks passed red with only a 3.15 leg failing under
it, that is this gap and not a real regression — re-run to confirm, then we split the 3.15 legs into their own job.