2.2 Models and the Semantic Gap

The last chapter gave you four places to inject a mechanism. This one is about the most valuable thing you can put there — a model — and about a trap that catches people the moment they try to enforce one: pushing on the model at the wrong level, and watching it slip. A model is the sweet spot between prose too vague to bind and code too verbose to reason over. But a model only helps if you check it where checking makes sense.

2.2.1 Words are soft, code is verbose, a model is the sweet spot

Your first governance mechanism is the prompt, because the agent is a language model and words are how you talk to it. But words are soft. They are ambiguous, and the more ambiguity you leave in, the less happy you will be. You can push the ambiguity down by writing documentation — describing the environment, the product, its goals, its policies — and if you were briefing a human team, that would be enough. Humans are not dumb; they remember, they know what matters, they know where to look things up, and they know they will be fired if they misbehave. Agents are different: brilliant reasoners who must be told exactly what to reason over, and for whom a loose document is simply not precise enough.

Code is the opposite failure. Code is perfectly precise — it is exactly what will happen — but it is far too verbose to reason over in bulk. What you want sits between the two: something accurate and unambiguous, yet compact. The word for that thing is a model.

You already know models from physics. Think of F = ma, or y = mx + b. Neither is reality — F does not quite equal ma, and real data scatters around the line — but each is a cheap, honest approximation you can actually reason over, instead of wrestling the full empirical dataset or a nightmare of fluid equations. A circle approximated by tangents is not a circle, but it is good enough to compute with. Software has its own such models. UML was the famous attempt: a whole language of them, out of the 1990s, expected to be the future. It never took off, and the reason it never took off is the reason this whole chapter exists.

2.2.2 Why the models drifted — and why that changes now

The models are the map; the code is the territory. You draw the map, you build the territory from it — and then the territory drifts. Code changes constantly, and the more it changes, the more it costs to keep the map true. Worse, no single model captures everything, so teams either piled every concern into one unreadable mega-model, or split their concerns across so many views that a single code change meant updating ten diagrams. So people gave up and drew box diagrams instead.

Keeping the map equal to the territory is an old research program, not a new worry. The field spent decades formalizing how a change on one side should cross to the other: model-transformation theory mapped out the design space of how one artifact is derived from another ¹1. Krzysztof Czarnecki and Simon Helsen, “Feature-Based Survey of Model Transformation Approaches,” IBM Systems Journal 45, no. 3 (2006): 621–45, https://doi.org/10.1147/sj.453.0621.; bidirectional-transformation work pushed past the two-artifact case to whole networks of models that must stay mutually consistent as any of them is edited ²2. Perdita Stevens, “Maintaining Consistency in Networks of Models: Bidirectional Transformations in the Large,” Software and Systems Modeling, ahead of print, 2020, https://doi.org/10.1007/s10270-019-00736-x.; and architecture-conformance techniques let an engineer measure the gap directly, computing where the code converges with the intended design and where it has drifted away ³3. Gail C. Murphy et al., “Software Reflexion Models: Bridging the Gap between Source and High-Level Models,” in “Proceedings of the 3rd ACM SIGSOFT Symposium on the Foundations of Software Engineering (FSE-3),” special issue, Proceedings of the 3rd ACM SIGSOFT Symposium on the Foundations of Software Engineering (FSE-3), 1995, 18–28.. The correspondence was always achievable. What never got cheap was holding it reliably and economically while both sides moved — the same daily-labor cost that pushed everyone outside the regulated shops back onto the code.

That cost is what agents change, and this book measures the change rather than asserting it: the model-synchronization measurement in Part 3 asks whether an agent fleet can carry the recurring reconciliation labor a person used to carry by hand. The claim is economic, not historical — agents did not invent synchronization; they made a maintenance regime feasible that the Agile era could not afford. Synchronization cost is reduced and redistributed, not zero: what does not move to the fleet is deciding what the correspondence should mean. The rest of this section is that regime made operational — agents reasoning over the models, and a drift gate that turns a disagreement into a failed build.

