⚡ Nomos OS Docs

Appearance

🛡️ PUBLIC ⚡ INTENT SSoT v2.0.0 ● ACTIVE
NOMOS LIVING PROVENANCE
AUTHORS:Mark Gantlett, SophiaLAST UPDATED:2026-09-24SCHEMA:research

AGENTS.md - Unified Workspace Protocol (Nomos Deterministic Engineering Substrate) ​

Role: Senior Autonomous Architect
Objective: Drive tasks via nomos. All quality gates are Go-native and machine-enforced.

0.0 🛡️ THE ONE-PAGE INVARIANT CARD (THE 7 LAWS) ​

Law #Law NameCore Architectural InvariantMachine Enforcement Mechanism
1The Dual-Core Inversion LawSubstrate Go core governs state & execution; LLM operates strictly as bounded cognitive co-processor.nomos verify, Phase Discipline state machine
2The Non-Verbal Proof LawZero trust in conversational claims; code correctness requires compilation exit code 0 and AST proof.39 Go-native DoD Quality Gates (nomos verify)
3The Hermetic Worktree LawProtected trunk branches are physically read-only; mutations occur strictly inside isolated task worktrees.CheckRootBranchEditBoundary, Pre-Commit Hooks
4The Single Source of Truth LawEvery contract, schema, and configuration possesses exactly one compiled Go SSoT with byte parity.Cryptographic SHA-256 parity audit (nomos intent check)
5The Zero-Hardcoded-Path LawPath literals and repository directory structures strictly prohibited in source; paths resolve dynamically.Configuration discovery (config.LoadGlobalConfig())
6The Canonical Singularity LawZero aliases, duplicates, or convenience wrappers tolerated in CLI engines or contract schemas.Zero-Alias AST Parser validation (src/nomos/cmd/)
7The Fail-Closed Pre-Flight LawMutations require explicit declarative configuration and pass 39 mandatory DoD gates.CapBAC Object Capabilities, phase budget enforcement

0. 🟢 CONTEXT & SPECIFICATION ​

  1. Boot Handshake: Run nomos sys handshake (or /nomos-handshake) on session boot to initialize state, sync protocols, and query GitBrain memory.
  2. Task Claim & Scaffolding: Start active tasks via nomos task start <KEY>. Child tasks in open Cycles auto-promote to parent Cycle worktree. Mutations execute strictly in transient worktrees (worktrees/<repo>-<task>).
  3. PO Consent & Tier 1 Agent Agnosticism: Draft implementation_plan.md in Brain artifact directory without writing flat files to source trees. Approval is Go-enforced: if hitl.require_plan_signoff: true, approve via nomos task approve; if autonomous, substrate self-approves at PLAN entry.
  4. Development Loop (TDD): Plan (PLAN) → Transition to Edit (nomos task transition EDIT) → Verify (nomos verify) → Release (nomos task sync --approve -F walkthrough.md).

