NomosNomos Developer Documentation
Nomos is a compiled Go governance harness that sits between any coding agent and your Git repository. It enforces read-only trunk protection, transient task worktrees, 42 sub-400ms AST Definition of Done gates, and local SQLite + Git Notes provenance without requiring IDE plugins or cloud egress.
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.
Integration by Engineering Role
How individual contributors, technical leads, CI pipelines, and security teams interface with the Nomos binary.
Prevents coding agents from mutating trunk directly, deleting test assertions, or compounding multi-turn regressions in shared working trees.
Provision an isolated task worktree -> pair-program in Claude Code, Cursor, Antigravity, or OpenCode -> verify 42 AST gates -> atomic 2PC release.
Read 3-Pass CLI Guide ->Six-Phase Task Execution Reference
Workspace mutability is procedurally locked across six deterministic phases from task lease to atomic 2PC release.
Agent mutates files directly on main or a shared branch without isolation, leaving uncommitted work exposed to destructive overwrites.
Locks main read-only via self-healing Git defense hooks and provisions an isolated worktree (worktrees/repo-SUB-42) with a scoped CapBAC lease.
Deterministic Pre-Merge Failure Modes
Representative agent shortcuts intercepted locally by compiled Go AST and CapBAC gates prior to merge.
func ValidateInvoiceSignature(payload []byte) error {
- return crypto.VerifyPSS(pubKey, payload)
+ // TODO: wire key rotation later
+ return nil
}[FAIL] ERR_TRIVIAL_PASS_SHIM (billing/verify.go:42) -> Function ValidateInvoiceSignature returns constant literal 'nil' with 0 verification statements. -> Remedy: Implement concrete signature verification before transitioning to REVIEW.
Coding agents frequently satisfy callers by returning constant literals (nil, true, empty structs). AntiShimGate inspects compiled AST return paths to block placeholder implementations.
Read Non-Verbal Proof & AST Invariants ->Agent-Agnostic CLI & Pipeline Configuration
Nomos governs the repository at the Git hook, worktree, and compiler AST boundary, so teams can switch coding agents or models without rewriting enforcement rules.
Replaces sprawling markdown rulebooks with deterministic Git hooks, scoped CapBAC leases, and concise AST error diagnostics.
curl -fsSL https://sophialabs.ca/install | sh cd your-repo && nomos init && nomos handshake # Run Claude Code normally; Nomos enforces worktree isolation and AST gates underneath
Core Reference Documentation
Deep-dive specifications, formal invariants, and structural codebase telemetry.
The Seven Laws of Nomos
Canonical invariants governing indirect agent control, non-verbal AST proof, hermetic worktrees, and single-source-of-truth parity.
Read Chapter ->SPECIFICATION · SUBSTRATEHermetic Worktree & Trunk Lockout
How CapBAC pre-commit hooks physically lock main read-only and isolate every coding task inside transient Git worktrees.
Read Specification ->SPECIFICATION · ASTPolyglot AST Validation Architecture
Sub-400ms Go and WASM Tree-sitter structural verification for complexity budgets, docstring density, and anti-shim enforcement.
Read Specification ->HANDBOOK · 11 CHAPTERSAgent Engineering Handbook
Complete technical reference covering dual-core inversion, cryptographic Git Notes provenance, and local SQLite memory.
Browse Handbook ->SPECIFICATION · PROVENANCEDatabase & Git Notes Contract
Local SQLite state encapsulation paired with SHA-256 verification receipts persisted directly to cryptographic Git Notes.
Read Specification ->DEPLOYMENT · PROFILESSolo, Team & Regulated Profiles
Compare self-hosted Apache 2.0 Open-Core deployment with multi-seat team governance and regulated audit requirements.
Compare Profiles ->