@dforce2055/dai 0.8.2 → 0.10.0

package/cli/dai.mjs

@@ -21,11 +21,12 @@ import { createInterface } from "node:readline/promises";
 import { acHash } from "./lib/ac-hash.mjs";
 import { discoverImplements, isPlaceholderId } from "./lib/implements.mjs";
 import { isValidKey, slugify, branchName, extractTitle, renderImplementsYaml } from "./lib/link-us.mjs";
-import { loadEnv } from "./lib/env.mjs";
+import { loadDaiEnv } 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";
@@ -47,8 +48,33 @@ const warn = (m) => process.stdout.write(`⚠ ${m}\n`);
 // Color ANSI mínimo — solo si es TTY y no está NO_COLOR (así no ensucia pipes/CI).
 const _color = process.stdout.isTTY && !process.env.NO_COLOR;
 const paint = (code, m) => (_color ? `\x1b[${code}m${m}\x1b[0m` : m);
-const C = { y: (m) => paint("33", m), r: (m) => paint("31", m), cy: (m) => paint("36", m), b: (m) => paint("1", m) };
+const C = { y: (m) => paint("33", m), r: (m) => paint("31", m), cy: (m) => paint("36", m), b: (m) => paint("1", m), dim: (m) => paint("2", m) };
 const ROOT = join(HERE, "..");            // raíz del paquete dai (cli/ está adentro)
+
+// Banner de bienvenida de `dai init`: el Sol de Mayo en bloques (cuerpo y rayos rectos en
+// oro; rayos ondulados en celeste) al lado del título, más el preview de lo que se configura.
+// Todo con caracteres — cero-dep. Degrada a ASCII sin color si no hay TTY o con NO_COLOR.
+const initBanner = () => {
+  const sun = [
+    "     █     ",
+    " ▒ ▄███▄ ▒ ",
+    "██ █████ ██",
+    " ▒ ▀███▀ ▒ ",
+    "     █     ",
+  ];
+  const paintSun = (line) => [...line].map((ch) => (ch === "▒" ? C.cy(ch) : ch === " " ? " " : C.y(ch))).join("");
+  const aside = ["", paint("1;33", "dai") + " · Desarrollo Asistido por IA", C.dim("La IA asiste; la persona firma."), "", ""];
+  let out = "\n";
+  for (let i = 0; i < sun.length; i++) out += "  " + paintSun(sun[i]) + (aside[i] ? "    " + aside[i] : "") + "\n";
+  out += "\n  " + C.b("Esto va a configurar el repo:") + "\n";
+  for (const b of [
+    "Skills del método (grill · link-us · tdd · dai-review) en tu asistente",
+    "La constitución del proyecto — las reglas del trabajo",
+    "OpenSpec para el CÓMO (design / tasks) — opcional",
+    "Plantilla de PR + .env.dai para el tracker",
+  ]) out += "    " + C.cy("▸") + " " + b + "\n";
+  return out;
+};
 const CLAUDE_SKILLS_DIR = process.env.CLAUDE_SKILLS_DIR || join(homedir(), ".claude", "skills");
 const CURSOR_SKILLS_DIR = process.env.CURSOR_SKILLS_DIR || join(homedir(), ".cursor", "skills");
 // Copilot lee las skills personales de ~/.copilot/skills (NO de ~/.claude/skills, que
