NomosDual-Core Architecture
How Nomos separates declarative Intent specifications from compiled Substrate execution, enforcing 42 deterministic Go and Tree-sitter AST verification gates inside hermetic Git worktrees.
End-to-End Repository Governance Blueprint
Every task executes across five deterministic boundaries: read-only trunk protection, SQLite CapBAC lease allocation, isolated Git worktree sandboxing, 42 sub-400ms AST quality gates, and atomic 2PC fast-forward sync.
From Natural Language Intent to AST-Verified Done
Experience deterministic AI engineering rails without changing how your team builds. You prompt in plain English with zero custom slash commands; your AI agent operates the compiled Go engine underneath.
Install & Initialize Once
Run the 1-liner to install the Go substrate and execute nomos init once in your repo. Scaffolds AGENTS.md / CLAUDE.md, ambient SessionStart hooks (.agents/hooks.json), and self-healing Git defense hooks with zero custom slash commands.
curl -fsSL https://sophialabs.ca/install | sh $ nomos init
$ SessionStart hook → nomos handshake (auto)
- Trunk branch (main) locked physically read-only
- Zero custom slash commands or workflow files to memorize
- Subconscious Nomos Mneme semantic memory rehydrated automatically
Hermetic Worktree & AST Gates
Describe your task in natural language. Your agent automatically mounts an isolated transient Git worktree (worktrees/<repo>-<task>), executes the TDD loop, and passes all 42 Go AST quality gates before any code touches staging.
chat > "Fix issue #42: add CapBAC token gate"
$ nomos task start SUB-42 → worktrees/repo-SUB-42 nomos verify (42 DoD Gates Passed)
- Zero branch drift: 100% sandboxed in transient worktree
- TDD Assertion: failing test required before logic changes
- AST complexity (< 15) & docstring density (>= 10%) enforced
Walkthrough Review & 2PC Sync
Review the agent's structured walkthrough diff in chat and type "approve". Upon consent, Nomos executes an atomic Two-Phase Commit (2PC) release: fast-forward merge to root, cryptographic Git Notes receipt generation, and transient worktree teardown.
chat > approve
$ nomos task sync SUB-42 -F .tmp/walkthrough.md
- Zero unapproved modifications escape to protected trunk
- Atomic 2PC release with cryptographic Git Notes receipt
- Transient sandbox automatically pruned and cleaned
Beyond Prompt-Based AI: Deterministic Rails vs. Stochastic Prompts
Why prompting an LLM to "follow rules" fails in production, and how compiled binary tooling enforces guaranteed architectural boundaries.
| Engineering Dimension | Ungoverned Agents (Claude Code, Cursor, OpenCode) | Nomos & SophiaLabs (Deterministic Harness) |
|---|---|---|
| Enforcement Substrate How rules are applied | Stochastic Prompt Suggestions (Honor System): The agent is given markdown instructions ("Please run tests", "Please don't edit main"). If the context window degrades, the model skips them without notice. | Compiled Go Substrate & OS Hooks: Git pre-commit hooks and machine-enforced gates physically block forbidden mutations. If nomos verify fails, code cannot be checked in. |
| Working Tree Isolation Multi-agent safety | Live "Dirty" Working Tree: Agents edit files directly inside your active checkout, colliding with human edits, dirtying branches, and breaking running local dev servers. | Transient Sandboxed Git Worktrees: Every task mounts an isolated directory (worktrees/repo-SUB-123) auto-linked via go.work/workspaces. Parallel agents execute in complete isolation. |
| Phase Discipline Plan vs. Execution lock | Unrestricted Arbitrary Writes: The agent can jump from planning straight into refactoring or deleting source files on a whim without human sign-off. | Cryptographic Phase State Locks: Repository files are locked read-only in PLAN. No source file can be touched until a valid phase transition token is issued by the human PO. |
| Definition of Done (DoD) Quality & Regression Gates | LLM Self-Evaluation ("Vibe Check"): The model evaluates its own code in prose ("All requirements met!"), masking reward-hacked tests, hollow shims, or dead code. | 42 Strict Binary Verification Gates: Zero-tolerance Go & WASM Tree-sitter AST analysis enforcing cyclomatic complexity (<= 15), file LOC (<= 400), anti-shim checks, and TDD assertion density (>= 10%). |
| Inference Efficiency Token spend & model viability | Context Thrashing & Retry Tax: Blind edits lead to broken builds. The agent re-reads 100k+ token contexts across 10-turn retry loops ($2.50+ per feature) and forces reliance on expensive frontier cloud APIs. | 85%+ Lower Token Spend & $0 Local SLMs: Sandboxed worktrees keep contexts under 8k tokens. 12ms AST line diagnostics resolve errors in 1 turn, unlocking production viability for fast, private local models. |
| The 90-Day Velocity Curve Speed vs. Long-Term Health | Day 1 Speed ➔ Day 90 Sludge: 10x code output feels fast initially, but unconstrained drift results in 80% of human time spent untangling AI spaghetti, dead imports, and phantom bugs. | Compound Acceleration ("Slow Down to Go Fast"): Spending 15 seconds executing sandboxed TDD and AST gates ensures code is written once, verified immediately, and never regressed. |
Stochastic Chaos vs. Deterministic Go Rails
Drag the slider to test how unmanaged prompt loops fail at scale versus physical AST-enforced compiler gates.
Real-Time AST Definition of Done Sandbox
Type or paste code to test cyclomatic complexity, docstrings, security invariants, and empty blocks in sub-10ms.