Anyone who has worked in a shop that tried to keep models by hand knows the failure in its bones. A new hire opens a diagram and cannot tell whether it is describing the system or lying about it — whether the box that is missing means the code lost a component or the diagram lost a maintainer. The model was drawn years ago by someone who has since left, and nobody updated it, because updating it was always the task that could wait until after the release. The map and the territory drifted apart quietly, and the first person to trust the map paid for the gap. That lived failure — a hand-maintained model that rots the moment the person maintaining it stops — is why the practice fell out of favor. Only the industries where a mistake is catastrophic — Rolls-Royce, Boeing — kept their models honest, because they could justify the cost. Everyone else chose agility and leaned on the code.

Agents flip the calculation, because an agent cannot reason over the code — there is too much of it — but it can reason over models. So if you can find the models that usefully approximate your system and keep them in sync, your agents will always know where to go. They walk the docs, hit a pointer to the model — a data-flow diagram, a performance model, an inheritance hierarchy, a user journey — and if that model is linked to the relevant code, they can make the change with the whole picture held in a single window.

And which model the agent reaches for shifts with the move it is making. Planning a feature, it climbs to the architecture to see how the pieces fit. Writing the code, it drops to the module the model points at. Asking whether the change still serves the user, it crosses to the journey that says what the product must do. The models form a hierarchy, and the craft is meeting each step at the altitude where it is legible — high enough to see the shape, low enough to act. One sweet-spot model cannot give you that; a set of honest, linked models can, because each is the right map for a different moment, and keeping them cheap to maintain is what lets the agent move among them instead of getting lost in the code between.

The model also lets the agent check its work: a test says the suite passed, but an invariant over a model says what must be true beyond the tests. This is how you stop architecture from decaying — the agent finds the architectural model, follows it, verifies against it, and when the territory genuinely moves, retrofits the map so the two stay equal. The companion catalogue's drift-and-parity gates are the mechanism that makes "the map equals the territory" a checked property rather than a hope: they fail the build the moment a model and the code it describes disagree.

Learn more about this governance mechanism: drift-and-parity gates.

Why agents don't reach for models on their own — a conjecture

Here a skeptic has a fair question. If working at the model level is such a win, why does the agent never reach for it on its own? Ask a coding agent to make a change and it dives straight for the code. It does not propose a model, does not ask where the map is, does not think to draw one. If models were the sweet spot, you would expect the model trained on all our software to have noticed.

I have a conjecture — and I flag it as a conjecture, not a finding. Two things may be compounding. The first is a gap in what the agent learned from. Serious model-based engineering happens inside regulated industry — aerospace, rail, power — where the stakes justify the cost, and that work does not leak into the open corpus a model trains on. The public code the agent read is overwhelmingly the agile kind that gave up on models and leaned on the code, so the agent saw very few real examples of the practice at all. The second is worse than absence. The corpus is full of text about models, and most of it is negative: the blog posts saying UML is dead, the war stories about diagrams that rotted, the received wisdom that model-based work is heavyweight and painful. So the agent is conditioned away twice over — starved of positive examples, and fed explicit priors that the whole approach is a mistake. There are, of course, other possible explanations; I think this one likely. And if it is right, the agent's reluctance is not evidence that models do not help. It is an echo of the era that abandoned them — and the thing that abandoned them, the cost of a human keeping the map in sync, is the thing agents just made cheap.

2.2.3 The apex of the documentation hierarchy is a structured model

Step back from drift for a moment and look at what you actually hand an agent to work from. It is never one thing. It is a hierarchy of descriptions, each aimed at the same system from a different angle. Prose docs at the top say what the thing is for; code comments say why a line reads the way it does; tests assert what must stay true; and schemas and typed records pin the shape of the data. Every one of these is a description of intent — and every one is partial, and every one drifts. The prose goes stale, the comment outlives the code it explained, the test pins yesterday's behavior, the schema lags the migration. This is the hierarchy the up-front half of governance climbs.

The usual agentic recipe gives you docs, code, and tests — and nothing binding them together. They sit as three separate islands. A change to the code does not touch the doc; a stale test does not know the schema moved; the prose swears the system does one thing while the code quietly does another. There is no glue, so there are no guardrails: nothing in the setup can tell you the three have fallen out of agreement, because nothing in the setup relates them at all. Drift, in this arrangement, is simply the default, and you find out only when it bites. Figure 2.2-1 draws the two arrangements side by side — the unbound islands, and the structured model that binds them.

