@dforce2055/dai 0.8.2 → 0.10.0

package/docs/tutoriales/claves-ssh.md

@@ -0,0 +1,93 @@
+# Claves SSH para GitHub y GitLab
+
+Guía para generar tu **clave SSH** y registrarla en GitHub y/o GitLab. En dai, **git usa
+SSH** (clonar, `push`, `pull`); los tokens son solo para el forge y el tracker, y **nunca**
+se usa la contraseña ([ADR-0007](../adr/0007-modelo-de-autenticacion.md)). Con la clave
+configurada, `dai pr` puede pushear la rama sin pedirte credenciales.
+
+> **Una vez por máquina.** La misma clave sirve para GitHub y GitLab (y para todos tus
+> repos). No necesitas una por proyecto.
+
+---
+
+## Paso 1 — ¿Ya tienes una clave?
+
+```bash
+ls ~/.ssh/id_ed25519.pub
+```
+
+Si el archivo existe, ya tienes clave: salta al **Paso 4**. Si dice *"No such file"*, sigue
+con el paso 2.
+
+---
+
+## Paso 2 — Genera la clave
+
+```bash
+ssh-keygen -t ed25519 -C "tu-correo@ejemplo.com"
+```
+
+- Usa el correo de tu cuenta de GitHub/GitLab.
+- Cuando pregunte la ubicación, acepta la default (Enter).
+- La *passphrase* es opcional pero recomendada (una contraseña que protege la clave).
+
+> Si tu sistema es viejo y no soporta `ed25519`, usa `-t rsa -b 4096`.
+
+---
+
+## Paso 3 — Carga la clave en el agente SSH
+
+```bash
+eval "$(ssh-agent -s)"        # inicia el agente
+ssh-add ~/.ssh/id_ed25519     # carga tu clave (pide la passphrase si pusiste una)
+```
+
+> **Windows:** usa **Git Bash** para estos comandos, o habilita el servicio *OpenSSH
+> Authentication Agent* de Windows.
+
+---
+
+## Paso 4 — Copia la clave **pública**
+
+Nunca compartas la privada (`id_ed25519`). Copia solo la **pública** (`.pub`):
+
+```bash
+cat ~/.ssh/id_ed25519.pub        # muestra la clave; copiala entera (empieza con "ssh-ed25519")
+# atajos: macOS → | pbcopy   ·   Windows (Git Bash) → | clip   ·   Linux → | xclip -sel clip
+```
+
+---
+
+## Paso 5 — Pégala en GitHub y/o GitLab
+
+- **GitHub:** *Settings → SSH and GPG keys → New SSH key*. Pega la clave, ponle un título
+  (ej. `laptop-trabajo`) y guarda.
+  Acceso directo: **https://github.com/settings/ssh/new**
+- **GitLab:** *Preferences → SSH Keys → Add new key*. Pega la clave y guarda. En un GitLab
+  **self-hosted/corporativo** entra por la URL de tu instancia
+  (`https://gitlab.tu-empresa.com/-/user_settings/ssh_keys`).
+
+---
+
+## Paso 6 — Prueba la conexión
+
+```bash
+ssh -T git@github.com
+# → "Hi <usuario>! You've successfully authenticated..."
+
+ssh -T git@gitlab.com
+# (self-hosted: ssh -T git@gitlab.tu-empresa.com)
+```
+
+La primera vez te pregunta si confías en el host: escribí `yes`. Si ves el saludo con tu
+usuario, quedó lista.
+
+---
+
+## Reglas de seguridad
+
+- 🔒 **La clave privada nunca sale de tu máquina.** No la pegues en ningún lado, no la
+  commitees, no la mandes por chat. Solo se registra la **pública** (`.pub`).
+- 🧯 **Si se compromete tu máquina**, borra la clave pública de GitHub/GitLab (misma
+  pantalla del paso 5) y generá una nueva.
+- 👤 Es **por máquina y por persona**: cada dev tiene la suya.

package/docs/tutoriales/configurar-git.md

