Skip to content

feat(gate-114): count the header actions bar, and warn when it grows - #723

Merged
rubenvdlinde merged 2 commits into
mainfrom
feat/gate-114-header-action-budget
Sep 9, 2026
Merged

rubenvdlinde merged 2 commits into
mainfrom
feat/gate-114-header-action-budget

Conversation

@rubenvdlinde

@rubenvdlinde rubenvdlinde commented Sep 9, 2026 •

Copy link
Copy Markdown
Contributor

What this adds

Gate 114 counts the buttons a page declares in config.headerActions[], across the effective manifest, and warns when a page's count grows against the delta base.

It ships as a warning. Nothing here can redden a repository.

Why

Three surfaces in dossiq, over the same fifteen changes:

Surface Budget What happened
Main navigation four to six, ADR-097 held at five
Case page tabs none ten to fourteen, then days of refactoring back to six
Case header actions none one to twelve, and nobody was counting

Measured on dossiq at development on 2026-09-09. Eleven of the twelve landed on a single day, 2026-09-08, across six pull requests (#1902, #1907, #1908, #1913, #1929, #1935). Not one has ever been removed. Every one of them merged green, because nothing in this package reads that array.

Replayed against this gate, the two biggest jumps report as findings. Commit 0f0d36c61 goes 3 to 7. Commit f060b12c3 goes 9 to 12.

For scale, the census across the fleet's working copies: dossiq's case page carries 12. The next longest bar anywhere is 3.

A ratchet, not a ceiling

A ceiling asks someone to guess the right number today. Nobody knows whether a case page should carry four buttons or seven. A guess that lands high enforces nothing, and a guess that lands low blocks work that is fine.

A ratchet asks the smaller question that has an answer: is this bar longer than it was at the base. Same shape as gate-69's custom-page ratchet and gate-52's custom-widget ratchet, and no checked-in baseline to go stale.

The finding is per page. An app-wide total would let one page grow as long as another shrank, and the complaint is never about an app's total. The app-wide census is printed anyway, on every run, because a gate that is silent when it passes cannot be shown to have run.

Warning first

This package resolves at @main for all 21 core apps. A blocking gate lands fleet-wide the minute it merges and fails every repository carrying inherited debt. So _warn, which keeps the gate inside the COVERAGE tally and leaves the failure count alone.

Promotion to blocking is a deliberate edit in two places: the runner, and arm 4 of test_check_header_action_budget.py, which pins the exit code at 0. Wire findings into the return value and that arm goes red immediately. That is the point of it.

The gate still calls _pass and _skip, not _warn alone. The declared inventory and check_gate_numbers_unique.sh both read _(pass|fail|skip) call sites and neither reads _warn, so a gate registered only as a warning is a gate the coverage accounting has never heard of.

One thing this PR found on the way, and did not fix

Three existing ratchets do not run in CI. Gates 52, 68 and 69 pass their base ref to their checker only inside if [ "${SCOPE_TO_DIFF}" = "1" ]. The shared quality workflow never puts this runner in diff scope. Full scope has been the default since ADR-020 was superseded, and --scope-to-diff appears in no workflow file. So the base is always empty for those three, and each ratchet half is skipped.

Verified on dossiq on 2026-09-09. Plant a thirteenth type:"custom" page and run gate-69's checker both ways:

no HYDRA_GATE_BASE_REF (the mode CI uses)   0 findings, empty log
HYDRA_GATE_BASE_REF=HEAD                     custom-page ratchet: 12 -> 13 (+1)

Gate-52 already prints a line saying its ratchet half was not computed. Gate-68 and gate-69 say nothing at all, and gate-69 is the one ADR-100 is enforced by. dossiq's custom-page count went 11 to 12 twice since gate-69 landed on 2026-08-21, in #1677 and #1985, and neither run reported anything.

Gate 114 is therefore wired the other way. It hands the checker ${BASE_REF} unconditionally, the way gates 16, 29, 47, 48 and 61 take theirs, and it prints a named line when there is no base so a reader can tell a ratchet that passed from one that never ran.

Turning the other three on is a separate change and a bigger decision, because all three are blocking and would start firing fleet-wide on the day they connect. Worth doing next, and worth doing on its own.

Per repo promotion

HYDRA_GATE_HEADER_ACTION_BUDGET_BLOCKING=1 makes the same finding block, for one app. That is the gate-112 and gate-113 convention. An app that has measured its bars and worked them down flips it on for itself, without waiting for the fleet. Tracking issue: #724.

Evidence

Watched, not assumed:

  • 8 unit arms, each mutation checked. Every arm was watched go red against a mutant that expresses its defect, then watched go green again, and the checker was diffed byte for byte against the backup afterwards.
  • Full runner on dossiq at development, no growth: [gate-114] header-action-budget: PASS, plus the named line saying the ratchet half had no base in that local run.
  • Full runner on dossiq with a thirteenth action committed, base development: base=22 head=23 delta=+1 and WARNING. The run's failure count was unchanged by it.
  • check_gate_numbers_unique.sh: 94 gates, every number claimed once. 114 was free on origin/main at branch time and rechecked before this PR.
  • tests/test-hydra-gates-bin.sh: 70 passed, 0 failed.
  • tests/run-helper-suites.sh: both new suites are auto-discovered and pass. The one red suite is test_gate_45_to_55_acceptance.sh, which refuses to run without ajv on this machine and is unrelated.
  • test_gate114_header_action_budget_scope.sh: 15 assertions over a real two-commit history, driving the real wrapper. Planted growth, a new page, a removal, inherited debt, no base, and the per-repo opt-in. Arm 6 was mutation proved: swallow the notice that the ratchet did not run and it goes red on its own.
  • test_gate_acceptance_matrix.sh: 250 passed, 0 failed. 87 of 94 gates fixtured, gate-114 among them.
  • test_gate_discarded_counts_and_empty_deltas.sh: 37 assertions, 0 failures. The advisory allowlist now reads 19 112 113 114, each with its reason and its issue.

Next

Merge this, then decide separately whether gates 52, 68 and 69 should read their base off the delta channel too. That change turns three dormant blocking ratchets on at once, so it wants its own pull request and its own measurement of who it reddens.

Conduction Release Bot added 2 commits September 9, 2026 11:22
dossiq's case page went from one header action to twelve while everyone
watched the tabs go ten to fourteen. Eleven of the twelve landed on a single
day, 2026-09-08, and not one has ever been removed. Every one arrived in a
green pull request, because nothing in this package reads
config.headerActions[].

The navigation next to it has a budget of four to six and an ADR enforcing
it, and it held at five over the same fifteen changes. Whatever is not
counted is where the complexity goes.

Gate 114 counts the bar on every page of the effective manifest, prints the
census on every run, and reports a page whose count grew against the delta
base. A ratchet, not a ceiling: nobody knows the right number today, and
everybody can answer whether the bar is longer than it was.

It ships as a WARNING. This package resolves at @main for all 21 core apps,
so a blocking gate lands fleet-wide the minute it merges. Promotion is a
deliberate edit here and in the test that pins the exit code.

The base comes off the delta channel unconditionally, the way gates 16, 29,
47, 48 and 61 take theirs, and NOT behind SCOPE_TO_DIFF. That condition is
how gates 52, 68 and 69 pass their base, and the shared quality workflow
never puts this runner in diff scope: full scope has been the default since
ADR-020 was superseded, and --scope-to-diff appears in no workflow. Those
three ratchets therefore do not run in CI. Verified by planting a thirteenth
type:"custom" page in dossiq: gate-69's checker reports one finding when
handed a base and zero in the mode CI uses.
…er the advisory

The package invariants on #723 named two gaps, both of them real.

The acceptance matrix requires every declared gate to have planted and clean
arms, or a reasoned row. gate-114 now has a wrapper-level suite over a real
two-commit history, the way gates 16, 98, 100, 101, 108 and 110 are covered,
because a delta gate in a bundle has no git and can only report its census.

ARM 6 is the one that matters. With no delta base the ratchet cannot run, and
the run has to NAME the half that did not run. That is exactly the defect
gates 52, 68 and 69 carry: measured on dossiq PR #1985, gate-69 printed PASS
over a custom-page increase with its delta base resolved and SCOPE-MODE full.
Mutation proved: swallow the notice and ARM 6 goes red on its own.

ARM 7 adds the per-repo promotion path the gate-112 and gate-113 convention
uses. HYDRA_GATE_HEADER_ACTION_BUDGET_BLOCKING=1 makes the same finding block
for one app, so a repo that has worked its bars down does not wait for the
fleet.

The advisory allowlist in test_gate_discarded_counts_and_empty_deltas.sh
bounds which gates may be non-blocking, by name and with a reason. 114 is
added with its tracking issue, .github#724.
@rubenvdlinde
rubenvdlinde merged commit 9452c35 into main Sep 9, 2026
40 checks passed
@rubenvdlinde
rubenvdlinde deleted the feat/gate-114-header-action-budget branch September 9, 2026 15:06
rubenvdlinde pushed a commit that referenced this pull request Sep 10, 2026
#734 landed first and took the two lines both PRs said they would touch: the
enumerator's find and the empty-scope skip reason. #723 and #736 took gate
numbers 114 and 115 and both rows of the advisory allowlist.

Every conflict is resolved as a UNION, never by taking one side whole. The
skip reason names five directories AND both tags. _ADVISORY_ALLOWED_GATES is
"19 46 112 113 114 115" with #723's and #736's reasons kept verbatim; the
diff against main for that file is additive apart from one word, four -> five.

#734 also took arm numbers 5 to 7, so this branch's four arms are renumbered 8
to 11, temp fixture directories included, and the header prose that named them
moved with them. A prose reference that disagrees with an arm header is how a
suite ends up describing a test it is not running.

Arm 12 is new and exists only because of this merge: the second tag inside the
newly opened directory, the one square neither change covered alone. #727
predicted it in as many words.

Verified on the merged tree, not on the branch point:
check_gate_numbers_unique.sh 95 gates every number claimed once,
test_gate_46_tests_scope.sh 20 assertions green, the acceptance matrix 254
passed 0 failed, test_gate_45_to_55_acceptance.sh all green,
test_gate_discarded_counts 37 assertions, the unit suite 70 tests.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant