docs(ci-cd): how an app depends on OpenRegister (ADR-083 + ADR-084)

[rubenvdlinde]

The gap

Both ADRs shipped with the ADR in hydra/openspec and the reasoning inside the
checkers — and nothing in the CI/CD page an app developer actually reads. The
rules were enforced by two gates and written down nowhere, so the first time a
developer meets them is a red build.

What the page now says

ADR-083 — the four rules, enforced by gate-66. Inject an unconditional
dependency; never extends/implements an OpenRegister class; keep the default
route core-only; check the version floor but never install.

With the parts that are easy to get wrong:

• the optional-capability exception, and that a guard has three valid
  spellings — ask the app manager, ask the autoloader, or try-and-degrade. A
  catch that rethrows is not a guard. Getting this wrong turns a clean
  "OpenRegister is not installed" message into a 500.
• why a class header is categorically different from injection: it is fatal at
  autoload, and takes down the very route that would have explained the problem.
• that OC\Installer is private API and bypasses admin consent — detect and
  inform, never install.

ADR-084 — type-hint the contract, gate-67. The interface, the
composition-root alias, why Nextcloud's autowiring needs it stated, and:

Keep the concrete import where the concrete NAME is still used.
ObjectService::class does not require the class to exist, so dropping that
import silently resolves the key to your app's own namespace and looks up
something nobody registered; instanceof becomes permanently false. Neither
errors at the point of the change.

"Two distribution paths in one package." hydra-gates now ships runtime
interfaces as well as gate scripts, and they reach an app differently:

what	route	needs a tag?
gate scripts	fetched from .github@main	no — live on merge
contracts/	composer, into vendor/	yes — apps pin ^1.0

Confusing the two cost a release: openregister bumped its lock specifically to
make gate-67 enforce, and the gate still said NOT APPLICABLE, because the
Hydra Gates job never runs composer install (fixed in #465).

Plus the package table row, which still claimed hydra-gates contains only the
gates and quality-config/.

Lessons recorded where they will be read

• A gate that has only ever skipped has not been shown to work. NOT APPLICABLE is deliberately not a pass — the wording was right and the gate was
  still useless.
• A rule derived from one observed idiom will mistake every other correct idiom
  for debt, at fleet scale and with a straight face. ADR-083's count went
  1263 → 1010 → 883 → 441; the 822-site difference was already-correct code.
• The cost that motivated ADR-083, stated rather than asserted: gate-7 reported
  50 findings on pipelinq, every one a correctly-delegated endpoint, because
  a string literal is invisible to it — and a human review of the same code the
  same day concluded the opposite about who enforced authorisation.

Related

• ADR-083, ADR-084 — ConductionNL/hydra#576
• interfaces + implements — feat(contract): publish ObjectService/ObjectEntity interfaces — one definition instead of eight openregister#2498
• gate-67 — feat(gate-67): ship the OpenRegister contract and enforce one definition (ADR-084) #463, fixed in fix(gate-67): look for the shipped copy where the runner actually is #465, released as v1.8.0

🤖 Generated with Claude Code