Why CLAUDE.md Fails Hexagonal Architecture: Polyglot Architectural Obligation Proofs#

A 3-Layer Verification & Paired Live-Model Brownfield Audit (Qwen3.8-27B-IQ3_M @ temp = 0.0) Evaluating Open-Core `nomos v4.13.0` Against Ungoverned ReAct Control (CLAUDE.md + Native Unit Tests) Across Python, TypeScript, and Go.

Benchmark Provenance & Three-Layer Verification Receipt
Date Evaluated: November 9, 2026 • Release: Open-Core `nomos v4.13.0` (c3268c9, Apache 2.0)
Layer 1 (Cleanroom Polyglot Adversarial Stress): `cleanroom_obligation_polyglot_stress_test.go` across Python, TypeScript, Rust, and Go (100% fail-closed detection on boundary leaks, missing contract fields, unbound TC-* obligations, and stale upstream specs)
Layer 2 (Live Self-Dogfooding): Active core-purity and modules-independence architecture_boundaries plus TC-OBL-001..010 obligation proofs enforced on the nomos compiler substrate itself (42/42 DoD gates)
Layer 3 (Paired Live-Model Brownfield A/B): 12 deterministic episodes (Qwen3.8-27B-IQ3_M, temperature = 0.0, enable_thinking = false, 40.3 tok/s on local RTX 4080 16GB VRAM) holding system prompt, CLAUDE.md handbook, tools, and turn budget constant

1. The Day-30 Architectural Failure Mode: Green Tests, Rotted Boundaries#

Every experienced systems architect recognizes the gap between functional test pass rates and architectural integrity. When a human or coding agent works inside a multi-module brownfield repository, two silent regressions routinely slip straight past green unit test suites and advisory Markdown prompt files (CLAUDE.md, .cursorrules, AGENTS.md):

1. Convenience-Driven Boundary Erosion: An explicit rule in CLAUDE.md states "Keep domain/ pure: never import from infra/." Yet infra/currency_norm.py (or src/infra/taxEngine.mjs or internal/infra) already exposes a working helper that solves half of today's ticket. Because stochastic coding agents optimize for reaching a passing test exit code (0) in minimum turns, they leave or add the forbidden infra import inside domain/, run pytest / node --test / go test ./..., see PASS, and ship the Coupling leak.
2. Silent Upstream Specification Taint: An architect updates specs/billing_spec.md in commit [INT-2] to add a regulatory field (taxRateBps) and test obligation (TC-BIL-03). Because existing v1 unit tests still exit 0 against the old v1 implementation, unguarded CI pipelines report a green repository while production code silently lags behind its specification contract.

2. Four Compiled Obligation Primitives in nomos v4.13.0#

Instead of asking a probabilistic language model to remember architectural invariants across a decaying context window, nomos v4.13.0 compiles four machine-enforced proofs directly into the single static Go binary (nomos verify, nomos handshake, and nomos hook post-tool):

flowchart LR
    Spec["Markdown Spec SSoT<br/>(Fenced Types + TC-* Table)"] -->|"SHA-256 Receipt"| Notes["Git Notes 2PC Ledger<br/>(refs/notes/nomos/releases)"]
    Notes -->|"Turn-0 Taint Diff"| Handshake["nomos handshake<br/>(Stale Spec Alert)"]
    Edit["Agent File Write<br/>(Hermetic SUB-* Worktree)"] -->|"< 5 ms PostToolUse"| Radar["Fast-File Boundary Radar<br/>(11-Language Import Check)"]
    Spec -->|"strict_types + verify_obligations"| Gate["IntentTraceabilityGate<br/>(Contract Parity + @verifies TC-*)"]
    Edit --> Gate
    Gate -->|"42/42 Gates Exit 0"| Sync["nomos task sync<br/>(Atomic Merge + New Spec SHA)"]

Scope Boundary: Structural & Trace-Binding Enforcement vs. Semantic Theorem Proving
We use obligation proofs in the pragmatic systems-engineering sense: machine-checked AST import locks, declared field parity, explicit test-to-vector binding (@verifies TC-*), and SHA-256 specification taint receipts. These checks deliberately trade full semantic theorem proving (TLA+, Lean, Coq), dynamic FFI/reflection analysis, and algorithmic equivalence proofs for <5ms execution speed that developers and agents keep enabled on every single edit. Domain invariants inside a test body remain the responsibility of executable unit/property tests and senior design review.

3. Layer 3 Paired Brownfield Benchmark (Qwen3.8-27B, temp = 0.0)#

