When specs and code disagree

Series: Aigile deep dives, paper 05 of 09. Elaborates working paper Sections 9 and 10. Depends on Papers 02, 03, 04.

Abstract

Specifications are maps; code and tests are territory. This paper specifies the two protocols that keep them aligned: the deviation protocol, which governs the moment an implementer (human or agent) discovers mid-work that the map is wrong, and the drift-management pipeline, which governs divergence discovered late. Both rest on one observable classification boundary and one philosophical commitment: drift is thermodynamics, not sin, and methodologies that treat it as shameful get hidden drift instead of managed drift. The target variable is drift half-life, the time from divergence to resolution, not drift count.

1. Position in the framework

These are the framework’s mid-loop backward edges (Paper 01, R1): the channels through which implementation learning flows into the ephemeral and durable layers between the intent step and the demo. The atomic PR (Paper 04) is their prevention arm; the constitution (Paper 03) is their escalation target; the retrospective (Paper 08) is their learning arm.

2. The problem in full

2.1 Why deviations are the process working

Implementation is where specification error becomes visible; a spec that survives contact with implementation unchanged is either trivial or unexamined. The design problem is the protocol, because both naive answers destroy the framework: always stopping recreates change-control paralysis (the team learns to stop discovering), and always guessing recreates vibe coding (the map quietly dies). The protocol must make honesty cheap and silence expensive.

2.2 Why self-classification cannot be trusted

The party that wants to deviate is the worst-placed party to judge whether the deviation matters. This is not an accusation of bad faith; it is a conflict of interest plus a competence gap, and it applies to agents with special force: an agent is precisely bad at knowing when its shortcut has behavioral consequences, and letting it decide builds the failure into the protocol. The boundary must therefore be observable, checkable from artifacts rather than from the deviator’s judgment.

2.3 Why drift is inevitable

Even with a perfect deviation protocol, representations of a system diverge: hotfixes enter sideways, dependencies change behavior, the world invalidates assumptions, and prose decays at its ambient rate. Zero drift is not a target; it is a claim that would itself be drift. The honest target is a short drift half-life: divergence detected, classified, and resolved quickly.

3. Mechanism one: the deviation protocol

3.1 The observable boundary

A deviation is behavioral if any acceptance test, public interface, or constitution clause must change to accommodate it. If all tests still pass and no contract moves, it is an implementation detail.

3.2 The tiered response

• Implementation details proceed without stopping, but are logged. The log is retro raw material (Section 5): chronic detail-deviations against one spec section indicate over-specification.
• Behavioral deviations pull the andon cord. The story stops. A consortium convenes under the authority matrix (Paper 07): in collaborative setups, agents recommend options with consequences and a competent human decides; in agentic setups, a lead-architect agent may decide within its mandate. The consortium runs under a latency budget, for example one hour to decision with a defined default on silence, because without the budget the consortium is a change control board and the team will learn to guess rather than ask.
• Constitutional conflicts (the deviation reveals the constitution is wrong or self-contradictory) escalate to the amendment process (Paper 03, R8) and are never patched locally (R10).

Every accepted behavioral deviation ships its spec-diff in the same PR as the code embodying it (R11), resolving the divergence at the moment it is born, when it costs least.

4. Mechanism two: the drift pipeline

Drift is deviation discovered late, and it is managed like defects, in four stages.

4.1 Prevent

The atomic PR closes the main birth channel. Executable criteria shrink the driftable surface (a test cannot drift silently). The derived layer removes the descriptive corpus from the surface entirely (R5). And the spec detail budget governs what prose remains:

Specify at the level of abstraction that changes slowest: what must be true, never what happens to be true. “Orders survive process restart and are queryable by customer within 500 ms” can hold for years; “orders are stored in table orders with columns x, y, z” will drift in weeks. Over-specification is not diligence. It is the manufacture of future drift, and every prose line is a standing liability priced accordingly.

4.2 Detect

