Skip to content

feat(gate-23): give rules 2 to 6 the exception path ADR-022 already grants - #755

Merged
rubenvdlinde merged 2 commits into
mainfrom
feat/gate-23-exception-path-for-rules-2-to-6
Sep 11, 2026
Merged

rubenvdlinde merged 2 commits into
mainfrom
feat/gate-23-exception-path-for-rules-2-to-6

Conversation

@rubenvdlinde

Copy link
Copy Markdown
Contributor

What

Gate 23 (lint-or-abstraction-anti-patterns.sh) now honours the ADR-022 exception clause in every rule, not just rule 7.

  • _cap_suppressed() and the exception-ADR index move above rule 2 and serve rules 2 to 6 as well. Their old position, directly above the only loop that called them, is exactly why the other rules never had a path.
  • Every suppression prints, with the file and the ADR that bought it. Rule 7's line gains the ADR name too.
  • An exception ADR that names no sunset still suppresses, and the gate prints a warning naming that ADR on every run.
  • An exception ADR whose sunset has passed stops suppressing. The finding comes back and says why.
  • Rule 2 asks a second question, the way rule 1 does for PDOK: a file that calls AuditTrailMapper is printed as compliant and not counted. The question is asked of code lines, so a docblock naming the mapper buys nothing.

Why

ADR-022 says an exception applies where an app-local ADR records it, and it ships a worked example. Gate 23 only ever asked in rule 7. Rules 2 to 6 had no exception path at all, so the gate was narrower than the ADR it enforces.

That gap is not theoretical. Rules 2 and 4 match on file name. In dossiq they flag:

  • lib/Service/TenantService.php, which resolves OpenRegister's OrganisationMapper and calls TenantLifecycleService::provision() at line 175
  • lib/Service/TenantAuditTrailService.php, which writes every entry through AuditTrailMapper::createAuditTrailEntry() at line 149

Both are the consumers ADR-022 asks for. Both were counted as violations of it. The only way to clear a name rule is to rename the file, which changes no behaviour at all, so the gate rewarded a cosmetic edit and penalised the correct architecture.

The decisive case is the approved migration. Ruben's decision 2b of 2026-09-11 keeps five Tenant-named satellite services in dossiq on purpose, because OpenRegister does not grow billing or configuration stores. So the migration as decided could not clear rule 4 however much of it was built. An exception path is needed whenever the gate blocks, which is why the 2026-10-03 date stays as it is.

This relaxes the gate, so it does not need the warn-first treatment

A new blocking rule ships as _warn first, because it fails repos on inherited debt the moment it merges and CI resolves @main fleet-wide. This is the opposite direction. Every code path added here only ever removes files from a list that a rule already reported, so no repository can newly fail because of it.

The expired-sunset arm is the single ratchet, and it fires for nobody today. Measured 2026-09-11 over all 21 core apps on development: 22 ADRs cite ADR-022, and not one carries a sunset date. An ADR gains that ratchet only by choosing a date.

Before and after

Forced BLOCK mode, both epochs, so the exit status carries the verdict:

HYDRA_OR_GATE_BLOCK_AFTER_EPOCH=0 HYDRA_OR_CAPABILITY_GATE_BLOCK_AFTER_EPOCH=0 \
  bash hydra-gates/scripts/lint-or-abstraction-anti-patterns.sh lib

dossiq at 8b4fa8c5, measured against the two exception ADRs in ConductionNL/dossiq#2484:

before after
or_abstraction_findings 5, exit 1 4, exit 1
rule 2, audit trail 2 files 1 file
rule 4, tenant 26 files 18 files
rule 5, workflow engine 4 files 0 files
rule 7, tenant middleware 4 files 4 files
rule 7, search_path 2 files 1 file

One of the two rule-2 files (TenantAuditTrailService) clears on the consumer check alone, with no ADR. The other (BezwaarAuditTrail) does not consume OpenRegister yet and stays lit, correctly.

decidiq at 45803ec:

before after
or_abstraction_findings 1, exit 1 1, exit 1

Unchanged, and deliberately so. decidiq needs no exception ADR: StateMachineValidator is retired by deletion in process-templates-as-lifecycle-policies, not excused.