@@ -0,0 +1,53 @@
+# Configurar tu identidad de git
+
+Antes de tu primer commit, git necesita saber **quién sos**: cada commit lleva un nombre y
+un correo de autor. Sin configurarlo, los commits salen con un autor vacío o incorrecto, y
+en dai la **autoría siempre es de una persona** — nunca de un bot.
+
+> **Una vez por máquina.** Con `--global` queda para todos tus repos.
+
+---
+
+## Paso 1 — Nombre y correo
+
+```bash
+git config --global user.name "Nombre Completo"
+git config --global user.email "tu-correo@ejemplo.com"
+```
+
+> **Usa el mismo correo que tu cuenta de GitHub/GitLab.** Así el forge te **atribuye** los
+> commits (aparecen con tu avatar y cuentan en tu actividad). Si el correo no coincide, los
+> commits quedan "huérfanos", sin vincularse a tu cuenta.
+
+---
+
+## Paso 2 — Verifica
+
+```bash
+git config --global user.name       # → Nombre Completo
+git config --global user.email      # → tu-correo@ejemplo.com
+git config --global --list          # ve toda la config global
+```
+
+---
+
+## Un correo distinto para un repo puntual
+
+Si en un repo específico quieres usar otra identidad (ej. trabajo vs. personal), configúralo
+**sin** `--global`, dentro de ese repo:
+
+```bash
+cd mi-repo
+git config user.email "correo-de-este-repo@ejemplo.com"
+```
+
+La config del repo **gana** sobre la global, solo ahí.
+
+---
+
+## Por qué importa en dai
+
+- **Trazabilidad de autoría:** dai ata el QUÉ al CÓMO, y el CÓMO lo firma una persona. Un
+  commit con autor mal seteado rompe esa cadena.
+- **El review sale a tu nombre:** cuando `dai-review` postea con tu token, el forge lo
+  atribuye a **ti** — tener bien tu identidad es parte de responder por lo que firmas.

package/docs/tutoriales/index.md

@@ -0,0 +1,18 @@
+# Tutoriales
+
+Guías de **setup operativo** — lo que haces una vez por máquina para trabajar con dai.
+
+## Preparar el entorno
+
+- [**Configurar git**](./configurar-git) — tu identidad (nombre + correo) para que los
+  commits te atribuyan.
+- [**Claves SSH**](./claves-ssh) — generar y registrar tu clave en GitHub / GitLab. En dai,
+  git usa SSH ([ADR-0007](../adr/0007-modelo-de-autenticacion.md)).
+- [**Instalar gh / glab**](./instalar-glab) — el CLI del forge, para que `dai pr` cree la
+  PR/MR.
+
+## Conectar el tracker
+
+- [**Token de Jira**](./token-jira) — generar tu token de API de Atlassian (`DAI_PM=jira`).
+- [**Token de ClickUp**](./token-clickup) — generar tu token personal de ClickUp
+  (`DAI_PM=clickup`).

package/docs/tutoriales/instalar-glab.md

@@ -0,0 +1,74 @@
+# Instalar el CLI del forge (`gh` / `glab`) para `dai pr`
+
+`dai pr` crea la Pull/Merge Request usando el **CLI del forge**: `gh` para GitHub, `glab`
+para GitLab. dai pushea la rama por **SSH** igual (necesitas las [claves SSH](claves-ssh)),
+pero para **crear la PR/MR** hace falta el CLI autenticado.
+
+> **Una vez por máquina.** Instalás el que use tu equipo (o los dos, si trabajás con ambos
+> forges). Sin el CLI, `dai pr` **igual pushea la rama** y te dice qué instalar — después
+> creás la PR a mano desde la web.
+
+---
+
+## GitHub → `gh`
+
+### Instalar
+
+```bash
+brew install gh                 # macOS
+winget install GitHub.cli       # Windows
+sudo apt install gh             # Debian/Ubuntu (o ver cli.github.com para tu distro)
+```
+
+### Autenticar
+
+```bash
+gh auth login
+```
+
+Elige **GitHub.com**, protocolo **SSH** (o HTTPS), y sigue los pasos. Verifica:
+
+```bash
+gh --version
+```
+
+---
+
+## GitLab → `glab`
+
+### Instalar
+
+```bash
+brew install glab               # macOS · o Linux con Homebrew
+winget install GitLab.GLab      # Windows  (alternativa: scoop install glab)
+sudo pacman -S glab             # Arch / Manjaro
+# Debian/Ubuntu y otras distros: el .deb o el binario de https://gitlab.com/gitlab-org/cli/-/releases
+```
+
+### Autenticar
+
+```bash
+# GitLab.com:
+glab auth login
+
+# GitLab self-hosted / corporativo (el --hostname es OBLIGATORIO):
+glab auth login --hostname gitlab.tu-empresa.com
+```
+
+Te va a pedir un **token con scope `api`** (lo generás en *GitLab → Preferences → Access
+Tokens*). Verifica:
+
+```bash
+glab --version
+```
+
+---
+
+## Notas
+
+- 🪟 **Windows:** después de instalar con `winget`/`scoop`, **abre una terminal nueva** para
+  que tome el PATH; si no, `glab`/`gh` "no se encuentra".
+- 🔑 **El CLI usa un token del forge** (no la contraseña, no la clave SSH). Git sigue usando
+  SSH; el CLI, token — cada uno lo suyo ([ADR-0007](../adr/0007-modelo-de-autenticacion.md)).
+- Con el CLI instalado y autenticado, `dai pr` (o `dai mr` en GitLab) crea la PR/MR
+  precargada con la US, el estado de `dai check` y los enlaces.

