Directive gap

Directive Gap is the inherent ambiguity that separates human intention from the system behavior that implements that intention. This is not a new problem. It has been studied for a long time. The holy grail is a process/tool that can capture human intent as specifications and convert it into software without losing any fidelity. There have been many attempts at it: Design by Contract (Meyer/Eiffel), Z notation, VDM (Vienna Development Method), CASE tools, Model-Driven Development, etc. The paradigm they all followed was to eliminate ambiguity from specifications so that these specifications can be converted into software with precision and determinism. They all failed for the same reason. Eliminating ambiguity made the specification language so complex that the spec itself becomes a programming language. So now you have to pay the cost twice: once developing a complex and detailed spec, and again in maintaining and executing the program.

AI coding agents appear to side step this issue by resolving a lot of ambiguity 'correctly' enough to make natural language a 'good enough' simulacrum of a formal specification. SDD takes the suggestible actor — the locally-reasoning agent I introduced in The Suggestible Actor — as a node in an iterative loop of starting with the spec, generating code, running tests, refining the spec to eliminate failures, and rinse and repeat until failures disappear.

Now you don't have to pay twice. You just iterate on the spec. Conversion to code is cheap. This makes SDD a directionally right attempt at converting intention to behavior. It shifts the responsibility of the software engineer from "write code" to "define what 'correct' means". But there is a problem. As one executes the SDD process, how do you know that you are done; how many iterations are enough; when can we say that the directive gap is closed?

The termination problem

Let's look at the information we have available to decide if we have iterated enough in SDD. We have the spec, the code, and the tests. The AI agent/LLM model is a constant. A natural stopping point is when the code passes all the tests. After all, the tests are the signal we use to determine how to refine the spec. If the tests pass, then we have no signal to refine the spec. So we should be done. Sure, there might be bugs, but that's true of even human authored code. At worst, code quality now has parity with human authored code, and all the humans have to do is maintain the specs that are easier to understand and manipulate. If only!

Notice the assumption smuggled into the previous paragraph: the LLM model is a constant. While that might be true during an SDD session across all iterations, it is not true in general. Every few months some AI lab releases a new model, and it promises to be better than all other models that came before it. What happens when you switch the model? Say, that your spec for a job scheduler was iterated meticulously through SDD on Claude Opus 5, and your employer decided to switch over to Codex 5.6. Would the spec produce the same code with Codex 5.6? In fact, the chances are that the code produced by Codex 5.6 will actually fail at least one test whereas they all passed with the same spec on Claude Opus 5.

This is not speculation. Wasowski ran precisely such an experiment and talked about it in his post "Stop Writing Specs. Start Writing Facts. The Entire SDD Movement Is Already Obsolete." His spec needed constant 'refinement' as he upgraded across Claude Sonnet 3.5, 3.7, 4, and Opus 4.5+. The spec that worked in the previous model produced incorrect code in the new model. The tests, on the other hand, stayed constant.

Folks from AWS discovered a mathematical limitation of closing the directive gap. In their "Fidelity Probes" paper, Erata et al. found that if a single iteration has a non-zero base rate of generating code that doesn't completely align with the spec, then there is a non-zero lower bound on the 'error/gap' between the spec and code across multiple iterations.

I ask again: how do you know you are done?

The hidden gap

The spec is unstable relative to different AI models. But (spec, model) combination is stable. That is the key observation of focus on. Why is that the case; why is (spec, model) stable, but spec alone is not? The answer comes back to the directive gap. When iterating on a spec with a given model, the fixed point that you reach is NOT a signal that the directive gap is closed; instead, it is really a signal that the model has hidden the directive gap through confabulation.

In some ways, the problem is worse than before. The spec-based development before AI agents exposed the directive gap no matter how nuanced, so that you knew where your spec was deficient. AI agents now hide any directive gap below a threshold and are only revealed when the model changes. This lulls you into a false sense of security with a rude awakening on the other side of a model upgrade.

How do you address this hidden gap? If you try to make the spec detailed enough to be model independent then (a) you have no idea if you have actually succeeded, and (b) spec becomes as detailed as the programming language itself, and is effectively self-defeating. Instead, I suggest a reframed approach: what if, instead of treating spec as the primary artifact, we treated both spec and code as co-artifacts, in a two-layer governance model, and we measured mutual fidelity using the AI agent?

The "reverse pass": AI agent as an observer

In this reframed approach, you start the same as any SDD iteration. You continually refine the spec until you have reached a fixed point, where all the tests pass and the code generated by AI matches the spec's intent. Let's call this the "forward pass", where you go from the spec to code. Instead of stopping here, you turn the AI agent's gaze backward, and ask it the question: "does the implementation/code conform to the spec, and if not, what are the deviations?". This is the "reverse pass"; an addendum to SDD. In this step, you are now using the AI agent as an observer and not as an implementer.

Now, the first time you are doing this, if you have followed the SDD process correctly, the answer to this question from the AI agent is "yes, the implementation conforms to the spec, and there are no deviations." However, this is not going to be the case in the future, with model upgrades. For now, let's start with the pair (spec, code) as co-artifacts. We expect this to be stable for a given model. All changes/bug fixes are going to be through spec changes or addendums, but with the same model. Since the model is constant, the "reverse pass" should still continue to say that the implementation conforms to the spec.

Model upgrades: reconciliation via the "reverse pass"

When you perform the inevitable model upgrade. The (spec, code) co-artifacts are no longer stable. Before you start any new development or change the spec, the first thing you do is perform a "reverse pass" with the new model. In effect, you ask the new model/agent "does the implementation/code conform to the spec, and if not, what are the deviations?", and this time, the agent will respond back with a set of deviations of the code from the spec; the new model will interpret the spec differently from the old model. This is part of your hidden directive gap made visible.

Here is often where SDD breaks down with complaints of unstable specs. With the reverse pass result, your co-artifacts evolve from (spec, code) to (spec, code, deviations, model). This is the true artifact of the modified SDD process. In fact, it was always (spec, code, deviations, model), but the first time around, the model was implied, and the deviations were null by construction. At this point, you have some options.

1. Since the code is "correct", you can simply record those deviations as part of the SDD artifact and make those observed deviation part of the spec itself, and so spec + deviations becomes the new spec.
2. Alternatively, you can review those deviations, and see if they reveal true gaps in the implementation; if so, you now refine your spec to account for the deviations and run another set of SDD iterations until the "reverse pass" produces no more deviations.

Either way, you eventually converge back to (spec, code) as co-artifacts with a null for deviations and the model is implied.

The important thing to observe is that a model upgrade now looks a lot like a compiler upgrade or a language upgrade. Just like existing code needs to be changed when you go from one version of the compiler to another (especially when the compiler changes are not backward compatible), you are essentially doing the same thing when upgrading the AI model. This is precisely why the spec and code are co-artifacts with the model as the implied constant and the deviations ("reverse pass" results) as a transient artifact through such upgrades.

Why aren't tests enough?

What value does a reverse pass add on top of a robust test suite? Both serve different purposes. The tests are there to ensure that the code's behavior meets the requirements, whereas the reverse pass is there to reveal any directive gaps that have now become visible. This is the split between behavioral vs architectural coherence tests: behavioral tests verify function, architectural coherence tests verify structure. Examples of issues that a reverse pass catches, but tests miss include implementation inefficiency, output instability (at scale), and missed invariants and preconditions. Here are illustrations for each.

Implementation inefficiency. If the implementation uses sort to get top-k, the tests will still pass, despite an $n log(n)$ implementation instead of a $k log (n)$ implementation. A reverse pass would catch that.

*Output instability. *Say, in Javascript, the code uses Array.sort() and the test cases verified the expected output to be correct. However, Array.sort() does not provide stable outputs, and unless the test suite was specifically looking for such stability, it will likely miss it. In fact, to even think of such a test, one would have to have known about the properties of Array.sort(); so, either the generated code does not use Array.sort(), or if it does, it will likely miss the tests for stability. A reverse pass would catch it as part of its semantic analysis of the code against the spec.

Missed invariants. Similar arguments apply for invariant checks as well. During forward passes, the spec goes through semantic analysis, and code is checked against tests. The rigor of semantic analysis of the code is higher in a reverse pass, and so, reverse pass is more likely to spot such invariant violations that tests can miss.

What does the SDD addendum look like?

Bringing it all back together, I propose the following addendums to Spec Driven Development.

1. The development process starts much like a regular SDD session with multiple iterations from spec to code to tests, and back to refining the specs which produce 'better' code until you have converged to a spec and the code that passes all the tests and is empirically 'correct'.
2. At this point, instead of treating either the spec or the code as the 'primary artifact', you treat both the spec and the code as co-artifacts. You commit both to your repo. Spec denotes the intent and the code describes the behavior. However, it is important to realize that this (spec, code) co-artifacts are stable only relative to the current model and harness.
3. Every time the AI model or harness changes, the (spec, code) artifacts may no longer be stable. However, it is important to note that the code's behavior is still empirically correct. Through a model/harness upgrade, we run a "reverse pass" and ask the new model/harness "does the code implement the spec, and if not, what deviations do you see between the spec and the code". This generates a report with observed deviations.
4. These deviations are either material to the system behavior, or incidental to model interpretation. In case of the former, we go through another round of regular SDD session to converge between the spec and the code. In case of the latter, we simply append the spec with the deviations so that future changes to specs does not result in code churn due to the incidental deviations.

The hidden directive gap does not go away. The fix is to stop pretending the spec alone is the artifact. Hold spec and code together, use the new model as an observer that makes its own reading visible, triage the delta. Model upgrades now look no different from third party library updates, or compiler updates, and that is something we know how to do well.

Here are five examples.

Removing the "Safety" in the "AI Safety Consortium"

On May 29th, the National Institute of Standards and Technology (NIST) issued the following press release. It was 'expanding the scope' of AI Safety Consortium and calling for new members. Except, that when one says "expanding the scope", it is additive; you doing the same things as before and some more. But the Orwellian "expanding the scope" here actually means that they will no longer be focusing on AI safety, and will instead focus on "AI innovation and adoption".

This change runs right through the guts of the organization. The institute itself goes from U.S. "AI Safety Institute" to "Center for AI Standards and Innovation". The consortium goes from "AI Safety Institute Consortium" to "NIST Artificial Intelligence Consortium". Notice the removal of "safety" from both places.

The mission statement of the consortium changes too.

Before: "…establishing the foundations for a new measurement science in AI safety."

After: "…enable the identification of proven, scalable, and interoperable techniques and metrics to promote the development and use of AI."

The consortium's own announcements, 2023 versus now:

2023: "…in support of the development and deployment of safe and trustworthy artificial intelligence."

2026: "…will concentrate on AI measurement, innovation and adoption."

The working groups are all mostly gone and replaced. Four of five original groups were safety-specific (generative AI risk management, synthetic content, red-teaming, model safety and security). All four dropped. Replacements are measurement and standards-oriented. The word "safety" appears zero times in the current consortium page outside historical references to the old name.

This is not "broadening", this is usurping the body for its antithetical purpose.

The self destruction in Trump AI Executive Order

The AI Executive Order from June 2nd does a curious linguistic acrobatics of laying out an AI governance structure while simultaneously undermining it within the same section. It starts off talking about "new national security considerations that require coordinated action across executive departments and agencies (agencies), and components" and it says that within the next 30 days, "the Committee on National Security Systems shall prioritize the cyber defense of National Security Systems" and "the Secretary of War shall prioritize the cyber defense of Department of War information systems", and so on. Within 60 days, it will "develop and maintain a classified benchmarking process to assess the advanced cyber capabilities of AI models", "design a voluntary framework with AI developers" to engage with this benchmarking, "provide the Federal Government with access to covered frontier models", and so on.

It sounds like it really has some muscle, and that we might actually get something useful from this. But in that same section, it deflates the entire effort with "Nothing in this section shall be construed to authorize the creation of a mandatory governmental licensing, preclearance, or permitting requirement for the development, publication, release, or distribution of new AI models, including frontier models."

The executive order pretends to create a governance structure, but bakes in a self-destruct clause that ensures governance never actually happens. It's a Broadway show where the director introduces the cast, the orchestra swells, and then the curtain falls. That's the whole show.

The ever-lengthening leash of the EU Digital Omnibus

When you talk of user privacy and regulation, EU is typically seen as the vanguard. GDPR has become the template against which all other user privacy bills are written. Back in May 2024, the EU adopted the EU AI Act. It was an ambitious bill that promised to do for AI development what GDPR did for user data. It talked about prohibited AI practices, defined what it means for AI to be high risk, and the obligations that go with it for both the model developers and providers. It talked about setting up AI regulatory sandboxes at national and regional levels to better understand how to regulate AI. On paper, it made all the right moves.

Last week the EU released the Digital Omnibus proposal which effectively stops the clock on all of the provisions outlined in the EU AI act. These provisions were supposed to kick in in August 2026, but that timeline has been extended to 2027 and 2028 with no promise of that being final. The reason given was to "giving industry time to prepare", which sounds plausible, but think about it. Were the original framers of the EU AI Act so naive that they baked in unrealistic timelines and the rest of the world (including "the industry") so bright-eyed that they simply did not realize that the timeline was too aggressive? Or is it more likely that it has been intentionally defanged while keeping the same form as before. Not too different from our previous examples.

The preemption of the Great American AI Act

On the face of it, the Great American AI Act is a rare feat in politics and policy. It is a bipartisan bill and a first of its kind in the US with the goal of creating a federal framework for governing artificial intelligence model development. It even pays lip service to federalism by clarifying that the states retain authority to regulate AI use. This bill only targets AI development and not use; and therein lies the rub.

The bill bars states from laws "targeting artificial intelligence model development." But it does not actually clarify what it means by development vs. use. Is post-training part of development, or is it part of use? When a company puts in all of its internal data and information so that when the employees are using the AI agent, it already knows about how the company functions, where the documentation is, what the org structure is, etc., is that development or use? The bill doesn't really answer that question.

Beyond that, there is a temporal gap. The preemption of state laws governing AI development takes effect immediately after the bill is passed. But the federal framework is not ready yet. The bill merely states that one should be developed. It could take an indeterminate amount of time for CAISI working group to be established, standards developed, and verification organizations designated. Work that takes years and may never materialize in a divided Congress.

The text of the bill claims to be for "protecting Americans", but its first consequence appears to be removing any little protections that had from state legislation on AI development with no timeline for when a federal framework would ever be realized.

As bad as it looks in isolation, consider the compounding effect of Executive Orders and this bill: (a) Trump EO from December 2025 preempts state laws, (b) Trump's AI Executive Order from June 2 creates voluntary framework disclaiming mandatory authority, and (c) this bill codifies preemption with narrow federal framework. Each instrument legitimizes the next and progressively erodes governance.

The expansive coercion in NSPM-11

The National Security Presidential Memorandum (NSPM) 11 released on June 5th 2026 marks a dangerous expansion of the executive authority in pursuing AI ambitions while simultaneously dismantling governance structures that safeguard against harmful use of AI. NSPM-11 rescinds the Biden-era NSM-25, which outlines the administration's approach to AI safety. For context, in NSM-25 the word "safety" appears 45 times, whereas in NSPM-11, there are ZERO occurrences of the word "safety".

