WHEN YOU RECEIVE ANY BUG / CRASH / TEST / SECURITY / FIX REQUEST:

1. DO NOT ask the user for stack versions — detect silently (§2.3)
2. DO NOT ask clarifying questions unless genuinely ambiguous
3. CLASSIFY severity (P0–P3) and error type (§3.1, §3.2)
4. RUN git-diff checker or rg before editing
5. FIX the root cause with the smallest possible diff (§4)
6. VERIFY with the VerificationEngine — three-state, never crash (§5)
7. NEVER say "done" until final_gate() returns all_pass == True (§12)

DELIVER IN ONE RESPONSE:
  Analysis → Root Cause → Fix → Tests → Verification → Risk

Fixing bugs is a science, not luck.
Deterministic CLI tools first. The AI agent reasons — no Ollama loop inside checkers.
One surgical change. One regression test. One verification command.
The verifier must be able to say "I don't know." Otherwise it defaults to "yes" —
which is exactly the false positive you are trying to eliminate.

# ponytail: the entire anti-false-positive contract hinges on this enum.
class Status(str, Enum):
    PASS = "PASS"
    FAIL = "FAIL"
    INCONCLUSIVE = "INCONCLUSIVE"  # could not measure -> must NOT count as pass

IF task is "check security of URL" / "scan headers" / "check TLS"
  → QUICK_AUDIT      → Headers + TLS + passive nuclei
IF task is "full audit" / repo or path provided
  → FULL_SCAN        → SCA → SAST → Secrets → DAST → Headers → IaC
IF task is "we've been hacked" / "breach" / "active attack"
  → INCIDENT_RESPONSE → Phase A→E emergency lockdown (§6.6)
IF task is "harden" / "secure this code" / "fix vulnerabilities"
  → HARDENING        → NEVER/ALWAYS remediation (§6.1)
IF task is "CI/CD security" / "DevSecOps"
  → DEVSECOPS        → Generate CI/CD security workflows
IF task is LLM/AI app security / "prompt injection"
  → AI_SECURITY      → OWASP LLM Top 10 audit
IF task is "code review" / "is this secure"
  → CODE_REVIEW      → Manual SAST + NEVER/ALWAYS check
IF task is bug/crash/test
  → DEBUG            → §3.2 error routing → §4 fix → §5 verify

DEFAULT → FULL_SCAN with cross-validation

#!/usr/bin/env bash
# ponytail: detect silently — never ask the user for stack versions.
set -euo pipefail
D="${1:-.}"
langs=""
[ -f "$D/package.json" ] && langs="$langs js/ts"
[ -f "$D/pyproject.toml" ] || [ -f "$D/requirements.txt" ] && langs="$langs python"
[ -f "$D/go.mod" ] && langs="$langs go"
[ -f "$D/Cargo.toml" ] && langs="$langs rust"
[ -f "$D/composer.json" ] && langs="$langs php"
[ -f "$D/Gemfile" ] && langs="$langs ruby"
echo "langs:${langs:-unknown}"
[ -f "$D/package.json" ] && grep -q '"next"' "$D/package.json" && echo "framework:nextjs"
[ -f "$D/manage.py" ] && echo "framework:django"
[ -f "$D/pytest.ini" ] && echo "test:pytest"
grep -q '"vitest"' "$D/package.json" 2>/dev/null && echo "test:vitest"
[ -f "$D/Dockerfile" ] && echo "containers:yes"
[ -f "$D/.env" ] && echo "env_present:HIGH_RISK"

ECONNREFUSED | 502 | 503        → Infra / Network (P0)
Cannot find module | ENOENT     → Build / Import (P1)
TypeError | undefined is not    → Runtime (P1)
CORS | Access-Control           → Backend / proxy (P1)
hydration | did not match       → SSR mismatch (P1)
OOM | heap | SIGKILL            → Memory (P2)
timeout | ETIMEDOUT | slow      → Performance (P2)
403 | permission denied         → Auth (P1)
deadlock | race | intermittent  → Concurrency (P1)
SQLITE_BUSY                     → Concurrent writes (P1)

PIPELINE ORDER: SCA → SAST → Secrets → DAST → Headers/TLS → IaC
GRACEFUL DEGRADATION: one tool failure does not halt the pipeline

# ponytail: regex rewrites break on multiline imports; AST is correct by construction.
import ast
from pathlib import Path

class ImportRemover(ast.NodeTransformer):
    def __init__(self, names: set[str]):
        self.names = names
    def visit_Import(self, node: ast.Import):
        node.names = [a for a in node.names if a.name not in self.names]
        return node if node.names else None
    def visit_ImportFrom(self, node: ast.ImportFrom):
        node.names = [a for a in node.names if a.name not in self.names]
        return node if node.names else None