package/docs/tutoriales/token-clickup.md

@@ -0,0 +1,73 @@
+# Cómo obtener el token de API de ClickUp
+
+Guía paso a paso para generar tu **token de API personal de ClickUp**, necesario para que
+`dai` (o cualquier script) se autentique contra la REST API de **ClickUp** cuando el tracker
+del repo es ClickUp (`DAI_PM=clickup`).
+
+> **¿Por qué un token y no la contraseña?** ClickUp no permite autenticar la API con la
+> contraseña de la cuenta (menos aún con SSO / verificación en dos pasos). El **token
+> personal** cumple ese rol: es una credencial que representa a tu usuario y que tratas
+> **igual que una contraseña**. Empieza siempre con `pk_`.
+
+**Atajo:** si quieres saltar los pasos 1 y 2, entra directo a
+👉 **https://app.clickup.com/settings/apps** (te lleva al paso 3).
+
+---
+
+## Paso 1 — Abre la configuración de tu cuenta
+
+En ClickUp, haz clic en tu **avatar** (arriba a la derecha) y elige **Settings**
+(Configuración).
+
+![Menú del avatar → Settings](/tutoriales/clickup-1-settings.png)
+
+---
+
+## Paso 2 — Ve a "API de ClickUp"
+
+En la barra lateral de configuración, bajo tu cuenta, entra a la sección **API de ClickUp**.
+Ahí, arriba de todo, verás el bloque **API Token**.
+
+![Barra lateral de Settings → Apps](/tutoriales/clickup-2-api.png)
+
+---
+
+## Paso 3 — Genera o copia el token
+
+En **API Token**:
+
+- Si es la primera vez, haz clic en **Generate** para crearlo.
+- Si ya tenías uno, aparece oculto con un botón **Copy** (y un **Regenerate** al lado).
+
+El token empieza con `pk_` (ej. `pk_1234567_ABCDEFG…`). Haz clic en **Copy** para copiarlo.
+
+![Bloque API Token → Generate / Copy](/tutoriales/clickup-3-generate-copy.png)
+
+---
+
+## Paso 4 — Guárdalo en tu `.env.dai`
+
+Pega el token en el `.env.dai` del repo (que **no se versiona**; el `.env` del equipo no se
+toca — [ADR-0017](../adr/0017-env-dai.md)), en la variable que espera dai:
+
+```bash
+DAI_PM=clickup
+DAI_CLICKUP_TOKEN=pk_...        # ← tu token, solo el token (sin comillas ni comentarios al lado)
+# DAI_CLICKUP_LIST_ID=          # solo hace falta para `dai publish` (crear tareas)
+```
+
+Verifica con `dai doctor` → debería decir **"token de ClickUp presente"**.
+
+---
+
+## Reglas de seguridad (importante)
+
+- 🔒 **Trátalo como una contraseña.** Nunca lo pegues en el código, en un commit, en un chat
+  ni en el `implements.yaml`. Solo va en `.env.dai` (no versionado).
+- ♻️ **No vence por sí solo** (a diferencia de Jira): queda válido hasta que lo **regeneres**.
+  Regenerar crea uno nuevo e **invalida el anterior al instante** — así lo rotas y así cortas
+  el acceso de uno filtrado.
+- 👤 **Es personal:** representa a tu usuario, con tus permisos. Cada dev usa el suyo, nunca
+  uno compartido.
+- 🧯 **Si se filtra**, entra a la misma pantalla (paso 3) y haz **Regenerate** de inmediato;
+  el viejo deja de funcionar y actualizas el `.env.dai` con el nuevo.

