feat(review-tools): formal verdict surface with below-the-model guards (v0.2.0)

[mabry1985]

ADR 0078 Phase B — the verdict surface for the QA-review takeover (protoAgent docs/plans/qa-review-takeover.md).

What ships

Tool	Gate
github_review_comment	none — a COMMENT is always safe
github_review_approve	CI-terminal + self-review guards, inside the tool
github_review_request_changes	same guards
github_path_exists (read)	the EXISTS/MISSING grounding probe (cross-repo capable; errors read as UNVERIFIED — a Gap, never a verdict)

The guards (Quinn's failure ledger, enforced below the model)

• CI-terminal (#863, killed 24/25 of her failures): blocking verdicts are refused while any check run is queued/in-progress — and when CI can't be read at all (a 403 says nothing about pass/fail: fail closed, never open). The refusal text instructs comment-instead and explicitly forbids waiting/polling, so the busy-wait failure class can't exist here either.
• Self-review: a blocking verdict on a PR authored by the token's own identity is refused (self-approval loops); commenting stays allowed.
• No checks at all = terminal by definition (nothing to wait for).

Review tools register under the existing github.write gate alongside merge/close.

Tests

13 new — the point is that the guards are unbypassable: pending CI, unreadable CI, and own-PR all refuse before anything reaches the Review API (asserted via the captured call list). Full suite 110 passed, ruff clean. v0.2.0.

Next: B2 — protoPatch as a fifth, non-LLM panel member.

🤖 Generated with Claude Code

[protoquinn]

👀 Quinn is reviewing — verdict (PASS / WARN / FAIL) + findings to follow.

[protoquinn]

QA Audit — PR #21 | feat(review-tools): formal verdict surface with below-the-model guards (v0.2.0)

VERDICT: WARN (CI settling — see below)

---

CI Status

• test: in_progress ⏳

Diff Review

• 7 files, +426/-3: new review_tools.py (219 lines), github_path_exists probe in read_tools.py, version bump 0.1.6 → 0.2.0 across pyproject.toml + protoagent.plugin.yaml, and tool registration hook in __init__.py.
• Architecture is clean: review tools register under the existing github.write gate alongside merge/close tools — no new auth surface.
• Guards are below-the-model: _ci_state() returns terminal/pending/unknown, and unknown (CI unreadable) is treated identically to pending — fail-closed, per #863.

Observations

• INFO: _viewer_login() returns "" on failure. If the self-review guard compares this against PR author, an empty viewer will never match a real author (fail-open on that guard specifically). This is the right tradeoff — the alternative (blocking all verdicts on a transient user-API error) would be worse, and the CI-terminal guard is the primary safety net.
• GAP: clawpatch structural review returned 2 report findings but the detail payload was null — could not surface the specific findings. The mapped features (9) and reviewed slice (1) suggest coverage of the new module; re-running with provider: proto on a re-review pass would give deeper coverage.
• GAP: The diff was truncated at 502 lines — the 3 tool definitions (github_review_comment, github_review_approve, github_review_request_changes) and the test files are not fully visible. The 13 new tests claim full guard coverage (pending CI, unreadable CI, own-PR all refuse before reaching the Review API).

---

⏳ CI is still settling — the test check is in progress. Per the approve-on-green policy, this COMMENT review will be promoted to a formal APPROVE automatically once every check completes terminal-green with no blockers on this review. No re-review dispatch is needed.

— Quinn, QA Engineer

[protoquinn]

Submitted COMMENT review on protoLabsAI/github-plugin#21.