# The Invisible Harness: Zero-CLI Agent Walkthrough

- **Canonical URL:** https://sophialabs.ca/handbook/invisible-harness-guide
- **Section:** Part I: Foundations (Architecture & Rigor)
- **Author:** Mark Gantlett
- **Published / Updated:** 2026-10-12 / 2026-11-16

---

Nomos is **not** a CLI workflow you have to memorize or babysit by hand. It is an **indirect-control governance layer** that sits silently between your existing **Tier 1 coding agent** (**Claude Code**, **Cursor**, **Antigravity**, **OpenCode**, **Windsurf**, or **Aider**) and your Git repository. Adoption follows a **3-rung progressive ramp** with zero Day-1 workflow tax: - **Pass 0 (`nomos xray .`):** Audit any legacy repository in 5 seconds with zero file writes (`--markdown`, `--sarif`, `--json`).
- **Pass 1 (`nomos init` or `nomos init --local`):** Enable **Branch Guard** with automatic brownfield baseline detection and auto-detected agent hooks (or a zero-footprint `.git/info/exclude` stealth trial), then code normally on `feat/*` branches.
- **Pass 2 (`nomos init --ci` & `nomos init --worktrees`):** Scaffold offline GitHub Actions (SARIF 2.1.0) and GitLab CI workflows, enforce diff-scoped PR mutation proofs, and graduate to isolated `worktrees/<repo>-<task>` sandboxes with `MTPO` collision checks and atomic 2PC releases whenever ready. --- ## Pass 0: Zero-Init Brownfield X-Ray (`5 Seconds`, Zero Writes) *Goal: Quantify AI technical debt, skipped tests, hollow stubs, CWE sinks, and ready-to-lock architectural boundaries before touching a single file in your repository.* Before committing any configuration to an existing `50k-500k+ LOC` repository, run the read-only polyglot X-Ray scanner after installing `nomos`: ```bash
curl -fsSL https://sophialabs.ca/install | bash
cd your-project
nomos xray .
``` `nomos xray` mutates **zero files** and outputs a Lipgloss terminal scorecard (`--json`, `--markdown` for PRs/Slack, or `--sarif` for OASIS SARIF 2.1.0 Code Scanning) in milliseconds across **11 languages** (including pure-Go `wazero` WASM AST scanning for Java and C# with `CGO_ENABLED=0`): - **`AI Hangover Score` (`0-100`, `Grade A` to `Grade F`):** Composite Git-index-aware (`git ls-files --cached --others --exclude-standard`, honoring `.gitignore`) structural health index across 11 languages, automatically skipping untracked build artifacts, `*.min.js`, `.svelte-kit`, and `.next`.
- **Signature, Reuse & Structural Debt Signals:** Flags structural code clones, `>400 LOC` monoliths, `>60 LOC` functions, high-arity (`>8` parameter) signatures, deep control-flow nesting (`>5` levels), and directory-scoped magic-string duplication clusters (`>10` repeats).
- **Anti-Cheat & Security Signals:** Counts empty/`TODO` function shims, skipped test annotations (`t.Skip`, `@pytest.mark.skip`, `#[ignore]`, `xit`), swallowed/unchecked errors (`_ = fn()`, bare `except: pass`, empty `catch {}`), hardcoded secret/host-path leaks, and CWE taint sinks.
- **Ready-to-Lock Hexagonal Boundaries:** Infers zero-violation directional `architecture_boundaries` you can freeze immediately on Day 0. --- ## Pass 1: Day 1 - Progressive Branch Guard (`nomos init` & `--local`) *Goal: Lock `main`, auto-baseline legacy debt, auto-detect installed coding agents, and work normally on `feat/*` branches in under 60 seconds.* ### Step 1: Install the Static `nomos` Binary Once Install the SHA-256-verified static Go binary (`CGO_ENABLED=0`, zero runtime dependencies) into your standard Go binary path (`$GOBIN` / `$(go env GOPATH)/bin` / `~/go/bin`): ```bash
curl -fsSL https://sophialabs.ca/install | bash
``` Or compile directly from source with Go `1.26+`: ```bash
CGO_ENABLED=0 go install github.com/mgantlett/nomos/substrate/cmd/nomos@main
``` *(To uninstall cleanly at any time: `curl -fsSL https://sophialabs.ca/uninstall | bash`.)* ### Step 2: Initialize Branch Guard or Stealth Mode Inside any Git repository (Go, TypeScript/Svelte, Python, Rust, Ruby, C/C++, Java, Kotlin, C#, or polyglot): ```bash
cd your-project
nomos init # Branch Guard + auto-baseline + auto-detected agent hooks (zero silent main commits)
# nomos init --local # Optional: stealth trial registered solely in .git/info/exclude (clean git status)
``` - **Zero Silent Trunk Commits & Automatic Brownfield Baseline:** Bare `nomos init` scans your codebase automatically, freezes observed legacy debt in `nomos.baseline.json` (`strict_mode: false`) when debt exists, keeps greenfield repos strict (`--strict` forces strict mode anywhere), and configures **`isolation_mode: "branch"`** without touching `main` history.
- **Stealth Trial (`--local`):** Registers `nomos.yaml`, `nomos.baseline.json`, `AGENTS.md`, and installed agent hooks in `.git/info/exclude` instead of modifying `.gitignore`, keeping `git status` clean before opening a team PR.
- **Auto-Detected Agent Hooks (`--agents`):** Automatically wires only the coding agents detected on your workstation (Claude Code, Cursor, OpenCode, Gemini CLI, or Antigravity) or accepts `--agents claude,cursor` to eliminate unwanted dot-dir clutter.
- **Compiled Contracts & Self-Healing Git Guards:** Generates [`nomos.yaml`](https://sophialabs.ca/docs/specs/go_ssot_and_json_schema_spec), compact `AGENTS.md` / `@AGENTS.md` `CLAUDE.md` pointers, sub-5ms `PreToolUse` / `PostToolUse` / `Stop` hooks (`nomos hook install` for explicit additions), and Git hooks (`pre-commit`, `commit-msg`, `post-commit`, `pre-push`) that block direct mutations on `main` and automatically distill resolved traps into local `mneme.db` after passing feature-branch commits. ### Step 3: Code on Normal Feature Branches With Any Agent Create a feature branch and prompt Claude Code, Cursor, Antigravity, OpenCode, or Windsurf in plain English: ```bash
git switch -c feat/ttl-cache
# Prompt your agent: "Add TTL cache eviction to Store with unit tests"
git add -A && git commit -m "feat: add TTL cache eviction"
``` Because `nomos init` wired ambient hooks and Branch Guard, `pre-commit` evaluates all `42` AST & toolchain gates on your diff before the commit lands, and `post-commit` distills verified patterns into `mneme.db`. When an agent hits a gate violation (empty stub, skipped test, function over `60 LOC`, or hardcoded path), `nomos verify` returns a structured [`NomosError`](https://sophialabs.ca/docs/specs/nomos_actionable_error_framework_spec) with the exact file, line, violated law, and remedy so the agent fixes itself on the next turn: ```text
🛡️ Nomos Deterministic Engineering Substrate · Definition of Done
──────────────────────────────────────────────────────────────────────────── Law 1: The Dual-Core Inversion Law [3/3 Cells] PASS (Governance & Control) Law 2: The Non-Verbal Proof Law [3/3 Cells] PASS (Epistemology & Verification) Law 3: The Hermetic Worktree Law [3/3 Cells] PASS (State & Isolation) Law 4: The Single Source of Truth Law [3/3 Cells] PASS (Contracts & Schemas) Law 5: The Zero-Hardcoded-Path Law [3/3 Cells] PASS (Portability & Environment) Law 6: The Canonical Singularity Law [3/3 Cells] PASS (Action Space & Surface) Law 7: The Fail-Closed Pre-Flight Law [3/3 Cells] PASS (Safety & Budgets)
──────────────────────────────────────────────────────────────────────────── ✅ All Laws Enforced · 42/42 Gates Satisfied
``` --- ## Pass 2: CI Proofs, Worktree Graduation & Episodic Memory (`--ci` & `--worktrees`) *Goal: Add zero-phone-home CI verification + OASIS SARIF 2.1.0 Code Scanning, and graduate to isolated Git worktrees, write-time `MTPO` collision radar, and 2PC receipts when your team scales.* ### 1. Scaffold Offline CI Workflows & GitHub PR Mutation Proofs (`nomos init --ci`) Generate deterministic CI workflows (`.github/workflows/nomos-verify.yml` with OASIS SARIF 2.1.0 upload and `.gitlab-ci.yml`) in one command, or run diff-scoped AST mutation testing (`0` LLM tokens) across Go, TypeScript/JS, and Python: ```bash
# Generate zero-phone-home GitHub Actions (SARIF) & GitLab CI workflows:
nomos init --ci # Generate a Zero-Trust PR governance & diff-scoped AST mutation proof receipt locally:
nomos verify --pr --mutate-diff # Attest built-in gate mutation sensitivity (100% MS, 0% FPR):
nomos verify proof
``` *(In GitHub Actions CI, you can also reference `mgantlett/nomos@v4.21.1` via the root composite `action.yml` to post deterministic PR proof receipts in the Job Summary on every pull request.)* ### 2. Graduate to Isolated Worktrees, Causal DAG & `MTPO` Radar (`nomos init --worktrees`) Whenever you want parallel multi-agent isolation (`worktrees/<repo>-<task>`), strict `INT-*` / `SUB-*` separation, and atomic 2PC release notes (`refs/notes/nomos/releases`), run `nomos init --worktrees`. Nomos then tracks live exported AST symbol hulls (`MTPO`) across sibling worktrees and warns on write-time symbol collisions before agents drift into merge conflicts: ```bash
# Upgrade an existing Branch Guard repository to hermetic worktrees:
nomos init --worktrees # Inspect unified phase, active worktrees, CapBAC lease, and HATEOAS Next Actions:
nomos status # Provision a hermetic chore worktree, run MTPO physics radar, or sync via 2PC:
nomos task chore "Add TTL cache eviction"
nomos task dag
nomos physics
nomos task sync SUB-1 -m "Add TTL cache eviction with unit coverage"
git notes --ref=nomos/releases show HEAD
``` ### 3. Query, Seed & Surface Agent Tooling (`Nomos Mneme` & `nomos --help-agent`) Walkthrough lessons and passing feature-branch commits promote into pure-Go SQLite hybrid vector memory (`mneme.db`). Run `nomos --help-agent` anytime to inspect internal agent-harness RPCs (`handshake`, `hook`, `directive`, `capabilities`, `physics`, and the hidden read-only `nomos mcp` JSON-RPC 2.0 stdio server): ```bash
# Query hybrid 64-dim vector + lexical memory (< 50ms local query):
nomos mem recall "redis lock backoff" # Record an explicit architectural decision for future agent sessions:
nomos mem save "Redis distributed locks require bounded jitter backoff" --kind decision --topic "infra/redis"
``` --- ## Pass 3: Month 1 - Policy Dials & Zero-Trust Guardrails (`nomos.yaml`) *Goal: Calibrate AST budgets, zero-trust MCP boundaries, and bilateral contract parity for team and regulated repositories.* All policy configuration lives in `nomos.yaml`, backed by compiled Go SSoT structs (`nomos.schema.json`) and pinned against `main` (`ThresholdIntegrityGate`) so a coding agent inside a task worktree can never weaken your thresholds to force a failing build green. ### 1. Cognitive & Coverage Ratchets ```yaml
governance: quality_gates: thresholds: max_cognitive_debt_score: 45 max_cyclomatic_complexity: 15 max_file_loc: 400 max_func_loc: 60 min_comment_density_pct: 10 min_test_coverage_pct: 55
``` ### 2. Zero-Trust MCP & Compositional Taint Guards Restrict which Model Context Protocol (MCP) servers a coding agent can invoke and block untrusted web ingress from flowing into credential reads or outbound network sinks ([`capability_flow_taint_guard_spec.md`](https://sophialabs.ca/docs/specs/capability_flow_taint_guard_spec) and [`zero_trust_mcp_ifc_spec.md`](https://sophialabs.ca/docs/specs/zero_trust_mcp_ifc_spec)): ```yaml
governance: mcp: default_policy: deny allowed_servers: - github-local - postgres-readonly
``` ### 3. Declarative Outbound Egress, SSRF & Credential Airlock Lock down outbound shell HTTP/network commands (`curl`, `wget`, `nc`, `ssh`, `scp`) in `PreToolUse` with zero proxy infrastructure. Even in default `allow` mode, Nomos blocks cloud metadata/RFC1918 SSRF targets (`169.254.169.254`, `localhost`, private CIDR ranges) and outbound high-entropy API tokens (`sk-*`, `ghp_*`, `AKIA*`, PEM keys): ```yaml
boundaries: egress_mode: allowlist # allow | allowlist | offline allowed_egress_domains: - github.com - proxy.golang.org - registry.npmjs.org blocked_egress_domains: - pastebin.com - webhook.site
``` ### 4. Strict Specification & Schema Parity For repositories maintaining formal `intent/architecture/specs/*_spec.md` contracts alongside implementation code, enable `strict_mode` and `contracts` so `nomos verify` enforces the Canonical Specification Blueprint, `@intent` AST anchors, and `NCTE-100` prose deterministically: ```yaml
governance: quality_gates: strict_mode: true contracts: contracts: enabled: true spec_roots: ["intent/architecture/specs"] schema_files: ["nomos.schema.json"]
``` --- ## Production Rollout Checklist - [ ] Install `nomos` across developer workstations and CI runners (`curl -fsSL https://sophialabs.ca/install | bash`).
- [ ] Run `nomos xray .` to audit baseline AI Hangover hotspots, then run `nomos init` (or `nomos init --local` for a zero-footprint `.git/info/exclude` stealth trial).
- [ ] Run `nomos init --ci` (or wire `mgantlett/nomos` via `action.yml`) into pull-request CI so OASIS SARIF 2.1.0 findings and tautological agent tests are surfaced before review.
- [ ] Code on normal `feat/*` branches with `pre-commit` verification, and run `nomos init --worktrees` whenever your team wants isolated worktrees and 2PC receipts (`git notes --ref=nomos/releases show HEAD`).
