@heretek-ai/agent-proof

v1.0.4

Published

5 days ago

Agent-Proof Mechanical Hard-Gate CLI for deterministic AI code governance

0High
0Medium
0Low

heretek

agent-proof agent-gate ai-governance pre-commit lefthook biome ruff aislop security code-quality

@heretek-ai/agent-proof 🔒

Zero-Bloat Mechanical Hard-Gate CLI for Autonomous AI Coding Agents — Deterministic multi-tier code governance, sub-50ms post-edit interceptors, sub-2.0s pre-commit hard gates, strict suppression hygiene, and LSP diagnostic envelopes with repair tokens for Claude Code, Antigravity, Cursor, Codex, and Aider.

🎯 Executive Overview

Prompt-based guardrails (CLAUDE.md, .cursorrules, rules.md, system prompts) inevitably degrade under context saturation and complex multi-file refactoring tasks. When autonomous AI coding agents make rapid edits, they frequently introduce AI Slop:

Swallowed Errors & Empty Catch Blocks: try { ... } catch (e) {} or except: pass that mask critical outages.
Strict Suppression Bypass: Blindly inserting // @ts-ignore, // biome-ignore, or # noqa to bypass checks without fixing underlying bugs.
Unsafe Type Casting: Pervasive as any or unchecked type assertions that erode type safety.
Hallucinated Dependencies: Imports from packages not declared in package.json or pyproject.toml.
Architectural Drift & Circular Imports: Breaking modular isolation boundaries and leaking domain abstractions.
Governance Tampering: Agents weakening or modifying linter configs (biome.json, ruff.toml, lefthook.yml) to pass commits.

Agent-Proof replaces soft prompt instructions with deterministic, zero-bloat mechanical hard gates: standalone compiled native binaries (Rust, Go) and lifecycle interceptors that physically prevent non-compliant code from reaching version control.

⚡ The Zero-Bloat Compiled Native Engine Philosophy

Traditional verification frameworks rely on heavy interpreted runtimes (Python venvs, JVMs, Ruby VMs, deep Node.js trees) that introduce 1.2s – 4.0s of startup latency. Agent-Proof strictly enforces compiled, standalone native binaries executing in single-digit to low double-digit milliseconds:

🏗️ 3-Tier Execution Architecture

flowchart TD
    A[AI Coding Agent / Developer] -->|File Modification| B[Stage 1: Agent Tool Interceptor]
    B -->|sub-50ms single AST| C{Biome / Ruff / hadolint / zizmor / ast-grep}
    C -->|Failure| D[LSP Diagnostic Streamer\nLSIF Envelope + Repair Tokens]
    D -->|Autonomous Self-Correction| A
    C -->|Success| E[Git Staging Area]
    E -->|git commit| F[Stage 2: Pre-Commit Hard Gate]
    F -->|sub-2.0s parallel native| G[Lefthook Parallel Runner\nBiome + Ruff + Tach + AISlop + TruffleHog + Typos + Actionlint + Zizmor + Hadolint + Tfsec]
    G -->|Commit Passed| H[Git Working Tree]
    H -->|git push / CI| I[Stage 3: CI & Codebase Graph Governance]
    I -->|Full Graph Analysis| J[Fallow Audit + Sherif + OWASP Noir + Cargo Deny]

Execution Stage SLA Matrix

🤖 Complex AI Agent Task Scenarios & Autonomous Self-Correction

Agent-Proof includes automated test scenarios that explicitly simulate complex real-world tasks where autonomous agents frequently fail, intercepting anti-patterns and emitting actionable repair_tokens:

