Skip to content

fix(gate-23): suppress an exception per (file, rule), not per file - #759

Merged
rubenvdlinde merged 1 commit into
mainfrom
fix/gate-23-exception-per-rule
Sep 11, 2026
Merged

rubenvdlinde merged 1 commit into
mainfrom
fix/gate-23-exception-per-rule

Conversation

@rubenvdlinde

Copy link
Copy Markdown
Contributor

Summary

Gate 23's ADR-022 exception clause (#755, 2fd3159) suppresses a finding by file path across every rule at once. An ADR written to excuse one file under one rule silences that same file under every other rule too. The concrete case: dossiq ADR-004 covers TenantAuditTrailService.php for rule 4 (the Tenant* name rule) and, as a side effect, silenced the same file's real rule-7 search_path finding — the evidence behind dossiq#2470, where tenant isolation is inert.

This PR makes suppression per (file, rule). A file's exception ADR now only buys the rules it names; any other rule's finding on that same file is reported and counts toward the exit code, same run.

Grammar

Extends #755's existing conventions (path tokens, Sunset: line) rather than inventing a parallel format:

  • ADR-wide: - **Gate 23 rules:** 4, 7 beside the Sunset: metadata bullet
  • Per path: - `lib/Service/TenantAuditTrailService.php` (gate 23 rules: 4) — replaces the ADR-wide list for that path only; later prose mentions of the same path do not widen it
  • A rule is named by its number in the gate script (2–7) or by the key the gate prints (consume-or-tenant-fleet-wide, or-capability:tenant-boundary); 7 covers every capability row, or-capability:<key> covers only that row
  • The parse is a single POSIX-awk pass per ADR (the runner's awk is mawk), anchored so a References-line sentence like "gate 23, rules 2, 4 and 7" does not declare anything — only a line that opens with Gate 23 rules: or a path followed by (gate 23 rules: …) counts

Backwards compatibility

An ADR naming no rules does not blanket-suppress. It is read as covering rule 7 only — the one rule an exception ADR could suppress before #755 — and the gate prints a warning on every run asking the author to add an explicit list. This is deliberately conservative: no repository can newly fail on a rule-less ADR that did not already rely on rule-7 suppression, and nothing #755 accidentally hid under rules 2–6 stays hidden.

Per-repo impact (measured, not assumed)

Surveyed all 21 core apps' openspec/architecture/*.md on their development branch for ADR-022 citations (openregister is exempt from gate 23 entirely — it's the abstraction provider, not a consumer). 13 apps have at least one citing file; 8 have none and are trivially unaffected.

Ran both the pre-fix script (2fd3159) and this branch's script against a sparse checkout (lib/, appinfo/, openspec/) of each of the 13 citing apps, twice: once under today's real WARN-mode config, and once with HYDRA_OR_GATE_BLOCK_AFTER_EPOCH=0 / HYDRA_OR_CAPABILITY_GATE_BLOCK_AFTER_EPOCH=0 to simulate the post-2026-10-03 BLOCK world this change actually matters for.

App old exit (BLOCK) new exit (BLOCK) findings old→new changed?
openregister 0 (exempt) 0 (exempt) 0→0 no
opencatalogi 0 0 0→0 no
integriq 1 1 1→1 no
filinq 0 0 0→0 no
launchpad 1 1 1→1 no
larpinq 0 0 0→0 no
dossiq 1 1 4→5 no (already red; rule-7 search_path reappears, as intended)
shillinq 1 1 2→2 no (rule already red on other files)
learniq 0 0 0→0 no
portaliq 1 1 1→1 no
keepiq 1 1 1→2 no (already red; rule-6 ShareAuthorizationService reappears)
hermiq 1 1 1→1 no (3 more files now listed under the already-red rule-4 block)
humaniq 0 0 0→0 no
buildiq / decidiq / pipelinq / thematiq / stackiq / zaakafhandelapp / versioniq / planninq — — — no ADR-022 citation; unaffected

No repo's exit code changes, today or in the simulated post-2026-10-03 world. Every app whose findings count grew (dossiq, keepiq) was already red on that same rule for an unrelated file, and every app that stayed at 0 findings had an ADR-022 citation that never named a path matching a gate-23 pattern in the first place. So this ships as a full fix, not warn-first — there is nothing to warn about.

dossiq's own count moving 4→5 is the intended outcome: ADR-004 now declares Gate 23 rules: 4, so TenantAuditTrailService.php's rule-7 search_path hit is reported again, tracked as dossiq#2470. See the companion dossiq PR.

Tests

Extended hydra-gates/scripts/lib/test_or_abstraction_exceptions.sh with a new PER (FILE, RULE) section: a file covered for rule A stays lit for rule B in the same run; an ADR naming no rules does not blanket-suppress (and is told so); an explicit rule list works by number and by printed key, ADR-wide and per path; a per-path list is not widened by the path's own later prose; or-capability:<key> covers only that capability row.

Mutation-checked both ways, per repo convention:

  • Against the OLD script (2fd3159): 24 of the new assertions FAIL (the ones asserting per-rule behaviour — a rule-A exception still blanket-suppresses rule B there).
  • Against this branch: all 80 assertions PASS, 0 fail.

Also ran:

  • hydra-gates/tests/run-helper-suites.sh (the discovered, not hand-listed, suite runner) — full run, including the ajv-dependent manifest-validation suites (installed pinned ajv@8.17.1 + ajv-formats@3.0.1 into a scratch dir, pointed at it via NODE_PATH rather than skipping).
  • ShellCheck 0.9.0 (CI's ludeeus/action-shellcheck@2.0.0 doesn't pin an exact ShellCheck version; 0.9.0 is this box's apt candidate) on both changed files — clean.

Files changed

  • hydra-gates/scripts/lint-or-abstraction-anti-patterns.sh — per-(file, rule) suppression parsing and lookup
  • hydra-gates/scripts/lib/test_or_abstraction_exceptions.sh — the PER (FILE, RULE) test section

🤖 Generated with Claude Code

#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