Deterministic Cognitive Scaffolding: Tier 1 Orchestrators vs. Tier 2 Autonomous Swarms

The Paradigm: Machine-Enforced Workflow Parity#

At the heart of the AI coding era is Deterministic Cognitive Scaffolding. This paradigm transitions AI from being an unstructured text-generation tool to a bounded execution engine.

Human workflows are captured as non-deterministic intents (the playbook) and are strictly bound by a rigid, unyielding Go-native binary engine (the substrate). This prevents hallucinations, enforces Definition of Done (DoD) quality gates, and allows workflow automation to scale exponentially.

The Two Layers of Nomos (Dual-Core Architecture)#

flowchart TD
    subgraph IntentPlane ["1. The Intent Plane (The Cognitive Layer)"]
        Playbook["Markdown Playbooks & Workflows (.md)"]
        SwarmPrompt["Swarm Prompts & Discoveries"]
        Intent["Non-Deterministic Goals ('What')"]
    end

    subgraph Substrate ["2. The Execution Substrate (The Mechanic Layer)"]
        GoBinary["Compiled Go Engine (bin/nomos)"]
        ASTParser["AST Parsers & Invariant Gates"]
        WorktreeEngine["Transient Sandboxed Worktrees"]
        SQLiteDAG["Cryptographic State (nomos_global.db)"]
    end

    IntentPlane -->|Non-Deterministic Reasoning| Substrate
    Substrate -->|Physical Machine Verification| Codebase["Production Codebase"]

1. The Intent Plane (The Cognitive Layer)#

• Medium: Markdown Playbooks (.md), Swarm Prompts, Cognitive Workflows.
• Function: This is the non-deterministic conscious contract. It handles ambiguity, defines high-level architectural goals, and orchestrates the "What". It is flexible, exploratory, and inherently human-readable.

2. The Execution Substrate (The Mechanic Layer)#

• Medium: Compiled Go Binaries (bin/nomos), AST Parsers, Telemetry Daemons.
• Function: This is the strict, deterministic verification boundary. It enforces the "How" and physically modifies the workspace. It mechanically applies rules (complexity limits, phase locking, compilation checks) to ensure the Intent Plane cannot hallucinate its way into breaking the system.

The Cognitive Inversion: Harness Over Model#

In conventional prompt engineering, developers try to build complex chain-of-thought prompts to persuade an LLM to behave:

"Please check for race conditions. Please make sure cyclomatic complexity does not exceed 15. Please do not touch main."

In Nomos, we have completely inverted the control flow:

The deterministic Go engine runs the core loop, 
and it calls the LLM as a bounded 'cognitive co-processor' or 'heuristic function'.

Nomos is not an IDE plugin—it is your exact engineering standards compiled into a deterministic runtime harness. Prevention is an order-of-magnitude cheaper than post-hoc sweeping.

The Cognitive Co-Processor Taxonomy#

In this inverted architecture, Large and Small Language Models are never the "master controllers" of the repository. Instead, the Go substrate engine calls different tiers of Cognitive Co-Processors depending on the cognitive depth and operational velocity required:

graph TD
    Substrate[Deterministic Go Engine / nomos Harness]
    
    Substrate -->|Calls for Intent & Planning| T1[Tier 1: Conscious Architect Co-Processor<br/>Frontier IDE Orchestrator]
    Substrate -->|Calls for Headless TDD Execution| T2[Tier 2: Headless Mechanical Solver<br/>Nomos Code Worker]
    
    T1 -->|Outputs Plan / Spec / Approval| Substrate
    T2 -->|Outputs Code Patch in Worktree| Substrate
    
    Substrate -->|Evaluates Non-Verbal Proof| DoD[39 Binary DoD Quality Gates]

Tier 1: The Conscious Architect (Frontier IDE Orchestrator)#

• Role: High-level reasoning, intent synthesis, strategic decomposition, and release approval.
• Operational Medium: Interactive IDE canvas (Antigravity IDE / VS Code) pair-programming with a Human Product Owner.
• Invoked During: PLAN, SPEC, AUDIT, REVIEW, and Human PO negotiation (/grill-me).
• Cognitive Profile: Frontier reasoning models (e.g. Gemini 3.7 Pro, Claude 3.7 Sonnet) evaluated for deep semantic comprehension and topological design.

