Transient Git Worktree Sandboxing & 2PC GitOps
In Nomos OS, autonomous AI agents are strictly prohibited from making direct code modifications on protected root branches (master, main, substrate, develop). All active engineering tasks execute inside isolated transient Git worktrees.
🌲 The Worktree Lifecycle
🛡️ Key Architectural Invariants
1. Root Branch Guardrails & Pre-Commit AST Hooks
Direct commits to repository root working trees trigger an immediate rejection via the Git pre-commit hook:
❌ Root Commit Blocked: Modifying source files on protected branch 'substrate' is disallowed.
Active engineering tasks must execute within transient worktrees (worktrees/<repo>-<task>).2. Multi-Repo Mesh Orchestration (go.work)
When a task spans multiple interconnected repositories (e.g. nomos and nomos-sovereign), nomos task start auto-discovers sibling dependencies and scaffolds linked cross-repo worktrees (worktrees/nomos-sovereign-<KEY>). It dynamically generates a localized go.work file so Go compiler symbol resolution works without cross-repo version drift.
3. Snapshot Isolation & Adoption
If a developer or agent has unstaged dirty modifications in the root directory before starting a task:
- By default, uncommitted diffs are safely stashed and restored upon task teardown.
- Passing
--adopt(nomos task start <KEY> --adopt) automatically carries working tree modifications into the newly provisioned worktree.
4. Zero-Leak Atomic Teardown
Upon successful execution of nomos task sync:
- The feature branch is rebased onto the target branch.
- The fast-forward merge is committed.
- The transient directory (
worktrees/<repo>-<KEY>) is purged from disk. - Git metadata (
git worktree prune) and SQLite active task locks are cleaned up in a single transactional step.