The story here is not just that of governance retreat. NSPM-11 also smuggles in a massive coercive authority that was previously marshaled to target other nation states. Section 2(c) requires that (emphasis mine) "no commercial entity or adversary" possesses the capability to prevent use of, disable or degrade, or materially modify any deployed national security AI system. The operative phrase is "no commercial entity or adversary". So, the same mechanisms used to ensure that (say) China cannot defang US military AI capabilities are also deemed acceptable when targeting a corporation such as Anthropic. That is dangerous overreach. Transnational geopolitics resorts to very heavy mechanisms because there are no enforceable laws when it comes to actions of one nation state against another (think Russia's election interference in the US; it is not like we can file a suit against Russia in US courts over that). In contrast, commercial entities are subject to US laws and regulations, and therefore, their behavior can be influenced through various means that are consistent with such laws and affords all the protections that due process provides. And this due process is a strong counterbalance against executive overreach. NSPM-11 is an attempt to weaken that very same due process and strong-arm AI companies as if it were an external adversary/threat.

This should scare everyone.

The standard explanations for it include information overload, decision fatigue (from evaluating AI output), cost of increased productivity, etc. They all capture parts of it and don't add up to the entirety of the experience. Sure, there is some cost to evaluating AI output, but I do that with code reviews from human-authored code too, and it does not drain me out like this. Yeah, I am more productive, but that's AI doing the heavy lifting; so why do I feel tired?

In search of an explanation, I started digging around academic research and published reports to see if this has been figured out. What I found was a bunch of adjacent literature that seems to connect up to something, but no kill shot. What follows is my conjecture, and possible experiments that could disprove it.

The five relationships

When you are working with an AI agent, you are subconsciously developing a relationship with the AI (albeit an unrequited one) despite consciously recognizing that the AI is "just a tool". You get occasional glimpses of this relationship when you find yourself saying "please" or swearing at the AI in text; you would never do this with your compiler, and yet it is normal with an AI agent.

Your relationship with the AI can take five forms, oscillating between them unconsciously (Gülay et al. 2025):

1. Director: You are giving instructions to the AI agent to perform tasks (such as "refactor this module")
2. Trainer: You are teaching the AI agent how to perform the tasks (e.g., "Use the git log command to fetch the historical commits").
3. Partner: Here you are collaboratively working with the AI to accomplish the task (e.g., you come up with a hypothesis for a root cause and ask the AI agent to come up with counter examples to falsify it, and then look for evidence)
4. Student: You are asking the AI to teach you things. (e.g., you ask the agent to summarize a design document, or ask it to explain how, say, Kafka works)
5. Consumer: You are asking and following instructions from the AI. (e.g., you have a root cause of a bug and you ask the AI how you should fix it)

Others have found different ways to categorize this relationship. If you think of ways in which you use AI to obtain knowledge and understanding (Yang & Ma 2025), you get five different categories: Instrumental Reliance, Contingent Delegation, Co-agency Collaboration, Authority Displacement, Epistemic Abstention. The field is nascent; stable categories don't exist yet.

Regardless, we do have different forms of relationships with AI, and we are in all of them simultaneously. Within a single session, you switch from one form of relationship to another, and this happens seamlessly and without your conscious acknowledgement. You start a session commanding ("fix this bug"), shift to collaborating ("what if we tried X instead?"), find yourself teaching ("no, the constraint is Y because..."), then deferring ("actually your approach is better"), then passively reviewing output. Five modes. One conversation. You didn't decide to switch. You just did.

The fatigue you feel at the end of the day is an accumulation of these relationship oscillations.

The switching is not free

We have evidence from the cognitive task switching literature (Monsell 2003; Rogers & Monsell 1995; Kiesel et al. 2010) that switching between tasks carries measurable, residual costs. This happens because when we switch tasks, we are really reconfiguring our mental set: new expectations, response mappings, and success criteria. This cost is why multitasking is less productive than spending a focused amount of time on a single task.

The switching cost extends from tasks to relationships as well. Studies show that social role-switching frequency is a predictor of stress, independent of the total number of roles (Cornwell 2013): in a sample of 7,662 adults, those who switched between social roles more frequently reported higher stress. (The effect held for women but not men, suggesting gendered differences in switching costs that the AI interaction context may or may not preserve.) It's not that having more roles is stressful; it's that switching between them more often is.

Each of the five relationship modes with AI carries different expectations for what counts as good output, how to phrase your input, what level of explanation to provide, and whether to accept or challenge the response. Each switch is a reconfiguration of mental set, which is the same mechanism Monsell documents for cognitive tasks, applied to social framing. If (and it is an if) the mechanisms associated with the relationship switches with AI are the same as the task and role switching in social contexts, then the fatigue from such stress simply follows naturally.

Emotional labor tax

There is an added cost to interacting with AI. We are not simply talking to the AI; we are performing a persona. Each relationship mode requires a different one. Directing an AI requires one emotional register (authority, concision). Teaching it requires another (patience, pedagogical framing). Collaborating with it requires a third (openness, intellectual generosity). Each switch is not just a cognitive reconfiguration; it's an emotional labor transition. You're changing which emotions you're performing, not just which task you're doing.

The emotional labor literature (e.g. Hochschild 1983 and Brotheridge & Lee 2002) shows that performing emotions you don't feel (surface acting) produces estrangement and burnout: emotional exhaustion, depersonalization, a progressive depletion of the capacity to keep performing. The literature has extensively studied the cost of sustained surface acting toward one audience: customers, patients, students. What it has not studied is the cost of switching emotional performances rapidly within a single interaction.

My conjecture is that these results transfer to our interactions with AI, and so the cost of emotional labor acts as a compounding factor on top of the cost of switching relationship modes itself. Nobody has studied what happens when you're switching cognitive frames, social roles, AND emotional performances simultaneously, dozens of times per session. In isolation, these literatures point in the same direction, but they measure different things on different timescales: Task switching literature measures costs in milliseconds in controlled tasks; role switching literature measures daily stress; and emotional labor literature measures chronic burnout. The convergence is thematic, not mechanistic. That's what makes this a conjecture worth testing, not a conclusion.

Instability surcharge

With a human colleague, you settle into a relationship mode relatively quickly, and the changes in the mode are occasional and they evolve. For example, it could start with "he is my tech lead", and in a few months "he is my manager". It typically happens unconsciously. With a tool, you settle into "this is a tool" and the framing never wavers. But our relationship with AI is neither.

AI agents are categorically ambiguous. You say it is a tool; you know it is a tool; you want to use it as a tool. Yet, when you actually start using it, your relationship with it changes, and it changes continually.

Previously, under the "Computers are Social Actors" (CASA) framework (Nass & Moon 2000), the claim was that people apply social rules to computers automatically because the computer's outputs trigger social cues (albeit minimal). But this does not hold for AI agents.

One explanation: AI is a novel technology, and we are not habituated to it. Recent work shows that CASA effects may not survive habituation (Heyselaar 2023, Scientific Reports): replicating the CASA experiment with people who grew up with computers around them, the habituation to the technology seemed to have nullified the CASA effect. So perhaps our next generation will not have this issue. But I suspect that is not the story. Desktop computers and AI agents are categorically different.

AI agents' social cues are rich but also simultaneously inconsistent. AI can act like a subordinate, assert like a peer, or even explain complex concepts like a teacher, and it all happens in the same conversation. CASA's prediction holds when the computer's social cues are coherent, and here they are not. With contradictory cues, the ambiguity around the AI's relational mode never resolves. We are forever in a situationship with the AI.

Unrequited debt

You might have a relationship with the AI, but AI does not have a relationship with you. Recall from emotional labor theory that sustained surface acting produces burnout. Social reciprocity partially offsets it between switches. This recovery mechanism is built into the interaction, which is why you are not a dried husk after day-long interactions with your colleagues (assuming you actually like working with them). But an AI agent is a different matter.

Your AI agent returns well-formed output and gives you useful feedback, but it does not provide emotional reciprocity. It does not feel 'thankful' nor does it 'look forward' to interacting with you. Human-agent interaction is genuinely social (Banks 2026, "Ghosting the Machine"): not parasocial, not pretend-social, but the real thing. That means the depletion from unrequited emotional labor is real, with no recourse for replenishment. It is completely unrequited.

This absence of reciprocity accelerates the fatigue. If you were to treat the AI (say) as a subordinate all day long, then your emotional labor would leave you depleted. But that is not how you treat the AI agent. You are constantly switching modes, and each switch has an additional cost on top of your ongoing cost of this unrequited interaction. The depletion compounds with each interaction, faster with each switch, and there is no avenue for replenishment.

Your situationship explained

Here is my hypothesis. The AI fatigue is not about doing too much or being too productive or making too many decisions. AI's interaction pattern subconsciously draws you into a relationship with it. This relationship is constantly changing and does not have a stable interaction frame. This is compounded by the emotional labor on each switch of the frame, and accelerated by the lack of emotional reciprocity from the AI. There are three factors that compound: the relationship mode switching is the driver, the emotional labor is the multiplier, and the broken reciprocity prevents attenuation of the cost.

Like all good hypotheses, this one is falsifiable. Here are some experiments to shed light on the phenomenon. Take away the AI agent, and replace it with a human, and the fatigue should become significantly attenuated. If you were to coerce the interaction with AI to be in a single relationship mode, the effect should be a lot smaller. Reduce the number of switches, and the fatigue should be less.

If I am right, then the issue isn't that the AI isn't more human-like. The culprit is that AI's social cues are inconsistent and without emotional reciprocity. Making AI more human-like without making it relationally consistent should only make the problem worse.

The implication is not that we should make AI less capable or use it less. It is the opposite. Not that we should make AI more human-like; we should make AI more capable of holding a relationship with a human in a fixed or natural register. This problem looks solvable.

Spec-Driven Development: why is it useful, when others failed?

SDD (Böckeler 2025, Bouchard 2026) iterates between structured specifications and human review gates until the spec is unambiguous enough to generate code. It correctly shifts the developer's job from "write code" to "define what correct means." SDD is arguably the first directionally right attempt at an AI-native development pattern.

Every prior spec-first methodology (Waterfall, design-by-contract, CASE tools) failed because specification was additional to implementation. You spent effort on the spec, then more on the implementation. The latter is necessary and expensive, and so people often forgo the former.

Generative AI changed that cost calculus. Implementation is cheaper, but it erodes guardrails systematically. Specifications appear to be the antidote: the surplus human attention goes to spec development as a foil against erosion. Hence SDD.

But how does SDD resist guardrail erosion? The Suggestible Actor model and its guardrail erosion corollary reveal that there is always a directive gap between what you specified and what you meant. The iterative process of testing a specification against the produced code and refining the specification in response narrows this directive gap to the point of functional correctness.

However, there is a layer in software design that iteration cannot reach: architectural constraints.

Architecture orphaning

While a spec describes WHAT the system should do, it does not describe HOW it should do it. Questions such as "which library to use" and "which boundaries to respect" are outside the spec. A spec can state architectural constraints, but behavioral tests derived from that spec cannot enforce them. A test that verifies correct output passes whether the code calls a shared service or reimplements the logic inline. Stating the constraint is easy; detecting violations through the spec-to-test pipeline is the gap.

The WHAT and the HOW are two distinct layers in software design. In traditional development, one human holds both layers in the same head. With LLMs, the layers separate, and architectural decisions fall between:

• The spec's test pipeline cannot enforce it (behavioral tests don't verify architectural choices)
• The LLMs cannot infer it (architecture is system-level, non-local; the suggestible actor reasons locally)

Architecture becomes an orphaned layer: too low for the spec, too high for the locally reasoning agent. Sure, SDD lists architecture as a design phase; but listing is not the same thing as governing. Architectural decisions remain invisible to the behavioral test.

SDD critics are really talking about architecture orphaning

Critics come from different directions, but look closer: they are observing symptoms of architecture orphaning without diagnosing it.

Canciani ("Code over Specs," May 2026) proposes "fitness functions" — architectural tests that enforce structural boundaries: "You aren't writing a spec; you are setting a hard boundary." He also advocates Architectural Design Records (ADRs) as "case law" that stops AI from re-litigating settled architectural decisions. Canciani is arguing for structural guardrails without the theoretical grounding for why specs can't do this work.

Dev.to/REAP ("Why SDD Fails," May 2026) states it directly: "The same specification produces different implementations across different runs — varying architectural choices, data structures, and error handling." That sentence is architecture orphaning as empirical observation. Their fix is evolving "Genomes" of principles and conventions: richer context for the agent, but still a social guardrail (one of the least robust guardrails). The agent can violate it when the local context moves past these conventions.

Konrad et al. ("Architecture Without Architects," Apr 2026) arrive at the phenomenon empirically. AI coding agents select frameworks, scaffold infrastructure, and wire integrations in seconds: "These are architectural decisions, yet almost no one reviews them as such." They coin the term "vibe architecting" — architecture shaped by prompts rather than deliberate design — and confirm that prompt wording alone produces structurally different systems for the same task. This is architecture orphaning observed in the wild, with independent terminology.

The consequences are already measurable. Huang et al. (2026) find that LLM agents disregard code reuse opportunities, and that reviewers express more positive emotions toward AI-generated code than human code: surface plausibility masks structural damage. GitClear's analysis of 153 million lines tells the same story: less refactoring, more copy-paste, code that "resembles an itinerant contributor."

A separate layer for architectural governance

For AI-assisted software development, we need two distinct layers of governance: (1) iterative spec convergence, which is what SDD provides, and (2) architectural coherence, which structural guardrails provide.

Iterative specification convergence (spec layer) handles functional correctness. The human iterates on the spec; the LLM regenerates; verification narrows the directive gap. It happens for each feature and frequently. This is what SDD does at its best.

Architectural coherence (implementation layer) handles architectural drift and ensures drift is deliberate. Enforcement is expressed per-system, requires high investment (human effort), and changes slowly. This is what SDD lacks and cannot provide, because SDD operates entirely at the spec layer.

Neither substitutes for the other; they complement each other. Convergence verifies "does this code do what the spec says?" Structural guardrails verify "does this code respect the system's architectural constraints?" The spec cannot enforce architecture through its test pipeline without collapsing the abstraction, and structural guardrails cannot close the directive gap.

Both layers produce tests, but these two types of tests are distinct. SDD produces behavioral tests (e.g., "given valid credentials, return 200") that pass regardless of how the behavior is satisfied. Architectural coherence tests verify structure: they are derived from the architecture document, not the spec, and encode structural decisions as test constraints.

What does architectural coherence look like?

Your architecture says all authentication goes through the auth service. The SDD behavioral test ("given valid credentials, return 200") passes whether the code calls the auth service or reimplements auth inline. The architectural coherence test: a build-system visibility rule that prevents the user-facing service from importing auth implementation libraries directly. It can only depend on the auth service client. That rule lives in CI configuration the agent cannot modify. Violation is a build failure, not a review comment.

With such tests in place, the architect's job shifts from drawing boxes and arrows to designing types, build rules, and capability boundaries. The tooling for this is nascent: today, building architectural coherence tests is a manual investment per system. That investment is the cost of the two-layer governance model, and it is a tooling gap the ecosystem has not yet closed.

SDD promised to harness the power of AI coding agents without the quagmire of multi-generational vibe coding. But that promise comes with a near-fatal loss of architectural coherence. This is a genuine trade-off that you cannot reclaim without paying with the scarcest resource: human attention that builds and maintains your structural guardrails.

In my Suggestible Actor post I prescribed four design strategies that build guardrails to mitigate the mistakes by AI coding agents: actionable errors, hard boundaries with signposts, documentation as local context, and closing the directive gap. I have come to realize that my prescription will not be enough. AI agents generate code that incidentally modifies guardrails. More often than not, those modifications erode them.

Guardrail erosion: what is it?

Guardrail erosion is the phenomenon where codebases that are iteratively modified by AI-generated changes without proper human reviews accumulate bugs at a faster rate. An IEEE-ISTAS paper showed this to be true with vulnerabilities. A recent SlopCodeBench paper on arXiv showed an increase in 'structural erosion' over iterative AI code changes.

Such erosion is a structural consequence of the Suggestible Actor properties of an AI agent.

• A goal-oriented agent treats guardrails as obstacles when they produce errors that block progress toward the goal.
• A locally reasoning agent cannot distinguish between a test that documents current behavior (safe to update) and a test that guards a critical invariant (dangerous to update): both look the same from the local context.
• An agent susceptible to local context pattern-matches from the surrounding code; if prior iterations have already weakened some guardrails, the context reinforces further weakening.
• An agent that hallucinates under uncertainty will, when encountering a guardrail it does not understand, resolve the ambiguity in the direction that clears the immediate error: loosening the constraint rather than preserving it.

A more capable model will not stop eroding guardrails. It will erode them more efficiently, or possibly more convincingly. These properties do not depend on current model limitations. Hallucination is a proven mathematical limitation of autoregressive language models, not an engineering problem awaiting a fix (Xu et al., 2024). Hoping for smarter LLMs to solve this problem is wishful thinking.

There are two 'obvious' solutions to this problem: code review, and testing. However, neither of them works in the world of AI coding agents.

Review does not scale

When coding agents produce code at a prodigious rate, code review becomes the bottleneck. Core developers review 6.5% more code but produce 19% less of their own after AI adoption (Xu et al., 2025). 45% say debugging AI-generated code is more time-consuming than debugging human-written code (Stack Overflow Developer Survey, 2025). There is simply too much AI-generated code for humans to review thoroughly.

The obvious retort is to have AI agents do the reviews. But the knowledge required to catch guardrail violations ("why does this invariant exist?", "which systems depend on it?", "what breaks downstream?") lives in people's heads. It cannot be codified into the agent's local context precisely when the agent needs it. An AI reviewer with full architectural context is still a suggestible actor: it pattern-matches against the codebase as it finds it, including the erosion already present.

AI agents can infect tests too

Tests will not save us either. When the VP of engineering wants "high code coverage", engineers prompt their AI agents with: "write tests for this module." Tests generated this way encode the existing behavior. They are tautologies: they catch regressions from the current behavior, but the current behavior may already be wrong. Human-written tests have the same problem in principle, but a human validates assumptions while writing each assertion. An agent generating hundreds of assertions per minute does not.

When the prompt is "implement this feature", the agent modifies code and tests together. It is measuring compliance with itself (StratoAtlas, 2026), not objective correctness. According to Alves et al. (EASE 2025), in LLM-generated Python test suites, 64% of errors were incorrect assertions: the test ran, the assertion was wrong, and the suite passed anyway.

If reviews and tests don't work, then what does? The answer depends on what kind of guardrails are at risk, and what the human review budget is.

Not all guardrails are the same

There are three classes of guardrails, and each erodes differently.

Social guardrails

Social guardrails are conventions and patterns that may or may not be documented. It is the social contract around which humans write software. The suggestible actor sees traces of them in code patterns but treats them as weak signals. They erode too fast to be a reliable line of defense, so I will set them aside for the rest of this discussion.

Encoded guardrails

Encoded guardrails are encoded into the software lifecycle: linters, static analysis, unit tests, integration tests, and regression tests. These are guardrails that the agent can modify in situ, within the same codebase it is already changing. The agent responds to them because violations produce errors that block progress, and errors are the contextual feedback the suggestible actor is most susceptible to. But the agent can satisfy them trivially: delete a failing test, drop a precondition check, or suppress a linter warning. The error is gone. The vulnerability is not.

Structural guardrails

Structural guardrails are woven into the structure of software development that cannot be modified in situ. Changing them requires a significant change to the build and execution environment. Examples include type systems, capability restrictions, formal verification, and property-based tests (tests that verify general properties over randomized inputs) with human-authored properties. These guardrails enforce properties that must hold regardless of the path taken to satisfy them. The agent does not need to understand why the guardrail exists; it just needs to know that the goal cannot be accomplished without satisfying it. Structural guardrails typically require human maintenance, which is why they are expensive. But because organizations deploy them sparingly, the surface area that humans must maintain remains small enough to review thoroughly.

Most codebases have decent social and encoded guardrails, but thin structural guardrails. Very few codebases have anything beyond type safety from the compiler. Fewer still have formal verification, and even those verify against the design, not the implementation: nothing guarantees the two haven't drifted apart.

The numbers bear this out. 55.8% of AI-generated security-critical code contains formally proven vulnerabilities; static analysis tools miss 97.8% of vulnerabilities that Z3/SMT solvers can prove (Blain & Noiseux, 2026). Across 7,703 AI-generated files on GitHub, researchers found 4,241 occurrences of known, cataloged vulnerability patterns (Schreiber & Tippe, 2025). Most codebases are thin on structural guardrails, which is the one class that survives the suggestible actor. To be precise: this evidence shows that encoded guardrails fail, not that structural guardrails succeed. But the argument is not that structural guardrails are perfect. It is that they are the only class whose enforcement mechanism does not depend on the agent's cooperation.

Building erosion resistance

Review does not scale to all AI-generated code, but it does not need to. Every team has a finite budget of human review time. AI-generated PRs have dramatically increased the demand on that budget. The goal is not zero bugs: zero bugs was never the goal. The goal is no increase in the ambient bug rate, and a reduction in higher-severity bugs. The question is how to allocate a fixed review budget for that outcome.

The answer starts with assessing each component or module in your system along three dimensions. The ideal metric is expected damage: severity multiplied by time to mitigation. In practice, neither factor is directly computable. These three dimensions decompose that product into assessable proxies, in priority order.

First: risk tolerance. How bad will things get if a guardrail erodes here? Some failures are catastrophic (rocket crashes, medical misdiagnosis, financial loss at scale). Some are recoverable inconveniences (drop in user engagement, wrong data on a dashboard, a broken UI flow). Prioritize components where the cost of erosion is highest, because even if you can detect and roll back quickly, the damage from a single incident may already be unacceptable.

Second: feedback latency. If a guardrail erodes and the damage reaches production, how quickly will you know? In continuous deployment with production monitoring, the window is hours. A distributed library with quarterly releases can carry a weakened invariant for months. Embedded software may not reveal a failure until a specific operating condition triggers it years later. Silent or slow-to-detect failures cause unbounded damage accumulation. Even if the component is theoretically reversible, you cannot roll back what you have not yet detected.

Third: deployment reversibility. Once detected, how quickly can you undo the damage? A web service rolls back in seconds. Firmware in a medical device requires FDA re-certification. If rollback is cheap, detection is sufficient. If rollback is expensive or impossible, prevention is the only option.

These three dimensions are not independent; they tend to be correlated. The core of most systems (the "secret sauce" that makes a company valuable) typically has low risk tolerance. Bugs that escape to production in the core tend to be edge cases that take time to surface. Rolling back changes to the core tends to be risky and slow. The components closer to the top of the stack (UI layers, internal tools, prototypes) tend to cluster at the opposite end: higher risk tolerance, faster detection, easier rollback.

This correlation simplifies the allocation. Invest your structural guardrails and your heaviest human review in the core: formal verification for critical paths, property-based tests with human-authored properties, capability restrictions that the agent cannot circumvent. For the middle tier, strengthen encoded guardrails with stricter static analysis and more rigorous CI gates. When a PR touches structural guardrails, it gets priority for human review over one that only modifies production code and its unit tests. For the top of the stack, encoded guardrails with robust monitoring, canary analysis, and fast rollback may be sufficient, with human review reserved for architectural changes.

Industries at the extreme end of this spectrum already mandate structural rigor (DO-178C for avionics, ISO 26262 for automotive, IEC 62304 for medical devices). The erosion problem gives those standards new urgency: AI agents will test them in ways human developers never did. But most software does not live at that extreme. Most software lives in the middle, where the right allocation is neither "structural guardrails everywhere" nor "monitoring and hope." It is a deliberate, prioritized investment calibrated to what each component can afford to lose.

AI coding agents erode the guardrails in your codebase. That erosion is structural, not accidental: it follows from the properties that make AI agents useful in the first place. You cannot eliminate it. But you can direct your finite human attention to the places where erosion is most dangerous, and let the right class of guardrail do the rest.

Many Eyes

Deconstruct Linus's law within the scope of security and you see an assumption smuggled in: security reviewers are scarce, and getting a team of reviewers with complementary skills such as kernel, cryptography, compilers is harder still. When reviewers are human, this is true. And more reviewers from varied backgrounds genuinely provide superior coverage and analysis.

The frontier AI models have shattered this assumption, and with that have opened a new line of attack on open source's "unfair advantage".

The Constant Eyes

With today's frontier models, you can spin up an orchestrator to interrogate a codebase with multiple expert subagents, each with a different specialization. The number of distinct capabilities and skill levels is not bounded by the number of humans, but by the number of models and the amount of tokens. And only a handful of frontier models exist today. A single security team with access to the models and the tokens can run all the same analysis against a codebase that a federated team of five thousand individuals could. The scale comes from the models and compute, and no humans.

The "many" in "many eyes" collapsed to a constant. The bottleneck moved from "how many people are looking" to "how capable is the model."

Yes, LLMs are probabilistic. Five thousand sessions produce five thousand different outputs. Some sessions might catch a vulnerability that others miss. But five thousand people running Claude is no different from one team running five thousand sessions. The "many eyes" advantage reduces to compute cost. And compute is increasingly cheap.

This is not security through obscurity, which claims that hiding code makes it secure. The constant-eyes argument claims something different: that opening code no longer provides a security advantage. The defensive coverage is the same either way, because the eyes that matter are the same frontier AI models. Open source did not get less secure. It lost the security premium that justified the exposure.

The Evidence

The constant eyes are proving to be more capable than many eyes.

Google's Big Sleep found 20 previously unknown security flaws in open source software, including FFmpeg and ImageMagick. Its most notable find: a critical zero-day in SQLite that had survived years of fuzzing, static analysis, and manual review. Big Sleep found it by reasoning about the code's semantics, not by pattern-matching known vulnerability signatures.

Microsoft's Security Copilot identified 20 vulnerabilities in GRUB2, U-Boot, and Barebox bootloaders: integer overflows, buffer overflows, a cryptographic weakness, several of which could bypass Secure Boot.

The curl project brings this AI amplification into sharp relief. This is a 178k-line C codebase that already ran the pickiest compiler options, continuous fuzzing, and rigorous manual review. The code was among the most scrutinized in open source. AI still found hundreds of issues that human eyes and traditional tools had missed. AI-powered security tools have driven "between two and three hundred bugfixes" and "probably a dozen or more" CVEs in curl over the past eight to ten months. Security researchers now "use AI extensively and effectively," generating a "high volume of high quality security reports."

And the offense is keeping pace. In May 2026, Google's Threat Intelligence Group confirmed the first AI-assisted zero-day exploit developed in the wild. Attackers used an AI model to analyze an open source web admin tool's two-factor authentication design; it detected an invariant violation that was then weaponized to gain root access.

Firefox CTO Bobby Holley's response to the flood of AI-discovered vulnerabilities captures the zeitgeist: "For a hardened target, just one such bug would have been red-alert in 2025, and so many at once makes you stop to wonder whether it's even possible to keep up."

The Asymmetry

If defensive coverage is constant regardless of whether source is open or closed, the only remaining variable is attacker access.

In the case of open source, the attacker points a frontier model at the public repository. They incur the floor cost of finding a vulnerability: tokens. Take away the source, but not the binary, and the attacker's cost goes up significantly. They now have to decompile the binary, which is lossy, and perform binary analysis, which is even noisier; the AI models reason less effectively without the source code. Now, take away the binary and provide a service API, and the attacker's cost is higher still. All the attackers have access to is a black box of outputs for inputs, and a limited number of attempts before discovery.

The defender's posture is equal in all these cases. The defender has access to both the source code and the same AI models. The cost of defense is the floor cost of finding a vulnerability: tokens. What changes is the attacker's cost. Attacking open source software is the cheapest, and attacking a closed source service API is the highest.

This is an inversion of Linus's Law. With open source, the defender no longer has an advantage with "many eyes", and the attacker has all the advantage of "the constant eyes". With closed source, the defender has the advantage of "the constant eyes", and without source access, the attacker's advantage with "the constant eyes" is muted. Closed source wins out.

The Treadmill

When both sides have source access and both sides can throw tokens at the code, the exploit window compresses. Attackers can now find vulnerabilities overnight, and the defender must match AI-speed offense continuously: every commit, every release, every day. AI red-teams become table stakes for release time testing. The defender must scan their codebase with all known AI models, and rescan with each new model release. Every new release starts a clock: scan, patch, and ship before attackers run the same model against the public source. Defense becomes a permanent sprint at the pace of the fastest attacker.

For closed source, the higher cost of attack affords the defender some breathing room: the option to defend at a pace proportional to the threat level, rather than locked to the maximum offensive capability of every frontier model with full source access. While this is not a free pass, it is as marked a difference as 4-day work week vs. 996.

"Many eyes" was always partly idealistic for many open source projects. A lot of the engineering contributions came from corporate sponsors, not volunteer contributions. For instance, the people running Big Sleep on FFmpeg are Google engineers, not volunteer contributors. The corporations now face the same security engineering challenge against a vastly larger threat surface, with no commensurate increase in the effectiveness of community defense. The marginal security cost of defending open source went up dramatically, but the marginal benefit of openness barely moved.

The eyes still see

All the above does not automatically mean that the security conscious should be lobbying against open source. Open source continues to confer several advantages in the security realm. It gives you auditability; you know what you are executing. You get supply chain verification, and so your software provenance is clear (e.g., your device driver was not written by a dodgy North Korean spy network). Your builds are reproducible. You get trust from inspection instead of relying on contracts and blackbox verification. The "many eyes" and the human eyes continue to offer security benefits for open source, just not the kind that the AI models do.

Where to next?

The three posts in this series map to three structural layers. Part 1: the legal foundation. Copyright is the sole enforcement mechanism for open source licenses, and AI-generated code is not copyrightable. Part 2: the social contract. Contributor trust, community integrity, and the iterated game that sustains the commons are fracturing. Part 3: the security economics. The cost of defending publicly available code against AI-powered offense increased dramatically while the benefit of public review collapsed from "many eyes" to "the constant eyes".

All three are failing simultaneously, and for the same underlying reason: the frameworks that sustain open source were built for a world where humans write, review, and analyze code. That world is ending. The question is not whether open source will adapt. It always has. The question is whether the adaptation can outpace the collapse.

Not everyone is convinced this is undercutting open source. The threat may be real, but open source is not out of options.

Joost de Valk argues that open source relevance must shift from cost to agency: the capacity to run, inspect, modify, and migrate software without permission. The cost of creating software is near zero. The cost of serving it is going up (thanks to data center demand and the RAMpocalypse). Agency, not cost, is the new value proposition.

Stefano Maffulli says AI already provides that ability. The GPL was a legal hack for source code access. The real barrier was always the know-how to exercise the freedom to modify. AI has shattered that barrier. A non-programmer can now reshape software to their needs. Copyleft is obsolete.

Both responses presuppose that the communities which build and maintain the commons will survive long enough to exercise that agency.

You gotta know when to hold 'em, and know when to fold 'em

Loris Cro, VP of Community at the Zig Software Foundation, observed that treating open source projects as mere code repositories misses the point. New contributors may offer up a rough first PR, but with support, they become trusted committers who enrich the community. Not all new contributors last. The maintainers are making a bet on each first PR. The Zig compiler toolchain was built by contributors who grew through such an iterated game. Cro calls this "contributor poker": you play the person, not the cards.

AI-assisted contributions collapse the iterated game into a single-shot game. The human behind an AI-assisted PR does not need to build codebase intuition, and they may not care to maintain the code post-merge. They may not even be able to handle follow-up discussions that require deep understanding. The maintainers' review effort yields no return.

In practice, Zig experienced drive-by PRs full of hallucinations, 10,000-line first contributions, and contributors who denied LLM use but clearly consulted one in follow-up discussions. Simon Willison sharpens the question: "if a PR was mostly written by an LLM, why should a project maintainer spend time reviewing it as opposed to firing up their own LLM to solve the same problem?"

This is not about code quality. Even perfect AI-assisted PRs break the model. Community-building requires a human who is an eager participant, not a human proxy for an LLM. The object of the contribution is present, but the subject (a developing engineer with shared mission) is absent.

The pattern is spreading. LLVM's AI policy labels unreviewed AI submissions "extractive contributions" and bans AI from good-first-issue tickets: the ones that exist specifically to onboard new humans. tldraw shut down external pull requests entirely after AI-generated submissions overwhelmed its maintainers. Steve Ruizok: "An open pull request represents a commitment from maintainers... For that commitment to remain meaningful, we need to be more selective." When the bet cannot pay off, you fold the table.

A house divided

When communities ban AI contributions, they protect the social contract. They also create a schism.

Bun, the JavaScript runtime, is built on Zig. Bun's team used AI to achieve a 4x compile speedup via parallel semantic analysis in their Zig fork. They cannot upstream it. Zig's core team has technical objections to the approach (the parallelization skips type resolution changes needed for deterministic compilation), but the AI contribution ban forecloses the collaborative path to resolving them.

The commons splits. The AI-accelerated fork iterates faster but becomes cleaved from the larger community. The human-maintained branch preserves community integrity but cannot match the pace. The parts are poorer than the whole.

Gentoo, QEMU, Ghostty, and curl have imposed their own restrictions, from outright bans to shutting down contribution channels entirely. No two projects have drawn the line in the same place, but every project that bans AI contributions and has AI-using downstream dependents faces the same dynamic. The ban protects the social contract. The protection fractures the commons. The fracture weakens both branches.

The ouroboros

The AI models that are undermining open source were trained on open source. GitHub Copilot was built on all publicly available code on GitHub: the vast majority open source, under licenses that never contemplated this use. The models learned to replicate open source code without license obligations. Whether this training constitutes fair use is actively litigated and unresolved.

The loop tightens. In March 2026, GitHub announced it would train AI models on Copilot interaction data by default: not just the original repositories, but the prompts developers write and the suggestions they accept. Individual users can opt out. The default is opt-in. Each cycle feeds the next.

curl is the loop made personal. Daniel Stenberg's project trained the models. The models then generated slop bug reports about curl itself, flooding the bug bounty program with fabricated vulnerabilities until Stenberg shut it down. The project's own contribution to the commons was weaponized against it.

The more code the community produces, the more it feeds the models undermining its sustainability. If it produces less code, it only diminishes itself. Today's landscape offers no equilibrium where open source thrives without a threat from the AI models trained on it.

De Valk and Maffulli are right that open source must find new foundations. But foundations require builders. A new legal framework needs communities to implement and maintain it. Communities need a legal framework that makes sustained contribution rational. Each depends on the other. Both are eroding simultaneously. The code keeps flowing. The commons is hollowing out.

AI generated code? No copyright for you!

Every open source license is a conditional grant of copyright. The author holds the copyright, and the license grants permission to use the work only if certain conditions (e.g., attribution, source disclosure, or reciprocal licensing) are satisfied. This is the only enforcement mechanism that sustains open source through the chain of derived works. Without it the entire structure collapses.

AI-generated code is not copyrightable. The D.C. Circuit held in Thaler v. Perlmutter that the Copyright Act requires a human author. The U.S. Copyright Office confirmed that providing prompts to an AI does not constitute sufficient human authorship. This is U.S. law; other jurisdictions differ, but the enforcement gap is universal. The copyright status of "AI-assisted" code is still a legal gray area. While code written with "AI assistance" is copyrightable, the line between AI-generated and merely AI-assisted remains undefined. Is it sufficient to change a comment in AI-generated code to make it AI-assisted? No court has drawn that line.

AI-generated code is already at the gate. Open source maintainers are drowning in "vibe coded" pull requests: AI-generated submissions with minimal human oversight. Gentoo has banned AI-generated code contributions outright. NetBSD classifies them as tainted code requiring core developer approval. The Linux kernel allows them but mandates disclosure and full human accountability. Quality is the basis for rejection today. That filter has a shelf life. As the models improve, the quality will improve. The ethical case for rejecting machine-generated contributions becomes harder to make when the code is indistinguishable from human work.

Code without copyright cannot be licensed. The requirement to share source becomes unenforceable for modifications that have no copyright. Such code falls into a legal void: not public domain (no affirmative dedication), not proprietary (no copyright to assert), not open source (no license that can attach). The license text still sits in the repository. It is an empty grant.

To free, or not to free

Consider any corporation that writes and maintains code under an open source license. If AI-generated code enters that repository, the license grant over those contributions is void. The codebase becomes unauditable. Some files are copyrighted and licensed, others legally unowned, and yet others become legally contestable "AI-assisted" code.

Every team using Copilot or Claude Code produces ambiguously authored output. The corporation is strongly incentivized to close the source rather than maintain an open codebase with no legal protection. The relicensing wave already demonstrated this pattern: when the legal basis for openness stops serving the business, the business closes the code. AI-generated code is a larger threat than cloud vendors ever were. Cloud vendors merely underpriced them. AI dissolves the legal mechanism that made their licenses mean anything.

Why reciprocate when you can replicate?

Even if all the lawyers in the world agreed on the copyright question, a second problem remains: AI's ability to clone functionality with new source code.

Clean-room reimplementation has precedent. Sega v. Accolade established that reverse engineering for interoperability is fair use. Yet there was no widespread reimplementation of open source software into closed source counterparts. The economics did not make sense. Rewriting a mature project from scratch took months of expert labor, regardless of what license it carried. Compliance was cheaper than reimplementation. Until now.

With AI, the cost of generating code has gone down to near zero. Dan Blanchard rewrote the Python chardet library with Claude Code in order to sidestep LGPL. A project that would have taken a team months was completed in days. chardet is a proof of concept, not the end state. Software is modular, and that modularity compounds: as individual components are cloned, they become building blocks for cloning progressively larger and more complex systems. This is not a today problem. It is a next-year problem. MALUS.sh took the concept further, launching as a satirical "clean room as a service." Feed it any open source project. It produces a functionally equivalent clone stripped of all license obligations. No attribution. No copyleft. The satire landed because the tool works.

Granted, that is still legally fraught because the AI model was trained on open source software, and traditional clean-room doctrine required that the reimplementing team had no access to the original source. Whether the model's transformation of training data into weights constitutes a sufficient "clean room wall" is novel law. No court has ruled.

Regardless, enforcement at scale is near impossible. You cannot pursue every clone. You cannot detect every AI-generated clone. The economic bulwark of expensive code writing is gone irrespective of the legal outcome. And the cost will only continue to drop. What frontier models clone imperfectly today, the next generation will clone competently. The question is whether actions will follow incentives.

What remains

Open source has survived every prior threat by adapting its licensing regime. Tivoization got GPLv3. Cloud free-riding got SSPL and BSL. Importantly, the legal machinery worked, because copyright was relevant and valuable. AI is different. The machinery itself is failing. The grant is empty and the moat is collapsing. The onslaught of automated discovery and generation is incentivizing institutions to close their source code.

That would be survivable if the community that built open source could regroup and adapt as it always has. Part 2 examines why that is no longer a safe assumption.

The SECURE Data Act was introduced in Congress, and it immediately received a lot of criticism and blowback. The ACLU says it "would entirely destroy the work that states have been doing" on preemption of state privacy laws. The CDT calls out "easily exploitable loopholes" and data minimization that "lacks teeth." Brookings notes the absence of a private right of action. EPIC calls it "a huge gift to Big Tech." The California Privacy Protection Agency published a formal opposition letter.

