deadpush 0.2.0__py3-none-any.whl

deadpush/ui.py

@@ -0,0 +1,156 @@
+"""
+Premium Rich-powered terminal UI for deadpush.
+
+Makes every command feel modern, beautiful, and trustworthy.
+Only activated if `rich` is installed (graceful fallback to plain output).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    from rich.console import Console
+    from rich.panel import Panel
+    from rich.progress import Progress, SpinnerColumn, BarColumn, TextColumn
+    from rich.table import Table
+    from rich.tree import Tree
+    from rich import box
+    from rich.text import Text
+    RICH_AVAILABLE = True
+except ImportError:
+    RICH_AVAILABLE = False
+    Console = None  # type: ignore
+
+from .graph import DeadSymbol, DebrisFile
+
+
+console = Console() if RICH_AVAILABLE else None
+
+
+def is_rich_available() -> bool:
+    return RICH_AVAILABLE
+
+
+def print_header(title: str, subtitle: str = "") -> None:
+    if not RICH_AVAILABLE:
+        print(f"\n=== {title} ===")
+        if subtitle:
+            print(subtitle)
+        return
+
+    panel = Panel(
+        f"[bold cyan]{title}[/bold cyan]\n[dim]{subtitle}[/dim]",
+        border_style="cyan",
+        box=box.ROUNDED,
+        padding=(1, 2),
+    )
+    console.print(panel)
+
+
+def print_success(message: str) -> None:
+    if RICH_AVAILABLE:
+        console.print(f"[bold green]✅ {message}[/bold green]")
+    else:
+        print(f"✅ {message}")
+
+
+def print_warning(message: str) -> None:
+    if RICH_AVAILABLE:
+        console.print(f"[bold yellow]⚠️  {message}[/bold yellow]")
+    else:
+        print(f"⚠️  {message}")
+
+
+def print_error(message: str) -> None:
+    if RICH_AVAILABLE:
+        console.print(f"[bold red]❌ {message}[/bold red]")
+    else:
+        print(f"❌ {message}")
+
+
+def create_debris_table(debris: list[DebrisFile]) -> Table | str:
+    if not RICH_AVAILABLE:
+        return "\n".join([f"  - {d.path} ({d.category})" for d in debris])
+
+    table = Table(title="Debris Detected", box=box.ROUNDED, show_lines=True)
+    table.add_column("Path", style="cyan", no_wrap=True)
+    table.add_column("Category", style="magenta")
+    table.add_column("Confidence", justify="right")
+    table.add_column("Block Push?", justify="center")
+    table.add_column("Suggestion", style="dim")
+
+    for d in debris:
+        block_style = "[bold red]YES[/bold red]" if d.block_push else "[green]No[/green]"
+        conf = f"{d.confidence * 100:.0f}%"
+        table.add_row(
+            d.path,
+            d.category.replace("_", " ").title(),
+            conf,
+            block_style,
+            d.suggestion[:60] + "..." if len(d.suggestion) > 60 else d.suggestion,
+        )
+    return table
+
+
+def create_dead_symbols_tree(dead_symbols: list[DeadSymbol]) -> Tree | str:
+    if not RICH_AVAILABLE:
+        return f"Found {len(dead_symbols)} dead symbols."
+
+    tree = Tree("[bold red]Dead Code Clusters[/bold red]")
+
+    by_file: dict[str, list[DeadSymbol]] = {}
+    for ds in dead_symbols:
+        by_file.setdefault(ds.symbol.path, []).append(ds)
+
+    for filepath, symbols in sorted(by_file.items()):
+        file_branch = tree.add(f"[cyan]{filepath}[/cyan] ({len(symbols)} symbols)")
+
+        for ds in symbols:
+            tier_color = {
+                "definite": "red",
+                "probable": "yellow",
+                "suspicious": "orange1"
+            }.get(ds.tier, "white")
+
+            label = (
+                f"[{tier_color}]{ds.symbol.name}[/{tier_color}] "
+                f"({ds.tier}, {ds.confidence*100:.0f}%)"
+            )
+            file_branch.add(label)
+
+    return tree
+
+
+def print_scan_summary(
+    total_files: int,
+    dead_count: int,
+    debris_count: int,
+    blocking_debris: int,
+    entry_points: int,
+) -> None:
+    if not RICH_AVAILABLE:
+        print(f"\nScan complete: {dead_count} dead | {debris_count} debris ({blocking_debris} blocking)")
+        return
+
+    table = Table.grid(padding=(0, 2))
+    table.add_row("[bold]Files Scanned[/bold]", str(total_files))
+    table.add_row("[bold red]Dead Symbols[/bold red]", str(dead_count))
+    table.add_row("[bold yellow]Debris Found[/bold yellow]", f"{debris_count} ({blocking_debris} blocking)")
+    table.add_row("[bold green]Entry Points[/bold green]", str(entry_points))
+
+    panel = Panel(table, title="[bold cyan]deadpush Scan Summary[/bold cyan]", border_style="cyan")
+    console.print(panel)
+
+
+def print_blocking_warning(debris: list[DebrisFile]) -> None:
+    if not RICH_AVAILABLE:
+        print("\nCRITICAL: Blocking debris found!")
+        return
+
+    console.print("\n[bold red on white]  🚫 PUSH BLOCKED BY deadpush  [/bold red on white]\n")
+
+    for d in debris:
+        if d.block_push:
+            console.print(f"[red]• {d.path}[/red] — {d.category}")
+            console.print(f"  [dim]{d.suggestion}[/dim]\n")

deadpush/verifier.py

@@ -0,0 +1,168 @@
+"""
+Post-write test verification.
+
+Discovers and runs the most relevant test file for a given source file.
+Used by the MCP verify_write tool so agents can verify their changes.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .config import Config
+
+
+TEST_RESULTS_DIR = ".deadpush/test_results"
+
+
+@dataclass
+class TestResult:
+    passed: bool
+    test_file: str
+    command: str
+    stdout: str
+    stderr: str
+    exit_code: int
+    timestamp: str
+    source_path: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "passed": self.passed,
+            "test_file": self.test_file,
+            "command": self.command,
+            "stdout": self.stdout[-2000:] if len(self.stdout) > 2000 else self.stdout,
+            "stderr": self.stderr[-2000:] if len(self.stderr) > 2000 else self.stderr,
+            "exit_code": self.exit_code,
+            "timestamp": self.timestamp,
+            "source_path": self.source_path,
+        }
+
+
+class TestVerifier:
+    """Discover and run tests for a given source file."""
+
+    def __init__(self, config: Config):
+        self.config = config
+        self.repo_root = config.repo_root
+
+    def find_test_for(self, source_path: str) -> Path | None:
+        """Find the most relevant test file for a source path.
+
+        Convention: deadpush/x.py → tests/test_x.py
+                    src/foo/bar.py → tests/test_foo/bar.py, tests/test_bar.py, etc.
+        """
+        rel = Path(source_path)
+        stem = rel.stem
+        parent = rel.parent
+
+        candidates = [
+            self.repo_root / "tests" / f"test_{stem}{rel.suffix}",
+            self.repo_root / "tests" / f"test_{parent.name}_{stem}{rel.suffix}",
+            self.repo_root / "tests" / parent.name / f"test_{stem}{rel.suffix}",
+            self.repo_root / "tests" / parent.name / f"test_{parent.name}{rel.suffix}",
+            self.repo_root / f"test_{rel}",
+        ]
+
+        for candidate in candidates:
+            if candidate.exists() and candidate.is_file():
+                return candidate.resolve()
+
+        return None
+
+    def find_or_create_results_dir(self) -> Path:
+        results_dir = self.repo_root / TEST_RESULTS_DIR
+        results_dir.mkdir(parents=True, exist_ok=True)
+        return results_dir
+
+    def run_test(self, test_file: Path) -> TestResult:
+        """Run a test file and return structured results."""
+        cmd_config = self.config.test
+        test_path = str(test_file.resolve())
+        command = cmd_config.command.format(test_file=test_path) if "{test_file}" in cmd_config.command else f"{cmd_config.command} {test_path}"
+        timeout = cmd_config.timeout_seconds
+
+        try:
+            proc = subprocess.run(
+                command.split(),
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                cwd=str(self.repo_root),
+            )
+            exit_code = proc.returncode
+            stdout = proc.stdout or ""
+            stderr = proc.stderr or ""
+        except subprocess.TimeoutExpired:
+            exit_code = -1
+            stdout = ""
+            stderr = f"Test timed out after {timeout}s"
+        except FileNotFoundError:
+            exit_code = -2
+            stdout = ""
+            stderr = f"Test command not found: {cmd_config.command}"
+        except Exception as e:
+            exit_code = -3
+            stdout = ""
+            stderr = str(e)
+
+        return TestResult(
+            passed=exit_code == 0,
+            test_file=str(test_file),
+            command=command,
+            stdout=stdout,
+            stderr=stderr,
+            exit_code=exit_code,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+        )
+
+    def verify_write(self, path: str, content: str) -> dict[str, Any]:
+        """Full verification flow: find test → run test → return result.
+
+        Called from the MCP verify_write tool handler.
+        """
+        source_path = Path(path)
+
+        # Find test file
+        test_file = self.find_test_for(str(source_path))
+        if not test_file:
+            return {
+                "verifiable": False,
+                "reason": "No test file found for this source path.",
+                "test_result": None,
+            }
+
+        # Run the test
+        result = self.run_test(test_file)
+
+        # Store result for get_test_results
+        results_dir = self.find_or_create_results_dir()
+        safe_name = source_path.name.replace("/", "__").replace("\\", "__")
+        result_path = results_dir / f"{safe_name}.json"
+        result.source_path = str(source_path)
+        result_path.write_text(json.dumps(result.to_dict(), indent=2), encoding="utf-8")
+
+        return {
+            "verifiable": True,
+            "reason": None,
+            "test_result": result.to_dict(),
+        }
+
+
+def load_recent_results(config: Config, limit: int = 10) -> list[dict[str, Any]]:
+    """Load recent test verification results for get_test_results MCP tool."""
+    results_dir = config.repo_root / TEST_RESULTS_DIR
+    entries = []
+    if results_dir.exists():
+        for f in sorted(results_dir.glob("*.json"), reverse=True)[:limit]:
+            try:
+                entries.append(json.loads(f.read_text(encoding="utf-8")))
+            except Exception:
+                pass
+    return entries