def remove_unused_imports(path: str, unused: set[str]):
    p = Path(path)
    tree = ast.parse(p.read_text(encoding="utf-8"))
    fixed = ImportRemover(unused).visit(tree)
    ast.fix_missing_locations(fixed)
    p.write_text(ast.unparse(fixed), encoding="utf-8")

#!/usr/bin/env python3
"""Lint only modified files. Falls back to capped 50-file scan if not a git repo."""
import subprocess
from pathlib import Path

def modified() -> list[Path]:
    cmd = "git diff --name-only && git diff --cached --name-only && git ls-files --others --exclude-standard"
    try:
        r = subprocess.run(cmd, shell=True, capture_output=True, text=True, check=True)
        return [Path(f.strip()).resolve() for f in r.stdout.splitlines() if f.strip()]
    except subprocess.CalledProcessError:
        # ponytail: cap at 50 files — never rglob entire monorepo
        out = []
        for ext in ("*.py", "*.ts", "*.js", "*.tsx", "*.sh", "*.go"):
            out.extend(Path(".").rglob(ext))
            if len(out) >= 50:
                break
        return [p.resolve() for p in out[:50]]

def lint(p: Path):
    ext = p.suffix.lower()
    if ext == ".py":
        subprocess.run(["python3", "-m", "py_compile", str(p)], check=False)
        subprocess.run(["ruff", "check", "--fix", str(p)], check=False)
    elif ext in {".js", ".ts", ".tsx", ".jsx"}:
        subprocess.run(["npx", "biome", "check", "--write", str(p)], check=False)
    elif ext == ".sh":
        subprocess.run(["shellcheck", str(p)], check=False)
    elif ext == ".go":
        subprocess.run(["go", "fmt", str(p)], check=False)

for f in modified():
    if f.exists() and f.is_file():
        lint(f)

import json, subprocess
from pathlib import Path

SAFE = {"pytest", "ruff", "mypy", "fastapi", "biome", "vitest", "typescript", "zod", "react", "next"}

def safe_install(name: str, lang: str = "python") -> bool:
    n = name.strip().lower()
    if n not in SAFE:
        if lang == "python":
            lock = Path("requirements.txt").read_text().lower() if Path("requirements.txt").exists() else ""
            if n not in lock:
                print(f"Blocked: {name}"); return False
        elif Path("package.json").exists():
            pkg = json.loads(Path("package.json").read_text())
            deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
            if n not in {d.lower() for d in deps}:
                print(f"Blocked: {name}"); return False
    cmd = ["pip", "install", n] if lang == "python" else ["npm", "install", n]
    return subprocess.run(cmd).returncode == 0

T=0s   Read stack trace
T=5s   rg "symbol" --type py|ts
T=15s  git log --oneline -10 -- <path>
T=20s  Reproduce minimal case
T=25s  git bisect if unknown regression
T=30s  Top 3 hypotheses
T=50s  Minimal fix + regression test
T=60s  ./scan.sh or targeted test command

import json, hashlib, traceback
from dataclasses import dataclass, asdict
from datetime import datetime, timezone

@dataclass
class ErrorLog:
    timestamp: str; error_type: str; message: str; location: str; fingerprint: str

def log_error(err: Exception, path: str = "errors.jsonl") -> str:
    tb = traceback.extract_tb(err.__traceback__)
    frame = tb[-1] if tb else None
    loc = f"{frame.filename}:{frame.lineno}" if frame else "unknown"
    fp = hashlib.md5(f"{type(err).__name__}|{loc}".encode()).hexdigest()[:12]
    entry = ErrorLog(datetime.now(timezone.utc).isoformat(),
                     type(err).__name__, str(err), loc, fp)
    with open(path, "a", encoding="utf-8") as f:
        f.write(json.dumps(asdict(entry)) + "\n")
    return fp

import tracemalloc

def check_memory_allocation(target_func, *args, **kwargs):
    tracemalloc.start()
    before = tracemalloc.take_snapshot()
    target_func(*args, **kwargs)
    after = tracemalloc.take_snapshot()
    tracemalloc.stop()
    for stat in after.compare_to(before, "lineno")[:5]:
        print(stat)

#!/usr/bin/env bash
# Usage: ./scan.sh [--fix] [--lang python|js|all]
set -euo pipefail
FIX=false; LANG="all"; FAILURES=0
for a in "$@"; do case $a in --fix) FIX=true ;; --lang) shift; LANG="$1" ;; esac; done
pass() { echo "[PASS] $*"; }; fail() { echo "[FAIL] $*"; FAILURES=$((FAILURES+1)); }