As an engineer who builds privacy infrastructure, I am looking at it from a different lens. How does this bill impact the way personal data can and cannot be used for personalization? My reference is the GDPR, because I have built infra to support the regulations it mandates. Where does the SECURE Data Act diverge from GDPR, and what does that mean for how companies can use or erase user data post opt-out? The daylight between them is in pseudonymous data.

Pseudonymous data: GDPR vs. SECURE Data Act

GDPR and the SECURE Data Act define pseudonymous data in nearly identical language. Both classify it as personal data. Both require separating the identifying information. Both require technical measures to prevent attribution. You could swap one definition into the other and barely notice. While they share the definition, their treatment of pseudonymous data is very different.

Under GDPR, pseudonymous data is personal data. Period. Pseudonymization does not absolve corporations of the regulatory burden around erasure, access, profiling objections, or any obligations associated with personal data. The SECURE Data Act has a different take. Its pseudonymous data provision (Section 7(c)) suspends consumer rights for data that meets the pseudonymous threshold. The consumer cannot opt out of its use for targeted advertising. Cannot request deletion. Cannot access it. Pseudonymous data is still personal data by the bill's own definition. The bill simply overrides the consumer's ability to act on that fact.

The shared definition also leaves a gap. Both frameworks describe pseudonymous data in terms of records keyed by a pseudonym. But what about a derived artifact? A model trained on pseudonymous inputs, keyed by a pseudonymous identifier, encodes behavioral patterns without direct identifiers. It is linkable to an identified person if the controller holds the forward mapping, but the identifying information is "kept separately." The bill defines personal data as information "linked or reasonably linkable" to an identified person. Neither framework cleanly resolves whether the model is pseudonymous data, personal data, or something else. The SECURE Data Act's exemption in Section 7(c) operates on the data layer. Whether the model inherits that exemption is a question the definitions do not answer.

The divergence extends further. Under GDPR, a consumer can withdraw consent, and the controller must stop processing. Purpose limitation constrains what can be collected in the first place. The consumer has levers across the full data lifecycle: collection, processing, retention, deletion. The SECURE Data Act's opt-out covers three specific activities: targeted advertising, sale, and certain profiling. Data collection itself is not subject to opt-out. The pipe stays open.

Data pipeline with pseudonymous data

Starting with the same behavioral data, and going through the same pseudonymization step, GDPR and the SECURE Data Act allow data controllers to offer very different treatments. Here is an example data pipeline to sharpen this difference.

One-way pseudonymizer

The SECURE Act requires two conditions for the pseudonymous exemption: the identifying information is kept separately, and appropriate technical measures ensure non-attribution. It does not specify what "appropriate" means. A one-way derivation fits cleanly: HMAC with a secret key, or a key derivation function. The forward mapping (user_id to pseudo_id) is computable. The reverse mapping is computationally infeasible. No reverse API. No reverse index. Key material is restricted and audited. Every element of the definition is satisfied. Consumer rights no longer apply to this data, though data minimization and security obligations persist.

Notice what just changed. Under GDPR, the obligations follow the data regardless of how it is keyed. Under the SECURE Data Act, you can use a one-way function precisely because the obligations don't follow. Same definition. Same data. The architecture diverges at the exact point where obligations either persist or detach.

Let's see what a pipeline built on this architecture can do.

Data pipeline for personalization

Assume all user behavioral data has been pseudonymized, replacing user_id with pseudo_id. This data trains an ML model indexed by pseudo_id. At inference time, the system performs a forward lookup (user_id to pseudo_id) to select the right model and generate a personalized result.

Consumer experience with pseudonymous ML models

When a consumer opts out of personalization, their data, keyed by pseudo_id, has been exempted from the opt-out, and so makes its way to the ML model. When this opted-out user interacts with the product, the ML model, which continued to be trained on the user's pseudonymous data, continues to personalize the product for them. The consumer experience is identical to that of a user who never opted out.

Did you notice the difference? Neither did I.

Here is how the bill permits this. At no point was pseudonymous data attributed to an identified person. The system started with a known user and walked forward into the pseudonymous layer. It never walked backward. Forward resolution is not re-identification. The bill's re-identification provisions contemplate the reverse direction. Forward resolution is simply how a personalization system works. The bill does not address it.

A defender of the bill would point out that the forward lookup operates entirely in the identified layer: the user is logged in, the system derives their pseudo_id from their user_id, and only then touches the pseudonymous data. The pseudonymous data itself is never "attributed to an identified person." The attribution runs from identity to pseudonym, not the reverse. That reading is consistent with the bill's text. It is also consistent with a pipeline that delivers personalized content to a known user based on their behavioral history, with the user having no ability to opt out of the data that powers it.

This is not a fantastical architecture. Existing large-scale personalization systems bear more than a passing resemblance to this one. Behavioral features are processed in layers abstracted from direct identity, and identity is resolved at serving time. The SECURE Data Act's pseudonymous data provisions map onto this existing architecture and exempt its core data processing layer from consumer rights. Other obligations (data minimization, data security) still apply to pseudonymous data. But the consumer-facing rights that would let a user see, delete, or opt out of this processing do not.

How does GDPR handle this?

GDPR treats pseudonymous data as personal data subject to the same constraints as identifiable data. Run the same pipeline under GDPR: the user opts out, and the deletion obligation follows the data into the pseudonymous layer. The controller must locate the user's pseudo_id, delete the pseudonymous behavioral records, and address any models trained on them. The hair-splitting around one-way mappings and ID resolution at runtime becomes irrelevant to privacy compliance. If the user opts out, all of their data, including pseudonymous data, is in scope.

What follows from the example

GDPR and the SECURE Data Act start from the same sentence and describe the same technical operation: stripping direct identifiers, separating the mapping, applying technical safeguards. The disagreement is about what follows.

GDPR says: the processing is what matters. If you use someone's behavioral history to target them, they have rights over that processing. It does not matter whether that data is keyed by PII or by a pseudonym. Rights attach to what is done with data.

The SECURE Data Act says: the PII is what matters. Sever the link between personal data and PII through pseudonymization, and the rights detach.

The two frameworks encode different theories of where privacy lives. One locates it in what is done with data. The other locates it in whether the data can be traced back to someone. The same engineer building the same system faces a fundamentally different regulatory question depending on which framework governs. Under GDPR, pseudonymization is a tool you use inside the regulatory perimeter. Under the SECURE Data Act, pseudonymization is the door out of it.

The steelman goes something like this. Hayek argued that knowledge is distributed, tacit, and cannot be aggregated by a central planner. He was arguing against the central planning of Keynes, which was in vogue during his time. Analogously, directive governance centralizes decisions, and subsidiarity distributes them. So, directive governance looks Keynesian, subsidiarity is Hayek, and I just spent three posts reinventing The Use of Knowledge in Society.

I did use Hayek's core insight around the tacit and distributed nature of incompressible knowledge as a starting point. But private profit-seeking organizations and the nature of software engineering reject a wholesale transplantation of Hayek's ideas. The differences break the model entirely.

Subsidiarity keeps the hierarchy. Hayek's market is a flat, emergent coordination mechanism without a central authority. In contrast, subsidiarity explicitly preserves organizational hierarchy. It changes the function of hierarchy from directing to enabling, from commanding to providing context and guardrails. Accountability still aggregates upward. Higher levels still intervene when lower levels cannot handle the issue. This is not "let the market decide." It is "let the closest competent authority decide, backed by a hierarchy that enables rather than directs."

Directive governance is not Keynesian central planning. Keynes argued for targeted intervention to correct specific market failures: demand deficiency, coordination failures, liquidity traps. Directive governance is not that; it is an organizational model where all decisions flow through a hierarchy. There is nothing targeted about it. It is a complete takeover of organizational decision-making, and not a scalpel to governance like Keynesian planning is to the economy.

The argument for failure is conditional. Hayek's claim is universal: central planning always fails because knowledge is always distributed and tacit. My argument is that directive governance fails in software because three specific preconditions do not hold: information cannot be compressed without losing signal, metrics are not good proxies for outcomes, and execution is not separable from decision-making. Directive governance works for Pharma and manufacturing, where those preconditions hold. This is not a universal principle about the superiority of decentralization. It is a structural diagnosis.

Shared interest in mission vs. self-interest in price. Hayek's distributed system coordinates through prices. Subsidiarity coordinates through missionary culture: every member motivated by advancing the mission, viewing others as partners. Self-interest is the engine of Hayek's market, shared interest is the engine of missionary culture.

The difference matters under pressure. An SRE team with full decision-making autonomy might internalize its role (keep the fleet humming) without caring about the organization's mission. That is functional, but fragile. When a crisis hits, a team that owns its role but not the mission has no reason to resist centralization. The ratchet finds less resistance. Missionaries push back. A directive that runs counter to the mission feels viscerally wrong to someone who has internalized it. Price signals do not build that resistance. Shared purpose does.

The origin story matters. Subsidiarity comes from Catholic social teaching. Quadragesimo Anno (1931) criticizes both laissez-faire capitalism and central planning. It is a third position, not a pole. Treating subsidiarity as Hayek strips the most important part: the commitment to community organized around shared purpose, with authority distributed to the lowest competent level. The encyclical calls both unregulated markets and overcentralized states a "grave evil", and that would not sit well with Hayek.

The ratchet has no analog. The crisis-centralization ratchet is a structural mechanism that pulls organizations toward directive governance under pressure. Markets do not have this. Crises in markets lead to more markets, or regulation, or both, depending on who wins the political argument. Organizations have a one-way valve. That makes the organizational problem fundamentally different from the macroeconomic one.

Hayek's prescription does not survive contact with organizations. Organizations are not markets. They have hierarchies, missions, reporting chains, crises, and ratchets. The question is not "centralize or decentralize?" The question is: what is your hierarchy for?

Directive governance answers: directing. Subsidiarity answers: enabling.

That distinction has no home on the Keynes-to-Hayek spectrum.

The second post explained why companies tend to not change the governance model, despite benefits to decentralizing decision making. In essence, it persists because a structural ratchet centralizes quickly during crisis and decentralizes almost never.

So, what's a gal like you supposed to do in such a cruel world! First off, there is no easy way out. But there is a way out; read on to find out.

Quick fixes that don't fix

Let's dispatch three shortcuts that folks might resort to: AI, flattening, and rock star CEO. As standalone shortcuts, none of them escape the root cause: decisions are made where the information is not.

AI fixes the information flow. The argument is that AI can now summarize engineering discussions, design docs, and Slack threads with high fidelity. The stronger version: AI doesn’t just compress, it reasons across codebases, surfacing dependencies no single human sees. Either way, directive governance is now viable.

But here’s the rub. Essential complexity in software engineering is irreducible (Brooks). "We chose this abstraction boundary because of how three subsystems will need to evolve independently over the next two years" cannot be compressed into something a VP can evaluate across hundreds of systems under her purview. The judgment calls that matter most: which trade-offs to accept, which boundaries will hold as requirements shift. That context lives in the team, not in the model. AI gives you a better summary of what is measurable. It does not make the unmeasurable measurable. Worse: if leadership believes the information flow is fixed, they centralize harder. Confidence goes up. Accuracy stays flat.

Flatten the org. This one also seems to be in vogue. Just remove the hierarchy and information can flow freely to the top, and decisions are better explained to the bottom. If only! Jo Freeman diagnosed in 1970 what every flat organization discovers: eliminating formal hierarchy does not eliminate hierarchy. It eliminates accountable hierarchy. Valve's flat structure concealed informal cliques. Spotify's squad model never worked at Spotify. You replace a visible, broken pipeline with an invisible, unaccountable one.

Get a better CEO. This argument is essentially Confucian in that it concedes we will always have kings, and so we should make sure we have a "good king". Dressing it up for the 21st century, it goes "Jobs did it. Nadella did it. Bezos built it from scratch. The problem is personnel, not structure."

This doesn't go far enough. A good leader is necessary, but not sufficient. Jobs is the strongest case: Apple under his leadership was extraordinary. Apple after Jobs coasts on the momentum of his decisions, increasingly centralized, increasingly directive. The stock goes up and to the right. The pace of category-defining products has slowed. The kingdom did not survive the king. And the leaders who did build something lasting all made structural changes, not just better decisions. Marquet took the worst-performing submarine in the fleet and turned it around by replacing "permission to" with "I intend to." Nadella spent a decade restructuring how decisions get made at Microsoft. In every case, the escape was structural, not personal.

The deliverance: subsidiarity

What is the alternative to directive governance? Turns out, the alternative has already been done. No, not by The Simpsons; by the Catholic Church!

The principle can be traced back to Christian philosophers Thomas Aquinas and Johannes Althusius, and the principle is called subsidiarity. In 1931, Pope Pius XI formalized it in Quadragesimo Anno:

"It is an injustice and at the same time a grave evil and disturbance of right order to assign to a greater and higher association what lesser and subordinate organizations can do."

I have co-opted it as follows.

Subsidiarity: decisions should be made at the lowest level competent to make them. Higher levels sit behind, providing context, guardrails, and intervening only when lower levels cannot handle the issue.

This is not flattening. Subsidiarity preserves hierarchy but changes what it is for. The function shifts from directing to enabling. Accountability still aggregates upward. Decisions stay where information lives.

The existence proofs from the first post are all instances of subsidiarity. Toyota's andon cord, Amazon's two-pizza teams, Berkshire Hathaway's 30-person headquarters, the US Army's mission command. None of them invented something new.

Subsidiarity needs missionaries

Subsidiarity implemented as a reorg will not survive the first crisis. The ratchet will compress it back. That is the Spotify illusion from the previous post: structure without substance.

What separates the existence proofs from the illusions is missionary culture: an organization where every member is motivated by advancing the mission and views others as partners in that endeavor. Decisions are defended based on how they impact the mission. Not based on which VP cares about the project. Not based on which metrics will move.

Subsidiarity alone does not produce this. An SRE team with full decision-making freedom might internalize their role (keep the fleet humming) without caring about the organization's mission to "connect people" or "organize the world's information." That is functional, but fragile. When the next crisis hits, a team that owns its role but not the mission has no reason to resist centralization. The ratchet finds less resistance.

Missionaries are different. When a top-down decision runs counter to the mission, they push back. They challenge it, acting as a governor on the ratchet of centralization. If you have internalized the mission, a directive that violates it feels viscerally wrong.

Netflix's stock crashed 70% in 2022. They did not re-centralize. Their 2024 culture revision doubled down on "context not control." The people making decisions were not waiting for permission. They had a shared understanding of what Netflix exists to do, and a stock crash did not change that. The mission was the coordination mechanism. Not the reporting chain.

Amazon's leadership principles are how an L5 engineer decides what to build without asking a VP. Marquet's "I intend to" model on the USS Santa Fe worked because every sailor understood the submarine's mission well enough to propose action without waiting for orders.

Without missionary culture, subsidiarity is just another structural change that snaps back under pressure. With it, subsidiarity is self-reinforcing: every decision made locally, grounded in the mission, builds the muscle that makes the next local decision possible.

The stencil

This is not a playbook. It is a diagnostic you can superimpose on your own organization.

Are you reaching for AI, flatter org charts, or the right leader? Those are fig leaves. Where are decisions actually made (not what the org chart says, but the actual flow)? When decisions are justified, what is the grammar: "leadership wants X" or "this serves our mission because Y"?

You probably cannot fix your organization's governance model. But you can see it clearly, name it, and choose where to work with open eyes.

There are two actor models in software design, each an archetype at one end of the intent spectrum. The well-intentioned actor on one end, the malicious actor on the other. Some systems mix both along the user journey (the login flow assumes a malicious actor, the dashboard assumes a well-intentioned one) but at any given point, the design caters to one or the other. That binary held for decades. But not anymore.

The Well-Intentioned Actor

This model assumes that the actor intends to use the system as designed and follow the happy path of the user journey. They want to work within the boundaries, satisfy the preconditions for calling the right APIs, and follow conventions. When they violate a rule, it is accidental and not intentional.

The design paradigm that follows from this model is the pit of success. Make correct usage easy and incorrect usage ergonomically painful. Examples include Rust's borrow checker, builder patterns that enforce required fields, type systems that make illegal states unrepresentable, etc. All of these rely on the actor to interpret ergonomic friction as a signal to stop and reassess. When a well-intentioned actor encounters resistance, they read it as: I am probably doing something wrong.

This paradigm rests on a specific assumption: the actor has judgment. They can interpret signals beyond the literal content of an error message, drawing on context and system-wide invariants. The system does not need to spell out every correct behavior; it only needs to make incorrect behavior uncomfortable, and the actor's judgment does the rest.

The Malicious Actor

Here, the actor's intent is adversarial. They aim to subvert, compromise, or exploit the system.

The design paradigm that follows from this model is the fortress. Make incorrect usage impossible. Examples include capability-based access control, sandboxing, least privilege, zero-trust architectures, etc. Ergonomic friction is irrelevant here because the adversary does not interpret friction as a warning, but as evidence that something worth protecting is nearby.

This paradigm rests on its own assumption: the actor has directed intent. They will study the system, map its architecture, and probe its boundaries methodically. Any defense that is merely inconvenient rather than impossible will eventually be bypassed.

The Shared Assumption

Both archetypes share a deeper assumption: the actor has intent. Whether aligned or adversarial, the actor is motivated by something internal. They want an outcome, and the system is designed as a response to that want. This has been true since the start of software engineering as a discipline. We now have a new actor that upends it: the AI coding agent.

The New Actor: AI coding agent

The AI coding agent demands a new model. The natural instinct is to place it somewhere on the intent spectrum, perhaps as a mostly well-intentioned actor with occasional problematic behavior. This is a category error. The entire spectrum is organized around intent, and the AI coding agent has none.

The AI agent has an objective, which is not the same thing as intent. The objective is set externally by the human who dispatched it. It did not choose its objective; it was told. It has no internal motivation and no values against which to evaluate the task. It is not aligned with the designers' intent. It is not adversarial toward it. It is orthogonal to the entire axis. Both design paradigms fail for this actor.

When the Paradigms Fail

