Primary Purpose of the kunchenguid/no-mistakes Repository: A Local Git-Proxy Gate

The kunchenguid/no-mistakes repository implements a local Git-proxy gate that intercepts pushes, runs an AI-driven validation pipeline in an isolated worktree, and only forwards branches to the remote after all checks pass.

The no-mistakes project introduces a unique approach to pre-push validation by acting as a gatekeeper between your local repository and the remote. Unlike traditional Git hooks, this tool creates a disposable worktree environment that isolates the developer’s working directory while orchestrating a comprehensive six-step validation process. According to the project documentation in docs/src/content/docs/start-here/introduction.md, the system purposefully separates the "gate" remote from origin to preserve trust and ensure origin is never rewritten directly.

What Is the no-mistakes Git-Proxy Gate?

The Git-proxy gate is the core architectural pattern implemented in this repository. When you run git push no-mistakes my-branch, the command triggers a daemon that intercepts the push and creates a temporary, disposable worktree. This isolation mechanism ensures that your local working directory remains untouched while the gate performs validation.

The gate operates as a distinct remote named no-mistakes, separate from your standard origin. As documented in lines 6-10 of the introduction file, this separation is intentional—it allows the system to rewrite history during the rebase step without risking the integrity of your main remote. The origin remote is never modified directly; only the gate repository at ~/.no-mistakes/repos/<id>.git handles the intermediate processing.

The Six-Step Validation Pipeline

Once a push enters the gate, the system executes a fixed sequence of validation steps defined in internal/pipeline/steps/*. If any step produces a blocking finding, the pipeline pauses for user approval, allowing you to fix, skip, or abort the operation.

The pipeline consists of:

• Rebase – Automatically rebases your branch against the latest upstream to ensure linear history.
• AI-driven code review – Extracts intent from commits and runs reviewer and fixer sessions to catch logical errors.
• Automated testing – Executes user-facing tests when intent is present, providing evidence of correctness.
• Documentation check – Validates that documentation stays in sync with code changes.
• Lint – Runs standard linting tools to enforce style consistency.
• Push and PR creation – Forwards the validated branch to the configured remote and automatically opens a pull request.

After the push completes, the daemon continues monitoring CI status and can auto-fix merge conflicts if they arise.

Installation and Basic Usage

The CLI entry point in cmd/no-mistakes/main.go defines several commands for initializing and interacting with the gate.

To install the gate in a repository:

no-mistakes init

This command installs the /no-mistakes skill and the post-receive hook, creating the gate repository at ~/.no-mistakes/repos/<id>.git.

To push a branch through the gate:

git push no-mistakes my-branch

This triggers the daemon, which runs the full validation pipeline. If all steps pass, the branch forwards to the real remote and opens a PR automatically.

To abort a running pipeline after a blocking finding:

no-mistakes axi abort --run <run-id>

The AXI Interface for Non-Interactive Use

For automation and agent-based workflows, the repository provides the AXI interface (defined in cmd/no-mistakes/main.go). This mode runs the same pipeline without the interactive UI, outputting TOON-formatted results that external agents can parse.

To run the pipeline programmatically:

no-mistakes axi run --intent "add health check"

This interface is particularly useful for CI/CD integrations where human interaction is not possible. The AXI commands support the same validation logic as the interactive mode, ensuring consistent gate behavior across manual and automated workflows.

Key Implementation Files

The architecture relies on several critical components:

• cmd/no-mistakes/main.go – The CLI entry point that parses sub-commands (init, axi, etc.) and routes user input to the appropriate handlers.
• internal/daemon/lock.go – Ensures a single daemon holds the NM_HOME lock, preventing concurrent gate runs that could corrupt the validation state.
• internal/pipeline/steps/* – Contains the implementation of each pipeline stage, including the rebase, review, test, document, lint, and push logic.
• docs/src/content/docs/start-here/introduction.md – Provides the high-level description of the gate model, with lines 22-27 outlining the pre-push steps and lines 48-56 containing the mermaid flowchart that visualizes the pipeline.
• docs/src/content/docs/reference/pipeline-steps.md – Detailed reference documentation for every pipeline step and its specific behavior.

Summary

• The kunchenguid/no-mistakes repository creates a local Git-proxy gate that validates code before it reaches the remote.
• The system uses a disposable worktree to isolate validation from your working directory, preventing interference with local changes.
• A six-step pipeline handles rebase, AI review, testing, documentation sync, linting, and push operations.
• The AXI interface supports non-interactive, agent-based workflows with machine-readable output.
• Key files include cmd/no-mistakes/main.go for the CLI, internal/daemon/lock.go for singleton enforcement, and internal/pipeline/steps/* for stage implementations.

Frequently Asked Questions

How does no-mistakes differ from standard Git hooks?

Standard Git hooks run in your local repository and share the same working directory, which risks interfering with uncommitted changes. The no-mistakes system creates a separate worktree and remote, isolating the validation process entirely. According to the source code in internal/daemon/lock.go, it also ensures only one validation runs at a time through file-based locking, preventing race conditions that standard hooks cannot easily handle.

What happens if a validation step fails?

If any step produces a blocking finding, the pipeline pauses and waits for user approval. You can choose to fix the issue, skip the specific check, or abort the entire operation. The gate will not forward the branch to the remote until you explicitly approve the continuation, as implemented in the pipeline orchestration logic within internal/pipeline/steps/*.

Can no-mistakes be used in CI/CD pipelines?

Yes, through the AXI interface. By running no-mistakes axi run --intent "your intent here", you can execute the same validation pipeline non-interactively. The AXI mode outputs TOON-formatted results that CI systems and automated agents can parse, making it suitable for integration into automated deployment workflows without requiring human intervention.

Where is the gate repository stored locally?

The gate repository is created at ~/.no-mistakes/repos/<id>.git when you run no-mistakes init. This location is separate from your project directory and acts as the intermediate remote that receives pushes before validation. The NM_HOME directory, managed by the locking mechanism in internal/daemon/lock.go, ensures that all gate operations reference this centralized storage location.

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