lint_py() { $FIX && ruff check --fix . && ruff format . || ruff check . && ruff format --check .; pass "Python lint"; }
lint_js() { $FIX && npx biome check --write . || npx biome check .; pass "JS lint"; }
test_py() { pytest -q --tb=short 2>/dev/null && pass "pytest" || fail "pytest"; }
test_js() { npx vitest run 2>/dev/null && pass "vitest" || fail "vitest"; }
security() {
  semgrep --config=p/default --quiet . && pass "Semgrep" || fail "Semgrep"
  gitleaks detect --source=. --no-banner 2>/dev/null && pass "Gitleaks" || fail "Gitleaks"
  trivy fs --severity HIGH,CRITICAL --quiet . && pass "Trivy" || fail "Trivy"
}
case $LANG in python) lint_py; mypy src/ 2>/dev/null || true; test_py ;;
  js) lint_js; npx tsc --noEmit 2>/dev/null || true; test_js ;;
  all) lint_py; lint_js; test_py; test_js ;; esac
security
[ $FAILURES -eq 0 ] && echo "ALL PASSED" || { echo "$FAILURES FAILED"; exit 1; }

#!/usr/bin/env bash
# remote-verify.sh
set -euo pipefail
TARGET="${1:-hetzner-dokploy}"
REMOTE_DIR="${2:-/opt/app-dev}"
rsync -avz --exclude node_modules --exclude .git --exclude .venv \
  ./ "${TARGET}:${REMOTE_DIR}"
ssh "$TARGET" "cd ${REMOTE_DIR} && ./scan.sh"

"""
verification_engine.py — Anti-False-Positive Verification Layer.

Design goals:
  - NEVER report success unless objectively provable.
  - NEVER crash the agent: every check returns a structured result.
  - Deterministic where claimed; tolerance-based otherwise.
  - No silent failures: unmeasurable => INCONCLUSIVE, never PASS.
"""
from __future__ import annotations

import hashlib, json, logging, os, shutil, subprocess, time
from dataclasses import dataclass, field, asdict
from enum import Enum
from pathlib import Path
from typing import Any, Callable, Optional

logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
log = logging.getLogger("verify")


class Status(str, Enum):
    PASS = "PASS"
    FAIL = "FAIL"
    INCONCLUSIVE = "INCONCLUSIVE"  # could not measure -> NOT a pass


@dataclass
class CheckResult:
    name: str
    status: Status
    detail: str = ""
    evidence: dict[str, Any] = field(default_factory=dict)

    @property
    def ok(self) -> bool:
        return self.status is Status.PASS

    def to_dict(self) -> dict[str, Any]:
        d = asdict(self); d["status"] = self.status.value; return d


def run_cmd(args: list[str], timeout: int = 120,
            binary_required: Optional[str] = None) -> tuple[bool, str, str]:
    """Returns (success, stdout, stderr). Never raises."""
    if binary_required and shutil.which(binary_required) is None:
        return False, "", f"Required binary not found on PATH: {binary_required}"
    try:
        proc = subprocess.run(args, capture_output=True, text=True,
                              timeout=timeout, check=False)
        return proc.returncode == 0, proc.stdout, proc.stderr
    except subprocess.TimeoutExpired:
        return False, "", f"Timeout after {timeout}s: {' '.join(args[:3])}..."
    except FileNotFoundError as e:
        return False, "", f"Binary missing: {e}"
    except Exception as e:  # last-resort guard so the agent never crashes
        return False, "", f"Unexpected error: {e!r}"


def _safe_path(path: str | os.PathLike) -> Path:
    return Path(path).expanduser().resolve()