@@ -118,10 +144,10 @@ async function cmdLinkUs(key, opts) {
     title = opts.title || extractTitle(md);
   } else {
     // Fuente tracker: traer la US del adaptador (mismo hash que usará `dai check`).
-    loadEnv();
+    loadDaiEnv();
     const adapter = getAdapter(process.env);
     const us = await adapter.fetchUS(key);
-    if (!us) fail(`no encontré la US ${key} en el backend ${adapter.kind}. Pasa --us <md> o revisa el .env.`, 2);
+    if (!us) fail(`no encontré la US ${key} en el backend ${adapter.kind}. Pasa --us <md> o revisa el .env.dai.`, 2);
     hash = us.ac_hash;
     if (hash == null) fail(`la US ${key} no tiene una sección 'Criterios de aceptación' con criterios testeables → sin ac_hash, no se puede linkear.\n  Agregá la sección en el tracker, o corré /grill-user-story ${key} para pulir la US (te interroga y la re-publica).`, 2);
     title = opts.title || us.title;
@@ -179,7 +205,7 @@ function gitCommit() { try { return git(["rev-parse", "HEAD"]); } catch { return
 
 // ── check ──────────────────────────────────────────────────────────────────
 async function cmdCheck() {
-  loadEnv();
+  loadDaiEnv();
   const adapter = getAdapter(process.env);
   const found = discoverImplements(process.cwd(), { includeArchived: false });
   let worst = 0, n = 0;
@@ -210,7 +236,7 @@ async function cmdCheck() {
 
 // ── stamp ──────────────────────────────────────────────────────────────────
 async function cmdStamp() {
-  loadEnv();
+  loadDaiEnv();
   const adapter = getAdapter(process.env);
   const remote = gitRemote(), branch = gitBranch(), commit = gitCommit();
   const found = discoverImplements(process.cwd());
@@ -232,7 +258,7 @@ async function cmdStamp() {
 
 // ── forge (review) ───────────────────────────────────────────────────────────
 async function cmdForge(sub, ref, opts) {
-  loadEnv();
+  loadDaiEnv();
   const pr = parsePrRef(ref, gitRemote());
   if (!pr) fail("no pude resolver la PR/MR. Pasa la URL completa o el número (con remoto git).", 1);
   if (sub === "pr") {
@@ -242,11 +268,82 @@ 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) ──────────
 
 // Los campos propios que exige el proyecto, declarados en .dai/jira-fields.json
@@ -260,7 +357,7 @@ function loadJiraFieldsSpec() {
 
 async function cmdPublish(file, opts = {}) {
   if (!file) fail("uso: dai publish <archivo-us.md> [--parent KEY] [--issuetype T] [--field alias=valor]", 1);
-  loadEnv();
+  loadDaiEnv();
   const md = readFileSync(file, "utf8");
   const title = extractTitle(md);
   if (!title) fail("no pude extraer el título de la US (falta un '# Título').", 1);
@@ -337,7 +434,7 @@ function cmdDone(opts) {
 // ── pr: crea TU PROPIA PR/MR precargada desde el template + el link ────────────
 // (Distinto de dai-review, que revisa la PR de OTRO. Tu PR la creas y revisas tú.)
 async function cmdPr(opts) {
-  loadEnv();
+  loadDaiEnv();
   const remote = gitRemote(), branch = gitBranch(), commit = gitCommit();
   if (!remote) fail("no hay remoto git 'origin'. Configúralo para crear la PR.", 1);
   if (!branch || branch === "HEAD") fail("no estás en una branch.", 1);
@@ -375,7 +472,7 @@ async function cmdPr(opts) {
   for (const f of found) for (const im of f.implements || []) {
     if (!isPlaceholderId(im.id)) { entry = { f, im }; break; }
   }
-  if (!entry) fail("no encontré un implements.yaml con una US real. Ejecuta `dai link-us` primero.", 1);
+  if (!entry) fail("no hay una US linkeada (implements.yaml). Si este PR implementa una US, corré `dai link-us` primero. Si es un chore/tooling (sin US), creá la PR con tu forge: `glab mr create` / `gh pr create`.", 1);
   const { id, version, ac_hash } = entry.im;
 
   // 2. Estado de trazabilidad (dai check) contra la US viva.
@@ -398,7 +495,7 @@ async function cmdPr(opts) {
   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}).`);
+    warn(`configurá DAI_TRACKER_URL_TEMPLATE en el .env.dai (p. ej. https://tu-tracker/browse/{id}).`);
   }
   const body = composePrBody(readFileSync(tplPath, "utf8"), {
     id, version, ac_hash, status, usUrl, usTitle: live?.title, commits,
@@ -560,7 +657,7 @@ async function cmdInstall(opts) {
 // dai (colisión → warn + skip). `dai sync` NO las toca: es solo de dai.
 function cmdInstallFrom(opts) {
   if (typeof opts.from !== "string" || !opts.from.trim())
-    fail("--from necesita una fuente: un git URL (github.com/org/skills[#ref]) o un path local", 2);
+    fail("--from necesita una fuente: un git URL (github.com/org/skills[#ref]), un paquete npm (npm:@scope/pkg) o un path local", 2);
   let want;
   try { want = parseAssistants(typeof opts.for === "string" ? opts.for : "all"); }
   catch (e) { fail(`--for ${e.message}`); }
@@ -579,6 +676,33 @@ function cmdInstallFrom(opts) {
     try { git(args); }
     catch (e) { rmSync(tmp, { recursive: true, force: true }); fail(`no pude clonar la fuente: ${String(e.message).split("\n")[0]}`, 1); }
     root = tmp;
+  } else if (src.type === "npm") {
+    tmp = mkdtempSync(join(tmpdir(), "dai-skills-"));
+    info(`bajando el paquete npm ${src.location} …`);
+    try {
+      // `npm install` (no `npm pack`) en el temp. Dos decisiones a propósito:
+      // 1) install en vez de pack: los registries de GRUPO de GitLab devuelven una
+      //    `dist.tarball` malformada (el scope duplicado en el nombre) que `npm pack` sigue
+      //    literal y da 404; `npm install` —como `npx`— reconstruye la URL y resuelve.
+      // 2) copiamos el `.npmrc` del repo al temp y corremos con cwd=temp: así npm ve el
+      //    registry/scope privado (con `--prefix` npm NO lee el `.npmrc` del cwd y se va al
+      //    registry público). `--ignore-scripts`: no corremos scripts de un paquete de 3ros.
+      const repoNpmrc = join(process.cwd(), ".npmrc");
+      if (existsSync(repoNpmrc)) cpSync(repoNpmrc, join(tmp, ".npmrc"));
+      runNpmTool("npm", ["install", src.location,
+        "--no-save", "--no-package-lock", "--ignore-scripts", "--no-audit", "--no-fund"],
+        { cwd: tmp, stdio: ["ignore", "ignore", "pipe"] });
+      // El paquete queda en <tmp>/node_modules/<name>. name = spec sin la versión
+      // (@scope/pkg@1.2.3 → @scope/pkg; el `@` inicial del scope no cuenta).
+      let name = src.location; const at = name.lastIndexOf("@");
+      if (at > 0) name = name.slice(0, at);
+      root = join(tmp, "node_modules", name);
+      if (!existsSync(root)) throw new Error(`npm install no dejó '${name}' en node_modules`);
+    } catch (e) {
+      rmSync(tmp, { recursive: true, force: true });
+      const detail = String(e.stderr || e.stdout || e.message || "").split("\n").map((s) => s.trim()).filter(Boolean).slice(0, 3).join("\n         ");
+      fail(`no pude bajar el paquete npm '${src.location}':\n         ${detail || "npm install falló — revisá el spec, el registry y el .npmrc del repo"}`, 1);
+    }
   } else {
     root = src.location;
     if (!existsSync(root)) fail(`no existe la fuente: ${root}`, 2);
@@ -666,7 +790,7 @@ async function cmdInit(repo, opts) {
   }
   const rl = process.stdin.isTTY ? createInterface({ input: process.stdin, output: process.stdout }) : null;
 
-  process.stdout.write("\n  dai · configurar este repo para desarrollo asistido por IA\n");
+  process.stdout.write(initBanner());
 
   // Preguntas primero (después cerramos readline para liberar stdin a los instaladores).
   let forOpt = typeof opts.for === "string" ? opts.for.toLowerCase() : null;
@@ -717,28 +841,32 @@ async function cmdInit(repo, opts) {
   writeFileSync(join(dai, "VERSION"), readFileSync(join(ROOT, "VERSION"), "utf8"));
   ok(".dai/         moldes (templates) + reglas (governance) del método");
 
-  // .env.example — aditivo, reflejando el --pm elegido: mismas claves que el .env
-  // (con valores VACÍOS, sin secretos) para que el token del tracker esté presente.
-  const exSrc = envFor(pm);
-  const exPath = join(repo, ".env.example");
+  // Config de dai en SUS PROPIOS archivos, sin tocar el `.env`/`.env.example` del equipo:
+  // muchas orgs versionan el `.env` como política, así que dai lo deja en paz (solo lo lee,
+  // por compat) y pone lo suyo en `.env.dai` (ver ADR-0017). `.env.dai.example` se versiona
+  // como plantilla; `.env.dai` (gitignored) es donde cada dev completa token y datos propios.
+  const envBlock = envFor(pm);
+
+  // .env.dai.example — plantilla VERSIONADA, mismas claves con valores VACÍOS (sin secretos).
+  const exPath = join(repo, ".env.dai.example");
   if (existsSync(exPath)) {
-    const cur = readFileSync(exPath, "utf8"), merged = mergeEnv(cur, exSrc);
-    if (merged !== cur) { writeFileSync(exPath, merged); ok(".env.example  claves de dai agregadas (aditivo)"); }
-    else ok(".env.example  ya tenía la config de dai");
-  } else { writeFileSync(exPath, exSrc); ok(".env.example  creado"); }
+    const cur = readFileSync(exPath, "utf8"), merged = mergeEnv(cur, envBlock);
+    if (merged !== cur) { writeFileSync(exPath, merged); ok(".env.dai.example  claves de dai agregadas (aditivo)"); }
+    else ok(".env.dai.example  ya tenía la config de dai");
+  } else { writeFileSync(exPath, envBlock); ok(".env.dai.example  creado (plantilla versionada)"); }
 
-  // .env — aditivo: agrega las claves de dai que falten; si no existe, lo crea.
-  const envPath = join(repo, ".env"), envBlock = envFor(pm);
+  // .env.dai — el real de cada dev (gitignored): aditivo; si no existe, lo crea.
+  const envPath = join(repo, ".env.dai");
   if (existsSync(envPath)) {
     const cur = readFileSync(envPath, "utf8"), merged = mergeEnv(cur, envBlock);
-    if (merged !== cur) { writeFileSync(envPath, merged); ok(`.env          claves de dai agregadas (aditivo, DAI_PM=${pm}${pm === "md" ? "" : " — completa el token"})`); }
-    else ok(".env          ya tenía la config de dai");
-  } else { writeFileSync(envPath, envBlock); ok(`.env          listo, DAI_PM=${pm}${pm === "md" ? "" : " (completa el token)"}`); }
+    if (merged !== cur) { writeFileSync(envPath, merged); ok(`.env.dai      claves de dai agregadas (aditivo, DAI_PM=${pm}${pm === "md" ? "" : " — completa el token"})`); }
+    else ok(".env.dai      ya tenía la config de dai");
+  } else { writeFileSync(envPath, envBlock); ok(`.env.dai      creado (no versionado), DAI_PM=${pm}${pm === "md" ? "" : " (completa el token)"}`); }
 
   // .gitignore — versiona los artefactos de dai (según --for), deja fuera solo lo personal.
   const giPath = join(repo, ".gitignore");
   const gi = reconcileGitignore(existsSync(giPath) ? readFileSync(giPath, "utf8") : "", want);
-  if (gi.changed) { writeFileSync(giPath, gi.text.endsWith("\n") ? gi.text : gi.text + "\n"); ok(".gitignore    ajustado (skills/constitución versionadas; .env y settings.local.json fuera)"); }
+  if (gi.changed) { writeFileSync(giPath, gi.text.endsWith("\n") ? gi.text : gi.text + "\n"); ok(".gitignore    ajustado (skills/constitución versionadas; .env.dai y settings.local.json fuera)"); }
 
   mkdirSync(join(repo, ".github"), { recursive: true });
   cpSync(join(ROOT, "templates", "pull-request.md"), join(repo, ".github", "pull_request_template.md"));
@@ -822,12 +950,12 @@ async function cmdInit(repo, opts) {
   }
 
   // ── Próximos pasos ─────────────────────────────────────────────────────────
-  process.stdout.write("\n  ✔ Repo configurado. Próximos pasos:\n");
+  process.stdout.write("\n  " + C.y("✔") + " " + C.b("Repo configurado.") + " Próximos pasos:\n");
   process.stdout.write(pm === "md"
-    ? "    1. Crea tu primera US en .dai/us/<ID>.md (criterios bajo '## Criterios de aceptación')\n"
-    : `    1. Completa el token de ${pm} en .env, y verifica con: dai doctor\n`);
-  process.stdout.write("    2. dai link-us <ID>     → crea la branch + el link a la US\n");
-  process.stdout.write("    3. Implementa con test primero, después: dai check\n");
+    ? `    1. Crea tu primera US en ${C.cy(".dai/us/<ID>.md")} (criterios bajo '## Criterios de aceptación')\n`
+    : `    1. Copia ${C.cy(".env.dai.example")} → ${C.cy(".env.dai")} y completa el token de ${pm}; verifica con ${C.y("dai doctor")}\n`);
+  process.stdout.write(`    2. ${C.y("dai link-us <ID>")}     → crea la branch + el link a la US\n`);
+  process.stdout.write(`    3. Implementa con test primero, después: ${C.y("dai check")}\n`);
   process.stdout.write("    Guía paso a paso: https://github.com/dforce2055/dai/blob/main/docs/PROBAR.md\n\n");
 }
 
@@ -959,7 +1087,7 @@ function cmdSync(repo, opts) {
     () => writeFileSync(giPath, gi.text.endsWith("\n") ? gi.text : gi.text + "\n"));
 
   if (dry) info("dry-run: nada escrito. Quitá --dry-run para aplicar.");
-  else { process.stdout.write("\n"); ok(`sync completo — .dai/ ahora en v${cliV}`); process.stdout.write("  (El .env y OpenSpec no se tocan: OpenSpec se actualiza aparte con `openspec`.)\n"); }
+  else { process.stdout.write("\n"); ok(`sync completo — .dai/ ahora en v${cliV}`); process.stdout.write("  (El .env.dai y OpenSpec no se tocan: OpenSpec se actualiza aparte con `openspec`.)\n"); }
 }
 
 // Imprime el estado de version-drift del scaffold (ADR-0010) con color + ícono.
@@ -1025,7 +1153,7 @@ function cmdUpgrade(opts) {
 
 // ── doctor: diagnóstico ───────────────────────────────────────────────────────
 function cmdDoctor() {
-  loadEnv();
+  loadDaiEnv();
   info(`dai doctor — versión v${readFileSync(join(ROOT, "VERSION"), "utf8").trim()}`);
 
   // Una skill sirve si está en el repo actual (la puso `dai init`) o global (la puso
@@ -1079,11 +1207,11 @@ function cmdDoctor() {
   const pm = process.env.DAI_PM || "md";
   ok(`DAI_PM=${pm}`);
   if (pm === "jira") {
-    if (!process.env.DAI_JIRA_BASE_URL) warn("falta DAI_JIRA_BASE_URL en el .env");
-    if (!process.env.DAI_JIRA_EMAIL) warn("falta DAI_JIRA_EMAIL en el .env");
+    if (!process.env.DAI_JIRA_BASE_URL) warn("falta DAI_JIRA_BASE_URL en .env.dai");
+    if (!process.env.DAI_JIRA_EMAIL) warn("falta DAI_JIRA_EMAIL en .env.dai");
     // Ojo: solo miramos que el token ESTÉ, no que sirva — uno vencido pasa este chequeo
     // y recién falla al publicar. Verificarlo de verdad es pegarle a la red.
-    if (!process.env.DAI_JIRA_TOKEN) warn("falta DAI_JIRA_TOKEN en el .env"); else ok("token de Jira presente (no verificado: eso lo dice `dai publish`)");
+    if (!process.env.DAI_JIRA_TOKEN) warn("falta DAI_JIRA_TOKEN en .env.dai"); else ok("token de Jira presente (no verificado: eso lo dice `dai publish`)");
     if (!process.env.DAI_JIRA_PROJECT) warn("DAI_JIRA_PROJECT vacío — solo hace falta para `dai publish` (crear issues)");
     else {
       try { ok(`proyecto=${assertProjectKey(process.env.DAI_JIRA_PROJECT)} (para dai publish)`); }
@@ -1101,7 +1229,7 @@ function cmdDoctor() {
     }
   }
   if (pm === "clickup") {
-    if (!process.env.DAI_CLICKUP_TOKEN) warn("falta DAI_CLICKUP_TOKEN en el .env"); else ok("token de ClickUp presente");
+    if (!process.env.DAI_CLICKUP_TOKEN) warn("falta DAI_CLICKUP_TOKEN en .env.dai"); else ok("token de ClickUp presente");
     process.env.DAI_CLICKUP_LIST_ID ? ok(`lista=${process.env.DAI_CLICKUP_LIST_ID} (para dai publish)`)
       : warn("DAI_CLICKUP_LIST_ID vacío — solo hace falta para `dai publish` (crear tareas)");
   }
@@ -1160,19 +1288,22 @@ 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" +
+      "  skills install --from <git-url|npm:pkg|path>[#ref] [--for <asistentes>]   instala skills EXTERNAS (por-stack), convertidas para los 3 asistentes (ADR-0013)\n" +
       "  init [<repo>]                scaffolder interactivo del repo (asistente, gestor, OpenSpec)\n" +
       "       --for <asistentes>      claude|copilot|cursor (combinables con coma) · o both|all (default all)\n" +
       "                               ej: --for claude,cursor · --for copilot · --for all\n" +
       "       --pm md|jira|clickup · --openspec   (con flags salteas las preguntas)\n" +
-      "  sync [<repo>] [--dry-run] [--for <asistentes>]   refresca skills/constitución/templates a la versión del CLI (aditivo; no toca .env ni OpenSpec)\n" +
+      "  sync [<repo>] [--dry-run] [--for <asistentes>]   refresca skills/constitución/templates a la versión del CLI (aditivo; no toca .env.dai ni OpenSpec)\n" +
       "  upgrade [--check] [--dry-run]   (alias: update) actualiza el CLI global a la última (npm i -g …@latest) y avisa si el repo quedó atrasado (ADR-0012)\n" +
       "  docs <destino>               documentación conceptual → <destino>\n" +
       "  doctor                       diagnóstico del entorno\n\n" +
-      "  (config: .env — ver .env.example)\n"
+      "  (config: .env.dai — ver .env.dai.example)\n"
     );
     process.exit(cmd && cmd !== "help" ? 1 : 0);
 }

package/cli/lib/bootstrap.mjs

@@ -47,13 +47,38 @@ function unquoteScalar(s) {
 // Parsea el frontmatter YAML de un SKILL.md → { name, description, body }.
 // Devuelve los valores YA sin comillas, para que quien los reserialice (skillToCursor)
 // no los cite dos veces.
+// Lee un campo del frontmatter. Soporta escalar de una línea (con/sin comillas) y BLOQUE
+// YAML (`|` literal, `>` plegado, con chomp `-`/`+`): junta las líneas indentadas siguientes
+// hasta la próxima clave (columna 0). El parser de dai es regex, no un YAML completo — esto
+// cubre lo común: descripciones multilínea, que es como se escriben las skills reales.
+function readFmField(fm, key) {
+  const lines = fm.split(/\r?\n/);
+  const keyRe = new RegExp(`^${key}:\\s*(.*)$`);
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(keyRe);
+    if (!m) continue;
+    const inline = m[1].trim();
+    const blk = inline.match(/^([|>])[-+]?\s*$/);       // |, >, |-, |+, >-, >+
+    if (!blk) return unquoteScalar(inline) || null;     // escalar de una línea
+    const buf = [];
+    for (let j = i + 1; j < lines.length; j++) {
+      if (lines[j].trim() === "") { buf.push(""); continue; }
+      if (!/^\s/.test(lines[j])) break;                 // sin indentar → empezó otra clave
+      buf.push(lines[j]);
+    }
+    const indent = ((buf.find((l) => l.trim() !== "") || "").match(/^\s*/) || [""])[0].length;
+    const text = buf.map((l) => l.slice(indent)).join("\n").replace(/\s+$/, "");
+    // `>` plegado: un salto simple → espacio; los dobles (párrafo) se conservan.
+    return (blk[1] === ">" ? text.replace(/([^\n])\n(?!\n)/g, "$1 ") : text) || null;
+  }
+  return null;
+}
+
 export function parseFrontmatter(md) {
   const m = md.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
   if (!m) return { name: null, description: null, body: md.trim() };
   const fm = m[1];
-  const name = unquoteScalar((fm.match(/^name:\s*(.+)$/m) || [])[1]) || null;
-  const description = unquoteScalar((fm.match(/^description:\s*(.+)$/m) || [])[1]) || null;
-  return { name, description, body: m[2].trim() };
+  return { name: readFmField(fm, "name"), description: readFmField(fm, "description"), body: m[2].trim() };
 }
 
 // Valida el contrato MÍNIMO de un SKILL.md para que dai lo ingiera y los asistentes lo
@@ -66,7 +91,11 @@ export function validateSkill(md) {
   if (!name) return "falta 'name' en el frontmatter";
   if (!description) return "falta 'description' en el frontmatter";
   for (const key of ["name", "description"]) {
-    const issue = yamlScalarIssue(rawFrontmatterValue(md, key));
+    const raw = rawFrontmatterValue(md, key);
+    // Un bloque YAML (`|`, `>`, con chomp) es literal → siempre válido; su contenido va en las
+    // líneas indentadas, no en el valor de la clave. No lo pasamos por el scalar-check.
+    if (/^[|>][-+]?\s*$/.test(String(raw ?? "").trim())) continue;
+    const issue = yamlScalarIssue(raw);
     if (issue) return `'${key}' no es YAML válido: ${issue} — citá el valor con comillas dobles`;
   }
   return null;
@@ -98,7 +127,7 @@ export function skillToCursor(md) {
 // 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";
+  const head = "# Config de dai — va en .env.dai (NO versionado), no en el .env del equipo.\n# Completá lo que falte. NUNCA commitees tokens.\n";
   if (pm === "clickup") {
     return head + "DAI_PM=clickup\nDAI_CLICKUP_TOKEN=\nDAI_CLICKUP_LIST_ID=\n";
   }
@@ -153,7 +182,13 @@ 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.
+  // `.env.dai` (config y secretos de dai) SÍ se ignora; el `.env` del equipo NO lo tocamos:
+  // es suyo y muchas orgs lo versionan como política (ADR-0017). La plantilla
+  // `.env.dai.example` sí se versiona (no matchea `.env.dai` exacto, así que no se ignora).
+  const ensure = [".env.dai", ".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;
@@ -196,7 +231,7 @@ export function constitution(kind) {
 - **El link se autora una vez** (\`implements.yaml\`); la cobertura se **deriva** (nunca a mano).
 - **Verifica el comportamiento, no solo que compile:** que pase el chequeo estático o el build no prueba que funcione; ejercita el flujo real antes de darlo por hecho.
 - **La IA confirma antes de construir:** el asistente declara que entendió esta constitución y la va a obedecer antes de generar código.
-- **Secretos:** en \`.env\` (nunca commiteados). git por **SSH**, APIs por **token scopeado**.
+- **Secretos:** en \`.env.dai\` (NO versionado; el \`.env\` del equipo no se toca). git por **SSH**, APIs por **token scopeado**.
 - **No bajes la seguridad para avanzar:** si una llamada falla por el certificado, declara la CA (\`NODE_EXTRA_CA_CERTS\`). **Nunca** \`NODE_TLS_REJECT_UNAUTHORIZED=0\`, \`verify=False\`, \`-k\` ni equivalentes: apagan la verificación de toda la conexión, y por ahí viajan los tokens.
 - **Si el CLI no llega, para y dilo:** cuando \`dai\` no cubre un caso, repórtalo — no improvises una llamada a la API por fuera. El atajo publica igual, pero rompe el link QUÉ↔CÓMO en silencio y nadie se entera hasta que la trazabilidad ya está mal.
 - **Docs vivas:** una constitución o arquitectura desactualizada es un defecto, no documentación.

package/cli/lib/env.mjs

@@ -4,6 +4,18 @@
 
 import { readFileSync } from "node:fs";
 
+// Config de dai: `.env.dai` (propio, nunca versionado) tiene prioridad sobre `.env`.
+// Pensado para equipos que versionan el `.env` (política de empresa): dai deja ese
+// archivo en paz y pone sus claves y secretos en `.env.dai` (gitignored). Se carga
+// `.env.dai` PRIMERO porque el loader es "primero-gana" (ver más abajo), así la
+// precedencia queda: entorno (shell/CI) > .env.dai > .env. Leer también `.env`
+// mantiene compatibilidad con repos previos que tienen los DAI_* ahí.
+export function loadDaiEnv(env = process.env) {
+  loadEnv(".env.dai", env);
+  loadEnv(".env", env);
+  return env;
+}
+
 export function loadEnv(path = ".env", env = process.env) {
   let text;
   try { text = readFileSync(path, "utf8"); } catch { return env; } // sin .env: no pasa nada

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-clickup.mjs

@@ -22,7 +22,7 @@ export function clickupTaskToText(json) {
 }
 
 export function clickupAdapter(env) {
-  if (!env.DAI_CLICKUP_TOKEN) throw new Error("falta DAI_CLICKUP_TOKEN en el .env (backend clickup).");
+  if (!env.DAI_CLICKUP_TOKEN) throw new Error("falta DAI_CLICKUP_TOKEN en el .env.dai (backend clickup).");
   return {
     kind: "clickup",
     async fetchUS(id) {
@@ -43,7 +43,7 @@ export function clickupAdapter(env) {
     },
     async createUS({ title, descriptionMarkdown }) {
       const list = env.DAI_CLICKUP_LIST_ID;
-      if (!list) throw new Error("falta DAI_CLICKUP_LIST_ID en el .env (la lista donde crear la tarea).");
+      if (!list) throw new Error("falta DAI_CLICKUP_LIST_ID en el .env.dai (la lista donde crear la tarea).");
       const res = await fetch(`${API}/list/${encodeURIComponent(list)}/task`, {
         method: "POST", headers: clickupAuthHeaders(env),
         body: JSON.stringify({ name: title, markdown_content: descriptionMarkdown }),