Banh Mi Guard (guard)

Dual-Gate Impact Analysis & Regression Guard for AI-Assisted Development
Enforcing the Sandwich Pattern with scope control, deterministic diff auditing, project invariants, and an LLM review.

guard wraps coding workflows in an automated safety harness that verifies changes before and after execution. It runs two gates around each task: a pre-task scope check and a post-task verification gate combining deterministic diff checks, static rules, project invariants, and an LLM review.

Live Documentation: https://okrath.github.io/banh-mi-guard/

Cross-Platform Installation (Windows, Linux, macOS)

Install the guard CLI globally on any platform:

# Recommended: Isolated global installation with pipx
pipx install banh-mi-guard

# Or with standard pip across all platforms:
pip install banh-mi-guard

For environment $PATH configuration, installation from GitHub main, and optional Alibaba OCR CLI setup, see CLI Reference: Installation & Environment Setup.

Five-Minute Quickstart

Integrate guard into your workflow in four simple steps:

# 1. PRE-TASK: Declare scope and capture baseline before editing code
guard pre "Implement mobile responsive navigation drawer" --scope src/components/nav

# 2. EDIT: Modify code using your AI agent (Claude Code, Cursor, Codex, etc.) or editor

# 3. POST-TASK: Verify diffs, static security rules, build health, and LLM approval
guard post

# 4. COMMIT: Commit approved changes (approvals are HMAC-signed; unapproved commits or unsigned older sessions are blocked)
git commit -m "feat: add responsive navigation drawer"

To run deep repository inspection with Alibaba OCR, use guard post --full. For a large or security-sensitive change, the post report asks you (through your agent) whether you want a deeper review by a panel of three reviewers, a full OCR review, or both.

Three-Pillar Architecture

Every modification is verified before and after execution across three layers:

1. Deterministic Pre-Task Gate (0 tokens): Locks declared scope boundaries, records baseline snapshots, and evaluates project invariants.
2. Deterministic Post-Task Verification (0 tokens): Audits diff blast radius, runs compilation/tests, checks for deleted references (DEAD-REF), evaluates static rules (SEC-001 to SEC-008), and detects code hygiene issues.
3. Generative LLM Review: Configured LLM (Claude, GPT, DeepSeek, Ollama, or local agent CLIs) evaluates batched diffs and verified evidence for a final APPROVED or REVISE verdict. Most of its findings are advisory review comments; the hard blocking comes from the deterministic checks of pillars 1 and 2 (see Scoring and the final verdict). Approved sessions receive a cryptographic HMAC signature required by Git commit hooks.

For architectural diagrams, taxonomy, and security specifications, see Architecture Specification.

Command Overview

• Verification Harness (guard pre, guard post, guard run): Enforces the Sandwich Pattern. guard pre sets scope and invariant baselines; guard post audits diffs, executes test suites, and requests gate approval; guard run wraps external commands in both gates atomically. See CLI Reference: Pre & Post.
• Project Invariants (guard invariants): Enforces domain and team behavioral invariants without token costs using regex checks across local (.guard/invariants.json) and shared (guard.invariants.json) files. See CLI Reference: Invariants.
• Agent & Hook Integration (guard install, guard hook, guard agent, guard uninstall): Configures Git hooks (core.hooksPath) and injects directives into global agent instruction files (CLAUDE.md, AGENT.md). Agent hook adapters intercept edit tools to block out-of-scope or unauthorized modifications. See CLI Reference: Installation & Hooks.
• Configuration & Setup (guard config, guard setup): Interactive wizards for configuring LLM credentials (APIs or local agent CLIs like claude, codex, omp), syncing settings to Alibaba OCR, and choosing commit message policies. See CLI Reference: Configuration.
• Review, Findings & Approvals (guard review, guard finding, guard accept, guard reset): Runs on-demand LLM diff reviews, tracks deferred or rejected findings, provides an interactive decision screen when review budgets are exhausted, and archives sessions. See CLI Reference: Review & Accept.
• Diagnostics & Supply-Chain Security (guard doctor, guard update, guard untracked): Performs environment diagnostics, upgrades guard (directly from GitHub) or Alibaba OCR (under a 3-day supply-chain quarantine cooling period covering OCR only), and tracks untracked directory exclusions. See CLI Reference: Doctor & Update.

Documentation & Quality Reference

• 📖 CLI Command Reference: Complete option flags, syntax, and operational rules for every command.
• 🏛️ Architecture Specification: Detailed system taxonomy, defense layers, state isolation, and HMAC approval signing.
• 🔎 Review Options, Stages & Limits: Optional review stages of guard post (reviewer panel, finding validation, test evidence, threat frame), what they cost, and the Not reviewed / limits section of the report. Developer-only measurement tool: Benchmark.
• 🛡️ Quality Pillars & Matrix: 2D quality matrix (domains × pillars), static rule catalog, and scoring rules.
• 🚀 Releasing Guide: Release process, version tagging, and PyPI trusted publishing workflow.
• 🌐 Live Documentation Website: Interactive documentation guide and full feature matrix.

Running the Test Suite

Run the integration and unit test suite locally:

pytest