VibeProof

Deterministic Control Engine, Diff Risk Analysis & Universal Skill Management for AI Coding Assistants.

Compatible with Claude Code, Cursor, Gemini CLI, GitHub Copilot, and Windsurf.

Executive Summary / Resumo Executivo

English

VibeProof provides deterministic verification, risk classification, and boundary controls for code generated by Large Language Models. While AI coding tools significantly accelerate software development, non-deterministic outputs can introduce type safety bypasses, missing boundary checks, unhandled asynchronous exceptions, and credential leaks.

VibeProof analyzes Git differentials line by line, categorizing modifications by structural risk level, synchronizing rule specifications across multiple AI environments, and offering ScopeLock controls to prevent unauthorized directory mutations.

Português (Brasil)

O VibeProof fornece verificação determinística, classificação de risco em diffs e controle de fronteiras de projeto para códigos gerados por modelos de IA. Embora assistentes de código acelerem o desenvolvimento, respostas probabilísticas podem introduzir desvios de tipagem, ausência de tratamento de exceções, falhas em casos de borda e vazamento de credenciais.

O VibeProof analisa diferenças de código no Git linha por linha, categoriza modificações por nível de risco estrutural, sincroniza especificações de regras entre diferentes IAs e fornece o controle ScopeLock para bloquear edições não autorizadas em diretórios protegidos.

Core Capabilities / Funcionalidades Principais

• Semantic Diff Risk Classification (npx vibeproof diff):
  Performs structural and syntax risk analysis on pending Git modifications:

  • High Risk: Type assertions (as any), suppressed linter rules (@ts-ignore), deleted test suites, hardcoded credentials.
  • Medium Risk: State mutations, async functions without explicit error handling, modified public exported signatures.
  • Low Risk / Safe: Imports, interface definitions, markup, formatting.

• Process Audit (npx vibeproof record + npx vibeproof audit):
  Answers a question the diff cannot: was this result arrived at honestly? A test weakened until it passed is, in the final diff, indistinguishable from a test that was legitimately changed — only the order (failed → edited → passed) separates them, and that order exists only while the work is happening. record installs hooks that write an append-only, hash-chained ledger, written by the hook and never by the assistant. audit reads it back and reports:

  • Did the declared command actually run?
  • Did it finish? (There is no exit code — a call that opens and never closes is the only outcome signal the harness gives.)
  • Does its output say what the claim says?
  • Was a test changed after the run that passed it?
  • Was a test changed between the failing run and the passing one?

  Findings are PROVEN, REFUTED or UNDETERMINED. Undetermined is never rendered as a pass and never exits zero. audit refuses to report at all when the ledger does not verify against its anchor: a finding drawn from evidence that may have been edited is not a finding.

  What it does not survive: an agent that rewrites both the ledger and its anchor. Both live on the machine it controls. Honest proof of that needs a co-signer beyond its reach, and there isn't one yet.

• Universal Skill Synchronization (npx vibeproof sync):
  Maintains a single source of truth for architectural guidelines in .vibeproof/skills/ and projects them into:

  • Claude Code (.claude/skills/)
  • Cursor (.cursor/rules/)
  • Gemini CLI (GEMINI.md)
  • GitHub Copilot (.github/copilot-instructions.md)

• Automated Pre-Commit Security (npx vibeproof install-hook):
  Registers an automated Git pre-commit hook that evaluates diffs and blocks commits containing unverified high-risk lines.

• Verdicts & Exit Codes:
  vibeproof diff exits 1 on REJECT and 0 otherwise, which is what allows the pre-commit hook and CI to gate on it.

  | Verdict | Exit | Meaning | |---|---|---| | REJECT | 1 | At least one high-risk line was found. | | INCONCLUSIVE | 0 | Some files could not be read (binary, oversized, permission denied). Never reported as safe. | | REVIEW | 0 | More than five medium-risk lines. | | SAFE | 0 | Everything changed was analyzed and nothing high-risk was found. |

• Context Token Overhead Linter (npx vibeproof lint):
  Calculates active prompt context overhead and checks rule specifications for conflicting directives.

• Local Visual Engine (npx vibeproof ui):
  Spins up a lightweight local monitoring server (http://localhost:3000) detailing connected AI tools, ScopeLock status, and active skill token budgets.

• Multilingual Support (npx vibeproof lang [pt-BR|en]):
  Native support for English and Brazilian Portuguese terminal outputs.

Installation & Usage / Instalação e Uso

VibeProof requires Node.js (>= 18.0.0). No global installation required.

Initialize Project / Inicializar Projeto

npx vibeproof init

Synchronize Architectural Guidelines / Sincronizar Regras

npx vibeproof sync

Run Risk Analysis / Executar Análise de Risco

npx vibeproof diff

Record & Audit the Session / Gravar e Auditar a Sessão

npx vibeproof record                      # install the recorder hooks, then restart your assistant
npx vibeproof audit --command "npm test"  # audit what the assistant claimed

Install Automated Git Pre-Commit Hook / Ativar Pre-Commit Hook

npx vibeproof install-hook

Launch Visual Dashboard / Abrir Painel Visual

npx vibeproof ui

License

MIT License. Copyright (c) VibeProof Team.