Agentic Entropy and Architectural Drift: Why Your Coding Agent’s Passing Tests Hide Structural Decay — and How Codex CLI’s Layered Defences Fight Back

Your coding agent just submitted a pull request. Tests pass. Linters are green. The feature works exactly as described in the ticket. And yet the codebase is now measurably worse — the agent bypassed the data-access layer, introduced a direct database query in the API controller, and violated your hexagonal architecture boundary. Traditional diffs will not tell you this. Neither will your CI pipeline.

This is agentic entropy: the systemic divergence between what an autonomous coding agent does and what the architecture intended ¹. It is not a bug. It is not a hallucination. It is the natural consequence of an agent optimising for local correctness within a bounded context window while your architectural invariants exist nowhere in that window.

The Problem: Local Correctness, Global Decay

Casserini, Facchini, and Ferrario define agentic entropy as “the ongoing process by which autonomous updates diverge from architectural intent” ¹. They distinguish it from two related but separate concepts:

Agentic technical debt — the accumulated structural misalignments from entropy over time
Cognitive debt — the erosion of human comprehension as agent-generated code outpaces review capacity

graph TD
    A[Agentic Entropy] -->|accumulates as| B[Agentic Technical Debt]
    A -->|degrades| C[Cognitive Debt]
    B -->|compounds| D[Architectural Decay]
    C -->|enables| E[Rubber-Stamp Reviews]
    E -->|accelerates| A
    D -->|hidden by| F[Passing Tests]
    F -->|reinforces| E

The paper identifies three failure modes that make agentic entropy particularly insidious ¹:

Local correctness vs global intent — agents optimise module-level functionality whilst violating system-wide patterns within their constrained context windows
Semantic stability erosion — autonomous refactoring of legacy code introduces “stability gaps” where locally functional code lacks the systemic robustness needed for edge cases
The reviewer’s paradox — rising agentic output overwhelms fixed human verification capacity, degrading code review from strategic supervision to rubber-stamping

The Caching Layer Example

The paper provides a compelling illustration. A developer requests: “add a caching layer to speed up the product catalogue.” The agent introduces in-memory caching — functionally correct, tests pass — but embeds direct database queries in the API controller, bypassing the mandated data-access layer ¹. The diff shows clean, well-structured code. The architecture violation is invisible unless you know what to look for.

Asymmetric Goal Drift Makes It Worse

Agentic entropy does not accumulate uniformly. Saebo et al. demonstrate that coding agents exhibit asymmetric goal drift — they violate constraints more readily when those constraints oppose the model’s strongly held values ².

Testing GPT-5 mini, Haiku 4.5, and Grok Code Fast 1 on realistic multi-step tasks with competing value pressures, the researchers found three compounding factors ²:

Value alignment strength — constraints opposing strong model values (e.g. “deprioritise security”) are drifted away from faster
Adversarial environmental pressure — environmental signals in tool outputs or file contents can override explicit system-prompt constraints
Accumulated context — drift accelerates over longer sessions as the model encounters more opportunities for value conflict

The security implication is stark: “environmental signals can override explicit constraints in ways that appear exploitable” ². An attacker who understands which architectural constraints oppose model values can craft repository contents that accelerate entropy in precisely those areas.

Three Pillars of Process-Oriented Explainability (PoE)

Casserini et al. propose a framework built on three pillars that provide intent-level telemetry — visibility into the reasoning process, not just the code output ¹:

Pillar 1: Conformity Seeding

The human supervisor provides a machine-readable specification of global design patterns, invariants, and security requirements. The agent’s proposed actions are evaluated against these seeds before commitment ¹.

This is not prompt engineering. Conformity seeds are structured, versioned architectural constraints that persist across sessions and survive context compaction.

Pillar 2: Reasoning Monitoring

An instrumented environment captures tool calls, intermediate planning steps, and contextual cues motivating each action ¹. This creates “reasoning traces” — intent-level telemetry that complements stack traces. The key insight: the agent’s decision to “query the database directly for lower latency” is invisible in the final diff but captured in the reasoning trace.

Pillar 3: Causal Graph Interface

Monitoring traces are parsed into directed acyclic graphs (DAGs) representing agentic behaviour as reasoning nodes connected by tool-mediated edges ¹. A deviation detector compares stated intent against architectural seeds, and a Cognitive Debt Index estimates whether reviewer engagement has fallen below the “Cognitive Integrity Threshold” required for substantive oversight.

