Quality Gates Before Publication

What publication claims

When you publish a repository, you make a claim you may not have intended: that what is on these pages is the architecture. Readers do not distinguish between "the model is wrong" and "the portal rendered it wrong". Either way, they stop trusting the portal, and trust is the only thing it has.

A quality gate is the mechanism that keeps the claim honest. It runs before publication and refuses to publish a baseline that fails it.

What to check

Referential integrity

Relationships whose endpoints are outside the published scope, diagram nodes referencing elements that no longer exist, views that reference deleted packages. These produce broken pages or, worse, pages that render fine but are missing content with no indication that anything is absent.

Geometry

Overlapping shapes on a diagram, nodes outside their container, views with no content at all. These are invisible in the modelling tool — the architect drew it, so it looks right to them — and obvious in an export.

Governance metadata

Canonical elements without an owner, elements past their review date, requirements with no verification. These are not rendering failures; they are the content being incomplete in ways a reader will interpret as fact.

Gate on errors, report on warnings

The failure mode of an over-strict gate is that people turn it off. A real repository always carries findings — visual-only shapes have no names, some packages are deliberately undocumented, some relationships cross a boundary by design. A gate that blocks on all of them blocks every week, and within a month someone adds --force to the scheduled job and nobody ever removes it.

Two severities is enough. Errors block. Warnings are counted, listed in the publication report, and published anyway. If a warning class turns out to matter, promote it to an error deliberately — that is a decision worth making explicitly rather than by accident.

Validate before you spend the time

Extraction from a large repository is not fast. Reading a few thousand elements with their tagged values and diagram contents over an automation API takes minutes, and a full publication run can take longer than that.

Run the cheap structural checks first, against the source, before committing to the expensive extraction. Discovering a broken reference after twenty minutes of work is annoying; discovering it in two seconds is a build step.

Make the gate's output the fix list

A gate that says "failed: 47 findings" is a wall. A gate that says which element, in which package, failed which rule is a work queue an architect can pick up on a Friday afternoon.

The difference in adoption between those two outputs is larger than any other decision in this area. Findings need a subject, a rule name and a location, in that order, and they need to be sorted so the same package's problems appear together.

Findings have a lifecycle

A gate that evaluates each run in isolation wastes half the information it produces. The interesting fact about a finding is rarely that it exists; it is whether it existed last week. Persisting findings across runs — keyed by element, rule and location — splits every report into three lists with entirely different audiences.

New findings are this week's news and the only list that deserves a notification: something changed since the last publication, and the person who changed it still has the context to fix it cheaply. Known findings are the standing backlog — worth a count and a trend line, worth nobody's inbox, because re-announcing the same warning weekly is how notifications get filtered to a folder nobody reads. And fixed findings are the list that gets ignored and should not be: it is the evidence that the gate is working, it deserves to be visible in the same report, and — a small human observation from running these — architects check whether their fixes registered, and a gate that acknowledges the work gets more of it.

The trend is also the practice's health metric in miniature. Warnings per hundred elements, per package, plotted across a quarter, answers questions that otherwise produce meetings: whether quality is improving, which domain needs help rather than pressure, whether that rule promoted to error in March actually changed behaviour. It slots naturally beside the portal's adoption metrics — one measures whether readers trust the output, the other whether the input deserves it, and they tend to move together with a lag that is itself informative.

The same gate guards the documents

Portals are not the only thing generated from the repository. The same estates produce Word and PDF deliverables — solution architecture documents, TOGAF artefacts assembled into a register, review packs for steering committees — and these are, if anything, less forgiving of model defects than a portal. A broken reference on a portal page is a gap a reader can navigate around; the same gap in a generated document is a blank table row in a PDF with the CIO's name on the cover, discovered after distribution, unfixable without re-issuing the document.

The implication is that the gate belongs to the repository, not to the portal pipeline that happened to build it first. One rule set, one waiver mechanism, one findings history — consumed by every generation path that turns models into artefacts people rely on. Document generation adds a handful of rules of its own, mostly completeness rules scoped to the template ("every section this template renders has a source element"), and those rules follow the same ownership and severity discipline as the rest. What the practice gains is a single answer to a question that otherwise fragments: what does this organisation check before architecture leaves the repository? When that answer is one list, published where the architects work, the gate has stopped being pipeline plumbing and become what it was always pretending to be — the practice's definition of finished.

Where the gate belongs

Before publication, and ideally also somewhere earlier. A gate that only runs at publication time means problems are found once a week by a scheduled job, attributed to nobody in particular, and fixed by whoever notices.

The same checks run on demand — a button in the modelling environment, or a command an architect can run against their own package — turn a weekly surprise into something people fix as they go. The gate then rarely fires, which is the goal.

Writing rules people can obey

The rules in the table share a property that is easy to miss and essential to copy: each one names a condition the architect can fix in the modelling tool, in minutes, without asking permission. That is the standard every candidate rule should meet, and most candidates fail it.