Tier 2: The Headless Mechanical Solver (Nomos Code Worker)#

• Role: Turn-bounded, high-velocity code mutation, syntax fixing, and TDD iteration.
• Operational Medium: Headless background execution daemons running inside isolated, transient Git worktree sandboxes (worktrees/<repo>-<task>).
• Invoked During: EDIT phase.
• Cognitive Profile: High-throughput open-weight models (e.g. local Gemma-4-26B / Qwen-27B on RTX 4080 silicon) or cost-efficient cloud models optimized for rapid tool calling and AST diffs.

Declarative Domain Routing & The Failover Escalation Ladder#

To prevent cognitive drift while optimizing inference economics, Nomos configures cognitive delegation declaratively in ~/.nomos/data/config.yaml:

# Declarative Cognitive Domain Routing
domains:
  triage:            { tier: 1, model: "gemini-3.7-flash", fallback: "local" }
  spec:              { tier: 1, model: "gemini-3.7-flash", fallback: "local" }
  planning:          { tier: 1, model: "gemini-3.7-flash", fallback: "workhorse" }
  code_generation:   { tier: 2, model: "local",            fallback: "workhorse" }
  adversarial_audit: { tier: 2, model: "gemini-3.7-flash", fallback: "workhorse" }
  review_walkthrough:{ tier: 1, model: "gemini-3.7-flash", fallback: "local" }

# Inverted Control & Dynamic Escalation Ladder
escalation:
  max_t2_retry_attempts: 3
  circuit_breaker_on_dod_fail: true
  auto_escalate_to_tier1: true

The Dynamic Escalation Flow:#

1. Substrate Delegation: The Go engine claims a task and dispatches EDIT execution to Tier 2 (nomos code) running high-velocity local silicon.
2. Machine Gatekeeping: The substrate evaluates non-verbal proof (compilation, AST complexity < 15, docstring density ≥ 10%, unit test traces).
3. Escalation Circuit Breaker: If Tier 2 fails DoD gates after N attempts or encounters an architectural complexity ceiling, the substrate trips an Escalation Circuit Breaker, escalating the task back up to the Tier 1 Orchestrator / Human PO with structured failure telemetry.

The 3 Strict Architectural Guardrails#

To prevent architectural drift and cognitive degradation across both Tier 1 and Tier 2 co-processors, Nomos enforces three strict, machine-verified guardrails:

1. Axiom of Topological Slicing (Domain & Layer Boundaries)#

Tasks must strictly respect Single-Layer Responsibility. An autonomous task must never span conflicting architectural planes:

• Compiled Substrate Layer (Go Engine): Core state machine, AST parsers, binary verification gates.
• Intent Plane (Playbooks & Workflows): Declarative markdown protocols, prompt guidelines.
• Membrane Layer (Frontend UI): Cockpit Avionics, Svelte components, CSS styling.

Slicing monolithic tasks must follow topological domain boundaries rather than arbitrary agile sizing.

2. YAGNI & Shallow Abstraction Guardrails#

All generated code must adhere to the YAGNI ladder:

• Standard library first → Native framework features second → Third-party dependencies last.
• No single-implementation interfaces without explicit requirement.
• No boilerplate factory classes or premature dependency injection wrappers.
• No magic strings: extract into typed constants.
• Delete or simplify legacy code before introducing new abstractions.

3. Machine-Enforced Surgical Override Boundary (≤ 3 Lines)#

When a Human Product Owner and an AI assistant are pair-programming live in the IDE canvas, requiring a background Swarm dispatch to fix a single-line typo or quick test assertion introduces friction.

To support live pair-programming without compromising structural integrity:

• --override=tier1 (or --override=surgical) is permitted exclusively for interactive PO-assisted surgical hotfixes of ≤ 3 lines.
• The pre-commit hook and DoD verification gate physically verify that git diff --staged is ≤ 3 lines. Any larger modification trips the Cognitive Firewall, blocking commit and forcing delegation to Tier 2 (nomos code <KEY>).

Cybernetic Avionics: Glass-Box Mission Cockpits#