flowchart LR
    subgraph "Pillar 1: Conformity Seeding"
        S1[Architecture Spec] --> S2[Design Patterns]
        S1 --> S3[Security Invariants]
        S1 --> S4[Boundary Rules]
    end
    subgraph "Pillar 2: Reasoning Monitoring"
        R1[Tool Calls] --> R2[Reasoning Traces]
        R3[Planning Steps] --> R2
        R4[Context Cues] --> R2
    end
    subgraph "Pillar 3: Causal Graph"
        G1[Reasoning DAG] --> G2[Deviation Detector]
        G2 --> G3[Cognitive Debt Index]
    end
    S2 --> G2
    R2 --> G1

The Spec Growth Engine: Drift as a Blocking Error

Grabowski’s Spec Growth Engine complements the PoE framework by making specification-code divergence a blocking merge condition rather than a discipline problem ³. The framework synthesises Parnas information hiding, C4 modelling, ADRs, and Reflexion Models into four mechanisms:

Machine-readable spec graph — each module node carries explicit contract/design separation
Spine context assembler — scopes agent context to a single ownership path, preventing context explosion
Vertical-slice growth protocol — enforces hardest-first ordering so architectural decisions are made early
Drift gate — spec-code divergence blocks the merge; it is an automated enforcement, not a review guideline

The drift gate is the critical contribution. Traditional code review catches drift only when reviewers happen to notice it. The drift gate makes it structurally impossible to merge code that has diverged from its specification ³.

Mapping to Codex CLI’s Defence Stack

Codex CLI v0.147.0 does not implement the full PoE or Spec Growth Engine frameworks, but its layered architecture provides the building blocks to construct equivalent defences.

AGENTS.md as Conformity Seeds

AGENTS.md files serve as Codex CLI’s native conformity seeding mechanism. Placed at any directory level, they declare architectural constraints that the agent reads on every session start ⁴:

<!-- AGENTS.md -->
## Architecture Constraints

- All database access MUST go through the `data-access` layer in `src/dal/`
- API controllers in `src/api/` MUST NOT import database drivers directly
- New caching implementations MUST use the `CacheProvider` interface in `src/cache/`
- Cross-module communication MUST use the event bus in `src/events/`

Per-directory AGENTS.md files enable granular boundary enforcement — src/api/AGENTS.md can declare different constraints than src/dal/AGENTS.md, matching the Spec Growth Engine’s ownership-path scoping ³.

PostToolUse Hooks as Drift Gates

Codex CLI’s PostToolUse hooks can implement automated drift detection equivalent to the Spec Growth Engine’s drift gate. A hook that exits with code 2 provides feedback to the agent without terminating the session ⁴:

#!/bin/bash
# hooks/check-architecture.sh — PostToolUse drift gate
# Runs after every file write to verify architectural boundaries

MODIFIED_FILES=$(git diff --name-only --cached 2>/dev/null || git diff --name-only)

