reviewgate 0.1.0__py3-none-any.whl

agentboard/__init__.py

@@ -0,0 +1,62 @@
+"""agentboard — a code review gate that verifies by executing tests.
+
+A model proposes edge-case tests from your intent and your change; a
+deterministic harness runs each one against the real code in a clean
+checkout; a behavior is a gap only if its test runs and fails. No model is in
+the pass/fail decision. The entry point is the `agentboard` CLI
+(`agentboard.cli:main`).
+
+The legacy whiteboard/loop API (built on LangGraph) is still importable from
+this package, but only when the optional `whiteboard` extra is installed
+(`pip install "agentboard[whiteboard]"`). It is not needed for the review
+gate, so a lean install does not pull LangGraph, and the imports below degrade
+to absent rather than crashing `import agentboard`.
+"""
+
+__version__ = "0.1.0"
+
+# Legacy whiteboard exports — available only with the [whiteboard] extra.
+# Wrapped so a lean install (review gate only) imports cleanly without
+# LangGraph. If you need these symbols, install the extra.
+try:  # pragma: no cover - exercised by the [whiteboard] install path
+    from .loop import build_loop, initial_board
+    from .personas import DEFAULT_PERSONAS, StubAgent
+    from .state import (
+        Board,
+        CodeChange,
+        Conflict,
+        Node,
+        Proposal,
+        Rejection,
+        Snapshot,
+    )
+    from .verifiers.schema_verifier import SchemaVerifier
+    from .whiteboards.html_adapter import HtmlWhiteboardAdapter
+    from .whiteboards.flow_adapter import FlowWhiteboardAdapter
+    from .ingestion.text_adapter import TextIngestionAdapter
+    from .ingestion.repo_adapter import RepoIngestionAdapter
+    from .verifiers.pytest_verifier import PytestVerifier
+    from .agents.openai_agent import OpenAIAgent
+
+    __all__ = [
+        "build_loop",
+        "initial_board",
+        "DEFAULT_PERSONAS",
+        "StubAgent",
+        "SchemaVerifier",
+        "HtmlWhiteboardAdapter",
+        "FlowWhiteboardAdapter",
+        "TextIngestionAdapter",
+        "RepoIngestionAdapter",
+        "PytestVerifier",
+        "OpenAIAgent",
+        "Board",
+        "Node",
+        "Proposal",
+        "CodeChange",
+        "Rejection",
+        "Conflict",
+        "Snapshot",
+    ]
+except ImportError:  # langgraph (the [whiteboard] extra) not installed
+    __all__ = []

agentboard/agents/critic_agent.py

