@dforce2055/dai 0.8.1 → 0.9.0

package/.env.example

@@ -6,8 +6,11 @@
 # md | jira | clickup
 DAI_PM=md
 
-# Plantilla del link al ticket (para `dai ls` / stamp). {id} se reemplaza.
-DAI_TRACKER_URL_TEMPLATE=https://jira.miempresa.com/browse/{id}
+# OPCIONAL. Plantilla del link al ticket (`dai ls`, `dai pr`, stamp). {id} se reemplaza.
+# Con DAI_PM=jira o =clickup, dai ya deduce el link solo: esto es un OVERRIDE, y solo
+# hace falta si tu tracker vive en otra URL (p. ej. un Jira Server con path propio).
+# Si dai no puede saber el link, avisa y deja la PR sin él — nunca escribe el id pelado.
+# DAI_TRACKER_URL_TEMPLATE=https://jira.miempresa.com/browse/{id}
 
 # ── Backend md (local, offline) ──────────────────────────────────────────────
 # Carpeta donde viven las US como <ID>.md (p. ej. ABC-482.md).

package/CHANGELOG.md

@@ -3,6 +3,85 @@
 Formato basado en [Keep a Changelog](https://keepachangelog.com/). Versionado semver
 (ver `VERSION`).
 
+## [0.9.0] — 2026-07-17
+
+**El review de dai deja de ser un comentario al final del hilo y pasa a ser un review
+_inline_: un resumen más un comentario anclado a cada `archivo:línea`, clasificado
+low/medium/high — como el de Copilot, pero con la puerta humana y la validación que a
+Copilot le faltan.**
+
+### Agregado
+- **`dai forge review <ref> --from <review.json>`** — review inline en GitHub y GitLab.
+  La skill `dai-review` produce un `review.json` (el criterio); el CLI hace lo mecánico
+  (ADR-0002): **valida que cada `path:line` exista de verdad en el diff** —traído con git,
+  local, por SSH— antes de salir a la red. Inventar líneas es el error más común de un
+  LLM revisando código, y el forge responde `422` sin decir cuál falló; en GitHub, que es
+  atómico, un hallazgo inventado tira los buenos. Lo descartado y lo filtrado **se
+  reportan**, nunca se caen en silencio.
+- **Puerta humana explícita.** Sin `--yes` no se postea nada: se muestra el preview y se
+  corta. `--dry-run` valida sin postear. Modo desatendido para reviews simples
+  (`--yes --min-severity --min-confidence --max-comments`), pero es una **excepción que
+  el humano pide**, no un default. El review sale siempre con `event: COMMENT`, nunca
+  `APPROVE` — dai comenta, la persona firma ([Art. 5](docs/MANIFIESTO.md#art-5)).
+- **Aviso de release en Discord.** Publicar un release de GitHub dispara el workflow
+  `discord-release.yml`, que postea al canal vía el secreto `DISCORD_WEBHOOK_URL`. El
+  secreto vive en GitHub Actions, nunca en el repo; el workflow no viaja en el paquete
+  npm (`.github/` fuera de `files`), así que no le impone notificaciones a nadie que use
+  dai. Ver [ADR-0016](docs/adr/0016-review-inline.md).
+
+### Cambiado
+- **`getPR` expone `headSha`, `baseRef` y `diffRefs`** — hacían falta para anclar un
+  comentario inline (GitHub necesita el sha del head; GitLab exige los tres shas de
+  `diff_refs` en cada comentario). `dai init` agrega `.dai/reviews/` al `.gitignore` del
+  repo (un review a medio editar no se commitea; `.dai/` sigue versionándose).
+
+### Interno
+- **224 tests** (+40): el parser de diff con varios hunks y archivos borrados, el
+  descarte de líneas inventadas por lado, los filtros de severidad/confianza/tope, y la
+  asimetría GitHub (atómico) vs. GitLab (no atómico: reporta los parciales en vez de
+  fingir atomicidad). Probado end-to-end contra una PR real: el comentario quedó inline
+  en el archivo, el review salió `COMMENTED`, y el hallazgo alucinado nunca tocó la red.
+
+## [0.8.2] — 2026-07-17
+
+**Dos agujeros que destapó el uso real, y que tienen la misma forma: dai hacía algo
+hacia afuera sin que un humano lo viera, o dejaba que otro le pisara lo que había
+escrito. El [Art. 5](docs/MANIFIESTO.md#art-5) no se cumple solo con no clickear
+Approve.**
+
+### Arreglado
+- **`dai-review` posteaba el comentario sin mostrártelo.** La skill componía el review y
+  lo publicaba de una: el paso 6 decía *"Postear"* y no había gate. Y el comentario sale
+  con **tu token y tu nombre** (`GITHUB_TOKEN`/`GITLAB_TOKEN` son tuyos), así que en la
+  PR de un compañero figura como si lo hubieras escrito vos. El corte estaba puesto en el
+  lugar equivocado: no aprobar sin humano estaba bien, pero publicar un juicio sobre el
+  código de otro, firmado por alguien que no lo leyó, es el mismo problema con otro
+  disfraz. Ahora la skill **muestra el comentario entero y espera un OK explícito** en
+  ese turno; sin "sí", no se postea. Es el tercer corte duro de la skill.
+- **`dai pr` escribía el id de la US disfrazado de link.** Sin `DAI_TRACKER_URL_TEMPLATE`,
+  `trackerUrl(id)` devolvía el **id pelado**; como un string es truthy, `composePrBody` lo
+  escribía igual y la PR quedaba con `- US: 86abc123` en vez de un enlace, sin un solo
+  aviso. Ahora la URL se resuelve por una cadena explícita —template > URL canónica del
+  tracker > derivada del backend > `null`— y **si dai no la sabe, avisa y omite la línea
+  en vez de mentir** (`lib/tracker-url.mjs`).
+- **El bloque de enlaces de `dai pr` no sobrevivía a un edit.** Iba marcado con un
+  comentario suelto, así que cualquier agente que reescribiera *"Enlaces relacionados"*
+  se lo llevaba puesto sin dejar rastro — pasó en PRs reales. Y el propio template lo
+  invitaba: su hint pedía *"US en el tracker, commit ancla, docs, issues"*, o sea justo la
+  sección que `dai pr` acababa de llenar. dai se peleaba consigo mismo y ganaba el que
+  corría último. Ahora el bloque va **delimitado** (`<!-- dai:links:start … end -->`),
+  se **regenera de forma idempotente**, preserva lo que el humano sumó abajo, y el hint
+  del template pide solo lo que dai **no** sabe (docs, issues, PRs relacionadas).
+
+### Cambiado
+- **dai deduce el link al tracker solo.** Con `DAI_PM=jira` o `=clickup` ya no hace falta
+  `DAI_TRACKER_URL_TEMPLATE`: se deriva de la config (`/browse/<KEY>` y
+  `/t/<id>`), y `fetchUS` ahora devuelve la **URL canónica** del tracker — en ClickUp, la
+  que trae el `team_id`, que no se puede deducir del id. La variable queda como
+  **override** para trackers con URL propia. `dai init` dejó de scaffoldearla: era
+  contraproducente, porque el template gana sobre la canónica y le tapaba el `team_id`.
+  Los `.env` que ya la tienen siguen andando igual (el override sigue ganando).
+
 ## [0.8.1] — 2026-07-16
 
 **Primera prueba real en Windows con analistas y devs de una empresa: el ciclo completo
@@ -326,6 +405,9 @@ ClickUp y Jira Cloud.
 - Tests de las rutas de red (jira/clickup/forge) con `fetch` mockeado. Sin links rotos;
   `files` de npm sin tests ni secretos.
 
+[0.9.0]: https://github.com/dforce2055/dai/releases/tag/v0.9.0
+[0.8.2]: https://github.com/dforce2055/dai/releases/tag/v0.8.2
+[0.8.1]: https://github.com/dforce2055/dai/releases/tag/v0.8.1
 [0.8.0]: https://github.com/dforce2055/dai/releases/tag/v0.8.0
 [0.7.0]: https://github.com/dforce2055/dai/releases/tag/v0.7.0
 [0.6.0]: https://github.com/dforce2055/dai/releases/tag/v0.6.0

package/README.md

@@ -106,7 +106,7 @@ dai check                       # ¿tu código sigue al día con la US?  ✅ /
 dai pr --assignee <compañero>   # crea la PR precargada y se la asigna a un compañero
 ```
 ```text
-/dai-review <PR>                # tu compañero deja un review estándar; un humano aprueba
+/dai-review <PR>                # tu compañero deja un review inline (comentario por línea); un humano aprueba
 ```
 ```bash
 dai stamp                       # al mergear: estampa la cobertura en el tracker
@@ -164,7 +164,7 @@ flowchart TD
 | 9 | **Code review propio** | revisas tu implementación (correctitud + calidad) antes de la PR | dev |
 | 10 | **Smoke test** | pides al agente un smoke local del flujo | dev + IA |
 | 11 | **Crear la PR** | `dai pr` → pregunta la branch base, arma el texto, lo muestra, confirma, pushea y crea la PR/MR | dev |
-| 12 | **Review de un partner** | skill `/dai-review <PR>` deja un comentario estándar; un humano aprueba | partner |
+| 12 | **Review de un partner** | skill `/dai-review <PR>` deja un **review inline** (resumen + un comentario por línea, low/medium/high); te muestra el preview y **espera tu OK** antes de postear; un humano aprueba | partner |
 | 13 | **Merge + estampar** | al mergear: `dai stamp` → cobertura inversa en el tracker | dev / CI |
 | 14 | **Cerrar la US** | `dai done` → vuelve a la base, actualiza y borra la branch local (si está mergeada) | dev |
 
@@ -195,7 +195,8 @@ flowchart TD
 | `dai stamp` | estampa la cobertura inversa en el tracker (branch + commit-ancla) |
 | `dai done [--base main] [--force]` | cierra la US: vuelve a la base, `fetch --prune` + `pull`, y borra la branch local **si está mergeada** (chequeo estricto; `--force` la borra igual). Redes: no estar en la base, sin cambios sueltos, sin commits sin pushear |
 | `dai archive [<change>] [--skip-specs]` | **funde los delta specs del change en las specs canónicas** (`openspec/specs/`) y lo archiva. Lo corre el **aprobador** de la PR (gate de aprobación, [ADR-0011](docs/adr/0011-archive-gate-de-aprobacion.md)); detecta el change activo o le pasás el nombre. Envuelve `openspec archive` |
-| `dai forge comment <ref> --body-file <f>` · `dai forge pr <ref>` | comentar / leer una PR/MR (GitHub/GitLab) |
+| `dai forge review <ref> --from <review.json>` `[--dry-run\|--yes]` | **review inline**: un resumen + un comentario anclado a cada `archivo:línea`, clasificado low/medium/high. **Valida cada posición contra el diff** (descarta lo que el modelo inventó) antes de postear; sin `--yes` muestra el preview y no postea nada. Modo desatendido: `--min-severity`/`--min-confidence`/`--max-comments`. El review sale con `event: COMMENT`, nunca `APPROVE` ([ADR-0016](docs/adr/0016-review-inline.md)) |
+| `dai forge comment <ref> --body-file <f>` · `dai forge pr <ref>` | comentar / leer una PR/MR (GitHub/GitLab) — el fallback simple, sin anclar |
 | `dai ac-hash <us.md>` | calcula el hash de los criterios de aceptación de una US |
 | `dai doctor` · `dai docs <dest>` · `dai version` | diagnóstico del entorno (incluye **version-drift** del scaffold) · copiar la doc · versión (`dai version` avisa si tu repo quedó atrás) |
 
@@ -328,7 +329,7 @@ Además: [`docs/glosario.md`](docs/glosario.md) · guías por rol ([`po`](docs/g
 dai/
 ├── cli/            🖥️  el binario `dai` (Node, cero dependencias) + su suite de tests
 ├── docs/           📖  la metodología: MANIFIESTO · METODOLOGIA · SCRUM-CON-IA · EJEMPLO ·
-│                       glosario · guias/ · detalle/ (10 pasos) · adr/ (0001–0009)
+│                       glosario · guias/ · detalle/ (10 pasos) · adr/ (0001–0016)
 ├── templates/      🧩  los moldes (formato-us · epica · DoR · DoD · adr · pull-request)
 ├── skills/         🤖  doc-to-backlog · grill-intent · grill-epic · grill-user-story · link-us · tdd · dai-review
 ├── governance/     🛡️  branch-naming · ci-rules · commit-convention

package/VERSION

@@ -1 +1 @@
-0.8.1
+0.9.0

package/cli/dai.mjs

@@ -24,7 +24,9 @@ import { isValidKey, slugify, branchName, extractTitle, renderImplementsYaml } f
 import { loadEnv } from "./lib/env.mjs";
 import { getAdapter, coverageStatus, statusLabel } from "./lib/pm-adapter.mjs";
 import { branchUrl, commitUrl, parseRemote, detectForge } from "./lib/forge-url.mjs";
-import { parsePrRef, getPR, postComment } from "./lib/forge-api.mjs";
+import { parsePrRef, getPR, postComment, postReview } from "./lib/forge-api.mjs";
+import { trackerUrl } from "./lib/tracker-url.mjs";
+import { parseFindings, diffPositions, validateFindings, filterFindings, renderFindingBody, renderReviewSummary } from "./lib/review-findings.mjs";
 import { composePrBody, prTitle, forgeTool } from "./lib/pr.mjs";
 import { dirsEqual } from "./lib/fsutil.mjs";
 import { parseFlags, parseAssistants, isAssistantToken, asList } from "./lib/args.mjs";
@@ -66,10 +68,9 @@ function runNpmTool(name, args, opts = {}) {
   const win = process.platform === "win32";
   return execFileSync(win ? `${name}.cmd` : name, args, { shell: win, ...opts });
 }
-function trackerUrl(id) {
-  const tpl = process.env.DAI_TRACKER_URL_TEMPLATE;
-  return tpl ? tpl.replace("{id}", id) : id;
-}
+// La URL de la US: template > canónica del tracker > derivada del backend > null.
+// Nunca el id pelado: ver el porqué en lib/tracker-url.mjs.
+const usUrlFor = (id, liveUrl = null) => trackerUrl(id, { env: process.env, liveUrl });
 
 // ── ac-hash ─────────────────────────────────────────────────────────────────
 function cmdAcHash(arg) {
@@ -88,7 +89,7 @@ function cmdLs(opts) {
     for (const im of f.implements || []) {
       if (isPlaceholderId(im.id)) continue;   // saltea plantillas sin completar
       rows.push({ change: f.change, repo: f.repo, id: im.id, version: im.version,
-                  ac_hash: im.ac_hash, link: trackerUrl(im.id) });
+                  ac_hash: im.ac_hash, link: usUrlFor(im.id) });
     }
   }
   if (opts.json) { process.stdout.write(JSON.stringify(rows, null, 2) + "\n"); return; }
@@ -242,9 +243,80 @@ async function cmdForge(sub, ref, opts) {
     if (!body) fail("falta --body-file <archivo> o --body <texto>.", 1);
     const res = await postComment(pr, body, process.env);
     process.stdout.write(`✓ comentario posteado${res.url ? `: ${res.url}` : ""}\n`);
+  } else if (sub === "review") {
+    await cmdForgeReview(pr, opts);
   } else {
-    fail("uso: dai forge <pr|comment> <ref> [--body-file f | --body t]", 1);
+    fail("uso: dai forge <pr|comment|review> <ref> [--body-file f | --body t | --from review.json]", 1);
+  }
+}
+
+// dai forge review <ref> --from review.json [--dry-run | --yes]
+//
+// El reparto del ADR-0002 en una función: la skill trajo el CRITERIO (el review.json),
+// el CLI hace lo MECÁNICO — validar que cada hallazgo apunte al diff de verdad, filtrar,
+// y postear. Lo que más valor tiene acá no es postear: es RECHAZAR lo que un LLM inventó
+// antes de que el forge conteste 422 sin decir cuál falló.
+async function cmdForgeReview(pr, opts) {
+  if (!opts.from) fail("falta --from <review.json>. Lo escribe la skill dai-review; revisalo antes de postear.", 1);
+  const review = parseFindings(readFileSync(opts.from, "utf8"));
+
+  // El diff sale de git (local, por SSH), no de la API: es la fuente de verdad de qué
+  // línea es comentable, y no gasta rate limit.
+  const remote = await Promise.resolve(getPR(pr, process.env)).catch(() => null);
+  if (!remote) fail("no pude leer la PR/MR del forge (¿token? ¿ref correcta?).", 1);
+  const base = opts.base || remote.baseRef;
+  if (!base) fail("no pude saber la branch base de la PR. Pasala con --base <branch>.", 1);
+  let diff = "";
+  try {
+    git(["fetch", "origin", base, remote.branch], { stdio: ["inherit", "pipe", "pipe"] });
+    diff = git(["diff", `origin/${base}...origin/${remote.branch}`]);
+  } catch (e) {
+    const err = String(e.stderr || e.message).trim();
+    if (/couldn't find remote ref|no such ref/i.test(err)) {
+      fail(`la branch '${remote.branch}' ya no está en origin (¿la PR se mergeó y se borró la branch?). ` +
+        `Un review inline necesita el diff vivo; sobre una PR cerrada no hay dónde anclar.`, 1);
+    }
+    fail(`no pude traer el diff de ${base}...${remote.branch}: ${err}`, 1);
+  }
+
+  // 1. Validar contra el diff. 2. Filtrar. Nada se cae en silencio: todo se reporta.
+  const { valid, rejected } = validateFindings(review.findings, diffPositions(diff));
+  const { kept, suppressed } = filterFindings(valid, {
+    minSeverity: opts.minSeverity || "low",
+    minConfidence: opts.minConfidence ? Number(opts.minConfidence) : 0,
+    maxComments: opts.maxComments ? Number(opts.maxComments) : Infinity,
+  });
+
+  const body = renderReviewSummary(review, { kept, suppressed, rejected });
+  const comments = kept.map((f) => ({ path: f.path, line: f.line, side: f.side, body: renderFindingBody(f) }));
+
+  // ── Preview (acción hacia afuera: se muestra SIEMPRE, se postea solo con --yes) ──
+  process.stdout.write(`\n  ── Review a postear en ${remote.url || `#${pr.number}`} ──────────\n`);
+  process.stdout.write(`  forge:    ${pr.forge}${pr.forge === "gitlab" ? " (no atómico: son N llamadas)" : " (atómico: 1 llamada)"}\n`);
+  process.stdout.write(`  diff:     ${base}...${remote.branch}\n`);
+  process.stdout.write(`  hallazgos: ${review.findings.length} en el archivo · ${kept.length} a postear · ${suppressed.length} filtrados · ${rejected.length} descartados\n\n`);
+  for (const f of kept) process.stdout.write(`  ✓ ${f.path}:${f.line} [${f.severity}] ${f.body.split("\n")[0].slice(0, 60)}\n`);
+  for (const { finding: f, reason } of suppressed) process.stdout.write(`  ~ ${f.path}:${f.line} [${f.severity}] filtrado — ${reason}\n`);
+  for (const { finding: f, reason } of rejected) process.stdout.write(`  ✗ ${f.path}:${f.line} [${f.severity}] DESCARTADO — ${reason}\n`);
+  process.stdout.write(`\n  ───────────────────────────────────────────────\n${body}\n  ───────────────────────────────────────────────\n`);
+
+  if (rejected.length) {
+    warn(`${rejected.length} hallazgo(s) NO apuntan al diff y no se postean. Corregí el 'path'/'line' en ${opts.from} o borralos.`);
   }
+  if (opts.dryRun) { info("[dry-run] no se posteó nada."); return; }
+  if (!opts.yes) {
+    info(`Nada posteado. Revisá el preview y, si está bien:  dai forge review ${pr.number} --from ${opts.from} --yes`);
+    return;
+  }
+  if (!kept.length && !review.summary) fail("no hay nada que postear (0 comentarios y resumen vacío).", 1);
+
+  const res = await postReview(pr, { body, comments, headSha: remote.headSha, diffRefs: remote.diffRefs }, process.env);
+  ok(`review posteado${res.url ? `: ${res.url}` : ""} — ${res.posted} comentario(s) en línea.`);
+  if (res.failed.length) {
+    warn(`${res.failed.length} comentario(s) NO entraron (gitlab no es atómico: el resumen y el resto SÍ están posteados):`);
+    for (const f of res.failed) process.stdout.write(`    ✗ ${f.path}:${f.line} — ${f.error}\n`);
+  }
+  info("La aprobación la firma un humano: dai comentó, no aprobó (Art. 5).");
 }
 
 // ── publish: crea la US en el tracker desde un .md (fallback del MCP) ──────────
@@ -394,8 +466,14 @@ async function cmdPr(opts) {
   // Commits de la branch (para precargar "Cambios realizados").
   let commits = [];
   try { commits = git(["log", `${base}..HEAD`, "--pretty=%s"]).split("\n").filter(Boolean); } catch { /* base local ausente */ }
+  // La canónica del tracker (live.url) gana sobre la derivada; el template gana sobre todo.
+  const usUrl = usUrlFor(id, live?.url);
+  if (!usUrl) {
+    warn(`no sé la URL de ${id} en el tracker: la PR va a quedar sin link a la US.`);
+    warn(`configurá DAI_TRACKER_URL_TEMPLATE en el .env (p. ej. https://tu-tracker/browse/{id}).`);
+  }
   const body = composePrBody(readFileSync(tplPath, "utf8"), {
-    id, version, ac_hash, status, usUrl: trackerUrl(id), usTitle: live?.title, commits,
+    id, version, ac_hash, status, usUrl, usTitle: live?.title, commits,
     branch, branchUrl: branchUrl(remote, branch), commit, commitUrl: commitUrl(remote, commit),
   });
   const title = prTitle(opts, id, live?.title);
@@ -1154,7 +1232,10 @@ switch (cmd) {
       "  done [--base main] [--force] cierra la US: vuelve a la base, actualiza y borra la branch local (si está mergeada)\n" +
       "  archive [<change>] [--skip-specs]   funde los delta specs del change en las specs canónicas y lo archiva (lo corre el aprobador en la PR)\n" +
       "  pr (alias mr) [--assignee u] [--base b] [--draft] [--yes]   crea TU PR/MR precargada (muestra + confirma)\n" +
-      "  forge comment <ref> --body-file <f> · forge pr <ref>   comentar/leer una PR ajena (github/gitlab)\n\n" +
+      "  forge comment <ref> --body-file <f> · forge pr <ref>   comentar/leer una PR ajena (github/gitlab)\n" +
+      "  forge review <ref> --from <review.json> [--dry-run|--yes]  review inline: resumen + comentario por línea\n" +
+      "      --min-severity low|medium|high · --min-confidence 0..1 · --max-comments N · --base <branch>\n" +
+      "      Sin --yes no postea nada: muestra el preview y valida que cada hallazgo apunte al diff.\n\n" +
       "Instalación:\n" +
       "  skills install [--global | --local <repo>] [--force] [--dry-run] [--for <asistentes>]   instala las skills de dai (alias: `install`)\n" +
       "  skills install --from <git-url|path>[#ref] [--for <asistentes>]   instala skills EXTERNAS (por-stack), convertidas para los 3 asistentes (ADR-0013)\n" +

package/cli/lib/bootstrap.mjs

@@ -92,10 +92,15 @@ export function skillToCursor(md) {
 }
 
 // Contenido del .env según el backend de PM elegido (tokens vacíos, a completar).
+//
+// Sin DAI_TRACKER_URL_TEMPLATE a propósito: con jira/clickup, dai deduce el link solo
+// (lib/tracker-url.mjs). Scaffoldearlo era peor que no ponerlo — el template GANA sobre
+// la URL canónica que devuelve el tracker, así que el `/t/{id}` que escribíamos acá
+// tapaba la de ClickUp con team_id. Queda como override manual para trackers raros.
 export function envFor(pm) {
   const head = "# Config de dai — completá lo que falte. NUNCA commitees tokens (.env está gitignored).\n";
   if (pm === "clickup") {
-    return head + "DAI_PM=clickup\nDAI_CLICKUP_TOKEN=\nDAI_CLICKUP_LIST_ID=\nDAI_TRACKER_URL_TEMPLATE=https://app.clickup.com/t/{id}\n";
+    return head + "DAI_PM=clickup\nDAI_CLICKUP_TOKEN=\nDAI_CLICKUP_LIST_ID=\n";
   }
   if (pm === "jira") {
     return head +
@@ -107,8 +112,7 @@ export function envFor(pm) {
       "DAI_JIRA_PROJECT=\n" +
       "DAI_JIRA_ISSUETYPE=Story\n" +
       "# Campos propios que tu Jira exige al crear. Si el archivo no existe, se ignora.\n" +
-      "DAI_JIRA_FIELDS_FILE=.dai/jira-fields.json\n" +
-      "DAI_TRACKER_URL_TEMPLATE=\n";
+      "DAI_JIRA_FIELDS_FILE=.dai/jira-fields.json\n";
   }
   return head + "DAI_PM=md\nDAI_MD_US_DIR=.dai/us\n";
 }
@@ -149,7 +153,10 @@ export function upsertBlock(existing, block, marker = "dai") {
 export function reconcileGitignore(text, want) {
   const norm = (s) => { let t = s.trim(); while (t.startsWith("/")) { t = t.slice(1); } while (t.endsWith("/")) { t = t.slice(0, -1); } return t; };
   const broad = new Set();
-  const ensure = [".env"];
+  // `.dai/` NO va acá: ahí vive config que SÍ se versiona (jira-fields.json). Solo se
+  // ignora `.dai/reviews/`, que son borradores de `dai forge review` — efímeros, con
+  // hallazgos a medio editar, y no tienen por qué viajar en un commit.
+  const ensure = [".env", ".dai/reviews/"];
   if (want.claude) { broad.add("CLAUDE.md"); broad.add(".claude"); ensure.push(".claude/settings.local.json"); }
   if (want.cursor) { broad.add(".cursor"); }
   let changed = false;

package/cli/lib/forge-api.mjs

@@ -40,6 +40,38 @@ export function commentApiUrl(ref) {
   return `${apiBase(ref)}/projects/${encodeURIComponent(ref.projectPath)}/merge_requests/${ref.number}/notes`;
 }
 
+// El endpoint del review INLINE (resumen + comentarios anclados a archivo:línea).
+// Distinto de commentApiUrl, que postea al hilo de la PR: por eso el comentario de dai
+// caía al final en vez de dentro del archivo.
+//   github → 1 POST con todo (atómico)
+//   gitlab → 1 nota (resumen) + 1 discussion por comentario (NO atómico)
+export function reviewApiUrl(ref) {
+  if (ref.forge === "github") return `${apiBase(ref)}/repos/${ref.owner}/${ref.repo}/pulls/${ref.number}/reviews`;
+  if (ref.forge === "gitlab") return `${apiBase(ref)}/projects/${encodeURIComponent(ref.projectPath)}/merge_requests/${ref.number}/discussions`;
+  throw new Error(`forge no soportado para review: ${ref.forge} (solo github/gitlab)`);
+}
+
+// La posición de un comentario inline según el forge.
+//   github → { path, line, side, body }
+//   gitlab → position con los TRES shas de diff_refs + new_line/old_line según el lado
+export function inlinePosition(ref, c, { diffRefs } = {}) {
+  if (ref.forge === "github") return { path: c.path, line: c.line, side: c.side || "RIGHT", body: c.body };
+  if (!diffRefs?.base_sha || !diffRefs?.head_sha) {
+    throw new Error("gitlab: faltan los diff_refs de la MR (base_sha/head_sha). Sin eso no se puede anclar un comentario.");
+  }
+  const position = {
+    base_sha: diffRefs.base_sha,
+    start_sha: diffRefs.start_sha || diffRefs.base_sha,
+    head_sha: diffRefs.head_sha,
+    position_type: "text",
+    new_path: c.path,
+    old_path: c.path,
+  };
+  if ((c.side || "RIGHT") === "LEFT") position.old_line = c.line;
+  else position.new_line = c.line;
+  return { body: c.body, position };
+}
+
 export function authHeaders(ref, env = process.env) {
   if (ref.forge === "github") {
     return { Authorization: `Bearer ${env.GITHUB_TOKEN || ""}`, Accept: "application/vnd.github+json", "User-Agent": "dai" };
@@ -75,13 +107,18 @@ export function renderReviewComment(r) {
 }
 
 // ── Efectos de red (testeados con fetch mockeado en cli/test) ────────────────
+// `baseRef`/`headSha`/`diffRefs` son lo que hace falta para ANCLAR un comentario inline:
+// GitHub necesita el sha del head; GitLab exige los tres shas de `diff_refs` en cada
+// discussion. Sin esto no se puede postear un review inline.
 export async function getPR(ref, env = process.env) {
   const res = await fetch(prApiUrl(ref), { headers: authHeaders(ref, env) });
   if (!res.ok) throw new Error(`forge ${res.status}: ${await res.text()}`);
   const j = await res.json();
   return ref.forge === "github"
-    ? { title: j.title, state: j.state, body: j.body, branch: j.head?.ref, url: j.html_url }
-    : { title: j.title, state: j.state, body: j.description, branch: j.source_branch, url: j.web_url };
+    ? { title: j.title, state: j.state, body: j.body, branch: j.head?.ref, url: j.html_url,
+        baseRef: j.base?.ref ?? null, headSha: j.head?.sha ?? null, diffRefs: null }
+    : { title: j.title, state: j.state, body: j.description, branch: j.source_branch, url: j.web_url,
+        baseRef: j.target_branch ?? null, headSha: j.diff_refs?.head_sha ?? null, diffRefs: j.diff_refs ?? null };
 }
 
 export async function postComment(ref, body, env = process.env) {
@@ -94,3 +131,53 @@ export async function postComment(ref, body, env = process.env) {
   const j = await res.json();
   return { url: j.html_url || j.web_url || null };
 }
+
+// ── Review inline ────────────────────────────────────────────────────────────
+// `comments` viene con el body YA renderizado (el render vive en review-findings.mjs;
+// acá solo se arma el payload y se postea).
+//
+// event: "COMMENT", NUNCA "APPROVE" — dai comenta, el humano firma (Art. 5). No es un
+// default configurable: es un corte duro.
+export async function postReview(ref, { body, comments = [], headSha = null, diffRefs = null }, env = process.env) {
+  if (ref.forge === "github") return postReviewGithub(ref, { body, comments, headSha }, env);
+  if (ref.forge === "gitlab") return postReviewGitlab(ref, { body, comments, diffRefs }, env);
+  throw new Error(`forge no soportado para review: ${ref.forge} (solo github/gitlab)`);
+}
+
+// GitHub: TODO en un POST. O entra el review entero o no entra nada.
+async function postReviewGithub(ref, { body, comments, headSha }, env) {
+  const payload = { event: "COMMENT", body, comments: comments.map((c) => inlinePosition(ref, c)) };
+  if (headSha) payload.commit_id = headSha;
+  const res = await fetch(reviewApiUrl(ref), {
+    method: "POST",
+    headers: { ...authHeaders(ref, env), "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+  if (!res.ok) throw new Error(`forge ${res.status}: ${await res.text()}`);
+  const j = await res.json();
+  return { url: j.html_url || null, posted: comments.length, failed: [], atomic: true };
+}
+
+// GitLab: NO hay review atómico. Son 1 nota (el resumen) + N discussions sueltas, así que
+// si la tercera falla, las dos primeras YA están publicadas. Se mitiga validando todo
+// antes de la primera llamada (ver review-findings.mjs), pero no se puede prometer
+// atomicidad — así que se reporta qué entró y qué no, en vez de fingirla.
+async function postReviewGitlab(ref, { body, comments, diffRefs }, env) {
+  const summary = await postComment(ref, body, env);
+  const failed = [];
+  let posted = 0;
+  for (const c of comments) {
+    try {
+      const res = await fetch(reviewApiUrl(ref), {
+        method: "POST",
+        headers: { ...authHeaders(ref, env), "Content-Type": "application/json" },
+        body: JSON.stringify(inlinePosition(ref, c, { diffRefs })),
+      });
+      if (!res.ok) throw new Error(`forge ${res.status}: ${await res.text()}`);
+      posted++;
+    } catch (e) {
+      failed.push({ path: c.path, line: c.line, error: String(e.message) });
+    }
+  }
+  return { url: summary.url, posted, failed, atomic: false };
+}

package/cli/lib/pm-adapter.mjs

@@ -7,9 +7,12 @@
 //   clickup — REST v2 (pm-clickup.mjs)
 //
 // Interfaz (fetchUS/stamp pueden ser sync o async — el CLI siempre await-ea):
-//   fetchUS(id)          → { id, title, spec_version, ac_hash } | null
+//   fetchUS(id)          → { id, title, spec_version, ac_hash, url } | null
 //   stamp(id, record)    → destino donde quedó la cobertura
 //   kind                 → nombre del backend
+//
+// `url` es la URL web canónica de la US según el tracker (opcional: null si el backend
+// no la sabe, como md). El CLI la prefiere sobre la derivada — ver tracker-url.mjs.
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";

package/cli/lib/pm-clickup.mjs

@@ -29,7 +29,9 @@ export function clickupAdapter(env) {
       const res = await fetch(clickupTaskUrl(id), { headers: clickupAuthHeaders(env) });
       if (res.status === 404) return null;
       if (!res.ok) throw new Error(`clickup ${res.status}: ${await res.text()}`);
-      return { id, ...parseUS(clickupTaskToText(await res.json())) };
+      const j = await res.json();
+      // `url` es la canónica (/t/<team_id>/<id>): la sabe ClickUp, no la deducimos.
+      return { id, ...parseUS(clickupTaskToText(j)), url: j.url || null };
     },
     async stamp(id, record) {
       const res = await fetch(clickupCommentUrl(id), {

package/cli/lib/pm-jira.mjs

@@ -143,7 +143,7 @@ export function jiraAdapter(env) {
       const res = await daiFetch(jiraIssueUrl(base, id), { headers: jiraAuthHeaders(env) });
       if (res.status === 404) return null;
       if (!res.ok) throw new Error(`jira ${res.status}: ${await res.text()}`);
-      return { id, ...parseUS(jiraIssueToText(await res.json())) };
+      return { id, ...parseUS(jiraIssueToText(await res.json())), url: `${trim(base)}/browse/${id}` };
     },
     async stamp(id, record) {
       const res = await daiFetch(jiraCommentUrl(base, id), {

package/cli/lib/pr.mjs

@@ -29,15 +29,44 @@ export function composePrBody(template, d) {
   if (d.commits && d.commits.length) {
     b = replaceSection(b, "Cambios realizados", d.commits.map((c) => `- [x] ${c}`).join("\n"));
   }
-  // Bloque de enlaces (lo agrega dai; el humano completa el resto del template).
-  const links = ["", "<!-- Enlaces precargados por `dai pr` -->"];
-  if (d.usUrl) links.push(`- US: ${d.usUrl}`);
+  return upsertLinksBlock(b, d);
+}
+
+// ── Bloque de enlaces ────────────────────────────────────────────────────────
+// Delimitado y regenerable a propósito. Con el comentario suelto de antes, cualquier
+// agente que reescribiera "Enlaces relacionados" se lo llevaba puesto sin dejar rastro
+// (pasó en PRs reales). Con marcadores, el bloque se detecta, se preserva y se
+// regenera — y quien edite el body ve que es de dai y que se pisa solo.
+export const LINKS_START = "<!-- dai:links:start · generado por `dai pr` — no editar a mano -->";
+export const LINKS_END = "<!-- dai:links:end -->";
+
+// Los links que dai sabe. Sin URL no inventa la línea: prefiere no decir nada.
+export function renderLinks(d) {
+  const links = [LINKS_START];
+  if (d.usUrl) links.push(`- US \`${d.id}\`: ${d.usUrl}`);
   if (d.branchUrl) links.push(`- branch \`${d.branch}\`: ${d.branchUrl}`);
   if (d.commitUrl) links.push(`- commit \`${(d.commit || "").slice(0, 8)}\`: ${d.commitUrl}`);
-  return b.replace(/(##\s*Enlaces relacionados\s*\n)(<!--[\s\S]*?-->)?/i,
-    (m, h) => `${h}${links.join("\n")}\n`) === b
-    ? b + "\n" + links.join("\n") + "\n"   // si no había sección Enlaces, apéndela
-    : b.replace(/(##\s*Enlaces relacionados\s*\n)(<!--[\s\S]*?-->)?/i, (m, h) => `${h}${links.join("\n")}\n`);
+  links.push(LINKS_END);
+  return links.join("\n");
+}
+
+// Inserta o reemplaza el bloque de dai. Idempotente: correrlo N veces da lo mismo.
+export function upsertLinksBlock(body, d) {
+  const block = renderLinks(d);
+  // 1. ¿Ya está el bloque delimitado? Se reemplaza entero (regenerar, no duplicar).
+  const delimited = /<!--\s*dai:links:start[\s\S]*?dai:links:end\s*-->/i;
+  if (delimited.test(body)) return body.replace(delimited, block);
+  // 2. ¿Está la sección del template? El bloque va debajo del heading, PRESERVANDO el
+  //    hint HTML si lo hay: es la guía para quien edite (y es invisible al renderizar).
+  //    dai suma, no borra — borrar el texto de otro es justo lo que estamos arreglando.
+  //    (el `\s*` tolera la línea en blanco entre el heading y el hint; como solo matchea
+  //     espacios, no puede saltar a la sección siguiente para buscarse un comentario)
+  const heading = /(^|\n)(##[^\n]*Enlaces relacionados[^\n]*\n)(\s*<!--[\s\S]*?-->[ \t]*\n)?/i;
+  if (heading.test(body)) {
+    return body.replace(heading, (m, pre, h, hint) => `${pre}${h}${hint || ""}\n${block}\n`);
+  }
+  // 3. Ni bloque ni sección: se apéndea con su propio heading.
+  return `${body.replace(/\s*$/, "")}\n\n## Enlaces relacionados\n\n${block}\n`;
 }
 
 // Título del PR: el pasado a mano, o "<ID>: <título de la US>", o solo el ID.

package/cli/lib/review-findings.mjs

@@ -0,0 +1,195 @@
+// dai · hallazgos de un review inline: parseo, validación contra el diff, filtros y render.
+// Puro y sin red (ADR-0002: lo mecánico en el CLI, el criterio en la skill).
+//
+// El contrato con la skill es un `review.json`. La skill lo escribe, el humano lo lee y
+// lo edita, y el CLI lo valida y lo postea. Ese archivo ES la puerta humana: es
+// diff-eable, editable a mano y auditable, y no ata el flujo a ningún asistente.
+
+export const SEVERITIES = ["low", "medium", "high"];
+const SEV = {
+  low: { emoji: "🔵", label: "Low" },
+  medium: { emoji: "🟡", label: "Medium" },
+  high: { emoji: "🔴", label: "High" },
+};
+const rank = (s) => SEVERITIES.indexOf(s);
+
+// ── Parseo del review.json ───────────────────────────────────────────────────
+// Errores accionables: un LLM se equivoca, y "Unexpected token" no le dice dónde.
+
+function fail(msg) {
+  throw new Error(`review.json inválido: ${msg}`);
+}
+
+export function parseFindings(text) {
+  let j;
+  try {
+    j = typeof text === "string" ? JSON.parse(text) : text;
+  } catch (e) {
+    fail(`no es JSON válido (${e.message}).`);
+  }
+  if (!j || typeof j !== "object" || Array.isArray(j)) fail("la raíz tiene que ser un objeto.");
+  if (!Array.isArray(j.findings)) fail("falta el array 'findings' (puede ir vacío, pero tiene que estar).");
+
+  const findings = j.findings.map((f, i) => {
+    const at = `findings[${i}]`;
+    if (!f || typeof f !== "object") fail(`${at}: tiene que ser un objeto.`);
+    if (typeof f.path !== "string" || !f.path.trim()) fail(`${at}: falta 'path' (ruta del archivo, relativa a la raíz del repo).`);
+    if (!Number.isInteger(f.line) || f.line < 1) fail(`${at} (${f.path}): 'line' tiene que ser un entero ≥ 1, vino ${JSON.stringify(f.line)}.`);
+    if (typeof f.body !== "string" || !f.body.trim()) fail(`${at} (${f.path}:${f.line}): falta 'body' (el hallazgo, en prosa).`);
+    const side = f.side === undefined ? "RIGHT" : String(f.side).toUpperCase();
+    if (side !== "RIGHT" && side !== "LEFT") fail(`${at} (${f.path}:${f.line}): 'side' tiene que ser RIGHT o LEFT, vino ${JSON.stringify(f.side)}.`);
+    if (!SEVERITIES.includes(f.severity)) fail(`${at} (${f.path}:${f.line}): 'severity' tiene que ser ${SEVERITIES.join(" | ")}, vino ${JSON.stringify(f.severity)}.`);
+    const confidence = f.confidence === undefined ? 1 : f.confidence;
+    if (typeof confidence !== "number" || confidence < 0 || confidence > 1) {
+      fail(`${at} (${f.path}:${f.line}): 'confidence' tiene que ser un número entre 0 y 1, vino ${JSON.stringify(f.confidence)}.`);
+    }
+    return { path: f.path.trim(), line: f.line, side, severity: f.severity, confidence, body: f.body.trim() };
+  });
+
+  return {
+    us: j.us ?? null,
+    version: j.version ?? null,
+    checkStatus: j.checkStatus ?? null,
+    dod: j.dod ?? null,
+    summary: typeof j.summary === "string" ? j.summary.trim() : "",
+    good: Array.isArray(j.good) ? j.good.filter((g) => typeof g === "string" && g.trim()) : [],
+    findings,
+  };
+}
+
+// ── Posiciones válidas según el diff ─────────────────────────────────────────
+// El anti-alucinación. Un LLM inventa números de línea con una facilidad pasmosa, y el
+// forge responde 422 sin decir cuál falló. Como el diff ya lo tenemos local, se verifica
+// acá antes de salir a la red.
+//
+// Devuelve: Map<path, { right: Set<line>, left: Set<line> }>. Las líneas de contexto
+// cuentan de los dos lados: el forge acepta comentarlas, son parte del hunk.
+
+export function diffPositions(diff) {
+  const files = new Map();
+  let cur = null, newLine = 0, oldLine = 0;
+
+  for (const raw of String(diff ?? "").split(/\r?\n/)) {
+    // Ojo el orden: '+++ ' y '--- ' empiezan con '+' y '-'. Van ANTES que las de contenido.
+    if (raw.startsWith("+++ ")) {
+      const p = raw.slice(4).trim().replace(/\t.*$/, "");
+      if (p === "/dev/null") { cur = null; continue; }        // archivo borrado: no hay lado derecho
+      cur = { right: new Set(), left: new Set() };
+      files.set(stripDiffPrefix(p), cur);
+      continue;
+    }
+    if (raw.startsWith("--- ")) continue;
+    if (raw.startsWith("@@")) {
+      const m = raw.match(/^@@+ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+      if (m) { oldLine = Number(m[1]); newLine = Number(m[2]); }
+      continue;
+    }
+    if (!cur) continue;
+    if (raw.startsWith("+")) cur.right.add(newLine++);
+    else if (raw.startsWith("-")) cur.left.add(oldLine++);
+    else if (raw.startsWith(" ")) { cur.right.add(newLine++); cur.left.add(oldLine++); }
+    // "", "index …", "diff --git …", "similarity …": se ignoran
+  }
+  return files;
+}
+
+// "b/src/x.ts" → "src/x.ts". git usa a//b/ como prefijos del diff.
+function stripDiffPrefix(p) {
+  return p.replace(/^[ab]\//, "");
+}
+
+// ── Validación ───────────────────────────────────────────────────────────────
+// Un hallazgo que no apunta al diff NO se postea. Se reporta, no se descarta en silencio.
+
+export function validateFindings(findings, positions) {
+  const valid = [], rejected = [];
+  for (const f of findings) {
+    const pos = positions.get(f.path);
+    if (!pos) {
+      rejected.push({ finding: f, reason: "el archivo no aparece en el diff" });
+      continue;
+    }
+    const lines = f.side === "LEFT" ? pos.left : pos.right;
+    if (!lines.has(f.line)) {
+      rejected.push({ finding: f, reason: `la línea ${f.line} no es parte del diff (lado ${f.side})` });
+      continue;
+    }
+    valid.push(f);
+  }
+  return { valid, rejected };
+}
+
+// ── Filtros ──────────────────────────────────────────────────────────────────
+// Lo que habilita el modo desatendido con red: por debajo del umbral, el hallazgo no se
+// postea pero se lista en el resumen. Nada se cae en silencio.
+
+export function filterFindings(findings, { minSeverity = "low", minConfidence = 0, maxComments = Infinity } = {}) {
+  if (!SEVERITIES.includes(minSeverity)) throw new Error(`--min-severity: valores ${SEVERITIES.join(" | ")}, vino '${minSeverity}'.`);
+  const kept = [], suppressed = [];
+  // Ordenado por severidad y después por confianza: si hay tope, se cortan los menos graves.
+  const sorted = [...findings].sort((a, b) => rank(b.severity) - rank(a.severity) || b.confidence - a.confidence);
+  for (const f of sorted) {
+    if (rank(f.severity) < rank(minSeverity)) { suppressed.push({ finding: f, reason: `severidad ${f.severity} < ${minSeverity}` }); continue; }
+    if (f.confidence < minConfidence) { suppressed.push({ finding: f, reason: `confianza ${f.confidence} < ${minConfidence}` }); continue; }
+    if (kept.length >= maxComments) { suppressed.push({ finding: f, reason: `tope de --max-comments (${maxComments})` }); continue; }
+    kept.push(f);
+  }
+  return { kept, suppressed };
+}
+
+// ── Render ───────────────────────────────────────────────────────────────────
+
+// El cuerpo de un comentario inline. Lleva marca de dai a propósito: el comentario se
+// postea con el token del humano, así que el forge lo atribuye a él SIN badge de bot. Sin
+// esta línea, el compañero ve un juicio sobre su código firmado por una persona, sin
+// forma de saber que lo escribió una máquina.
+export function renderFindingBody(f) {
+  const { emoji, label } = SEV[f.severity];
+  return `${emoji} **${label}** — ${f.body}\n\n<sub>🤖 <code>dai-review</code> · revisión asistida por IA, revisada y firmada por un humano</sub>`;
+}
+
+const bullets = (arr) => (arr.length ? arr.map((x) => `- ${x}`).join("\n") : "- — ninguno —");
+
+function detailsList(title, items) {
+  if (!items.length) return null;
+  const rows = items.map(({ finding: f, reason }) => `- \`${f.path}:${f.line}\` (${f.severity}) — ${reason}\n  > ${f.body.split("\n")[0]}`);
+  return `<details>\n<summary>${title} (${items.length})</summary>\n\n${rows.join("\n")}\n\n</details>`;
+}
+
+// El cuerpo del review (el "Pull request overview"). Mismo encabezado de metodología que
+// renderReviewComment — los reviews del equipo se siguen leyendo igual.
+export function renderReviewSummary(r, { kept = [], suppressed = [], rejected = [] } = {}) {
+  const head = r.us
+    ? `**US:** \`${r.us}\`${r.version ? ` @ ${r.version}` : ""} · \`dai check\`: ${r.checkStatus || "?"}`
+    : "**US:** _(este PR no declara implementar una US)_";
+
+  const counts = SEVERITIES.slice().reverse()
+    .map((s) => ({ s, n: kept.filter((f) => f.severity === s).length }))
+    .filter(({ n }) => n > 0)
+    .map(({ s, n }) => `${n} ${SEV[s].emoji} ${SEV[s].label}`);
+
+  const hallazgos = kept.length
+    ? `Dejé **${kept.length}** ${kept.length === 1 ? "comentario" : "comentarios"} en línea: ${counts.join(" · ")}.`
+    : "Sin comentarios en línea: no encontré nada concreto que marcar.";
+
+  return [
+    "## 🤖 dai-review",
+    "",
+    head,
+    r.dod ? `**Definition of Done:** ${r.dod}` : null,
+    "",
+    r.summary || null,
+    r.summary ? "" : null,
+    "### Hallazgos",
+    hallazgos,
+    "",
+    "### ✅ Lo que está bien",
+    bullets(r.good),
+    "",
+    detailsList("Suprimidos por el filtro", suppressed),
+    detailsList("Descartados: no apuntan al diff", rejected),
+    "",
+    "---",
+    "_Revisión asistida por dai. La aprobación la firma un humano (Art. 5 del manifiesto)._",
+  ].filter((l) => l !== null).join("\n").replace(/\n{3,}/g, "\n\n") + "\n";
+}

package/cli/lib/tracker-url.mjs

@@ -0,0 +1,36 @@
+// dai · la URL de la US en el tracker. Puro, sync, sin red (ADR-0007: config por .env).
+//
+// Cadena de resolución, del más específico al más general:
+//   1. DAI_TRACKER_URL_TEMPLATE — override explícito del usuario: siempre gana.
+//   2. La URL que devolvió el tracker en `fetchUS` — la canónica (ClickUp la trae con
+//      el team_id; la derivada no puede saberlo). Solo existe si hubo red.
+//   3. Derivada del backend + su config — determinística y offline.
+//   4. `null` — dai NO sabe la URL.
+//
+// El paso 4 es el que importa. Antes devolvíamos el `id` pelado, y como un string es
+// truthy, quien consumía esto lo escribía igual — un id disfrazado de enlace, sin un
+// solo aviso. Preferimos no decir nada antes que mentir: quien llama decide si omite
+// la línea o avisa.
+
+// URL web de la US deducida del backend, sin salir a la red.
+export function deriveTrackerUrl(id, env = {}) {
+  if (!id) return null;
+  const kind = String(env.DAI_PM || "md").toLowerCase();
+  if (kind === "clickup") {
+    // /t/<id> redirige a la canónica /t/<team_id>/<id>. Sin token no sabemos el team.
+    return `https://app.clickup.com/t/${encodeURIComponent(id)}`;
+  }
+  if (kind === "jira") {
+    const base = String(env.DAI_JIRA_BASE_URL || "").replace(/\/+$/, "");
+    return base ? `${base}/browse/${encodeURIComponent(id)}` : null;
+  }
+  return null;   // md: la US es un archivo local, no tiene URL web
+}
+
+// La URL final, o null si no hay forma de saberla. `liveUrl` es la que trajo fetchUS.
+export function trackerUrl(id, { env = {}, liveUrl = null } = {}) {
+  if (!id) return null;
+  const tpl = env.DAI_TRACKER_URL_TEMPLATE;
+  if (tpl) return String(tpl).replace(/\{id\}/g, id);
+  return liveUrl || deriveTrackerUrl(id, env);
+}

package/docs/PROBAR.md

@@ -65,8 +65,9 @@ Si esto anda, el flujo está bien. Pasa al tracker real.
 cat > .env <<'EOF'
 DAI_PM=clickup
 DAI_CLICKUP_TOKEN=pk_XXXXXXXX
-DAI_TRACKER_URL_TEMPLATE=https://app.clickup.com/t/{id}
 EOF
+# El link a la tarea lo deduce dai solo. Solo si tu tracker vive en otra URL:
+#   DAI_TRACKER_URL_TEMPLATE=https://mi-tracker/t/{id}
 dai doctor                       # confirma DAI_PM=clickup y el token
 
 dai link-us 86cxyz               # trae la US de ClickUp → branch + implements.yaml

package/docs/adr/0016-review-inline.md

@@ -0,0 +1,128 @@
+# 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](0002-agnostico-del-asistente.md) aplicada al review: el criterio es de
+la skill, lo determinista es del CLI.
+
+**Por qué un archivo y no una TUI.** Evaluamos [hunk](https://github.com/modem-dev/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](../MANIFIESTO.md#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.

package/docs/adr/README.md

@@ -21,6 +21,7 @@ decisión cambia, se escribe un ADR nuevo que supersede al viejo. Molde en
 | [0013](0013-skills-externas-install-from.md) | `dai skills install --from`: skills externas por-stack, sin registro ni gatekeeping | aceptado |
 | [0014](0014-copilot-agent-skills.md) | Copilot lee `SKILL.md` nativo (Agent Skills): se elimina el adaptador `.prompt.md` — modifica la 0002 | aceptado |
 | [0015](0015-jira-corporativo.md) | `dai publish` en Jira corporativo: campos propios declarados, `--parent`/`--issuetype`, TLS con CA (nunca apagar la verificación) | aceptado |
+| [0016](0016-review-inline.md) | Review inline: `review.json` como contrato y puerta humana, el CLI valida las posiciones contra el diff, `--yes` explícito, nunca `APPROVE` | aceptado |
 
 > Estas son las decisiones que cierran las "Decisiones abiertas" de
 > [`METODOLOGIA.md §7`](../METODOLOGIA.md) y las enmiendas al

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforce2055/dai",
-  "version": "0.8.1",
+  "version": "0.9.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/",

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 y lo postea — vía el MCP del forge si está disponible, o vía `dai forge comment` (token) si no. 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,44 +52,93 @@ 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. **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
 ```
 
-## Dos 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. **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
+> leído en la letra —no clickeaba Approve— y mal puesto en la práctica: te dejaba
+> firmar en público un review que nunca viste. Que salga bueno era suerte, no diseño.
+
 ## Relación con el modelo
 
 - 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.

package/templates/pull-request.md

@@ -42,7 +42,11 @@
 
 ## Enlaces relacionados
 
-<!-- US en el tracker, commit ancla, docs, issues. -->
+<!--
+  La US, la branch y el commit ancla los precarga `dai pr` en el bloque `dai:links`
+  de abajo: NO los escribas a mano ni reescribas ese bloque (se regenera y te lo pisa).
+  Acá abajo sumá solo lo que dai no sabe: docs, issues, PRs relacionadas, dependencias.
+-->
 
 ---