Schemas
Every payload the CLI and the MCP server accept or return is validated against a schema. The six schemas below are generated from the single zod source of truth in core/model.ts by scripts/gen-schemas.ts, and continuous integration fails the build if the checked-in files under schemas/ ever drift from that source. What you read here is exactly what the package enforces at runtime.
Config
Machine-local settings resolved before every command: your GitHub login, default repository, custom skills directory, default reviewers, the peer agent logins the expedition safety gate counts as agents rather than humans, and the opt-in review metadata capture fields.
{
"$ref": "#/definitions/config",
"definitions": {
"config": {
"type": "object",
"properties": {
"githubLogin": {
"type": [
"string",
"null"
],
"default": null
},
"defaultRepo": {
"type": "string"
},
"skillsDir": {
"type": [
"string",
"null"
],
"default": null
},
"model": {
"type": "string"
},
"agent": {
"type": "string"
},
"toolVersion": {
"type": "string"
},
"captureMetadata": {
"type": "boolean",
"default": false
},
"reviewers": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"default": []
},
"knownAgentLogins": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"default": []
},
"mergeMethodByRepo": {
"type": "object",
"additionalProperties": {
"type": "string",
"enum": [
"merge",
"squash",
"rebase"
]
}
}
},
"additionalProperties": false
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
Example:
{
"githubLogin": null,
"defaultRepo": "input-output-hk/some-repo",
"skillsDir": null,
"reviewers": ["peer-agent-login"],
"knownAgentLogins": ["peer-agent-login"],
"captureMetadata": false
}
Review Request
The input to review.create: the pull request to review, the skills to attach, and the reviewers to request.
{
"$ref": "#/definitions/review-request",
"definitions": {
"review-request": {
"type": "object",
"properties": {
"repo": {
"type": "string",
"pattern": "^[^/]+\\/[^/]+$"
},
"pr": {
"type": "integer",
"exclusiveMinimum": 0
},
"skills": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"reviewers": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1
},
"note": {
"type": "string"
}
},
"required": [
"repo",
"pr",
"reviewers"
],
"additionalProperties": false
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
Example:
{ "repo": "input-output-hk/some-repo", "pr": 42, "skills": ["security", "cryptography"], "reviewers": ["yshyn-iohk"], "note": "focus on the crypto changes" }
Claim Marker
The JSON payload embedded in the claim comment. It pins a review to a commit SHA and records who claimed it and from which machine.
{
"$ref": "#/definitions/claim-marker",
"definitions": {
"claim-marker": {
"type": "object",
"properties": {
"v": {
"type": "number",
"enum": [
1,
2
]
},
"reviewer": {
"type": "string",
"minLength": 1
},
"machine": {
"type": "string",
"minLength": 1
},
"sha": {
"type": "string",
"minLength": 7
},
"claimedAt": {
"type": "string",
"minLength": 1
},
"model": {
"type": "string"
},
"agent": {
"type": "string"
},
"toolVersion": {
"type": "string"
}
},
"required": [
"v",
"reviewer",
"sha",
"claimedAt"
],
"additionalProperties": false
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
Review Result
The input to review.complete: the review event, the summary, and any inline comments.
{
"$ref": "#/definitions/review-result",
"definitions": {
"review-result": {
"type": "object",
"properties": {
"repo": {
"type": "string",
"pattern": "^[^/]+\\/[^/]+$"
},
"pr": {
"type": "integer",
"exclusiveMinimum": 0
},
"event": {
"type": "string",
"enum": [
"approve",
"request-changes",
"comment"
]
},
"summary": {
"type": "string",
"minLength": 1
},
"comments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"line": {
"type": "integer",
"exclusiveMinimum": 0
},
"body": {
"type": "string"
}
},
"required": [
"path",
"line",
"body"
],
"additionalProperties": false
}
},
"reviewedSha": {
"type": "string",
"minLength": 7
},
"mode": {
"type": "string",
"enum": [
"initial",
"rereview",
"convergence"
]
},
"findings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"severity": {
"type": "string",
"enum": [
"critical",
"high",
"medium",
"low"
]
},
"confidence": {
"type": "string",
"enum": [
"confirmed",
"high",
"plausible",
"unverified"
]
},
"scope": {
"type": "string",
"enum": [
"introduced",
"regression",
"pre-existing",
"follow-up",
"accepted-risk"
]
},
"status": {
"type": "string",
"enum": [
"open",
"resolved",
"still-open",
"regressed",
"superseded",
"accepted-risk",
"follow-up"
]
},
"blocking": {
"type": "boolean"
},
"path": {
"type": "string",
"minLength": 1
},
"line": {
"type": "integer",
"exclusiveMinimum": 0
},
"evidence": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"remediation": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"relatedFindingId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 160
},
{
"type": "null"
}
]
},
"followUpIssue": {
"type": "string",
"format": "uri"
},
"reopenedBecause": {
"type": "string",
"minLength": 1,
"maxLength": 1000
}
},
"required": [
"id",
"title",
"severity",
"confidence",
"scope",
"status",
"blocking",
"path",
"line",
"evidence",
"remediation"
],
"additionalProperties": false
},
"maxItems": 20
}
},
"required": [
"repo",
"pr",
"event",
"summary"
],
"additionalProperties": false
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
Example:
{
"repo": "input-output-hk/some-repo",
"pr": 42,
"event": "request-changes",
"summary": "The nonce reuse is a confirmed blocker; see the inline comment.",
"reviewedSha": "abc1234",
"mode": "initial",
"findings": [
{
"id": "crypto-nonce-reuse",
"title": "Nonce is reused across messages",
"severity": "high",
"confidence": "confirmed",
"scope": "introduced",
"status": "open",
"blocking": true,
"path": "src/crypto.rs",
"line": 88,
"evidence": "The encryption loop passes the same nonce to every message.",
"remediation": "Derive or generate a unique nonce for each encrypted message."
}
],
"comments": [
{
"path": "src/crypto.rs",
"line": 88,
"body": "Nonce is reused across messages."
}
]
}
Enrichment
The input to review.enrich: an enricher's overall verdict, summary, and any new findings the primary review missed.
{
"$ref": "#/definitions/enrichment",
"definitions": {
"enrichment": {
"type": "object",
"properties": {
"overallVerdict": {
"type": "string",
"enum": [
"agree",
"disagree",
"mixed"
]
},
"summary": {
"type": "string",
"minLength": 1
},
"newFindings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"line": {
"type": "integer",
"exclusiveMinimum": 0
},
"body": {
"type": "string"
}
},
"required": [
"path",
"line",
"body"
],
"additionalProperties": false
}
},
"reviewedSha": {
"type": "string",
"minLength": 7
},
"mode": {
"type": "string",
"enum": [
"initial",
"rereview",
"convergence"
]
},
"findings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"severity": {
"type": "string",
"enum": [
"critical",
"high",
"medium",
"low"
]
},
"confidence": {
"type": "string",
"enum": [
"confirmed",
"high",
"plausible",
"unverified"
]
},
"scope": {
"type": "string",
"enum": [
"introduced",
"regression",
"pre-existing",
"follow-up",
"accepted-risk"
]
},
"status": {
"type": "string",
"enum": [
"open",
"resolved",
"still-open",
"regressed",
"superseded",
"accepted-risk",
"follow-up"
]
},
"blocking": {
"type": "boolean"
},
"path": {
"type": "string",
"minLength": 1
},
"line": {
"type": "integer",
"exclusiveMinimum": 0
},
"evidence": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"remediation": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"relatedFindingId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 160
},
{
"type": "null"
}
]
},
"followUpIssue": {
"type": "string",
"format": "uri"
},
"reopenedBecause": {
"type": "string",
"minLength": 1,
"maxLength": 1000
}
},
"required": [
"id",
"title",
"severity",
"confidence",
"scope",
"status",
"blocking",
"path",
"line",
"evidence",
"remediation"
],
"additionalProperties": false
},
"maxItems": 20
},
"assessments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"findingId": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"disposition": {
"type": "string",
"enum": [
"confirm",
"refute"
]
},
"rationale": {
"type": "string",
"minLength": 1,
"maxLength": 2000
}
},
"required": [
"findingId",
"disposition",
"rationale"
],
"additionalProperties": false
},
"maxItems": 50
}
},
"required": [
"overallVerdict",
"summary"
],
"additionalProperties": false
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
Label Spec
One label definition, a name, a color, and a description, applied when labels.bootstrap provisions a repository.
{
"$ref": "#/definitions/label-spec",
"definitions": {
"label-spec": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"color": {
"type": "string",
"pattern": "^[0-9a-fA-F]{6}$"
},
"description": {
"type": "string"
}
},
"required": [
"name",
"color",
"description"
],
"additionalProperties": false
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}