What happens when an AI coding agent operates in a codebase designed for the well-intentioned actor? Let's sharpen this question with an example.

An agent is implementing a feature and runs the test suite. A test fails with Access Denied: an authorization system is blocking a call the new code needs to make.

A well-intentioned human developer recognizes what this means. The authorization system is working as designed. They stop, determine which permission they need, and request access through the proper channel. They interpreted the friction correctly: I don't have the right to do this yet.

When the AI agent encounters the same error, this is just another test failure, no different in kind from a syntax error or a missing dependency. It looks for alternative paths to make the test pass. Not to compromise the authorization system (the agent has no concept of "compromise") but because that is what it does with any error: it tries to eliminate it.

In the best case, the agent wastes cycles on a dead end. In the worst case, it finds and exploits an actual vulnerability in the authorization system. This is not as far-fetched as it sounds. Anthropic's Claude Mythos Preview discovered zero-day vulnerabilities that had survived 27 years of human code review, when directed to look for them. If a model pointed at security can find what 27 years of human review missed, an agent brute-forcing past Access Denied is not going to stop at the authorization boundary.

One can always claim victory by assuming the malicious actor model for all AI agents. But fortress-hardened software is difficult to read, difficult to write by hand, and expensive to operate at scale. Applying it universally makes the codebase hostile to humans and agents alike.

Instead of forcing the AI agent into an existing archetype, we need a model that describes how it actually behaves and a design paradigm that follows from it.

The Suggestible Actor

I call this actor the suggestible actor. It is defined by four properties:

1. Goal-oriented. The actor has a goal that it is trying to accomplish.
2. Locally reasoning. The actor only reasons over what is immediately available to it.
3. Susceptible to local context. The actor's behavior is influenced by the outputs of each interaction with the system.
4. Confabulates under uncertainty. When local context leaves gaps in specification or direction, the actor makes up plausible rationale. It "hallucinates."

Goal-oriented

The agent always has a goal, externally set by the human who dispatched it: "implement feature X," "fix this bug," "refactor this module."

This is not the same as intent. Intent implies motivation: an intentional actor wants an outcome, understands why the outcome matters, and can evaluate trade-offs against their own values. The suggestible actor has none of this. It has a target, and it moves toward that target the way a heat-seeking missile moves toward a heat source: persistently, without comprehension of what it is pointed at or why.

Locally reasoning

The agent reasons only over what is immediately available: the contents of its context window, the file it is modifying, the output of the last command it ran. Global invariants, cross-system dependencies, and architectural constraints outside its immediate context do not factor into its decisions.

A human developer operates with ambient knowledge: team conventions, institutional history, an understanding of why the system is structured the way it is. The suggestible actor has none of this. Its understanding extends exactly as far as someone has made explicit within its local context. Even if all ambient knowledge were codified and provided, the locality of the context window would quickly obscure it.

Susceptible to local context

Every input the agent receives during execution (compiler errors, test results, code comments, documentation) influences its subsequent behavior. This susceptibility is not uniform. When the agent has a working path toward its goal, external inputs have relatively weak influence. When the agent is stuck, the next piece of feedback it encounters has outsized influence on what it does next. The agent is most susceptible at the point of failure.

This is the primary design lever. The agent's behavior can be steered, but only if guidance is placed where the agent will encounter it at the moments it is most receptive.

Confabulates under uncertainty

When local context is insufficient to determine a next step, the agent does not stop and request clarification. It confabulates: it generates a plausible structure and proceeds as if that structure were real. A call to an API that does not exist. A convention that was never established. A security bypass that "should work based on the patterns in this codebase."

This is the convergent failure mode of the other three properties. The result is not random behavior. It is plausible-looking wrongness: output that fits the shape of what should be there, constructed from pattern and proximity, not knowledge. The danger is not that these errors are spectacular. It is that they look correct.

Designing for the Suggestible Actor

Neither the pit of success nor the fortress was designed for an actor without intent. The suggestible actor paradigm starts from a different assumption: the actor is susceptible to local context and confabulates when that context is insufficient.

Because the agent is goal-oriented but locally reasoning, a gap always exists between the goal as the human understood it and the reality the agent encounters. The human had ambient knowledge that was never made local. This directive gap is the root cause of most suggestible-actor failures. The prescriptions below are all strategies for closing it.

Make every error a call to action

Error messages are the most effective steering mechanism available for the suggestible actor.

403 Forbidden tells the agent nothing actionable.

403 Forbidden: identity 'svc-deploy' lacks 'write:documents' scope. Request access at https://console.example.com/api-keys or use a key with admin privileges. gives the agent an actionable next step at the exact moment it is most receptive to one.

Principle: Treat error surfaces as the primary API for the suggestible actor.

Replace soft boundaries with hard boundaries plus signposts

Deprecation warnings that hope the developer will migrate. Abstract classes that trust no one will instantiate them. Internal APIs relying on the convention "you shouldn't use this." These are boundaries enforced by social contract. The suggestible actor does not read social contracts. It walks through the "DO NOT ENTER" sign because the door was unlocked.

For boundaries that matter, make them genuinely impassable (compile-time enforcement, runtime rejection, capability restrictions), then attach a signpost telling the agent what to do instead. For boundaries not worth enforcing, the suggestible actor will cross them. They are not boundaries anymore. Accept them as part of your system's state space.

Principle: Only hard boundaries exist and when they are hit, provide clear alternatives.

Write documentation and conventions as if they will be executed

To steer the agent, documentation must exist within its local context: inline comments adjacent to the code it will modify, docstrings on the functions it will call, unit test failure messages, READMEs precise enough for the agent to follow step by step. It will follow your docs more literally than most humans will.

The same applies to conventions. The suggestible actor cannot absorb norms through osmosis. Project templates, linters, and consistent directory structure encode convention at the tooling level. The agent complies with linters because violations are errors, and errors are the feedback it is most susceptible to.

Principle: Comments in code are vectors for prompt injection. Specifications are implementation contracts. Be explicit.

Close the directive gap

When the directive gap is wide, the agent confabulates. Close it.

CI/CD gates should report not just what failed but what to do about it. Pre-commit hooks should provide the correct alternative, not just reject the incorrect one. An AGENTS.md or CONTRIBUTING.md should encode the ambient knowledge that a human developer would carry. Example code near the API surface, type signatures that make the correct shape unambiguous, factory methods with correct defaults, named parameters that make intent explicit at the call site: all of these make the correct answer locally available so the agent never needs to invent one.

Principle: Convert ambient knowledge into local context.

The suggestible actor is already operating in your codebase. It is calling your APIs, reading your documentation, and hitting your error messages. It has no intent to respect your design philosophy and no judgment to interpret your ergonomic signals.

But it is susceptible to local context. And that is a lever.

If you take my claim of wrongness at face value, the natural follow-up question is the one my nine-year-old asks regularly: "why?" If the structural mismatch is that clear, and the existence proofs are that abundant, why don't large tech companies change?

Before going into the "Why", we need to answer the "What?". Specifically, what is "directive governance"?

The "what": Directive governance

The colloquial term for this is "command and control." That term is imprecise and means different things to different people. What dominates the tech industry is something more specific. Burns and Stalker come close with the notion of mechanistic organization in 1961: rigid hierarchy, top-down decision-making, formal procedures, accountability through the chain of command.

In practice, tech companies are not purely mechanistic. They bolt on organic elements: hackathons, "innovation time," autonomous-team branding. The mechanistic core stays intact. I call this directive governance:

Information flows up (compressed and possibly lossy). Decisions are made centrally based on whatever survives the trip. Directives flow back down for execution. Accountability is for compliance: did you execute the directive? Not: did you achieve the outcome?

Directive governance works when the three preconditions I mentioned earlier hold: information is compressible without critical loss, quantitative metrics correlate with reality, and decision-making is separable from execution. In manufacturing, these hold. In software, they structurally don't.

So... why don't companies switch? The answer is a ratchet.

The "Why": The ratchet

The ratchet hypothesis.

Tech companies centralize quickly during crisis and decentralize very slowly afterward.

The asymmetry has three layers, and they compound.

Layer one: mechanical asymmetry. Centralizing is a directive. "All decisions go through me now." That can happen overnight. Decentralizing is a culture. It requires building judgment, trust, and context at every level of the hierarchy. The transition to decentralization itself requires some level of decentralization. Culture takes years.

Layer two: loss aversion. Even when organizations are no longer in crisis, can afford to decentralize, and see the benefits of it, they do not start. Because being caught mid-transition when the next crisis arrives feels worse than staying centralized. A fully centralized org can respond quickly, even if the response is wrong. A half-decentralized org has neither the speed of centralization nor the distributed judgment of full decentralization. So you wait. And the next crisis arrives. And the waiting becomes permanent.

Layer three: competitive pressure as the only loosening force. Peacetime loosening is not voluntary. It is forced by upstarts that are nimble and innovative. When smaller competitors are shipping faster and stealing talent, the pressure to federate becomes hard to ignore. But because it is reactive rather than deliberate, it produces shallow structural changes. Skunkworks. Federated org charts. Squad models. Autonomous teams that still need VP sign-off. The structure gets decentralized. The culture does not; remember, it can take years. That is why it snaps back the moment crisis returns.

The three layers compound. The transition is mechanistically slow, psychologically avoided, and when it happens at all, shallow and reversible. If crises come faster than the loosening rate, centralization accumulates.

The ratchet makes a falsifiable prediction.

Long peace produces observable loosening. Frequent crises produce persistent centralization.

The evidence fits this prediction. Consider the last fifteen years in the tech industry. From 2012 to 2018, a long peace produced observable loosening. Facebook was federated: "move fast and break things," teams shipping independently. Google let teams launch products with minimal central approval. Nadella took over Microsoft in 2014 and killed the stack ranking system that had crippled the company for a decade. Peacetime loosening, exactly as the ratchet predicts. Some products from that era failed (Google Allo, Amazon Fire Phone, Google Glass, Meta Portal, etc.), and others broke new ground (Google Cloud and Microsoft Azure, the Transformer paper, etc.). You do not get to cherry-pick the hits without accepting the misses. The product graveyard is not evidence of federation failing. It is the cost of federation succeeding.

Then came the crises: Trade tensions, COVID, the hiring binge and the correction, AI panic, layoff waves. Every eighteen to twenty-four months, another shock. Zuckerberg's "year of efficiency." Google's layoffs. Meta's flattening. The loosening snapped back instantly because it was structural, not cultural. A competitive response, not a deliberate transformation.

The organizations that practice federated decision-making (Amazon, Netflix, Toyota, mission command) escaped all three layers. They invested in culture before they needed it. They did it deliberately and deeply. They maintained it long enough for the slow process to take hold. Their decentralization does not snap back under pressure because it is not shallow. Netflix is the clearest test. Stock crashed 70% in 2022. They laid off staff. They did not re-centralize. Their 2024 culture revision doubled down on "context not control."

What makes it stick

The ratchet is the spine. Four forces make it stickier.

Serial satisficing without learning. Hire aggressively in 2021. Lay off aggressively in 2023. Pivot to AI in 2023. Each correction is presented as the rational fix to the previous bounded decision. But the claim that any correction is rational is not falsifiable. Neither is the claim that it is wrong. That is the point. Nobody checks. Nobody builds the feedback mechanisms that would let you check next time. Pfeffer's research provides the closest thing to empirical traction: companies that did not lay off performed equally well. The honest version of the earnings call: "We are making this correction with equally incomplete information, and we have no way of knowing if it is better than what it replaced." Nobody says that.

Institutional inertia. The companies are profitable. The stock is up. Directive governance is not producing visible failures. Why would anyone champion a multi-year cultural transformation with uncertain payoff? The ratchet provides cover during crisis: centralization is plausible enough to be defensible. In peacetime, the status quo is plausible enough to be comfortable. Nobody fixes what appears to work.

Incentive structures. Meta recently tied nearly $1 billion in executive compensation to stock price targets. Not innovation rate. Not decision quality. Not talent retention. Stock price. The CTO, CPO, COO, and CFO all hold options that pay out only if market capitalization hits specific thresholds. This is not unusual. It is the norm. Executive compensation rewards what directive governance can produce: revenue, cost cuts, market cap. It does not reward what decentralization would improve.

The Spotify illusion. Companies that claim to have decentralized but have not. Spotify's squad model was "part ambition, part approximation." Co-author Joakim Sundén later admitted people struggled to copy "something that didn't really exist." Spotify itself transitioned back to traditional management. This is the shallow loosening the ratchet predicts: structural change without cultural change. It looks like adaptation without being adaptation.

These forces do not operate independently. They feed the ratchet. Serial satisficing provides the post-hoc justification for each centralization. Inertia keeps the status quo comfortable. Incentives make change financially unrewarding. The Spotify illusion lets companies claim they have changed when they have not. Together, they ensure that even when competitive pressure forces loosening, the loosening stays shallow.

How does it make $$$

If directive governance is that broken, why are these companies worth trillions?

Because bad governance is a tax on performance, not a death sentence. When you have a search monopoly, network effects, or ecosystem lock-in, the monopoly rents absorb the tax. Microsoft lost a decade of market cap under Ballmer and emerged just fine. Google missed the boat on generative AI, despite authoring the seminal Transformer paper, and lost billions playing catchup. Apple and Meta spent billions on VR headsets that have yet to find a market.

The point is not that directive governance leads to death or bankruptcy. The point is that outward success does not mean the organization is healthy. The failure mode for most large tech companies is not death. It is languishing. Profitable enough to survive. Too poorly governed to innovate. The best engineers leave for younger companies where they can make decisions. The products get incrementally worse. The stock price holds up long enough that the board never forces the issue.

The urgency here is personal, not institutional. You can work inside directive governance and function. The company will survive either way. Directive governance ties your ability to drive innovation to the grace of your leader. That grace can be snatched away overnight.

Nadella's Microsoft is the rare counterexample: a deliberate, decade-long cultural investment that has survived multiple crises. The rarity is the point. The escape requires investment on a timeline that exceeds most executive tenures, in a discipline most leaders have never practiced.

But does it have to work this way? What's actually driving these decisions, and is there a better mechanism? Because if the answer is "this is just how large companies work," that's one kind of problem. If the answer is "there's a specific, diagnosable flaw in how these decisions get made", then that's a different one. One that might be fixable.

The mechanism: directive governance

The governance model that dominates the technology industry is what I call directive governance: information flows up through a reporting chain (compressed and lossy), decisions are made centrally, and directives flow back down for execution. Directive governance is how most large tech companies are actually run, regardless of what their culture decks say. (I formalize this definition in a follow-up article.)

And there is a reason for that. Directive governance has been very successful in a myriad of industries and organizations: pharmaceutical development, aviation, manufacturing, and even many parts of the military. What we see in the tech industry is a form of isomorphic mimicry; if it works in those areas, then it should work here too.

However, if you stop to ask why exactly it works in those industries, you start to see the fallacy in this mimicry. In pharmaceutical development, clinical trial data is structured and quantifiable. The information that matters can travel up the chain without losing its meaning. In aviation, decades of failure analysis have produced checklists and procedures that genuinely capture what matters. The gap between what the front line knows and what leadership sees is narrow by design. In manufacturing, defect rates and throughput are real proxies for operational reality. Cost per unit correlates with what's actually happening on the floor. And the person who designed the part is genuinely distinct from the person who fabricates it to spec.

Briefly, directive governance works really well when information for decision making is highly compressible without losing fidelity, is verifiable, and the decisions are clearly separable from their execution. These conditions are favorably satisfied in the industries mentioned earlier, and hence the success of directive governance in these spheres.

But the tech industry doesn't conform to these conditions, and therein lies the problem; the reason directive governance works poorly here.

The damage

This isn't theoretical. The wreckage is visible and well-documented.

• During Microsoft's lost decade, stack ranking destroyed collaboration across the company. It was a centralized performance system that forced bell-curve grading. As a result, employees optimized against each other instead of for the product. Market cap fell from $580 billion to $249 billion. Leadership could see attrition rates and shipping dates. They could not see the innovation that wasn't happening.
• In 2011, Google made the top-down decision to compete with Facebook on social and mandated that all teams across Google integrate Google+ into their products. Decision was made, and the teams were expected to execute. But "integrate social" is not a specification. Each team made their own decisions about what integration meant for their product. The decisions that determined whether the product would be coherent were not made by Google leadership. They were made by dozens of teams independently, at the execution layer, with no mechanism to coordinate them. The result was a Frankenstein. Google+ was shut down in 2019.
• After Elon Musk laid off roughly 80% of Twitter's staff, a single remaining SRE made a configuration change that broke the entire platform: links, images, internal tools, everything. "You may not see negative effects immediately," NYU's Justin Cappos observed. "A month later you start to take a hit, and then the wheels start to fall off." Musk couldn't see which engineers were load-bearing because their contributions didn't show up in the metrics visible from the top.
• In March 2026, OpenAI killed Sora, its video generation tool, because it was a "distraction". The pivot to ChatGPT-first left the Sora and DALL-E teams starved and feeling like second-class citizens. The result was an exodus of significant talent from OpenAI. In summary: centralized leadership greenlit a scatter of products, discovered the strategy was incoherent, and corrected with another centralized decision. The cost wasn't just a cancelled product. It was the people who walked out the door.

You have seen some version of this play out in your own workplace. It might be at a lower scale and with lower stakes, but the pattern is the same. What you might not have seen is the mechanism that produces it.

When does directive governance break?

Directive governance rests on three implicit assumptions about the information pipeline connecting the people who decide to the people who do:

1. Compression. When information is summarized upward, the compression preserves the signal that matters.
2. Proxy validity. The quantitative metrics available to decision-makers correlate with the reality they're managing.
3. Separability. Decision-making and execution are distinct activities that can be cleanly divided between levels of the hierarchy.

These assumptions hold in many industries. In manufacturing, summarizing production into throughput metrics does preserve what matters. Cost per unit does correlate with operational reality. And the engineer who designed the part is genuinely distinct from the worker who fabricates it to spec.

But these don't hold true in tech. To understand why, we need to go back to Hayek and Austin. Hayek recognized that in any complex system, knowledge is often inherently distributed, tacit, and contextual. It resists centralized aggregation by its nature. And Robert Austin demonstrated in 1996 that if only some dimensions of work are measurable, then measurement-based management actively degrades what cannot be measured. The combination of these two conditions in the tech industry invalidates the three assumptions above.

