The Invariant Card & Technical Glossary

This chapter is the substrate's pocket constitution. The card is the set of laws an agent is not permitted to renegotiate. The glossary is the type system for talking about those laws without lexical drift.

An axiom states why the universe is bounded. An invariant is the wall the process hits. A gate is the compiled predicate that raises the wall. A capability is the affine token that authorizes a single step inside the wall. A receipt is the signed artifact that the step occurred and that the wall still stands.

If a term does not land in one of those five layers, it is commentary. Commentary is not load-bearing.

The One-Page Invariant Card#

Seven laws. One sentence each. No aliases, no softenings, no "should."

Pin this card. The remainder of the handbook is commentary on how these seven sentences become os.Exit(1).

Lifecycle the card implies, and that the engine actually runs:

IDLE → PLAN → EDIT → REVIEW → SYNC → LEARN

The LLM does not traverse this graph. The engine does. The LLM is called from a node, under a token that dies when the node exits.

The Five-Layer Stack#

Core rule. An axiom that has no invariant is a sermon. An invariant that has no gate is a comment. A gate that issues no receipt is an anecdote.

Layer I — Axioms#

Axioms are not code. They are the premises from which code is not allowed to deviate. Nomos derives every constraint from this set. The seven laws on the card are the operational subset; the entries below are the full ontological bed.

Axiom of Topological Symmetry. The harness underneath the agent must mirror the state topology of the agent's reasoning loop. If the agent thinks in TRIAGE → … → LEARN, the engine must refuse any other walk.

Axiom of Dual-Core Division. The Intent Core (Yang) explores, designs, and refactors; the Substrate Core (Yin) enforces, verifies, and guarantees. Stochastic reasoning and deterministic execution never occupy the same layer.

Axiom of Non-Verbal Proof. We never ask an LLM if code is correct. We compile it, verify AST invariants, and run tests through deterministic Go binaries. Self-reported success is discarded.

Axiom of Topological Slicing. Cognitive size is the early-warning indicator; domain and layer separation is the structural remedy. Files exceeding 400 lines or Cognitive Debt Score > 45 must be sliced across sibling modules without destructive omission. Tasks must not span conflicting architectural planes.

Axiom of Canonical Singularity (Zero-Alias Law). Every capability possesses strictly one canonical, bijective representation. Command aliases, convenience shortcuts, and redundant shims are purged.

Axiom of Epistemic Distrust (Verification Asymmetry). State transitions require non-verbal proof: exit code 0 and verified AST invariants. Commit authorization requires 2PC against the binary DoD suite before a worktree may merge into a plane trunk.

Axiom of Ambient State Isolation (Hermetic Worktree Law). Protected trunks are physically read-only. Active mutations occur strictly inside ephemeral, single-task worktrees (worktrees/<repo>-<task>).

Axiom of Non-Destructive Refactoring (AST Preservation). Under context-window pressure, models truncate, stub, or comment out working code. Modularization must never be achieved by omission. Gates verify AST symbol parity, exported signatures, and comment density across sibling files.

Axiom of Unified Schema Transduction (Single-Path SSoT). Any contract maintained in multiple languages will drift. Every contract has exactly one compiled Go SSoT. Downstream consumers receive projected, hash-verified mirrors.

Axiom of Dynamic Ecosystem Discovery (Zero-Hardcoded-Path). No physical workspace path or repository identity may exist as a string literal. Filesystem boundaries, repository mappings, and worktree roots resolve at runtime via config.LoadGlobalConfig().

Axiom of Total Reification (Zero-Implicit). Implicit context, ambient environment variables, and hidden default fallbacks are hallucination vectors. Every dependency, parameter, tool argument, and execution invariant is declared in an AST, SQLite schema, or task manifest.

Axiom of Binary Diagnostics (Silent Metric). Advisory warnings are ambiguous signals: agents either ignore critical debt or burn budget "fixing" notices. Evaluation is PASS or FATAL structured JSON. Never conversational prose.

