# Implementation Parity Report Format

All implementation parity check agents return results in this JSON structure.

## Schema

```json
{
  "check_type": "<one of: model-doc-code-parity, command-doc-code-parity, command-error-implementation-parity, command-doc-test-parity, query-doc-code-parity, query-error-implementation-parity, query-doc-test-parity>",
  "module": "<module-name>",
  "gaps": [
    {
      "source": "<source doc or code path>",
      "target": "<target code or doc path, or 'missing'>",
      "check": "<check_id from the agent's parity checks table>",
      "status": "pass | fail | skip",
      "evidence": "<file:line supporting the verdict — required for pass and fail>",
      "detail": "<human-readable description of the finding>"
    }
  ],
  "inconsistencies": [
    {
      "type": "<inconsistency type, e.g. type_mismatch, missing_description>",
      "location": "<source vs target description>",
      "detail": "<human-readable description>"
    }
  ],
  "summary": {
    "total_checks": 0,
    "passed": 0,
    "failed": 0,
    "skipped": 0,
    "claims_total": 0
  }
}
```

## Field Reference

### gaps[]

One entry per parity check performed. `status` is:

- `pass`: doc and code are consistent
- `fail`: gap or mismatch found
- `skip`: target code/doc missing or empty, check could not run

### inconsistencies[]

Cross-cutting issues found during the check that don't fit a single gap entry (e.g., type mismatches, naming violations, missing descriptions across multiple files).

### summary

Aggregate counts. `total_checks = passed + failed + skipped`.

`claims_total` is the omission detector: it is fixed while enumerating doc claims (before reading any code), so the aggregator can catch silently skipped claims — if `total_checks < claims_total`, the agent verified fewer claims than it enumerated. Evidence catches sloppy passes; `claims_total` catches silent omission.

## Router-Level Severity and Verdict

The router (SKILL.md Step 3) assigns severity to each non-pass finding after collecting all agent results. Agents do NOT assign severity — they only report `status` and `detail`.

The router classifies each finding as:

- `critical`: blocks progress — missing implementation of documented feature, broken contract between doc and code
- `major`: should fix — incomplete implementation, missing test case for documented business rule
- `nit`: nice to have — minor naming difference, optional JSDoc improvement, cosmetic code style issue

Verdict rule:

- `APPROVED`: zero `critical` and zero `major` findings (nits only, or all pass)
- `NEEDS_CHANGES`: one or more `critical` or `major` findings