Nomos OS Docs

Appearance

Deterministic DAG Task Scheduling & The Control Plane Substrate ​

1. Architectural Foundations: Where Nomos Sits ​

Nomos OS operates on the Dual-Core Architecture (Substrate Core vs. Intent Core). The fundamental division separates the stochastic reasoning plane (Intent Plane / Yang) from the deterministic compiled Go substrate (Execution Substrate / Yin).

2. Conversational Steering vs. The Deterministic Railway Track ​

A central debate in autonomous software engineering is whether agent workflows should be guided through conversational steering or through an inverted compiled control plane.

The Failure of Conversational Steering ​

Conventional coding tools (such as chat-prompt loops and single-threaded terminal prompts) rely entirely on conversational nudges — repeatedly re-prompting the LLM, begging it to remember coding standards, and hoping it does not violate workspace boundaries.

This paradigm exhibits severe structural flaws:

  1. The Compute & Token Penalty: Every conversational correction re-submits the entire conversation history. Re-feeding 50,000+ tokens per correction turn burns massive compute and incurs substantial API costs.
  2. Cache Expiration Anxiety: Fragile prompt cache windows (e.g. 5 minutes) force developers into hyper-vigilant prompt pacing, keeping humans glued to the screen playing token optimization games.
  3. Hallucinatory Drift & Blast Radius: Without hard operating system boundaries, stochastic models inevitably wander off, hallucinating multi-file diffs and invalid dependencies before the human can catch the error.

The Nomos Approach: The Substrate is the Railway Track ​

"Nomos doesn't need conversational steering because the runtime control plane is the track the train runs on."

In Nomos OS, the compiled Go engine functions as an immutable, inverted state machine:

  • Zero-Token Boundary Enforcement: A compiled Go pre-tool hook or verification gate executes locally in 2 milliseconds, costs 0 API tokens, and halts boundary violations before the model can write an invalid diff.
  • Permanent Substrate Encoding: Any workflow pattern or structural constraint that emerges during engineering is immediately encoded into the compiled Go substrate (Yin) rather than repeated in chat prompts.
  • Fail Fast at the OS Level: Invariants are enforced by AST parsers, compiler typechecks, and SQLite state locks — not by conversational self-attestation.
┌─────────────────────────────────────────────────────────────────────────┐
│                          THE TOKEN ECONOMICS                            │
├──────────────────────────────────┬──────────────────────────────────────┤
│ Conventional Conversational Loop │ Nomos OS Compiled Substrate Engine   │
├──────────────────────────────────┼──────────────────────────────────────┤
│ Context reload: ~50,000 tokens   │ Compiled Go execution: 0 tokens      │
│ Latency: 3,000ms – 10,000ms      │ Latency: 2ms (local AST verification)│
│ Enforcement: Stochastic (Prompt) │ Enforcement: Deterministic (Binary)  │
│ Result: Hallucination drift      │ Result: Fail-closed OS safety gate   │
└──────────────────────────────────┴──────────────────────────────────────┘

3. Interactive Human Supervision & Zero-Friction Interruption ​

Operating on a deterministic substrate does not mean human developers are locked out. Nomos maintains a strict balance between autonomous execution and human authority:

  • Interrupt at Any Time: The human Product Owner can halt execution, modify task parameters, or pivot architectural plans at any moment via CLI commands (nomos task reset, nomos task edit).
  • Cognitive Firewall Across 4 Procedural Phases:
    1. PLAN Phase (Read-Only): The workspace source tree is cryptographically locked. Enables safe, unconstrained cognitive tangents and deep architectural reviews without mutation blast radius.
    2. EDIT Phase (Sandboxed Mutations): Workspace unlocks exclusively inside isolated transient worktrees (worktrees/<repo>-<task>), guarded by AST pre-commit hooks.
    3. REVIEW Phase (DoD Audit): Substrate executes 36 binary AST quality gates before allowing commit authorization.
    4. IDLE Phase (Clean Baseline): Feature branches are fast-forward merged and transient worktrees are torn down.