Axiom of Deterministic Ephemerality (Anti-Accretion). Unversioned local state is contamination. Every mutation phase executes against a worktree whose input boundary is hash-pinned to a clean commit and whose output collapses to a single verifiable diff.

Axiom of Bidirectional Verifiability (Specification-First). Verification predicates, invariant schemas, and contract gates precede execution. An agent cannot enter EDIT without a deterministic gate that fails on current state and passes only on correct completion.

Axiom of Non-Contamination. Cross-plane contamination is forbidden. Substrate never authors Intent. Membrane never queries raw Substrate tables. Intent is inert until Substrate compiles its satisfaction to exit code 0.

Axiom of Cognitive Inversion. Control flow is inverted relative to 2024–2026 agent loops. The compiled engine drives the lifecycle; the model is a co-processor, not a controller.

Harness Over Model. Intelligence without invariants is liability; invariants without intelligence is rigidity. The harness is the physical totem. The model is not.

Layer II — Invariants#

An invariant is the physical, executable manifestation of an axiom, anchored to a single source artifact. Where an axiom states why, an invariant is the wall.

SSoT Invariant. One artifact is canonical. All other representations are projections. Drift between projection and source is a hard failure, not a merge conflict.

Dual-Core Two-Hemisphere Topology (ADR-0061 & ADR-0066). Strict domain separation, partitioned into two complementary hemispheres:

Protected Trunk Invariant (Law 3). Protected trunk branches (main) are physically read-only. Direct mutations on trunk are blocked by pre-commit hooks and CapBAC capability verification.

Hermetic Worktree Invariant. Active execution is strictly confined to transient worktrees (worktrees/<repo>-<task>). Lifecycle: Scaffold → Sandboxed TDD → Machine DoD (42 gates) → 2PC Atomic Release → Teardown. Zero residual state.

Zero-Alias Invariant. CLI flags, command hierarchies, and tool schemas are bijective. Duplicate names fail compilation of the contract schema (zero_alias.go class of checks).

Cognitive Firewall. Workspace is locked read-only during non-mutation phases (PLAN, REVIEW). Mutation capability exists only inside the task worktree, and only in EDIT.

Total Reification Invariant. No ambient fallbacks. Missing explicit declaration is a schema error, not a default.

AST Preservation Invariant. Refactors must preserve symbol parity, exported signatures, and docstring density (≥ 10%). Incomplete stubs are rejected, not "followed up later."

Hash-Pinned Input Boundary. A worktree that cannot name its parent commit hash is invalid before the first edit.

Layer III — Gates#

Gates are compiled predicates. They do not advise. They evaluate to boolean and, on failure, refuse the transition.

Non-Verbal Proof Gate. AST static analyzers plus test runner. Representative thresholds (the numbers are the law, not a style guide):

• cyclomatic complexity ≤ 15
• docstring density ≥ 10%
• import boundary closures (no illegal cross-plane or cross-package imports)
• 100% green test traces

Failure → exit 1 → phase transition blocked. The agent cannot negotiate.

Definition of Done (DoD). The canonical suite of 42 machine-enforced gates (across 7 Laws and 21 Invariant Cells) that must all return PASS before 2PC will consider a worktree mergeable. Partial green is red.

Pre-Commit Trunk Lock. Hooks reject any mutation whose target is a protected trunk branch. The only legal write path is the worktree.

Two-Phase Commit (2PC) Release Gate. Prepare: DoD + AST + tests inside the sandbox. Commit: atomic fast-forward into the plane trunk, then teardown. Abort: worktree remains isolated; trunk is untouched.

Binary Diagnostic Schema. Gate output is structured JSON { "status": "PASS" | "FATAL", ... }. Narrative linter prose is not a gate.

Import Boundary Gate. Compiler-enforced closure of plane and package edges. Membrane must not import Substrate internals. Substrate must not author Intent documents.

