Hermetic Git Hooks, Task Commit, and Staged Boundary Enforcement Specification

1. Executive Summary & Problem Statement#

Under Law 1 (Dual-Core Inversion) and Law 3 (Hermetic Worktree), the Go substrate governs execution while Tier 1 agents operate inside isolated worktrees.

In uncontained development environments, agents or developers frequently introduce four classes of repository corruption:

1. Direct git commit invocations on protected trunk branches (main), corrupting canonical history.
2. Unsanitized exec.Command("git", ...) calls that inherit host GIT_DIR or GIT_WORK_TREE variables across worktrees.
3. Scratch walkthrough files written directly to the repository root instead of the .tmp/ containment boundary.
4. Redundant file-list dumps in Git commit bodies or missing Task: Git trailers required by release tooling.

This specification defines the Hermetic Git Hooks Lifecycle, the nomos task commit CLI contract, and three statutory probes: Cell 3.1 (staged_boundaries), Cell 3.2 (git_hygiene), and Cell 6.1 (commit_schema).

---

2. Axiomatic Invariants & Governing Laws#

Law #	Law Name	Architectural Invariant	Machine Enforcement Mechanism
1	The Dual-Core Inversion Law	Substrate Go core governs execution; agents commit through canonical CLI commands.	nomos task commit, Cell 3.2 (git_hygiene) AST probe
2	The Non-Verbal Proof Law	Commit rationale prose and anti-shim rules are machine-verified before merge.	Cell 6.1 (commit_schema) gate, table-driven tests
3	The Hermetic Worktree Law	Mutations execute strictly inside transient worktrees while trunk stays read-only.	pre-commit hook, Cell 3.1 (staged_boundaries) gate
4	The Single Source of Truth Law	Git tree diffs own manifests; hooks and gates share Go SSoT.	commit_schema_gate.go, workspace/hooks.go
5	The Zero-Hardcoded-Path Law	Worktrees, hooks, and repository roots resolve dynamically at runtime.	config.ResolveWorktreeDir(), workspace.FindRepoRoot()
6	The Canonical Singularity Law	One commit CLI (nomos task commit) emits Conventional Commits with Task: trailers.	Cell 6.2 (zero_alias) gate, commit-msg hook
7	The Fail-Closed Pre-Flight Law	Boundary escapes, missing Task: trailers, or unsanitized git calls fail closed.	Gate pipeline exit code 1

---

3. Live Git Hooks & Compiled Go SSoT Contracts#

Nomos installs and self-heals three hermetic client-side hooks inside .git/hooks/:

3.1 pre-commit#

• Root Protection: Rejects direct commits on protected trunk branches (main, master, intent, substrate, develop).
• Worktree Boundary Enforcement: Verifies that the working directory resides inside worktrees/<repo>-<KEY>.
• Boundary Escape Audit: Inspects git diff --cached --name-only so staged paths never escape via .. or absolute paths.
• Workflow Enforcement: Fails closed unless nomos task commit exports NOMOS_COMMIT_IN_PROGRESS=1.
• Pre-Flight DoD Verification: Executes nomos verify across all active quality gates.

3.2 commit-msg#

• Prefixed Conventional Subject: Enforces ^\[(INT|SUB)-[1-9][0-9]*(-[a-z0-9-]+)?\]\s+(feat|fix|docs|chore|refactor|test)(\([a-z0-9_,/-]+\))?:\s+\S+ (<= 110 chars) and blocks trailing [KEY] duplicates.
• Anti-Dump, Anti-Scissors & Anti-Shim Guard: Rejects --- scissors lines (in favor of ___), legacy Dual-Layer headers, raw - M file diff dumps, and canned placeholder shims.
• Rationale & Trailer Parity Audit: Requires substantive plain-text rationale prose and a Task: <KEY> RFC 822 Git trailer matching the [<KEY>] subject prefix.

3.3 pre-push#

• Trunk Push Defense: Blocks pushing non-trunk branches directly to remote trunk and runs nomos verify --range before trunk pushes.

3.4 Compiled Go Hook & Hermetic Subprocess Contracts#

Package substrate/src/nomos/core/workspace/ (git.go and hooks.go) defines the compiled Go Single Source of Truth for sanitized Git execution and self-healing hook installation:

package workspace

import "os/exec"

// SanitizedGitEnv returns the current operating system environment stripped of all Git hook variables.
func SanitizedGitEnv() []string

// SafeGitCommand creates an *exec.Cmd targeting the specified directory with sanitized environment variables.
func SafeGitCommand(dir string, args ...string) *exec.Cmd

// RunSafeGit executes a git command in the target directory with a scrubbed environment and returns the output.
func RunSafeGit(dir string, args ...string) ([]byte, error)

// InstallHooks installs the pre-commit, commit-msg, and pre-push defense hooks into .git/hooks.
func InstallHooks(repoRoot string) error

// EnsureHooksInstalled audits .git/hooks and installs canonical hooks if missing or drifting.
func EnsureHooksInstalled(repoRoot string) (bool, error)