Verification

  • bash -n clean. ShellCheck 0.10.0 clean, exit 0, no new suppressions.
  • New suite hydra-gates/scripts/lib/test_or_abstraction_exceptions.sh, 38 assertions, auto-discovered by run-helper-suites.sh. It covers the positive control (a flagged file with no ADR still fails), the negative control (a file named by a valid ADR is suppressed and printed with its ADR), an ADR without a sunset (suppresses, and the warning naming it is asserted, so it cannot silently pass), an expired sunset (does not suppress), an ADR that never cites ADR-022, a sibling path, a directory token that must not reach outside itself, one rule-7 regression, and both halves of the audit-trail consumer check.
  • Mutation-checked. The suite takes GATE=<path>. Run against the pre-change script, 23 assertions redden and the positive controls stay green, so they are not measuring the change.
  • bash hydra-gates/tests/run-helper-suites.sh green.

Coordination

No overlap with #751, which touches run-hydra-gates.sh and lib/check_no_admin_idor.py. origin/main merged in before pushing. No waiting was needed.

Refs ConductionNL/dossiq#2460, ConductionNL/decidiq#1277.

🤖 Generated with Claude Code

…rants

ADR-022 says an exception applies where an app-local ADR records it, and it
ships a worked example. Gate 23 only ever asked in rule 7: _cap_suppressed()
was defined below rules 2 to 6 and called from the rule-7 loop alone. So the
gate was narrower than the ADR it enforces.

Rules 2 and 4 match on file name. In dossiq that flags TenantService, which
calls OpenRegister's OrganisationMapper and TenantLifecycleService::provision(),
and TenantAuditTrailService, which writes every entry through
AuditTrailMapper::createAuditTrailEntry(). Both are the consumers ADR-022 asks
for, both were counted as violations of it, and the only way to clear a name
rule is a rename that changes no behaviour. The approved dossiq tenancy
migration keeps five Tenant-named satellites on purpose, so it could not clear
rule 4 however much of it was built.

One exception mechanism now serves every rule:

  * an app-local ADR that cites ADR-022 and names the path suppresses it
  * every suppression prints, with the file and the ADR that bought it
  * an ADR with no sunset still suppresses, but prints a warning naming it
  * an ADR whose sunset has passed stops suppressing

Rule 2 also asks a second question, the way rule 1 does for PDOK: a file that
calls AuditTrailMapper is printed as compliant and not counted. The question is
asked of code lines, so a docblock buys nothing.

This only removes findings, so it cannot newly fail a repo. Measured in forced
BLOCK mode: dossiq 5 rule findings to 4, decidiq 1 to 1.

New suite scripts/lib/test_or_abstraction_exceptions.sh, 38 assertions,
auto-discovered by run-helper-suites.sh. Mutation-checked against the
pre-change script: 23 assertions redden, the positive controls stay green.
@rubenvdlinde
rubenvdlinde merged commit 2fd3159 into main Sep 11, 2026
40 checks passed
rubenvdlinde added a commit that referenced this pull request Sep 11, 2026
)

#755 gave rules 2 to 6 the ADR-022 exception path, but matched on path
alone, across every rule. An ADR written to excuse a file under one rule
silenced it under all of them. dossiq ADR-004 covers TenantAuditTrailService
for rule 4, and that hid the same file's rule-7 search_path hit, the
evidence for dossiq#2470.

An exception ADR now names the rules it covers: a "Gate 23 rules:" line
beside the sunset (ADR-wide) or "(gate 23 rules: ...)" after a path on the
line that lists it (per path, replaces the ADR-wide list). Rules are named by
number (2 to 7) or by the key the gate prints. A finding under a rule the ADR
does not cover is reported as usual, with a note naming the ADR that named
the path.

An ADR that names no rules is read as covering rule 7 only, the one rule an
exception ADR could suppress before 2026-09-11, and is told so on every
suppression. That restores the pre-#755 behaviour for every such ADR, and
ends #755's accidental suppressions: keepiq, hermiq and shillinq ADRs that
mention lib/Service/ or lib/Lifecycle/ in prose had silenced rule 2, 4 and 6
findings.

Measured on all 21 core apps at development: no exit code changes, forced
BLOCK or default WARN.
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