Bidirectional Spec Gate. EDIT is unreachable until a failing predicate exists for the claimed change. Generation without a failing gate is unconstrained generation.

Cognitive Size Gate. File length and Cognitive Debt Score trip slicing requirements. The gate fails closed: oversized modules do not merge.

Projection Parity Gate. Downstream membranes and docs must match the Go SSoT at SHA-256 byte parity. "Semantically equivalent" is not a predicate.

Layer IV — Capabilities#

Capabilities are substructural. They are not roles, not API keys, and not ambient authority. They are affine tokens: usable once, in one phase, for one task, then gone.

CapBAC (Capability-Based Access Control). Tokens bound to (task_id, phase). Discrete step and token depletion per lifecycle phase. Exhaustion terminates the stochastic loop (cybernetic damping) without poisoning the next phase.

MutationCapability. Issued only in EDIT, only against the task worktree. Absent in PLAN, SPEC, REVIEW. Possession is checked by the engine, not by the model.

Step Budget / Token Budget. Finite counters on the CapBAC token. The model is a stochastic ALU with a cycle limit. Runaway loops die by arithmetic, not by plea.

Cognitive Co-Processor. The LLM is a bounded, ephemeral heuristic function called by the Go harness. It does not own the repository, the shell, or the state machine.

Tier 1 — Orchestrator (Conscious Architect). Frontier model invoked for PLAN, SPEC, REVIEW, architectural decomposition, and human PO negotiation. Strategic, not mechanical.

Tier 2 — Swarm (Headless Mechanical Solver). Turn-bounded TDD workers (sovereign only: nomos code) on local open-weight SLMs inside transient worktrees. High velocity, no trunk authority, no ambient shell.

Declarative Domain Routing. ~/.nomos/data/nomos.yaml maps domains (planning, code_generation, adversarial_audit) onto tiers, models, and fallback escalation. Routing is configuration, not prompt folklore.

SLM. Compact open-weight models (7B–32B class) on local GPU silicon. Zero marginal token tax, no codebase egress. Used where gates, not the model, carry correctness.

Cognitive Yield Ratio (CYR). CYR = ΔComplexity / Tokens. Distinguishes verified architectural work from context thrashing. A metric, not a gate; gates remain binary.

Model Downgrade Paradox. Unconstrained prompt agents require frontier-scale models to imitate compilers. Agents under a Substrate Core execute on cheap/fast models or local SLMs at identical DoD parity, because the compiler is not being impersonated.

Conduit. Local browser bridge / MCP provider: programmatic access to DOM, network, accessibility tree. A capability surface, not a second SSoT.

Layer V — Receipts#

A receipt is evidence that a transition happened under the preceding four layers. Without a receipt, the transition is hearsay.

Release Receipt. Ed25519-signed artifact attached to Git Notes (refs/notes/nomos/releases) at 2PC commit. Binds: task id, phase, parent commit, result diff hash, DoD vector, capability id, signer.

SHA-256 Byte-Parity Proof. Cryptographic identity between SSoT and a projection (Membrane docs, generated bindings, published handbook pages). Semantic similarity is not a receipt.

Worktree Teardown Receipt. Evidence that the ephemeral worktree was destroyed after merge or abort. Residual directories are invariant violations, not leftovers.

Phase-Exit Receipt. Structured record that a lifecycle node exited with PASS or FATAL, including remaining CapBAC budget. Enables LEARN without re-trusting the model's narrative of what it did.

LEARN Distillation. After Substrate execution, control inverts once: empirical facts discovered in the worktree are written back into Intent as durable law. The receipt of LEARN is an Intent patch that itself must pass Non-Verbal Proof on the next cycle. Entropy is allowed to decrease only through this channel.

Compact Index#

Usage#

Quote the card in AGENTS.md. Compile the invariants. Wire the gates to os.Exit(1). Issue capabilities that expire. Refuse any merge that cannot produce a receipt.

If an agent argues with a gate, the agent is wrong. That is the entire handbook, compressed.