Dual-Core Architecture: Substrate Core (Yin) vs. Intent Core (Yang)

The Bifurcation of Intelligence#

In modern agentic systems, the greatest source of failure is the blurring of lines between reasoning and execution. When an LLM is given direct access to a file system or a compiler without a mediating layer, the result is "Cognitive Drift"—a state where the model's probabilistic nature overrides the codebase's deterministic requirements.

The Dual-Core Architecture solves this by enforcing a hard physical and logical separation between two fundamental planes of operation: the Substrate Core (Yin) and the Intent Core (Yang).

1. Substrate Core (Yin): The Deterministic Engine (The "How")#

Substrate Core is the bedrock of the system. It is composed of compiled, type-safe, and mathematically verifiable code (primarily Go). It does not "think"; it executes.

Characteristics of Substrate Core:#

• Deterministic: Given the same input and state, it always produces the same output.
• Invariant-Driven: It operates based on strict rules (e.g., "Cyclomatic complexity must be ≤ 15", "All functions must have docstrings").
• Non-Probabilistic: It does not use tokens or temperature. It uses AST (Abstract Syntax Tree) parsing, regex, and binary execution.
• The Gatekeeper: It is the final authority. If Substrate Core says a change violates a rule, the change is rejected, regardless of how "smart" the reasoning layer claims it is.

Components:#

• The AST Parser: Analyzes code structure to ensure compliance.
• The Sandbox (Worktree): Provides an ephemeral, isolated environment for mutations.
• The DoD Gatekeeper: A suite of 39 automated, machine-enforced AST checks that must pass before any state change is committed.

2. Intent Core (Yang): The Non-Deterministic Reasoning Plane (The "What")#

Intent Core is the cognitive layer. It is composed of Large Language Models (LLMs) and Small Language Models (SLMs) operating in a high-entropy, probabilistic space. It is responsible for planning, reasoning, and intent synthesis.

Characteristics of Intent Core:#

• Probabilistic: It operates on the likelihood of the next token. It is inherently uncertain.
• Heuristic-Driven: It uses patterns, semantic understanding, and "intuition" to solve complex problems.
• High-Entropy: It is capable of creative leaps and architectural synthesis that a deterministic engine cannot perform.
• The Architect: It proposes what should happen, but it has no inherent power to make it happen.

Components:#

• The Planner (nomos task plan / /nomos-plan): Decomposes high-level goals into a Directed Acyclic Graph (DAG) of subtasks.
• The Solver (nomos code / nomos-code): Generates code patches based on the plan.
• The Auditor (nomos audit / /nomos-deep-review): Performs adversarial reasoning and first-principles red-teaming.

The Dual-Core Interface: The Cognitive Bridge#

The magic of this architecture lies in the Interface—the protocol by which Intent Core communicates its desires to Substrate Core.

1. Intent Proposal: Intent Core generates a structured plan (e.g., a Markdown specification or AST diff proposal).
2. Validation Request: The plan is passed to Substrate Core.
3. Deterministic Verification: Substrate Core checks the plan against the current AST and system invariants.
4. Execution/Rejection:
   • If the plan is valid, Substrate Core executes the mutation inside an isolated transient worktree sandbox.
   • If the plan is invalid (e.g., "This change will increase complexity to 18"), Substrate Core rejects the proposal and returns a Structured Error Trace to Intent Core.
5. Feedback Loop: Intent Core receives the error, reasons about the constraint, and proposes a revised plan.

sequenceDiagram
    participant Yang as Intent Core / Yang (LLM/SLM)
    participant Bridge as Cognitive Bridge (API/Protocol)
    participant Yin as Substrate Core / Yin (Go Engine)
    participant Code as Codebase

    Yang->>Bridge: Propose Plan (Spec / Diff)
    Bridge->>Yin: Validate Plan against Invariants
    alt Plan is Valid
        Yin->>Code: Apply Mutation (Worktree Sandbox)
        Code-->>Yin: Success (39 DoD Gates Passed)
        Yin-->>Bridge: Commit Success (2PC)
        Bridge-->>Yang: Plan Executed & Synced
    else Plan is Invalid
        Yin-->>Bridge: Reject (Error: Complexity Violation)
        Bridge-->>Yang: Error Trace (Constraint: Complexity < 15)
        Note over Yang: Reasoning: "I must refactor the function..."
        Yang->>Bridge: Propose Revised Plan
    end

Summary: Why Bifurcation Matters#

By separating the Probabilistic Intent from the Deterministic Execution, we achieve:

• Safety: The LLM can never "hallucinate" a valid file structure or bypass AST gates.
• Reliability: The system's state is always governed by code and machine verification, not prompts.
• Scalability: We can swap out or upgrade the LLM (Intent Core) without ever changing the core engineering rules (Substrate Core).

This is the foundation of the Nomos philosophy: Harness the intelligence, but trust the substrate.