How the Architectural Intent Verifier Works

In the companion piece on why this matters, I made the case that architectural drift is a gate we've never built. This article is about the gate itself — how the Architectural Intent Verifier actually works when a pull request opens, told the way I'd explain it to another architect who wants to know exactly what's reasoning about their code and where a human still holds the wheel.

The Verifier is a StudioX Mission. That word is precise. A Mission isn't a script and it isn't a chatbot — it's a small org chart of specialist agents coordinated by a reasoning core, that takes a goal in plain language, delegates work, and returns a result with every decision traced. Our goal, expressed once when we configure the mission, is roughly: "When a PR opens, check this change against our active architecture decisions and tell me where it drifts." Everything below is how that sentence becomes a verdict.

The roster

A Mission is defined by the agents registered to it — each one a name, a description the reasoning core reads to decide routing, and a StudioX Vibe backed by its own bot and knowledge base. For the Verifier, three specialists carry the load:

• The Diff Agent reads the pull request — files changed, symbols added and removed, new dependencies, new call edges. It doesn't judge anything; it produces a faithful, structured picture of what moved.
• The Decision Registry Agent owns a knowledge base of your active architecture decisions — the ADRs, boundary rules, and dependency constraints that are currently in force. Knowledge isolation is deliberate here: this agent searches decisions and nothing else, so it never confuses a code comment for a rule.
• The Drift Report Agent takes the change from one and the intent from the other and produces the verdict — a plain-language finding for each place the diff diverges from a decision, with the specific rule it violates and the line it violates it on.

Because every agent's behavior lives in its knowledge base rather than in code, the mission evolves without a release. Ratify a new ADR, drop it in the registry, and the very next PR is checked against it. Retire a decision and it stops being enforced. Nobody redeploys anything.

What runs when a PR opens

When the PR webhook fires, the mission's chat route authenticates, loads the enabled agents and their knowledge bases, and hands the goal to the Reasoning Core — the router. The core doesn't know anything about architecture; all the domain knowledge lives in the agents. It reads the roster and the goal and decides, one round at a time, which single agent should act next.

Round one, it routes to the Diff Agent. That invocation runs the agent's planner, which discovers the agent's capabilities and executes them: here, the capability is a GitHub MCP server. This is the part I most want engineers to understand — we didn't write a GitHub integration. We registered an MCP server, and the agent discovered its tools at runtime. Wiring GitLab, Bitbucket, or an internal review system is the same move: stand up the MCP server, register it, and the agent uses it on the next run. No integration project, no redeploy. That's what "instant MCP servers" means in practice.

Round two, the core routes to the Decision Registry Agent, which queries its knowledge base for the decisions relevant to the files that moved. Then the core routes to the Drift Report Agent, whose plan ends — as every StudioX plan must — in a reason step. That final step runs on the mission's own reasoning layer, holds the diff and the matched decisions side by side, and produces the verdict: for each divergence, the rule, the location, and a plain-language explanation of the conflict.

Watching it think

Every one of those decisions streams. The mission emits observations — a live reasoning trace over Server-Sent Events — and they render on the Explain rail in true execution order: routing to Diff Agent… reading PR #4127… querying Decision Registry… matched ADR-014 "checkout must not read loyalty tables directly"… drift found at checkout/balance.ts:88. You are not handed a verdict and asked to trust it. You watch the mission reason its way there, and if it gets something wrong, the trace shows you the exact step — usually a stale or missing decision in the registry — so you fix the knowledge, not the code.

Where the human holds the wheel

I promised honesty about what's autonomous and what isn't, so here it is plainly. The checking is read-only. The Diff Agent reads the PR; the Registry Agent reads decisions. The mission does not push commits, does not merge, does not mutate your repository. Its output is a verdict.

The consequential moment is the override. When the Verifier flags a real violation and a team believes it's a justified exception, that's not a decision an autonomous system should make silently. So the mission emits a [REQUEST_APPROVAL] block, and the route turns it into a row in the Decision Queue — the surface where actions await human sign-off. The architect on rotation gets a magic-link approve/reject, the exception is recorded with its rationale, and the audit trail is complete. Human-in-the-loop isn't bolted on; it's the gate's whole point. The field report shows what that looks like on a real team, day to day.

The portal is the UI surface where the architecture board reviews trends — which decisions get challenged most, where drift clusters. All of it runs inside your perimeter, one instance of the pattern behind every AI Mission on the enterprise AI platform: agents that reason, act where you let them, and explain every step.