Expectation-Driven Development is not primarily a testing technique. It is governance for acceptance: implementations, tests, and agents may produce evidence, but none may define the expected outcome or grant itself PASS. A change passes only when the system reproduces a protected, approved expectation through the declared write path.
AI did not create the verification problem. It made it impossible to ignore.
01 / The blind spot
Testing remains necessary, but a test is a question inside an authored boundary—not the authority that decides what “done” means. Normal development asks the implementation team to produce both the code and the proof that the code works. That is efficient, but it is not independent. When the same misunderstanding shapes the implementation and its tests, both can be wrong in the same direction.
The dangerous failure is not red. It is green for the wrong reason.
The familiar loop
If neither author imagined the missing field, the overwritten value, or the untouched neighboring record, the check never asks about it. Green means the asked questions passed.
The EDD break
The application must reconstruct the governed outcome through its declared entry point. Neither the evaluated application nor its implementing agent may rewrite the answer key, silently ignore unknown state, or mint the verdict.
02 / The mechanism
EDD is a method. Gold-State Parity™ is its deterministic acceptance gate. The gate separates what is being built from the authority that decides whether it is right.
A trusted, versioned gold state holds the approved data and outcomes. It is governed outside the code-writing agent’s unreviewed write authority.
The system receives only the inputs an ordinary user could supply through the declared interface. The evaluated application cannot read the protected expected state at runtime.
After the write path reaches a declared stable point, the gate captures the resulting business state, related records, and named durable effects.
Every in-scope observable must be compared, translated, checked by a named invariant, or explicitly delegated. Missing, stale, ambiguous, or newly unclassified state stops the run.
No agent votes on PASS. An agent may diagnose a failure and propose a repair. The accept-or-reject path remains deterministic, and the repair does not count until the gate independently witnesses it again.
03 / The failure that looks like success
Imagine a subscription record with a service level. Months later, someone changes only its renewal date. The renewal form rebuilds the whole record from the fields on that screen. Service level is not on that screen, so the update quietly writes an empty value over it.
The test is not careless. It proves the renewal date changed and the save succeeded. Both statements are true.
The defect lives in the fact nobody thought to assert: what must remain unchanged.
EDD turns that loss from a review hunch into a named disagreement: this record, this field, expected this value, received that one.
04 / Making it real at scale
Driving a full production-sized corpus through a real interface would be too slow. EDD divides the proof obligation without pretending either half proves the other.
Proof · /prove · deep and narrow
The real UI is driven through ordinary interactions. It establishes declared interface obligations, selected end-to-end state parity, and the exact command variants observed at the capture boundary.
Validate · /validate · broad and below the boundary
The official command entry point processes the volume, but only through command shapes tethered to passing Proof evidence for the same declared identity. An unseen or ambiguous shape is a hard failure.
A green Validate run cannot repair a missing interface trace. A green Proof run cannot establish full-corpus fidelity. Green is always scoped to the versioned behaviors and observables actually inside the gate.
05 / Intertwined with the codebase
Tests remain evidence; they are not acceptance authority. In the reference application, EDD became four linked enforcement layers so that an incomplete, stale, bypassed, or misremembered check cannot quietly redefine done.
In the implemented design, /prove drives selected scenarios through the real UI. /validate drives the full in-scope corpus through command shapes the UI proved for the same evidence identity. Both compare persisted state with the protected known-good state.
Repository hooks and CI refuse a commit or push when required evidence is missing, stale, or bound to a different build. “I ran it earlier” is not an acceptable substitute for current evidence.
Architecture Decision Records preserve why a rule, scope boundary, or exemption exists. The next person—or agent—does not get to re-litigate it from memory.
Architecture tests fail the build when executable behavior and the governing ADR disagree. The decision is not merely documentation; it has an enforcement path.
The implementation rule is simple: if a load-bearing constraint depends on memory, give it an executable failure path.
06 / The evidence
The parity exercise was seeded to isolate what persisted from what the interface-level checks believed had happened. It demonstrates a conviction stage for a narrow fault class, not organic discovery or a detection rate.
A later source audit established that two of sixteen planned mutants were executed. Those seeded runs produced seven reported parity failures while the corresponding behavioural checks remained green. The other fourteen outcomes were computed predictions, not observations.
This corrects the earlier 7/7 shorthand. It is a bounded conviction-stage demonstration, not a discovery or detection-rate claim. Read the public correction to Field Report 1. The artifacts are proprietary and not independently auditable, and no current full-chain run is claimed.
A gate compared a token to itself, so one branch reported success while skipping its intended check. Its enforcement test read source text differently from runtime execution. A proposed exemption sounded right until measurement proved it wrong.
A sanitized practitioner incident from a separate application. The source artifacts are proprietary and the account is not independently auditable.
A real green-for-the-wrong-reason chain
The lesson was not abstract. A vocabulary-renaming gate and the controls around it exposed three different ways verification can lie while looking disciplined.
A typo made one branch compare a token with itself. The condition always matched, so files carrying the retired spelling were silently skipped while the gate reported success.
The architecture test inferred behavior from source text, but the shell computed something different at runtime. A one-character change could bypass the affected gate branch while its test stayed green.
Three proposed exemptions sounded reasonable. The gate measured instead of agreeing, and one of the three justifications did not survive the evidence.
Three failures in the assurance chain. A careful-looking review and a green check had not made them visible.
07 / What changes for us
EDD does not ask teammates to speak more confidently. It asks them to make smaller, sharper claims that survive contact with evidence.
08 / The price
A method that distrusts implementation evidence must also distrust its own comparator, projections, fixtures, gates, and evidence lineage. That recursion can find switched-off safety checks. It can also become a machine that mostly audits itself.
Where it earns its keep
A write path that runs everywhere, a gate that controls every push, a data transformation that can corrupt neighboring records—these fail quietly and are costly to reconstruct by eye.
Where it becomes tax
If a mistake is obvious, contained, and inexpensive to repair, adding layers of oracle machinery can cost more than the defect class it is meant to catch.
One rename, fully enforced
Five commits. Three review rounds. The first round found the switched-off safety check. The next two increasingly audited the auditors.
The sequence is retained; product, repository, file, test, and decision identifiers are deliberately omitted.
The recursion is real
The test that checks the ADR is itself unchecked code. A test checking that test would also be unchecked. People still have to decide when the remaining blast radius no longer justifies another layer.
Depth of enforcement should key to blast radius, not principle.
EDD has kill conditions. If oracle maintenance exceeds the review effort displaced, escaped defects remain comparable to review-only development, the gate becomes too slow or flaky, fault-injection detection stays poor, or oracle changes become coupled to ordinary implementation changes, the economics have failed.
The whole method in three words
EDD is not certainty, and it is not merely more testing. It is a disciplined refusal to confuse confidence with evidence—and a way to localize failure without giving the implementation, its tests, or the repairing agent authority over the verdict.