The failures come in recognisable families. Style rules that fight the tool — naming case conventions the modelling environment will not enforce as you type — generate findings faster than anyone clears them, and teach people that findings are noise. Aspiration rules — "every application must have a roadmap" — encode a governance ambition as if it were a model defect, and punish the architect for the organisation's unfinished homework. And judgement rules — "diagram should not be cluttered" — cannot be evaluated by code honestly, so implementations approximate them with thresholds that fire on exactly the diagrams that needed their density. Checkable is not the same as valuable; a rule earns its slot only when a firing finding reliably means work someone should do this week.

Real estates also need exemptions, and exemptions need discipline more than they need prevention. The pattern that keeps them honest is a waiver recorded in the model — a tagged value on the element naming the rule, the reason, the approver and an expiry date. The gate skips waived findings, the publication report lists active waivers, and expired waivers fire again automatically. Compare that with the alternative everyone improvises — a growing exclusion list inside the gate's configuration file — where exceptions accumulate invisibly, outlive their reasons, and surface only when an auditor asks why a rule that "always passes" has forty elements carved out of it in a file nobody owns.

Every rule has an owner

A gate is a small piece of legislation, and legislation without an owner drifts into disrepute. Each rule deserves a line of provenance: who proposed it, what incident or review made it worth having, and who decides its severity. This costs a paragraph per rule in the practice's operating documentation and pays for itself the first time someone asks "why does the gate care about this?" — a question that otherwise gets answered with a shrug and a --force.

Ownership also gives severity changes a process. Promoting a warning to an error is a real decision — it will block a future publication — and it should be made by the rule's owner, announced before it takes effect, with the current count of would-be errors published so nobody is ambushed. The same path runs downhill: a rule that has fired weekly for a quarter without anyone acting on it is not enforcing quality, it is generating background radiation, and demoting or deleting it is the honest move. A gate whose every rule can answer "who wants this and why" stays small, respected and enforced — three properties that travel together in both directions.

Rules worth starting with

A gate is only useful if someone wrote the rules. Six cover most of what actually goes wrong, and they can be implemented against any repository that exposes its model programmatically.

The overlap rule is the one people are surprised by, and it earns its place. Overlapping shapes are invisible in the modelling tool — the architect drew them and the tool renders them the way they intended — and obvious in an export, by which point nobody is looking.

Geometry checks need the parent chain

One implementation detail that determines whether a geometry rule works or produces nonsense: shape coordinates are frequently relative to a parent, not to the diagram.

A checker that treats every coordinate as absolute will report hundreds of overlaps that do not exist, because it has placed every nested shape at the top-left of the canvas. The rule has to resolve coordinates through the parent chain exactly as the renderer does, and it has to compare only siblings — a shape inside its own container is not an overlap, it is the point.

The gate's first month

How a gate is introduced determines whether it survives, and the introductions that survive all follow the same arc: two weeks of silence, one week of conversation, then enforcement — in that order, with no steps skipped.

The silent fortnight runs the full rule set in report-only mode against every scheduled publication. Nothing blocks; the findings accumulate into a baseline nobody is blamed for. This is where you discover that the overlap rule fires four hundred times because of the coordinate bug described below, that one package contributes half of all warnings because it was imported from a tool with different conventions, and that two of your rules disagree with each other on legacy stereotypes. Finding this out while the gate is silent costs nothing; finding it out the morning the gate first blocks a publication costs the gate its reputation, permanently, in one email thread.

The conversation week publishes the baseline to the people who own the findings — per package, with counts and examples — framed as the starting line rather than as an accusation. This is also the moment to agree the initial severity split, and the working rule is conservative: only findings that make the portal wrong start as errors, and the whole error list at go-live should be short enough that it is plausibly empty on a good week. Everything else is a warning with a trend line and a burn-down ambition, not a blocker.

Then enforcement begins, and the practice needs one more thing agreed in advance: what happens the Friday the gate blocks a publication someone urgently wants. The answer cannot be "it never happens" and must not be "the operator forces it quietly". The workable answer is a bypass that exists, requires a named approver, is recorded in the publication report, and is expected to be rare — the same shape as any other emergency change control. Count the bypasses. Zero for a quarter means the gate and the practice have converged; one a week means either the rules are wrong or the deadline culture is, and the count is the evidence for that conversation. A gate is ultimately a promise the practice makes to its readers about what "published" means, and the first month is where the practice decides whether it intends to keep it.

What the gate never checks

A closing boundary, worth stating so the gate is not oversold to the people approving it. Nothing in this article checks whether the architecture is true. A model can pass every rule — endpoints resolved, geometry clean, owners assigned — while asserting that a retired platform is live or that an integration exists which never shipped. The gate checks publishable form; truth remains a human responsibility, exercised through review, ownership and the willingness of readers to report what they know to be wrong.

That is not a weakness to apologise for; it is the division of labour working as intended. The gate's contribution to truth is indirect and real: by guaranteeing the form, it lets every human eye that touches the model spend itself on the content — and by keeping the portal trustworthy in the small things, it earns the readership whose corrections are the only mechanism that keeps a model true in the large ones. Machines guard the shape, people guard the meaning, and a practice that keeps both guards posted is what "the portal is reliable" actually means.