package/docs/tutoriales/token-jira.md

@@ -0,0 +1,74 @@
+# Cómo obtener el token de API de Jira (Atlassian)
+
+Guía paso a paso para generar un **token de API de Atlassian**, necesario para que `dai`
+(o cualquier script) se autentique contra la REST API de **Jira Cloud** cuando el tracker
+del repo es Jira (`DAI_PM=jira`).
+
+> **¿Por qué un token y no la contraseña?** Jira Cloud no permite autenticar la API con la
+> contraseña de la cuenta (menos aún con SSO / verificación en dos pasos). El token cumple
+> ese rol: es una credencial revocable, con vencimiento, que tratas **igual que una
+> contraseña**.
+
+**Atajo:** si quieres saltar los pasos 1 y 2, entra directo a
+👉 **https://id.atlassian.com/manage-profile/security/api-tokens** (te lleva al paso 3).
+
+---
+
+## Paso 1 — Abre la configuración de tu cuenta
+
+En Jira, haz clic en tu **avatar** (arriba a la derecha) y elige **Configuración de la cuenta**.
+
+![Menú del avatar → Configuración de la cuenta](/tutoriales/jira-1-avatar.png)
+
+---
+
+## Paso 2 — Ve a Seguridad → Tokens de API
+
+En la barra superior, entra a la pestaña **Seguridad**. Baja hasta la sección
+**Tokens de API** y haz clic en **Crear y gestionar tokens de API**.
+
+![Pestaña Seguridad → Crear y gestionar tokens de API](/tutoriales/jira-2-seguridad-tokens.png)
+
+---
+
+## Paso 3 — Crea el token
+
+Haz clic en **Crear token de API** (el botón simple, no el de "con alcances").
+Acceso directo => https://id.atlassian.com/manage-profile/security/api-tokens
+
+![Botón Crear token de API](/tutoriales/jira-3-crear-token.png)
+
+---
+
+## Paso 4 — Nombre y vencimiento
+
+- **Name:** un nombre que describa para qué es (ej. `dai-frontend`, `dai-backend`).
+- **Caduca el:** una fecha de vencimiento. Por seguridad, Atlassian **no permite más de un
+  año**. Pon la fecha máxima si no quieres renovarlo seguido, o una más corta para rotarlo
+  antes.
+
+Haz clic en **Crear**.
+
+![Formulario: Name + fecha de caducidad](/tutoriales/jira-4-nombre-vencimiento.png)
+
+---
+
+## Paso 5 — Cópialo AHORA (no se recupera después)
+
+Atlassian te muestra el token **una sola vez**. Haz clic en **Copiar** y guárdalo en un
+lugar seguro. **Si cierras esta ventana sin copiarlo, no hay forma de recuperarlo** —
+tendrías que crear uno nuevo.
+
+![Ventana Copia tu token de API](/tutoriales/jira-5-copiar.png)
+
+---
+
+## Reglas de seguridad (importante)
+
+- 🔒 **Trátalo como una contraseña.** Nunca lo pegues en el código, en un commit, en un chat
+  ni en el `implements.yaml`. Solo va en `.env.dai`, que **no se versiona** (el `.env` del
+  equipo no se toca; ver [ADR-0017](../adr/0017-env-dai.md)).
+- ♻️ **Rótalo** periódicamente y **revoca** los que no uses (misma pantalla del paso 3, columna
+  *Acción → Revocar*).
+- ⏱️ **Vencimiento:** el token deja de funcionar en la fecha que pusiste; anota cuándo renovarlo.
+- 🧯 **Si se filtra**, revócalo de inmediato y crea uno nuevo.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforce2055/dai",
-  "version": "0.8.2",
+  "version": "0.10.0",
   "description": "Metodología de desarrollo asistido por IA — CLI de acciones deterministas (trazabilidad QUÉ↔CÓMO).",
   "repository": { "type": "git", "url": "git+https://github.com/dforce2055/dai.git" },
   "homepage": "https://dforce2055.github.io/dai/",