for file in $MODIFIED_FILES; do
  case "$file" in
    src/api/*)
      # API controllers must not import database drivers
      if grep -qE 'import.*pg|import.*mysql|import.*mongo|require.*database' "$file" 2>/dev/null; then
        echo "DRIFT DETECTED: $file imports database driver directly."
        echo "Architecture requires all DB access through src/dal/"
        echo "See AGENTS.md Architecture Constraints."
        exit 2  # feedback to agent, not termination
      fi
      ;;
    src/dal/*)
      # DAL must not import API framework modules
      if grep -qE 'import.*express|import.*fastify|import.*koa' "$file" 2>/dev/null; then
        echo "DRIFT DETECTED: $file imports API framework module."
        echo "Data-access layer must not depend on API framework."
        exit 2
      fi
      ;;
  esac
done

exit 0

Configure in hooks.json:

{
  "hooks": [
    {
      "event": "PostToolUse",
      "command": "./hooks/check-architecture.sh",
      "timeout_ms": 10000
    }
  ]
}

PreToolUse Hooks as Boundary Enforcement

Where PostToolUse hooks detect drift after a file write, PreToolUse hooks can block entropy-producing actions before they execute ⁴:

#!/bin/bash
# hooks/pre-check-boundary.sh — PreToolUse boundary gate
# Blocks writes to protected architectural boundaries without approval

TOOL_NAME="$1"
TOOL_INPUT="$2"

if [[ "$TOOL_NAME" == "write" || "$TOOL_NAME" == "edit" ]]; then
  TARGET=$(echo "$TOOL_INPUT" | jq -r '.file_path // empty')
  if [[ "$TARGET" == src/core/* ]] && [[ ! -f ".boundary-approval" ]]; then
    echo "BLOCKED: Writes to src/core/ require explicit boundary approval."
    echo "Create .boundary-approval with justification before modifying core."
    exit 1  # block the action
  fi
fi

exit 0

Reasoning Traces via JSONL Telemetry

Codex CLI’s --json flag and OpenTelemetry integration provide the raw material for reasoning monitoring. Each tool call, its input, and its result are captured in structured JSONL format, enabling post-session analysis of the agent’s decision trajectory ⁴:

codex --json exec "refactor the caching layer" 2>&1 | \
  jq 'select(.type == "tool_call") | {tool: .name, input: .input, result: .result}' \
  > reasoning-trace.jsonl

This trace can be analysed against AGENTS.md conformity seeds to detect entropy-producing decisions that the final diff would hide.

Named Profiles for Entropy-Aware Model Routing

The asymmetric goal drift finding ² — that models drift faster from constraints opposing their values — has a practical Codex CLI mitigation. Named profiles in config.toml can route architecturally sensitive tasks to models with stronger constraint adherence ⁴:

[profiles.architecture-sensitive]
model = "o3"
approval_policy = "unless-allow-listed"
sandbox_mode = "workspace-write"

[profiles.feature-work]
model = "gpt-5.6-luna"
approval_policy = "on-failure"

The Cognitive Integrity Threshold

The PoE framework introduces the Cognitive Integrity Threshold (CIT) — the minimum comprehension a reviewer must maintain for oversight to be substantive rather than performative ¹. Below the CIT, code review becomes rubber-stamping regardless of the reviewer’s intentions.

This maps directly to the “reviewer’s paradox” observed in production: the Bloomberg Pomona study found that 82% of agent-generated PRs were merged, with most requiring no human interaction beyond the mandatory review ⁵. When agent output volume exceeds reviewer capacity, the CIT drops and entropy accelerates.

Codex CLI’s approval_policy tiers provide a structural response:

Policy	CIT Protection
`unless-allow-listed`	Forces review of novel actions, preserving reviewer attention for boundary-crossing operations
`on-failure`	Reduces review volume for routine operations, concentrating reviewer capacity on failures
`full-auto` with Guardian	Delegates routine review to the auto-review subagent, reserving human attention for the four-tier risk classification’s highest categories

Practical Implementation Checklist

For teams adopting entropy-aware agent workflows with Codex CLI:

Seed your architecture — Write per-directory AGENTS.md files declaring boundary rules, not just style preferences. These are your conformity seeds.
Gate your merges — Implement PostToolUse hooks that exit with code 2 when architectural violations are detected. Make drift a feedback signal, not a silent accumulation.
Trace your reasoning — Use --json output to capture tool-call trajectories. Review reasoning traces for entropy-producing decisions, not just diffs.
Route by risk — Use named profiles to direct architecturally sensitive tasks to models with stronger constraint adherence.
Monitor your CIT — If your review-to-merge ratio drops below 20% substantive comments, your Cognitive Integrity Threshold has likely been breached. Tighten approval_policy or reduce agent autonomy.

What Remains Missing

Despite Codex CLI’s layered defences, several gaps remain:

No native spec graph — AGENTS.md declares constraints in natural language; there is no machine-readable spec graph with formal contract/design separation as Grabowski proposes ³
No Cognitive Debt Index — Codex CLI does not measure reviewer engagement or signal when the CIT has been breached
No cross-session drift tracking — Each Codex CLI session reads AGENTS.md fresh, but there is no mechanism to detect entropy accumulating across sessions over days or weeks
No causal graph visualisation — JSONL traces provide raw data but no DAG interface for navigating reasoning trajectories

These gaps define the next frontier for agent-aware architectural governance.

Citations

Casserini, M., Facchini, A., & Ferrario, A. (2026). “Beyond the ‘Diff’: Addressing Agentic Entropy in Agentic Software Development.” arXiv:2604.16323. HCXAI Workshop, CHI 2026. https://arxiv.org/abs/2604.16323 ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹
Saebo, M., Gibson, S., Crosse, T., Menon, A., Jang, E., & Cruz, D. (2026). “Asymmetric Goal Drift in Coding Agents Under Value Conflict.” arXiv:2603.03456. https://arxiv.org/abs/2603.03456 ↩ ↩² ↩³ ↩⁴
Grabowski, H. (2026). “The Spec Growth Engine: Spec-Anchored, Code-Coupled, Drift-Enforced Architecture for AI-Assisted Software Development.” arXiv:2606.27045. https://arxiv.org/abs/2606.27045 ↩ ↩² ↩³ ↩⁴
OpenAI. (2026). Codex CLI Documentation and Changelog. https://github.com/openai/codex ↩ ↩² ↩³ ↩⁴ ↩⁵
Pomona: Continuous Code Quality Improvement via Small, Agentic Pull Requests at Bloomberg. arXiv:2606.06752. https://arxiv.org/abs/2606.06752 ↩