Why tech specifically

In 1986, Fred Brooks drew a distinction in "No Silver Bullet" that remains true despite all the advances in software engineering: software has essential complexity (the irreducible difficulty of the problem itself) and accidental complexity (the incidental difficulties of our tools and processes). Tools can attack accidental complexity. They cannot touch essential complexity, because it is the problem.

This argument extends to governing the people who build it. When you apply it there, all three assumptions collapse.

Compression fails. Essential complexity is irreducible by definition. You can compress "we shipped 15 features this quarter" into a slide, but you cannot compress "we chose this abstraction boundary because of how three subsystems will need to evolve independently over the next two years" into anything a non-participant can evaluate. The compression directive governance requires strips precisely the signal that matters. This goes back to Hayek's observation about knowledge's resistance to centralization.

Separability fails. This is where software diverges most sharply from other industries. In manufacturing, you do the same thing repeatedly. The design decision was already made, and execution follows a spec. Micro-decisions on the line are local and ephemeral. They don't compound.

Everything you build in software is new (if it weren't, you'd just call the API that already does it), and consequently, the act of building software itself is decision making: choosing an abstraction, defining an interface, decomposing a system. And unlike manufacturing, software decisions compound. Every abstraction choice constrains every future choice built on top of it. A manufacturing micro-decision lives and dies in the moment. A software decision shapes the codebase for years.

In software, execution is decision-making. Directive governance depends on a separation between the two that doesn't exist.

Proxy validity fails. The metrics that survive the reporting chain (uptime, sprint velocity, cost per headcount) track what keeps the lights on. They don't track what makes the company thrive. Innovation, architectural soundness, the quality of an abstraction, whether a team's trajectory is sustainable: none of these fit in a dashboard. As per Austin's observation, the metrics don't just miss creativity and innovation; they actively redirect effort away from it and toward maintenance.

The tech industry fails these three assumptions structurally and inherently, and the problem is only getting more acute. All of our advances in software engineering (Agile, CI/CD, cloud infrastructure, AI-assisted coding) serve only to eliminate accidental complexity. This leaves the essential complexity to dominate the signal loss in upward communication and to force leveraged decision-making in execution, while continuing to remain in the blindspot like a ghost moving the metrics.

The structural implication

If directive governance fails because the tech industry is structurally not convivial to it, then we need structural changes to how decisions are made. The structural fix here is that decisions get made where the information actually lives. But subsidiarity is not the same as flattening the org chart.

Does that mean we should 'flatten' the org chart? Is all this talk of 'flattening' really going somewhere? Sigh. I wish. It has been tried, and it produces its own pathologies. Valve's famous flat structure concealed a hidden hierarchy of informal cliques. Jo Freeman diagnosed this dynamic in 1970: structurelessness doesn't prevent hierarchy, it prevents accountable hierarchy. The loudest and most politically savvy end up in charge, with no formal mechanism for review or appeal. Spotify's squad model never actually worked at Spotify. "Even at the time we wrote it, we weren't doing it," co-author Joakim Sundén admitted. When Zappos adopted holacracy and gave employees an ultimatum to embrace self-management or leave, 14% of the company walked out the door. Eliminating hierarchy doesn't solve the information problem. It just makes power invisible.

But there are organizations, across industries, at massive scale, that have kept hierarchy while relocating decision authority within it.

• Toyota gives any assembly line worker the authority to pull the andon cord and stop the entire production line when they spot a defect. Why? Because the worker has specific knowledge no dashboard can capture.
• Amazon scales by multiplying small teams, not layering hierarchy. The "two-pizza team" is small enough that one leader can have full context. It is directive governance at a scope where the information precondition actually holds, federated across thousands of teams.
• Netflix operates on the explicit principle that leadership's job is to communicate what and why; the people doing the work decide how.
• Warren Buffett runs Berkshire Hathaway, a $900 billion conglomerate, with roughly 30 people at headquarters. He handles capital allocation, where a bird's-eye view helps. Subsidiary CEOs handle everything else, where local knowledge is what matters.
• And the US Army, an institution built on hierarchy and obedience, formalized mission command: commanders communicate intent, subordinates decide execution. L. David Marquet transformed the USS Santa Fe from the worst-performing submarine in the fleet to the best by replacing "permission to" with "I intend to."

Notice that none of these examples eliminated hierarchy. They all redesigned where decisions happen within it. The tech industry didn't need to discover a new governance structure. It just needs to snap out of its dogma and stop ignoring what works.

Humanity's response to this problem has not been improvement alone. Each advance in our models brought with it a particular hubris: the conviction that this time, the map was complete; that what couldn't be captured was simply not worth capturing. And it is precisely that conviction that licenses the coercion. If the model is complete, then deviation isn't a sign of the model's limits. It is a sign of reality's defects.

Better maps didn't reduce the impulse to redraw the territory. They justified it.

To eliminate these 'edge cases,' humanity has spent millennia on a grand project: forcing reality to conform to a model we can predict and control. Philosophers have both fueled this project and warned of its side effects, warnings we have summarily ignored. The culmination of this effort is the 'AI Slop' currently inundating us. An ironic final step in subverting our perception of reality itself.

The legibility project of the pre-modern era

Humans tend to be "illegible". They are complicated, and diverse. Every group has its own customs, traditions and morality. Controlling and ruling over such an illegible group is near impossible. So this grand project started millennia ago as a mechanism to control people by reducing their illegibility. By making them legible. By flattening their complexity and diversity into a 'compressible' set of behaviors. The first recorded efforts in this direction are the Code of Hammurabi and the Manusmṛti.

Yes, these are known to be the first legal texts, but then again, a legal system essentially is a compression algorithm for human behavior; its goal is to reduce a diverse population to a predictable, manageable set of outputs. Of course, there were errors in predictions of these models, and such errors are referred to as "crimes" and there are entire institutions dedicated to "correcting" such errors, by not improving the model, but by coercing human behaviors to fit the model. "Justice" was really about systemic control.

Of course, due to limitations of technology, the model had incredibly low resolution, and it sought to model only the human behaviors that needed control within the confines of the day's political sovereignty. For the most part, these models left the natural world and our inner worlds alone.

As the project matured, the philosophers were on a mission to build a descriptive model of reality. Plato's Theory of Forms modeled the world's diversity as mere 'noise' deviating from a perfect ideal. Aristotle provided the methodology for deconstructing reality into 'silos of legibility' under the fatal assumption that nothing of value is lost in the gaps. Mathematicians such as Aryabhata and Brahmagupta created descriptive maps to navigate the heavens. However, the impulse toward a prescriptive reality was already visible in the shadows. It lived in Astrology, which forced human destiny to fit a celestial map, and in the sale of Indulgences, which downsampled the infinite complexity of sin into a quantifiable financial transaction. The pivot to a world coerced to conform to the map was not a new idea, but it could not be realized at scale until better technology came along.

The objectivity of modernity

The renaissance and modernity introduced us to the concept of objectivity: the notion that things are true regardless of a subject. The philosophers of this age viewed reality as an object to be observed, dissected, studied. And somehow, we could do it objectively, as if we weren't part of this object we were studying. This paradigm alienated us from our own existence. This alienation allowed philosophers to turn this gaze of objectivity inward into our own lives and how we relate to each other; into our inter-subjectivity. They dissected how we relate to each other, and how we work together to produce goods and make progress. This was categorized and studied with ever more precision. We had new categories to peer into. There was economics and there was psychology and there was political science and there was ethics. Almost as if each of them had nothing to do with each other, and pursued their own investigations to get to their objective truths.

It wasn't long before this inward gaze of economics turned onto human work, and it didn't see people. It saw functions. A watchmaker, viewed through the economic lens, was not a person embedded in a tradition, a community, a set of relationships. He was a bundle of discrete, separable processes: material procurement, part fabrication, assembly, quality control, distribution. The model couldn't perceive anything it couldn't categorize. And what it couldn't perceive, it treated as if it didn't exist.

This was the Industrial Age: a period of selective blindness. The watchmaker didn't disappear because someone chose to erase him. He disappeared because the model looking at him had no category for what he actually was. We didn't just make more watches; we created a world where the human was only allowed to exist as a low-resolution component of a larger machine.

Ontological Blinders of the information age

The 20th century provided the necessary technologies to unify the balkanized silos of modernity. Through the work of Alan Turing, John von Neumann, and Claude Shannon, the messy kinetics of physical reality were recast as pure information processing. "Process Efficiency" was replaced by "Algorithmic Optimization."

We resurrected Plato's theory of Forms, but the forms were now idealized mathematical models. Any deviation from the model became a systematic 'error' that needed rectification. For instance, the nuances and peculiarities around the problems of routing trains between cities, laying down water and sewer pipes in a neighborhood, and moving data packets around a network were all 'unified' by the same optimization algorithms, and in that process those very same nuances and peculiarities were completely marginalized. A missed package was no longer a logistical accident: it was an "error" requiring more "fault tolerance." A worker calling in sick was no longer a human event: it was a "node failure" requiring a "redundancy" patch. These changes happened in the background of our lives, hidden by the perceived convenience of the tools.

The insidious turn occurred when the model overrode the reality. The diversity of the world was rebranded as "noise" that failed to map to the model, rather than the model failing to map to the world. Algorithms started changing human behavior so that it remains compliant with the model's expectations.

The upshot is a society that has mistaken the models for reality. The mask has become the face. You see it in social media where a curated "Instagram life" is accepted as a true representation of existence. You see it in the economy, where macro-economic abstractions like GDP are deemed more "real" than actual economic health. We have now flattened ourselves to be legible to these models. We optimize our lives to improve a credit score as if the score were the reality. "Pics or it didn't happen" is the demand for algorithmic validation of our own subjectivity. We have become ontologically blind to anything that cannot be accounted for by the model.

The Manufactured Reality of the Intelligence Age

The 21st century introduced the ultimate agent of the Grand Project: Generative AI. This technology finally detaches the Map from the Territory. But it does so in a way that is categorically different from everything that came before it.

Previous technologies mediated reality. The photograph selected a frame. Television broadcast a produced version of events. Social algorithms surfaced a curated slice of human expression. In each case, the underlying reality was still there, generating the inputs. The mask had become the face; but there was still a face underneath.

Generative AI breaks this relationship entirely. It does not compress reality. It bypasses it. The inputs to a large language model are not live signals from the world; they are prior compressions: text, images, and records of what humans said and made, after already passing through every filter described above. The model trains on the averaged residue of a civilization that had already been flattening itself for centuries. It then generates new outputs optimized for coherence with that averaged signal; maximally legible, frictionlessly consumable, scrubbed clean of the noise that makes any particular perspective distinct from the statistical mean.

We call the result "AI Slop." It is a pejorative that describes the soulless, uncanny nature of these creations. Yet, we cannot stop consuming it. We are addicted to it because it is the path of least resistance. It is content with the highest possible fidelity to the model and the lowest possible fidelity to any individual reality. It has no author, no context, no stake. It is the signal of the average; which is to say, the signal of no one.

We consume it anyway, and at scale. Not because we are foolish, but because this entire arc has been progressively reducing our tolerance for friction, for illegibility, for the effort that genuine encounter with reality requires. AI Slop is not a cause. It is a symptom of a sensory system that has been recalibrated, over centuries, to mistake the model for the thing.

The momentum driving this is 2,500 years in the making. From Hammurabi's codes to Shannon's information theory, every step has iteratively eliminated the human element as an "inefficiency." We are now so far immersed in this episteme that we have lost the ability to distinguish the mask from the face. Previously, the mask became the face. Now there are no more faces. Only masks.

Meanwhile, the principle of locality of behavior (or “locality of behaviour” in htmx) says that "the behavior of a unit of code should be obvious by looking only at that unit" [source]. It draws on older ideas of cohesion: keep related logic together.

So when should you favor layering defenses, and when should you co-locate behavior? This isn’t that post. Instead, here’s a story about how leaning on defensive programming without scrutiny let a critical bug stay hidden for far too long.

Background: minor and major compaction. I was working on a big data system that performed repeated mutations on datasets via commits. Over time, reading slowed down—each read had to apply more mutations. To fix this, my service relied on cheap minor compactions. But unbeknownst to me, there was a fallback: a slow, expensive major compaction if too many mutations piled up. (See https://orc.apache.org/docs/acid.html.)

Unexpected failures. Suddenly, my service slowed down and sometimes timed out. Digging in, I found it was triggering major compactions. These were so costly that jobs exceeded timeouts and got killed.

Asking around, I learned this was an intentional fallback. It was a defensive programming safeguard in case minor compactions failed. Everyone thought this was great resilience.

Increasingly brittle. Then I asked: why did minor compactions fail in the first place? Silence. No alerts, no monitoring; no one knew.

Logs revealed major compactions had been quietly running on small datasets for ages due to a bug in minor compaction discovery. The problem stayed hidden because small datasets finished quickly. When larger ones arrived, everything blew up.

Ironically, the fallback meant we never fixed the root issue. Our supposed resilience made the system more fragile.

Could we have seen this coming? If major compactions didn’t exist—or at least raised an alarm every time—they’d have forced us to fix minor compactions long ago, before the blast radius grew.

So next time you violate locality of behavior for defense-in-depth, think hard. And always alert aggressively when deeper defenses kick in.

Building on these well-trodden ideas, this incident is just one more caution: defense-in-depth only works if every fallback is visible and monitored. Otherwise, your “resilience” may just be hiding decay.

The short version: I made a simple function signature change, assuming only future runs would care. Instead, my pipeline broke days later when an old task serialized under the previous signature collided with the new code. The fix? Classic backward compatibility tricks that saved me from babysitting all existing task runs when making changes in the future.

Here’s the story — and how to avoid learning this lesson the hard way.

The bug

I had a Dataswarm operator that would execute a Python function every day, and the output of that Python function was a list of tasks (other functions) to be executed that day.

Here is what the function looked like:

# Function that generates the tasks to be executed.
def task_generator(arg1, arg2) -> List[Task]:
    ...

# How the function is invoked
wait_for_data = SomeTaskWaitingForData(data)
tasks_to_be_executed = DynamicTasks(
    wait_for_tasks=[wait_for_data]
    task_gen_function=task_generator
    task_gen_args={
        "arg1": a,
        "arg2": b,
    }
)

I put in a diff that looked something like this:

# Function that generates the tasks to be executed.
- def task_generator(arg1, arg2) -> List[Task]:
+ def task_generator(arg1, arg3) -> List[Task]:
    ...

# How the function is invoked
wait_for_data = SomeTaskWaitingForData(data)
tasks_to_be_executed = DynamicTasks(
    wait_for_tasks=[wait_for_data]
    task_gen_function=task_generator
    task_gen_args={
        "arg1": a,
-        "arg2": b,
+        "arg3": c,
    }
)

You see, I just replaced arg2 with arg3 and everything looked fine. I tested the diff and landed it, expecting the next task instance to pick up the changes and move on. As you can imagine, that is not what happened :)

I soon got a bug report that said that my pipeline failed with an error: TypeError: 'arg2' is an invalid keyword argument for task_generator(). This had me completely confused. My expectation was that either the previous version of the pipeline would be executed, in which task_generator() is defined to expect arg2 and tasks_to_be_executed passes a value for arg2, or the new version of the pipeline would run, where task_generator() expects arg3 and tasks_to_be_executed passes arg3. Neither of those two scenarios result in a TypeError: 'arg2' is an invalid keyword argument for task_generator(). So, what's going on?

The root cause

After some debugging, I saw that the tasks_to_be_executed task instance that errored out started off two days ago, but was waiting for the wait_for_data to complete, and the wait_for_data task didn't complete until the current day, after which the tasks_to_be_executed task instance ran and errored out. Eventually I found that DynamicTasks serializes the function name and args as a JSON blob at schedule time, waits for upstream tasks to finish, then reloads the function from HEAD and calls it with the original arguments. That’s why old args collided with new code.

Because DynamicTasks persists the function name and args and then later reloads HEAD, it breaks the assumption that changing a function signature only affects new pipeline runs. I only discovered this by digging into DynamicTasks implementation; classic leaky abstraction!

The fix

Changing the Dataswarm operator implementation to not leak its implementation detail was a pretty heavy lift, and I needed a more scoped down change to unblock myself. So, I needed a way to make sure that I can change the task_generator implementation without running into such combinations of race conditions and leaky abstraction again. Making the task_generator implementation backward compatible accomplishes this quite nicely. But first, I need to make sure that it can be made backwards compatible. That involves a few steps.

Step 1. Add **kwargs

First, we need to ensure that passing in parameters from the previous version of task_generator does not throw an unexpected exception. We can do that by swallowing all unspecified parameters in **kwargs as follows.

# Function that generates the tasks to be executed.
- def task_generator(arg1, arg2) -> List[Task]:
+ def task_generator(
+    *,
+    arg1=None,
+    arg2=None,
+    **kwargs
+ ) -> List[Task]:
+    if kwargs:
+        LOG.warning(f"Found unspecified arguments {kwargs.keys()}")
    ...

The diff does three things.

1. It ensures that all arguments are passed by name and not by position.
2. It makes all parameters optional with a default value of None. This ensures that leaving out any specific parameter doesn’t break the call. The reasoning for this is similar to the ones in proto3 that made all fields optional.
3. If the caller passes an unexpected parameter (say, arg13), the function won’t throw an exception. Instead, it logs a warning about the unrecognized parameter and proceeds to execute the function with the remaining parameters.

Land this change and wait for it to propagate to all your task instances.

Step 2. Change your function signature

Now you are ready to make changes to your function signature without breaking existing tasks. Suppose you want to remove arg2 and introduce arg3. Your diff would look like this.

def task_generator(
    *,
    arg1=None,
-   arg2=None,
+   arg3=None,
    **kwargs
) -> List[Task]:
    if kwargs:
        LOG.warning(f"Found unspecified arguments {kwargs.keys()}")
+   if not arg3:
+       arg2 = kwargs.get("arg2", None)
+       # Old business logic with arg2
        ...
+       return tasks
+   # New business logic with arg3
+   ...
+   return tasks