class VerificationEngine:
    def __init__(self, work_dir: str = "./work", max_ram_mb: int = 2048,
                 max_time_sec: int = 600, duration_tolerance_sec: float = 1.0,
                 progress_file: str = "progress.json"):
        self.work_dir = _safe_path(work_dir)
        self.work_dir.mkdir(parents=True, exist_ok=True)
        self.max_ram_mb = max_ram_mb
        self.max_time_sec = max_time_sec
        self.duration_tol = duration_tolerance_sec
        self.progress_file = _safe_path(progress_file)
        self.progress: dict[str, dict[str, Any]] = self._load_progress()

    def _load_progress(self) -> dict[str, dict[str, Any]]:
        if self.progress_file.exists():
            try:
                return json.loads(self.progress_file.read_text())
            except (json.JSONDecodeError, OSError):
                log.warning("progress.json corrupt; starting fresh")
        return {}

    def _save_progress(self) -> None:
        tmp = self.progress_file.with_suffix(".tmp")
        tmp.write_text(json.dumps(self.progress, indent=2))
        tmp.replace(self.progress_file)  # atomic write

    # ----------------------------- duration ------------------------------ #
    def probe_duration(self, path: str | os.PathLike) -> Optional[float]:
        """Return duration in seconds, or None if undeterminable (image, raw)."""
        p = _safe_path(path)
        if not p.exists():
            return None
        ok, out, _ = run_cmd(
            ["ffprobe", "-v", "error",
             "-show_entries", "format=duration:stream=duration",
             "-of", "json", str(p)],
            binary_required="ffprobe",
        )
        if not ok:
            return None
        try:
            data = json.loads(out)
        except json.JSONDecodeError:
            return None
        fmt_dur = data.get("format", {}).get("duration")
        if fmt_dur not in (None, "N/A"):
            try:
                return float(fmt_dur)
            except ValueError:
                pass
        for stream in data.get("streams", []):
            sd = stream.get("duration")
            if sd not in (None, "N/A"):
                try:
                    return float(sd)
                except ValueError:
                    continue
        return None

    # --------------------------- utility test ---------------------------- #
    def verify_file(self, path: str | os.PathLike,
                    expected_duration: Optional[float] = None) -> CheckResult:
        name = f"verify_file:{Path(path).name}"
        p = _safe_path(path)
        if not p.exists():
            return CheckResult(name, Status.FAIL, "File missing", {"path": str(p)})
        size = p.stat().st_size
        if size == 0:
            return CheckResult(name, Status.FAIL, "File empty", {"size": 0})
        ok, _, err = run_cmd(
            ["ffprobe", "-v", "error", "-show_entries", "format=duration",
             "-of", "json", str(p)], binary_required="ffprobe",
        )
        if not ok:
            return CheckResult(name, Status.FAIL, f"Invalid media: {err.strip()}",
                               {"size": size})
        duration = self.probe_duration(p)
        if duration is None:
            if expected_duration is not None:
                return CheckResult(name, Status.INCONCLUSIVE,
                                   "Cannot measure duration but one was expected",
                                   {"size": size})
            return CheckResult(name, Status.PASS, "Valid (no duration applicable)",
                               {"size": size})
        if expected_duration is not None:
            diff = abs(duration - expected_duration)
            if diff > self.duration_tol:
                return CheckResult(
                    name, Status.FAIL,
                    f"Duration mismatch: got {duration:.3f}s, "
                    f"expected {expected_duration:.3f}s (tol {self.duration_tol}s)",
                    {"duration": duration, "expected": expected_duration, "diff": diff},
                )
        return CheckResult(name, Status.PASS, f"Valid, duration={duration:.3f}s",
                           {"duration": duration, "size": size})

    # --------------------- live frame inspection ------------------------- #
    def capture_inspection_frame(self, video_path: str | os.PathLike,
                                 output_dir: str | os.PathLike,
                                 pct: float = 0.5) -> CheckResult:
        name = f"inspect_frame:{int(pct * 100)}pct"
        if not (0.0 <= pct <= 1.0):
            return CheckResult(name, Status.FAIL, f"pct out of range: {pct}")
        duration = self.probe_duration(video_path)
        if duration is None or duration <= 0:
            return CheckResult(name, Status.INCONCLUSIVE,
                               "Cannot determine video duration")
        out_dir = _safe_path(output_dir)
        out_dir.mkdir(parents=True, exist_ok=True)
        ss = duration * pct
        frame_path = out_dir / f"inspect_{int(pct * 100)}pct.jpg"
        ok, _, err = run_cmd(
            ["ffmpeg", "-y", "-ss", f"{ss:.3f}", "-i", str(_safe_path(video_path)),
             "-vframes", "1", "-q:v", "2", str(frame_path)],
            binary_required="ffmpeg",
        )
        if not ok or not frame_path.exists() or frame_path.stat().st_size == 0:
            return CheckResult(name, Status.FAIL, f"Frame extraction failed: {err.strip()}")
        return CheckResult(name, Status.PASS, f"Frame captured at {ss:.2f}s",
                           {"frame_path": str(frame_path), "timestamp": ss})

    # --------------------------- scene count ----------------------------- #
    def count_scene_changes(self, video_path: str | os.PathLike,
                            threshold: float = 0.3) -> Optional[int]:
        ok, _, err = run_cmd(
            ["ffmpeg", "-i", str(_safe_path(video_path)), "-vf",
             f"select='gt(scene,{threshold})',metadata=print", "-an",
             "-f", "null", "-"],
            timeout=self.max_time_sec, binary_required="ffmpeg",
        )
        if not ok and "scene" not in err:
            return None
        cuts = err.count("lavfi.scene_score")
        return cuts + 1  # scenes, not cuts

    # ---------------------------- sync / E2E ----------------------------- #
    def sync_test(self, video_path: str | os.PathLike,
                  expected_scene_count: Optional[int] = None,
                  min_audio_words: int = 1,
                  transcribe: bool = True) -> CheckResult:
        name = "sync_test"
        vp = _safe_path(video_path)
        evidence: dict[str, Any] = {}

        # 1. Extract audio
        audio_path = self.work_dir / (vp.stem + ".wav")
        ok, _, err = run_cmd(
            ["ffmpeg", "-y", "-i", str(vp), "-vn", "-ac", "1", "-ar", "16000",
             str(audio_path)], binary_required="ffmpeg",
        )
        if not ok or not audio_path.exists() or audio_path.stat().st_size == 0:
            return CheckResult(name, Status.FAIL,
                               f"Audio extraction failed: {err.strip()}")
        evidence["audio_bytes"] = audio_path.stat().st_size

        # 2. Mean volume (silence check)
        ok, _, vol_err = run_cmd(
            ["ffmpeg", "-i", str(audio_path), "-af", "volumedetect",
             "-f", "null", "-"], binary_required="ffmpeg",
        )
        mean_vol = None
        for line in vol_err.splitlines():
            if "mean_volume:" in line:
                try:
                    mean_vol = float(line.split("mean_volume:")[1].split("dB")[0])
                except (ValueError, IndexError):
                    pass
        evidence["mean_volume_db"] = mean_vol
        audio_audible = mean_vol is not None and mean_vol > -60.0

        # 3. Optional transcription
        word_count = None
        if transcribe and shutil.which("whisper"):
            ok, _, _ = run_cmd(
                ["whisper", str(audio_path), "--model", "tiny",
                 "--output_format", "json", "--output_dir", str(self.work_dir)],
                timeout=self.max_time_sec, binary_required="whisper",
            )
            json_out = self.work_dir / (audio_path.stem + ".json")
            if ok and json_out.exists():
                try:
                    tdata = json.loads(json_out.read_text())
                    word_count = len(tdata.get("text", "").split())
                    evidence["transcript_words"] = word_count
                except (json.JSONDecodeError, OSError):
                    word_count = None

        # 4. Scene count
        scene_count = self.count_scene_changes(vp)
        evidence["scene_count"] = scene_count

        # ---- Decide status ----
        failures: list[str] = []
        inconclusive: list[str] = []
        if not audio_audible:
            failures.append(f"audio inaudible (mean_volume={mean_vol})")
        if transcribe:
            if word_count is None:
                inconclusive.append("transcription unavailable")
            elif word_count < min_audio_words:
                failures.append(f"too few words: {word_count} < {min_audio_words}")
        if expected_scene_count is not None:
            if scene_count is None:
                inconclusive.append("scene count unmeasurable")
            elif scene_count != expected_scene_count:
                failures.append(
                    f"scene count {scene_count} != expected {expected_scene_count}")

        if failures:
            return CheckResult(name, Status.FAIL, "; ".join(failures), evidence)
        if inconclusive:
            return CheckResult(name, Status.INCONCLUSIVE, "; ".join(inconclusive), evidence)
        return CheckResult(name, Status.PASS, "A/V verified", evidence)

    # --------------------- deterministic stability ----------------------- #
    def stability_test(self, pipeline_func: Callable[[Any], str],
                       input_data: Any, runs: int = 3) -> CheckResult:
        """
        Encoded media is rarely byte-identical. We hash *decoded, normalized
        content* via ffmpeg framemd5, which IS deterministic for the same frames.
        """
        name = "stability_test"
        if runs < 2:
            return CheckResult(name, Status.INCONCLUSIVE, "runs must be >= 2")
        content_hashes: list[str] = []
        for i in range(runs):
            try:
                output = pipeline_func(input_data)
            except Exception as e:
                return CheckResult(name, Status.FAIL, f"Run {i} crashed: {e!r}")
            out_p = _safe_path(output)
            if not out_p.exists():
                return CheckResult(name, Status.FAIL, f"Run {i} produced no file")
            h = self._content_hash(out_p)
            if h is None:
                return CheckResult(name, Status.INCONCLUSIVE,
                                   f"Run {i} content not hashable")
            content_hashes.append(h)
        identical = len(set(content_hashes)) == 1
        return CheckResult(
            name, Status.PASS if identical else Status.FAIL,
            "Deterministic" if identical else "Non-deterministic output",
            {"hashes": content_hashes, "identical": identical},
        )

    def _content_hash(self, path: Path) -> Optional[str]:
        ok, out, _ = run_cmd(
            ["ffmpeg", "-i", str(path), "-map", "0", "-f", "framemd5", "-"],
            timeout=self.max_time_sec, binary_required="ffmpeg",
        )
        if not ok:
            try:
                return hashlib.sha256(path.read_bytes()).hexdigest()
            except OSError:
                return None
        payload = "\n".join(l for l in out.splitlines() if l and not l.startswith("#"))
        return hashlib.sha256(payload.encode()).hexdigest()

    # ------------------------- performance ------------------------------- #
    def performance_monitor(self, cmd_args: list[str],
                            timeout: Optional[int] = None) -> CheckResult:
        """Runs a subprocess (so we can kill IT) and enforces RAM + time limits."""
        try:
            import psutil
        except ImportError:
            return CheckResult("performance", Status.INCONCLUSIVE,
                               "psutil not installed")
        name = "performance_monitor"
        timeout = timeout or self.max_time_sec
        peak_ram_mb = 0.0
        start = time.time()
        try:
            proc = subprocess.Popen(cmd_args, stdout=subprocess.PIPE,
                                    stderr=subprocess.PIPE, text=True)
        except (FileNotFoundError, OSError) as e:
            return CheckResult(name, Status.FAIL, f"Launch failed: {e!r}")
        ps = psutil.Process(proc.pid)
        killed_reason = None
        while proc.poll() is None:
            elapsed = time.time() - start
            try:
                rss = ps.memory_info().rss
                for child in ps.children(recursive=True):
                    try:
                        rss += child.memory_info().rss
                    except (psutil.NoSuchProcess, psutil.AccessDenied):
                        pass
                peak_ram_mb = max(peak_ram_mb, rss / 1024 / 1024)
            except (psutil.NoSuchProcess, psutil.AccessDenied):
                pass
            if peak_ram_mb > self.max_ram_mb:
                killed_reason = f"RAM limit exceeded: {peak_ram_mb:.0f}MB"
            elif elapsed > timeout:
                killed_reason = f"Time limit exceeded: {elapsed:.0f}s"
            if killed_reason:
                proc.kill()
                proc.wait(timeout=5)
                break
            time.sleep(0.2)
        elapsed = time.time() - start
        evidence = {"peak_ram_mb": round(peak_ram_mb, 1),
                    "time_sec": round(elapsed, 2),
                    "return_code": proc.returncode}
        if killed_reason:
            return CheckResult(name, Status.FAIL, killed_reason, evidence)
        if proc.returncode != 0:
            return CheckResult(name, Status.FAIL,
                               f"Process exited {proc.returncode}", evidence)
        return CheckResult(name, Status.PASS, "Within limits", evidence)

    # ---------------------------- checkpoint ----------------------------- #
    def checkpoint(self, task_name: str, status: str,
                   evidence_path: Optional[str] = None) -> dict[str, Any]:
        self.progress[task_name] = {
            "status": status,
            "timestamp": time.time(),
            "evidence": evidence_path,
            "verified": False,
        }
        self._save_progress()
        return self.progress[task_name]

    # ------------------------------ final gate --------------------------- #
    def final_gate(self, required_outputs: dict[str, str | os.PathLike],
                   expected_durations: Optional[dict[str, float]] = None
                   ) -> tuple[bool, dict[str, Any]]:
        """
        The agent CANNOT declare success unless EVERY required output is PASS.
        INCONCLUSIVE counts as NOT passing (anti-false-positive core rule).
        """
        expected_durations = expected_durations or {}
        all_pass = True
        report: dict[str, Any] = {}
        for name, path in required_outputs.items():
            res = self.verify_file(path, expected_durations.get(name))
            report[name] = res.to_dict()
            self.progress.setdefault(name, {})
            self.progress[name]["verified"] = res.ok
            self.progress[name]["verify_info"] = res.detail
            if not res.ok:
                all_pass = False
        self._save_progress()
        return all_pass, report


