Est.

Architecture Graph Invariants as the Unit of Measurement for AI Drift

Architecture graph invariants make code drift measurable and enforceable at merge time.

Sponsored by Graphide

The Architecture Graph Editors
· 9 min read
Cover illustration for “Architecture Graph Invariants as the Unit of Measurement for AI Drift”
Codebase Architecture · November 2, 2026 · 9 min read · 1,999 words

Architecture drift in AI-generated codebases occurs when code continues to pass behavioral tests while its dependencies, boundaries, or call relationships diverge from the intended design. Architecture graph invariants make that divergence measurable through explicit, machine-checkable properties that either hold or fail. Enforcing those properties at merge time turns architectural intent into a control that can keep pace with agent output.

Why agents make drift structural, not incidental

Agents author a growing share of production commits, and their contribution is accelerating. The study identified as arXiv:2606.24429 documents that trajectory in tracked open-source projects from late 2025 to early 2026. The consequence extends beyond the amount of code produced. A single prompt can touch dozens of files, reshaping a slice of the system. The amount of review people can do does not grow with the diff.

That mismatch makes drift structural. An agent can introduce a direct database query into an API controller, bypassing the data-access layer while still returning the correct result. The implementation succeeds locally but violates the system’s hexagonal architecture boundaries. A conventional diff exposes the added query without establishing whether that relationship is permitted, while tests concerned only with outcomes may remain green.

Hartwig Grabowski’s Spec Growth Engine identifies context explosion as a companion failure mode. Without principled scoping, an agent reasons over unrelated repository concerns and produces “global fixes” that cross boundaries outside its task. Agent-authored pull requests also have meaningfully higher rollback rates than human-authored equivalents, indicating that existing review is not closing the gap. Whether agents can write correct code therefore matters alongside whether the development pipeline can preserve design intent as they do so.

Why line-by-line review and test outcomes cannot measure drift

A diff records edits. It shows which import was added, but not whether the importing module belongs on that side of a boundary. It can expose a new call without revealing the dependency path that call completes elsewhere in the codebase. Architectural drift is in those relationships between modules. Reading files in sequence leaves the reviewer to reconstruct them.

Behavioral tests answer a different question again. They establish whether a function or service satisfies the behavior being tested. A test can pass after an agent bypasses a declared contract interface. The Spec Growth Engine describes the resulting gap plainly. “The agent changes code; nobody updates the specification; the system still passes tests; the divergence is never flagged.”

Human approval cannot reliably supply the missing representation. When agent-generated changes have high merge rates and require little substantive interaction beyond mandatory approval, the gate is open by default. The Cognitive Integrity Threshold names the minimum comprehension needed for oversight to be substantive. Below that threshold, an approval records assent without establishing understanding.

The argument concerns the limits of review attention as a measurement instrument for a relational property. Even a careful reviewer must infer system-wide dependencies from a representation organized around changed lines. What is needed instead is a unit of measurement that is relational, machine-checkable, and independent of any individual reviewer’s attention span.

What an architecture graph invariant is and why it is the right atomic unit

An architecture graph invariant is an explicit assertion about a structural property that must hold across changes to the codebase. It is expressed against the architecture graph. The property may set rules for module boundaries, dependency directions, or call relationships. Its result is binary. Either the graph satisfies the assertion or it does not.

“Invariant” distinguishes the assertion from a guideline. “No component in the API layer imports directly from the persistence layer” declares a testable boundary, whereas a preference for loose coupling leaves compliance to interpretation. “All cross-module calls pass through the declared contract interface” specifies permitted communication. “The payments module has no transitive dependency on the notifications module” specifies a reachability condition. Each statement gives an atomic check, so a reviewer does not have to decide whether the architecture looks acceptable.

The graph supplies the right representation because these properties concern edges and paths. Dependency direction is an edge property. A forbidden transitive dependency is a path that must not exist, while a gateway requirement constrains which node a call path must traverse. These relationships become queryable objects. A direct-import rule and a transitive-dependency rule are therefore different predicates, even when they concern the same modules.

Formatting rules govern how code is written. These assertions govern which parts of the system may depend on or communicate with others. An invariant violation signals a departure from declared design intent. A prompt can describe that intent, but it cannot establish compliance with the resulting graph. The check must run outside the agent’s context.

How to define invariants that are precise enough to enforce and stable enough to survive legitimate change

A useful invariant encodes a decision that would require deliberate architectural reconsideration to change. It does not freeze every implementation choice. Dependency direction, boundary crossing, and call relationships are useful categories because each can be checked with a graph predicate. A precise rule names both the modules it covers and the relationship it constrains. Otherwise, the gate cannot tell an architectural violation from ordinary implementation work.

Consider the dependency rule that module A may import from module B, but module B may not import from module A. Conceptually, the graph query selects resolved import edges whose source belongs to B and whose destination belongs to A. The assertion holds when that result is empty. If an agent adds an import from B to A, the returned edge is the violation, even if the new code passes its behavioral tests. The rule does not prohibit changes inside either module or imports in the permitted direction.

The scope of that query is essential. A rule about direct imports does not by itself ban every transitive path, and a rule about calls through a gateway needs call-path evidence beyond import evidence alone. Over-specification creates a different failure mode. If every implementation preference becomes a blocking invariant, the gate flags legitimate changes and teaches teams to ignore it.