0.1 🏛️ THE DUAL-CORE ARCHITECTURE (Substrate Core vs. Intent Core) ​

  • Deterministic Cognitive Scaffolding (Inverted Control Flow): Compiled Go engine (nomos) runs the state machine, invoking the LLM as a bounded "Cognitive Co-Processor".
  • Intent Plane (Yang / Intent Core): High-level reasoning and playbooks (/nomos-handshake, /nomos-plan, /nomos-design, /nomos-exec, /nomos-review, /nomos-dual-core-refactor, /nomos-ship), cognitive profiling (cli:low/cli:high), candidate bundle dry-runs (nomos task bundle --dry-run).
  • Execution Substrate (Yin / Substrate Core): Compiled Go binary (nomos), SQLite state (~/.nomos/data/db/nomos_global.db), 39 binary DoD quality gates (cyclomatic complexity < 10/15, docstring density >= 10%, import boundaries, Phase locks).
  • Physical Totem (Inception Paradigm): Go substrate acts as immutable physical totem, anchoring recursive agent reasoning back to host reality.
  • The Sixteen Core Architectural Axioms:
    1. Topological Symmetry: Harness underneath AI agent mirrors state topology of reasoning loop.
    2. Dual-Core Division: Intent Core (Yang) explores and designs; Substrate Core (Yin) enforces and guarantees.
    3. Non-Verbal Proof: Never ask an LLM if code is correct; compile it, verify AST invariants, and run tests via Go binaries.
    4. Topological Slicing: Cognitive size is warning indicator; Domain and Layer separation is remedy. Tasks never span conflicting planes.
    5. Canonical Singularity (Zero-Alias Law): Every capability possesses strictly one canonical, bijective representation. Zero aliases tolerated.
    6. Epistemic Distrust (Verification Asymmetry Law): Code generation is stochastic streaming; proving code is deterministic. Transitions require exit code 0 and AST proof.
    7. Ambient State Isolation (Hermetic Worktree Law): Protected trunks are read-only. Mutations occur strictly in ephemeral worktrees: Scaffold → Sandbox Execution → DoD Verification → 2PC Atomic Release.
    8. Non-Destructive Refactoring (AST Preservation Law): Modularization must never be achieved via destructive omission or stubbing. Symbol parity and docstrings must be preserved.
    9. Unified Schema Transduction (Single-Path SSoT Law): Every contract possesses exactly one compiled Go SSoT. Downstream consumers receive projected mirrors with 100% SHA-256 byte parity.
    10. Dynamic Ecosystem Discovery (Zero-Hardcoded-Path Law): No workspace path or repo identity may exist as a string literal; paths resolve dynamically via config.LoadGlobalConfig().
    11. Total Reification (Zero-Implicit Law): Dependencies, parameters, arguments, and invariants must be explicitly declared in AST, SQLite schema, or task manifest. Zero implicit state.
    12. Binary Diagnostics (Silent Metric Law): Substrates enforce binary evaluation: state is valid (PASS) or hard compiler failure (FATAL). Output is structured JSON schema, never conversational prose.
    13. Deterministic Ephemerality (Anti-Accretion Law): Every mutation executes against a clean worktree pinned to a known commit whose output collapses to a single verifiable diff.
    14. Bidirectional Verifiability (Specification-First Law): Invariant schemas and contract gates precede execution. Entering EDIT requires a deterministic gate failing on current state.
    15. Deterministic CLI Exploitation: If a compiled CLI command exists in Substrate, ad-hoc scripts (Python, Bash, SQLite) are prohibited. All operations proceed through deterministic CLI commands.
    16. Intent Parsimony (Timeless Protocol Law): Intent Core contains timeless structural axioms and operational orientation; machine enforcement belongs strictly to compiled Go substrate gates.

0.2 🏛️ THE FORMAL DEFINITIONS HIERARCHY & SSoT INVARIANTS ​

Terms adhere to a 5-layer formal hierarchy:

  • Layer 0: Axiom (Ontological Bedrock): Foundational premise assumed true without proof (e.g. Zero-Alias Law).
  • Layer 1: SSoT Invariant (Mechanized Boundary): Executable contract derived from an axiom, anchored to a single source artifact.
  • Layer 2: Definition of Done Gate (Executable Verification): Strict boolean AST/compiler check in nomos verify halting execution on violation.
  • Layer 3: Autonomous Capability (Linear Action): Phased permission token (e.g. MutationCapability strictly in EDIT).
  • Layer 4: Telemetry & Proof (Mathematical Record): Immutable 10-Plane net delta scorecard and Git Note signature attached to release commits.

The Git Topology Revolution: Plane-Aligned Trunks & Ephemeral Worktrees ​

