Baseline

A rule you cannot turn on is a rule you do not have. Most repositories that would benefit most from architectural policy already violate the policy they need, and the honest alternative to recording those violations is not fixing them first — it is leaving the rule off.

baseline: .architecture-baseline.json
# …

architecture baseline    # record what the repository currently violates
architecture check       # green, carrying those and refusing anything new

A baselined violation does not report. Everything else does, immediately — so the rule is on from the first day, and the next occurrence is caught in the pull request that introduces it.

Two properties make it a ratchet

Without both of these, a baseline is a suppression list, and a suppression list is a place where policy goes to die quietly.

Entries are line-independent fingerprints. An entry is kind|rule|file|subject — never a line or column. Reformat the file, move the import to the top, add fifty lines above it: the entry still matches the same violation. A baseline keyed on a position goes stale on the first reformat and silently re-admits exactly what it was written to record.

A stale entry is an error. If the baseline holds an entry the code no longer produces, check fails and names it:

2 baseline entries no longer fire. The code was fixed; prune them:
  import|domain-isolation|src/modules/user/domain/user.root.ts|packages/database/src/index.ts
  ...

  architecture baseline    # rewrites the file from what still fires

That is the tooth. Fixing a violation is not complete until its line is gone, so the count only ever goes down, and the file keeps describing something real. Without it the baseline accumulates entries for code that was deleted years ago and stops meaning anything.

Reading it

The output of check says how much debt is being carried:

1284 files, 0 violations, 37 carried by the baseline

Thirty-seven is a number a team can watch, put in a retro, and drive down. It is the same discipline as a coverage floor: raise it when it rises, never lower it to make a red build green.

When not to use one

If the rule you are adding has fewer than a handful of violations, fix them instead. A baseline earns its complexity when the count is large enough that fixing it all at once is its own risky change — not as the default way to land a rule.

And a baseline is not a place for violations you have decided are correct. If a case is genuinely fine, the manifest should say so: an except on the prohibition, an entry on the allowlist, a requiresNot on the parity rule. A permanent baseline entry is a decision that nobody wrote down.