The Spec Growth Engine separates Layer-1 invariants in ARCHITECTURE.md from implementation-level contracts attached to individual nodes. The former govern cross-cutting decisions and become blocking merge conditions, while the latter can evolve within a slice. Eidos makes a related distinction through container boundaries and interface contracts, identified as CNT-* and CTR-*, and component or in-place design decisions, identified as CMP-* and DEC-*.

A legitimate reversal of the example dependency requires an explicit architectural transition. A DLT-* SpecDelta can declare the intended change and move through draft, proposed, verified, and applied states. Verification evaluates that planned transition against the codebase. When it lands, the invariant update and code change are committed together. The architecture remains changeable, but a newly permitted edge becomes a named decision rather than an incidental consequence of implementation.

Where invariants live: the spec graph as a versioned artifact in the repository

Invariants belong in the repository with the code they govern. Their authoritative form must be machine-readable and versioned, rather than dependent on a diagram, external wiki, or an architect’s memory. The Spec Growth Engine places Layer-1 invariants in ARCHITECTURE.md, from which architectural checks and drift reporting derive their intent.

Eidos stores specifications as AsciiDoc files with structured YAML frontmatter inside the repository. Specifications and code therefore share the same git history, and an invariant change has a diff, an author, and a timestamp. That arrangement makes a SpecDelta part of the development record. It also preserves the architectural intent associated with a particular code revision.

The queryable graph is computed from those authoritative inputs. Eidos indexes C4 specifications, AST code symbols, and test-bound invariants into a local SQLite graph, using recursive CTE traversal to follow relationships. The index can be rebuilt from the specification files and code on demand. Engineers maintain the declared intent. Computation removes the manual work of keeping the graph synchronized, while explicit specification changes remain visible in version control.

That history also supports investigation and audit. RAD-AI, by Larsen and Moghaddam in 2026, identifies EU AI Act Annex IV documentation requirements concerning how software components build on, feed into, and integrate with one another. A versioned specification graph provides an auditable record of those relationships over time. For production engineering, the immediate benefit is the ability to compare a code revision with the architectural intent recorded for it. CI can then use that same repository state to decide whether the new change can merge.

How CI enforcement turns the invariant from a declaration into a merge gate

At merge time, the Spec Growth Engine computes an Evidence Graph from incoming code and compares it with the Intent Graph derived from the specification. A divergence produces a hard error. The merge remains blocked until the violation is resolved or a SpecDelta explicitly changes the governing intent. This is the operational distinction between a documented rule and an enforced invariant. Compliance no longer depends on whether a reviewer notices the offending relationship.

Eidos implements the check through eidos drift in CI, evaluating the working tree against the specification graph. Each INV-* invariant binds directly to an automated test function. The check derives its answer from the repository alone, without an external service dependency. Because specification and implementation are evaluated together, the gate can test the architectural agreement represented by that revision.

The check must follow relationships beyond the changed lines. Graph queries find the ownership path and dependency edges of modules that changed, showing the containers, contracts, and invariants within their blast radius. The code-review-graph tool shows how graph traversal differs from reading raw files. A blast-radius query asks which other parts of the system a change touches, rather than only which lines changed. That is the information needed to detect a newly forbidden path.

The same checks can run before merge time. Directory-level hooks that run after tool use can check invariants inside the agent’s session, so the agent gets feedback on boundary violations right away, before CI. Deterministic checks of dependency direction, contract shape, and security posture fit this layer because they give precise results that need little judgment to interpret. The agent can correct a structural violation while working on the change.

ArchCodex constraint-injection benchmarks indicate that upstream architectural constraints reduce drift and increase architecturally sound output. The economic case is less late repair and more effort directed toward compliant solutions. An exit-code-2 signal is therefore not a rejection of agent speed. It redirects that speed by giving the agent a precise, machine-readable constraint violation, which is more actionable than a human review comment three days later.

What graph-invariant enforcement changes about the developer's role

With automatic enforcement, developers can have the most impact by improving specifications and defining constraints. A precise boundary between the API and persistence layers becomes a standing instruction for agents that later touch those modules. It outlasts any individual prompt or review session. Poorly defined invariants, however, reproduce the weakness of poorly defined prompts. An agent can satisfy the literal predicate while departing from the intent that predicate was meant to express.

Eidos exposes a C4 Architecture Portal for human engineers and a CLI for agents, both backed by the same graph. Developers can examine new edges, dependency paths, module ownership, and constraint coverage instead of reconstructing every relationship through diff-scrolling. Exploring the structure shows whether the code kept to the design intent. Code review can then address questions that the architectural predicates do not settle.

This division does not transfer architectural authority to the gate. The gate enforces decisions the developer has already formalized, and SpecDelta provides the path for changing them deliberately. The Spec Growth Engine describes the specification as “a living contract, not a historical artefact”. Its value lies in keeping architectural evolution visible while construction accelerates. The graph invariant is not a constraint on what agents can build, but the mechanism by which the developer remains the author of the architecture while the agent does the construction.

The developer who defines the invariants is steering. The developer who only reviews diffs is following.

Sources

  1. The Spec Growth Engine: Spec-Anchored, Code-Coupled, Drift-Enforced Architecture for AI-Assisted Software Development
  2. RAD-AI: Rethinking Architecture Documentation for AI-Augmented Ecosystems

More in Codebase Architecture