The MAGE move is to take the hierarchy to its limit. Climb past the most careful prose and what sits at the apex is a structured model — the description that binds the islands into one checkable whole. A model is a description precise enough that a machine can read it, and because the machine can read it, the machine can check the other descriptions against it. That is the property no amount of good prose can give you. The model becomes the single description you hold the docs, the code, and the tests up to: does the code still match the state machine the model declares? Does the schema still match the records? When the model and the territory disagree, a build-time check fails, and the disagreement surfaces the instant it appears instead of the instant it bites. This is the same drift-and-parity gate from the last section, seen from the other side: there it kept the map equal to the territory; here it is the glue the three-island picture was missing. It is the one edge that makes docs, code, and tests a bound system instead of three things that happen to describe the same repo.

That is the Modeling Thesis at full strength. Documentation matters, and agents have made thorough documentation cheap for the first time, so climb the hierarchy all the way up. The rung at the top is a structured model that binds intent to implementation and that a checker can prove things about. Everything below it — the prose, the comments, the tests — is honest and useful and still drifts; the model is the one description that cannot silently lie, because the gate stays red until it tells the truth again. This is why the companion catalogue gives the models-bridge its own role. The whole aim of the up-front half is to build the one description the machine can check the rest against — and building it well is a craft the Model Zoo in Part 3 teaches by example.

One school of thought comes most of the way here and then stops one rung short. It agrees that loose prose is too soft, and it pushes intent into a fixed shape — but it keeps that shape in constrained English: requirements written to a strict grammar, structured to read like acceptance criteria, with a real model reserved for the cases whose stakes justify the trouble. This is the old cost calculation wearing new clothes. Structured English is still prose. A machine can pattern-match it, but it cannot hold the code up to it and prove the two agree, because the words carry no semantics a checker can act on. And reserving the model for where the stakes justify it is the same where-warranted hedge that once confined formal modeling to the high-stakes industries — a judgment that modeling is expensive, formed in a world where keeping the map current cost a person's standing labor. Agents cut that recurring cost sharply. When the map stays in sync almost for free, the structured model stops being the rung you climb to for the critical case and becomes the one you start from.

Modeling the surface turned up real bugs

The argument so far is that a structured model earns its keep by binding intent to implementation and letting a checker prove things about it. There is a plainer payoff the practice kept producing: modeling a subsystem surfaced real defects in it, not just a cleaner picture of it. Across a run of efforts that each built a structured model for a previously un-modeled part of the system, the act of writing the model — naming the states, the invariants, the seams — forced the kind of reading that finds bugs. It found a command-line seam whose exit codes were mislabeled, a resource leak on a cleanup path, an editing session that could lose an update because two writers were never fenced apart, and a queue-depth counter that drifted because it only ever moved one way. These were not style notes. They were live defects the tests had not caught, made visible because someone had to state precisely what the subsystem was supposed to do before they could model it.

Two honesties keep the claim the right size. Half of the defects were low-severity — the count is four real bugs, but two of them were minor — so read this as "modeling reliably surfaces something actionable," not "modeling finds a catastrophe every time." And the efforts that turned up no bug were not failures: each still produced an architectural strengthening, because modeling a clean subsystem still forces you to write down what "clean" meant. The mechanism at work is not luck. It is that you cannot author a spec — as opposed to mirroring the code — without deciding what the code ought to do, and that decision is exactly the reading under which a wrong "is" finally shows.

2.2.4 A drift check proves agreement, not correctness

The claim I just made hides a trap, and the book's enthusiasm for drift gates can be misread into a dangerous half-truth. A model wired to a build-time drift check cannot rot — that much is real. But it can still be wrong. The gate proves one thing: the model and the code agree. It says nothing about whether either of them matches what you meant. Both can move together, in the same wrong direction, and the gate stays a contented green the whole way.

Picture a model that says an endpoint is protected, and code that leaves it open. A drift check catches that — but only because the model already carries the concept that the endpoint is meant to be protected. Now derive the model from the implementation instead. The derived model reads the open endpoint and records it, faithfully, as unprotected. The code is unprotected; the model says unprotected; the drift check agrees. The bug is invisible, the gate is green, and everything is "in sync."

The power, then, was never in modeling as such; it was in the model being authored independently of the code. A model derived from the code is a mirror: it reflects what is, and a mirror cannot tell you the thing it reflects is wrong. A model authored from intent is a spec: it says what ought to be, and only a spec catches a wrong "is." People will generate a model from their codebase and believe they hold the same thing as someone who wrote one from intent. They do not. The drift check looks identical in both cases. What differs is whether an independent claim exists for the code to be measured against, or only a reflection agreeing with itself.

This does not weaken the drift gate; it tells you what the gate is for. Checking that the model and the code agree is mechanical, and the book automates it. Deciding what belongs in the model — which concepts it must carry, which "ought"s it must assert — does not automate. That is the essential residual Brooks warned would not yield, and under this method it moves one level up: from "write correct code" to "author the model that says what correct means." The gate is necessary. The authored model is what makes the gate mean anything.

We met a corner of this already, without naming it. A done-check can confirm the model was updated but not that it is right — the same asymmetry surfaces below, in the semantic-gap passage on the definition-of-done audit. And it recurs in the test dimension: a journey test that asserts only that the flow ran is a mirror of execution, while a typed task-closure post-condition is the authored spec that says what "done" means — the Scenarios view draws that line for oracles.

A model is a convenience, not a second copy of the truth

There is an over-reach on the other side of the mirror, and it is worth naming before the enthusiasm for models runs away. Grant that the model is a spec, authored from intent, and that the drift gate holds it honest against the code. It is still not a second place the truth lives. The code already holds the truth: it is exactly what runs. A model that only restates what the code plainly says has bought you a maintenance bill and nothing else — a faithful copy you now have to keep faithful.

What a model earns its keep with is what it lets an agent do. It puts the right place in one window, so the fleet navigates to a change instead of grepping for it. It carries the claim across a boundary two files should honor, so a root-cause walk reads the seam instead of guessing at it. It gives a benchmark somewhere to point. Each of those is an operation the raw code could not afford at the fleet's speed, and each is the reason to draw the model. None of them is "record what the code says a second time." So the test before you model a surface is not "could this be modeled" — almost anything can — but "what will an agent do with the map that it cannot do against the territory." Model where an operation needs the map. Where none does, the code is already the truth, and a model only adds a thing to keep in sync.

2.2.5 Just execute the model? A short history of CASE and MDA

If the structured model is where you now start, an old idea says to finish there too: skip the code and execute the model directly. The field has spent forty years on that idea, and where it landed marks the boundary this book keeps.

The dream had several names. Through the 1980s it was CASE — computer-aided software engineering ⁴4. Wikipedia, “Computer-Aided Software Engineering,” 2026, https://en.wikipedia.org/wiki/Computer-aided_software_engineering. — tools to draw a design and generate code from it; by the early 1990s the market held nearly two hundred of them. Their prize was round-trip engineering: change the design and see it in the code, change the code and see it in the design, so the two never diverged. Tools like Rational Rose sold that to a generation. In 2001 the Object Management Group formalized the most ambitious version, Model-Driven Architecture ⁵5. Wikipedia, “Model-Driven Architecture,” 2026, https://en.wikipedia.org/wiki/Model-driven_architecture. — write a platform-independent model, transform it into a platform-specific one, transform that into running code. With an action language, Executable UML went the whole way, to the promise this section is named for: do not write the code, just execute the model.

It did not take over the mainstream, and the reason was less a failure of the tools than a mismatch of tempo. The world went Agile, and software ate everything — most of it nowhere near safety-critical, and changing under you by the week. Heavy modeling could not keep that pace. Holding a model equal to code that moved every day cost a person's continuous labor, and outside the regulated niches (avionics, telecom, the shops where a mistake is catastrophic) the guarantees a model bought were not worth the rigidity it imposed. By 2006 one analyst house rated MDA "on the rise" while another had pronounced it dead on arrival. A survey of 450 practitioners found where it settled: teams rarely generate whole systems from models; they generate key parts, usually through small domain-specific languages built for one job.

