ADR-0016 — Review inline: el review.json como puerta humana, y el CLI como validador

• Estado: aceptado
• Fecha: 2026-07-17
• Decide: lead / arquitecto de la metodología

Contexto

dai-review dejaba un comentario al final del hilo de la PR con todos los hallazgos en una lista. El reviewer humano tenía que leer "src/checkout.ts:42 — el guard falla abierto", abrir el archivo, buscar la línea, y reconstruir el contexto a mano. Por cada hallazgo.

El review de Copilot, con todos sus defectos, hace algo mejor: deja un comentario anclado a cada archivo:línea, clasificado Low/Medium/High, más un resumen arriba. El hallazgo aparece al lado del código del que habla.

Técnicamente el gap era chico y estaba en un solo lugar: dai forge comment postea al endpoint de issues (el hilo). El review inline es otro endpoint. No hacía falta una arquitectura nueva.

Pero al abrirlo aparecieron tres problemas que sí son de diseño:

1. El modelo inventa líneas. Un LLM revisando código produce path:line que no existen en el diff con una facilidad pasmosa. El forge responde 422 sin decir cuál de los seis comentarios falló, y en GitHub el review es atómico: un hallazgo inventado tira los cinco buenos.
2. La skill posteaba sin gate (ver 0.8.2). Con un comentario suelto ya era grave. Con seis comentarios inline firmados con el token del humano —el forge los atribuye a él como usuario, sin badge de bot— pesa mucho más.
3. "Desatendido" no puede significar "sin criterio". Hacía falta una forma de que un review simple salga solo sin que eso implique postear cualquier cosa.

Decisión

1. El contrato es un archivo, y ese archivo es la puerta humana

La skill deja de componer markdown y escribe un review.json en .dai/reviews/<n>.json. El CLI lo valida y lo postea.

skill (criterio)        →  .dai/reviews/22.json  →  dai forge review (mecánico)
hallazgos + severidad      el humano lo edita        valida vs. diff, filtra, postea

Es la ADR-0002 aplicada al review: el criterio es de la skill, lo determinista es del CLI.

Por qué un archivo y no una TUI. Evaluamos hunk, que resuelve esto con una sesión interactiva en la terminal donde el humano navega los hunks y el agente le anota comentarios. Lo bueno de robar es el contrato: el agente emite un lote estructurado y la publicación es un paso aparte. Lo que no robamos es la TUI: construirla es un proyecto entero y ata el flujo a que el humano esté en tu terminal — justo lo contrario de la 0002. Un JSON es diff-eable, editable a mano, auditable, y anda igual en Claude, Copilot o Cursor.

2. El CLI valida contra el diff antes de salir a la red

dai forge review trae el diff con git (local, por SSH — no gasta rate limit ni depende de la API) y verifica que cada path:line exista de verdad en el hunk, del lado declarado. Lo que no apunta al diff no se postea.

Esto es lo que más valor tiene del comando, más que postear. Es la diferencia entre un review que entra y un 422 críptico que se lleva puestos los hallazgos buenos.

3. Nada se cae en silencio

Un hallazgo descartado o filtrado se reporta: en el preview del CLI y en un <details> del propio resumen posteado. Un tope (--max-comments) que corta en silencio se lee como "revisé todo" cuando no. Si dai suprime algo, lo dice.

4. --yes explícito; el desatendido es una excepción que se pide

Sin --yes no se postea nada, nunca: se muestra el preview y se corta. El modo desatendido existe —--yes --min-severity medium --min-confidence 0.8 --max-comments N— pero es una excepción que el humano tipea, no un default al que se llega por descuido.

confidence es lo que lo hace usable: por debajo del umbral el hallazgo no se postea y queda listado. Es el equivalente honesto del "Comments suppressed due to low confidence" de Copilot.

5. event: COMMENT, nunca APPROVE

Ni siquiera en desatendido, ni por configuración. dai comenta; la aprobación la firma un humano (Art. 5).

6. Cada comentario inline lleva marca de dai

El review sale con el token del humano, así que el forge lo atribuye a él sin badge de bot — a diferencia de Copilot, que postea vía GitHub App y muestra el badge AI. Sin una marca en el cuerpo, el compañero ve seis juicios sobre su código firmados por una persona, sin forma de saber que los escribió una máquina. Cada comentario cierra con una línea que lo dice.

Consecuencias

A favor

• El hallazgo aparece al lado del código. El reviewer humano deja de reconstruir contexto.
• El validador de posiciones convierte el error más común del LLM en un descarte legible, antes de la red.
• El review.json es auditable y editable: el humano puede bajar una severidad o borrar un hallazgo sin pelearse con un prompt.
• Sirve igual en GitHub y GitLab, y con cualquier asistente.

En contra / a asumir

• GitLab no es atómico, y no lo podemos fingir. GitHub postea resumen + N inline en un solo POST (o entra todo o no entra nada). GitLab necesita 1 nota para el resumen y N discussions separadas: si la tercera falla, las dos primeras ya están publicadas. Se mitiga validando todo antes de la primera llamada, pero cuando falla igual, el CLI reporta qué entró y qué no en vez de prometer una atomicidad que no tiene.
• GitLab exige los tres shas de diff_refs en cada comentario: getPR tuvo que dejar de descartarlos.
• Un review.json a medio editar no debe commitearse: dai init agrega .dai/reviews/ al .gitignore del repo (.dai/ sigue versionándose — ahí vive jira-fields.json).

Fuera de alcance, a propósito

• Bloques suggestion (el botón "Apply suggestion"). Son valiosos pero la sintaxis difiere entre GitHub y GitLab; el schema queda abierto para sumarlos después.
• Cuenta bot / GitHub App para que los reviews salgan marcados como IA como los de Copilot. Una cuenta bot es solo otro token en el .env (cero código); una GitHub App sí es trabajo real (JWT + installation token). Es una decisión de operación del equipo, no del CLI, y por eso no la cierra esta ADR.
• La calidad del review en sí. dai no compite en catálogos de bugs ni reglas: eso no es su dominio. Lo suyo es la trazabilidad y que el hallazgo aterrice donde sirve.