How the no-mistakes Gate Proxy Architecture Handles Disposable Worktrees

The no-mistakes gate proxy architecture isolates every pipeline step inside a temporary Git worktree carved from an immutable bare gate repository, using IPC-backed guards to prevent nested execution and ensure complete reproducibility.

The kunchenguid/no-mistakes repository implements a unique gate proxy pattern that treats validation as a sandboxed operation. By combining a persistent bare gate repository with ephemeral worktrees, the system guarantees that each validation run operates on a pristine checkout while protecting the underlying gate from mutation.

Core Architecture Components

Gate-Aware Command Guard

The architecture prevents corruption through guardGateControl in internal/cli/gate_context.go. This function intercepts pipeline-control commands and checks whether the caller is already inside an active validation step.

If classifyGateControlCaller detects a nested gate context via IPC daemon queries, the guard returns a structured error and refuses to execute commands like no-mistakes init or no-mistakes sync. This safety mechanism ensures that a step running inside a disposable worktree cannot accidentally launch a new pipeline that would corrupt the current isolation boundary.

Execution Context Classification

The classifyGateControlCaller function determines the runtime environment by querying the daemon through the MethodGateContext RPC defined in internal/ipc. It retrieves the current run ID, phase, and nesting status.

When no daemon is available, the implementation falls back to read-only database inspection. This dual-mode detection guarantees that the CLI always knows whether it is operating inside a gate-proxy disposable worktree or a standard user repository, preventing context confusion.

Disposable Worktree Lifecycle

The daemon orchestrates worktree creation through internal/git/git.go. During no-mistakes axi run, the system:

1. Generates a fresh temporary directory
2. Executes git worktree add <dir> <target-commit> against the bare gate repository
3. Records run metadata in the database

The worktree's .git file points back to the bare gate repository using the standard git-worktree pointer format. After the run completes—regardless of success, failure, or user abort—the daemon removes the temporary directory entirely, leaving the immutable gate untouched.

How the Gate Proxy Isolates Each Run

Explicit Agent Prompting

To prevent AI agents from mistaking the worktree pointer file for a "non-repository," the system injects executionContextPromptSection from internal/pipeline/steps/execution_context.go into every agent prompt. This fragment explicitly states:

• The current directory is an isolated git worktree
• The .git pointer file is standard git-worktree layout
• This directory is the source of truth for the current run

This prompt engineering stops agents from searching the filesystem for a "real" checkout and confines them to the disposable worktree boundary.

Strict Git Command Handling

All Git operations route through the git.Run wrapper in internal/git/git.go, which automatically detects bare repositories and prepends --git-dir=<dir>. This prevents the bare-gate-repo trap where standard Git commands would otherwise traverse up to parent worktrees.

The wrapper ensures every subprocess—whether invoked by the step or an embedded agent—operates exclusively on the disposable worktree, never on the underlying bare gate repository.

IPC-Backed Context Enforcement

The daemon exposes run state through IPC, reporting Nested: true when executing inside a worktree. The CLI consumes this state to emit helpful error messages that list allowed commands (such as no-mistakes axi status) while refusing destructive operations.

This creates a single source of truth for gate ownership, enforcing the "one-step-one-phase" contract that keeps disposable worktrees read-only for the step that created them.

Code Implementation Details

Creating a Disposable Worktree

The daemon uses this implementation to spawn isolated environments:

// internal/git/git.go – simplified snippet
func (g *Git) CreateWorktree(dir, commit string) error {
    // git worktree add <dir> <commit>
    return g.Run("worktree", "add", dir, commit)
}

The function receives a fresh t.TempDir() and the target commit SHA, establishing the worktree link to the bare gate repository.

Guarding Against Nested Execution

The protection mechanism in internal/cli/gate_context.go rejects unsafe nested calls:

// internal/cli/gate_context.go – critical guard
func guardGateControl(cmd *cobra.Command) error {
    if !mutatesPipelineControl(cmd) {
        return nil
    }
    result, err := classifyGateControlCaller(cmd.Context())
    if err != nil {
        return err
    }
    if !result.Nested {
        return nil
    }
    return emitGateContextRefusal(cmd, result) // returns a structured exitError
}

When a step attempts to run no-mistakes sync from inside a disposable worktree, this guard aborts with a structured gatecontext.ErrorCode and directs the user to context-appropriate commands.

Agent Context Prompt

The following fragment automatically prepends agent prompts to clarify the worktree layout:

// internal/pipeline/steps/execution_context.go
func executionContextPromptSection() string {
    return `
Execution context:
- You are running inside an isolated git worktree at the current working directory.
- The worktree's .git is a pointer file (not a directory) referencing a bare gate repository elsewhere on disk; this is standard git‑worktree layout and all normal git commands work as expected.
- The worktree is checked out to the change being processed; treat it as the project's source of truth for this run and do not search the filesystem for "the real" checkout - this is it.
- Operate only within this working directory. Do not modify or read from the gate's bare repository or any other clone of this project.
`
}

This explicit context prevents agents from escaping the sandbox and accessing the immutable gate repository directly.

Summary

• Disposable worktrees are created via git worktree add from an immutable bare gate repository, providing pristine isolation for each validation run.
• guardGateControl in internal/cli/gate_context.go prevents nested pipeline execution that could corrupt the current worktree state.
• IPC-backed context via MethodGateContext ensures the CLI and daemon maintain a single source of truth for run ownership and nesting status.
• Explicit agent prompting through executionContextPromptSection ensures AI agents recognize the worktree pointer file as valid and remain within the sandbox.
• Automatic cleanup removes worktree directories after run completion, guaranteeing no cross-run contamination while preserving the bare gate repository unchanged.

Frequently Asked Questions

What is a disposable worktree in the no-mistakes architecture?

A disposable worktree is a temporary Git worktree created by the daemon in internal/daemon/manager.go for each pipeline run. It is carved out of the bare gate repository using git worktree add, checked out to the specific commit being validated, and deleted immediately after the run completes. This pattern ensures every validation step operates on a clean, isolated copy of the code without modifying the persistent gate repository.

How does no-mistakes prevent nested pipeline execution?

The system uses classifyGateControlCaller to query the daemon via IPC and detect when code is running inside an existing disposable worktree. If result.Nested returns true, guardGateControl rejects pipeline-mutating commands like no-mistakes init or no-mistakes sync with a structured error. This prevents a step from accidentally launching a new pipeline that would corrupt the current worktree's isolation.

Why does the gate proxy use a bare repository instead of a standard clone?

The bare gate repository serves as an immutable validation engine that never changes during normal operation. By keeping the gate bare and creating disposable worktrees for each run, the architecture eliminates working directory state pollution and enables safe parallel execution. The bare repository acts as the source of truth while worktrees provide the mutable scratch space needed for validation.

How do AI agents know they are working inside a disposable worktree?

Before each step execution, the system injects executionContextPromptSection from internal/pipeline/steps/execution_context.go into the agent's prompt. This text explicitly describes the git-worktree pointer file layout and instructs the agent to treat the current directory as the source of truth. This prevents agents from mistaking the .git pointer for a non-repository and searching for a "real" checkout elsewhere on the filesystem.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}