In classical development, a standard terminal window is sufficient for a single interactive shell. In multi-tier autonomous engineering, however, an engineering workspace is no longer a single thread of execution. It involves:

• Tier 1 Conscious Architects conducting architectural planning in the IDE canvas;
• Tier 2 Headless Solvers (ncode) running parallel TDD loops inside transient worktrees;
• 39 Definition of Done AST quality gates verifying complexity, docstrings, and security in real time.

Streaming these concurrent processes into a single terminal produces unreadable scrolling noise. Operators lose situational awareness, and trust in autonomous systems collapses.

flowchart TD
    subgraph SwarmMesh ["1. Autonomous Engineering Swarm Mesh"]
        T1["Tier 1 Conscious Architect (IDE Agent)"]
        T2["Tier 2 Headless Swarm Fleet (ncode on RTX 4080)"]
        DoD["39 Definition of Done AST Gate Engine"]
    end

    subgraph AvionicsHUD ["2. Nomos Cockpit (Membrane Avionics)"]
        Avionics["44px Real-Time Top HUD Strip"]
        Tree["Interactive Task & Cycle Dependency DAG"]
        GlassBox["Glass-Box Token Reasoning & Trajectory Stream"]
        Spectator["Public Spectator Live Feed (/cockpit)"]
    end

    subgraph Operator ["3. Human Product Owner (PO)"]
        Steering["One-Click Parity Steering & Gate Approvals"]
        Backlog["Quick-Capture Backlog Rail"]
    end

    SwarmMesh -->|"Bi-Directional Telemetry Stream"| AvionicsHUD
    AvionicsHUD -->|"Real-Time Visual Situational Awareness"| Operator
    Operator -->|"Cryptographic Intent & Phase Steering"| SwarmMesh

The Three Pillars of Cybernetic Avionics:#

1. The 44px Top Avionics Strip: Consolidates active task state, current phase locks (IDLE → PLAN → EDIT → REVIEW), transient worktree paths, active swarm providers, and velocity metrics into a unified 44px HUD strip.
2. Glass-Box Token Telemetry: Instead of opaque black-box background processes, Cockpit renders live token reasoning traces, turn-by-turn hypothesis synthesis, and AST error diagnostics in real time. Operators observe the exact moment an agent detects a regression and initiates a test-first fix.
3. Human-in-the-Loop (HITL) Parity Steering: Autonomous swarms move at supersonic speed while human Product Owners retain ultimate cryptographic command. Cockpit provides one-click visual approval gates for phase transitions, candidate bundle dry-runs, and multi-portal release shipping (nomos release ship).

The 9-Phase Autonomous Cognitive State Machine#

The Nomos state machine coordinates the entire engineering lifecycle across 9 discrete phases:

stateDiagram-v2
    [*] --> IDLE
    IDLE --> TRIAGE : Ingest Intent / Backlog
    TRIAGE --> SPEC : Auto-Size & Route
    SPEC --> PLAN : Lock Schema Contract
    PLAN --> EDIT : Approve DAG Plan (nplan)
    EDIT --> AUDIT : TDD Solver Complete (ncode)
    AUDIT --> REVIEW : Adversarial Check Pass (nreview)
    REVIEW --> SYNC : 39 DoD Gates Verified
    SYNC --> LEARN : 2PC Atomic Release
    LEARN --> IDLE : Index GitBrain Notes

The Nomos Cognitive Firewall#

What began as simple Definition of Done (DoD) and Definition of Ready (DoR) gates has evolved into The Nomos Cognitive Firewall.

This is a cryptographic and procedural boundary that physically locks the workspace state:

• Repository files are locked read-only during PLAN, SPEC, and REVIEW phases.
• Mutations must occur exclusively inside isolated transient worktrees (worktrees/<repo>-<task>).
• If an agent attempts to skip required structural checks or modify protected branches directly, the Cognitive Firewall physically halts execution and rejects the change at the Git hook level.

GitBrain vs. The Vault#

• GitBrain functions as the machine's subconscious—a high-density local vector store and note graph (refs/notes/agent) for context retrieval, semantic indexing, and raw intelligence processing.
• The Unified Vault functions as the conscious contract—a structured, human-readable repository for governance, architecture, and overarching engineering strategy.