Read that as a spectrum, not a verdict. At one end is no modeling: fast to change, nothing to keep in sync, no guarantee past the tests. At the other is the executable model that is the system: intent bound to code as tightly as it goes, and the least forgiving of change, because a model detailed enough to run is as large and verbose as the code it replaces. Every point between trades the same way: the further you model, the stronger the result — and yet the harder it is to move. Brooks still guards the far end. A model never makes the problem's essential complexity easy, so going all the way buys rigidity without buying simplicity. But where on that line you should sit was never fixed. It was an economic call, set by the cost of keeping the map equal to the territory, and that cost is what agents just changed.

So the book takes no strong stance on where to stop, because the sweet spot moved and is still moving. When keeping a model current costs a person's daily labor, you model sparingly and generate a slice or two. When a derived gate keeps the map equal to the territory for almost nothing, you can afford to sit much further along the line than the Agile era ever could. The old verdict against executable models is then worth reopening, not inheriting. This book sketches the spectrum and works a comfortable stretch of it: compact models you keep and reason through, with generation used narrowly where a model plainly governs an artifact. It does not claim that stretch is the optimum; the optimum shifted outward, and likely further than these pages go. The Executable Zoo is where the discipline for whatever point you pick gets its rules.

2.2.6 The semantic gap

Enforce a property at the wrong level and it slips through; Figure 2.2-2 shows the fix — lift the check to where the meaning is legible.

Now the trap. Say you want to enforce "if the agent substantially changed the call graph but did not update the overlaid model, reject it." It sounds like a pre-commit hook. It is not. An agent carrying out a real task makes many commits toward one goal; the model may be legitimately out of sync in the middle and correct again by the end. Enforce at the commit and you are checking a sentence for grammar before the paragraph is written.

This is the semantic gap: the failure you get whenever you enforce a property at the wrong level of abstraction. Operating-system security lives with it constantly — the OS sees individual system calls, but "this program is exfiltrating data" is a pattern across calls, invisible in any single one; you have to stitch ten network calls together before the leak is legible. Model drift is the same shape. The commit is the wrong granularity.

The fix is to find the level where the property is actually legible, and enforce there. For model drift, that level is the agent returning from its task, because at that moment the entire feature and its plan are visible. You can see whether the work changed the model, and whether the body of commits includes the tests, the documentation, and everything else the task was supposed to carry. This is exactly where the companion repository places its definition-of-done audit: a check that runs when an agent finishes an Epic, over the whole unit of work, rather than at any single commit inside it. "Correct" is a hard word — you cannot fully prove the model is right — but you can check that it was updated and that the surrounding work is complete, and that is the right semantic level to do it.

Learn more about this governance mechanism: definition-of-done audit.

Epic. A tracked unit of work larger than one commit: a feature or effort with its own file, plan, and definition of done, carried out over several agent dispatches.

Definition of done (DoD). The explicit list of conditions a unit of work must meet to count as finished — tests present, docs updated, the model in sync — checked at the end rather than assumed.

2.2.7 A worked example: the context-fullness bank-hook

A second instance of the semantic gap lives not in the product but in the operator's own loop. It is small, it is concrete, and it shows the same trap from a different angle: the machinery you are given sits below the meaning you actually care about, so it guesses, and the fix is to move the check up to where the meaning is legible.

When I run a long session, the harness has a context window, and when it fills, the harness compacts: it summarizes the conversation so far and throws the raw history away to make room. Compaction costs something. It is a lossy save, and the harness decides on its own what to keep and what to drop. That decision is a best-effort guess, and it is a guess because the harness has no way of knowing which parts of the conversation were load-bearing. It sees tokens. It does not see that the three paragraphs where I settled the architecture matter more than the forty where an agent walked a directory tree. Only the operator knows what was worth banking and where it should go. The harness sits below the semantics of "what is worth keeping," so it cannot help but approximate.

That is the semantic gap again, in miniature. The property I care about — is the durable record of this session current, so that a compaction loses nothing important? — is not legible at the level where the harness operates. The harness knows one number: how full the window is. It does not know whether my strategy document and my hand-off notes reflect the last hour of decisions or whether they went stale ninety minutes ago while I was busy dispatching work.

