Nomos OS Docs

Appearance

Nomos Modules API Reference ​

The modules packages implement the business logic, task ticketing, Definition of Done verification, GitOps orchestration, and state disaster recovery engines.

📦 Modules Packages Catalog (18 Packages) ​

1. modules/task ​

SQLite-backed task ticketing state machine, Cognitive Load Index (CLI) calculation, and topological DAG backlog scheduling.

  • Key Structs: Task (Key, Project, ParentKey, Type, Title, Status, ContextBurden, LogicDepth, Labels, ArchLayer, BlockedBy, BoundPlanHash).
  • Key Methods:
    • (t *Task) CognitiveLoadIndex() int: Calculates composite difficulty score (ContextBurden + LogicDepth).
    • CreateTask(ctx, task) error: Inserts new task into nomos_global.db.
    • ListTasks(ctx, filter) ([]Task, error): Queries open backlog and active tasks across subprojects.

2. modules/verify ​

Runs the 36 Go-native Definition of Done (DoD) quality gates before any task can be synchronized or released.

  • Key Structs: StageResult (Name, Passed, Message, Error), CruftReport.
  • Key Stages:
    • tdd.go: Automated unit test pass rate validation.
    • complexity.go: Cyclomatic complexity threshold enforcement ($< 15$).
    • comments.go: Comment density gate ($\ge 10%$).
    • dead_code.go: Unused private function and dead code branch detector.
    • magic_strings.go: AST literal detector.
    • spec.go: Plan constraint validation against AST changes.

3. modules/gitops ​

Isolated transient Git Worktree sandboxing and 2-Phase Commit (2PC) atomic synchronization.

  • Key Functions:
    • ScaffoldWorktree(repoRoot, branch, taskKey string) (string, error): Scaffolds transient task worktrees (worktrees/<repo>-<task>) and updates go.work.
    • DirectMerge(worktreePath, targetBranch string) error: Fast-forward merges task branches into trunk.
    • TeardownWorktree(worktreePath string) error: Safely removes transient worktree paths.

4. modules/state ​

Hot online SQLite database state snapshotting and disaster recovery using native non-blocking VACUUM INTO.

  • Key Structs: SnapshotMetadata (ID, CreatedAt, GlobalDbSize, LocalDbSize, HasConfig, IntegrityStatus, TablesCount).
  • Key Functions:
    • CreateSnapshot(ctx, name, maxRetention) (*SnapshotMetadata, error): Captures atomic snapshot of nomos_global.db and nomos_local.db with PRAGMA integrity checks.
    • ListSnapshots(ctx) ([]SnapshotMetadata, error): Catalogs available database snapshots.
    • RestoreSnapshot(ctx, id, force) error: Rollback-guarded state restoration from a snapshot archive.
    • AutoBackupCheck(ctx, maxAge, maxRetention) (*SnapshotMetadata, error): Enforces rolling daily backup policy.

5. modules/diag ​

System diagnostics, repo hygiene, and Go module diagnostic reporting.

  • Key Structs: DiagnosticResult (Category, Status, Message).
  • Key Functions:
    • RunDoctor(ctx *workspace.WorkspaceContext) []DiagnosticResult: Evaluates SQLite schemas, toolchains, and environment health.

6. modules/schema ​

CLI AST schema reflection and markdown schema validation.

  • Key Structs: CliSchema (Name, Flags, Subcommands).
  • Key Functions:
    • ExportCliSchemaJSON() ([]byte, error): Walks the Cobra command tree and exports cli_schema.json.

7. modules/release ​

SemVer release cascade orchestration, automated version tagging, and structured release diffing.

  • Key Structs: ReleaseReport, ChangelogSection.
  • Key Functions:
    • GenerateChangelogDiff(ctx, fromTag, toTag string) (*ReleaseReport, error): Extracts structured task payloads between release tags.

8. modules/telemetry ​

Substrate execution trace mining, gate latency profiling, and ASCII dashboard aggregation.

  • Key Functions:
    • MineTelemetry(ctx, window time.Duration) (*TelemetryReport, error): Aggregates execution metrics from local SQLite cache.

