# Structured review reports and persistent findings

Code Eye now distinguishes an AI review finding from a walkthrough note. The
preferred `review` tool input is a structured `report` containing:

- review mode (`quick` or `deep`) and a summary;
- findings with a concrete claim, impact, evidence, severity, category,
  confidence, exact diff location, and optional suggestion;
- checks actually run; and
- explicit coverage (`reviewedFiles` and skipped files with reasons).

The extension validates the report before opening a surface. Findings without
evidence, impact, a valid location, or confidence in the `0..1` range are
rejected rather than rendered as authoritative review feedback.

## Finding identity and lifecycle

Findings provide a stable semantic `identity` slug based on the affected
symbol, invariant, and failure mode. The extension derives its fingerprint from
category, file, and that identity. Natural-language title/claim and line numbers
are deliberately excluded, so an issue keeps its identity when wording changes
or nearby edits move it.

The latest report persists in `<gitdir>/code-eye/state.json` alongside user
comments. Version 1 state migrates to version 2 on load.

- A repeated finding keeps its id and first-seen time.
- A finding omitted by a `deep` review becomes `fixed`.
- A `quick` review preserves omitted findings because they may be outside its
  coverage.
- Dismissed findings remain dismissed when reported again.

Only open findings are projected into the active review surface. Fixed and
dismissed findings remain in the ledger for incremental reconciliation.

## Presentation

TUI and web surfaces remain adapters over the same review data. Findings are
ordered by severity and confidence, display their evidence and impact, and are
accompanied by review/check/coverage summaries. User comments still follow
ADR-0002 and are the only content returned to the agent as work items.

Legacy `summary` + `stops` tool input remains supported for existing clients,
but it does not create a structured report.

This ADR supersedes ADR-0003's original walkthrough-first behavior for
`/code-eye-web`: the command now requests a quick or deep structured report
before opening the same temporary local web surface.