The fix: a hook one level up, checking two things

So I moved the check up to where the property is legible: the operator's loop. Not inside the harness, which cannot see the meaning, but at a hook the orchestrator controls, which can. The hook fires as the session runs and checks two conditions together:

Learn more about this governance mechanism: orchestrator lifecycle hooks.

• Is the context window getting full? The harness exposes this. On its own it is not enough to act on. A full window with a fresh strategy doc needs nothing done.
• Are the durable records stale? Have the strategy and hand-off documents gone untouched for more than a few minutes while work continued? This is the part the harness cannot see, because it is a fact about meaning: whether the map still matches the territory of the session.

When both are true, the hook does one thing: it emits a reminder to bank the current state into the strategy and hand-off documents. Then, when a compaction does fire, a second hook runs on the far side — a post-compaction hook — and it knows exactly where to look to rebuild context, because the pre-work made the durable records the authoritative place to look. The bank-hook tells the operator to write the record; the post-compaction hook tells the freshly-compacted session to read it. The two ends meet at the same documents.

Why both conditions, and not one

Why insist on both conditions? Because the dual check is what keeps the hook from becoming a nuisance, and the nuisance here has a specific and nasty shape.

Suppose I fired the reminder on fullness alone. Then every time the window filled, I would be told to bank, even if I had just banked. Worse, suppose I fired it on staleness alone. Then every few minutes, whether or not compaction was anywhere near, I would be nudged to stop and write. Either way the hook fires too often, and a hook that fires too often trains the operator to stop and re-summarize the session constantly. That failure has a name.

Sidebar — ouroboros. The ouroboros is the ancient image of a snake eating its own tail. In this loop it names the degenerate state where the model spends its turns summarizing its own recent work instead of doing new work — banking, then banking the banking, forever consuming its own output. A reminder that fires on a single loose condition drives straight into it. The dual check is the guard: fullness and staleness together are rare enough that the reminder lands only when it is genuinely worth acting on.

Requiring both conditions is what makes the firing meaningful. A full window is common. A stale record is common. Both at once — the window filling and the durable state having drifted out of date — is the exact situation where a compaction would actually lose something, and that is the only situation where the reminder earns its interruption.

The honest part: the pre-compact hook is the wrong hook

I want to be straight about a compromise buried in this, because it is the kind of thing the semantic-gap idea should make you notice rather than paper over.

The theoretically right moment to bank is the instant before compaction — you would catch every last decision, lose nothing, and never fire early. The harness even offers a pre-compact hook that runs at exactly that moment. It is the wrong hook to use. Two reasons. First, it fires too close to the end: by the time you are at the edge of the window, you may already be past the point where a comfortable bank fits. Second, and worse, the bank itself costs tokens. Writing a thorough hand-off is real work in the window, so a bank kicked off at the pre-compact boundary can be the very thing that trips the auto-compaction it was meant to precede. You reach for the save and the save pushes you over. The hook that seemed to sit at the perfect level turns out to sit slightly past it.

So I do not use it. I approximate the right firing point instead — earlier, on the dual condition — and accept a little loss: sometimes the reminder fires with nothing new to bank, sometimes a decision lands in the gap and has to be reconstructed from the summary. This is not the sound placement the drift example gave us, where agent-return is genuinely the level at which the property is legible and you lose nothing by waiting for it. Here there is no clean rung, so a hook at roughly the right level beats both.

Two promissory notes come due later, and it is worth saying where. The special language for stating invariants over a model — linear temporal logic, the split between safety and liveness, bounded model checking, and formal invariant verification — arrives in The Process View, where a model stops being a picture and becomes something a checker can prove things about. And the question of how you actually author a model in a repo — a typed record, a schema file, a lint that reads it, a diagram that stays honest — is answered by example, not by lecture, across the Model Zoo in Part 3. You now believe models matter; those chapters show you how to build and check one. And the move underneath this one is bigger than models: enforce a property at the level where it becomes observable. You will meet the same discipline in security reading a leak across many system calls, in testing choosing the unit or the journey, in CI gating a merge and not a keystroke, and again in monitoring, distributed consensus, and formal methods — the semantic gap is one instance of a pattern that recurs across the field.