How to enforce architectural decisions in CI

What makes a CI check a trustworthy architectural gate?

A trustworthy gate has a named governing decision, a defined scope, a deterministic detection method, a severity, a remediation path and an evidence record. It should identify the changed file or dependency edge rather than reporting a generic failure. It should also state what it does not check. A dependency rule can prove that one import exists; it cannot prove that the resulting design is good in every context.

Start with checks that remove repeated, expensive review work. A rule that prevents domain code importing infrastructure, validates an API contract or checks a data-residency field is easier to explain than a broad model-generated architecture score. Link the rule to the decision so the rationale survives when the implementation moves.

• Report the decision ID and affected files in the failure.
• Separate blocking errors, warnings and unclassified guidance.
• Offer approved alternatives or an exception workflow.
• Version the check with the decision evidence it claims to support.

How should teams handle a legitimate exception in CI?

An exception should be explicit, scoped and expiring. The pull request or decision registry should name the default rule, explain why the check cannot pass, record the approver and attach compensating controls. CI can then show the exception as evidence rather than silently disabling the rule. When the expiry date passes, the exception becomes a visible review item and the default policy is restored unless a new approval is recorded.

This is especially important for generated code. An agent can propose a workaround, but it should not be able to turn a temporary bypass into an unowned permanent rule.

What should a decision-aware CI failure report contain?

A useful failure report reads like a reviewer’s first explanation. Start with the decision ID and a one-line statement of the governing rule. Name the affected repository, file, symbol or dependency edge, then show the detected evidence. Explain why the check failed, which alternatives are approved and whether an exception can be requested. Link to the decision, rule version and remediation documentation. This is more actionable than a generic message such as ‘architecture violation’.

Keep the evidence bounded. A dependency check should not paste the entire graph; it should show the edge that violated the scoped rule. A policy check should identify the field and expected value. A test should preserve its result and commit revision. These details let a reviewer determine whether the code is wrong, the scope is wrong or the decision needs review.

• Governing decision and rule version.
• Affected file, symbol, configuration field or dependency edge.
• Detected value and approved alternative.
• Exception and remediation links with an owner.

How should enforcement coverage be reported?

Report enforcement coverage as a map from decisions to checks, not as a single percentage that implies every consequence is encoded. For each active decision, show whether a rule exists, which repositories and paths it covers, the last successful run, recent violations and any disabled or expired exceptions. A decision can be healthy with no automated rule when its consequence is qualitative; that status should be explicit rather than counted as a silent gap.

Use the report to prioritise engineering work. Repeated violations may indicate poor implementation, an unclear rule or a decision that no longer fits the system. A disabled check should create a review item with an owner and due date. When a decision is superseded, retire its checks deliberately and link the replacement. This keeps CI evidence aligned with current authority instead of accumulating orphaned policies.

• Decision-to-rule mapping and exact scope.
• Latest result, policy revision and violation trend.
• Disabled checks and expired exceptions with owners.
• Explicit status for qualitative consequences without automation.

Start with a checkable consequence

An ADR may contain several consequences, only some of which can be evaluated mechanically. 'The service must not import the UI package' is checkable. 'The architecture should remain elegant' is not. Classify the former for enforcement and leave the latter for review.

Trying to automate the whole paragraph with an LLM judge makes the gate difficult to reproduce and easy to overstate.

Make scope explicit

A changed-files check answers a different question from a full-tree certification. The first can block a patch from introducing a new violation; the second can claim that the current repository satisfies the rule. Report which mode ran and avoid presenting incremental coverage as global compliance.

Return evidence a reviewer can inspect

A useful failure names the governing record, the check, the affected file and the observed condition. A useful pass says what was examined. This lets a reviewer distinguish a real guarantee from a green status with ambiguous scope.

• Decision: ADR-014 — preserve the restoration window.
• Constraint: no direct hard-delete call in account closure paths.
• Scope: files changed by this pull request.
• Evidence: matching file and line, or an explicit clean result.

Version the check with the decision

When a decision is superseded, the corresponding constraint must be updated or retired through review. Relating the two prevents abandoned policy code from enforcing a rule the team no longer accepts.