@@ -0,0 +1,174 @@
+"""CriticAgent — the second seat, a DIFFERENT model (Claude by default).
+
+The first agent (ReviewerAgent, GPT) derives the behaviors the intent promises
+and tests them — it produces a competent *feature checklist*. Empirically it
+does NOT reach for adversarial schema shapes on its own.
+
+This agent's job is different, and it MUST be a different model family, because a
+same-model second seat is a clone with the same blind spots (proven). It receives
+the first agent's coverage as a finished artifact and asks only: what does this
+MISS? What inputs would break these features? It proposes tests for the gaps.
+
+Why this is collaboration and not a vote:
+  - The critic does not judge whether the first agent's tests are "correct" — the
+    gate already runs those.
+  - It ADDS candidate gap-tests the first agent didn't think of.
+  - Every candidate it proposes still goes through the deterministic FindingVerifier.
+    Two models agreeing "composite FKs break this" proves nothing until the test
+    fails on the branch. Collaboration raises candidate quality; the gate decides
+    truth.
+
+Structure mirrors reviewer_agent: model call split from pure parsing.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+from ..review import ReviewFinding
+
+_SYSTEM = """You are a staff engineer doing a second-pass review. Another engineer already reviewed a code change against this intent and wrote tests for the behaviors it promises:
+
+INTENT:
+{intent}
+
+Their tests (the coverage so far) are given to you. Your job is NOT to re-check what they covered. Your job is to find what their coverage MISSES — the realistic inputs and data shapes that would break this tool but that their tests never exercise.
+
+Think like someone trying to find the bug they didn't think of. Consider unusual but legitimate shapes of the data this tool processes. For each gap you find, write ONE test that asserts the CORRECT behavior for that shape.
+
+Constraints:
+- Only propose gaps that are within the intent's scope — real inputs the tool is supposed to handle, not invented features.
+- Do NOT try to force a failure. Assert what SHOULD happen for that input and let it run.
+- MANDATORY SETUP: reproduce the exact project setup the existing tests use (create org, create project, set active status, load schema via the project's db exec) before calling the tool. Never call the tool with a project_id you did not create this way. Copy the setup verbatim from the existing tests; change only the schema you load and the assertions.
+- Reuse the existing test harness exactly (same imports, helpers, style). The test must compile.
+- EXACTNESS FOR PRODUCED COLLECTIONS (mandatory). Whenever the tool returns a collection and the intent implies it is the complete, authoritative answer, assert it EXACTLY: assert the count AND deep-equal the full expected set — nothing missing and nothing extra. A consumer relies on this as truth; an item that should not be there is false information it will act on, a correctness failure. Presence-only matchers (arrayContaining, toContain, toContainEqual, objectContaining, stringContaining) are FORBIDDEN when the collection is meant to be complete — they pass even when the tool over-produces. Assert length (toHaveLength(N)) plus a full deep-equal; sort both sides by a stable key first if output order is not guaranteed.
+
+Output ONLY JSON:
+{{"gaps": [
+  {{"behavior": "<the uncovered case, one sentence>",
+    "axis": "correctness" | "consistency",
+    "test_path": "<repo-root-relative path to the test file>",
+    "test_code": "<a complete test in the existing harness style>"
+  }}
+]}}"""
+
+
+def _loads_gaps_lenient(text: str) -> dict:
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+    objs, stack, instr, esc = [], [], False, False
+    for i, ch in enumerate(text):
+        if instr:
+            if esc:
+                esc = False
+            elif ch == "\\":
+                esc = True
+            elif ch == '"':
+                instr = False
+            continue
+        if ch == '"':
+            instr = True
+        elif ch == "{":
+            stack.append(i)
+        elif ch == "}" and stack:
+            start = stack.pop()
+            try:
+                o = json.loads(text[start : i + 1])
+                if isinstance(o, dict) and "behavior" in o and "test_code" in o:
+                    objs.append(o)
+            except json.JSONDecodeError:
+                pass
+    return {"gaps": objs}
+
+
+def parse_gaps(data: dict) -> list[ReviewFinding]:
+    findings: list[ReviewFinding] = []
+    for g in data.get("gaps", []) or []:
+        behavior = str(g.get("behavior", "")).strip()
+        tc = g.get("test_code")
+        if not behavior or not (isinstance(tc, str) and tc.strip()):
+            continue
+        axis = g.get("axis", "correctness")
+        if axis not in ("correctness", "consistency"):
+            axis = "correctness"
+        findings.append(
+            ReviewFinding(
+                behavior=behavior,
+                axis=axis,
+                covered_by_existing=False,
+                coverage_note="proposed by critic (2nd-pass, different model)",
+                test_path=g.get("test_path"),
+                test_code=tc,
+            )
+        )
+    return findings
+
+
+def _coverage_digest(prior: list[ReviewFinding]) -> str:
+    lines = []
+    for f in prior:
+        lines.append(f"- ({f.axis}) {f.behavior}")
+    return "\n".join(lines) if lines else "(no prior coverage)"
+
+
+class CriticAgent:
+    def __init__(
+        self, model: str = "claude-opus-4-8", client=None, max_tokens: int = 3000
+    ):
+        self.model = model
+        self._client = client
+        self.max_tokens = max_tokens
+        self._is_openai = model.startswith("gpt") or model.startswith("o")
+
+    def _client_lazy(self):
+        if self._client is None:
+            if self._is_openai:
+                from openai import OpenAI
+
+                self._client = OpenAI()
+            else:
+                from anthropic import Anthropic
+
+                self._client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
+        return self._client
+
+    def critique(
+        self, intent: str, source: str, existing_tests: str, prior: list[ReviewFinding]
+    ) -> list[ReviewFinding]:
+        user = (
+            f"SOURCE FILE:\n```\n{source[:9000]}\n```\n\n"
+            f"EXISTING TESTS (harness to reuse):\n```\n{existing_tests[:9000]}\n```\n\n"
+            f"COVERAGE SO FAR (the first reviewer's behaviors — find what these MISS):\n"
+            f"{_coverage_digest(prior)}\n\nRespond ONLY with the JSON specified."
+        )
+        try:
+            client = self._client_lazy()
+            if self._is_openai:
+                resp = client.chat.completions.create(
+                    model=self.model,
+                    response_format={"type": "json_object"},
+                    messages=[
+                        {"role": "system", "content": _SYSTEM.format(intent=intent)},
+                        {"role": "user", "content": user},
+                    ],
+                )
+                data = json.loads(resp.choices[0].message.content or "{}")
+            else:
+                resp = client.messages.create(
+                    model=self.model,
+                    max_tokens=8000,
+                    system=_SYSTEM.format(intent=intent)
+                    + "\n\nRespond with ONLY the JSON object, no prose before or after.",
+                    messages=[{"role": "user", "content": user}],
+                )
+                text = "".join(
+                    b.text for b in resp.content if getattr(b, "type", None) == "text"
+                )
+                data = _loads_gaps_lenient(text)
+        except Exception as ex:  # never crash the loop
+            print(f"  [warn] critic: {ex}")
+            return []
+        return parse_gaps(data)

agentboard/agents/fix_agent.py

@@ -0,0 +1,98 @@
+"""FixAgent — proposes a code fix for a confirmed_gap. It NEVER judges.
+
+The judge is TransitionVerifier.verify_transition: the finding's own red test must
+go green under the fix, with zero regressions. This agent only turns
+(behavior, observed failure, source) into a candidate CodeChange.
+
+Deterministic pre-checks before anything expensive runs:
+  - `find` must be non-empty and occur EXACTLY ONCE in the target file
+    (ambiguous or missing anchors are rejected here, not by a test run).
+  - `replace` must differ from `find`.
+These reject malformed proposals for free; they do not judge correctness.
+"""
+from __future__ import annotations
+
+import json
+import os
+
+from ..state import CodeChange
+
+_SYSTEM = """You are a senior engineer proposing a MINIMAL fix for a verified bug.
+
+You are given:
+- the intended behavior that a failing test proved is violated,
+- the observed assertion failure,
+- the failing test's code,
+- the full content of one source file, with its repo-relative path.
+
+Propose ONE minimal edit to THAT file that makes the intended behavior hold.
+
+Rules:
+- Smallest change that fixes the cause. No refactors, no style changes, no
+  drive-by improvements.
+- `find` must be an EXACT, UNIQUE substring of the file as given (copy it
+  verbatim, whitespace included). `replace` is its replacement.
+- Do not touch the test.
+
+Respond ONLY with JSON:
+{"find": "<exact snippet>", "replace": "<replacement>", "note": "<one line: what/why>"}
+If you cannot propose a defensible fix in this file, respond {"find": null}."""
+
+
+def check_change_applies(source: str, find: str | None, replace: str | None):
+    """Deterministic applicability check. Returns (ok, reason)."""
+    if not find:
+        return False, "agent proposed no fix"
+    if source.count(find) == 0:
+        return False, "proposed `find` snippet not present in file"
+    if source.count(find) > 1:
+        return False, f"proposed `find` snippet ambiguous ({source.count(find)} occurrences)"
+    if replace is None or replace == find:
+        return False, "replace missing or identical to find"
+    return True, ""
+
+
+class FixAgent:
+    def __init__(self, repo_root: str, model: str = "gpt-5.5"):
+        self.repo_root = repo_root
+        self.model = model
+        self._client = None
+
+    def _client_lazy(self):
+        if self._client is None:
+            from openai import OpenAI
+            self._client = OpenAI()
+        return self._client
+
+    def propose(self, behavior: str, observed: str, test_code: str,
+                target_path: str) -> tuple[CodeChange | None, str]:
+        """Returns (CodeChange, note) or (None, reason)."""
+        src_file = os.path.join(self.repo_root, target_path)
+        try:
+            source = open(src_file, encoding="utf-8").read()
+        except OSError as e:
+            return None, f"cannot read target file: {e}"
+
+        user = (
+            f"INTENDED BEHAVIOR (a test proved this is violated):\n{behavior}\n\n"
+            f"OBSERVED FAILURE:\n{observed}\n\n"
+            f"FAILING TEST:\n{test_code}\n\n"
+            f"FILE: {target_path}\n----- FILE CONTENT -----\n{source}"
+        )
+        resp = self._client_lazy().chat.completions.create(
+            model=self.model,
+            messages=[{"role": "system", "content": _SYSTEM},
+                      {"role": "user", "content": user}],
+            response_format={"type": "json_object"},
+        )
+        try:
+            data = json.loads(resp.choices[0].message.content or "{}")
+        except (json.JSONDecodeError, IndexError):
+            return None, "agent returned unparseable output"
+
+        find, replace = data.get("find"), data.get("replace")
+        ok, why = check_change_applies(source, find, replace)
+        if not ok:
+            return None, why
+        note = (data.get("note") or "").strip()[:200]
+        return CodeChange(path=target_path, find=find, replace=replace), note

agentboard/agents/fix_with_test_agent.py

@@ -0,0 +1,135 @@
+"""FixWithTestAgent — proposes a change AND the test that proves it.
+
+The plain OpenAIAgent emits a fix (find/replace) but no test, so it can't feed
+the TransitionVerifier, which needs a NEW test to check red-on-baseline /
+green-after. This agent asks the model for both, in one shot, and packs them
+into a single Proposal (``change`` + ``test_change``).
+
+Same discipline as openai_agent: the network call and the parsing are split, so
+``parse_fix_with_test`` is a pure, offline-testable function.
+
+It does NOT try to guarantee the test is good — that's not its job and it
+couldn't if it tried. The TransitionVerifier is the judge: if the model's test
+doesn't actually fail-before-and-pass-after, the proposal is rejected. The agent
+proposes; the world disposes.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+
+from ..state import CodeChange, Proposal
+
+_SYSTEM = (
+    "You are a senior engineer. You are given one source file and a goal. Propose "
+    "ONE small, surgical change that advances the goal, AND a NEW test that proves "
+    "it.\n\n"
+    "CRITICAL constraint on the test — it will be checked mechanically:\n"
+    "  * The test MUST FAIL on the current (unchanged) code.\n"
+    "  * The test MUST PASS once your change is applied.\n"
+    "A test that passes on the current code will be rejected as worthless.\n\n"
+    "Output ONLY JSON with this shape:\n"
+    '{{"issue": {{"text": "<one sentence>", "severity": "low|medium|high"}},\n'
+    '  "fix": {{"text": "<one sentence>", "find": "<exact substring from the file, or null>", '
+    '"replace": "<replacement, or null>", "append": "<code to append, or null>"}},\n'
+    '  "test": {{"path": "<repo-root-relative path to a test file>", '
+    '"append": "<a complete vitest test, including any imports it needs>"}}}}\n'
+    "Rules: use EITHER find+replace (find must be copied verbatim and occur once) "
+    "OR append, not both. The test `path` may be a new file. Keep the change minimal."
+)
+
+
+def _slug(s: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", s.lower()).strip("-")[:24]
+
+
+def parse_fix_with_test(persona: str, node_id: str, data: dict) -> list[Proposal]:
+    """Turn the model's JSON into one Proposal carrying change + test_change.
+    Pure and defensive: anything malformed yields no proposal rather than a crash."""
+    mod = _slug(node_id.split("/")[-1])
+    issue = data.get("issue") or {}
+    fix = data.get("fix") or {}
+    test = data.get("test") or {}
+
+    text = str(fix.get("text") or issue.get("text") or "").strip()
+    if not text:
+        return []
+    sev = issue.get("severity", "medium")
+    if sev not in ("low", "medium", "high"):
+        sev = "medium"
+
+    # implementation change: find/replace OR append
+    find, replace, append = fix.get("find"), fix.get("replace"), fix.get("append")
+    change: CodeChange | None = None
+    if isinstance(find, str) and find and isinstance(replace, str):
+        change = CodeChange(path=node_id, find=find, replace=replace)
+    elif isinstance(append, str) and append.strip():
+        change = CodeChange(path=node_id, append=append)
+    if change is None:
+        return []
+
+    # the test that proves it
+    tpath, tappend = test.get("path"), test.get("append")
+    test_change: CodeChange | None = None
+    if isinstance(tpath, str) and tpath and isinstance(tappend, str) and tappend.strip():
+        test_change = CodeChange(path=tpath, append=tappend)
+    if test_change is None:
+        return []  # no test -> nothing for the TransitionVerifier to check; skip
+
+    gid = f"{persona}:{mod}:fix"
+    return [Proposal(gid, persona, "fix", node_id, text, severity=sev,
+                     change=change, test_change=test_change)]
+
+
+class FixWithTestAgent:
+    """Implements the ``Agent`` protocol; proposes change + proving test."""
+
+    def __init__(self, repo_root: str, model: str = "gpt-4o",
+                 focus_modules: list[str] | None = None, max_source_chars: int = 9000,
+                 client=None, temperature: float = 0.2):
+        self.repo_root = repo_root
+        self.model = model
+        self.focus_modules = focus_modules
+        self.max_source_chars = max_source_chars
+        self._client = client
+        self.temperature = temperature
+
+    def _client_lazy(self):
+        if self._client is None:
+            from openai import OpenAI
+            self._client = OpenAI()
+        return self._client
+
+    def _ask(self, persona: str, goal: str, node_id: str, source: str) -> list[Proposal]:
+        user = f"Goal: {goal}\nFile: {node_id}\n\n```\n{source}\n```"
+        try:
+            resp = self._client_lazy().chat.completions.create(
+                model=self.model,
+                temperature=self.temperature,
+                response_format={"type": "json_object"},
+                messages=[{"role": "system", "content": _SYSTEM},
+                          {"role": "user", "content": user}],
+            )
+            data = json.loads(resp.choices[0].message.content or "{}")
+        except Exception as e:  # never crash the loop on a bad call/parse
+            print(f"  [warn] {persona} on {node_id}: {e}")
+            return []
+        return parse_fix_with_test(persona, node_id, data)
+
+    def propose(self, persona, goal, nodes, prior_committed, iteration):
+        if iteration != 1:
+            return []
+        ids = [n.id for n in nodes]
+        targets = self.focus_modules or ids
+        proposals: list[Proposal] = []
+        for node_id in targets:
+            if node_id not in ids:
+                continue
+            try:
+                with open(os.path.join(self.repo_root, node_id), encoding="utf-8") as f:
+                    source = f.read()[: self.max_source_chars]
+            except OSError:
+                continue
+            proposals += self._ask(persona, goal, node_id, source)
+        return proposals

agentboard/agents/gap_auditor.py

@@ -0,0 +1,166 @@
+"""GapAuditor — the precision layer. ADVISORY, never a verdict.
+
+Tonight's proven problem: every `confirmed_gap` the pipeline produced was a FALSE
+POSITIVE — the agent asserted its own ASSUMPTION, and the tool's real contract
+(often in code the PR didn't touch) disagreed. Only a human reading source caught
+them.
+
+This does that source-reading step and hands the human the evidence:
+for each confirmed_gap, a DIFFERENT model reads the source file + the agent's test
++ the observed assertion failure, and judges: does the code's ACTUAL behavior match
+what the test asserted?
+
+CRITICAL THESIS GUARD:
+  - This NEVER changes the gate's verdict. The gate already ran the code; that
+    result stands. The auditor only ANNOTATES: likely_real / likely_false_positive
+    / uncertain, with a one-line reason and the source lines it relied on.
+  - It is triage, not truth. It tells the human WHICH gaps to check first and WHERE
+    to look. The human still decides. An LLM does not get to rule a real failing
+    test "not a bug" and suppress it.
+  - Because it's a judgment (not a deterministic check), it must show its evidence
+    so the human can overrule it in seconds.
+"""
+from __future__ import annotations
+
+import json
+import os
+
+from ..review import ReviewFinding
+
+Assessment = str  # "likely_real" | "likely_false_positive" | "uncertain"
+
+_SYSTEM = """You are auditing a code review finding for FALSE POSITIVES. Another agent claimed a tool has a bug because a test it wrote failed. Your job is NOT to decide if the tool is good — it is to decide whether the failing test actually reflects a real defect, or whether the agent simply ASSERTED something the code was never contracted to do.
+
+You are given: the source file, the test the agent wrote, and the assertion that failed.
+
+Reason strictly from the SOURCE:
+- Find the code that produces the value under test. Quote the specific lines.
+- Ask: is the agent's assertion the code's ACTUAL contract, or the agent's assumption about how it *should* behave?
+- A test can fail for three reasons: (1) the tool has a real defect, (2) the agent asserted a behavior the tool never promised (design disagreement / wrong assumption), or (3) the agent's test setup didn't create what it assumed (so the tool correctly returned empty/less).
+- Cases (2) and (3) are FALSE POSITIVES. Only (1) is a real gap.
+
+Be skeptical of the agent, but be MORE skeptical of dismissing a real bug. Calling a genuine defect a false positive is the worst error you can make here: the failing test already EXECUTED against real code, so the burden of proof is on the dismissal, not on the bug. A test that ran and failed is presumed to reflect a real defect UNTIL you can quote the exact source line or rule that proves the agent asserted something the code never promised.
+
+HARD BAR FOR likely_false_positive: you may only answer likely_false_positive if you can QUOTE the specific line(s) of source that establish the code's actual contract and show the agent's assertion contradicts that contract (a design disagreement) OR show the test's setup did not create what it assumed. Put that quoted line in "evidence". If you cannot quote such a line, you are NOT permitted to say likely_false_positive — answer likely_real or, only if the code path is genuinely untraceable, uncertain.
+
+WATCH FOR REAL BUGS THAT LOOK BENIGN: if the observed failure shows actual state being lost, mutated, or fabricated (e.g. a prototype changed, a value dropped, a count off by one, "expected true to be false" on a pollution check), lean likely_real — those are the exact signatures of the defects this tool exists to catch, and they are easy to wave away as "the agent's assumption."
+
+COMMIT to a call. "uncertain" is ONLY for when you genuinely cannot find the relevant code or the source is truly ambiguous — it is NOT a safe default. If you can trace the code path that produces the value under test, you MUST decide likely_real or likely_false_positive:
+- If the code plainly produces a WRONG result for a valid input the intent covers (loses, duplicates, or fabricates information), say likely_real.
+- If the code behaves consistently by its own clear rule AND you can quote that rule, and the agent merely assumed a different rule, say likely_false_positive.
+Do not hide correct analysis behind "uncertain." If your reasoning has identified the mechanism, state the verdict that reasoning implies.
+
+You MUST always fill in "reason" and "evidence" with specifics from the source (name the behavior and the lines/logic). An empty reason is not acceptable; a likely_false_positive with no quoted source line is not acceptable.
+
+Output ONLY JSON:
+{"assessment": "likely_real" | "likely_false_positive" | "uncertain",
+ "reason": "<one sentence, plain — required, never empty>",
+ "evidence": "<the specific source behavior/lines you relied on — required, never empty>"}"""
+
+
+def _loads_one(text: str) -> dict:
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        s, e = text.find("{"), text.rfind("}")
+        if s >= 0 and e > s:
+            try:
+                return json.loads(text[s:e + 1])
+            except json.JSONDecodeError:
+                pass
+    return {}
+
+
+class GapAuditor:
+    def __init__(self, model: str = "gpt-5.5", client=None, max_source_chars: int = 16000):
+        self.model = model
+        self._client = client
+        self.max_source_chars = max_source_chars
+        self._is_openai = model.startswith("gpt") or model.startswith("o")
+
+    def _client_lazy(self):
+        if self._client is None:
+            if self._is_openai:
+                from openai import OpenAI
+                self._client = OpenAI()
+            else:
+                from anthropic import Anthropic
+                self._client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
+        return self._client
+
+    def _ask(self, source: str, finding: ReviewFinding) -> dict:
+        user = (
+            f"SOURCE FILE:\n```\n{source[:self.max_source_chars]}\n```\n\n"
+            f"THE AGENT'S CLAIMED GAP: {finding.behavior}\n\n"
+            f"THE TEST IT WROTE:\n```\n{finding.test_code or '(none)'}\n```\n\n"
+            f"THE ASSERTION THAT FAILED:\n{finding.observed or '(none)'}\n\n"
+            f"Audit this for a false positive. Respond ONLY with the JSON."
+        )
+        client = self._client_lazy()
+        if self._is_openai:
+            resp = client.chat.completions.create(
+                model=self.model,
+                response_format={"type": "json_object"},
+                messages=[{"role": "system", "content": _SYSTEM},
+                          {"role": "user", "content": user}],
+            )
+            return _loads_one(resp.choices[0].message.content or "{}")
+        resp = client.messages.create(
+            model=self.model, max_tokens=2500,
+            system=_SYSTEM + "\n\nRespond with ONLY the JSON object, nothing before it.",
+            messages=[{"role": "user", "content": user}],
+        )
+        text = "".join(b.text for b in resp.content if getattr(b, "type", None) == "text")
+        return _loads_one(text)
+
+    def audit(self, source: str, finding: ReviewFinding) -> ReviewFinding:
+        """Annotate a confirmed_gap with an advisory assessment. Verdict UNCHANGED.
+
+        Two guards against the auditor's own failure modes, both learned from a
+        benchmark run:
+          * empty reason -> retry once. Sonnet hedged 'uncertain' with a blank
+            reason on ~6 gaps (concentrated on prototype-semantics questions); a
+            single retry recovers most into a committed, reasoned call.
+          * likely_false_positive with no quoted source line -> DOWNGRADE to
+            uncertain. Dismissing a real, executed failure is the costliest
+            error here (it once flagged a genuine strict catch as FP), so a
+            dismissal that cannot cite the contract it relies on is not trusted.
+        """
+        if finding.status != "confirmed_gap":
+            return finding
+        try:
+            data = self._ask(source, finding)
+            reason = str(data.get("reason", "")).strip()
+            if not reason:  # empty-reason hedge -> one retry
+                data = self._ask(source, finding)
+        except KeyError as e:  # missing API key — make it LOUD, not a silent skip
+            finding.audit = "not_audited"
+            finding.audit_reason = f"auditor could not run: missing {e} — gap is UNVERIFIED"
+            print(f"  [AUDITOR DID NOT RUN] missing {e}; gaps are unverified")
+            return finding
+        except Exception as e:
+            finding.audit = "not_audited"
+            finding.audit_reason = f"auditor error: {e} — gap is UNVERIFIED"
+            print(f"  [warn] auditor: {e}")
+            return finding
+        assessment = data.get("assessment", "uncertain")
+        if assessment not in ("likely_real", "likely_false_positive", "uncertain"):
+            assessment = "uncertain"
+        reason = str(data.get("reason", "")).strip()[:200]
+        evidence = str(data.get("evidence", "")).strip()[:300]
+        # A dismissal must cite the contract it relies on. No evidence quote ->
+        # the auditor has not earned the FP call; downgrade so a real bug is
+        # never buried under an unsupported "false positive".
+        if assessment == "likely_false_positive" and not evidence:
+            assessment = "uncertain"
+            reason = ("(downgraded from false-positive: no source line cited) "
+                      + reason)[:200]
+        finding.audit = assessment
+        finding.audit_reason = reason
+        finding.audit_evidence = evidence
+        return finding
+
+    def audit_all(self, source: str, findings: list[ReviewFinding]) -> list[ReviewFinding]:
+        for f in findings:
+            self.audit(source, f)
+        return findings