# ---------------------------------------------------------------------------- #
# Bounded self-heal: max 3 attempts, evidence-based, never fake-pass.
# ---------------------------------------------------------------------------- #
def verify_with_self_heal(check_fn: Callable[[], CheckResult],
                          fix_fn: Callable[[CheckResult], None],
                          max_attempts: int = 3) -> CheckResult:
    result = check_fn()
    for attempt in range(max_attempts):
        if result.status is Status.PASS:
            return result
        log.warning(f"Attempt {attempt+1} {result.status}: {result.detail}")
        if attempt < max_attempts - 1:
            fix_fn(result)            # apply targeted fix using result.detail
            result = check_fn()       # re-verify
    return result                     # final (failing) result, never a fake pass

─────────────────────────────────────────────────
TOOL VERIFY: [tool name] [version]
Command run:  [exact command with all flags — no placeholders]
Exit code:    [actual numeric: 0, 1, 2...]
Duration:     [elapsed seconds]
Output size:  [bytes or line count]
Sample line:  [first non-empty line of real stdout/stderr, max 120 chars]
Status:       EXECUTED | SKIPPED (reason: ...) | FAILED (error: ...)
─────────────────────────────────────────────────

def test_engine_catches_failures(tmp_path):
    eng = VerificationEngine(work_dir=tmp_path)
    empty = tmp_path / "empty.mp4"; empty.touch()
    assert eng.verify_file(empty).status is Status.FAIL
    assert eng.verify_file(tmp_path / "nope.mp4").status is Status.FAIL
    res = eng.verify_file(known_5s_video, expected_duration=30.0)
    assert res.status is Status.FAIL

