Artifacts & Schema Reference

Use this page when you want to integrate PatchPatrol output into automation, checkers, or any non-interactive workflow.

Source of truth: schema.json plus the current artifact writing behavior in patchpatrol/artifacts.py and patchpatrol/cli.py.

What PatchPatrol Writes

PatchPatrol writes files into AI_REVIEW_OUTPUT_DIR (default .ai-review).

Use the First review output page for quick interpretation.

Core JSON contract (stable)

ai-review.json validates against schema.json with three required top-level fields:

• meta
• summary
• findings

The top-level object and finding objects reject unknown properties, so key names above and their nested fields should match what integrators send to downstream systems.

meta

meta is required and includes at least these stable keys:

• model
• base_sha
• head_sha
• generated_at
• diff_stats
• limits

meta.diff_stats requires:

• files
• insertions
• deletions

meta.limits is a dictionary. It always exists and carries runtime-applied limit values and execution diagnostics.

summary

summary is required and includes these stable fields:

• overall_risk
• top_issues

overall_risk is one of low, medium, or high.

findings

findings is required and is an array of finding objects.

A finding currently requires:

• severity
• category
• file
• line_start
• line_end
• title
• description
• recommendation
• confidence

suggested_patch and provenance are optional.

Published enums and controlled values

The following enum sets are the reliable values currently emitted and validated:

• finding.severity: blocker, high, medium, low, info
• finding.category: security, correctness, reliability, performance, maintainability, testing, style
• summary.overall_risk: low, medium, high
• finding.provenance.origin: llm, semantic, security_tool, combined
• finding.provenance.sources: llm, semantic, security_tool
• meta.security_precheck.status: pass, fail, unavailable, error, skipped

Runtime fields in meta you may see today

The schema allows additional public metadata in meta. In the shipped runtime paths, these meta sections are currently present in supported cases:

• meta.semantic_precheck
• meta.security_precheck
• meta.trust_gate
• meta.provider_runtime
• meta.feedback
• meta.repository_overview
• meta.usage_ledger
• meta.performance_diagnostics

These are additive and may grow as execution behavior evolves.

Treat missing optional sections as normal and preserve unknown keys when forwarding or storing reports.

Minimal valid payload example

{
  "meta": {
    "model": "deepseek-coder-v2:16b",
    "base_sha": "1111111",
    "head_sha": "2222222",
    "generated_at": "2026-02-26T12:00:00Z",
    "diff_stats": {
      "files": 0,
      "insertions": 0,
      "deletions": 0
    },
    "limits": {
      "max_diff_bytes": 32768,
      "max_files": 50
    }
  },
  "summary": {
    "overall_risk": "low",
    "top_issues": []
  },
  "findings": []
}

That structure is intentionally minimal, but valid for parser bootstrap checks and contract tests.

Stability posture

• ai-review.json and ai-review.md are the shipped public artifact baseline.
• schema.json is the contract source for those artifacts.
• Integrators should validate required fields and enums from schema.json and treat extra fields as optional forward-compatible extensions.
• Any optional output sections should be handled defensively (null/absent checks first), because these sections are surfaced opportunistically.