fix(hydra-gates): a not-applicable gate is not a coverage gap — fix the accounting, then flip the flag

[rubenvdlinde]

PO instruction, verbatim: "if a gate is legitimately not applicable the flag shouldnt fail the run"

What the current code actually does — measured, not inferred

_skip deliberately does not add to _EMITTED_GATES, so every skip counts against coverage. And most gates never even reach a _skip: they are wrapped in a bare if [ -d src ] with no else, so when the prerequisite is false they emit nothing at all — no line, no reason, no trace.

Measured on a Tier-0 fixture with nothing wrong with it:

[hydra-gates] COVERAGE: 33 of 63 declared gates reported a result.
[hydra-gates] GATES THAT DID NOT RUN: 4 5 6 7 10 12 13 14 15 19 22 24 25 26 31 32 33
                                      34 35 36 37 38 39 40 41 42 43 44 45 53
EXIT=98

30 of 63 gates did not report; 25 of them only because the repo has no src/. Of the 30, just 4 emitted a SKIPPED line at all — the other 26 were pure silence. So yes: category (a) currently fails the run, and the flag was unusable fleet-wide.

Three states, only two fail

verdict	meaning	counts?
NOT APPLICABLE	subject matter absent from this repo/diff	no
SKIPPED (structural)	subject matter EXISTS, nothing produced the gate's input	yes
SKIPPED (wiring)	the gate's own helper/tool is missing	yes

wiring is called out separately because it is the worst shape: a missing helper once let gate-7 report PASS over 11 real unguarded IDOR endpoints.

Gates 4, 24 and 33 — classified explicitly

gate-4 had three ways to emit nothing, all byte-identical to success:

• no composer.json → na (no PHP dependency tree exists)
• composer.json/.lock not in a diff-scoped run → na (ADR-020 — the case the PO named)
• composer not on PATH → wiring. A dependency tree that exists and was never audited. This one had no output whatsoever before.

gate-24 is split on the gate's own subject matter, not on the presence of its checker — the only test that cannot drift from what the gate correlates:

• no new LeafDescriptor( in lib/ and no registerIntegration( in src/ → na (there is no pair to correlate)
• either present, no parity script → structural

Deciding from [ -f scripts/check-integration-parity.sh ] alone is why every repo in the fleet reported the same skip regardless of whether it had any leaves.

gate-33's input is the one thing the runner cannot make for itself:

• no src/ → na
• src/, caller never declared enable-axe → na — that choice is a visible line in the caller's workflow, not a gap hidden in the runner
• enable-axe declared, report absent → structural, and it fails

quality.yml now passes --axe-enabled from inputs.enable-axe so the runner can tell those apart instead of guessing "unverified" for both — which is what made the flag unusable everywhere.

Two things stop NOT APPLICABLE becoming a mute

1. Silence still counts AGAINST coverage. A gate that emits nothing is a gap by default. To stop counting it must declare itself not-applicable, by name and with a reason.
2. The category is validated. na|structural|wiring only; anything else is a hard gate failure, never a default. A gate cannot stop counting by misspelling its reason. Asserted in the suite — with a reverse control proving the unpatched runner does not emit that error.

The 25 silent gates are covered by applicability declarations restating each group's own if guard, negated. They cannot mask a live gate: _declare_na refuses to touch a gate that already reported, and each condition fires only when the prerequisite is absent — so a gate that stays silent while its subject exists remains a gap exactly as before. A positive control asserts that with src/ present, all 16 src-guarded gates really run, so table-vs-guard drift is detectable.

Both directions proven

Either alone is satisfiable by a broken flag — one that never fails passes the first, one that always fails passes the second.

run	expected	measured
only category-(a) skips, flag ON	0	EXIT=0 — 33 of 33 applicable gates ran
+ an integration leaf registered, no parity check (b)	98	EXIT=98 — [gate-24] SKIPPED (structural)
helper check_no_admin_idor.py removed (c)	98	EXIT=98 — [gate-7] SKIPPED (wiring)
--axe-enabled with no report (b)	98	EXIT=98 — [gate-33] SKIPPED (structural)
typo'd category nq	fail	FAIL — … not one of na|structural|wiring

Suite 25 → 31 tests, 0 failing.

bin/hydra-gates had to learn the new verdict

It recomputes coverage independently. A NOT APPLICABLE line contains no ': SKIPPED', so the old filter would have counted every not-applicable gate as having REPORTED A RESULT — miscounted silently, in the direction that always reads better than the truth. It also no longer prints ALL 63 GATES PASSED — and all 63 of them ran over a run where 30 did not.

Blast radius of the flip — measured on real repos, flag ON

repo	not applicable	DID NOT RUN
openregister	4, 33	none
opencatalogi	4, 7, 24, 33	none
docudesk	4, 6, 7, 24, 33	none
hermiq	4, 33	24
openconnector	4, 7, 33	24

Three of five have complete coverage. The two that don't fail on a genuine, named, actionable gap: both register integration leaves and neither ships a parity check. That is the flag working, not the flag misfiring. Only repos with enable-hydra-gates: true are affected at all.

Verification

• actionlint positive-controlled (exit 1 with 2 real findings on a deliberately broken workflow); this branch exit 0.
• The default: true and the arg wiring verified from the parsed YAML, not the draft: DEFAULT from parsed YAML : True bool.
• Rebased onto main after fix(quality): scope axe to the app's own DOM, and prove the scope is not a mute #161 merged.

🤖 Generated with Claude Code