REFERENCE · STATIC GO BINARY · ZERO ALIASES (LAW 6)

CLI & `nomos.yaml` Reference

Under indirect control, SessionStart and pre-commit hooks invoke these commands automatically while you prompt Claude Code, Cursor, Antigravity, or OpenCode in plain English. Use this reference for CI pipelines, custom budgets, and direct substrate inspection.

01 · BOOTSTRAP

Repository Setup & Session Handshake

Initialize a Git repository once and let SessionStart hooks run capability verification automatically on every coding-agent turn.

nomos init PHASE: IDLE

Initializes .nomos/ configuration, local SQLite WAL ledger, SessionStart agent hooks, and self-healing Git defense hooks.

--force (reconcile existing hooks without overwriting ledger history)

$ cd your-project && nomos init

nomos handshake PHASE: ANY

Verifies Git defense hooks, validates active CapBAC worktree leases, checks SQLite health, and prints ready DAG wavefront tasks.

--json (emit machine-readable session state receipt)

$ nomos handshake

nomos doctor PHASE: ANY

Audits local Go/polyglot toolchains, Git worktree integrity, hook permissions, and schema byte parity.

--fix (auto-repair stale hook shims or orphaned lockfiles)

$ nomos doctor

nomos hook install PHASE: ANY

Non-destructively merges Nomos SessionStart, PreToolUse, PostToolUse, and Stop hooks into Claude Code, Gemini CLI, and OpenCode configs with .bak backups.

--claude / --gemini / --opencode (target specific Tier 1 agent harnesses)--user (install into user-level global harness config)

$ nomos hook install --claude --gemini

nomos hook stop PHASE: EDIT / REVIEW

Evaluates turn-exit verification readiness, blocking premature agent completion when dirty worktree edits remain unverified or DoD gates fail.

(invoked automatically via Stop / AfterAgent lifecycle hooks)

$ nomos hook stop

02 · VERIFICATION

Deterministic AST & DoD Gate Suite

Evaluates all 42 compiled Go AST, .scm structural query, wazero WASM, secret-entropy, and toolchain gates with zero network egress.

nomos verify PHASE: EDIT / REVIEW