---

4. Canonical CLI Interface (nomos task commit)#

Usage:
  nomos task commit [TASK_KEY] [flags]

Flags:
  -m, --message string     Commit summary line (normalized to <=72-rune Conventional Commit subject)
      --rationale string   Problem context and architectural rationale (defaults to Scope & Context)
      --mechanics string   Optional key design mechanics (defaults to deduplicated walkthrough bullets)
  -F, --file string        Optional walkthrough markdown file to hydrate commit prose
  -a, --all                Automatically stage all modified files (default: true)
  -d, --dir string         Working directory (default: current directory or resolved task worktree)

4.1 Deterministic Golden Commit Hydration (INT-874, INT-903, INT-904)#

1. Task Key Resolution: Resolves INT-<N> or SUB-<N> from TASK_KEY, the active worktree directory name, or feature/<KEY>.
2. 80-Rune Subject Normalization: Emits [<KEY>] <type>(<scope>): <summary> within 80 runes, stripping duplicate keys and preserving acronyms (AST, CapBAC, MCP, CLI, Go).
3. Flowing Unwrapped CommonMark Body:
   • Paragraph 1 (Rationale): Hydrates an unwrapped paragraph from --rationale, Living Ledger ## Scope & Context, walkthrough prose, or module intent for IDE hover cards.
   • Optional Mechanics Bullets: Hydrates bullets from --mechanics, deduplicated walkthrough summaries (excluding ## Verification / ## Test), or ## Acceptance Criteria without file dumps.
4. Divider & RFC 822 Git Trailers: Emits a git interpret-trailers-safe ___ CommonMark divider followed by Task: <KEY> and automatic Twin: <TWIN_KEY> whenever TaskRecord.TwinKey is bound.
5. Dirty Worktree Sync Parity: nomos task sync <KEY> -F <walkthrough> routes uncommitted edits through the identical Golden Commit pipeline.

---

5. Statutory Sensor Probes Activated#

5.1 Cell 3.1 (staged_boundaries)#

• Sensor: StagedBoundariesGate (substrate/src/nomos/modules/verify/staged_boundaries_gate.go).
• Invariant: Blocks staged root scratch files outside .tmp/ and enforces transient worktree containment.

5.2 Cell 3.2 (git_hygiene)#

• Sensor: GitSubprocessHygieneGate (substrate/src/nomos/modules/verify/git_hygiene_gate.go).
• Invariant: Requires workspace.SafeGitCommand or workspace.RunSafeGit for every Go git subprocess outside core/workspace/git.go.

5.3 Cell 6.1 (commit_schema)#

• Sensor: CommitSchemaGate (substrate/src/nomos/modules/verify/commit_schema_gate.go).
• Invariant: Validates Conventional Commit subjects, plain-text rationale prose, zero diff dumps, and canonical Task: / Twin: Git trailers across trunk..HEAD.

---

6. Table-Driven Verification Vectors#

Vector ID	Evaluation Subject	Condition	Expected Outcome
TC-HOOK-01	Raw git commit in worktree	NOMOS_COMMIT_IN_PROGRESS unset	Blocked (exit 1); directs caller to nomos task commit.
TC-HOOK-02	nomos task commit	Valid rationale and Task: trailer	Passes pre-commit and commit-msg; records Golden Commit.
TC-GATE-01	Cell 3.1 (staged_boundaries)	walkthrough.md staged at repo root	Fails closed; scratch files belong inside .tmp/.
TC-GATE-02	Cell 3.2 (git_hygiene)	AST contains exec.Command("git", "status")	Fails closed with exact file path and line number.
TC-GATE-03	Cell 6.1 (commit_schema)	Commit missing Task: trailer or [KEY] subject prefix	Fails closed with nomos task commit remedy.
TC-HYD-01	nomos task commit without flags	Task has 3-section card, twin, and walkthrough	Emits <=80-rune subject, unwrapped prose, Task:, and Twin: trailers.
TC-HYD-02	Cell 6.1 (commit_schema) & commit-msg	Commit contains - M file.go dump or canned shim	Fails closed under Law 2 and Law 4.

---

7. Cross-Plane Traceability & DoD Verification#

• Intent Lineage: INT-734, INT-874, INT-903.
• Substrate SSoT: SUB-1212, SUB-1700 (substrate/src/nomos/core/workspace/hooks.go, substrate/src/nomos/core/workspace/git.go, substrate/cli/commit_hydration.go, substrate/cli/commit_subject.go, substrate/src/nomos/modules/verify/staged_boundaries_gate.go, substrate/src/nomos/modules/verify/git_hygiene_gate.go, substrate/src/nomos/modules/verify/commit_schema_gate.go).
• Canonical 7x3 Matrix Coordinates: Cell 3.1 (staged_boundaries), Cell 3.2 (git_hygiene), Cell 6.1 (commit_schema), Cell 6.2 (zero_alias).
• Deterministic Verification: nomos verify audits hook parity, subprocess hygiene, staged boundaries, and branch commit schema compliance with exit code 0.