@paradigma-inc/flywheel 0.1.95 → 0.1.99

package/skills/flywheel-llm-proof-paper/scripts/check_paper.py

@@ -0,0 +1,1065 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "bibtexparser>=1.4,<2",
+#     "tenacity>=9.1.2",
+# ]
+# ///
+"""Small local preflight for LaTeX papers."""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import difflib
+import json
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import xml.etree.ElementTree as ET
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+import bibtexparser
+from bibtexparser.bparser import BibTexParser
+from tenacity import (
+    retry,
+    retry_if_exception,
+    stop_after_attempt,
+    wait_exponential_jitter,
+)
+
+Severity = Literal["hard", "warning"]
+
+USER_AGENT = "paper-llm-proof-skill/0.1 (+https://github.com)"
+CSL_JSON_ACCEPT = "application/vnd.citationstyles.csl+json"
+RETRYABLE_HTTP_STATUSES = {0, 408, 425, 429, 500, 502, 503, 504}
+MIN_INTERVAL_BY_HOST = {"api.crossref.org": 0.2, "export.arxiv.org": 3.0}
+TITLE_SIMILARITY_THRESHOLD = 0.70
+TITLE_TOKEN_SIMILARITY_THRESHOLD = 0.85
+TITLE_STOPWORDS = {
+    "a",
+    "an",
+    "and",
+    "are",
+    "as",
+    "at",
+    "be",
+    "been",
+    "being",
+    "by",
+    "for",
+    "from",
+    "in",
+    "is",
+    "of",
+    "on",
+    "or",
+    "the",
+    "to",
+    "was",
+    "were",
+    "with",
+}
+SKIP_DIRS = {
+    ".git",
+    ".hg",
+    ".svn",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "node_modules",
+    "out",
+}
+BIB_RESOURCE_RE = re.compile(
+    r"\\(?:bibliography|addbibresource)(?:\s*\[[^\]]*\])?\s*\{(?P<names>[^}]+)\}",
+    re.IGNORECASE,
+)
+BIB_ENTRY_RE = re.compile(
+    r"@\s*(?P<type>[A-Za-z][\w-]*)\s*[{(]\s*(?P<key>[^,\s]+)",
+    re.IGNORECASE,
+)
+DOI_RE = re.compile(r"10\.\d{4,9}/[-._;()/:A-Z0-9]+", re.IGNORECASE)
+ARXIV_RE = re.compile(
+    r"(?P<id>(?:[a-z-]+(?:\.[A-Z]{2})?/\d{7})|(?:\d{4}\.\d{4,5}))(?P<version>v\d+)?",
+    re.IGNORECASE,
+)
+
+
+@dataclass(frozen=True)
+class BibEntry:
+    key: str
+    fields: dict[str, str]
+    file: Path
+    line: int
+
+
+@dataclass(frozen=True)
+class Issue:
+    severity: Severity
+    code: str
+    message: str
+    file: str | None = None
+    line: int | None = None
+    key: str | None = None
+    evidence: str | None = None
+
+
+@dataclass(frozen=True)
+class Report:
+    project: str
+    tex_files: tuple[str, ...]
+    bib_files: tuple[str, ...]
+    checked_keys: tuple[str, ...]
+    slop_guard_requested: bool
+    issues: tuple[Issue, ...]
+
+
+@dataclass(frozen=True)
+class ExtractedIdentifier:
+    value: str | None
+    error: str | None = None
+
+
+@dataclass(frozen=True)
+class CatalogTitle:
+    raw: str
+    text: str
+    warning: str | None = None
+
+
+class LookupErrorWithStatus(RuntimeError):
+    def __init__(self, status: int, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+class CatalogClient:
+    def __init__(self, timeout: float) -> None:
+        self.timeout = timeout
+        self.last_request_by_host: dict[str, float] = {}
+
+    def get_json(
+        self, url: str, headers: dict[str, str] | None = None
+    ) -> dict[str, object]:
+        parsed = json.loads(self.get_text(url, headers=headers))
+        if not isinstance(parsed, dict):
+            raise LookupErrorWithStatus(0, f"Expected JSON object from {url}")
+        return parsed
+
+    def get_text(self, url: str, headers: dict[str, str] | None = None) -> str:
+        return self.fetch(url, headers=headers)
+
+    @retry(
+        retry=retry_if_exception(
+            lambda exc: (
+                isinstance(exc, LookupErrorWithStatus)
+                and exc.status in RETRYABLE_HTTP_STATUSES
+            )
+        ),
+        wait=wait_exponential_jitter(initial=1, max=30),
+        stop=stop_after_attempt(4),
+        reraise=True,
+    )
+    def fetch(self, url: str, headers: dict[str, str] | None = None) -> str:
+        self.wait_for_rate_limit(url)
+        request_headers = {"User-Agent": USER_AGENT}
+        if headers:
+            request_headers.update(headers)
+        request = urllib.request.Request(url, headers=request_headers)
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                return response.read().decode("utf-8")
+        except urllib.error.HTTPError as exc:
+            raise LookupErrorWithStatus(exc.code, f"HTTP {exc.code} for {url}") from exc
+        except urllib.error.URLError as exc:
+            raise LookupErrorWithStatus(
+                0, f"Network error for {url}: {exc.reason}"
+            ) from exc
+
+    def wait_for_rate_limit(self, url: str) -> None:
+        host = urllib.parse.urlparse(url).netloc.lower()
+        min_interval = MIN_INTERVAL_BY_HOST.get(host)
+        if min_interval is None:
+            return
+        now = time.monotonic()
+        if (
+            host in self.last_request_by_host
+            and now - self.last_request_by_host[host] < min_interval
+        ):
+            time.sleep(min_interval - (now - self.last_request_by_host[host]))
+        self.last_request_by_host[host] = time.monotonic()
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        report = run_check(Path(args.project).expanduser().resolve(), args)
+    except Exception as exc:
+        print(f"paper-llm-proof could not complete: {exc}", file=sys.stderr)
+        return 3
+
+    hard_count = sum(issue.severity == "hard" for issue in report.issues)
+    warning_count = sum(issue.severity == "warning" for issue in report.issues)
+    exit_code = 2 if hard_count else 0
+    rendered = render_report(report, args.format)
+    if args.out:
+        out_path = Path(args.out).expanduser().resolve()
+        out_path.write_text(rendered, encoding="utf-8")
+        print(
+            f"paper-llm-proof wrote {out_path} (hard={hard_count}, warnings={warning_count}, exit={exit_code})",
+            file=sys.stderr,
+        )
+    else:
+        print(rendered)
+    return exit_code
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Sanity-check a LaTeX/BibTeX paper for real references and prose lint signals.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument("project", help="Path to the LaTeX project root")
+    parser.add_argument(
+        "--bib", action="append", default=[], help="Additional .bib file to include"
+    )
+    parser.add_argument("--format", choices=("markdown", "json"), default="markdown")
+    parser.add_argument("--out", help="Write report to this file")
+    parser.add_argument(
+        "--offline",
+        action="store_true",
+        help="Skip external catalog calls. Bibliography parsing still runs.",
+    )
+    parser.add_argument(
+        "--slop-guard",
+        action="store_true",
+        help="Run Slop Guard and report warning-only prose lint evidence.",
+    )
+    parser.add_argument(
+        "--slop-guard-command",
+        help="Command used to launch Slop Guard. The checker appends '-j -'.",
+    )
+    parser.add_argument("--timeout", type=float, default=60.0)
+    parser.add_argument("--no-cache", action="store_true", help=argparse.SUPPRESS)
+    return parser
+
+
+def run_check(project: Path, args: argparse.Namespace) -> Report:
+    if not project.exists() or not project.is_dir():
+        raise NotADirectoryError(f"Project path is not a directory: {project}")
+
+    tex_files = find_files(project, ".tex")
+    if not tex_files:
+        raise FileNotFoundError(f"No .tex files found under {project}")
+
+    bib_files = resolve_bib_files(
+        project, tex_files, resolve_explicit_bib_files(project, args.bib)
+    )
+    entries = parse_bibliography_files(bib_files)
+    entries_by_key = {entry.key: entry for entry in entries}
+    keys_to_check = tuple(sorted(entries_by_key))
+
+    issues = []
+    if not bib_files:
+        issues.append(
+            Issue(
+                "hard",
+                "no-bib-files",
+                "No BibTeX files were found or referenced by the LaTeX project.",
+                file=str(project),
+            )
+        )
+    client = None if args.offline else CatalogClient(args.timeout)
+    issues.extend(
+        verify_references([entries_by_key[key] for key in keys_to_check], client)
+    )
+    if args.slop_guard:
+        issues.extend(run_slop_guard(tex_files, args.slop_guard_command))
+
+    return Report(
+        project=str(project),
+        tex_files=tuple(str(path) for path in tex_files),
+        bib_files=tuple(str(path) for path in bib_files),
+        checked_keys=keys_to_check,
+        slop_guard_requested=bool(args.slop_guard),
+        issues=tuple(issues),
+    )
+
+
+def find_files(root: Path, suffix: str) -> tuple[Path, ...]:
+    return tuple(
+        sorted(
+            path.resolve()
+            for path in root.rglob(f"*{suffix}")
+            if not any(part in SKIP_DIRS for part in path.relative_to(root).parts[:-1])
+        )
+    )
+
+
+def resolve_explicit_bib_files(
+    project: Path, bib_paths: Sequence[str]
+) -> tuple[Path, ...]:
+    paths = []
+    for bib_path in bib_paths:
+        resolved = Path(bib_path).expanduser()
+        resolved = resolved if resolved.is_absolute() else project / resolved
+        if not resolved.exists():
+            raise FileNotFoundError(f"Explicit BibTeX file does not exist: {resolved}")
+        if not resolved.is_file():
+            raise IsADirectoryError(f"Explicit BibTeX path is not a file: {resolved}")
+        paths.append(resolved.resolve())
+    return tuple(paths)
+
+
+def resolve_bib_files(
+    project: Path, tex_files: Sequence[Path], explicit_bibs: Sequence[Path]
+) -> tuple[Path, ...]:
+    paths = {bib for bib in explicit_bibs if bib.exists()}
+    for tex_file in tex_files:
+        visible_text = strip_latex_comments(read_text(tex_file))
+        for match in BIB_RESOURCE_RE.finditer(visible_text):
+            for raw_name in match.group("names").split(","):
+                if resolved := resolve_bib_reference(
+                    project, tex_file, raw_name.strip()
+                ):
+                    paths.add(resolved)
+    return tuple(sorted(paths or find_files(project, ".bib")))
+
+
+def resolve_bib_reference(project: Path, tex_file: Path, name: str) -> Path | None:
+    if not name:
+        return None
+    candidate = Path(name)
+    if candidate.suffix != ".bib":
+        candidate = candidate.with_suffix(".bib")
+    for path in (
+        candidate if candidate.is_absolute() else tex_file.parent / candidate,
+        project / candidate,
+    ):
+        if path.exists():
+            return path.resolve()
+    return None
+
+
+def parse_bibliography_files(bib_files: Sequence[Path]) -> tuple[BibEntry, ...]:
+    return tuple(
+        entry
+        for bib_file in bib_files
+        for entry in parse_bibtex(read_text(bib_file), bib_file)
+    )
+
+
+def parse_bibtex(text: str, path: Path) -> list[BibEntry]:
+    parser = BibTexParser(common_strings=True)
+    parser.homogenize_fields = False
+    parser.interpolate_strings = False
+    line_numbers = entry_line_numbers(text)
+    entries = []
+    for raw in bibtexparser.loads(text, parser=parser).entries:
+        key = str(raw.get("ID", "")).strip()
+        if key:
+            fields = {
+                field.lower(): normalize_space(str(value))
+                for field, value in raw.items()
+                if field not in {"ID", "ENTRYTYPE"}
+            }
+            lines_for_key = line_numbers.get(key)
+            entries.append(
+                BibEntry(
+                    key, fields, path, lines_for_key.pop(0) if lines_for_key else 1
+                )
+            )
+    return entries
+
+
+def entry_line_numbers(text: str) -> dict[str, list[int]]:
+    lines: dict[str, list[int]] = {}
+    for match in BIB_ENTRY_RE.finditer(text):
+        lines.setdefault(match.group("key").strip(), []).append(
+            line_for_offset(text, match.start())
+        )
+    return lines
+
+
+def verify_references(
+    entries: Sequence[BibEntry], client: CatalogClient | None
+) -> list[Issue]:
+    return [issue for entry in entries for issue in verify_reference(entry, client)]
+
+
+def verify_reference(entry: BibEntry, client: CatalogClient | None) -> list[Issue]:
+    title = catalog_title(entry.fields.get("title", ""))
+    doi = extract_doi(entry)
+    arxiv_id = extract_arxiv_id(entry)
+    for identifier, code, label in (
+        (doi, "malformed-doi", "DOI"),
+        (arxiv_id, "malformed-arxiv-id", "arXiv identifier"),
+    ):
+        if identifier.error:
+            return [
+                reference_issue(
+                    entry,
+                    "hard",
+                    code,
+                    f"BibTeX key '{entry.key}' has a malformed {label} field.",
+                    identifier.error,
+                )
+            ]
+    if not doi.value and not arxiv_id.value:
+        return [
+            reference_issue(
+                entry,
+                "warning",
+                "reference-needs-agent-check",
+                f"BibTeX key '{entry.key}' has no DOI or arXiv ID; verify the title manually.",
+                title.text or title.raw or "No title",
+            )
+        ]
+    if client is None:
+        return [
+            reference_issue(
+                entry,
+                "warning",
+                "catalog-check-skipped",
+                f"Skipped catalog reality check for '{entry.key}' because --offline was used.",
+            )
+        ]
+    if doi.value and not is_arxiv_doi(doi.value):
+        return verify_identifier(
+            entry,
+            "doi",
+            doi.value,
+            title,
+            lambda: lookup_doi(doi.value, client),
+            "doi-not-found",
+            "doi-title-mismatch",
+        )
+    return verify_identifier(
+        entry,
+        "arxiv",
+        arxiv_id.value or "",
+        title,
+        lambda: lookup_arxiv(arxiv_id.value or "", client),
+        "arxiv-not-found",
+        "arxiv-title-mismatch",
+    )
+
+
+def verify_identifier(
+    entry: BibEntry,
+    method: str,
+    identifier: str,
+    title: CatalogTitle,
+    lookup: Callable[[], tuple[str, str] | None],
+    not_found_code: str,
+    mismatch_code: str,
+) -> list[Issue]:
+    try:
+        record = lookup()
+    except LookupErrorWithStatus as exc:
+        return [
+            reference_issue(
+                entry,
+                "hard",
+                "catalog-request-failed",
+                f"Could not complete {method} lookup for '{entry.key}'.",
+                str(exc),
+            )
+        ]
+    if record is None:
+        return [
+            reference_issue(
+                entry,
+                "hard",
+                not_found_code,
+                f"{method} for BibTeX key '{entry.key}' did not resolve.",
+                identifier,
+            )
+        ]
+    source, remote_title = record
+    if not remote_title:
+        return [
+            reference_issue(
+                entry,
+                "warning",
+                "title-needs-agent-check",
+                f"{method} for BibTeX key '{entry.key}' resolves, "
+                "but no catalog title was available for automatic comparison.",
+                no_catalog_title_evidence(title, source),
+            )
+        ]
+    if title.warning:
+        return [
+            reference_issue(
+                entry,
+                "warning",
+                "title-needs-agent-check",
+                f"{method} for BibTeX key '{entry.key}' resolves, but the BibTeX title needs agent review.",
+                title_warning_evidence(title, source, remote_title),
+            )
+        ]
+    score = title_similarity(title.text, remote_title) if remote_title else None
+    token_score = title_token_similarity(title.text, remote_title)
+    if score is not None and (
+        score < TITLE_SIMILARITY_THRESHOLD
+        or token_score < TITLE_TOKEN_SIMILARITY_THRESHOLD
+    ):
+        if title_prefix_variant(title.text, remote_title):
+            return [
+                reference_issue(
+                    entry,
+                    "warning",
+                    "title-needs-agent-check",
+                    f"{method} for BibTeX key '{entry.key}' resolves, "
+                    "but the title needs agent review.",
+                    title_variant_evidence(
+                        title.text, source, remote_title, score, token_score
+                    ),
+                )
+            ]
+        evidence = (
+            f"BibTeX: {title.text} | {source}: {remote_title} | "
+            f"score={score:.2f} | token_score={token_score:.2f}"
+        )
+        return [
+            reference_issue(
+                entry,
+                "hard",
+                mismatch_code,
+                f"{method} for BibTeX key '{entry.key}' resolves, but the title does not match.",
+                evidence,
+            )
+        ]
+    return []
+
+
+def title_warning_evidence(title: CatalogTitle, source: str, remote_title: str) -> str:
+    parts = [title.warning or "Title could not be compared automatically."]
+    if title.raw:
+        parts.append(f"BibTeX: {title.raw}")
+    parts.append(f"{source}: {remote_title}")
+    return " | ".join(parts)
+
+
+def no_catalog_title_evidence(title: CatalogTitle, source: str) -> str:
+    title_text = title.raw or title.text or "No BibTeX title"
+    return (
+        f"{source} resolved without title metadata. "
+        f"BibTeX title needs agent review: {title_text}"
+    )
+
+
+def title_variant_evidence(
+    local_title: str,
+    source: str,
+    remote_title: str,
+    score: float,
+    token_score: float,
+) -> str:
+    return (
+        "Title differs by prefix/subtitle-like extra text. "
+        f"BibTeX: {local_title} | {source}: {remote_title} | "
+        f"score={score:.2f} | token_score={token_score:.2f}"
+    )
+
+
+def reference_issue(
+    entry: BibEntry,
+    severity: Severity,
+    code: str,
+    message: str,
+    evidence: str | None = None,
+) -> Issue:
+    return Issue(
+        severity,
+        code,
+        message,
+        file=str(entry.file),
+        line=entry.line,
+        key=entry.key,
+        evidence=evidence,
+    )
+
+
+def lookup_doi(doi: str, client: CatalogClient) -> tuple[str, str] | None:
+    try:
+        data = client.get_json(
+            f"https://api.crossref.org/works/{urllib.parse.quote(doi, safe='')}"
+        )
+    except LookupErrorWithStatus as exc:
+        if exc.status == 404:
+            return lookup_doi_resolver(doi, client)
+        raise
+    message = data.get("message")
+    title = first_string(message.get("title", []) if isinstance(message, dict) else [])
+    return ("Crossref", title or "")
+
+
+def lookup_doi_resolver(doi: str, client: CatalogClient) -> tuple[str, str] | None:
+    try:
+        text = client.get_text(
+            f"https://doi.org/{urllib.parse.quote(doi, safe='/')}",
+            headers={"Accept": CSL_JSON_ACCEPT},
+        )
+    except LookupErrorWithStatus as exc:
+        if exc.status in {404, 410}:
+            return None
+        raise
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        return ("DOI resolver", "")
+    if not isinstance(data, dict):
+        return ("DOI resolver", "")
+    return ("DOI resolver", csl_title(data.get("title")) or "")
+
+
+def lookup_arxiv(arxiv_id: str, client: CatalogClient) -> tuple[str, str] | None:
+    url = "https://export.arxiv.org/api/query?" + urllib.parse.urlencode(
+        {"id_list": arxiv_id}
+    )
+    root = ET.fromstring(client.get_text(url))
+    entry = root.find("{http://www.w3.org/2005/Atom}entry")
+    title = (
+        entry.findtext("{http://www.w3.org/2005/Atom}title")
+        if entry is not None
+        else None
+    )
+    return ("arXiv", clean_bib_value(title)) if title else None
+
+
+def extract_doi(entry: BibEntry) -> ExtractedIdentifier:
+    doi_field = clean_bib_value(entry.fields.get("doi", ""))
+    candidates = [doi_field] if doi_field else []
+    candidates.extend(
+        value
+        for field in ("url", "note", "eprint")
+        if (value := entry.fields.get(field, "")) and looks_like_doi_source(value)
+    )
+    for raw in candidates:
+        if normalized := normalize_doi(raw):
+            return ExtractedIdentifier(normalized)
+    return (
+        ExtractedIdentifier(None, candidates[0])
+        if candidates
+        else ExtractedIdentifier(None)
+    )
+
+
+def looks_like_doi_source(raw: str) -> bool:
+    cleaned = clean_bib_value(raw)
+    return bool(
+        DOI_RE.search(cleaned)
+        or re.search(r"^(?:https?://)?(?:dx\.)?doi\.org/", cleaned, re.IGNORECASE)
+        or re.search(r"\bdoi\s*:", cleaned, re.IGNORECASE)
+    )
+
+
+def normalize_doi(raw: str) -> str | None:
+    cleaned = clean_bib_value(raw).strip()
+    cleaned = re.sub(
+        r"^(?:https?://)?(?:dx\.)?doi\.org/", "", cleaned, flags=re.IGNORECASE
+    )
+    cleaned = re.sub(r"^doi\s*:\s*", "", cleaned, flags=re.IGNORECASE)
+    match = DOI_RE.search(cleaned)
+    return match.group(0).rstrip(".,;:)]}").lower() if match else None
+
+
+def is_arxiv_doi(doi: str) -> bool:
+    return doi.lower().startswith("10.48550/arxiv.")
+
+
+def extract_arxiv_id(entry: BibEntry) -> ExtractedIdentifier:
+    eprint = clean_bib_value(entry.fields.get("eprint", ""))
+    archive = clean_bib_value(entry.fields.get("archiveprefix", "")).lower()
+    eprint_type = clean_bib_value(entry.fields.get("eprinttype", "")).lower()
+    candidates = (
+        [eprint] if eprint and (archive == "arxiv" or eprint_type == "arxiv") else []
+    )
+    candidates.extend(
+        value
+        for field in ("eprint", "url", "note", "doi")
+        if (value := entry.fields.get(field, "")) and looks_like_arxiv_source(value)
+    )
+    for raw in candidates:
+        if arxiv_id := normalize_arxiv_id(raw):
+            return ExtractedIdentifier(arxiv_id)
+    return (
+        ExtractedIdentifier(None, candidates[0])
+        if candidates
+        else ExtractedIdentifier(None)
+    )
+
+
+def looks_like_arxiv_source(raw: str) -> bool:
+    cleaned = clean_bib_value(raw)
+    lower = cleaned.lower()
+    return bool(
+        "arxiv.org/" in lower
+        or "10.48550/arxiv." in lower
+        or re.search(r"\barxiv\s*:", cleaned, re.IGNORECASE)
+    )
+
+
+def normalize_arxiv_id(raw: str) -> str | None:
+    cleaned = re.sub(r"^arxiv\s*:\s*", "", clean_bib_value(raw), flags=re.IGNORECASE)
+    cleaned = re.sub(
+        r"^https?://arxiv\.org/(?:abs|pdf)/", "", cleaned, flags=re.IGNORECASE
+    ).removesuffix(".pdf")
+    match = ARXIV_RE.search(cleaned)
+    if match:
+        return f"{match.group('id')}{match.group('version') or ''}"
+    doi_match = re.search(r"10\.48550/arxiv\.([0-9.]+)", cleaned, flags=re.IGNORECASE)
+    return doi_match.group(1) if doi_match else None
+
+
+def run_slop_guard(
+    tex_files: Sequence[Path], command_override: str | None
+) -> list[Issue]:
+    text = slop_guard_text(tex_files)
+    if not text:
+        return []
+    try:
+        completed = subprocess.run(
+            slop_guard_command(command_override),
+            input=text,
+            capture_output=True,
+            check=False,
+            text=True,
+            timeout=120.0,
+        )
+        if completed.returncode not in (0, 1):
+            raise RuntimeError(
+                normalize_space(completed.stderr or completed.stdout)[:500]
+            )
+        data = json.loads(completed.stdout)
+        if not isinstance(data, dict):
+            raise TypeError("Slop Guard JSON payload was not an object.")
+    except (
+        FileNotFoundError,
+        OSError,
+        RuntimeError,
+        TypeError,
+        subprocess.TimeoutExpired,
+        json.JSONDecodeError,
+    ) as exc:
+        return [
+            Issue(
+                "warning",
+                "slop-guard-error",
+                "Slop Guard could not complete.",
+                evidence=str(exc),
+            )
+        ]
+
+    score = as_float(data.get("score"))
+    return (
+        [
+            Issue(
+                "warning",
+                "slop-guard-signal",
+                "Slop Guard reported prose-lint findings. Treat as triage, not proof.",
+                evidence=slop_guard_evidence(score, data),
+            )
+        ]
+        if score is not None and score < 80.0
+        else []
+    )
+
+
+def slop_guard_text(tex_files: Sequence[Path]) -> str:
+    return normalize_space(
+        "\n\n".join(
+            latex_to_plain_text(
+                strip_latex_boilerplate(strip_latex_comments(read_text(path)))
+            )
+            for path in tex_files
+        )
+    )[:100_000]
+
+
+def slop_guard_command(command_override: str | None) -> list[str]:
+    if command_override:
+        command = shlex.split(command_override)
+        if not command:
+            raise FileNotFoundError("--slop-guard-command was empty")
+        return [*command, "-j", "-"]
+    if installed := shutil.which("sg"):
+        return [installed, "-j", "-"]
+    if uvx := shutil.which("uvx"):
+        return [uvx, "--from", "slop-guard", "sg", "-j", "-"]
+    raise FileNotFoundError("Install `sg` or `uvx` as an available shell command.")
+
+
+def slop_guard_evidence(score: float, data: dict[str, object]) -> str:
+    band = data.get("band") if isinstance(data.get("band"), str) else "unknown"
+    parts = [f"score={score:.0f}", f"band={band}"]
+    violations = data.get("violations")
+    if isinstance(violations, list):
+        hits = []
+        for item in violations[:5]:
+            if not isinstance(item, dict):
+                continue
+            rule = item.get("rule")
+            match = item.get("match")
+            if isinstance(rule, str) and isinstance(match, str):
+                hits.append(f"{rule}: {normalize_space(match)[:80]}")
+        if hits:
+            parts.append("hits=" + "; ".join(hits))
+    return " | ".join(parts)
+
+
+def render_report(report: Report, report_format: str) -> str:
+    if report_format == "json":
+        data = dataclasses.asdict(report)
+        data["counts"] = {
+            "hard": sum(issue.severity == "hard" for issue in report.issues),
+            "warning": sum(issue.severity == "warning" for issue in report.issues),
+            "checked": len(report.checked_keys),
+        }
+        return json.dumps(data, indent=2, sort_keys=True)
+    return render_markdown(report)
+
+
+def render_markdown(report: Report) -> str:
+    hard = [issue for issue in report.issues if issue.severity == "hard"]
+    warnings = [issue for issue in report.issues if issue.severity == "warning"]
+    lines = [
+        "# Paper LLM-Proof Report",
+        "",
+        f"- Project: `{report.project}`",
+        f"- TeX files: {len(report.tex_files)}",
+        f"- Bib files: {len(report.bib_files)}",
+        f"- Checked references: {len(report.checked_keys)}",
+        f"- Hard failures: {len(hard)}",
+        f"- Warnings: {len(warnings)}",
+        f"- Slop Guard: {'requested' if report.slop_guard_requested else 'not requested'}",
+        "",
+    ]
+    lines.extend(render_issue_section("Hard Failures", hard))
+    lines.extend(render_issue_section("Warnings", warnings))
+    return "\n".join(lines)
+
+
+def render_issue_section(title: str, issues: Sequence[Issue]) -> list[str]:
+    lines = [f"## {title}", ""]
+    if not issues:
+        return [*lines, "None.", ""]
+    for issue in sorted(
+        issues, key=lambda item: (item.file or "", item.line or 0, item.code)
+    ):
+        location = f" `{issue.file}`" if issue.file else ""
+        location += f":{issue.line}" if issue.file and issue.line else ""
+        key = f" `{issue.key}`" if issue.key else ""
+        lines.append(f"- `{issue.code}`{key}{location}: {issue.message}")
+        if issue.evidence:
+            lines.append(f"  Evidence: {issue.evidence}")
+    return [*lines, ""]
+
+
+def read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return path.read_text(encoding="latin-1")
+
+
+def strip_latex_comments(text: str) -> str:
+    return "".join(
+        strip_latex_comment_line(line) for line in text.splitlines(keepends=True)
+    )
+
+
+def strip_latex_comment_line(line: str) -> str:
+    for index, char in enumerate(line):
+        if char == "%" and (index == 0 or line[index - 1] != "\\"):
+            return line[:index] + ("\n" if line.endswith("\n") else "")
+    return line
+
+
+def strip_latex_boilerplate(text: str) -> str:
+    text = re.sub(r"\\documentclass(?:\s*\[[^\]]*\])?\s*\{[^{}]*\}", " ", text)
+    text = re.sub(r"\\(?:begin|end)\s*\{document\}", " ", text)
+    return re.sub(
+        r"\\(?:bibliography|bibliographystyle|addbibresource)(?:\s*\[[^\]]*\])?\s*\{[^{}]*\}",
+        " ",
+        text,
+    )
+
+
+def latex_to_plain_text(text: str) -> str:
+    text = re.sub(
+        r"\\[A-Za-z]*[Cc]ite[A-Za-z]*\*?(?:\s*\[[^\]]*\]){0,3}\s*\{[^{}]*\}",
+        " [CITATION] ",
+        text,
+    )
+    text = re.sub(r"\\(?:ref|eqref|label)\s*\{[^{}]*\}", " ", text)
+    text = re.sub(r"\\(?:url|href)\s*\{([^{}]*)\}", r" \1 ", text)
+    text = re.sub(r"\\[a-zA-Z]+\*?(?:\s*\[[^\]]*\])?", " ", text)
+    return normalize_space(
+        re.sub(
+            r"[{}$^_~]",
+            " ",
+            text.replace("\\&", "&").replace("\\%", "%").replace("\\_", "_"),
+        )
+    )
+
+
+# Boundary: title comparison is deliberately not a LaTeX interpreter. It handles
+# obvious plain text and simple formatting macros; anything still command-like
+# becomes an agent-review warning after the DOI/arXiv identifier resolves.
+def catalog_title(text: str | None) -> CatalogTitle:
+    raw = normalize_space(text or "")
+    if not raw:
+        return CatalogTitle(raw, "", "BibTeX title is empty.")
+    cleaned = unwrap_simple_latex_text(raw)
+    commands = remaining_latex_commands(cleaned)
+    if commands:
+        return CatalogTitle(
+            raw,
+            "",
+            "BibTeX title contains LaTeX command(s) the checker does not interpret: "
+            + ", ".join(commands[:5]),
+        )
+    cleaned = strip_bibtex_markup(cleaned)
+    if not cleaned:
+        return CatalogTitle(raw, "", "BibTeX title did not leave comparable text.")
+    return CatalogTitle(raw, cleaned)
+
+
+def clean_bib_value(text: str | None) -> str:
+    if text is None:
+        return ""
+    text = unwrap_simple_latex_text(text)
+    text = re.sub(r"\\[a-zA-Z]+\*?", " ", text)
+    return strip_bibtex_markup(text)
+
+
+def unwrap_simple_latex_text(text: str) -> str:
+    text = re.sub(r"\\['`^\"~=.]\s*\{?([A-Za-z])\}?", r"\1", text)
+    text = re.sub(r"\\[uvHcdbtr](?=\s|\{)\s*\{?([A-Za-z])\}?", r"\1", text)
+    text = re.sub(
+        r"\\(?:href|hyperref)\*?(?:\s*\[[^\]]*\])?\s*\{[^{}]*\}\s*\{([^{}]*)\}",
+        r"\1",
+        text,
+    )
+    while True:
+        updated = re.sub(
+            r"\\[a-zA-Z]+\*?(?:\s*\[[^\]]*\])?\s*\{([^{}]*)\}",
+            r"\1",
+            text,
+        )
+        if updated == text:
+            break
+        text = updated
+    return text
+
+
+def remaining_latex_commands(text: str) -> tuple[str, ...]:
+    return tuple(
+        sorted({match.group(0) for match in re.finditer(r"\\[a-zA-Z]+\*?", text)})
+    )
+
+
+def strip_bibtex_markup(text: str) -> str:
+    return normalize_space(
+        text.replace("{", "")
+        .replace("}", "")
+        .replace("\\&", "&")
+        .replace("\\_", "_")
+        .replace("\\%", "%")
+    )
+
+
+def normalize_space(text: str) -> str:
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def normalize_for_match(text: str) -> str:
+    return normalize_space(re.sub(r"[^a-z0-9]+", " ", text.lower()))
+
+
+def title_similarity(left: str, right: str) -> float:
+    left_norm = normalize_for_match(left)
+    right_norm = normalize_for_match(right)
+    if not left_norm or not right_norm:
+        return 0.0
+    return difflib.SequenceMatcher(None, left_norm, right_norm).ratio()
+
+
+def title_token_similarity(left: str, right: str) -> float:
+    left_tokens = set(significant_title_tokens(left))
+    right_tokens = set(significant_title_tokens(right))
+    if not left_tokens or not right_tokens:
+        return 0.0
+    return len(left_tokens & right_tokens) / len(left_tokens | right_tokens)
+
+
+# Boundary: prefix/subtitle variants are not clear contradictions. They still
+# need an agent check, but they should not block like different titles do.
+def title_prefix_variant(left: str, right: str) -> bool:
+    left_tokens = tuple(normalize_for_match(left).split())
+    right_tokens = tuple(normalize_for_match(right).split())
+    if not left_tokens or not right_tokens or left_tokens == right_tokens:
+        return False
+    shorter, longer = (
+        (left_tokens, right_tokens)
+        if len(left_tokens) < len(right_tokens)
+        else (right_tokens, left_tokens)
+    )
+    return longer[: len(shorter)] == shorter
+
+
+def significant_title_tokens(text: str) -> tuple[str, ...]:
+    tokens = tuple(
+        token
+        for token in normalize_for_match(text).split()
+        if token not in TITLE_STOPWORDS
+    )
+    return tokens or tuple(normalize_for_match(text).split())
+
+
+def line_for_offset(text: str, offset: int) -> int:
+    return text.count("\n", 0, offset) + 1
+
+
+def first_string(values: object) -> str | None:
+    if not isinstance(values, list):
+        return None
+    for value in values:
+        if isinstance(value, str) and value.strip():
+            return clean_bib_value(value)
+    return None
+
+
+def csl_title(value: object) -> str | None:
+    if isinstance(value, str) and value.strip():
+        return clean_bib_value(value)
+    return first_string(value)
+
+
+def as_float(value: object) -> float | None:
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, str):
+        try:
+            return float(value)
+        except ValueError:
+            return None
+    return None
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())