JSON Schema: /api/contract/v1/schema.json

HQ Rabbit review contract (v1)

A submission is how a developer's local agent hands a finished code review to HQ Rabbit. It is one plain PR comment with a marker and a JSON payload. The server validates it deterministically: if it fits this contract and matches the PR, the bot reposts the findings as its own review, deletes the comment and turns the hq-rabbit check green. If not, the bot replies with the errors listed below and leaves the comment in place so the agent can fix it and post a new submission.

The source of truth is the src/contract module. A JSON Schema generated from it is served at /api/contract/v1/schema.json.

Comment format

<!-- hq-rabbit:submission v1 -->
```json
{ ...payload... }
```
  • The marker <!-- hq-rabbit:submission v1 --> must be the first non-whitespace content of the comment. A comment that mentions the marker anywhere else is not treated as a submission and is ignored by the server.
  • Exactly one fenced json block follows. The opening fence is a line of 3 or more backticks followed by json; the closing fence is a line of only backticks, at least as many as the opening fence. Text before or after the block is ignored.
  • The block must be strict JSON: double-quoted keys and strings, no comments, no trailing commas.
  • Backticks inside JSON strings (for example a code block in a finding body) need no special care: strings in valid JSON cannot contain raw newlines, and a closing fence must be a line of its own, so they can never end the block. As a precaution, buildSubmissionComment uses a fence one backtick longer than any backtick run in the JSON, and the parser accepts any fence of 3 or more backticks.

Post it with gh pr comment <number> --body-file <file>.

Payload

{
  "version": 1,
  "headSha": "<40-char hex commit SHA the review was performed against>",
  "summary": "<overall assessment, 1–2,000 chars>",
  "reviewer": {                       // optional, informational only
    "tool": "claude-code",            // free text, max 60
    "model": "<model id>"             // free text, max 100
  },
  "filesReviewed": ["path/a.ts", "path/b.ts"],   // 1–3,000 unique repo-relative paths
  "findings": [                       // 0–50 items; empty means a clean review
    {
      "path": "src/x.ts",             // required, repo-relative
      "line": 42,                     // optional; omit for a file-level finding
      "startLine": 40,                // optional; requires line; startLine <= line
      "side": "RIGHT",                // optional, "RIGHT" (default, new code) or "LEFT" (removed code)
      "severity": "major",            // "critical" | "major" | "minor" | "nit"
      "title": "<max 120 chars>",
      "body": "<max 1,000 chars, markdown allowed>",
      "suggestion": "<optional replacement code, max 1,000 chars>"
    }
  ]
}

Unknown keys, at the top level, in reviewer or in a finding, are rejected so that typos surface as errors.

Field reference

FieldRequiredRules
versionyesThe number 1.
headShayesFull 40-character hex SHA of the commit you reviewed (git rev-parse HEAD). Must equal the PR's head.
summaryyes1–2,000 characters, not blank. Overall assessment; say here if lower-severity findings were dropped.
reviewernoObject with optional tool (max 60) and model (max 100). Informational only.
filesReviewedyes1–3,000 unique repo-relative paths. Must include every file the PR changes, including deleted files.
findingsyes0–50 findings. [] is a clean review.
findings[].pathyesRepo-relative path of the file the finding is about.
findings[].linenoPositive integer: the line the comment attaches to (the last line of a range). Omit for a file-level note.
findings[].startLinenoPositive integer, first line of a multi-line range. Requires line, and startLine <= line.
findings[].sidenoRIGHT (default): line numbers in the new version of the file. LEFT: line numbers in the old version.
findings[].severityyescritical, major, minor or nit (see below).
findings[].titleyes1–120 characters, not blank. One-line statement of the problem.
findings[].bodyyes1–1,000 characters, not blank. Markdown allowed. Explain the problem and the fix.
findings[].suggestionno1–1,000 characters. Replacement code for the line range (rendered as a GitHub suggestion where possible).

A repo-relative path has no leading /, no . or .. segments and no line breaks, and is spelled exactly as GitHub lists it in the PR's files, for example src/app/page.tsx. Paths are at most 1,024 characters.

Findings whose line cannot be placed on the PR diff are still accepted; the bot puts them in the body of its review instead of inline.

Severity

  • critical — will break production, lose data, or open a security hole.
  • major — a real bug or a design problem that should be fixed before merge.
  • minor — worth fixing but not blocking.
  • nit — style or preference.

Limits

LimitValue
summary2,000 characters
reviewer.tool60 characters
reviewer.model100 characters
filesReviewed1–3,000 paths
Any path1,024 characters
findings50
findings[].title120 characters
findings[].body1,000 characters
findings[].suggestion1,000 characters
Whole payload, as compact JSON60,000 characters (total)