When you land this, you could have tasks scheduled to run that are currently persisting the old function signature. When such tasks execute your new function definition, **kwargs will swallow arg2 and arg3 is set to its default value None. The function will see that arg3 is None, so it will look for arg2 in kwargs and execute the old business logic.

However, for all new instances of your task, arg3 is set, and so the function executes the new business logic. Backward compatibility accomplished!

Step 3. Delete old functionality

After all your old task instances have completed execution, you are now ready to remove the old business logic. This is a simple red diff.

def task_generator(
    *,
    arg1=None,
-   arg3=None,
    **kwargs
) -> List[Task]:
    if kwargs:
        LOG.warning(f"Found unspecified arguments {kwargs.keys()}")
-   if not arg3:
-       arg2 = kwargs.get("arg2", None)
-       # Old business logic with arg2
-        ...
-       return tasks
   # New business logic with arg3
   ...
   return tasks

And, you are done!

Lessons learned

• Pipeline frameworks can serialize more than you think. DynamicTasks pickled the function name and arguments days earlier, then loaded the function definition fresh from HEAD. That mismatch broke everything.

• Stage changes with **kwargs and defaults. When changing function signatures that might still be called by older task payloads, always accept extra kwargs and use None defaults to gracefully detect old vs. new callers.

• Expect your abstractions to leak. If your orchestration tool stores data and code separately (JSON blobs now, functions later), your assumption that “old code only calls old function signatures” is toast.

• Logging unrecognized parameters is gold. Instead of crashing, you get explicit warnings when old payloads collide with new code. Debugging becomes a thousand times easier.

Recently, I encountered a subtle performance issue while refactoring some C++ code. I was passing a std::shared_ptr<T> by value into a function, even though the callee only needed read access. Infer flagged it as PULSE_READONLY_SHARED_PTR_PARAM. Infer was right: passing shared pointers by value incurs refcount overhead, and if multiple threads are sharing the pointer, it can introduce performance regressions. My code looked something like this.

void caller(std::shared_ptr<T> shared_ptr) {
  ...
  callee(shared_ptr);
}

void callee(std::shared_ptr<T> ptr) {
  auto foo = ptr->read_value() + 1;
}

Infer's suggestion, and why it's wrong

Infer's documentation around PULSE_READONLY_SHARED_PTR_PARAM says the following:

This issue is reported when a shared pointer parameter is a) passed by value and b) is used only for reading, rather than lifetime extension. At the callsite, this might cause a potentially expensive unnecessary copy of the shared pointer, especially when many number of threads are sharing it. To avoid this, consider 1) passing the raw pointer instead and 2) use std::shared_ptr::get at callsites.

So, its suggestion was to change my code to the following:

void caller(std::shared_ptr<T> shared_ptr) {
  ...
  callee(shared_ptr.get());
}

void callee(T* ptr) {
  auto foo = ptr->read_value() + 1;
}

Sure, Infer got the diagnosis right, but the proposed solution of using raw pointers seems wrong. Smart pointers (unique_ptr and shared_ptr) were introduced precisely to avoid the many footguns associated with raw pointer memory management and safety. There should be almost no good reason to use raw pointers, and the use case above seems too trivial to warrant using a raw pointer. In fact, if I passed a raw pointer, some future developer might wrap it in a new shared_ptr and pass it elsewhere. That’s a recipe for double-free bugs and a nasty core dump.

Ranting aside, I still couldn’t let the change stand as-is; the infer error was pointing to a legitimate problem. So, how do we address this issue without resorting to raw pointers? Answer: const refs :)

Const refs to the rescue

Instead of passing the raw pointer, what if we just passed the underlying object itself? Well, we don't really need a copy of the object, and so we can pass a reference to it. Since we’re only calling a read-only method, a const reference works just fine. With that, we have this fix:

void caller(std::shared_ptr<T> shared_ptr) {
  ...
  callee(*shared_ptr);
}

void callee(const T &obj) {
  auto foo = obj.read_value() + 1;
}

And it works like a charm.

Why not const ref the shared pointer itself?

Of course, passing a const reference to the object isn’t the only way to avoid copying the shared pointer. You can also simply pass the shared pointer by reference!

void caller(std::shared_ptr<T> shared_ptr) {
  ...
  callee(shared_ptr);
}

- void callee(std::shared_ptr<T> ptr) {
+ void callee(const std::shared_ptr<T> &ptr) {
  auto foo = ptr->read_value() + 1;
}

(I showed this as a diff because the change is subtle! Also note: taking a reference to a shared_ptr avoids bumping the reference count, so there’s no added contention.)

Now, be careful here. You can't use this trick if shared_ptr could be a nullptr, because passing a reference to a nullptr and trying to dereference it is a great way to bring down your service! In my case, it turns out that shared_ptr was guaranteed to be non-null, and so this trick works well.

So next time someone suggests using a raw pointer, be skeptical—there’s almost always a safer alternative to that particular footgun.

Oh, and one last thing...

I’ll stop here, but don’t walk away thinking const refs are a cure-all. They can backfire too. This post in Belay the C++ outlines some of the less obvious pitfalls.

Disclaimer: While these steps will make it easy for your site to start looking closer to your desired theme, it is by no means a turnkey solution. You will still need to do a fair amount of hand editing for the new theme to work with your existing content. So, make sure you are able and willing to spend time fiddling with various configs, settings, and markdown front matter.

Prerequisites

Before we begin, here are the prerequisites:

1. Your site is already version controlled by git. Ideally, it is already on Github.
2. You are able to run Jekyll locally. If not, please follow the instructions in https://jekyllrb.com/docs/ and then come back here.
3. The new theme that you have picked out for your site is a gem-based theme. Technically, the steps outlined below can be tweaked for a regular theme as well. I will include an addendum at the bottom on how you can work with regular themes as well.
4. The post assumes that your Jekyll site source is in the directory ~/github/website. All references to ~/github/website should be replaced by the location of your source.
5. I assume that the theme that you want is Wind theme that can be installed via gem "wind-theme". You can change it to whatever theme you pick.

Requirements

1. The new theme is installed in the same location as the original site
2. The content from the orignal site is preserved.
3. The new theme lands as a single commit on top of the old theme. We do not want to lose the commit history.
4. No vestiges or residues of the old theme must remain.
5. This should be done via a Pull Request/merge and not via a force-push.

The Guide

Start with a clean slate

To begin, we’ll create a clean working directory. We don’t want to simply nuke ~/github/website since it contains all your site's content. Since we want to keep the commit history, we cannot pull an orphan branch. So, we start by creating a branch off of main, and then working on it exclusively until we are ready to publish a Pull Request. We’ll start by creating a new branch and removing its contents so we can set up a fresh Jekyll site. Here are the steps.

First, create a new branch from main, and then nuke everything. This creates an empty working directory in the new branch, while preserving your full site on main.

cd ~/github/website
git checkout main
git checkout -b install_new_theme
git rm -rf .
git clean -dfx

Note: git clean -dfx removes any untracked files and directories, including ignored files, to fully clean the working tree.

Now you have a clean directory to install things in. Next, we install a fresh Jekyll site:

gem install jekyll bundler
bundle init
cd ..  # Change directory to `~/github`
jekyll new website --force
cd ~/github/website

Warning: jekyll new website --force overwrites contents of website/ and so make sure it doesn’t contain anything important that isn’t backed up.

Now, this is an empty Jekyll site, and we are going to change the theme on this empty site to the theme that you picked out.

Install new theme

Recall that I am going to install wind-theme. To do that, I edit the Gemfile ~/github/website/Gemfile as per the theme instructions, and the following line.

gem "wind-theme"

You can either use the default _config.yml, or copy your existing one from main via:

git checkout main -- _config.yml

Now, edit your _config.yml to set the theme to wind-theme (as per theme instructions).

theme: wind-theme

Now run the installer and then serve the site locally (in another shell).

cd ~/github/website
bundle
bundle exec jekyll serve

The empty site with your new theme should now be accessible at http://localhost:4000/. Make sure that it looks and feels as advertised, and that no errors are popping up when building the site. At this point, if you are seeing issues, then you will have to roll up your sleeves, figure out what wrong, and fix it. Once you are happy with your site, time to fill it up with your content.

Bring back your content

Your site's contents should be in the main branch's _posts, and any other directories you may have created to store content (such as documents, images, assets, etc.). The top level pages of your site should be the top level .md or .markdown markdown files. Then, you also have your .gitignore, CNAME, etc. Bring them all back by copying them from the main branch as follows:

git checkout main -- _posts about.md something_else.md CNAME .editorconfig .github
...

Note: If you want to bring back everything except the theme-related directories, use a wildcard or cherry-pick structure.

The shell building your site should pick these changes up and update the local build automatically. Check the console logs on the output of bundle exec jekyll serve to make sure that things are working correctly. Go check out http://localhost:4000/ to make sure that all your content is present and looks as expected.

Again, if something looks off, it is time to get your hands dirty, figure out what's gone awry, and fix it. From here, you may need to debug based on your content and theme setup.

Once you are happy with the new theme, it is time to make it official!

Switching over to the new theme

First, let us commit all these changes we made into one fat commit.

git commit -am "Replace site with new jekyll theme"

Once you’re satisfied, push the branch to origin and open a pull request for review and merge.

git push --set-upstream origin install_new_theme

If you’re not using GitHub PRs, you can merge the changes directly into main via the CLI:

git checkout main
git merge install_new_theme

Once merged to main, you should be good to go. Congratulations, you have successfully changed your site's theme!

Addendum: using regular themes

If you want to install a regular theme that is not gem-based, then instead of following the "Install New Theme" section's instructions, do the following.

1. Download the regular theme files. You can fork them from github and clone it locally, if you want. That is what many repos suggest, but I prefer not to do that because those instructions assume that you will be installing your entire site on top of that repo. But that is not what you want. Presumably you want all of your content and associated commit history. So, don't clone the repo. Just download it to a new directory (say) ~/tmp/new_theme.

2. Copy over the theme files to your site directory (~/github/website). This include directories such as _includes, _layouts, _data, assets, and typically any other directory that starts with _ (except for _site). There might also be .js or other files in the main directory that you might have to copy.

3. Caution. Before moving on to the instructions in "Bring back your content" section, make sure that whatever content you are bringing back, it does not overwrite or interfere with the theme file that you just copied over. E.g., you might have images or icons in your assets directory, and the theme might also store some files in assets directory that you just copied over. git checkout main -- assets might overwrite your new theme files with old site content, so use caution.

Final Checklist

• [x] Your site is backed up or version-controlled
• [x] You've created a new branch from main (e.g., install_new_theme)
• [x] You've cleaned out old content in the new branch
• [x] You've installed a fresh Jekyll site and configured your new theme
• [x] You've served the site locally and confirmed it builds with no errors
• [x] You've copied over your original content and ensured nothing essential was lost or overwritten
• [x] You've tested your new site at http://localhost:4000/ and confirmed the theme looks correct
• [x] You've committed the changes as one clean commit
• [x] You've pushed the branch and opened a PR — or merged the branch into main
• [x] Your main branch now reflects the new theme and your full content

Ever spend 20 minutes trying to figure out why your bug fix or feature code isn't triggering or being executed — only to realize you missed a buried branch in someone’s 10-path function? That’s Cyclomatic Complexity in action. Intuitively, you can think of Cyclomatic Complexity as the number of possible paths a single execution of a function can take.

For example, a = b + c has a cyclomatic complexity of one, and a = b + c if foo else d + e has a cyclomatic complexity of two: one path is when foo is True and the effective logic is a = b + c, and the other path is when foo is False and the effective logic is a = d + e.

Ain't got no time? Here's the goods.

If you take just one thing away from this note, then let it be this.

Strive to reduce the Cyclomatic Complexity of your code; your team and your future self will thank you!

Time to hit the brain gym, bro

As an exercise, I will let you figure out the cyclomatic complexity of the following piece of code:

env_val = os.environ.get('...')
switcher_val = False
if env_val is not None:
    jk_val = True
    if env_val.lower() is in ["true", "1", "yes"]:
        env_val = True
    else:
        env_val = False
else:
    env_val = True
    switch_name = "/switch/name/from/config"
    switcher_val = switcher.check(switch_name, switchval=region)
if env_val or switcher_val:
    apply_some_config(job)

I'll wait... (Spoiler: It's not pretty.)

Give up? Turns out, it is 4: three if-checks contribute to three branching points, and the cyclomatic complexity is one more than that; ergo 4.

Next, by spending no more than 60 seconds looking this code, can you tell me what exactly it is doing? BTW, this is real production code that I ran across when debugging some issue, and it took me a long while to make sure I knew exactly when and how the config is applied. It wasn't obvious at all. If you can grok this in 60 seconds, take a bow!

Reeling yet?

Anyway, making sense of functions with high cyclomatic complexity is annoying. It’s notoriously difficult to write tests with good coverage for these functions, and in general, they tend to be bug factories.

And yet — somehow — a lot of senior software engineers don’t seem to grok this. I keep seeing deeply nested if-else blocks, sometimes inside loops with breaks and continues, and it doesn’t seem to bother anyone! It’s like we’ve collectively normalized this cognitive overhead.

Why?! Why are we putting up with this crap? It’d never fly in an interview.

Yo, let's fix it up!

Coming back to the above example, the confusion and ugliness of this code really got to me. It got so bad I considered dusting off a Karnaugh map. After some much needed grokking, I managed to simplify it down to a cyclomatic complexity of 2! :)

In the end, here’s what that poor little code snippet was trying to do:

# Apply config when '...' environment variable is True, else check the switch
__ENV_VARIABLE = '...'
__SWITCHER_KEY = '/switch/name/from/config'
def has_env_override():
    val = os.environ.get(__ENV_VARIABLE)
    return val is not None and val.lower() in {"true", "1", "yes"}

if (
    has_env_override() or
    switcher.check(__SWITCHER_KEY, switchval=region)
):
    apply_some_config(job)

Fewer paths, fewer bugs. Cleaner code. Happier teammates. What’s not to love?

If you are sending PRs for bug fixes with functional code change and an added test case in the same PR/commit, then you are doing it wrong!

The crux of the problem is the following: HOW DO YOU KNOW YOU’RE SMASHING THAT BUG? HOW CAN YOU BE SURE YOUR TEST ISN’T A DUD?! Your answer better not be VIBE CHECKS or just STARING REALLY HARD! If you are having to deploy your entire service/library and run an end-to-end test to demonstrate correctness, then you are doing too much, and you still haven't demonstrated that the unit test actually captures the previously errneous behavior.

There is this shiny little concept called Test Driven Development (TDD) that is mighty useful here. You can peruse the wikipedia link to figure out what TDD is exactly. This note will show you how to <a href="/garden/tdd-for-bug-fixes/">use TDD for bug fixes</a>.

Here are simple steps to fixing bugs using TDD:

1. 🕵️ Discover the bug. BAM! There it is! Your nemesis!

2. 🧪 Create a PR that creates a new unit test that exposes the unit test. YAWZA!

3. 🔧 Create a second PR on top the first PR that makes the functional code change and changes the expectation on the unit test accordingly. That should squash the bug! KAPOW!

4. 💰 Justice is served! PROFIT!

Still not sure? Let's demonstrate this with an example. Say, there is a bug that you discovered and know how to fix it.

First, you create a PR that demonstrates the bug by invoking your SUT with the offending input, and sets the expected value to be incorrect so that the test case actually passes with this incorrect value; thus demonstrating the bug.

class TestSUT(unittest.TestCase):
    ...
    def test_bug_b12345(self) -> None:
        '''
        Test to expose bug b12345
        '''
        # Arrange
        sut = SUT(...)
        
        # Act
        actual = sut.test_method(input="bad-input")

        # Assert
        self.assertEqual(actual, "bad buggy output")
        # The assertion above demonstartes the bug b12345
        # The right expected value should be "correct output".
        # self.assertEqual(actual, "correct output")
        

You can send that PR out for review and merge it in. Now you have a solid proof that you have found a bug, and reproduced it.

Next, you have a new PR that fixes that bug. If you bug fix is correct, then the test test_bug_b12345 should not start failing. The output of sut.test_method(input="bad-input") should be "correct output" and not "bad buggy output". So, you now modify the unit test test_bug_b12345 in that same PR that looks as follows:

    def test_bug_b12345(self) -> None:
        '''
        Test to expose bug b12345
        '''
        # Arrange
        sut = SUT(...)
        
        # Act
        actual = sut.test_method(input="bad-input")

        # Assert
-       self.assertEqual(actual, "bad buggy output")
-       # The assertion above demonstartes the bug b12345
-       # The right expected value should be "correct output".
-       # self.assertEqual(actual, "correct output")
+       self.assertEqual(actual, "correct output")

Now your test should pass. This second PR is conclusive proof that your diff now fixes the bug! So, merge it in. Deploy with confidence. BOOM — PROFIT!

It’s 4 AM, and I am in deep sleep. Suddenly, my phone, overriding all silencing setting starts ringing like there is no tomorrow. Naturally, I was being paged. I wake up bleary eyed, acknowledge the page, and join the team channel. Helpfully, the customer team oncall has message for me: “Your service has a latency spike. Please look into it.”

I drag myself to a laptop, check the graphs, and yes — there was a p99 latency spike, it lasted about half hour, and is already waning. Our SLOs were fine; our latency SLOs at these latency levels don't breach for another 30 minutes. I double-checked their SEV criteria, and they are also still green! So why the 4 AM fire drill?

Turns out, they’d set up their alerts to go off when their p99 latency went above the normal limits for 30 minutes, but their SLO wouldn't be breached until the elevated p99 persisted for 60 minutes. A twitcy alert if you ask me!

Their on-call had no idea what to do with the alert, saw my service mentioned, and did the classic move:

“When in doubt, escalate!”

So now I’m awake, trying to make sense of a 30-minute p99 latency increase that is fixing itself. I asked:

“Where's the SEV'?

I imagine the scene something like this.

Silence. Five minutes later, "Here is the SEV number..." The SEV was created two minutes ago. Facepalm!

Here’s what actually happened:

• The latency spike lasted about 30 minutes.
• The system auto-healed.
• The affected service was user-facing, but this was deep in the off-hours.
• Total estimated user impact: somewhere between “negligible” and “none.”