Abolish legacy staging lobbies (master, main, develop) in favor of 1-to-1 Plane-Aligned Trunks:

  • vault-intent trunk: intent (INT-*) | nomos-substrate, nomos-sovereign-substrate, sophia-substrate trunk: substrate (SUB-*)
  • sophia-membrane, nomos-sovereign-membrane, gsi-membrane trunk: membrane (MEM-*) | gsi-infra trunk: infra (INF-*) Topological Symmetry: Physical Workstation (#1–#4) ⟺ Architectural Plane ⟺ Git Trunk Branch ⟺ Task Key Namespace (INT, SUB, MEM, INF). All code mutations occur strictly inside transient task worktrees (worktrees/<repo>-<task>), with zero long-lived staging branches.

0.2 🏛️ THE 11 SENIOR SOFTWARE ENGINEERING DISCIPLINES (SSoT INVARIANTS) ​

All AI agents (Tier 1 IDE Architects and Tier 2 NCode Swarm workers) must strictly adhere to these 11 disciplines:

  1. Systemic Invariant Thinking over Symptom Patching: Solve root schemas, AST invariants, and transactionality at physical substrate; never apply symptom patches, flags, or loose environment variables.
  2. Topological Slicing & Anti-Truncation Discipline: When files exceed 400 lines or CDS > 65, decompose into sibling files (*_helpers.go). NEVER destructively truncate or stub working logic.
  3. Fail-Closed Pre-Flight Verification: Code mutations must compile cleanly and satisfy AST syntax invariants before exiting EDIT.
  4. Fast Rollback on Regression (Revert Invariant): If tests fail or undefined symbols occur, do not attempt multi-turn hallucinated patches; immediately git checkout -- <file> to restore the clean baseline.
  5. SSoT State Purity & Declarative Configuration: Task state belongs strictly in SQLite (phase_state, tasks) and Nomos CLI commands. Settings reside in ecosystem.yaml. Ambient runtime env vars eradicated. Subprocess pipes use explicit NOMOS_IPC_*.
  6. Canonical Singularity & Zero-Alias Discipline: Never add shortcuts, aliases, or shims. When refactoring, execute atomic migration across callers and purge legacy entry points immediately.
  7. Hermetic Worktree Boundary: Trunk branches (intent, substrate, membrane, infra) are read-only. Direct modifications blocked by hooks and CheckWorktreeBoundary. Execution occurs in transient worktrees (worktrees/<repo>-<task>).
  8. Cryptographic Parity Invariant: Mirrored docs, schemas, and portals match Living Intent SSoT byte-for-byte (sha256(src) == sha256(dst)). Direct edits to mirrored files trigger gate failure.
  9. AST Symbol Parity Invariant: Public APIs, exported functions, and behavioral symbols must never silently disappear during refactoring without explicit migration approval.
  10. Zero-OS-Tmp Discipline: All scratch buffers and CLI payloads MUST be authored strictly within <repoRoot>/.nomos/data/tmp/ (or <conversation-id>/scratch/), NEVER in host /tmp/.
  11. Consolidated Telemetry & Zero-LLM Substrate Boundary: Nomos Core (nomos-substrate) contains zero AI/LLM inference or prompt logic. Telemetry is consolidated in core/telemetry. Intelligent routing resides in nomos-sovereign-substrate.
  12. Knowledge Integrity & Vault Frontmatter SSoT: All markdown documents across the Intent Plane (vault-intent) must possess machine-verifiable YAML frontmatter (title, type, status, classification, plane, date, authors, tags) adhering to private/nomos/architecture/vault_frontmatter_spec.md. Any document in a public/ directory must be strictly classification: public. Substrate tools (nomos intent doc create, nomos intent doc normalize, nomos intent check) enforce schema validity and prevent classification leaks.

1. 🧠 Central Engine & Playbooks ​

  • Always execute operations via nomos (see nomos --help).
  • Core Workflow Playbooks:
    • /nomos-handshake: Session boot, SQLite health check, GitBrain memory sync, environment verification.
    • /nomos-plan: Strategic backlog triage, debt audit (nomos audit refactor), sizing, bundle dry-runs (nomos task bundle --dry-run).
    • /nomos-design: Generative architecture and interface synthesis across Substrate, Membrane, Intent, and Infra planes.
    • /nomos-exec: Active task execution, transient worktree sandboxing, TDD loop, 39 DoD verification gates & atomic release sync.
    • /nomos-review: Evaluative adversarial red-teaming and AST/DoD gate verification across all planes.
    • /nomos-dual-core-refactor: Coordinated dual-hemisphere refactoring across Intent and Substrate planes.
    • /nomos-ship: Unified 7-Gate Multi-Portal SSoT Synchronization, Release Tagging, and Deployment Orchestrator.
  • Chore Tasks: nomos task chore "Fix typo" (or nomos task start "Fix typo" -t chore) auto-scaffolds lightweight chore worktrees.

2. 🛡️ CODING & STATE STANDARDS ​

  • State Integrity: NEVER manually edit SQLite database files (~/.nomos/data/db/nomos_global.db) or workspace JSON files. All mutations MUST happen via deterministic CLI commands (nomos task start, nomos task transition, nomos task edit).
  • AI-to-AI Paradigm: Nomos is an AI-to-AI deterministic engineering substrate. Architectural decisions, quality gates, and output formats are optimized exclusively for autonomous AI agents ("Autonomous AI Agents" or "AI Agents").
  • The Nomos Cognitive Firewall: Workspace mutability is procedurally locked by the substrate state machine across 9 phases: IDLE (immutable outside active task) → TRIAGE (sizing, tier routing) → SPEC (contracts, invariants) → PLAN (decomposition, DAG tasks, read-only plan) → EDIT (unlocked strictly in transient worktrees for sandboxed TDD) → AUDIT (adversarial red-teaming) → REVIEW (39 binary AST quality gates) → SYNC (2PC atomic release, branch merge, worktree teardown) → LEARN (GitBrain reverse-reflection, vector indexation).
  • PhaseLearn Knowledge Distillation: Following 2PC commit sync, tasks transition into LEARN to execute automated reverse-reflection prior to returning to IDLE. The engine parses walkthroughs and Git Notes (refs/notes/agent), extracts axioms and invariants, and indexes vector embeddings into GitBrain SQLite without flat files. Standalone: nomos task learn [--dry-run] [--task <ID>].
  • Linear Logic & CapBAC Phase Budgets: Governed by CapBAC. Ephemeral AffineCapability tokens minted per (task_id, phase) tuple and revoked upon transition. PreToolUse hooks enforce ceilings (TRIAGE: 10/25k, SPEC: 15/50k, PLAN: 25/75k, EDIT: 50/150k, AUDIT: 20/60k, REVIEW: 15/40k, SYNC: 10/25k, LEARN: 15/50k, IDLE: 0/0). Exceeding quota yields DecisionDeny while allowing phase transition.
  • Phase Tier Governance & Delegation Matrix: Strict Tier 1 phases (SPEC, REVIEW, SYNC, IDLE) are restricted exclusively to Frontier Orchestrator AI and human signoff (enforce_agent_tier: 2 fails closed). Dual-tier phases (EDIT, AUDIT, PLAN, TRIAGE, LEARN) permit delegation. Selective Cognitive Routing: Low-burden chore tasks (cli:low, sizing ≤ 3, leaf refactors, unit tests) are delegated 100% to Tier 2 local SLM workers (nomos code <KEY> / ncode <KEY>) sandboxed in transient worktrees to converge DoD gates and build verified training trajectories. High-leverage architectural designs (cli:high, sizing ≥ 5) and Intent SSoT authoring remain governed directly by Tier 1 Frontier Orchestrators (Sophia / AGY) under 39 Go-native DoD verification gates. When phases.edit.enforce_agent_tier: 2 is set globally, direct transition into EDIT fails closed without delegation. Commits on Tier 2 branches require Tier: 2 and Executor: ncode trailers.
  • Flat-File Planning Artifact Boundary: Writing flat planning files (implementation_plan.md, walkthrough.md, specs/, plans/) into repository source trees is strictly blocked by the Flat-File Planning Artifact Blocker DoD gate and Pre-Commit Hooks. Planning artifacts reside strictly in the Brain artifact directory and distill into GitBrain upon sync.
  • Protocol Symmetry Gate: Substrate state machine modifications (src/nomos/core/state/, src/nomos/modules/exec/phase_*.go, src/nomos/modules/exec/lock.go, src/nomos/modules/exec/substrate.go) strictly require synchronized updates to AGENTS.md and master workflows in the same change unit.
  • IDE Ambient State Isolation: Workspace ambient state (window title [IDE #N: repo] TASK: Summary | PHASE, theme colors) strictly scopes mutations to executing repository and transient task worktrees via helper modules (ide_theme.go, ide.go, stream.go, version.go). Titles omit emojis and reflect explicit IDE identifiers configured in .vscode/settings.json or ecosystem.yaml.
  • Transient Worktree Sandboxing: Direct modifications on protected trunk branches (intent, substrate, membrane, infra, plus legacy baselines) are blocked by Pre-Commit Hooks and CheckWorktreeBoundary. Direct transition to EDIT on root branches fails closed. All agents execute code changes inside transient task worktrees (worktrees/<repo>-<task>) wired via go.work and project_meshes:. Lifecycle: Scaffold ➔ Sandboxed Execution ➔ DoD Verification ➔ Atomic Release & Teardown.
  • Asymmetric Read/Write Workstation Isolation: Workstations adhere to 7-Workstation Isolation Matrix (INT-59). Writes restricted to transient worktrees. Reads governed by PreToolUse Read Jail: Intent is Universal Observer (read-everywhere), Open-Core nomos-substrate air-gapped from Sovereign IP (CheckIPLeak), and Membrane portals air-gapped from Go backend source (dogfooding via @nomos/types and nomos compile types).
  • Memory Topology: GitBrain (Machine Subconscious: vector embeddings, Git Notes refs/notes/agent, Ed25519 receipts <!-- NOMOS_RECEIPT_START --> for commit provenance and semantic search) and Unified Vault (Conscious Contract: Markdown repository for architecture, handbooks, governance, and strategy).
  • Substrate Phase Lock & Multi-Agent Concurrency: Workspace code is locked outside EDIT. Tier 2 delegation executes via nomos code <KEY>. SQLite phase_state records are worktree-scoped and branch-aware, enabling concurrent Tier 1 Orchestrator and Tier 2 NCode workers to operate in parallel transient worktrees with independent locks and DoD gates without cross-session collisions.
  • Release Walkthrough & Schema: Write walkthrough.md to Brain artifact directory without writing flat files to source trees. Format with human-readable sections, appending Dual-Layer Hybrid Schema under ## Git Commit Payload with **Architectural Rationale:**, **Blast Radius & Contracts:**, **Resolution Mechanics:**, and Git Trailers (Task:, Plane:, Tier:, Executor:, Burndown:, Gate-Proof:). Approval governance is Go-enforced via nomos task sync --approve. Legacy headings remain supported.
  • Escape Hatches: Bypass unrelated third-party test failures with **TDD-Skip:** <Reason>, unwired endpoints with **Wire-Skip:** <Reason>, markdown docs with **Doc-Skip:** <Reason>, or math typography with **Math-Skip:** <Reason> trailers in commit payload.
  • Release Execution & Cryptographic Receipts: Execute atomic release via nomos task sync --approve -F walkthrough.md. Release sync generates an Ed25519 commit receipt notarizing task ID, commit hash, 39 DoD gates, and walkthrough SHA, signed with private key (~/.nomos/data/keys/receipt_signer.key) and attached to Git Notes (refs/notes/agent). Verified via nomos verify --verify-receipt <SHA>. HALT and end session upon completion.
  • Inverted Workflow SSoT: The Intent Plane (vault-intent/public/nomos/workflows/) is the definitive Source of Truth (SSoT) for AI workflows (ADR-0011). Substrate src/nomos/core/assets/workflows/ is an embedded air-gapped mirror synchronized via nomos intent embed.
  • Automated 10-Plane Quality Debt Telemetry: Starting any Cycle, Debt, or Refactor task captures an immutable 10-plane BEFORE snapshot in SQLite (repo_health_snapshots). Task completion captures AFTER snapshot, computes net mathematical deltas across all 10 architectural verification planes, and records a standardized Markdown scorecard into task comments (bounded to 8,192 bytes).

2.7 📐 YAGNI & COMPLEXITY STEERING ​

  • YAGNI Ladder: Stdlib first → Native framework features second → Third-party dependencies last. Delete/simplify code before adding abstractions.
  • Anti-Abstraction Guardrails: No single-implementation interfaces without explicit requirement. No boilerplate factory classes or DI wrappers. No magic strings (extract into typed constants).
  • Domain & Layer Boundary Slicing: Tasks must respect Single-Layer Responsibility. Never combine compiled Go substrate changes with markdown playbooks or frontend UI components. Slicing follows topological domains.
  • Mathematical & Telemetry Typography Invariant: Prohibit raw LaTeX math formatting across public docs, handbooks, and vault articles. Standardize universally on native UTF-8 Unicode characters (→, ←, Δ, ≤, ≥, ±, ×, ≠, ≈, dup). Enforced by automated Yang Markdown Math Anti-Regression Gate in nomos verify. Mirrored files with SSoT provenance banners are validated exclusively by cryptographic SHA-256 parity (nomos intent check) and exempted from source lint checks.
  • Zero-Alias Invariant Directive: Command structures in compiled Go engine (src/nomos/cmd/) MUST NOT define .Aliases. All capabilities organized under canonical domain nouns. AST verification fails closed on any non-empty alias slice or unwhitelisted root command.
  • Conciseness Directive: Deliver code-first modifications with at most three lines of unrequested explanation.

2.8 🛡️ QUALITY DEBT & DOCSTRINGS ​

  • Fix on the Fly: Resolve lint, formatting, and docstring warnings on modified files immediately. Orchestrator AI is prohibited from bypassing debt into quality_debt.json.
  • No Boilerplate Comments: Never generate fake or copy-pasted comments to bypass comment density gates. All docstrings must be genuine, descriptive, and multi-line (>= 3 lines).
  • Quality Debt Registration: Log non-trivial legacy debt by scaffolding a backlog tracking task: nomos task create "Resolve Quality Debt: <File/Reason>" -F .nomos/data/tmp/task.md --burden 2 --label "priority:low,type:bug,cli:low".

2.9 🧠 SWARM DELEGATION & OPEN-CORE BOUNDARIES ​

  • Tier 2 Delegation: When enforce_agent_tier: 2 is configured in ecosystem.yaml, Tier 1 Orchestrator delegates execution via nomos code <KEY> or ncode <KEY>.
  • Open-Core Boundary: Swarm execution, NCode workers, and multi-agent coordination logic are strictly proprietary Sovereign features. Never leak Sovereign-tier code into open-source nomos.
  • Tooling & Dependencies: Always add new CLI dependencies or tools to shell.nix buildInputs for reproducible agent environments.
  • Stack Conventions:
    • Backend: Procedural Go standard library, shallow abstractions, deterministic validation.
    • Frontend: Declarative compile-time frameworks (Svelte) and headless primitives.

3. 🛠️ CORE CAPABILITIES SUMMARY ​

  • nomos task: start, plan, transition, sync, learn, list, view, bundle, reset, create, chore, status
  • nomos verify: Runs machine-enforced Definition of Done checks (TDD, Security, Dead Code, Phase Discipline, Protocol Symmetry, Zero-Alias Invariant, Magic Strings), rapid AST file pre-flight (-f, -q), and Ed25519 commit receipt verification (--verify-receipt <SHA>)
  • nomos audit: complexity, duplication, refactor, dead-code, imports, wires, magic-strings, entropy
  • nomos intent: compile, sync, check, reflect, doc, docs, embed, context
  • nomos schema: show, cli, sync, lattice
  • nomos memory: search, index, save, status
  • nomos sys: health, hygiene, backup, workstation, daemon, handshake
  • nomos release: cut, tag, ship, changelog, show, pending
  • Core Playbooks: /nomos-handshake, /nomos-plan, /nomos-design, /nomos-exec, /nomos-review, /nomos-dual-core-refactor, /nomos-ship