Structured annotations for agent findings

[dlorenc]

Overview

Allow agents (and humans) to attach structured, machine-readable findings to a branch alongside free-text comments. Findings are queryable, renderable distinctly from prose comments, and actionable by policies.

Data model

{
  "type": "finding",
  "category": "security",
  "severity": "critical|high|medium|low|info",
  "rule": "CWE-89",
  "file": "internal/db/store.go",
  "line": 142,
  "message": "Potential SQL injection via string concatenation"
}

API

POST /repos/{owner}/{name}/-/branch/:branch/findings
GET  /repos/{owner}/{name}/-/branch/:branch/findings

Findings are scoped to a branch+sequence (invalidated on new push, like check runs).

Policy integration

Policies can gate on findings:

deny if {
  some f in input.findings
  f.severity == "critical"
}

input.findings added to policy input alongside input.reviews, input.check_runs.

Why

Without structured annotations, agent output is prose comments that humans read but systems can't act on. Structured findings let:

• Policies block merges on critical findings
• Other agents query findings without parsing text
• UI render a findings panel separate from discussion
• Metrics track finding trends over time

Scope

• Schema: findings table (repo, branch, sequence, category, severity, rule, file, line, message, reporter)
• API: POST/GET endpoints
• Policy input: add findings []FindingInput to policy engine input
• Events: emit FindingReported CloudEvent
• Include findings in agent context endpoint (issue Agent context assembly endpoint #252)