Runs the 42 Definition of Done quality gates across all 11 supported languages (Go, Python, TS, JS, Svelte, Rust, Ruby, C/C++, Java, Kotlin, C#) against diff-scoped worktree edits.

--all (audit entire repository tree in CI)--strict (promote warnings to fail-closed exit 1)--law <1..7> (run gates mapped to a specific Canonical Law)

$ nomos verify --all --strict

nomos verify proof PHASE: REVIEW / CI

Executes adversarial mutation-sensitivity probes verifying every active AST gate catches synthetic shims and violations.

--json (output cryptographic attestation summary)

$ nomos verify proof

03 · LIVING LEDGER

Hermetic Worktree & 2PC Task State Machine

Manages procedural phase transitions (IDLE -> PLAN -> EDIT -> REVIEW -> SYNC -> LEARN) inside isolated worktrees/<repo>-<task> directories.

nomos task chore "<title>" PHASE: IDLE -> EDIT

Atomically allocates a burden-1 task, provisions an isolated Git worktree, and mints an active EDIT phase CapBAC lease in one turn.

-p, --plane <intent|substrate> (default: substrate)

$ nomos task chore "Tighten parser boundary check"

nomos task start <KEY> PHASE: IDLE -> PLAN / EDIT

Provisions a hermetic worktrees/<repo>-<KEY> checkout and binds a scoped CapBAC capability token for an existing task.

--edit (enter EDIT phase directly when architectural plan is settled)

$ nomos task start SUB-104 --edit

nomos task commit <KEY> -m "<type(scope): summary>" PHASE: EDIT

Stages worktree mutations, validates plane separation, and records a Golden Conventional Commit with Task trailers.

-m "<message>" (required Conventional Commit summary)

$ nomos task commit SUB-104 -m "feat(ast): enforce cyclomatic ceiling"

nomos task sync <KEY> -F <walkthrough.md> PHASE: REVIEW -> SYNC

Executes Two-Phase Commit (2PC) release: runs all 42 DoD gates, fast-forwards main, writes Git Notes receipt, and prunes the worktree.

-F <file> (structured verification walkthrough markdown)

$ nomos task sync SUB-104 -F .tmp/walkthrough-SUB-104.md

nomos task dag PHASE: ANY

Displays the causal dependency DAG and unblocked wavefront of ready INT-* and SUB-* tasks.

--pending (filter to incomplete tasks)

$ nomos task list --pending && nomos task dag

04 · NOMOS MNEME

Local SQLite WAL Associative Memory

Queries and persists repository-scoped architectural patterns and verified pitfalls without touching raw .db files directly.

nomos mem recall "<query>" PHASE: ANY

Performs hybrid lexical + vector associative recall scoped to the active repository partition.

-A, --cross-repo (search across all local workstation repositories)

$ nomos mem recall "worktree pre-commit boundary"

nomos mem save -p <repo> "<insight>" PHASE: SYNC / LEARN

Persists a distilled architectural invariant or verified post-mortem lesson into Nomos Mneme.

-p <repo> (target repository partition identifier)

$ nomos mem save -p my-repo "All webhook handlers require idempotency keys"

05 · PROCESS CONTRACT

Deterministic Exit Codes

Exit	Constant	Condition	Indirect Control Recovery
0	`EXIT_VERIFIED_OK`	All 42 deterministic DoD gates, compilation checks, and CapBAC boundaries passed.	Proceed to next lifecycle transition or atomic 2PC release.
1	`EXIT_INVARIANT_VIOLATION`	One or more AST, worktree boundary, plane separation, or test assertion gates failed.	Read structured remediation guidance on stderr, fix root cause in worktree, and re-verify.
2	`EXIT_PREFLIGHT_CONFIG_ERR`	Invalid CLI arguments, missing nomos.yaml contract, or expired CapBAC capability lease.	Run nomos handshake or inspect declarative repository configuration before retrying.

06 · DECLARATIVE BUDGETS

Repository Budgets (`nomos.yaml`)

Configuration Key	Default	Enforcing Gate	Invariant Enforced
`budgets.max_file_loc`	400	Law 2 (G-24)	Maximum source lines of code per file before modular decomposition is required.
`budgets.max_func_loc`	60	Law 2 (G-24)	Maximum lines of code per function or method body.
`budgets.max_cyclomatic`	15	Law 2 (G-25)	Maximum cyclomatic branching complexity allowed per function AST.
`budgets.min_docstring_density`	0.10	Law 2 (G-27)	Minimum descriptive docstring ratio across exported symbols and packages.
`budgets.min_test_coverage`	0.55	Law 2 (G-19)	Minimum verified non-shim statement coverage floor across modified packages.
`git.protected_branches`	["main"]	Law 3 (G-01)	Physically read-only trunk branches guarded by pre-commit and worktree boundary hooks.
`planes.strict_separation`	true	Law 7 (G-15)	Rejects single-commit cross-hemisphere mutations mixing INT-* specs with SUB-* code.
`governance.quality_gates.strict_mode`	false (init) / true (dogfood)	Law 2 & Law 7	Selects brownfield monotonic baseline ratcheting (false, zero Day-1 repo rewrite) vs. repository-wide strict enforcement (true).
`governance.quality_gates.verify_scope`	"diff"	Law 2 (Polyglot)	Scopes worktree verification across all 11 languages to modified/unattested diff paths ("diff") or the full repository tree ("repo").
`governance.quality_gates.tdd_mode`	"ratchet" / "strict"	Law 2 (TDD)	Switchable paired-test policy when strict_mode is false: "off", "ratchet" (net-new modules only), "diff" (all touched files), or "strict".
`governance.quality_gates.coverage_mode`	"live"	Law 2 (G-19)	Switchable statement coverage mode across Go, Python, JS/TS, Ruby, Rust, C++, Java, Kotlin, and C#: "off", "artifact" (LCOV/JaCoCo/Cobertura), or "live".
`governance.quality_gates.tdd_exclude`	[]	Law 2 (TDD)	Optional path globs (e.g. ["cmd/", "generated/"]) exempt from paired-test assertions in brownfield repositories.
`boundaries.egress_mode`	"allow"	Law 7 (PreToolUse)	Outbound shell network airlock mode (allow, allowlist, or offline) alongside automatic RFC1918/metadata SSRF and secret blocking.