How Archgate turns Architecture Decision Records into executable, deterministic compliance checks — the detection layer of the governance loop.
Rules are the executable side of an ADR. Where the ADR document explains a decision to humans and AI agents, the rule verifies that decision against the codebase automatically. Rules are the engine of the detection layer: deterministic, free to run, and fast enough to live in pre-commit hooks and CI.
How rules relate to ADRs
Section titled “How rules relate to ADRs”An ADR that has rules: true in its frontmatter carries a companion rules file alongside the document. When you run a check, Archgate loads every ADR that declares rules, executes its companion file against your code, and reports any violations with the file path and line number where they occur.
This pairing is what makes Archgate more than a linter. The decision and its enforcement live together: the rule never drifts from the documented intent, because they are versioned as one unit and reviewed together. When the lessons-learned skill proposes a new rule, it does so as part of an ADR — the rationale and the check arrive together.
What a rule can do
Section titled “What a rule can do”A rule inspects the codebase and reports findings. Conceptually, each rule:
- Receives the set of files in scope — narrowed by the ADR’s
filesglobs, with the changed-files set available for diff-aware checks. - Reads and searches those files (glob, read, regex search across files).
- Reports findings at one of three severities:
- error — a hard violation that fails the check and blocks the merge.
- warning — a flagged issue that is surfaced to the developer but does not block.
- info — a purely informational notice.
Severity is what lets the governance loop be strict where it matters and advisory elsewhere. Errors are the hard gate; warnings nudge toward better patterns without halting work.
Where rules run
Section titled “Where rules run”The same rules execute in three places, giving you defense in depth:
| Location | Trigger | Role in the loop |
|---|---|---|
| Editor | After an AI agent edits code | Immediate feedback during development |
| Pre-commit | Before code is staged for commit | Fast local gate, scoped to staged files |
| CI | On pull request / push | The hard gate that blocks non-conformance |
Because the check is deterministic and runs identically everywhere, a passing local commit and a passing CI run mean the same thing — there is no “works on my machine” gap in governance.
Rules vs. AI review
Section titled “Rules vs. AI review”Rules handle what a machine can verify mechanically — roughly 70–80% of a typical ADR base. The subjective remainder (architectural fit, judgment calls) is handled by the reviewer skill applying AI review against the same ADRs. The strategic aim is to keep moving rules from the AI-review column into the deterministic-rules column over time, which the learning movement of the loop drives. Free checks go up, token spend goes down.