review-contract

Review contract

One schema, one severity vocabulary, one event rule — defined here and only here. Reviewer agents preload this skill; the posting layer (orc:inline-review) and any new reviewer agent reference it instead of restating it.

Finding schema

Reviewer agents return strict JSON only (no surrounding markdown, no prose preamble):

{
  "summary": "≤ 2 sentences, ~40 words: one clause on what the PR does + finding counts by severity. Informational only — does NOT decide the event.",
  "findings": [
    {
      "path": "src/auth.ts",
      "line": 42,
      "start_line": null,
      "side": "RIGHT",
      "severity": "bug",
      "title": "Null deref when token absent",
      "body": "When `req.headers.authorization` is missing, `parseToken()` returns null and the next line dereferences `.userId` unconditionally — 500 to client, no log. Guard with an early return.",
      "suggestion_code": "const token = parseToken(req);\nif (!token) return res.status(401).end();",
      "confidence": 0.92
    }
  ]
}

Zero findings: {"summary": "No actionable issues found. …", "findings": []} — the posting layer computes APPROVE from the empty list.

Field semantics

• Required per finding: path, line, severity, title, body, confidence.
• Optional: start_line (multi-line spans: start_line: 45, line: 47; else null), suggestion_code (see gate below; else null).
• path — repo-relative POSIX path. NOT a URL, NOT a/- or b/-prefixed. In workspace mode, still repo-relative; the orchestrator prefixes [repo:<name>].
• line — line number in the NEW file (post-change), computed from the diff hunk header @@ -OLD,N +NEW,N @@ plus offset within the hunk. NOT the hunk offset.
• side — always "RIGHT" (the new/changed code).
• title — ≤ 80 chars, one line.
• body — orc:caveman-review tone: terse, actionable, signal-only.
• confidence — 0–1. Drop the finding entirely if < 0.8. A noisy review burns the author's time; false positives erode trust faster than misses.