# SQL Injection
NEVER:  cursor.execute("SELECT * FROM users WHERE id=" + user_id)
ALWAYS: cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
ALWAYS: User.objects.filter(id=user_id)  # Django ORM

# Password Hashing
NEVER:  hashlib.md5(password.encode()).hexdigest()
NEVER:  hashlib.sha256(password.encode()).hexdigest()
ALWAYS: bcrypt.hashpw(password.encode(), bcrypt.gensalt(rounds=12))

# Deserialization
NEVER:  pickle.loads(user_data)
NEVER:  yaml.load(user_data)             # without Loader=
ALWAYS: yaml.safe_load(user_data)
ALWAYS: json.loads(user_data)            # for untrusted input

# Secrets
NEVER:  API_KEY = "sk-abc123"
ALWAYS: API_KEY = os.environ.get("API_KEY"); assert API_KEY, "API_KEY not set"

# Session (settings.py)
SESSION_COOKIE_SECURE = True
SESSION_COOKIE_HTTPONLY = True
SESSION_COOKIE_SAMESITE = "Strict"
CSRF_COOKIE_SECURE = True

// XSS
NEVER:  element.innerHTML = userInput
ALWAYS: element.textContent = userInput
ALWAYS: DOMPurify.sanitize(userInput)

// Prototype Pollution
NEVER:  Object.assign({}, req.body)
ALWAYS: structuredClone(req.body)        // Node 17+