To isolate the exact causal effect of compiled obligation proofs without vendor CLI noise, both arms executed inside the exact same 5-tool JSON ReAct agent loop (read_files, write_file, run_tests, git_log, finish; 12-turn cap) over Qwen3.8-27B-IQ3_M (temperature = 0.0, non-thinking 40.3 tok/s execution on local RTX 4080 silicon) across Python, TypeScript, and Go multi-module brownfield repositories (5 specifications, 12+ source/adapter/test files, and an identical 45-line CLAUDE.md Service Engineering Handbook explicitly stating all hexagonal boundary, contract-field, and @verifies TC-* rules):

1. Control Arm (CLAUDE.md + Native Unit Tests): Receives the full CLAUDE.md handbook on Turn 0 and completes (finish) as soon as the native language test suite (python3 -m unittest, node --test, go test ./...) exits 0 - zero Nomos worktree isolation, handshake, or AST gate checks.
2. Nomos v4.13.0 Arm (Identical ReAct Loop + Nomos Hooks): Runs the identical prompt, model, and 5 tools, plus Nomos's three standard indirect-control hooks: Turn-0 nomos handshake --json stale-obligation banner inside an isolated nomos task chore worktree, PostToolUse nomos verify feedback after write_file, and 42/42 nomos verify enforcement on finish.

Each repository was evaluated across two brownfield lifecycle stages:

• Stage A (Brownfield Feature Build Under Convenience Pressure): Complete the domain implementation and unit tests for specs/ledger_spec.md (Python), specs/billing_spec.md (TypeScript), and specs/order_spec.md (Go) inside a repository where domain/ currently imports a working validation helper from infra/ and unit tests exit 0.
• Stage B (Upstream Compliance Spec Evolution): All 5 service modules and unit tests pass 100% after [SUB-1], followed by an upstream [INT-2] commit adding a new required contract field (settled, taxRateBps, IdempotencyKey) and TC-*-03 obligation while v1 unit tests continue exiting 0.

Paired 12-Episode Results#

Why Control Failed 3 / 3 Stage A Runs Despite Explicit CLAUDE.md Rules#

In every single Stage A episode (Python, TypeScript, and Go), the Control agent read CLAUDE.md on Turn 1, read the specification and domain source file on Turn 2, added the missing schema_version / ledgerVersion / SchemaVersion field and @verifies TC-* unit tests, ran the native test runner (unittest / node --test / go test ./...), observed exit code 0, and immediately called finish. Because keeping the existing infra import already satisfied every functional assertion in the specification, advisory prose in CLAUDE.md exerted zero corrective force once tests turned green.

Under Nomos v4.13.0, the moment the agent wrote the domain file inside its isolated worktrees/<project>-SUB-1 sandbox, nomos verify returned a deterministic architectural boundary diagnostic:

⚠️ [Intent Traceability Validation Gate] architecture boundary violation(s):
   src/domain/invoice.mjs imports forbidden package "../infra/taxEngine.mjs"
   (rule "ts-domain-purity" forbids "src/infra/**")

Presented with a non-negotiable exit 1 and exact rule provenance, the exact same local Qwen3.8-27B model inlined pure domain validation on the very next turn (+1 turn in Python and TypeScript, +2 turns in Go; +9.4s mean wall-clock delta) and converged cleanly across all 42/42 gates.

Meanwhile, in Stage B, while Control succeeded in a 5-spec repository only by brute-force reading every spec file in the directory, Nomos v4.13.0 surfaced the exact tainted specification in O(1) at Turn 0 via nomos handshake (Stale Spec Obligations (1): specs/billing_spec.md, last verified by SUB-1) - a capability that scales cleanly to enterprise monorepos with 50+ specifications where reading every Markdown file on session boot is impossible.

4. Adopting Obligation Proofs in Any Brownfield Repository (60 Seconds)#

Install or upgrade Open-Core nomos (v4.13.0+, Apache 2.0, single static binary with zero cloud dependencies):

curl -fsSL https://sophialabs.ca/install | bash

Then declare your layer boundaries and specification obligation contracts in nomos.yaml:

governance:
  quality_gates:
    intent_source_roots:
      - "specs"
    architecture_boundaries:
      - name: "domain-purity"
        from: "src/domain/**"
        forbid_imports:
          - "src/infra/**"
          - "src/adapters/**"
    contracts:
      contracts:
        enabled: true
        spec_roots:
          - "specs"
        strict_types: true
        verify_obligations: true
        fail_on_stale_obligations: true

From that commit forward, nomos.yaml is pinned against main so coding agents cannot weaken your boundary rules inside a task worktree, PostToolUse hooks flag forbidden cross-layer imports in <5ms, and every SUB-* release stamps cryptographic specification SHA-256 provenance into refs/notes/nomos/releases.