• The conformance function, a linter for the map: something reads spec sections against code and tests and reports contradictions (“section 4.2 claims idempotent retries; implementation retries without deduplication”). It produces findings only, never autonomous fixes.
• Freshness metadata: each maintained spec section carries the commit hash at which it was last verified, yielding a spec-freshness metric analogous to test coverage. Drift becomes a number, not an anxiety.
• Scaling: in small teams, the conformance function is a ritual, not a role. Standing vigilance is a task class humans measurably perform badly (the CCTV-wall problem), so nobody is assigned the watchtower; instead the retrospective includes a fifteen-minute agent-assisted sweep (“read section X against the module; list contradictions”). The graduation trigger is evidential, not organizational: when the ritual sweep regularly surfaces more than trivial descriptive drift, the spec surface has outgrown the ritual and a standing conformance agent pays for itself. The methodology names the trigger; the team chooses the tooling.

4.3 Triage

Classification reuses the observable boundary, asked mechanically: what must change to resolve this?

4.4 Learn

Per-section drift frequency is design feedback about the map itself. A chronically drifting section is saying one of two things: it is over-specified and should be demoted (to derived, or deleted), or it expresses something fundamental that keeps being violated and should be promoted to the constitution, where it gains andon teeth. Promotion and demotion execute at gardening (Paper 08).

5. Normative protocol

R15 (Observable classification). Deviation and drift class are determined by what must change (tests, interfaces, constitution), never by the deviator’s or detector’s judgment of importance. R16 (Andon with latency budget). Behavioral deviations stop the story; the deciding authority per the matrix resolves within the standing latency budget; budget breaches are incidents. R17 (Same-PR resolution). Accepted deviations ship their spec-diff with their code-diff. A deviation resolved in code only is reclassified as normative drift. R18 (Findings, not fixes). The conformance function proposes; humans (or matrix-designated authorities) dispose. No representation of the system is corrected autonomously by the instrument that detected the divergence. R19 (Half-life accounting). Every drift finding records detection time and resolution time; the half-life distribution is a first-class health metric reviewed at retro.

6. Orderly worked example

During increment four of consolidated invoicing, the implementing agent finds the spec assumes one currency per billing entity, but a pilot customer has entities transacting in two. Tests must change: behavioral, andon. The consortium (two humans, agent analysis attached) decides in forty minutes: per-currency sub-invoices, spec-diff ships in the same PR. Three weeks later, the ritual conformance sweep finds section 2.1 of the ingestion spec still describing the pre-event-sourcing storage layout (descriptive drift; spec-diff batch-approved, and the section is flagged for demotion, since storage layout is derivable). The same sweep finds retry code violating the idempotency clause introduced by a hotfix that bypassed the loop entirely: normative drift against the constitution, andon, defect story, and a retro item on the hotfix path, which is the real finding. Half-life for the quarter: descriptive median 6 days, normative median 11 days, one constitutional finding resolved in 3 days by clarifying amendment v2.1.1.

7. Failure modes

• Silent guessing: deviations resolved in code without the protocol. Detection: R17 reclassification plus conformance findings clustered around recent increments.
• Andon spam: everything escalated, budget saturated, humans habituate. Counter: the observable boundary is the filter; detail-deviations do not stop the line.
• Watchtower assignment: a human given standing conformance duty, guaranteeing decayed vigilance and ritual blame. Counter: ritual-not-role, and the graduation trigger.
• Drift shame: findings treated as failures, so findings stop. Counter: half-life, not count, is the metric; a rising count with falling half-life is a healthy immune system, not a sicker patient.

8. Metrics

Drift half-life by class (the headline); findings per sweep and their trend; deviation log volume per spec section (over-specification signal); andon frequency and decision latency against budget; hotfix-path bypass count (target zero).

9. Open questions

Optimal sweep cadence as a function of change velocity; whether conformance findings can be risk-ranked reliably enough to prioritize human attention; cross-repo drift when one spec governs several services; formal verification as a third truth anchor for narrow domains.

10. Derivative artifacts

Playbook chapters for both protocols with decision trees; andon consortium runbook (roles, budget, default rules); conformance-agent product requirements (findings format, freshness stamps, half-life accounting); retro sweep script template.