deadpush/watch.py

@@ -0,0 +1,103 @@
+"""
+Watch mode for deadpush.
+
+Continuously monitors the repository for new debris (especially dangerous ones like CLAUDE.md)
+while the developer is actively coding with AI tools.
+
+Usage:
+    deadpush watch
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Callable
+
+try:
+    from watchdog.observers import Observer
+    from watchdog.events import FileSystemEventHandler, FileCreatedEvent, FileModifiedEvent
+    WATCHDOG_AVAILABLE = True
+except ImportError:
+    WATCHDOG_AVAILABLE = False
+
+from .config import load_config
+from .crawler import iter_source_files
+from .debris import DebrisDetector
+from .ui import print_warning, print_success, print_error, is_rich_available
+
+
+class DebrisEventHandler(FileSystemEventHandler):
+    def __init__(self, config, callback: Callable):
+        self.config = config
+        self.callback = callback
+        self.detector = DebrisDetector(config)
+
+    def on_created(self, event):
+        if event.is_directory:
+            return
+        self._check_file(Path(event.src_path))
+
+    def on_modified(self, event):
+        if event.is_directory:
+            return
+        self._check_file(Path(event.src_path))
+
+    def _check_file(self, path: Path):
+        # Only check relevant source/config files
+        from .crawler import get_supported_extensions
+        # always watch code + docs/config for debris
+        code_exts = get_supported_extensions()
+        if path.suffix.lower() not in code_exts | {".md", ".txt", ".env", ".toml", ".yaml", ".yml", ".json"}:
+            return
+        if any(x in str(path) for x in ["__pycache__", ".git", "node_modules", ".deadpush-archive"]):
+            return
+
+        try:
+            # Quick single file debris check
+            from .crawler import FileInfo
+            fi = FileInfo(
+                path=path,
+                rel_path=path.relative_to(self.config.repo_root),
+                size=path.stat().st_size if path.exists() else 0,
+                is_text=True,
+                mtime=time.time()
+            )
+            debris = self.detector.scan([fi])
+            blocking = [d for d in debris if d.block_push]
+
+            if blocking:
+                self.callback(blocking, path)
+        except Exception:
+            pass  # Never crash the watcher
+
+
+def start_watch(callback: Callable | None = None):
+    if not WATCHDOG_AVAILABLE:
+        print_error("Watch mode requires 'watchdog'. Install with: pip install deadpush[watch]")
+        return
+
+    config = load_config()
+    print_success(f"Watching {config.repo_root} for new debris... (Ctrl+C to stop)")
+
+    if callback is None:
+        def default_callback(blocking_debris, changed_path):
+            print_warning(f"\nNew blocking debris detected in {changed_path.name}!")
+            for d in blocking_debris:
+                print(f"  → {d.path} ({d.category})")
+                print(f"    {d.suggestion}")
+        callback = default_callback
+
+    event_handler = DebrisEventHandler(config, callback)
+    observer = Observer()
+    observer.schedule(event_handler, str(config.repo_root), recursive=True)
+    observer.start()
+
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        observer.stop()
+        print_success("\nWatch mode stopped.")
+
+    observer.join()

deadpush-0.2.0.dist-info/METADATA

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: deadpush
+Version: 0.2.0
+Summary: Guardrails for the vibe coding era — reachability-based dead code detection + semantic debris detection with pre-push git hooks
+Project-URL: Homepage, https://github.com/harris-ahmad/deadpush
+Project-URL: Source, https://github.com/harris-ahmad/deadpush
+Project-URL: Bug Tracker, https://github.com/harris-ahmad/deadpush/issues
+Project-URL: Documentation, https://github.com/harris-ahmad/deadpush#readme
+Author-email: Harris Ahmad <harris@deadpush.dev>
+License: MIT
+License-File: LICENSE
+Keywords: ai-coding,call-graph,dead-code,debris-detection,git-hook,llm,reachability,static-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1.7
+Requires-Dist: pathspec>=0.12.1
+Requires-Dist: tree-sitter-cpp>=0.23.0
+Requires-Dist: tree-sitter-go>=0.23.0
+Requires-Dist: tree-sitter-java>=0.23.0
+Requires-Dist: tree-sitter-javascript>=0.23.0
+Requires-Dist: tree-sitter-python>=0.23.0
+Requires-Dist: tree-sitter-rust>=0.23.0
+Requires-Dist: tree-sitter-typescript>=0.23.0
+Requires-Dist: tree-sitter>=0.23.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.45.0; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: rich>=13.7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: watchdog>=4.0.0; extra == 'dev'
+Provides-Extra: rich
+Requires-Dist: rich>=13.7.0; extra == 'rich'
+Provides-Extra: watch
+Requires-Dist: watchdog>=4.0.0; extra == 'watch'
+Description-Content-Type: text/markdown
+
+# deadpush
+
+[![GitHub stars](https://img.shields.io/github/stars/harris-ahmad/deadpush?style=social)](https://github.com/harris-ahmad/deadpush)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Your personal AI Agent Guardian.**  
+Protects you from the mistakes, secrets, and context pollution that AI coding agents (Claude, Cursor, Windsurf, etc.) inevitably create — even when you're not watching.
+
+Run it once with `deadpush protect --daemon` and it runs in the background forever, monitoring your filesystem in real time.
+
+---
+
+## The Problem (2026 AI Coding Reality)
+
+You tell your agent to "add the new feature" and walk away.
+
+30 minutes later you come back to:
+- A `claude.md` or `.cursorrules` file committed to the repo
+- Hardcoded API keys in `.env` files the agent "helpfully" created
+- 47 new "temporary" scripts and scratchpads
+- Dead code and duplicated logic everywhere
+
+**deadpush** is the always-on guardian that catches this the moment it happens.
+
+## One Command. Real Protection.
+
+```bash
+pip install deadpush[watch,rich]
+deadpush protect --daemon
+```
+
+That's it.
+
+It will:
+- Install a smart pre-push git hook
+- Merge AI-specific ignore patterns into `.cursorignore`, `.claudeignore`, and `.gitignore`
+- Start a persistent background process that watches your entire repo
+- Automatically quarantine dangerous files the second they appear
+- Track a **Safety Score** that reacts intelligently when multiple agents are going wild
+
+While you're at the gym, in a meeting, or sleeping, deadpush is on duty.
+
+## See It In Action
+
+```bash
+# After running protect --daemon, try simulating an agent:
+mkdir -p .deadpush-e2e-sandbox
+touch .deadpush-e2e-sandbox/claude.md
+echo 'OPENAI_API_KEY=sk-...' > .deadpush-e2e-sandbox/.env.bad
+
+deadpush status
+deadpush quarantine list
+```
+
+You'll see the guardian react, drop the Safety Score, and quarantine the files.
+
+For a full automated demo of every feature (including burst simulation and call-graph verification):
+
+```bash
+python scripts/full_e2e_test.py --simulate-agent --burst --run-scan
+```
+
+## Key Features
+
+- **True background guardian** — Survives terminal close, supports systemd/launchd autostart
+- **Smart multi-agent Safety Score** — Penalizes bursts of dangerous activity from parallel agents
+- **Automatic quarantine** (never hard-delete) — Easy `deadpush quarantine list` / `restore`
+- **Local Control Interface for agents** — Your AI coding agents can query the guardian themselves (`GET /status`, `/quarantine-list`, etc. on localhost)
+- **Cross-platform pre-push hook** — Works in PowerShell, CMD, and Git Bash
+- **Strong static analysis + verification** — Structured call graphs + `deadpush verify` so you can actually trust (or challenge) the dead code reports
+- **Debris detection** — LLM context files, vibe scratchpads, hardcoded secrets, AI-generated duplicates
+
+## Commands You'll Actually Use
+
+```bash
+deadpush protect --daemon     # The one command you run per repo
+deadpush status               # Is the guardian alive? What's the Safety Score?
+deadpush quarantine list      # See what it caught
+deadpush verify               # Cross-check the static analysis with real references
+```
+
+## Why This Matters in the AI Era
+
+AI agents are incredible productivity multipliers.
+
+They are also incredibly good at creating technical debt, leaking secrets, and polluting your context — especially when you give them long-running tasks and step away.
+
+deadpush is the missing safety net.
+
+## Installation
+
+```bash
+pip install deadpush[watch,rich]
+```
+
+Then run `deadpush protect --daemon` in any repo you care about.
+
+## Windows Users
+
+The pre-push hook ships as a Python script + `.cmd` shim. It works from PowerShell, Command Prompt, and Git Bash. The `deadpush protect` command records the exact Python interpreter so everything works even inside virtualenvs.
+
+## Development
+
+```bash
+git clone https://github.com/harris-ahmad/deadpush
+cd deadpush
+pip install -e ".[dev,watch,rich]"
+```
+
+## Architecture
+
+deadpush is organized into four layers that work together:
+
+### 1. Intercept Layer (`deadpush/intercept.py`)
+The real-time guardrail engine. Every file write is checked against:
+- **Security guardrails**: `eval`, `subprocess`, pickle deserialization, SQL injection patterns
+- **Secret detection**: Hardcoded API keys, tokens, passwords (with **path-aware lowering** — test/mock files get `warn` instead of `block`)
+- **Prompt injection**: AI prompt manipulation patterns (ignore-previous-instructions, role-play overrides, chat markup)
+- **Destructive change detection**: Near-empty rewrites, >50% line reduction
+- **Sensitive config protection**: CI/CD, deployment, Docker files
+- **Layer violations**: Architecture import rules
+- **Debris detection**: AI artifacts, stub code, temp files
+
+**Path-aware guardrails**: Files in `test/`, `spec/`, `tests/`, `__tests__/`, `mocks/`, `fixtures/` directories, or files with `test_`, `_test`, `_spec` stems, automatically receive lowered severity for security/secret checks — recognizing that test code commonly uses patterns that would be dangerous in production.
+
+**Learned false positive suppression**: When the agent adjudicator confirms a finding is a false positive, the pattern is persisted to `.deadpush/learned_patterns.json` and auto-suppressed on future checks. This creates a **feedback-driven learning loop** that reduces noise over time.
+
+### 2. Analysis Layer (`deadpush/deadness.py`, `deadpush/graph.py`, `deadpush/importgraph.py`)
+Multi-factor dead code scoring combining 8 signals:
+- **Call graph in-degree** (0.30): How many callers reference the symbol
+- **Registration detection** (0.20): Framework decorators, URL routes, CLI commands
+- **String reference** (0.10): Name appears as string literal elsewhere
+- **Import count** (0.10): External module imports
+- **Entry point reachability** (0.05): Reachable from detected entry points
+- **Git freshness** (0.05): Recently modified (git blame)
+- **Call chain propagation** (0.10): Callers are themselves live (pass-through scoring)
+- **Test coverage** (0.10): Referenced in test files
+
+Each symbol gets a `DeadnessResult` with an `alive_score` (0.0–1.0), a `tier` (high/medium/low/uncertain), factor breakdown, reasons, and an **uncertainty** field explaining why the classifier might be wrong.
+
+The `uncertainty` field is populated when the signal is ambiguous (e.g., "String reference detected but could be coincidental", "Import found but likely re-export", "Only one caller — may be indirect").
+
+### 3. Call Graph Resolution (`deadpush/cli.py:84-148`)
+The `_resolve_callee_to_symbol` function uses a 5-step heuristic pipeline:
+1. **Local exact match**: Symbol exists in the same file
+2. **Method receiver resolution**: Class methods via receiver name (`self`, `this`, or class name)
+3. **Import resolution**: Module-qualified names from `file_imports`
+4. **Dotted name resolution**: `module.function` style callee splitting
+5. **Fallback name match**: Any symbol with matching name across the project (lowest confidence)
+
+Each step uses exact prefix/suffix matching rather than loose substring checks to avoid false edges.
+
+### 4. MCP Server (`deadpush/mcp_server.py`)
+A Model Context Protocol server (stdio transport) exposing all capabilities as tools:
+- **Agent-as-Adjudicator**: `verify_finding` and `learn_false_positive` tools let the agent itself adjudicate uncertain findings and teach deadpush about false positive patterns, creating a **feedback-driven learning loop**.
+- **Write/Check pipeline**: `write_file`, `check_file`, `get_write_diff`, `retry_write`
+- **Test-verified writes**: `verify_write` runs guardrails + tests atomically
+- **Scanning**: `scan`, `get_dead_symbols`, `get_debris`, `get_test_issues`, `get_stale_docs`, `get_layer_violations`, `get_security_boundaries`, `get_complexity_alerts`
+- **Configuration**: `add_allowed_pattern`, `ignore_path`, `set_guardrail_level`, `reset_runtime_config`
+- **Feedback**: `get_feedback`, `get_recent_feedback`, `acknowledge_feedback`
+
+### Data Flow
+
+```
+Agent writes file
+       ↓
+Intercept Layer checks (security, secrets, prompt injection, debris, layers, destructive changes)
+       ↓
+Path-aware lowering for test/mock files  →  Learned pattern suppression
+       ↓
+Approved?  →  Blocked → Quarantine + Feedback
+  Yes
+       ↓
+MCP verify_write (optional) → Run tests → Pass? → Write
+                                              Fail → Quarantine + Restore from git
+```
+
+## Philosophy
+
+Set it and forget it.
+
+The best guardian is one you forget exists — until the moment it saves you from your own agent.
+
+---
+
+**Star the repo** if you think every developer running AI coding agents in 2026 should have this running in the background.
+
+For the complete source and architecture, see the implementation notes in the repo.