9. modules/exec ​

Sandboxed subprocess execution, shell launchers, and environment variable isolation.

  • Key Functions:
    • Command(name string, arg ...string) *exec.Cmd: Prepares wrapped execution commands with sanitized environment variables.

10. modules/env ​

Host environment detection, FHS container discovery, and IDE integration hooks.

  • Key Functions:
    • DetectEnvironment() string: Identifies NixOS, Linux FHS, or standard POSIX runtimes.

11. modules/provider ​

LLM provider client adapters and sampling parameters for local and cloud models.

  • Key Functions:
    • NewClient(settings config.ProviderSettings) (LLMClient, error): Initializes provider client connection.

12. modules/harness ​

AI evaluation benchmark engine and golden dataset test harness.

  • Key Functions:
    • RunEvalSuite(endpoint string, cases []EvalCase) (*EvalResults, error): Executes semantic accuracy benchmarks.

13. modules/integration ​

External tool integrations and Conduit native messaging bridge adapters.

  • Key Functions:
    • SyncConduitManifest(dir string) error: Configures native Chrome messaging manifests.

14. modules/docs ​

Documentation synchronization, VitePress building, and markdown structure validation.

  • Key Functions:
    • Sync() error: Verifies that compiled AST commands match published documentation.

15. modules/swarm ​

Native Go ReAct tool execution loop and multi-agent coordination.

  • Key Functions:
    • ExecuteReActLoop(agentId string, prompt string) (*ReActResult, error): Runs tool execution steps deterministically.

16. modules/workspace ​

Workspace maintenance, database defragmentation, and stale branch pruning.

  • Key Functions:
    • RunHygieneCleanups(ctx *workspace.WorkspaceContext) error: Executes central workspace cleanup routines.

17. modules/adapter ​

Modular agent adapters and multi-agent lifecycle hook safety gateway supporting Google Antigravity (nomos-agy), SophiaLabs Sovereign Nomos Code (nomos-code), Claude Code (nomos-ccode), and OpenCode / Aider (nomos-ocode).

  • Key Structs: NormalizedToolCall, HookResult, Registry.
  • Key Interfaces: Adapter (Name, DisplayName, Tier, NormalizeToolCall, FormatResult, GenerateHookConfig, GuardToolCall).
  • Key Functions:
    • Global.DetectAdapter(payload []byte) Adapter: Auto-discovers caller agent from payload signatures.
    • Global.GetOrDetect(name string, payload []byte) (Adapter, error): Retrieves named or auto-detected agent adapter.

18. modules/vault ​

Living Vault Single Source of Truth (SSoT) compilation, multi-portal content mirroring, and byte-level SHA-256 parity verification.

  • Key Structs: SyncReport, ParityReport, ParityViolation.
  • Key Functions:
    • FindVaultPublic(override string) (string, error): Resolves public vault SSoT root.
    • SyncVault(vaultDir, portalDir string) (*SyncReport, error): Mirrors handbook and dispatches with SSoT provenance banners.
    • AuditParity(vaultDir, portalDir string) (*ParityReport, error): Verifies 100% SHA-256 byte parity without banner drift.
    • SyncDocs(nomosDocsDir, portalDir string, skipBuild bool) error: Synchronizes VitePress documentation distribution.

19. modules/auth ​

Terminal-first cryptographic authentication, local credential storage (~/.nomos/data/auth.json), and license status querying.

  • Key Structs: AuthCredentials (AccessToken, RefreshToken, SignedLicense, UpdatedAt), AuthStatus (IsAuthenticated, Subject, Email, Tier, ExpiresAt, InGracePeriod, RemainingGrace).
  • Key Functions:
    • SaveCredentials(creds *AuthCredentials) error: Atomically persists authentication credentials with strict 0600 file permissions.
    • LoadCredentials() (*AuthCredentials, error): Reads and parses local credentials.
    • ClearCredentials() error: Removes locally persisted auth credentials.
    • GetAuthStatus(pubKey ed25519.PublicKey) (*AuthStatus, error): Inspects local credentials and verifies the cryptographic license signature.