Nomos Code: The AST-Constrained Cognitive Substrate for Deterministic Software Engineering

The Fragility of Chat-Centric Coding Agents#

The standard industry paradigm for autonomous coding agents relies on conversational persuasion:

• The model is prompted with generic system guidelines ("Write clean code", "Follow TDD").
• It emits arbitrary shell commands and unstructured diffs.
• When an execution fails, the agent is fed raw stack traces in an uncontrolled chat loop until its context window fragments or hallucinated fixes compound.

In production engineering, this approach collapses under cognitive load. Autonomous agents do not fail because models lack raw token intelligence; they fail because their operating environment lacks mathematical invariants.

To solve real-world software engineering benchmarks (such as SWE-bench Verified) and handle enterprise-grade code refactoring, we designed Nomos Code (nomos-code)—the Tier 2 Tactical Substrate of the Nomos ecosystem.

The Four Core Architectural Axioms#

graph TD
    subgraph IntentPlane ["The Intent Plane (ND // Cognitive Co-Processor)"]
        LLM["Large or Small Language Model<br/>(Local Qwen-27B / Cloud Frontier)"]
        Tangents["Hypothesis Generation & Root-Cause Synthesis"]
    end

    subgraph SubstratePlane ["The Execution Substrate (D // Compiled Go Engine)"]
        State["Deterministic 5-Stage TDD State Machine"]
        AST["AST Pre-Commit & Verification Gates"]
        Sandbox["Transient Worktrees & Docker Sandboxes"]
    end

    LLM -->|"Bounded Function Calls"| State
    State -->|"Non-Verbal Proof & AST Invariants"| AST
    AST -->|"Compile & Regression Verification"| Sandbox

1. Axiom of Dual-Core Division (Substrate Core vs. Intent Core)#

We partition agent execution into two non-overlapping architectural planes:

• Intent Core (Yang / Non-Deterministic): The LLM acts purely as an exploratory heuristic function or bounded cognitive co-processor. It proposes hypotheses, drafts potential bug fixes, and identifies test strategies.
• Substrate Core (Yin / Deterministic): A compiled Go engine manages the workspace state machine, enforces cyclomatic complexity limits, validates import topologies, and runs pre-commit AST guards. The model is never trusted to self-verify; verification is entirely machine-enforced.

2. Axiom of Non-Verbal Proof#

We never ask an LLM if its code works. Instead:

1. It compiles against the native language toolchain.
2. It executes against an ephemeral, isolated reproducer test.
3. It passes 39 binary Definition of Done (DoD) AST quality gates.

If the exit code is non-zero or an AST invariant is violated, the transition is blocked by the substrate, Snap-back rollback mechanics restore the workspace, and the agent is forced to reformulate its hypothesis.

3. Axiom of Ephemeral Sandboxing#

Direct modifications to protected branches (main, develop, substrate) are cryptographically and procedurally locked by pre-commit hooks. Active engineering tasks execute exclusively inside transient isolated worktrees or sandboxed Docker containers:

Lifecycle: Scaffold ➔ Sandboxed TDD Loop ➔ DoD Verification ➔ Atomic Merge & Teardown

4. Axiom of Memory Topology (GitBrain)#

Cognitive context is divided between:

• The Conscious Contract (Unified Vault): Human-readable Markdown specifications and architectural contracts.
• The Machine Subconscious (GitBrain): Ephemeral Git Notes (refs/notes/agent) and high-density vector embeddings that index previous session failures, successful patches, and AST execution traces without polluting the primary source tree.

The 5-Stage TDD State Machine#

Nomos Code (nomos code) enforces a strict, turn-bounded finite state machine for every software repair or feature task:

stateDiagram-v2
    [*] --> Stage1_TestDiscovery: Observe & Pinpoint API
    Stage1_TestDiscovery --> Stage2_Reproducer: Author Isolated Test
    Stage2_Reproducer --> Stage3_ASTEdit: Execute Surgical Patch
    Stage3_ASTEdit --> Stage4_Regression: Run Full Test Suite
    Stage4_Regression --> Stage5_Teardown: Prune Reproducer & Exit
    Stage5_Teardown --> [*]

1. Stage 1 — Test-First Discovery: Before reading source code, the model investigates existing test suites (tests/, testing/). This immediately grounds the model in caller contracts, valid inputs, and expected return types without blind exploration.
2. Stage 2 — Diagnostic Reproducer: The agent authors an isolated, minimal reproduction script (reproduce_issue.py) confirming the defect with an exit code ≠ 0. The substrate's ephemeral reproducer filter ensures this test script is tracked as diagnostic, preventing premature task completion.
3. Stage 3 — AST Surgical Edit: Modifications are executed via structured AST replacement tools (replace_file_content). Search blocks require unique line-level anchoring, whitespace-tolerant AST alignment, and reject empty string payloads to eliminate false positives.
4. Stage 4 — Regression Gate: The reproducer is re-run (confirming exit code 0), followed by the complete repository test suite to guarantee zero upstream regressions.
5. Stage 5 — Clean Teardown: The temporary reproducer is automatically pruned, git status is validated clean, and the final atomic release is synchronized to the base branch.

Local Silicon vs. Cloud Frontier: The Empirical Reality#

A common industry misconception assumes that high-accuracy autonomous software engineering requires massive cloud frontier models (200B+ parameters).

In our empirical evaluations across the SWE-bench Verified Golden Suite, Nomos Code demonstrated that:

• A locally hosted Qwen 3.8 27B open-weight model running on a single consumer RTX 4080 (16 GB VRAM) achieved exact resolution parity (60.0%) with Google's flagship Gemini 3.7 Flash (with 8k Thinking).
• Driven by the Go-native substrate's strict test-first discovery and AST surgical verification, the local 27B model converged in 11.2 mean turns to resolution—matching and exceeding Cloud Gemini 3.7 Flash (12.6 mean turns post-optimization) at zero marginal inference cost.
• Across our broader empirical shootouts, sovereign execution on local RTX 4080 silicon delivered 100% Pass@1 (5/5) in 6.4 mean turns on LiveCodeBench Contamination-Free Suite and 100% Pass@1 (5/5) across Go, Python, Rust, JavaScript, and C++ in 6.2 mean turns on the Aider Polyglot Benchmark.

When the harness guarantees mathematical invariants, smaller open-weight models become lethal software engineering engines—running 100% air-gapped, sovereign, and at zero marginal inference cost.