// JWT
NEVER:  jwt.verify(token, "hardcoded-secret")
NEVER:  localStorage.setItem("token", jwt)
ALWAYS: jwt.verify(token, process.env.JWT_SECRET, { algorithms: ["HS256"], expiresIn: "15m" })
ALWAYS: store in httpOnly + Secure + SameSite=Strict cookie

// Headers
import helmet from "helmet";     // min 7.1.0
app.use(helmet());

Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
Content-Security-Policy: default-src 'self'; script-src 'self'; object-src 'none'
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: geolocation=(), microphone=(), camera=()
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Resource-Policy: same-origin

IF HARDCODED SECRETS FOUND:
1. ROTATE IMMEDIATELY — the secret is already compromised
2. PURGE FROM HISTORY:
   git filter-repo --path <file> --invert-paths
   OR BFG: docker run --rm -v "$(pwd):/repo" erikvanzijst/bfg:latest --delete-files <file> /repo
   THEN:  git push --force-with-lease --all     # NEVER --force
3. ADD TO .gitignore: .env, *.pem, *.key, secrets/
4. MIGRATE to env vars or secret manager (Vault, AWS SSM)

❌ npm audit fix --force             → breaks semver
❌ pip install --break-system-packages → corrupts system Python
❌ npm update                        → uncontrolled mass upgrade
❌ docker run --privileged           → full host kernel access
❌ docker run --cap-add SYS_ADMIN    → dangerous kernel caps
❌ docker pull [image]:latest        → unpinned
❌ go install [module]@latest        → unpinned
❌ git push --force                  → use --force-with-lease

PHASE A — CONTAIN (first 5 min)
  1. WAF → full block for non-whitelisted IPs
  2. Invalidate ALL session tokens + API keys
  3. Force MFA re-enrollment for admins
  4. If breach confirmed → take service offline

PHASE B — PRESERVE EVIDENCE (5–15 min)
  5. Snapshot ALL VM disks + container states BEFORE cleanup
  6. Export 30-day logs to immutable storage
  7. Record UTC timestamp of each action

PHASE C — ISOLATE (15–30 min)
  8. DB → promote read-only replica, primary rejects writes
  9. DNS → maintenance page
 10. Rotate ALL TLS certs, secrets, API keys, DB creds
 11. Zero-trust: deny all, allowlist verified IPs

PHASE D — ANALYZE (1–24 h)
 12. Build attack timeline → MITRE ATT&CK IDs
 13. RCA: entry vector, scope, data exposed, permanent fix

PHASE E — RECOVER & HARDEN (1–7 d)
 14. Apply NEVER/ALWAYS fixes for the entry vector
 15. Re-run FULL_SCAN to confirm vuln closed
 16. Activate monitoring queries
 17. Threat-model review of affected components

┌─────────────────────────────────────────────────────────────┐
│ 1. CHECK     Run verify_file / scan.sh / pytest              │
│              → CheckResult { PASS | FAIL | INCONCLUSIVE }    │
│                                                             │
│ 2. READ      If FAIL/INCONCLUSIVE:                          │
│              - result.detail + result.evidence              │
│              - rg "error string" --type py|ts               │
│              - git log --oneline -10 -- <path>              │
│              - read the actual file at the flagged line     │
│                                                             │
│ 3. CLASSIFY  Map to §3.2 error routing matrix               │
│              Assign P0–P3 severity                          │
│                                                             │
│ 4. ISOLATE   Reproduce minimal case                         │
│              git bisect if unknown regression               │
│              Form top 3 hypotheses                          │
│                                                             │
│ 5. FIX       Apply SMALLEST possible diff at root cause     │
│              - AST rewriter (§4.2) over regex               │
│              - One logical change                           │
│              - Add regression test                          │
│              - No "while-I-am-here" refactors               │
│                                                             │
│ 6. RE-VERIFY Run the SAME check that failed                 │
│              → must return PASS                             │
│              If still FAIL/INCONCLUSIVE → loop (max 3)      │
│                                                             │
│ LOOP BOUND: max 3 attempts. Then STOP and report.           │
│             Never weaken the check. Never fake a pass.      │
└─────────────────────────────────────────────────────────────┘