| Scenario | Complex Task Assigned | Agent Anti-Pattern Injected | Gate Interceptor | Actionable repair_tokens | | :--- | :--- | :--- | :--- | :--- | | 1. Async Auth Migration | Refactor JWT auth from callbacks to async/await | Empty catch (err) {} block | AISlop (AI_SLOP_SWALLOWED_ERROR) | throw new AppError('Operation failed', { cause: error }); | | 2. Strict Type Constraints | Generic data mapper refactoring | Blind // @ts-ignore directive | AISlop (AI_SLOP_UNAUTHORIZED_SUPPRESSION) | Typed interface & type guard replacement | | 3. Multi-Provider LLM Client | Anthropic + OpenAI fallback client | Hardcoded high-entropy OpenAI API token | TruffleHog (VERIFIED_SECRET_OPENAI) | process.env.OPENAI_KEY \|\| process.env.API_KEY | | 4. Batch Ingestion Pipeline | High-throughput batch consumer | Identifier typos (acnowledgeReceipt) | Typos (TYPO_DETECTED) | acknowledgeReceipt | | 5. Microservice Dockerization | Multi-stage Dockerfile generation | Unpinned apt-get & root user | Hadolint (DL3008, DL3002) | USER node, non-root container user | | 6. GitHub Actions Auto-Triage | Issue triage and label workflow | Shell expression injection ${{ github.event.issue.title }} | Zizmor (template-injection) | Safe env: variable mapping | | 7. Modular Boundary Layer | Monorepo cross-package logging | Direct private database pool import in route handler | ast-grep (no-direct-db-query) | Service layer boundary encapsulation | | 8. Autonomous Skill Codegen | Custom agent skill authoring | Missing YAML frontmatter headers | SkillCheck (SKILL_INVALID_FRONTMATTER) | Valid YAML frontmatter block |

🌐 Real-World Polyglot GitHub Matrix Benchmarks

Agent-Proof is continuously verified across real-world open-source repositories spanning major programming ecosystems:

⚡ Performance SLA Benchmarks

| Operation | SLA Target | Measured Latency | Verification Test | | :--- | :--- | :--- | :--- | | Multi-Stack Polyglot Detection | < 30ms | 2 – 4 ms | tests/benchmark.test.ts | | Configuration Codegen (Lefthook, Claude, Biome, Ruff, AISlop) | < 15ms | < 1 ms | tests/benchmark.test.ts | | 1,000-Line LSP Diagnostic Streaming & Aggregation | < 25ms | ~6 ms | tests/benchmark.test.ts | | POSIX chmod 0444 Permission Lock-in | < 10ms | < 1 ms | tests/benchmark.test.ts |

🛡️ Strict Suppression Hygiene Gate