4. Goal Decomposition: Topological Slicing & CPM Scheduling ​

Transforming high-level roadmap items into safely executable units requires rigorous domain and cognitive decomposition.

4.1 Topological Domain & Layer Slicing (Axiom 4) ​

Tasks must strictly respect Single-Layer Responsibility. Tasks are categorized across three architectural planes:

Architectural LayerIdentifierScope & Invariants
Substrate Planelayer:0Compiled Go engine, state machines, CLI commands, AST verification gates.
Membrane Planelayer:1SvelteKit UI components, frontend layouts, headless widgets, telemetry HUD.
Intent Planelayer:2Living Vault specifications, markdown playbooks, handbooks, agent guidelines.

Axiom 4 (Topological Slicing): Cognitive size is the early-warning indicator; Domain and Layer separation is the structural remedy.

Monolithic tasks spanning multiple planes (e.g., combining Go engine changes with Svelte frontend and documentation playbooks) are automatically flagged by the substrate and tagged with needs-split.

4.2 Cognitive Load Index (CLI) Sizing ​

Each task node in the DAG is quantified by two dimensions:

  • Context Burden ($B$, 1–10): Estimated working memory context footprint. Tasks with $B > 10$ exceed single-agent attention capacity and must be decomposed.
  • Logic Depth ($D$, 1–10): Cyclomatic complexity, conditional branching, and AST mutation depth.

4.3 Critical Path Method (CPM) Heuristic Cycle Bundler ​

The DAG Engine (src/nomos/modules/task/bundler.go) traverses the task graph to aggregate related micro-tasks into parent Cycles:

Combined Context Burden = Sum(Child Burden) <= Max Capacity (Default: 8)
Combined Logic Depth    = Max(Child Depth)
Domain Invariant        = Single-Layer Responsibility (Axiom 4)
  • Cycle Promotion: When a child task belonging to an open Cycle is started (nomos task start <KEY>), the substrate automatically promotes execution to the parent Cycle worktree.
  • Critical Path Calculation: Computes the longest chain of dependent unblocked tasks to prioritize high-leverage bottlenecks in the backlog.

5. Dynamic Auto-Remediation DAG Substrate ​

When Definition of Done (DoD) verification gates fail during the EDIT or REVIEW phase, the substrate guarantees fail-closed release safety through Dynamic Auto-Remediation:

  1. Failure Fingerprinting: The failing verification gate computes a cryptographic hash from the failing rule, target file path, and error diagnostics.
  2. Blocking DAG Task Creation: An ephemeral remediation task node is inserted into SQLite (~/.nomos/data/db/nomos_global.db), dynamically blocking the active parent task:
    • [NOM-540] is blocked by [remedy-9ff7184d: Resolve Comment Density in backup.go]
  3. Automated Convergence: The AI agent reads the localized remediation directive, applies surgical AST corrections, and re-executes verification.
  4. Auto-Resolution: Once all 39 DoD gates pass cleanly, nomos task sync automatically marks all associated remedy-* tasks as resolved and closes them in the release transaction.

6. Two-Phase Commit (2PC) GitOps Release Pipeline ​

All code modifications are sandboxed inside isolated transient Git worktrees, keeping protected trunk branches (master, substrate) pristine:

7. Substrate Invariants Summary ​

  • Single-Layer Responsibility: Unit tasks never cross topological boundaries between compiled Go substrate, frontend membrane, and markdown intent playbooks.
  • AST Gate Enforcement: Cyclomatic complexity $< 15$, docstring density $\ge 10%$, and zero magic strings are deterministic release prerequisites.
  • Transactional State Integrity: All state transitions occur through compiled CLI commands (nomos task start, nomos task transition, nomos task sync), ensuring zero out-of-band SQLite corruption.
  • Inverted Control Flow: The engine coordinates the agent; the agent never coordinates the engine.