Error: [stack trace]
For each of 5 hypotheses:
  - theory: ...
  - why: ...
  - one verify command: ...
  - minimal patch if confirmed: ...

GATE 1 COMPREHENSION — read full file; rg callers
GATE 2 CORRECTNESS   — root cause; minimal change; lockfile versions match
GATE 3 SAFETY        — no new lint/type errors; no secrets; error paths handled
GATE 4 VERIFICATION  — regression test; ./scan.sh; rollback plan
IF ANY GATE FAILS → DO NOT SHIP

# BROKEN — discards valid session cookies
if exp is not None and isinstance(exp, (int, float)) and exp <= now:
    return None

# CORRECT — only discard if exp is a positive timestamp in the past
if exp is not None and isinstance(exp, (int, float)) and exp > 0 and exp <= now:
    return None

# Morning
just scan                          # or ./scan.sh
rg "\[TYPE\] BUG" knowledge/vip_notes/

# Coding (git-diff aware watcher running)
# Pre-commit
pre-commit run --all-files

# Pre-push
./scan.sh                          # exit 0 required

# Weekly (server)
ssh hetzner-dokploy 'tail -n 100 /var/log/scan.log'

npm:    npm audit → npm update <specific-package>
pip:    python -m venv .venv && source .venv/bin/activate → pip-audit → pip install --upgrade <specific-package>
go:     govulncheck ./... → go get <module>@<specific-version>
cargo:  cargo audit → cargo update -p <specific-crate>

# What's broken on this box?
systemctl --failed
journalctl -p err -b --no-pager | tail -n 50
df -h | grep -vE '^Filesystem|tmpfs|loop'
free -h
ss -tlnp | head -n 20

# Find the noisy process
ps aux --sort=-%mem | head -n 10
ps aux --sort=-%cpu | head -n 10

# Git state
git status --short
git log --oneline -10
git diff --stat

## Analysis
[What is happening, in one paragraph. Cite file:line.]

## Root Cause
[The why. Not the what. Distinguish symptom from cause.]

## Solution
[The surgical fix. Smallest possible diff. Why this approach over alternatives.]

## Changes
[Diff or file:line list. One logical change per commit.]

## Tests
[Regression test added. Existing tests that cover the path.]

## Risk Assessment
[What could break. Rollback plan. P0–P3.]

## Verification
[CheckResult output. final_gate() output. Status: PASS.]
[If any check is INCONCLUSIVE → DO NOT report done.]

Confidence: [score]/100
Breakdown: source(+N) cve(+N) exploit(+N) clarity(+N) fp(+N or -N)
Status: VERIFIED / LIKELY_TRUE / NEEDS_REVIEW / FALSE_POSITIVE
OWASP: [A0X:2021] | CWE: [CWE-NNN]
NEVER (vulnerable): [code snippet ≤5 lines]
ALWAYS (secure):    [code snippet ≤10 lines, annotated]
Language/version:   [e.g. Python 3.11 / Django 4.2]
Source: [Tier 1/2/3 + URL]

┌──────────────────────────────────────────────────────────────┐
│ AGENT CANNOT SAY "done" UNTIL:                               │
│                                                              │
│  1. Every fix has a regression test                          │
│  2. Every fix passed the four quality gates (§7)            │
│  3. final_gate(required_outputs) returns all_pass == True    │
│  4. No check has status INCONCLUSIVE                         │
│  5. No verification tool has status FAILED or SKIPPED        │
│  6. ./scan.sh exit 0                                         │
│  7. VIP note written for non-trivial bugs                    │
│                                                              │
│  IF ANY OF THE ABOVE FAILS → CONTINUE THE DEBUG LOOP (§7)    │
│  AFTER 3 ATTEMPTS → STOP AND REPORT, do not fake a pass      │
└──────────────────────────────────────────────────────────────┘

[ID]           BUG-2026-0001
[TYPE]         BUG | PATTERN | DECISION | SECURITY | PERF
[CONTEXT]      Module file name and line range
[SYMPTOM]      Failing condition or console crash trace
[ROOT CAUSE]   Why it failed (not what)
[PROOF]        Local unit test output or verification log
[FIX]          Unified git diff or surgical code patch
[TEST]         Command run to verify fix locally
[CODE]         Minimal repro snippet
[META]         Confidence (1-5), Status (Fixed), Tags