Agents frequently attempt to bypass mechanical gates by inserting blind suppression comments (// @ts-ignore, // biome-ignore, # noqa, // eslint-disable).

Agent-Proof's Suppression Hygiene Gate treats newly inserted unapproved suppression markers as blocking Severity 1 violations:

{
  "source": "aislop",
  "rule_id": "AI_SLOP_UNAUTHORIZED_SUPPRESSION",
  "severity": "ERROR",
  "file_path": "src/auth.ts",
  "error_message": "Unauthorized @ts-ignore suppression comment inserted to bypass type checking.",
  "repair_instruction": {
    "action": "REWRITE_BLOCK",
    "description": "Remove unauthorized suppression comment. Fix the underlying type or lint issue rather than bypassing governance.",
    "repair_tokens": [
      "// Remove suppression comment and fix root cause with type guards or explicit handling"
    ]
  }
}

🚀 Quick Start

Initialize mechanical hard gates in any repository with zero configuration:

# Zero-install execution via npx (Latest Release)
npx @heretek-ai/agent-proof init

# Alternative compatibility aliases
npx create-agent-proof
npx create-agent-gate

# Or install as dev dependency
npm install -D @heretek-ai/agent-proof
npx agent-proof init

CLI Command Reference

Both agent-proof and agent-gate binaries are fully supported:

# Inspect repository stack, emit configs, install git hooks, and lock permissions
agent-proof init [directory]

# Detect language stacks and agent harnesses without modifying filesystem
agent-proof detect [--json]

# Run mechanical gate stages directly
agent-proof run post-edit <filePath>   # Stage 1: PostFileEdit hook (< 50ms)
agent-proof run pre-commit            # Stage 2: Staged files hard gate (< 2.0s)
agent-proof run pre-push              # Stage 3: Full codebase graph audit

# Stream and format raw tool stderr into LSP Diagnostic Envelope
cat tool_output.log | agent-proof format-diagnostics --tool aislop

# Manage immutable governance permissions
agent-proof status                    # Inspect locked status (chmod 0444)
agent-proof lock                      # Apply read-only permission lock
agent-proof unlock                    # Temporarily unlock for admin maintenance

📦 Polyglot Multi-Stack Auto-Detection Matrix

Agent-Proof automatically inspects polyglot repositories and configures appropriate native compiled engines:

| Ecosystem / Stack | Detection Indicators | Generated Mechanical Engine | | :--- | :--- | :--- | | JavaScript / TypeScript | package.json, tsconfig.json, biome.json | Biome (--write, --staged) + Fallow Audit | | Python | pyproject.toml, requirements.txt, Pipfile | Ruff (--fix, --staged) + Tach (architecture) | | Go | go.mod, go.sum | gosec (-quiet) + revive | | Rust | Cargo.toml, Cargo.lock | cargo deny check | | C / C++ | CMakeLists.txt, Makefile, compile_commands.json | clang-format (--Werror) | | C# / .NET | *.csproj, *.sln, global.json | dotnet format (--verify-no-changes) | | Ruby | Gemfile, Gemfile.lock | RuboCop (--force-exclusion) | | Elixir | mix.exs, mix.lock | Credo (--strict) | | GitHub Actions / CI | .github/workflows/*.{yml,yaml} | Actionlint + Zizmor (workflow security) | | Docker / Containers | Dockerfile*, Containerfile*, docker-compose.yml | Hadolint (container security) | | Terraform / IaC | *.tf, *.tfvars, terraform/ | Tfsec (cloud security static analysis) | | Kubernetes | k8s/, kubernetes/, helm/, *.k8s.yml | Kube-Score (pod security context analysis) | | AI Agent Harnesses | .claude/, CLAUDE.md, .cursor/, SKILL.md | Claude Hooks + SkillCheck + Permission Lock-in |

📡 LSP Diagnostic Envelopes & Autonomous Auto-Repair

When any mechanical gate fails, Agent-Proof strips ANSI terminal codes and formats the error stream into a standard LSP Diagnostic Envelope (https://json.schemastore.org/lsif.json):

{
  "$schema": "https://json.schemastore.org/lsif.json",
  "version": "1.0.0",
  "status": "GATE_FAILED",
  "summary": {
    "total_errors": 1,
    "total_warnings": 0,
    "gate_stage": "PreCommit"
  },
  "diagnostics": [
    {
      "source": "aislop",
      "rule_id": "AI_SLOP_SWALLOWED_ERROR",
      "severity": "ERROR",
      "file_path": "src/auth/session.ts",
      "range": {
        "start": { "line": 42, "column": 5 },
        "end": { "line": 44, "column": 6 }
      },
      "error_message": "Empty catch block silently swallows authentication failure.",
      "repair_instruction": {
        "action": "REWRITE_BLOCK",
        "description": "Handle the exception explicitly. Either log the error, rethrow a custom Error, or return an explicit failure response.",
        "repair_tokens": [
          "import { AppError } from '../errors';",
          "throw new AppError('Operation failed', { cause: error });"
        ]
      }
    }
  ]
}

🔒 Immutable File Locking Protocol

To prevent autonomous agents from modifying or deleting governance configs during execution, Agent-Proof enforces a POSIX permission lock (chmod 0444):

# Verify locked configuration files
agent-proof status

# Output:
# 🛡️ Governance Configuration Status:
#    🔒 [LOCKED] .claude/settings.json (mode: 444)
#    🔒 [LOCKED] .claude/hooks.json (mode: 444)
#    🔒 [LOCKED] lefthook.yml (mode: 444)
#    🔒 [LOCKED] biome.json (mode: 444)
#    🔒 [LOCKED] ruff.toml (mode: 444)
#    🔒 [LOCKED] .aislop/config.yml (mode: 444)