@@ -32,7 +32,7 @@
     "skills",
     "manifest.yaml",
     "install.sh",
-    ".env.example",
+    ".env.dai.example",
     "VERSION",
     "LICENSE",
     "README.md",
@@ -43,7 +43,13 @@
   ],
   "scripts": {
     "test": "node --test cli/test/*.test.mjs",
-    "prepublishOnly": "npm test"
+    "prepublishOnly": "npm test",
+    "docs:dev": "vitepress dev",
+    "docs:build": "vitepress build",
+    "docs:preview": "vitepress preview"
+  },
+  "devDependencies": {
+    "vitepress": "^1.6.3"
   },
   "engines": {
     "node": ">=18"

package/skills/dai-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dai-review
-description: "Revisa una Pull/Merge Request de un repo remoto (GitHub o GitLab) de forma consciente de la metodología dai, y deja un comentario estándar en español con errores y mejoras. Corre `dai check` (¿la US está atrasada?), valida el Definition of Done, hace el review de código (correctitud + calidad), compone el comentario estándar, TE LO MUESTRA Y ESPERA TU OK, y recién entonces lo postea — vía el MCP del forge si está disponible, o vía `dai forge comment` (token) si no. Nunca postea sin aprobación explícita: sale con tu nombre y tu token. Invocar como /dai-review <URL-de-la-PR o número>. Usar en el paso 6 de SCRUM-CON-IA (code review), antes de que un partner humano firme."
+description: "Revisa una Pull/Merge Request de un repo remoto (GitHub o GitLab) de forma consciente de la metodología dai y deja un REVIEW INLINE en español: un comentario de resumen más un comentario anclado a cada archivo:línea, clasificado low/medium/high. Corre `dai check` (¿la US está atrasada?), valida el Definition of Done, hace el review de código (correctitud + calidad), escribe un review.json, lo valida contra el diff con `dai forge review --dry-run` (descarta las líneas que el modelo inventó), TE MUESTRA EL PREVIEW Y ESPERA TU OK, y recién entonces postea con `dai forge review --yes`. Nunca postea sin aprobación explícita: sale con tu nombre y tu token, sin badge de bot. Hay modo desatendido para reviews simples (--yes --min-severity --min-confidence), pero se pide, no es el default. Invocar como /dai-review <URL-de-la-PR o número>. Usar en el paso 6 de SCRUM-CON-IA (code review), antes de que un partner humano firme."
 ---
 
 # dai-review — review de PR consciente de la metodología
@@ -9,16 +9,33 @@ Es el **primer pase** del paso 6 (code review). No reemplaza al partner humano:
 saca el ruido para que firme lo que importa ([Art. 5](../../docs/MANIFIESTO.md#art-5) del manifiesto). Funciona igual
 en **GitHub y GitLab**.
 
-## Las dos caras (cómo postea el comentario)
+## El reparto: tú traes el criterio, el CLI hace lo mecánico
 
-Mismo comentario estándar, dos formas de dejarlo (elige la disponible, en este orden):
+No compones markdown y lo posteas. Escribes un **`review.json`** y el CLI lo valida y lo
+postea (ADR-0002 / [ADR-0016](../../docs/adr/0016-review-inline.md)):
 
-1. **MCP del forge** — si hay un MCP de GitHub/GitLab conectado, postea por ahí.
-2. **CLI con token** — si no, `dai forge comment <ref> --body-file <archivo>`. Usa
-   `GITHUB_TOKEN`/`GITLAB_TOKEN` del `.env` (token scopeado, **nunca** contraseña).
+```
+tú (criterio)          →  .dai/reviews/<n>.json   →  dai forge review (mecánico)
+hallazgos + severidad     el humano lo edita          valida vs. el diff, filtra, postea
+```
+
+Ese archivo **es la puerta humana**: es diff-eable, editable a mano y auditable, y no ata
+el flujo a ningún asistente. No hay TUI que aprender.
+
+**Por qué el CLI y no tú directamente:** `dai forge review` verifica que cada `path:line`
+**exista de verdad en el diff** antes de salir a la red. Inventar números de línea es el
+error más común de un LLM revisando código, y el forge responde `422` sin decir cuál
+falló. El CLI lo caza antes.
 
-> **Auth:** git (traer la branch) usa **SSH**; comentar la PR usa **token del forge**
-> (comentar no se puede por SSH). Cero contraseñas.
+### Cómo postear (elige la primera disponible)
+
+1. **`dai forge review <ref> --from <archivo> --yes`** — la forma. Review inline:
+   resumen + un comentario por línea. Usa `GITHUB_TOKEN`/`GITLAB_TOKEN` del `.env`.
+2. **MCP del forge / `dai forge comment`** — fallback si no hay token, o si necesitas
+   dejar un comentario suelto sin anclar. Pierdes el inline y la validación.
+
+> **Auth:** git (traer el diff) usa **SSH**; postear usa **token del forge** (postear no
+> se puede por SSH). Cero contraseñas.
 
 ## Input
 
@@ -35,47 +52,83 @@ Mismo comentario estándar, dos formas de dejarlo (elige la disponible, en este
    - ¿existe `implements.yaml`? (si es un PR de producto, es obligatorio)
    - **Definition of Done** (`templates/definition-of-done.md`): cuenta cuántos ítems cumple.
 4. **Review de código (criterio, no mecánico):** busca
-   - 🔴 **Errores** de correctitud (bugs, casos borde, seguridad).
-   - 🟡 **Mejoras** de calidad (reuso, simplicidad, eficiencia).
-   - ✅ Lo que está **bien** (refuerza lo bueno).
-5. **Componer el comentario estándar** (ver formato abajo).
-6. **Mostrarlo y esperar el OK.** Imprimí el comentario **entero**, tal cual va a salir,
-   y preguntá: _"¿lo posteo así, lo edito, o lo descarto?"_ **Frená ahí.** Si te piden
-   cambios, aplicalos y volvé a mostrarlo. No hay atajo: sin un "sí" explícito en este
-   turno, no se postea. Un "sí" de una PR anterior no cuenta para esta.
-7. **Postear** por MCP o `dai forge comment`. Confirmar el link al comentario.
-
-## El comentario estándar
-
-Es el mismo que emite `renderReviewComment` del CLI — respeta esta forma:
-
-```markdown
-## 🤖 dai-review
-
-**US:** `ABC-482` @ v1 · `dai check`: ✅ al día
-**Definition of Done:** 4/5
+   - 🔴 **high** — errores de correctitud: bugs, casos borde, seguridad.
+   - 🟡 **medium** — riesgo real pero no roto: contratos que mienten, races, deuda que muerde.
+   - 🔵 **low** — calidad: reuso, simplicidad, nombres.
+   - ✅ Lo que está **bien** (refuerza lo bueno) → va en `good`.
+5. **Escribir el `review.json`** en `.dai/reviews/<número-de-PR>.json` (ver el schema abajo).
+   Cada hallazgo va anclado a `path` + `line` **del diff que trajiste en el paso 2** —
+   no de tu memoria del archivo.
+6. **Validar sin postear** — `dai forge review <ref> --from .dai/reviews/<n>.json --dry-run`.
+   Te dice qué se postea, qué se filtra y qué se **descarta por no apuntar al diff**. Si
+   hay descartados, corregí el `path`/`line` y repetí. **No pases al paso 7 con descartados
+   que puedas arreglar.**
+7. **Mostrarlo y esperar el OK.** Mostrá el preview **entero** y preguntá: _"¿lo posteo
+   así, lo edito, o lo descarto?"_ **Frená ahí.** Si te piden cambios (bajar una severidad,
+   borrar un hallazgo, reescribir un texto), editás el JSON y volvés a mostrarlo. Sin un
+   "sí" explícito **en este turno**, no se postea. Un "sí" de una PR anterior no cuenta.
+8. **Postear** — `dai forge review <ref> --from .dai/reviews/<n>.json --yes`. Confirmá el link.
+
+## El `review.json`
+
+```json
+{
+  "us": "ABC-482",
+  "version": "v1",
+  "checkStatus": "✅ al día",
+  "dod": "4/5",
+  "summary": "Prosa breve: el juicio general del PR. Es el cuerpo del review.",
+  "good": ["Algo real y específico que está bien."],
+  "findings": [
+    {
+      "path": "src/checkout.ts",
+      "line": 42,
+      "side": "RIGHT",
+      "severity": "high",
+      "confidence": 0.9,
+      "body": "El hallazgo, en prosa. Qué está mal, por qué, y qué harías."
+    }
+  ]
+}
+```
 
-### 🔴 Errores (correctitud)
-- <hallazgo concreto con archivo:línea>
+| campo | obligatorio | qué |
+|---|---|---|
+| `path` | sí | ruta **relativa a la raíz del repo**, tal cual sale en el diff |
+| `line` | sí | línea **del lado que declares**; tiene que ser parte del diff |
+| `side` | no (`RIGHT`) | `RIGHT` = archivo nuevo · `LEFT` = línea borrada |
+| `severity` | sí | `low` \| `medium` \| `high` |
+| `confidence` | no (`1`) | 0–1. **Sé honesto**: por debajo de `--min-confidence` el hallazgo no se postea y queda listado como suprimido. Es lo que hace usable el modo desatendido. |
+| `body` | sí | el hallazgo, en prosa. Sin `**High**` ni emoji: lo pone el CLI. |
 
-### 🟡 Mejoras (calidad, reuso, simplicidad)
-- <sugerencia concreta>
+## Modo desatendido
 
-### ✅ Lo que está bien
-- <algo real y específico>
+Para reviews simples que no necesitan supervisión, el humano puede pedirlo explícito:
 
----
-_Revisión asistida por dai. La aprobación la firma un humano (Art. 5 del manifiesto)._
+```bash
+dai forge review <ref> --from <archivo> --yes --min-severity medium --min-confidence 0.8 --max-comments 10
 ```
 
-## Tres cortes duros
+Es una **excepción que se pide**, no el default. Sin `--yes` no se postea nada, nunca.
+Y el `--yes` lo tipea el humano: la skill no lo agrega por su cuenta.
+
+## Cuatro cortes duros
 
 1. **No aprobar.** La skill **comenta**, no firma la aprobación. Eso es de un humano.
-2. **No postear sin OK.** El comentario sale **con el token del humano y con su nombre**
-   (`GITHUB_TOKEN`/`GITLAB_TOKEN` son suyos): en la PR de un compañero figura como si lo
-   hubiera escrito él. Publicar un juicio sobre el código de otro, firmado por alguien
-   que no lo leyó, es tan grave como aprobar sin mirar. El paso 6 no es opcional.
-3. **Hallazgos concretos.** Nada de "mejorar la calidad" en abstracto: archivo, línea,
+   `dai forge review` postea siempre con `event: COMMENT`, nunca `APPROVE` — ni siquiera
+   en desatendido. No es configurable.
+2. **No postear sin OK.** El review sale **con el token del humano y con su nombre**
+   (`GITHUB_TOKEN`/`GITLAB_TOKEN` son suyos): el forge lo atribuye a él como usuario, sin
+   badge de bot, así que en la PR de un compañero es indistinguible de haberlo escrito a
+   mano. Publicar un juicio sobre el código de otro, firmado por alguien que no lo leyó,
+   es tan grave como aprobar sin mirar. **El paso 7 no es opcional**, y pesa más que
+   antes: un review con 6 comentarios inline firmados por alguien es mucho más que un
+   comentario suelto.
+3. **Las líneas se sacan del diff, no de la memoria.** Inventar un `path:line` es el
+   error más común de un LLM revisando código. El CLI lo caza y lo descarta, pero un
+   hallazgo descartado es un hallazgo perdido: si el paso 6 marca descartes, **arreglalos**
+   en vez de postear igual.
+4. **Hallazgos concretos.** Nada de "mejorar la calidad" en abstracto: archivo, línea,
    y el porqué. Si no es accionable, no va.
 
 > **Por qué el corte 2 existe:** esta skill posteaba directo. El Art. 5 estaba bien
@@ -87,4 +140,5 @@ _Revisión asistida por dai. La aprobación la firma un humano (Art. 5 del manif
 - Es el paso 6 de [`SCRUM-CON-IA.md`](../../docs/SCRUM-CON-IA.md).
 - Se apoya en `dai check` (ADR-0003) y en el forge adapter (`dai forge`, ADR-0002:
   lo mecánico en el CLI, la inteligencia en la skill).
-- El comentario estándar hace que todos los reviews del equipo se lean igual.
+- El review inline y el contrato del `review.json`: [ADR-0016](../../docs/adr/0016-review-inline.md).
+- El formato estándar hace que todos los reviews del equipo se lean igual.