Lengths are counted in JavaScript string length (UTF-16 code units; most characters count as 1, emoji as 2).

Why a total cap. A GitHub comment holds at most 65,536 characters. The per-field limits alone allow far more than that (50 findings with full bodies and suggestions is over 100,000 characters before JSON escaping), so the payload also has a total cap: JSON.stringify(payload) must be at most 60,000 characters. Within that cap, a comment built by buildSubmissionComment is always under 65,536 characters, fences included. If you hit the cap, shorten finding bodies and suggestions, or keep the highest-severity findings and say in summary that lower ones were dropped. The cap is measured on compact JSON; indenting adds characters, so use compact JSON for payloads near the cap (buildSubmissionComment indents with 2 spaces, and switches to compact JSON when the indented form would exceed 60,000 characters).

Large PRs. Each filesReviewed entry costs its length plus 3 characters, so the total cap binds before the 3,000-path limit: with an average path of 50 characters, about 1,000 files fit alongside a short summary and a few findings. PRs larger than that cannot be submitted in v1 and should be split.

If there are more than 50 findings, keep the 50 most severe and say in summary that lower-severity ones were dropped. Multi-part submissions are not part of v1.

Checks against the PR

After the payload fits the schema, the server checks it against the PR:

  • headSha must equal the PR's current head SHA. A push after the review makes the submission stale: pull, review again, resubmit.
  • Every file the PR changes (every filename in GitHub's list-PR-files response, including removed files) must appear in filesReviewed. Extra paths are allowed.

Error codes

Every error has a stable code, a path into the payload where relevant (for example findings[2].title), and a message that says how to fix it. The bot's rejection reply lists them (at most 30, then a count of the rest).

CodeMeaning
missing_markerThe comment does not contain the submission marker.
marker_not_firstThe marker is present but something comes before it.
unsupported_versionThe marker or version names a contract version other than 1.
missing_json_blockNo fenced json block after the marker, or the block is never closed.
multiple_json_blocksMore than one fenced json block.
invalid_jsonThe block is not valid JSON (comments, trailing commas, single quotes, unescaped newlines...).
unknown_keyA key the contract does not define (often a typo).
schemaA field is missing, has the wrong type, is out of range or too long, or breaks a rule such as startLine.
duplicate_fileA path appears more than once in filesReviewed.
too_many_findingsMore than 50 findings.
too_largeThe payload exceeds 60,000 characters as compact JSON.
stale_shaheadSha is not the PR's current head. The message names both SHAs.
missing_filesChanged files are missing from filesReviewed. The message lists up to 20 of them and counts the rest.

The JSON Schema covers everything except the cross-field and whole-payload rules: unique filesReviewed, startLine requiring line and being at most line, and the total size cap.

Examples

A review with findings:

<!-- hq-rabbit:submission v1 -->

````json
{
  "version": 1,
  "headSha": "3f2a9c1e8b7d6a5f4e3d2c1b0a9f8e7d6c5b4a39",
  "summary": "Adds rate limiting to the login endpoint. The limiter itself is sound, but the key ignores proxies and one error path leaks whether an account exists.",
  "reviewer": { "tool": "claude-code", "model": "claude-opus-4-5" },
  "filesReviewed": [
    "src/app/api/login/route.ts",
    "src/lib/rate-limit.ts",
    "src/lib/rate-limit.test.ts",
    "src/lib/old-throttle.ts"
  ],
  "findings": [
    {
      "path": "src/lib/rate-limit.ts",
      "line": 18,
      "startLine": 15,
      "severity": "major",
      "title": "Rate limit key uses the proxy address",
      "body": "Behind the load balancer `req.ip` is the proxy, so every user shares one bucket. Use the first address in `x-forwarded-for`, which the platform sets.",
      "suggestion": "const key = req.headers.get(\"x-forwarded-for\")?.split(\",\")[0]?.trim() ?? req.ip;"
    },
    {
      "path": "src/app/api/login/route.ts",
      "line": 42,
      "severity": "critical",
      "title": "Error message reveals whether the account exists",
      "body": "Unknown emails return `No such user` while bad passwords return `Wrong password`. Return the same message for both:\n\n```ts\nreturn error(401, \"Invalid email or password\");\n```"
    },
    {
      "path": "src/lib/rate-limit.test.ts",
      "severity": "nit",
      "title": "Test names describe implementation, not behavior",
      "body": "Consider naming tests after what the user sees, e.g. `blocks the sixth attempt within a minute`."
    }
  ]
}
````

A clean review:

<!-- hq-rabbit:submission v1 -->

```json
{
  "version": 1,
  "headSha": "0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d",
  "summary": "Renames the config loader and updates its callers. No issues found.",
  "filesReviewed": ["src/config/load.ts", "src/server.ts"],
  "findings": []
}
```