Intent and drift
Write down the architecture you intend, have it ratified, and let Veriom flag drift when an audit finds something different.
This page is for the architect or tech lead who owns how a system should be built. Intent is the architecture you mean to have. Drift is any difference between that intent and what an audit actually observes.
How intent and drift fit together
Each audit builds the observed architecture from evidence: the services, data stores, and connections it can prove. Intent is a separate, versioned record of the architecture you want. Veriom never changes the observed architecture to match your intent. It compares the two and reports each difference as drift, with the evidence.
Before you start
- The Intent tab appears under Architecture only when intended architecture is turned on for your workspace. Ask Veriom support to turn it on.
- You need the Analyst role to write intent, and the Admin role to ratify it. Viewers can read it.
- The repository has finished at least one audit.
Write your first intent
- Open Architecture and select the Intent tab.
- Click Adopt current as draft. Veriom copies the observed architecture into a draft you can edit. A draft can hold up to 2,000 elements.
- Edit the draft: remove what should not exist, add what should, and add rules.
- Ask an Admin to open the draft and click Ratify this architecture. They enter a reason and confirm their identity.
The ratified version is now the intent Veriom compares against. To change it later, click Amend ratified intent. That creates a new draft, which must be ratified again.
If someone ratifies another version while you edit, Veriom says the draft must be rebased. Review the newer version and start your change again from it.
Rules you can add
| Rule | Example |
|---|---|
| Element must exist | The payments service must exist |
| Element must be absent | No public database |
| Relationship must exist | The API must call the auth service |
| Relationship must be absent | The web app must not call the database directly |
| Attribute must equal | The data store's encryption must be on |
| Only these sources may enter | Only the gateway may call the payments service |
Kinds of drift
| Drift | What it means |
|---|---|
| Unintended presence | The audit observed architecture outside your intended model |
| Missing control | Architecture your intent requires is missing |
| Violated invariant | One of your rules failed |
| Stale intent | Your intent refers to architecture that is no longer there |
| Invalidated intent | A rule in your intent no longer holds |
| Overdue plan | A planned change passed its date without happening |
| Intent gap | Observed architecture has no ratified intent explaining it. Veriom counts this as missing explanation, not as drift |
A comparison can also report insufficient evidence, when the audit cannot prove either way.
When Veriom checks for drift
- On demand: on the Intent tab, choose an observation and click Compare observation.
- At every audit: the reporting stage compares the new observation against each release check.
The Diff tab shows the differences. Release checks shows the results per policy.
Release checks
A release check turns intent rules into a gate.
- A new check starts in shadow mode. It reports results but blocks nothing.
- An enforced check can block a release. Enforcement needs a second workspace setting that Veriom support turns on.
- An exception to an enforced check lasts at most 24 hours.
On GitHub, enforced results reach pull requests through the Veriom architecture guard check. See Run Veriom in CI.
Boundary suggestions
On Architecture → Discovery, Veriom suggests where service boundaries should be: dependencies between services, which team owns what, and services that should split.
An Analyst confirms or rejects each suggestion with a reason. Suggestions to split a service always need a person. An Admin can let Veriom accept other suggestions with high confidence on its own. See Autopilot and autonomy.
Propose intent from an AI assistant
The MCP tools preview_intent_proposal and submit_intent_proposal let an assistant draft intent for review. A person still ratifies it. See MCP.
Was this guide useful?
Your response stays in this browser unless you open a GitHub issue.Work with findings
Read a Veriom finding, triage it, mark false positives, accept a risk, merge duplicates, and ask Veriom to open a fix pull request.
Autopilot and autonomy
What Veriom sets up for you when you connect a repository, what it can do on its own once an Admin allows it, and what always waits for a person.