feat(gates): host conduction/hydra-gates here, and wire it into the shared quality workflow

[rubenvdlinde]

Why

The 61 mechanical gates were packaged and merged into hydra (ConductionNL/hydra#504), but the pilot — ConductionNL/openbuild#104 — could not ship. It consumed the package through a composer path repository at ../hydra, which works on a developer machine and fails in CI with Source path "../hydra" is not found (10 failed composer jobs). hydra is private, so a vcs repository pointed at it would need credentials in every consuming repo and every runner.

This repository is public and already owns the shared workflows, so hosting the package here solves distribution and puts the gates into the default checks.

What is here

hydra-gates/ is now the single source of truth for the gate runner, its 24 Python/JS helpers, the vendored manifest + icon schemas, and the distributable bin/hydra-gates. The root composer.json names the package, so a plain vcs repository resolves it — composer has no subdirectory-package support, which is why the manifest is at the root rather than inside hydra-gates/.

hydra delegates; it keeps no copy (see the companion hydra PR). Two copies that drift is the failure these gates exist to catch.

Git history was deliberately not imported. A subtree split would have published the private orchestrator's commit history into a public repository. Provenance is recorded in hydra-gates/README.md.

Only gate code was moved. hydra-internal helpers — forge-api.sh, github-rest.sh, env-credentials.sh, load-config.py, the record/board tooling — were explicitly not copied, and the payload was scanned for credential-shaped strings and for references back to them before commit.

How a repo adopts it

Shared workflow (no composer needed, works for non-PHP repos):

uses: ConductionNL/.github/.github/workflows/quality.yml@main
with:
  app-name: yourapp
  enable-hydra-gates: true

composer (gates inside check:strict):

"repositories": [
  { "type": "vcs", "url": "https://github.com/ConductionNL/.github.git", "no-api": true }
],
"require-dev": { "conduction/hydra-gates": "^1.0" }

"no-api": true makes composer clone over git instead of the GitHub API, so a rate-limited unauthenticated runner cannot turn into a failed install.

Blast radius of the quality.yml change

A new job, opt-in per repo, enable-hydra-gates defaulting to false. Zero repos change behaviour until they opt in.

This was the deliberate choice over a fleet-wide hard gate. The gates are diff-scoped per ADR-020, but switching them on everywhere at once turns red every repo whose in-flight branches happen to touch files carrying inherited debt — openbuild alone fails 16 gates on a full-repo run. Staged opt-in lets each repo enable it once its own diffs are clean.

When enabled, the job joins report's needs, so a gate failure blocks the Quality Report rather than being a green box nobody reads. Two further inputs are also opt-in: hydra-gates-ref (pin the gate version so a gate change cannot alter a repo's verdict without a commit in that repo) and hydra-gates-require-full-coverage.

The properties that had to survive

• Exit code is the failure COUNT. The run step captures it through an && / || list — a run: block's default shell is bash -e, so a bare call followed by RC=$? would abort before the assignment and collapse the count to a boolean. That is one character away at all times.
• Fail-closed base ref. On a pull_request the job names the PR's real target branch. @{upstream} is used nowhere: on a pushed feature branch it is the branch, so the diff is empty exactly when CI runs — that produced "58 gates green over 0 changed files". No HEAD~1 fallback either. An unresolvable base exits 99, prints no green, and the job reports 99 distinctly from "N gates failed".
• fetch-depth: 0 on the app checkout is required, not an optimisation: a shallow clone has no base branch, and the run would (correctly) refuse to scope.
• Coverage is asserted. The wrapper reads the gate inventory out of the runner, not from a hardcoded 61 — verified live, see the correction below.
• No || echo '...skipping'. Missing prerequisites are named with what they left uncovered.
• Waiver counts are stated on every green, so a green earned by passing is distinguishable from one earned by waiving.

Verification

.github/workflows/hydra-gates-package.yml makes the proof permanent rather than a one-off. It installs the package through composer, from this repository's public VCS URL, into a scratch project in a clean php:8.3-cli container — no local checkout of the package on the box, no credentials — and then runs the positive control in both directions:

• inject error_log() (gate-2) and window.confirm() (gate-34) — violations no other fleet tool reports, so the signal cannot come from phpcs/psalm/phpstan/eslint — and assert both offending files are named, both gates are named, and the exit code is exactly 2, the count;
• remove them, and assert via git ls-files --error-unmatch that the revert actually applied before re-measuring. (A prior run of this exercise used git revert -q, git 2.25 rejected it, the rejection went unchecked, and the identical violating tree was silently re-measured.) Then assert exit 0 with coverage and waiver counts stated;
• unresolvable base ref → exit 99, no green, no gate lines emitted.

node is deliberately absent from that container, so the run must also name the gates that left uncovered instead of counting them toward the green.

Locally, before pushing: the package's own 13 invariant assertions pass from the relocated layout, and a --full run against openbuild reproduces its known 16-gate failure set with zero missing-helper errors — which is what confirms the extracted helper subset is complete.

Two corrections to what was briefed

"61 declared, 59 report" is right for origin/development, but the count is not fixed and the wrapper proves it. I first extracted the runner from a working checkout that had two uncommitted WIP gates in it; the coverage line came back "61 of 63 declared gates reported a result" — correctly, because the inventory is read from the runner. Caught it, re-extracted from the canonical branch, and the shipped runner declares 61 with 24 and 33 still the two that skip. The near-miss is worth recording: hydra's default branch is main, but gate work lands on development (hydra#504's base), and main is far behind at 45 declared gates. Extracting from main would have silently shipped a 16-gate regression.

The wrapper's own documentation contradicted its code. The usage header listed @{upstream} as step 3 of the base-ref chain and the fatal message said Tried: @{upstream}, ..., while the code correctly omits it. Fixed — that comment is exactly how the removed fallback gets re-added by someone trusting the docs.