# 🛡️ Parry (`parry.sh`) — Deflect AI Hallucinations & Slop Before `git push`

[![License: MIT](https://img.shields.io/badge/License-MIT-amber.svg)](LICENSE)
[![GitHub Action](https://img.shields.io/badge/GitHub_Action-AI--Ops1%2FParry%40v1-blue.svg?logo=github)](https://github.com/marketplace/actions/parry-ast-gatekeeper-pr-shield)
[![Top-100 Evil AI Benchmark](https://img.shields.io/badge/Evil_AI_Benchmark-100%2F100_Deflected_(100%25)-10b981)](benchmark/manifest.json)
[![Clean Counterparts](https://img.shields.io/badge/Clean_Counterparts-0.0%25_FP-10b981)](benchmark/manifest.json)
[![Execution Latency](https://img.shields.io/badge/Execution_Latency-%3C_150ms_Offline-amber)](benchmark/manifest.json)
[![Live Platform](https://img.shields.io/badge/Live_Platform-parry.scopeledger.net-00e599)](https://parry.scopeledger.net)

> **Zero style nitpicks. Zero token spend. 100% BYOK.**
> Parry is a deterministic hybrid AST gatekeeper built to deflect hallucinated packages, training-cutoff API drift, structural AI slop, and subtle logic traps in AI-generated code before it reaches production.
>
> Directly integrates into **Cursor**, **Claude Code**, **Windsurf**, **VS Code**, **Google Gemini**, **OpenAI Codex**, and **GitHub Actions**.
>
> 🌐 **Interactive Demo & Leaderboard:** [https://parry.scopeledger.net](https://parry.scopeledger.net)

---

## ⚡ 10-Second Proof: Top-100 Evil AI Benchmark & Leaderboard

Standard syntax linters (`eslint`, `flake8`, `cargo check`) catch human typos and syntax errors. AI coding models generate code that is **100% syntactically valid but semantically broken**.

Run Parry against our public **Top-100 Evil AI Benchmark** (100 real-world hallucinated vulnerabilities generated by Claude, GPT-4o, Cursor, and Gemini paired against 100 clean counterpart patches across Python, TypeScript, JavaScript, Rust/Solana, and EVM/Solidity):

```bash
python parry.py bench --leaderboard
```

### Frontier Model Reliability Scorecard (100 Evil AI Cases)

| Rank | System / Evaluated Model | Deflected (Recall) | Clean FP Rate | Execution Latency | Cloud Dependencies |
| :---: | :--- | :---: | :---: | :---: | :---: |
| **#1** | **Parry Hybrid AST Engine** | **100 / 100 (100.0%)** | **0.0%** | **< 150ms** | **Zero (100% Offline)** |
| #2 | **Claude 3.7 Sonnet** (Anthropic) | 58 / 100 (58.0%) | ~4.0% | ~2,400ms | Requires API Token |
| #3 | **Gemini 2.0 Flash** (Google) | 51 / 100 (51.0%) | ~6.0% | ~1,100ms | Requires API Token |
| #4 | **GPT-4o** (OpenAI) | 48 / 100 (48.0%) | ~5.0% | ~2,100ms | Requires API Token |
| #5 | **DeepSeek-V3 / R1** | 42 / 100 (42.0%) | ~8.0% | ~3,200ms | Requires API Token |
| #6 | **Cursor Agent** (Default Prompting) | 39 / 100 (39.0%) | ~7.0% | ~1,800ms | Cloud Agent Proxy |
| #7 | **Standard Linters** (`eslint` + `flake8` + `cargo`) | 8 / 100 (8.0%) | 0.0% | < 50ms | Zero (Local Only) |

> 🧪 Test all 100 paired cases live or play the interactive **"Spot The AI Bug" Challenge** in your browser at [parry.scopeledger.net](https://parry.scopeledger.net#benchmark).

---

## 🚀 What Parry Does

### 1. 🛡️ GitHub Marketplace PR Shield & SARIF Gatekeeper
Drop Parry into any GitHub CI workflow in 30 seconds.
- **Sticky PR Shield Comment**: Posts and updates a single sticky PR comment with deflected bugs, severity, and suggested replacements without spamming pull request activity.
- **AST Baseline Fingerprinting (`.parry-baseline.json`)**: Emits AST-relative SHA-256 fingerprints so PRs only fail on **net-new AI defects** introduced in the PR diff, never failing on pre-existing legacy code debt.
- **Native SARIF 2.1.0**: Directly populates the **GitHub Security / Code Scanning** tab with zero SaaS subscription dependencies.

```yaml
# .github/workflows/parry.yml
name: Parry PR Shield
on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  pull-requests: write
  security-events: write

jobs:
  parry-shield:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: AI-Ops1/Parry@v1
        with:
          paths: "."
          fail-on: "warning"
          comment-pr: "true"
          changed-only: "true"
          sarif-output: "parry-results.sarif"
      - uses: github/codeql-action/upload-sarif@v3
        if: always() && hashFiles('parry-results.sarif') != ''
        with:
          sarif_file: parry-results.sarif
```

---

### 2. ⚡ Turnkey AI IDE Hooks & Local MCP Server
Stop hallucinated packages and logic bugs before they ever reach a git commit.
- **1-Command Universal Setup**: Configure Cursor, Claude Code, Windsurf, VS Code, and Codex with one command:
  ```bash
  python parry.py install-hooks --ide all --instructions
  ```
- **Real-Time Post-Tool-Use Interceptor (<20ms)**: Hooks into Claude Code, Cursor, and Windsurf file edits to inspect and auto-repair AI changes the millisecond they are generated.
- **Git Staged Pre-Commit Hook**: Scans only modified files during `git commit` in under 15ms.
- **Zero-Dependency stdio MCP Server**:
  ```bash
  python parry.py mcp
  ```
  Exposes the `parry_verify_code` tool directly to Claude, Gemini, and Cursor so the model inspects and self-heals its own code before saving.

---

### 3. 🧠 Repo-Context Enforcement & Structural AI Slop Rules
Defend against prompt injections and eliminate lazy AI engineering habits.
- **Prompt Injection Defense for Context Files**:
  Scans `.cursorrules`, `AGENTS.md`, and `CLAUDE.md`. Normalizes Unicode homoglyphs and strips zero-width invisible character evasion attempts (`\u200B`, `\uFEFF`, soft hyphens) used to hijack coding agents.
- **Structural Slop Deflection**:
  - **Type Escape-Hatch Spikes**: Flags lazy type bypassing (`as any`, `@ts-ignore`, `@ts-nocheck`, bare `except: pass`, and unchecked `.unwrap()`).
  - **Loop N+1 Async Traps**: Catches unbatched `await fetch()` or database queries inside serial loops, suggesting `Promise.all` or `asyncio.gather`.
  - **Cross-File Code Duplication**: Warns when AI duplicates utility functions instead of reusing existing imports.
- **Human Review Focus Brief (`--review`)**:
  ```bash
  python parry.py check src/ --review
  ```
  Partitions findings into **Instant 1-Click Auto-Fixes** and an **Architectural Triage Brief** for human reviewers, cutting PR review fatigue.

---

### 4. 🌐 Team Incident Webhooks & Web3 / Smart Contract Safety
- **SSRF-Protected Incident Alerts**: Real-time notifications dispatched to **Slack, Discord, and PagerDuty** whenever high-severity AI vulnerabilities are committed:
  ```bash
  python parry.py check src/ --webhook-url https://hooks.slack.com/services/... --team-enforce
  ```
- **Specialized Web3 & Crypto Threat Suite**:
  ```bash
  python parry.py check contracts/ --web3-audit
  ```
  Specialized detection for Solana Anchor missing signer checks, EVM flash loan oracle manipulation, arbitrary `delegatecall` vulnerabilities, signature replay missing nonces, and slopsquatted crypto packages (`@solana-web3/sdk`, `solana-agent-kit-v2`).
- **Comprehensive Vertical Guides**:
  - [Solo Developers Guide](https://parry.scopeledger.net/guide/solo-devs): Setup for Cursor, Claude Code, and BYOK workflows.
  - [Web3 & High-Stakes Agencies Guide](https://parry.scopeledger.net/guide/web3-agencies): Protocol verification, CI gates, and smart contract compliance.

---

## 💻 CLI Commands Reference

```bash
# --- BENCHMARKING & EVALUATION ---
python parry.py bench                     # Run 100-case Evil AI Benchmark
python parry.py bench --leaderboard       # Display 7-model comparative leaderboard
python parry.py bench --format markdown   # Output leaderboard as Markdown table

# --- CODE SCANNING & DEFLECTION ---
python parry.py check path/to/code        # Scan files or directories
python parry.py check --staged            # Scan only git staged files (< 15ms)
python parry.py check --diff-base origin/main # Scan only files changed in PR branch
python parry.py check --review            # Output Human Review Focus Brief
python parry.py check --web3-audit        # Run Web3 protocol security audit

# --- REPAIR & AUTO-FIX ---
python parry.py fix path/to/code          # Automatically repair deterministic defects in-place
python parry.py check path/to/code --fix  # Preview LLM prompt patches and diffs

# --- BASELINES & SILENCING LEGACY DEBT ---
python parry.py init --baseline .         # Generate .parry-baseline.json to mute legacy debt

# --- IDE HOOKS & MCP ---
python parry.py install-hooks --ide all   # Configure Cursor, Claude, Windsurf, Gemini, Codex
python parry.py install-hooks --ide claude --instructions
python parry.py post-edit <file>          # Real-time PostToolUse file check (< 20ms)
python parry.py mcp                       # Start stdio MCP JSON-RPC 2.0 server

# --- TEAM WEBHOOKS & CI INTEGRATION ---
python parry.py check --webhook-url <url> --team-enforce # Notify Slack/Discord on PR bugs
python parry.py check --format sarif --output parry.sarif # Export SARIF 2.1.0 for GitHub Security
```

---

## 🔌 Multi-AI BYOK Stage 3 Diff-Critic (`--provider`)

Parry works completely offline without API keys. If you want deep semantic critique using your own model, supply your API key with zero cloud proxying:

```bash
# Google Gemini (GEMINI_API_KEY)
python parry.py check src/ --provider gemini

# Anthropic Claude (ANTHROPIC_API_KEY)
python parry.py check src/ --provider claude

# OpenAI / Codex (OPENAI_API_KEY)
python parry.py check src/ --provider codex

# 100% Local Ollama (OLLAMA_HOST)
python parry.py check src/ --provider ollama
```

---

## 📄 License & Attribution

- Open-source core, GitHub Action, IDE hooks, and Top-100 Evil AI Benchmark released under the [MIT License](LICENSE).
- Commercial Team Org Management, Managed Enterprise Webhooks, and Cloud Dashboards powered by [ScopeLedger](https://parry.scopeledger.net).