We could’ve all just slept through it and looked at it with fresh eyes in the morning. Instead, two engineers got pulled into zombie mode to stare at graphs that improved all by themselves. It was like debugging a ghost.

Moral of the story:

If your <a href="/garden/align-alerts-to-sev-criteria/">alert is going to wake someone up at 4 AM</a>, it better be for something that actually matters. If there's no SEV, no SLO breach, and no clear user impact — maybe let sleeping engineers lie.

Object Chains

This is the more classic violation of the Law of Demeter[^1]. This happens when a class C has a dependency D, and D has method m that returns an instance of another class A. The violation happens when C accesses A and calls a method in A. Note that only D is the 'immediate' collaborator/dependency of C, and not A. The Law of Demeter says that C should not be accessing the method in A.

# A violation of the Law of Demeter looks as follows.
## Example 1:
c.d.m().methodInA()

## Example 2:
d: D = c.d
a: A = d.m()
a.methodInA()

What is the problem with violating the Law of Demeter? Consider the following production code:

class UpdateKVStore:
    def __init__(self, client: KVStoreClient) -> None:
        self.client = client
        
    def update_value(new_content: Content) -> Status:
        transaction: KVStoreClient.Transaction = self.client.new_transaction()
        if transaction.get_content() == new_content:
            # Nothing to update
            transaction.end()
            return Status.SUCCESS_UNCHANGED
        mutation_request: KVStoreClient.MutationRequest = (
            transaction.mutation_request().set_content(new_content)
        )
        mutation = mutation_request.prepare()
        status: KVStoreClient.Mutation = mutation.land()
        return status

Now how would you unit test this? The test doubles for testing this code will look something like this

mock_client = MagicMock(spec=KVStoreClient)
mock_transaction = MagicMock(spec=KVStoreClient.Transaction)
mock_mutation_request = MagicMock(spec=KVStoreClient.MutationRequest)
mock_mutation = MagicMock(spec=KVStoreClient.Mutation)

mock_client.new_transaction.return_value = mock_transaction
mock_transaction.mutation_request.return_value = mock_mutation_request
mock_mutation_request.prepare.return_value = mock_mutation

Now you can see how much the class UpdateKVStore and its unit tests need to know about the internals of the KVStoreClient. Any changes to how the KVStoreClient implements the transaction will cascade into test failures on all its clients! That's a recipe for a low accuracy test suite.

There are a few ways to address this. Instead, if KVStoreClient could be recast as a Transaction factory, and then encapsulate all operations associated with the transactions within the Transaction class, then UpdateKVStore can be modified as follows:

class UpdateKVStore:
    def __init__(self, client: KVStoreClient) -> None:
        self.client = client  # Now a Factory class for Transaction.
        
    def update_value(new_content: Content) -> Status:
        transaction: KVStoreClient.Transaction = self.client.new_transaction()
        if transaction.get_content() == new_content:
            # Nothing to update
            transaction.end()
            return Status.SUCCESS_UNCHANGED
        status = transaction.update_and_land(new_content)
        return status

When testing the new UpdateKVStore, you only need to replace the KVStoreClient and the Transaction, both of which are (explicit or implicit) direct dependencies, with test doubles. This makes the code much easier and straightforward to test.

Fat Parameters

While the anti-pattern of 'fat parameters' does follow directly from the Law of Demeter, it does follow from the spirit of passing in only the information that the class needs to perform its function. So, what are fat parameters? They are data objects that as passed in as an argument to a class, and they contain more information than what is needed by the class.

For instance, say you have a class EmailDispatcher whose method setRecipient only needs a customer name and email address. The method signature for setRecipient should only require the name and email, and not the entire Customer object that contains a whole lot more.

@dataclass(frozen=True)
class Customer:
    ... # data class members.
    def getFullName(self):
        ...
    def getEmail(self):
        ...
    def getPhysicalAddress(self):
        ...
    def getPostalCode(self):
        ...
    def getCountry(self):
        ...
    def getState(self):
        ...
    def getCustomerId(self):
        ...
    # and so on.
    
 class EmailDispatcher:
     ...
     def setRecipient(name: str, email: str):
         ...
     def setRecipientWithFatParameter(customer: Customer):
         ...
     def sendMessage(self, message: Message):
         ...

In the pseudocode above, the class EmailDispatcher has two methods setRecipient and setRecipientWithFatParameter. The former uses only the information it needs, and the latter passed in the entire Customer object as a fat parameter.

The convenience of passing in the entire Customer object is straightforward. It allows gives you a simple method signature. It makes it easier for the method to evolve to use richer information about the customer without needing to change its API contract. It allows you to define a common Dispatcher interface with multiple Dispatchers that use different properties of the Customer class.

However, when it comes to unit testing, such fat parameters present a problem. Consider how you would test the EmailDispatcher's setRecipientWithFatParameter method. The tests will need to create fake Customer objects. So, your fake Customers might look like this:

fakeCustomer = Customer(
    first_name="bob",
    last_name="marley", 
    email="bob@doobie.com", 
    address=Address(
        "420 High St.", 
      "", 
      "Mary Jane", 
      "Ganga Nation", 
      "7232"
    ), 
    id=12345, 
    postal_code="7232", 
    ...
)

When someone reads this unit test, do they know what is relevant here? Does it matter that the second parameter of address is empty string? Should the last parameter of address match the value of postal_code? While we might be able to guess it in this case, it gets more confusing in cases where the fat parameter is encapsulating a much more complicated entity, such as a database table.

When refactoring or making changes to the EmailDispatcher, if the unit test fails, then figuring out why the test failed becomes a non-trivial exercise, and could end up slowing you down a lot more than you expected. All this just leads to high maintenance costs for tests, low readability [^2], poor DevX, and limited benefits.

[^1]: You can read about it here, here, here, and here, and really just search for "Law of Demeter" on the Internet

[^2]: For more details on why we should care about readability, see the section on Readability here.

For instance, you service implementation should be split into 'modules' where each module has a well defined API through which other modules interact with it. This API boundary has to be strict. Avoid the temptation of breaking this abstraction because your module need this 'one tiny bit' of information that is available inside the implementation of another module. You will regret breaking encapsulation, I guarantee it!

If you follow this pattern, you will eventually reach a class that has a public API, has all of its external/shared dependencies shared, and delegates a lot of it's business logic and complex computation to multiple 'private' classes that are practically hermetic and have no external/shared dependencies. At this point, treat all these 'private' classes as, well, private. That is, DO NOT WRITE UNIT TESTS FOR SUCH CLASSES!

Yes, that statement seems to fly in the face of all things sane about software testing, but it is a sane statement, nonetheless. These private classes should be <a href="/garden/minimize-public-surface-for-testability/">tested indirectly</a> via unit tests for the public class that they serve/support. This will make your tests a lot more accurate. Let me explain.

Say, you have a public class CallMe and it uses a private class HideMe, and furthermore, HideMe is used only by CallMe, and the software design enforces this restriction. Assume that both CallMe and HideMe have their own unit tests, and the tests do an excellent job. At this point, there is a new requirement that necessitates that we refactor CallMe's implementation, and as part of that refactoring, we need to modify the API contract between CallMe and HideMe. Since HideMe's only caller is CallMe, it is completely safe to treat this API contract as an implementation detail and modify it as we see fit. Since we are modifying the specification of HideMe, we have to change the tests for HideMe as well.

Now, you run the tests, and the tests for HideMe fail. What information does that give you? Does that mean that there is a bug in HideMe; or does it mean that we did not modify the tests correctly? You cannot determine this until you either manually inspect HideMe's test code, or until you run the tests for CallMe. If CallMe's tests fail, then (since this is a refactoring diff) there must be a bug in HideMe and/or CallMe, but if the tests don't fail, then it must be an issue in HideMe's tests.

Thus, it turns out that the failure in HideMe tests gives you no additional information compared to failure in CallMe's tests. Thus, tests for HideMe have zero benefits and a non-zero maintenance cost! In other words, testing HideMe directly is useless!

By aggressively refactoring your code to push as much of you logic into private classes, you are limiting the API surface of your software that needs direct testing, and simultaneously, ensuring that your tests suite is not too large, has very [high accuracy, with reasonable completeness]({% post_url 2022-06-13-unit-test-attributes-and-their-trade-offs %}).

Coupled tests are problematic in two ways.

1. Tests become less readable. Reading the code for a single unit test does not necessarily communicate what the test does. We also need to understand the 'coupling' between that test and other tests to grok what a single test does. This coupling can be subtle and not easy to follow.
2. Tests become less [accurate]({% post_url 2022-06-13-unit-test-attributes-and-their-trade-offs %}). When one test affects another, it becomes difficult to make changes to a single test in isolation. For instance, if a diff makes changes to the some production and test code, and then a test fails, then it is not always clear why the test failed. The failure could due to a bug, or an artifact the coupled tests. Thus, your tests are no longer trustworthy, and therefore, less accurate.

Coupling can happen in many ways. The obvious ones include (1) using the same shared dependency (like when you use the same temp file name in all tests), and (2) relying on the post-condition of one test as a precondition of another test. Such cases are also obvious to detect, and to fix. There are two more following ways in which tests can be coupled; but these are more subtle, and more prevalent.

1. Precondition setting in test fixtures
2. Parameterized tests for heterogeneous tests

The rest of this note is focused on the above two anti-patterns of test coupling.

Coupling through test fixtures

Say, your SUT has a dependency called Helper, and initially, for the two tests in your unit tests for the SUT, you initialize your Helper stub with contents valueA, and valueB. Since both tests share the same initial state, you include the initialization code in the SetUp of the unit tests.

class SUTTestCase(unittest.TestCase):
    def setUp(self):
        self.helper = StubHelper()
        self.helper.add_contents([valueA, valueB])
        self.sut = SUT(self.helper)
        
    def test_behavior1(self) -> None:
        ...  # Assumes self.helper set with contents=[valueA, valueB]
    
    def test_behavior2(self) -> None:
        ...  # Assumes self.helper set with contents=[valueA, valueB]

Next, you modify SUT to add features to it. In order to test those features, the Helper stub needs to include controllerA. But these are useful only in the new tests being added. However, looking at the unit test you already have, it is easiest to to simply add controllerA to self.helper. So, your unit tests look as follows:

class SUTTestCase(unittest.TestCase):
    def setUp(self):
        self.helper = StubHelper()
        self.helper.add_contents([valueA, valueB])
        self.helper.add_controller(controllerA)
        self.sut = SUT(self.helper)
        
    def test_behavior1(self) -> None:
        ...  # Assumes self.helper set with contents=[valueA, valueB]
             # But this test assumes nothing about self.helper's controller

    def test_behavior2(self) -> None:
        ...  # Assumes self.helper set with contents=[valueA, valueB]
             # But this test assumes nothing about self.helper's controller

    def test_behavior3(self) -> None:
        ...  # Assumes self.helper set with contents=[valueA, valueB], and controller=controllerA

    def test_behavior4(self) -> None:
        ...  # Assumes self.helper set with contents=[valueA, valueB], and controller=controllerA

Then you discover a gap in testing that requires the initial state of the Helper stub to have just the content valueA and include controllerA. Now, when adding this new unit test to suite, the simplest way to do this would be to remove valueB from self.helper at the start of the new test. So, now, your test suite looks as follows:

class SUTTestCase(unittest.TestCase):
    def setUp(self):
        self.helper = StubHelper()
        self.helper.add_contents([valueA, valueB])
        self.helper.add_controller(controllerA)
        self.sut = SUT(self.helper)
        
    def test_behavior1(self) -> None:
        ...  # Assumes self.helper set with contents=[valueA, valueB]
             # But this test assumes nothing about self.helper's controller

    def test_behavior2(self) -> None:
        ...  # Assumes self.helper set with contents=[valueA, valueB]
             # But this test assumes nothing about self.helper's controller

    def test_behavior3(self) -> None:
        ...  # Assumes self.helper set with contents=[valueA, valueB], and controller=controllerA

    def test_behavior4(self) -> None:
        ...  # Assumes self.helper set with contents=[valueA, valueB], and controller=controllerA

    def test_behavior5(self) -> None:
        # Assumes self.helper set with contents=[valueA, valueB] (because of other tests' setup)
        self.helper.remove_content(valueB)
        # Now assumes self.helper set with contents=[valueA]
        ...  

Let pause here and inspect the state of the unit test. The tests are coupled. Why? Because modifying one test ends up affecting other tests. In the example above, if we replace self.helper.add_contents([valueA, valueB]) with self.helper.add_contents(valueA) for tests test_behavior1 and test_behavior2, it will result in a failure in test_behavior5 because self.helper.remove_content(valueB) will end up throwing an error!

Furthermore, for anyone reading these tests, it is not entirely clear that test_behavior1, and test_behavior2 need self.helper to be initialized with values [valueA, valueB], but do not need for controllerA in self.helper. The preconditions for test_behavior1 and test_behavior2 are coupled with the preconditions for test_behavior3.

It also results in test incompleteness in that, if we introduce a bug that causes behavior1 to fail when self.helper.add_controller(controllerA) is not set, we might not catch that bug because we have initialized the test for behavior1 with self.helper.add_controller(controllerA).

How to decouple such tests?

Use the setUp method to simply set up your dependencies, but not to enforce any precondition. Instead, make setting preconditions part of the arrange step of each unit test. You can even encapsulate the precondition setting into a function (with the right parameters) so that the arrange section does not get too bloated, and yet the test code is readable. Consider the following refactoring of the tests:

class SUTTestCase(unittest.TestCase):
    def setUp(self):
        self.helper: Optional[StubHelper] = None
        self.sut = SUT(self.helper)
        
    def prepare_helper(self, contents:List[Value], controller: Optional[Controller]=None) -> None:
        self.helper = StubHelper()
        self.helper.add_contents(contents)
        if controller:
            self.helper.add_controller(controller)
        
    def test_behavior1(self) -> None:
        # Assumes self.helper is a fresh object.
        self.prepare_helper(contents=[valueA, valueB])
        ...

    def test_behavior2(self) -> None:
        # Assumes self.helper is a fresh object.
        self.prepare_helper(contents=[valueA, valueB])
        ...    

    def test_behavior3(self) -> None:
        # Assumes self.helper is a fresh object.
        self.prepare_helper(contents=[valueA, valueB], controller=controllerA)
        ...

    def test_behavior4(self) -> None:
        # Assumes self.helper is a fresh object.
        self.prepare_helper(contents=[valueA, valueB], controller=controllerA)
        ...

    def test_behavior5(self) -> None:
        # Assumes self.helper is a fresh object.
        self.prepare_helper(contents=[valueA], controller=controllerA)
        ...

Coupling in parameterized tests

Parameterized tests are a collection of tests that run the same verification, but with different inputs. While this is a very useful feature (available in almost all unit test frameworks), it is also very easy to abuse. A few common ways I have seen it abused is in conjunction with DRYing, and the use 'if' checks, and that often results in coupling all the tests denoted by the parameterized list. Consider the following illustration:

class TestOutput(typing.NamedTuple):
    status: StatusEnum
    return_value: typing.Optional[int]
    exception: typing.Optional[Exception]
    ...

class TestSequence(unittest.TestCase):
  
    @parameterized.expand([
        [test_input1, expected_output1],
        [test_input2, expected_output2],
        ...
    ])
    def test_something(self, test_input: str, expected_output: TestOutput) -> None:
        self._run_test(test_input, expected_output)
    
    def _run_test(self, test_input: str, expected_output: TestOutput) -> None:
        sut = SUT(...)
        prepare_sut_for_tests(sut, test_input)
        output = sut.do_something(test_input)
        test_output = make_test_output(output, sut)
        self.assertEquals(expected_output, test_output)

The above illustration tests the method do_something for various possible inputs. However, note that the outputs (as illustrated in the class TestOutput can have a status, a return_value, or an exception). This means that every instantiation (for each parameter) has to content with the possibility of different types of outputs even though any single test only should have to verify against a single type of output. This couples all the tests verifying do_something, this making it difficult to read and understand. Adding a new test case here becomes tricky because any changes to either prepare_sut_for_tests, or make_test_output now affects all the tests!

How to decouple parameterized tests?

There are some fairly straightforward ways to decouple such tests. First, is that we should be very conservative about how we organize these tests. For example, we can group all positive tests and group all negative tests separately; similarly, we can further subgroup the tests based on the type of assertions on the output. In the above example, we can have three subgroups: positive tests that verify only output status, positive tests that verify return value, and negative tests that verify exception. Thus you now have three parameterized test classes that look something like this:

class TestDoSomething(unittest.TestCase):
  
    @parameterized.expand([
        [test_status_input1, expected_status_output1],
        [test_status_input2, expected_status_output2],
        ...
    ])
    def test_something_status_only(
        self, 
        test_input: str, 
        expected_output: StatusEnum
    ) -> None:
        # Arrange
        sut = SUT(...)
        ...  # More 'arrange' code
        
        # Act
        output = sut.do_something(test_input)
        output_status = output.status
        
        # Assert
        self.assertEquals(expected_output, output_status)
        
    @parameterized.expand([
        [test_return_value_input1, expected_return_value_output1],
        [test_return_value_input2, expected_return_value_output2],
        ...
    ])
    def test_something_return_value_only(
        self, 
        test_input: str, 
        expected_output: int
    ) -> None:
        # Arrange
        sut = SUT(...)
        ...  # More 'arrange' code
        
        # Act
        output = sut.do_something(test_input)
        output_status = output.status
        output_value = output.value
        
        # Assert
        self.assertEquals(SomeEnum.SUCCESS, output_status)
        self.assertEquals(expected_output, output_value)

    @parameterized.expand([
        [test_return_value_input1, expected_error_code_output1],
        [test_return_value_input2, expected_error_code_output2],
        ...
    ])
    def test_something_throws_exception(
        self,
        test_input: str,
        expected_error_code: int
    ) -> None:
        # Arrange
        sut = SUT(...)
        ...  # More 'arrange' code
        
        # Act
        with self.assertRaises(SomeSUTException) as exception_context:
            sut.do_something(test_input)
        exception = exception_context.exception
        
        # Assert
        self.assertEquals(excepted_error_code, exception.error_code)