@dforce2055/dai 0.15.0 → 0.15.1

package/CHANGELOG.md

@@ -3,6 +3,61 @@
 Formato basado en [Keep a Changelog](https://keepachangelog.com/). Versionado semver
 (ver `VERSION`).
 
+## [0.15.1] — 2026-09-10
+
+**Una US puede estar impecable y dai igual no leerla. El molde de trazabilidad pide que la
+metadata viva en una tabla, y cuando la US se escribe a mano en Jira esa tabla es una tabla
+de verdad — que dai no sabía leer. El `spec_version` declarado se perdía en el camino y el
+link quedaba estampado en `pendiente`, con un mensaje que mandaba a agregar una fila que ya
+estaba ahí. Esta versión le enseña a dai a leer y escribir tablas.**
+
+### Corregido
+- **El `spec_version` que la US declaraba y dai no veía.** `adfToMarkdown` no tenía caso
+  para las tablas de Jira Cloud, así que caían al `default` y cada celda terminaba en su
+  propia línea: `spec_version` en una, `v1` en la siguiente. Como el regex que lee la
+  versión no cruza saltos de línea —a propósito, para no capturar un `v2` de veinte líneas
+  más abajo— no encontraba nada, y el link se estampaba en `version: pendiente`. El aviso
+  era el peor de todos: uno que **acusa al usuario** de no haber hecho algo que sí hizo.
+  Ahora una fila de tabla llega como una fila de markdown. El `ac_hash` **no se mueve** —la
+  metadata vive arriba del bloque de criterios—, así que ningún `implements.yaml` ya
+  estampado queda atrasado por este cambio: lo único que cambia es que `pendiente` pasa a
+  ser la versión que la US declara. Es el hermano del #46: aquel era el campo escrito
+  `specversion`, este es el campo escrito en la tabla que el propio molde pide.
+- **La otra mitad del mismo bug: dai tampoco escribía tablas.** `markdownToAdf` mandaba la
+  metadata del molde —y el comentario de cobertura de `dai release stamp`, que también es
+  una tabla— como párrafos con pipes adentro. Ilegibles, y encima invitaban a rehacerlos
+  como tabla de Jira a mano, que es justo lo que del otro lado no se sabía leer. Ahora
+  viajan como nodo `table` y el ida y vuelta de `dai edit-us` no destruye la metadata.
+- **`dai release done` avisaba de un problema inexistente.** Miraba `origin/release/X.Y.Z`,
+  una ref local que sobrevive desactualizada hasta el próximo prune, en vez de preguntarle
+  al remoto. Cuando GitHub ya había borrado la rama al mergear —su comportamiento por
+  default— intentaba borrar algo que no estaba y reportaba un ⚠ sobre un estado que era el
+  correcto. Ahora pregunta con `git ls-remote --heads`, que es autoritativo, limpia la ref
+  fantasma y explica en una línea por qué no hubo nada que borrar. Un aviso falso es caro:
+  enseña a ignorar los avisos.
+
+### Cambiado
+- **`dai release plan --json` expone `counts.stale`, antes `counts.atrasadas`.** Era una
+  clave en español en una salida que lee un script — la única que quedaba — y sigue el
+  glosario que ADR-0008 ya había fijado (*atrasado* → *stale*). Si escribiste algo contra
+  el `--json` de la 0.15.0 (publicada un día antes), es el único nombre que tenés que
+  cambiar.
+
+### Interno
+- **Convención de idioma, ahora escrita.** El repo siempre fue código en inglés y
+  comentarios en español, pero no estaba en ningún lado: al escribir el ciclo de release se
+  rompió sistemáticamente (25% de identificadores en español en lo nuevo, contra ~2%
+  preexistente). Se renombraron 209 identificadores al inglés y la regla quedó como sexta
+  regla de oro en `CONTRIBUTING.md`, con una excepción deliberada: **`autor` se queda**. No
+  es código, es un campo del `implements.yaml` y parte del contrato del método (ADR-0004);
+  renombrarlo sería romper un contrato para ganar consistencia interna.
+- **ADR-0008** documenta el relevamiento que falta para poder ejecutar el i18n.
+- **484 tests** (+9 desde la 0.15.0): las tablas ADF en las dos direcciones —incluido el
+  ida y vuelta markdown → ADF → markdown, que es el que protege la metadata de `dai
+  edit-us`— y la primera cobertura de integración de `dai release done`, que era casi todo
+  efecto y no tenía ninguna: el ciclo completo contra un repo con remoto de verdad, el caso
+  del forge que se adelantó, y las dos negativas a taguear.
+
 ## [0.15.0] — 2026-09-09
 
 **Un equipo puede tener el link QUÉ↔CÓMO perfecto y seguir sin poder contestar la pregunta
@@ -988,6 +1043,7 @@ 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.15.1]: https://github.com/dforce2055/dai/releases/tag/v0.15.1
 [0.15.0]: https://github.com/dforce2055/dai/releases/tag/v0.15.0
 [0.14.0]: https://github.com/dforce2055/dai/releases/tag/v0.14.0
 [0.13.3]: https://github.com/dforce2055/dai/releases/tag/v0.13.3

package/CONTRIBUTING.md

@@ -41,6 +41,28 @@ git config core.hooksPath .githooks   # valida convención de commits + autoría
    (Cursor, Copilot, Claude, …). Un agente puede ayudarte, pero el cambio lo firmas
    tú: con tu identidad y sin el trailer del agente. Un check de CI lo bloquea en cada
    PR (ver [`governance/human-authorship.md`](governance/human-authorship.md)).
+6. **Código en inglés, comentarios en español.** Los identificadores —variables,
+   funciones, constantes, claves de objeto— van en **inglés**; los comentarios y la
+   documentación, en **español**. Y todo lo que sale por una interfaz de máquina
+   (`--json`, el payload de un webhook, los códigos de estado internos) va en inglés
+   también: es una API, la lee un script, y traducirla después rompe a quien la consume.
+
+   ```js
+   // El endpoint ES la credencial: quien lo tiene, postea.   ← comentario en español
+   export function describeTarget(cfg) {                      ← código en inglés
+     const target = new URL(cfg.endpoint).host;
+   ```
+
+   **La excepción, y es una sola:** los nombres de campo del `implements.yaml` son
+   parte del contrato del método, no del código. `autor:` se llama así en el schema
+   (ADR-0004) y en todos los repos que ya lo usan; renombrarlo sería romper el
+   contrato para ganar consistencia interna, que es el peor cambio posible.
+
+   Lo que **todavía no** cumple esta regla son los **mensajes al usuario**, que hoy son
+   literales en español repartidos por todo el CLI. Eso no es un descuido: es el
+   refactor que [ADR-0008](docs/adr/0008-estrategia-de-i18n.md) tiene planificado como
+   fase 3 (`DAI_LANG` + un catálogo `t(key)` sin dependencias). Mientras tanto, escribí
+   los mensajes en español y **no inventes un mecanismo de traducción propio**.
 
 ## Flujo (la propia metodología)
 

package/VERSION

@@ -1 +1 @@
-0.15.0
+0.15.1

package/cli/dai.mjs

@@ -33,7 +33,7 @@ import { listPrCmd, parsePrList, updatePrCmd, updatePrApiCmd, isAlreadyExistsErr
 import { parseCommitLog, proposeBump, nextVersion, buildManifest, renderManifest, BUMP_CAVEAT } from "./lib/release-plan.mjs";
 import { bumpPackageJson, bumpVersionFile, changelogEntry, insertChangelogEntry, changelogSection, changelogGaps, releaseBranch, tagName, normalizeVersion } from "./lib/release-files.mjs";
 import { notifyConfig, describeTarget, renderNotice, sendNotice, formatFecha } from "./lib/notify.mjs";
-import { releaseMarker, alreadyStamped, renderReleaseStamp, stampPlan, renderStampPlan, stampWarning, SIN_ESTAMPAR } from "./lib/release-stamp.mjs";
+import { releaseMarker, alreadyStamped, renderReleaseStamp, stampPlan, renderStampPlan, stampWarning, NOT_STAMPED_NOTE } from "./lib/release-stamp.mjs";
 import { parseImplements } from "./lib/implements.mjs";
 import { absolutizeSiteLinks } from "./lib/docs-links.mjs";
 import { diagnoseGitSsh, pushFailureHint, WINDOWS_OPENSSH } from "./lib/git-ssh.mjs";
@@ -353,9 +353,9 @@ function ciBranch() {
 // lo hace pasar por verificado (issue #46). No cambia el exit code — el hash manda.
 function versionDriftHint(im, live) {
   const declared = String(im?.version ?? "").trim();
-  const real = String(live?.spec_version ?? "").trim();
-  if (!real || declared === real) return;
-  warn(`${im.id}: el link declara version '${declared || "(vacío)"}' y la US viva dice '${real}'.`);
+  const liveVersion = String(live?.spec_version ?? "").trim();
+  if (!liveVersion || declared === liveVersion) return;
+  warn(`${im.id}: el link declara version '${declared || "(vacío)"}' y la US viva dice '${liveVersion}'.`);
   process.stdout.write(`    Ese número se publica en la PR y se estampa en el tracker. Corregilo:  dai link-us ${im.id} --resync\n`);
 }
 
@@ -366,7 +366,7 @@ async function cmdCheck() {
   const adapter = getAdapter(process.env);
   const found = discoverImplements(process.cwd(), { includeArchived: false });
   let worst = 0, n = 0;
-  const atrasadas = [];
+  const stale = [];
   for (const f of found) for (const im of f.implements || []) {
     if (isPlaceholderId(im.id)) continue;   // plantilla sin completar, no es una US real
     n++;
@@ -378,7 +378,7 @@ async function cmdCheck() {
     }
     else if (status === "atrasado") {
       process.stdout.write(`⚠️  ${im.id} ATRASADO: implementaste ${im.ac_hash}, la US viva es ${live.ac_hash}${live.spec_version ? ` (${live.spec_version})` : ""}\n`);
-      atrasadas.push(im.id);
+      stale.push(im.id);
       worst = Math.max(worst, 1);
     } else if (status === "sin-respuesta") {
       // No es "no hay US": es "no pude preguntar". Antes moría acá con `fetch failed` y sin
@@ -391,9 +391,9 @@ async function cmdCheck() {
     }
   }
   if (n === 0) process.stdout.write("No hay implements.yaml para chequear.\n");
-  if (atrasadas.length) {
+  if (stale.length) {
     process.stdout.write("\n  El QUÉ cambió desde que lo implementaste. Para resincronizar:\n");
-    for (const id of atrasadas) process.stdout.write(`    dai link-us ${id} --resync     # re-estampa el ac_hash contra la US viva\n`);
+    for (const id of stale) process.stdout.write(`    dai link-us ${id} --resync     # re-estampa el ac_hash contra la US viva\n`);
     process.stdout.write("  Después, revisa si tu implementación cubre el criterio nuevo.\n");
   }
   process.exitCode = worst;
@@ -1091,8 +1091,8 @@ async function cmdPr(opts) {
   const existing = findExistingPr(tool, branch);
 
   // 4. Mostrar y pedir confirmación (acción hacia afuera).
-  const accion = existing ? `a ACTUALIZAR (#${existing.number})` : "a crear";
-  process.stdout.write(`\n  ── Pull Request ${accion} ──────────────────────────────\n`);
+  const action = existing ? `a ACTUALIZAR (#${existing.number})` : "a crear";
+  process.stdout.write(`\n  ── Pull Request ${action} ──────────────────────────────\n`);
   process.stdout.write(`  título:   ${title}\n  de:       ${branch}\n`);
   process.stdout.write(`  a:        ${base}  ${C.dim(`(${baseSource}${baseWhy ? ` — ${baseWhy}` : ""})`)}${toProd ? `   ${C.b("⚠️  DESPLIEGA A PRODUCCIÓN")}` : ""}\n`);
   process.stdout.write(`  US:       ${id || C.dim("(sin US)")}  ${C.dim(`— ${usWhy}`)}\n`);
@@ -1284,16 +1284,16 @@ function linkedInRange(range) {
     raw = git(["log", "--format=\x1e%H", "--name-only", "--diff-filter=AMR", range, "--", "*implements.yaml"]);
   } catch { return rows; }
   let order = 0;
-  for (const bloque of raw.split("\x1e")) {
-    const lineas = bloque.split("\n").map((l) => l.trim()).filter(Boolean);
-    if (lineas.length === 0) continue;
-    const sha = lineas[0];
-    for (const path of lineas.slice(1)) {
+  for (const chunk of raw.split("\x1e")) {
+    const outLines = chunk.split("\n").map((l) => l.trim()).filter(Boolean);
+    if (outLines.length === 0) continue;
+    const sha = outLines[0];
+    for (const path of outLines.slice(1)) {
       if (!path.endsWith("implements.yaml")) continue;
-      let texto;
-      try { texto = git(["show", `${sha}:${path}`]); } catch { continue; }   // borrado después
+      let text;
+      try { text = git(["show", `${sha}:${path}`]); } catch { continue; }   // borrado después
       let parsed;
-      try { parsed = parseImplements(texto); } catch { continue; }
+      try { parsed = parseImplements(text); } catch { continue; }
       for (const im of parsed.implements || []) {
         if (isPlaceholderId(im.id)) continue;
         rows.push({ ...im, change: parsed.change, repo: parsed.repo, path, sha, order: order++ });
@@ -1307,11 +1307,11 @@ function linkedInRange(range) {
 // contestar "qué entra en esta versión" — si cada comando lo calculara a su manera,
 // tarde o temprano dirían cosas distintas y le creerías al que tenés más a mano.
 async function releaseManifest(opts = {}, { from, to } = {}) {
-  const desde = from ?? (textOpt(opts, "from") || lastTag());
-  const hasta = to ?? (textOpt(opts, "to") || branchFlow(process.env).dev || gitBranch());
-  const toRev = resolveRev(hasta) || resolveRev(`origin/${hasta}`);
-  if (!toRev) fail(`no encuentro '${hasta}' (ni local ni en origin/${hasta}).\n  Traelo primero:  git fetch origin ${hasta}`, 1);
-  const range = desde ? `${desde}..${toRev}` : toRev;
+  const fromRef = from ?? (textOpt(opts, "from") || lastTag());
+  const toRef = to ?? (textOpt(opts, "to") || branchFlow(process.env).dev || gitBranch());
+  const toRev = resolveRev(toRef) || resolveRev(`origin/${toRef}`);
+  if (!toRev) fail(`no encuentro '${toRef}' (ni local ni en origin/${toRef}).\n  Traelo primero:  git fetch origin ${toRef}`, 1);
+  const range = fromRef ? `${fromRef}..${toRev}` : toRev;
 
   let commits = [];
   try { commits = parseCommitLog(git(["log", "--format=%H\x1f%s", range])); }
@@ -1335,7 +1335,7 @@ async function releaseManifest(opts = {}, { from, to } = {}) {
   // declararla nunca. Se mira el repo entero, no el rango.
   const repoUsesStories = flattenImplements(discoverImplements(process.cwd())).length > 0;
   const m = buildManifest({ commits, linked, live, unreachable: unreachable || Boolean(opts.noNetwork), repoUsesStories });
-  return { manifest: m, commits, from: desde, to: hasta, range };
+  return { manifest: m, commits, from: fromRef, to: toRef, range };
 }
 
 // La versión que este repo declara hoy. `null` si no espeja el número en ningún archivo
@@ -1386,31 +1386,31 @@ async function cmdReleaseCut(versionArg, opts = {}) {
   const { manifest: m, commits, from, to } = await releaseManifest(opts);
   const { version: current, file: versionFile } = currentVersion();
   const { bump, reason } = proposeBump(commits);
-  const sugerida = current ? nextVersion(current, bump) : null;
+  const suggested = current ? nextVersion(current, bump) : null;
 
   // Qué archivos espejan el número en ESTE repo. Puede no haber ninguno (un repo .NET, un
   // frontend corporativo): el tag sigue siendo la versión.
-  const espejos = [];
+  const mirrors = [];
   for (const [file, fn] of [["VERSION", bumpVersionFile], ["package.json", bumpPackageJson]]) {
     const p = join(process.cwd(), file);
     if (!existsSync(p)) continue;
     const r = fn(readFileSync(p, "utf8"), version);
-    espejos.push({ file, path: p, ...r });
+    mirrors.push({ file, path: p, ...r });
   }
 
-  const crearBranch = opts.branch !== false && !opts.noBranch;
-  const nombreBranch = releaseBranch(version);
+  const makeBranch = opts.branch !== false && !opts.noBranch;
+  const releaseBranchName = releaseBranch(version);
 
   process.stdout.write("\n" + renderManifest(m, { from, to, current: current || "(sin archivo)", proposed: version, bump: `pediste ${version}`, reason }) + "\n");
   process.stdout.write(`\n  ── Se va a preparar ─────────────────────────────────\n`);
-  process.stdout.write(`  versión:  ${version}${sugerida && sugerida !== version ? C.dim(`   (dai habría propuesto ${sugerida} — ${bump})`) : ""}\n`);
-  process.stdout.write(`  branch:   ${crearBranch ? `${nombreBranch}  (desde ${branch})` : C.dim("ninguna — se taguea desde la rama de integración")}\n`);
-  for (const e of espejos) process.stdout.write(`  ${e.file.padEnd(9)} ${e.changed ? `${e.from} → ${version}` : C.dim(`ya está en ${version}`)}\n`);
-  if (espejos.length === 0) process.stdout.write(`  ${C.dim("este repo no espeja el número en ningún archivo que dai reconozca: la versión es el tag")}\n`);
+  process.stdout.write(`  versión:  ${version}${suggested && suggested !== version ? C.dim(`   (dai habría propuesto ${suggested} — ${bump})`) : ""}\n`);
+  process.stdout.write(`  branch:   ${makeBranch ? `${releaseBranchName}  (desde ${branch})` : C.dim("ninguna — se taguea desde la rama de integración")}\n`);
+  for (const e of mirrors) process.stdout.write(`  ${e.file.padEnd(9)} ${e.changed ? `${e.from} → ${version}` : C.dim(`ya está en ${version}`)}\n`);
+  if (mirrors.length === 0) process.stdout.write(`  ${C.dim("este repo no espeja el número en ningún archivo que dai reconozca: la versión es el tag")}\n`);
   process.stdout.write(`  CHANGELOG entrada nueva para ${version} (con el manifiesto para repartir)\n`);
   process.stdout.write(`  commit:   chore(release): v${version}\n`);
   process.stdout.write(`  ─────────────────────────────────────────────────────\n`);
-  if (m.counts.atrasadas > 0) warn(`vas a cortar una versión con ${m.counts.atrasadas} US ATRASADA(S). Revisalas o resincronizá antes.`);
+  if (m.counts.stale > 0) warn(`vas a cortar una versión con ${m.counts.stale} US ATRASADA(S). Revisalas o resincronizá antes.`);
   if (m.orphans.length) warn(`hay ${m.orphans.length} branch(es) sin US ni prefijo exento en el rango.`);
 
   if (opts.dryRun) { info("[dry-run] no se tocó nada."); return; }
@@ -1420,35 +1420,35 @@ async function cmdReleaseCut(versionArg, opts = {}) {
     if (!["s", "si", "sí", "y", "yes"].includes(a)) { info("Cancelado — no se tocó nada."); return; }
   }
 
-  if (crearBranch) {
-    try { git(["checkout", "-b", nombreBranch]); ok(`branch ${nombreBranch}`); }
-    catch (e) { fail(`no pude crear '${nombreBranch}': ${String(e.message).split("\n")[0]}`, 1); }
+  if (makeBranch) {
+    try { git(["checkout", "-b", releaseBranchName]); ok(`branch ${releaseBranchName}`); }
+    catch (e) { fail(`no pude crear '${releaseBranchName}': ${String(e.message).split("\n")[0]}`, 1); }
   }
-  const tocados = [];
-  for (const e of espejos) {
+  const touched = [];
+  for (const e of mirrors) {
     if (!e.changed) continue;
     writeFileSync(e.path, e.text);
-    tocados.push(e.file);
+    touched.push(e.file);
     ok(`${e.file}: ${e.from} → ${version}`);
   }
 
   // CHANGELOG: el andamio y el material. La prosa la escribe una persona (o la skill).
   const chPath = join(process.cwd(), "CHANGELOG.md");
   const entry = changelogEntry({ version, date: new Date().toISOString().slice(0, 10), manifest: m });
-  const previo = existsSync(chPath) ? readFileSync(chPath, "utf8") : "# Changelog\n";
+  const previousChangelog = existsSync(chPath) ? readFileSync(chPath, "utf8") : "# Changelog\n";
   const repoUrl = (() => { const p = parseRemote(gitRemote()); return p ? `https://${p.host}/${p.path}` : null; })();
-  const res = insertChangelogEntry(previo, entry, { version, repoUrl });
-  if (res.changed) { writeFileSync(chPath, res.text); tocados.push("CHANGELOG.md"); ok(`CHANGELOG.md: entrada para ${version}`); }
+  const res = insertChangelogEntry(previousChangelog, entry, { version, repoUrl });
+  if (res.changed) { writeFileSync(chPath, res.text); touched.push("CHANGELOG.md"); ok(`CHANGELOG.md: entrada para ${version}`); }
   else warn(`CHANGELOG.md sin tocar — ${res.reason}.`);
 
-  if (tocados.length === 0) { warn("no hubo nada que cambiar: no hago un commit vacío."); return; }
-  git(["add", ...tocados]);
+  if (touched.length === 0) { warn("no hubo nada que cambiar: no hago un commit vacío."); return; }
+  git(["add", ...touched]);
   git(["commit", "-m", `chore(release): v${version}`, "-m", `Manifiesto: ${m.counts.stories} US · ${m.counts.commits} commits desde ${from || "el principio"}.`]);
   ok(`commit chore(release): v${version}`);
 
   process.stdout.write("\n");
   info("Falta lo que dai no puede escribir por vos: repartí el manifiesto del CHANGELOG y contá el porqué.");
-  info(`Después:  dai pr${crearBranch ? "" : ""}   →   se mergea   →   dai release done ${version}`);
+  info(`Después:  dai pr${makeBranch ? "" : ""}   →   se mergea   →   dai release done ${version}`);
 }
 
 // ── release done: cerrar la versión ────────────────────────────────────────
@@ -1481,20 +1481,24 @@ async function cmdReleaseDone(versionArg, opts = {}) {
   const notes = existsSync(join(process.cwd(), "CHANGELOG.md"))
     ? changelogSection(readFileSync(join(process.cwd(), "CHANGELOG.md"), "utf8"), version) : null;
   const cfg = (() => { try { return notifyConfig(process.env); } catch (e) { warn(String(e.message)); return null; } })();
-  const avisar = cfg && !opts.noNotify;
+  const willNotify = cfg && !opts.noNotify;
 
   process.stdout.write(`\n  ── Cerrar la versión ${version} ──────────────────────────\n`);
   process.stdout.write(`  tag:      ${tag} → ${prod} @ ${String(head).slice(0, 8)}\n`);
   process.stdout.write(`  release:  ${opts.noRelease ? C.dim("no (--no-release)") : `nota en el forge${notes ? "" : C.dim(" (sin sección del CHANGELOG: sale con las notas del forge)")}`}\n`);
   process.stdout.write(`  back-merge: ${dev ? `${prod} → ${dev}` : C.dim("no (DAI_BRANCH_DEV no declarada)")}\n`);
   const relBranch = releaseBranch(version);
-  const hayLocal = Boolean(safeGit(["rev-parse", "--verify", "--quiet", relBranch]));
-  const hayRemota = Boolean(safeGit(["rev-parse", "--verify", "--quiet", `origin/${relBranch}`]));
-  const limpiar = (hayLocal || hayRemota) && !opts.keepBranch;
-  process.stdout.write(`  limpieza: ${limpiar
-    ? `borrar ${relBranch}${hayLocal ? " (local)" : ""}${hayLocal && hayRemota ? " +" : ""}${hayRemota ? " (remota)" : ""}`
-    : C.dim(hayLocal || hayRemota ? "no (--keep-branch)" : "nada que borrar")}\n`);
-  process.stdout.write(`  aviso:    ${avisar ? describeTarget(cfg) : C.dim(cfg ? "no (--no-notify)" : "no (DAI_NOTIFY no declarado)")}\n`);
+  const hasLocal = Boolean(safeGit(["rev-parse", "--verify", "--quiet", relBranch]));
+  // Se pregunta al REMOTO, no a `origin/<branch>`: esa ref local queda desactualizada
+  // cuando el forge borra la rama al mergear (auto-delete on merge, que es lo normal), y
+  // dai terminaba intentando borrar algo que ya no estaba y reportando un ⚠ por un estado
+  // que en realidad era el correcto. Avisar de un problema inexistente enseña a ignorar los avisos.
+  const hasRemote = Boolean(safeGit(["ls-remote", "--heads", "origin", relBranch])?.trim());
+  const willCleanup = (hasLocal || hasRemote) && !opts.keepBranch;
+  process.stdout.write(`  limpieza: ${willCleanup
+    ? `borrar ${relBranch}${hasLocal ? " (local)" : ""}${hasLocal && hasRemote ? " +" : ""}${hasRemote ? " (remota)" : ""}`
+    : C.dim(hasLocal || hasRemote ? "no (--keep-branch)" : "nada que borrar")}\n`);
+  process.stdout.write(`  aviso:    ${willNotify ? describeTarget(cfg) : C.dim(cfg ? "no (--no-notify)" : "no (DAI_NOTIFY no declarado)")}\n`);
   process.stdout.write(`  ─────────────────────────────────────────────────────\n`);
   if (opts.dryRun) { info("[dry-run] no se tocó nada."); return; }
   if (!opts.yes) {
@@ -1552,33 +1556,40 @@ async function cmdReleaseDone(versionArg, opts = {}) {
   // no pasa acá, se acumulan — y una rama de release que sobrevive a su release es un fork.
   // Misma disciplina que `dai done`: `git branch -d` (minúscula) se niega si no está
   // mergeada, así que la red de seguridad la pone git, no una suposición nuestra.
-  if (limpiar) {
-    if (hayLocal) {
+  if (willCleanup) {
+    if (hasLocal) {
       try { git(["branch", "-d", relBranch]); ok(`borrada la branch local ${relBranch}`); }
       catch (e) {
         warn(`no borré '${relBranch}' local: ${String(e.message).split("\n")[0]}`);
         process.stdout.write(`  git se niega a borrar una branch sin mergear. Revisala: quizá tiene commits que no llegaron a '${prod}'.\n`);
       }
     }
-    if (hayRemota) {
+    if (hasRemote) {
       try {
         git(["push", "origin", "--delete", relBranch], { stdio: ["inherit", "pipe", "inherit"], env: { ...process.env, GIT_TERMINAL_PROMPT: "1" } });
         ok(`borrada la branch remota origin/${relBranch}`);
       } catch (e) {
         warn(`no borré 'origin/${relBranch}': ${String(e.message).split("\n")[0]}`);
-        process.stdout.write(`  Puede que ya la haya borrado el forge al mergear. Si no:  git push origin --delete ${relBranch}\n`);
+        process.stdout.write(`  Borrala a mano:  git push origin --delete ${relBranch}\n`);
+      }
+    } else if (hasLocal) {
+      // La ref local puede seguir apuntando a una rama que el forge ya borró. Se limpia
+      // para que el próximo `git branch -r` no muestre un fantasma.
+      if (safeGit(["rev-parse", "--verify", "--quiet", `origin/${relBranch}`])) {
+        safeGit(["branch", "-dr", `origin/${relBranch}`]);
+        info(`la branch remota ya no estaba (la borró el forge al mergear); limpié la referencia local`);
       }
     }
   }
 
   // 5. El aviso. Lo último a propósito: anunciar algo que después falla es peor que no anunciar.
-  if (avisar) {
+  if (willNotify) {
     const ev = {
       event: "released", app: releaseApp(opts), version, environment: null,
       author: gitUser(), date: formatFecha(), url: releaseUrl,
       stories: m.stories.map((s) => ({ id: s.id, title: s.title })),
     };
-    await confirmarYAvisar(cfg, ev, opts);
+    await confirmAndNotify(cfg, ev, opts);
   }
   process.stdout.write("\n");
   ok(`versión ${version} cerrada.`);
@@ -1609,11 +1620,11 @@ async function cmdReleaseStamp(versionArg, opts = {}) {
 
   // El manifiesto de ESA versión: lo que entró entre el tag anterior y este. Se pide por
   // tag, no por rama, porque estampar es contar qué se desplegó — y lo desplegado es el tag.
-  const previo = safeGit(["describe", "--tags", "--abbrev=0", `${tag}^`])?.trim() || null;
+  const previousTag = safeGit(["describe", "--tags", "--abbrev=0", `${tag}^`])?.trim() || null;
   if (!safeGit(["rev-parse", "--verify", "--quiet", `${tag}^{commit}`])) {
     fail(`no existe el tag ${tag} en este repo.\n  Cerrá la versión primero:  dai release done ${version}\n  (o traé los tags:  git fetch --tags)`, 1);
   }
-  const { manifest: m } = await releaseManifest(opts, { from: previo, to: tag });
+  const { manifest: m } = await releaseManifest(opts, { from: previousTag, to: tag });
 
   // ¿Cuáles ya están estampadas? Sin poder leer los comentarios dai NO afirma que no las
   // estampó: lo dice, y quien decide es la persona. Afirmar de más acá se paga en duplicados.
@@ -1631,42 +1642,42 @@ async function cmdReleaseStamp(versionArg, opts = {}) {
   const plan = stampPlan({ stories: m.stories, stamped, unknown });
   process.stdout.write("\n" + renderStampPlan(plan, { app, version, environment, tracker: adapter.kind }) + "\n");
   warn(stampWarning(plan));
-  if (plan.pendientes.length === 0) { info("Nada que hacer."); return; }
+  if (plan.pending.length === 0) { info("Nada que hacer."); return; }
 
   if (opts.dryRun) { info("[dry-run] no se escribió nada."); return; }
   if (!opts.yes) {
     if (!process.stdin.isTTY) {
-      info(`Sin TTY y sin --yes: no estampo. Re-ejecutá con --yes si querés los ${plan.pendientes.length} comentarios.`);
+      info(`Sin TTY y sin --yes: no estampo. Re-ejecutá con --yes si querés los ${plan.pending.length} comentarios.`);
       return;
     }
-    const a = (await askOrCancel(`  ¿Estampo ${plan.pendientes.length} comentario(s)? (s/N) `) || "").toLowerCase();
+    const a = (await askOrCancel(`  ¿Estampo ${plan.pending.length} comentario(s)? (s/N) `) || "").toLowerCase();
     if (!["s", "si", "sí", "y", "yes"].includes(a)) {
       info("No se estampó nada — la release está hecha igual.");
-      info(SIN_ESTAMPAR);
+      info(NOT_STAMPED_NOTE);
       return;   // salida 0: decir que no es una respuesta válida, no un error
     }
   }
 
-  const cuerpo = renderReleaseStamp({
+  const body = renderReleaseStamp({
     app, version, environment, date: formatFecha(), commit: safeGit(["rev-list", "-n", "1", tag])?.trim(),
     url: textOpt(opts, "url") || null,
   });
-  let hechos = 0;
-  const fallados = [];
-  for (const s of plan.pendientes) {
-    try { await adapter.comment(s.id, cuerpo); hechos++; ok(`${s.id} estampada`); }
-    catch (e) { fallados.push(s.id); warn(`${s.id}: ${String(e.message).split("\n")[0]}`); }
-  }
-  if (fallados.length) {
-    warn(`quedaron ${fallados.length} sin estampar: ${fallados.join(", ")}. Volvé a correr el comando — las ya hechas se saltean.`);
+  let stampedCount = 0;
+  const failed = [];
+  for (const s of plan.pending) {
+    try { await adapter.comment(s.id, body); stampedCount++; ok(`${s.id} estampada`); }
+    catch (e) { failed.push(s.id); warn(`${s.id}: ${String(e.message).split("\n")[0]}`); }
+  }
+  if (failed.length) {
+    warn(`quedaron ${failed.length} sin estampar: ${failed.join(", ")}. Volvé a correr el comando — las ya hechas se saltean.`);
     process.exitCode = 1;
-  } else ok(`${hechos} US estampada(s) con ${app} ${tag} → ${environment.toUpperCase()}.`);
+  } else ok(`${stampedCount} US estampada(s) con ${app} ${tag} → ${environment.toUpperCase()}.`);
 
   // El aviso al canal es del EVENTO de despliegue, no del estampado: sale aunque no se
   // haya estampado nada (para eso está `--only-notify`), y no sale si el repo no lo declaró.
   const cfg = (() => { try { return notifyConfig(process.env); } catch (e) { warn(String(e.message)); return null; } })();
   if (cfg && !opts.noNotify) {
-    await confirmarYAvisar(cfg, {
+    await confirmAndNotify(cfg, {
       event: "deployed", app, version, environment, author: gitUser(), date: formatFecha(),
       url: textOpt(opts, "url") || null, stories: m.stories.map((x) => ({ id: x.id, title: x.title })),
     }, opts);
@@ -1703,21 +1714,21 @@ async function cmdReleaseStatus(opts = {}) {
 
   // Back-merge pendiente: producción adelante de integración es el olvido clásico.
   if (prod && flow.dev) {
-    const pendiente = safeGit(["rev-list", "--count", `${flow.dev}..${prod}`])?.trim();
-    if (pendiente && Number(pendiente) > 0) {
-      warn(`'${prod}' está ${pendiente} commit(s) adelante de '${flow.dev}': falta el back-merge.`);
+    const behind = safeGit(["rev-list", "--count", `${flow.dev}..${prod}`])?.trim();
+    if (behind && Number(behind) > 0) {
+      warn(`'${prod}' está ${behind} commit(s) adelante de '${flow.dev}': falta el back-merge.`);
       process.stdout.write(`    git checkout ${flow.dev} && git merge ${prod} && git push origin ${flow.dev}\n`);
     }
   }
 
   // Branches de release abiertas (model B): una que sobrevive a su release es un fork.
-  const abiertas = (safeGit(["branch", "--list", "release/*", "--format=%(refname:short)"]) || "")
+  const openBranches = (safeGit(["branch", "--list", "release/*", "--format=%(refname:short)"]) || "")
     .split("\n").map((x) => x.trim()).filter(Boolean);
-  if (abiertas.length) {
-    warn(`${abiertas.length} branch(es) de release sin borrar: ${abiertas.join(", ")}`);
+  if (openBranches.length) {
+    warn(`${openBranches.length} branch(es) de release sin borrar: ${openBranches.join(", ")}`);
     process.stdout.write(`    Una rama de release que sobrevive a su release es un fork. Desde 0.15.0 las borra\n`);
     process.stdout.write(`    \`dai release done\`; las de antes se limpian a mano (git se niega si alguna no está mergeada):\n`);
-    process.stdout.write(`      git branch -d ${abiertas.join(" ")}\n`);
+    process.stdout.write(`      git branch -d ${openBranches.join(" ")}\n`);
   }
 
   const cfg = (() => { try { return notifyConfig(process.env); } catch { return null; } })();
@@ -1730,8 +1741,8 @@ async function cmdReleaseStatus(opts = {}) {
     try {
       const out = execFileSync(tool, ["release", "list", ...(tool === "gh" ? ["--limit", "3"] : ["--per-page", "3"])],
         { encoding: "utf8", cwd: process.cwd(), stdio: ["ignore", "pipe", "pipe"] });
-      const lineas = String(out).split("\n").filter(Boolean).slice(0, 3);
-      if (lineas.length) { info("últimos releases publicados:"); for (const l of lineas) process.stdout.write(`    ${l}\n`); }
+      const outLines = String(out).split("\n").filter(Boolean).slice(0, 3);
+      if (outLines.length) { info("últimos releases publicados:"); for (const l of outLines) process.stdout.write(`    ${l}\n`); }
     } catch { /* sin binario, sin auth o sin releases: no es un problema que resolver acá */ }
   }
 }
@@ -1745,7 +1756,7 @@ async function cmdReleaseNotify(opts = {}) {
   try { cfg = notifyConfig(process.env); } catch (e) { fail(String(e.message), 1); }
   if (!cfg) fail("no hay canal declarado: poné DAI_NOTIFY (y DAI_NOTIFY_WEBHOOK) en el .env.dai.", 1);
   if (!opts.test) fail("por ahora `dai release notify` solo sabe probar el canal:  dai release notify --test", 2);
-  await confirmarYAvisar(cfg, { event: "test" }, opts);
+  await confirmAndNotify(cfg, { event: "test" }, opts);
 }
 
 // El nombre de la app en los avisos y en el stamp. Sale del repo, no de una variable
@@ -1756,7 +1767,7 @@ function releaseApp(opts) {
 
 // Mostrar el mensaje EXACTO que va a salir y pedir confirmación. Un mensaje a un canal de
 // equipo no se desmanda: se muestra antes, siempre, aunque el aviso sea de una sola línea.
-async function confirmarYAvisar(cfg, ev, opts = {}) {
+async function confirmAndNotify(cfg, ev, opts = {}) {
   const msg = renderNotice(ev);
   process.stdout.write(`\n  ── Aviso a ${describeTarget(cfg)} ──\n`);
   process.stdout.write(msg.split("\n").map((l) => `  │ ${l}`).join("\n") + "\n");
@@ -2169,14 +2180,14 @@ function cmdDocs(dest) {
   // repo de nadie: las capturas de los tutoriales ni siquiera viajan en el paquete npm
   // (issue #37). Se saltea, y los links que las nombran se absolutizan contra el sitio.
   cpSync(join(ROOT, "docs"), dest, { recursive: true, filter: (src) => !/[/\\]public([/\\]|$)/.test(src) });
-  let reescritos = 0;
+  let rewritten = 0;
   for (const f of walkMd(dest)) {
     const md = readFileSync(f, "utf8");
     const out = absolutizeSiteLinks(md);
-    if (out !== md) { writeFileSync(f, out); reescritos++; }
+    if (out !== md) { writeFileSync(f, out); rewritten++; }
   }
   ok(`documentación copiada a ${dest}`);
-  if (reescritos) info(`${reescritos} documento(s) con capturas: los links apuntan al sitio publicado.`);
+  if (rewritten) info(`${rewritten} documento(s) con capturas: los links apuntan al sitio publicado.`);
 }
 
 // Los .md de un árbol, para la reescritura de links de cmdDocs.
@@ -2437,13 +2448,13 @@ function cmdDoctor() {
   if (localActive.length && existsSync(join(cwd, "openspec"))) {
     info("OpenSpec — los comandos van en el chat del asistente, no en la terminal:");
     for (const a of localActive) {
-      const faltan = OPSX_IDS.filter((id) => !existsSync(opsxPath(a.kind, id)));
-      if (faltan.length === OPSX_IDS.length) {
+      const missing = OPSX_IDS.filter((id) => !existsSync(opsxPath(a.kind, id)));
+      if (missing.length === OPSX_IDS.length) {
         warn(`${a.label}: no hay comandos opsx. Generalos:  openspec init --tools ${OPENSPEC_TOOL[a.kind]} --force`);
       } else {
         const hay = OPSX_IDS.filter((id) => existsSync(opsxPath(a.kind, id)));
         ok(`${a.label}: ${hay.map((id) => opsxCommand(a.kind, id)).join(" · ")}`);
-        if (faltan.length) warn(`${a.label}: faltan ${faltan.join(", ")} — regenerá con \`openspec init --tools ${OPENSPEC_TOOL[a.kind]} --force\``);
+        if (missing.length) warn(`${a.label}: faltan ${missing.join(", ")} — regenerá con \`openspec init --tools ${OPENSPEC_TOOL[a.kind]} --force\``);
       }
     }
     process.stdout.write("    (el nombre sale del archivo que genera OpenSpec: solo Claude usa los dos puntos)\n");

package/cli/lib/bootstrap.mjs

@@ -169,7 +169,7 @@ export function envFor(pm) {
   // Flujo de branches: sin esto, `dai pr` tiene que adivinar la base, y en un repo con
   // ramas de ambiente adivinar significa proponer un merge a producción (issue #46).
   // Van vacías a propósito: vacío = "no declarada", y dai cae a la default del remoto.
-  const flujo =
+  const flowBlock =
     "\n# ── Flujo de branches (dai pr · dai done) ─────────────────────────────────\n" +
     "# Las DOS ramas de vida larga del repo. La base de una PR sale del TIPO de branch:\n" +
     "#   feature/ · fix/     → PR contra DAI_BRANCH_DEV\n" +
@@ -178,7 +178,7 @@ export function envFor(pm) {
     "DAI_BRANCH_DEV=\n" +
     "DAI_BRANCH_PROD=\n";
   if (pm === "clickup") {
-    return head + "DAI_PM=clickup\nDAI_CLICKUP_TOKEN=\nDAI_CLICKUP_LIST_ID=\n" + flujo;
+    return head + "DAI_PM=clickup\nDAI_CLICKUP_TOKEN=\nDAI_CLICKUP_LIST_ID=\n" + flowBlock;
   }
   if (pm === "jira") {
     return head +
@@ -192,9 +192,9 @@ export function envFor(pm) {
       "# Solo si tu Jira exige campos propios AL CREAR una US (lo usa grill-user-story,\n" +
       "# no hace falta para leerlas). El default ya es .dai/jira-fields.json; descomentá\n" +
       "# solo para apuntar a otra ruta. Si el archivo no existe, se ignora.\n" +
-      "# DAI_JIRA_FIELDS_FILE=.dai/jira-fields.json\n" + flujo;
+      "# DAI_JIRA_FIELDS_FILE=.dai/jira-fields.json\n" + flowBlock;
   }
-  return head + "DAI_PM=md\nDAI_MD_US_DIR=.dai/us\n" + flujo;
+  return head + "DAI_PM=md\nDAI_MD_US_DIR=.dai/us\n" + flowBlock;
 }
 
 // ── Helpers aditivos para `dai init` — no destruir la config de un repo vivo ──

package/cli/lib/branch-flow.mjs

@@ -29,7 +29,7 @@ export function branchFlow(env = {}) {
 
 // Los tipos de branch que van contra producción: una release que se corta y un hotfix
 // que sale del tag que está en PRO. El resto integra.
-const HACIA_PROD = new Set(["release", "hotfix"]);
+const PROD_BOUND_TYPES = new Set(["release", "hotfix"]);
 
 // Resuelve la base de una PR y —tan importante como el valor— POR QUÉ es esa.
 //   --base > el mapa de ramas según el tipo de branch > rama default del remoto > main
@@ -38,9 +38,9 @@ export function resolveBase({ flag, branch = null, env = {}, originHead = null }
   if (explicit) return { base: explicit, source: "--base", reason: null };
 
   const flow = branchFlow(env);
-  const tipo = branchType(branch);
-  if (HACIA_PROD.has(tipo) && flow.prod) {
-    return { base: flow.prod, source: "DAI_BRANCH_PROD (.env.dai)", reason: `la branch es ${tipo}/` };
+  const branchKind = branchType(branch);
+  if (PROD_BOUND_TYPES.has(branchKind) && flow.prod) {
+    return { base: flow.prod, source: "DAI_BRANCH_PROD (.env.dai)", reason: `la branch es ${branchKind}/` };
   }
   if (flow.dev) {
     return { base: flow.dev, source: "DAI_BRANCH_DEV (.env.dai)", reason: null };
@@ -61,12 +61,12 @@ export function isProdBranch(base, env = {}) {
 }
 
 // Las fuentes que YA son una decisión de alguien: no hay nada que avisar.
-const DECIDIDAS = new Set(["--base", "DAI_BRANCH_DEV (.env.dai)", "DAI_BRANCH_PROD (.env.dai)", "lo respondiste vos"]);
+const DECIDED_SOURCES = new Set(["--base", "DAI_BRANCH_DEV (.env.dai)", "DAI_BRANCH_PROD (.env.dai)", "lo respondiste vos"]);
 
 // El aviso que va debajo del preview cuando la base salió de un default. Desaparece en
 // cuanto el repo declara su mapa de ramas, que es justo lo que se le pide.
 export function baseHint(source, base) {
-  if (DECIDIDAS.has(source)) return null;
+  if (DECIDED_SOURCES.has(source)) return null;
   return `la base '${base}' salió de ${source} — dai no sabe cuáles son las ramas de vida larga de este repo. Declaralas una vez en el .env.dai:\n` +
          `    DAI_BRANCH_DEV=<rama-que-integra>   ·   DAI_BRANCH_PROD=<rama-que-despliega-a-PRO>\n` +
          `    Con eso: feature/ y fix/ van contra DEV; release/ y hotfix/ contra PROD (con confirmación).`;

package/cli/lib/notify.mjs

@@ -26,7 +26,7 @@
 import { daiFetch } from "./http.mjs";
 
 // El envelope de cada canal. Esto es el adaptador entero.
-const CANALES = {
+const CHANNELS = {
   discord:  (msg) => ({ content: msg }),
   slack:    (msg) => ({ text: msg }),
   webex:    (msg) => ({ markdown: msg }),
@@ -37,7 +37,7 @@ const CANALES = {
   webhook:  (msg, cfg, ev) => ({ ...eventFields(ev), text: msg }),
 };
 
-export const CANALES_VALIDOS = Object.keys(CANALES);
+export const VALID_CHANNELS = Object.keys(CHANNELS);
 
 // ── Config ───────────────────────────────────────────────────────────────────
 // Devuelve null cuando el repo no declaró canal: no avisar es el default, y un default
@@ -45,9 +45,9 @@ export const CANALES_VALIDOS = Object.keys(CANALES);
 export function notifyConfig(env = {}) {
   const channel = String(env.DAI_NOTIFY ?? "").trim().toLowerCase();
   if (channel === "" || channel === "none") return null;
-  if (!CANALES[channel]) {
+  if (!CHANNELS[channel]) {
     throw new Error(
-      `DAI_NOTIFY='${channel}' no es un canal que dai conozca (${CANALES_VALIDOS.join(" | ")} | none).\n` +
+      `DAI_NOTIFY='${channel}' no es un canal que dai conozca (${VALID_CHANNELS.join(" | ")} | none).\n` +
       `  Para un destino propio —Teams, Mattermost, un sistema interno— usá 'webhook':\n` +
       `  manda los campos del release en JSON y tu endpoint hace lo que quiera con ellos.`,
     );
@@ -121,10 +121,10 @@ function eventFields(ev = {}) {
 // diferencia entre el QUÉ y el CÓMO que sostiene todo el método.
 const MAX_BULLETS = 8;
 
-const dosDigitos = (n) => String(n).padStart(2, "0");
+const pad2 = (n) => String(n).padStart(2, "0");
 export function formatFecha(d = new Date()) {
-  return `${dosDigitos(d.getDate())}/${dosDigitos(d.getMonth() + 1)}/${d.getFullYear()} ` +
-         `${dosDigitos(d.getHours())}:${dosDigitos(d.getMinutes())}`;
+  return `${pad2(d.getDate())}/${pad2(d.getMonth() + 1)}/${d.getFullYear()} ` +
+         `${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
 }
 
 export function renderNotice(ev = {}) {
@@ -161,7 +161,7 @@ export function renderNotice(ev = {}) {
 
 // El cuerpo que se le manda al canal.
 export function payloadFor(cfg, ev) {
-  const envelope = CANALES[cfg.channel];
+  const envelope = CHANNELS[cfg.channel];
   if (!envelope) throw new Error(`canal desconocido: ${cfg.channel}`);
   return envelope(renderNotice(ev), cfg, ev);
 }
@@ -190,16 +190,16 @@ export async function sendNotice(cfg, ev) {
 }
 
 export function explainNotifyError(cfg, status, body = "") {
-  const donde = describeTarget(cfg);
+  const target = describeTarget(cfg);
   if (status === 401 || status === 403) {
-    return `${donde} rechazó el aviso (${status}): el endpoint existe pero no autoriza.\n` +
+    return `${target} rechazó el aviso (${status}): el endpoint existe pero no autoriza.\n` +
            "  Revisá DAI_NOTIFY_WEBHOOK en el .env.dai — puede estar revocado o ser de otro espacio.";
   }
   if (status === 404) {
-    return `${donde} no existe (404). El webhook fue borrado, o la URL está mal copiada.`;
+    return `${target} no existe (404). El webhook fue borrado, o la URL está mal copiada.`;
   }
   if (status === 429) {
-    return `${donde} te frenó por rate limit (429). El aviso no salió; el release sí está hecho.`;
+    return `${target} te frenó por rate limit (429). El aviso no salió; el release sí está hecho.`;
   }
-  return `${donde} respondió ${status}.${body ? `\n  ${body}` : ""}`;
+  return `${target} respondió ${status}.${body ? `\n  ${body}` : ""}`;
 }

package/cli/lib/pm-adapter.mjs

@@ -65,8 +65,8 @@ function mdAdapter(env) {
     comment(id, markdown) {
       const p = join(dir, `${id}.deploys.md`);
       mkdirSync(dirname(p), { recursive: true });
-      const previo = existsSync(p) ? readFileSync(p, "utf8") : `# Despliegues de ${id}\n`;
-      writeFileSync(p, `${previo.replace(/\s*$/, "")}\n\n${markdown}\n`);
+      const previousTag = existsSync(p) ? readFileSync(p, "utf8") : `# Despliegues de ${id}\n`;
+      writeFileSync(p, `${previousTag.replace(/\s*$/, "")}\n\n${markdown}\n`);
       return p;
     },
     listComments(id) {

package/cli/lib/pm-jira.mjs

@@ -43,6 +43,12 @@ export function jiraAuthHeaders(env) {
 }
 
 // ── ADF → markdown (para leer la descripción) ────────────────────────────────
+
+// Una celda puede tener varios párrafos, y una fila de markdown no sobrevive un salto de
+// línea en el medio: se aplana a UNA línea y se escapan los `|` que traiga el texto.
+const inlineCell = (cell) => adfToMarkdown(cell).replace(/\s+/g, " ").replace(/\|/g, "\\|").trim();
+const mdRow = (cells) => `| ${cells.join(" | ")} |`;
+
 export function adfToMarkdown(node) {
   if (node == null) return "";
   if (Array.isArray(node)) return node.map(adfToMarkdown).join("");
@@ -53,6 +59,25 @@ export function adfToMarkdown(node) {
     case "bulletList":
     case "orderedList": return (node.content || []).map(adfToMarkdown).join("");
     case "listItem":    return "- " + (node.content || []).map(adfToMarkdown).join("").trim() + "\n";
+    // Jira Cloud tiene tablas de verdad, y el molde de US pone la metadata —`spec_version`
+    // incluido— en una. Sin estos casos caían al `default`, que aplana cada celda a su
+    // propia línea: `spec_version` quedaba en una y `v1` en la siguiente, y SPEC_VERSION_RE
+    // —que no cruza saltos de línea a propósito— no encontraba nada. La US declaraba `v1`
+    // en el tracker y dai estampaba `version: pendiente` sin que nada explicara por qué.
+    case "table": {
+      const rows = (node.content || []).filter((r) => r?.type === "tableRow");
+      if (rows.length === 0) return "";
+      const out = rows.map((r) => mdRow((r.content || []).map(inlineCell)));
+      // El separador va solo si la primera fila es de encabezados: es lo que hace que esto
+      // se RENDERICE como tabla donde el markdown importa (el cuerpo de una PR, el .md que
+      // baja `dai edit-us`). Para el parseo no cambia nada.
+      const head = rows[0].content || [];
+      if (head.length && head.every((c) => c?.type === "tableHeader")) {
+        out.splice(1, 0, mdRow(head.map(() => "---")));
+      }
+      return out.join("\n") + "\n";
+    }
+    case "tableRow":    return mdRow((node.content || []).map(inlineCell)) + "\n";
     case "text":        return node.text || "";
     case "hardBreak":   return "\n";
     default:            return (node.content || []).map(adfToMarkdown).join("");
@@ -60,23 +85,62 @@ export function adfToMarkdown(node) {
 }
 
 // ── markdown → ADF (para CREAR el issue: la descripción va en ADF) ────────────
-// Parser de bloques: headings, párrafos y bullets. Suficiente para el formato de US.
+// Parser de bloques: headings, párrafos, bullets y tablas. Suficiente para el formato de US.
+
+// Una fila de markdown: `| a | b |`. El separador (`|---|---|`) marca que la fila de
+// arriba era el encabezado; no es una fila de datos.
+const MD_ROW_RE = /^\s*\|.*\|\s*$/;
+const MD_SEP_RE = /^\s*\|[\s:|-]+\|\s*$/;
+const splitCells = (line) =>
+  line.trim().replace(/^\||\|$/g, "").split(/(?<!\\)\|/).map((c) => c.replace(/\\\|/g, "|"));
+
 export function markdownToAdf(md) {
-  const clean = (s) => s.replace(/[*_`]+/g, "").trim();
+  // El `_` se saca solo cuando hace de énfasis (_así_), no cuando vive DENTRO de una
+  // palabra: sacarlo siempre publicaba la fila del molde como `specversion`, un nombre de
+  // campo que nadie escribió y que del otro lado hubo que aprender a leer (issue #46).
+  const clean = (s) => s.replace(/[*`]+/g, "").replace(/(?<![A-Za-z0-9])_+|_+(?![A-Za-z0-9])/g, "").trim();
   const content = [];
-  let para = [], bullets = null;
+  let para = [], bullets = null, rows = null;
   const flushPara = () => { if (para.length) { const t = clean(para.join(" ")); if (t) content.push({ type: "paragraph", content: [{ type: "text", text: t }] }); para = []; } };
   const flushBullets = () => { if (bullets) { if (bullets.length) content.push({ type: "bulletList", content: bullets }); bullets = null; } };
+  // La metadata de trazabilidad del molde de US es una TABLA, y el comentario de cobertura
+  // también. Sin este caso viajaban a Jira como párrafos con pipes adentro: ilegibles, y
+  // encima invitaban a rehacerlos como tabla de Jira a mano — que es justo lo que del otro
+  // lado dai no sabía leer.
+  const flushTable = () => {
+    if (!rows) return;
+    const data = rows.filter((r) => !r.sep);
+    if (data.length) {
+      const headed = rows.length > 1 && rows[1].sep;
+      const cell = (raw, header) => {
+        const text = clean(raw);
+        return {
+          type: header ? "tableHeader" : "tableCell",
+          attrs: {},
+          content: [{ type: "paragraph", content: text ? [{ type: "text", text }] : [] }],
+        };
+      };
+      content.push({
+        type: "table",
+        attrs: { isNumberColumnEnabled: false, layout: "default" },
+        content: data.map((r, i) => ({ type: "tableRow", content: r.cells.map((c) => cell(c, headed && i === 0)) })),
+      });
+    }
+    rows = null;
+  };
   for (const raw of String(md || "").split(/\r?\n/)) {
     const line = raw.replace(/\s+$/, "");
     const h = line.match(/^(#{1,6})\s+(.*)$/);
     const b = line.match(/^\s*[-*+]\s+(?:\[[ xX]\]\s+)?(.*)$/);
-    if (h) { flushPara(); flushBullets(); const t = clean(h[2]); if (t) content.push({ type: "heading", attrs: { level: h[1].length }, content: [{ type: "text", text: t }] }); }
-    else if (b) { flushPara(); if (!bullets) bullets = []; const t = clean(b[1]); if (t) bullets.push({ type: "listItem", content: [{ type: "paragraph", content: [{ type: "text", text: t }] }] }); }
-    else if (line.trim() === "") { flushPara(); flushBullets(); }
-    else { flushBullets(); para.push(line.trim()); }
+    if (h) { flushPara(); flushBullets(); flushTable(); const t = clean(h[2]); if (t) content.push({ type: "heading", attrs: { level: h[1].length }, content: [{ type: "text", text: t }] }); }
+    // Una fila se reconoce por abrir Y cerrar con `|`; el separador entra acá también,
+    // marcado, porque es lo único que distingue un encabezado de una fila más.
+    else if (MD_ROW_RE.test(line)) { flushPara(); flushBullets(); if (!rows) rows = []; rows.push({ sep: MD_SEP_RE.test(line), cells: splitCells(line) }); }
+    else if (b) { flushPara(); flushTable(); if (!bullets) bullets = []; const t = clean(b[1]); if (t) bullets.push({ type: "listItem", content: [{ type: "paragraph", content: [{ type: "text", text: t }] }] }); }
+    else if (line.trim() === "") { flushPara(); flushBullets(); flushTable(); }
+    else { flushBullets(); flushTable(); para.push(line.trim()); }
   }
-  flushPara(); flushBullets();
+  flushPara(); flushBullets(); flushTable();
   if (content.length === 0) content.push({ type: "paragraph", content: [{ type: "text", text: " " }] });
   return { type: "doc", version: 1, content };
 }

package/cli/lib/release-files.mjs

@@ -63,10 +63,10 @@ export function changelogEntry({ version, date, manifest = {}, secciones = ["Agr
 // Acá es un AVISO, no un bloqueo: cortar la versión no debe frenarse por la redacción.
 export function changelogGaps(entry) {
   const gaps = [];
-  const cuerpo = String(entry ?? "").replace(/<!--[\s\S]*?-->/g, "");
+  const body = String(entry ?? "").replace(/<!--[\s\S]*?-->/g, "");
   if (String(entry ?? "").includes(CHANGELOG_MARK)) gaps.push("el manifiesto de dai sigue sin repartir");
-  const conTexto = cuerpo.split("\n").some((l) => /^\s*[-*]\s+\S/.test(l));
-  if (!conTexto) gaps.push("no hay ni un ítem en las secciones");
+  const hasItems = body.split("\n").some((l) => /^\s*[-*]\s+\S/.test(l));
+  if (!hasItems) gaps.push("no hay ni un ítem en las secciones");
   return gaps;
 }
 
@@ -99,9 +99,9 @@ export function changelogSection(text, version) {
   const m = s.match(re);
   if (!m) return null;
   const ini = m.index + m[0].length;
-  const resto = s.slice(ini);
-  const j = resto.search(/^## \[/m);
-  return (j === -1 ? resto : resto.slice(0, j)).replace(/<!--[\s\S]*?-->/g, "").trim() || null;
+  const rest = s.slice(ini);
+  const j = rest.search(/^## \[/m);
+  return (j === -1 ? rest : rest.slice(0, j)).replace(/<!--[\s\S]*?-->/g, "").trim() || null;
 }
 
 // ── Nombres ──────────────────────────────────────────────────────────────────

package/cli/lib/release-plan.mjs

@@ -67,20 +67,20 @@ export function mergedBranch(subject) {
 // observable. Cualquier derivación automática habría cortado un patch equivocado.
 // Por eso esto devuelve un PISO y su justificación, y quien firma es una persona.
 export function proposeBump(commits = []) {
-  const reales = commits.filter((c) => !c.merge);
-  if (reales.some((c) => c.breaking)) {
-    const cual = reales.find((c) => c.breaking);
-    return { bump: "major", floor: true, reason: `hay un commit marcado como breaking (${cual.subject})` };
+  const realCommits = commits.filter((c) => !c.merge);
+  if (realCommits.some((c) => c.breaking)) {
+    const offender = realCommits.find((c) => c.breaking);
+    return { bump: "major", floor: true, reason: `hay un commit marcado como breaking (${offender.subject})` };
   }
-  if (reales.some((c) => c.type === "feat")) {
-    const n = reales.filter((c) => c.type === "feat").length;
+  if (realCommits.some((c) => c.type === "feat")) {
+    const n = realCommits.filter((c) => c.type === "feat").length;
     return { bump: "minor", floor: true, reason: `${n} commit(s) feat: agregan funcionalidad` };
   }
   return {
     bump: "patch",
     floor: true,
-    reason: reales.length
-      ? `solo hay ${[...new Set(reales.map((c) => c.type || "sin-tipo"))].sort().join(", ")}: ningún feat ni breaking`
+    reason: realCommits.length
+      ? `solo hay ${[...new Set(realCommits.map((c) => c.type || "sin-tipo"))].sort().join(", ")}: ningún feat ni breaking`
       : "no hay commits nuevos",
   };
 }
@@ -118,7 +118,7 @@ export function buildManifest({ commits = [], linked = [], live = {}, unreachabl
 
   const stories = [...porId.values()].map((r) => {
     const l = live[r.id];
-    const estado = unreachable || !l ? (unreachable ? "sin-respuesta" : "sin-us")
+    const storyStatus = unreachable || !l ? (unreachable ? "sin-respuesta" : "sin-us")
       : l.ac_hash === r.ac_hash ? "al-dia" : "atrasado";
     return {
       id: r.id,
@@ -127,7 +127,7 @@ export function buildManifest({ commits = [], linked = [], live = {}, unreachabl
       ac_hash: r.ac_hash ?? null,
       spec_version: l?.spec_version ?? null,
       change: r.change ?? null,
-      status: estado,
+      status: storyStatus,
     };
   }).sort((a, b) => String(a.id).localeCompare(String(b.id)));
 
@@ -136,11 +136,11 @@ export function buildManifest({ commits = [], linked = [], live = {}, unreachabl
   // trabajo de producto sin link, y esta es la última oportunidad de verlo.
   const ids = new Set(stories.map((s) => String(s.id).toLowerCase()));
   const branches = commits.map((c) => mergedBranch(c.subject)).filter(Boolean);
-  const EXENTAS = new Set(["chore", "docs", "ci", "build", "test", "refactor", "style", "release", "hotfix", "revert"]);
+  const EXEMPT_TYPES = new Set(["chore", "docs", "ci", "build", "test", "refactor", "style", "release", "hotfix", "revert"]);
   const chores = [], orphans = [];
   for (const b of branches) {
-    if (nombraAlguna(b, ids)) continue;                 // ya está contada como US
-    if (EXENTAS.has(branchType(b))) { chores.push(b); continue; }
+    if (namesAnyStory(b, ids)) continue;                 // ya está contada como US
+    if (EXEMPT_TYPES.has(branchType(b))) { chores.push(b); continue; }
     // "Entró trabajo sin link" solo es un hallazgo si el repo trabaja con User Stories. En
     // un repo de tooling —el de dai, sin ir más lejos— NINGUNA branch va a declarar una, y
     // marcarlas todas convierte el aviso en ruido que se aprende a ignorar. La excepción es
@@ -158,22 +158,22 @@ export function buildManifest({ commits = [], linked = [], live = {}, unreachabl
       commits: commits.filter((c) => !c.merge).length,
       merges: commits.filter((c) => c.merge).length,
       stories: stories.length,
-      atrasadas: stories.filter((s) => s.status === "atrasado").length,
+      stale: stories.filter((s) => s.status === "atrasado").length,
     },
   };
 }
 
 // ¿El nombre de la branch nombra alguna de las US del manifiesto? Comparación en
 // minúsculas: el slug de la branch va en minúscula y el key del tracker en mayúscula.
-function nombraAlguna(branch, ids) {
+function namesAnyStory(branch, ids) {
   const b = String(branch).toLowerCase();
   for (const id of ids) if (b.includes(id)) return true;
   return false;
 }
 
 // ── Render ───────────────────────────────────────────────────────────────────
-const ICONO = { "al-dia": "✅", atrasado: "⚠️ ", "sin-us": "❓", "sin-respuesta": "⚠️ " };
-const ETIQUETA = {
+const ICON = { "al-dia": "✅", atrasado: "⚠️ ", "sin-us": "❓", "sin-respuesta": "⚠️ " };
+const LABEL = {
   "al-dia": "al día", atrasado: "ATRASADA", "sin-us": "no está en el tracker",
   "sin-respuesta": "no verificada",
 };
@@ -195,13 +195,13 @@ export function renderManifest(m, ctx = {}) {
     const w = Math.max(...m.stories.map((s) => String(s.id).length), 4);
     for (const s of m.stories) {
       const t = s.title ? `  ${s.title}` : "";
-      L.push(`    ${ICONO[s.status] || " "} ${String(s.id).padEnd(w)}  ${s.version || "?"}${t}`);
-      if (s.status !== "al-dia") L.push(`       ${" ".repeat(w)}   ${ETIQUETA[s.status]}`);
+      L.push(`    ${ICON[s.status] || " "} ${String(s.id).padEnd(w)}  ${s.version || "?"}${t}`);
+      if (s.status !== "al-dia") L.push(`       ${" ".repeat(w)}   ${LABEL[s.status]}`);
     }
   }
-  if (m.counts.atrasadas > 0) {
+  if (m.counts.stale > 0) {
     L.push(``);
-    L.push(`  ⚠ ${m.counts.atrasadas} US ATRASADA(S): el QUÉ cambió después de implementarlo.`);
+    L.push(`  ⚠ ${m.counts.stale} US ATRASADA(S): el QUÉ cambió después de implementarlo.`);
     L.push(`    Esta release las llevaría sin cubrir el criterio nuevo. Revisalas antes de cortar.`);
   }
   if (m.chores.length) {

package/cli/lib/release-stamp.mjs

@@ -32,8 +32,8 @@ export function alreadyStamped(comments = [], marker) {
 // y el ticket solo necesita saber qué salió, dónde y cuándo.
 export function renderReleaseStamp(ev = {}) {
   const v = `v${String(ev.version ?? "").replace(/^v/, "")}`;
-  const amb = String(ev.environment ?? "").toUpperCase();
-  const L = [`**${ev.app || "app"} ${v}** desplegada en **${amb}** — ${ev.date || ""}`.trim(), ""];
+  const envLabel = String(ev.environment ?? "").toUpperCase();
+  const L = [`**${ev.app || "app"} ${v}** desplegada en **${envLabel}** — ${ev.date || ""}`.trim(), ""];
   if (ev.commit) L.push(`- commit: \`${String(ev.commit).slice(0, 8)}\``);
   if (ev.url) L.push(`- release: ${ev.url}`);
   L.push("");
@@ -48,9 +48,9 @@ export function renderReleaseStamp(ev = {}) {
 //   stories  → las US del manifiesto
 //   stamped  → Set de ids que YA tienen la marca de este (app, versión, ambiente)
 export function stampPlan({ stories = [], stamped = new Set(), unknown = false } = {}) {
-  const pendientes = [], repetidas = [];
-  for (const s of stories) (stamped.has(s.id) ? repetidas : pendientes).push(s);
-  return { pendientes, repetidas, unknown, total: stories.length };
+  const pending = [], alreadyDone = [];
+  for (const s of stories) (stamped.has(s.id) ? alreadyDone : pending).push(s);
+  return { pending, alreadyDone, unknown, total: stories.length };
 }
 
 // El aviso de alcance. Es la pantalla que pidió existir: cuántos comentarios, en qué
@@ -62,8 +62,8 @@ export function renderStampPlan(plan, { app, version, environment, tracker } = {
   L.push(`  versión:  ${v}     app: ${app || "?"}     ambiente: ${String(environment ?? "").toUpperCase()}`);
   L.push(`  tracker:  ${tracker || "?"} · ${plan.total} User Storie(s) en el release`);
   L.push(`  ─────────────────────────────────────────────────────`);
-  for (const s of plan.pendientes) L.push(`    ${s.id}${s.title ? `  ${s.title}` : ""}`);
-  for (const s of plan.repetidas) L.push(`    ${s.id}${s.title ? `  ${s.title}` : ""}   ← ya estampada, se saltea`);
+  for (const s of plan.pending) L.push(`    ${s.id}${s.title ? `  ${s.title}` : ""}`);
+  for (const s of plan.alreadyDone) L.push(`    ${s.id}${s.title ? `  ${s.title}` : ""}   ← ya estampada, se saltea`);
   if (plan.total === 0) L.push(`    (ninguna: el manifiesto de esta versión no declara US)`);
   L.push(`  ─────────────────────────────────────────────────────`);
   if (plan.unknown) {
@@ -75,13 +75,13 @@ export function renderStampPlan(plan, { app, version, environment, tracker } = {
 
 // La frase que decide. Dice el número REAL de escrituras y que no hay vuelta atrás.
 export function stampWarning(plan) {
-  const n = plan.pendientes.length;
+  const n = plan.pending.length;
   if (n === 0) return "no hay nada para estampar: todas las US ya tienen esta versión en este ambiente.";
-  const saltea = plan.repetidas.length ? ` (${plan.repetidas.length} ya estampada(s), se saltean)` : "";
-  return `esto escribe ${n} comentario(s) en el tracker de todo el equipo${saltea}. No se deshace.`;
+  const skipped = plan.alreadyDone.length ? ` (${plan.alreadyDone.length} ya estampada(s), se saltean)` : "";
+  return `esto escribe ${n} comentario(s) en el tracker de todo el equipo${skipped}. No se deshace.`;
 }
 
 // Lo que se pierde al decir que no. Se dice UNA vez, sin insistir: elegir menos ruido es
 // una decisión legítima, no un error a corregir.
-export const SIN_ESTAMPAR =
+export const NOT_STAMPED_NOTE =
   "sin estampar, el ticket no va a decir en qué versión salió: el registro queda solo en el release note.";

package/cli/lib/review-findings.mjs

@@ -168,7 +168,7 @@ export function renderReviewSummary(r, { kept = [], suppressed = [], rejected =
     .filter(({ n }) => n > 0)
     .map(({ s, n }) => `${n} ${SEV[s].emoji} ${SEV[s].label}`);
 
-  const hallazgos = kept.length
+  const findings = 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.";
 
@@ -181,7 +181,7 @@ export function renderReviewSummary(r, { kept = [], suppressed = [], rejected =
     r.summary || null,
     r.summary ? "" : null,
     "### Hallazgos",
-    hallazgos,
+    findings,
     "",
     "### ✅ Lo que está bien",
     bullets(r.good),

package/cli/lib/us-format.mjs

@@ -93,8 +93,8 @@ export function validateUS(md) {
 
   for (const c of criteria) {
     if (!isGherkin(c)) {
-      const falta = [!c.dado && "Dado", !c.cuando && "Cuando", !c.entonces && "Entonces"].filter(Boolean).join(" / ");
-      warnings.push(`${c.label}: no es Gherkin completo — falta ${falta}. Un criterio sin las tres partes es difícil de volver un test.`);
+      const missingParts = [!c.dado && "Dado", !c.cuando && "Cuando", !c.entonces && "Entonces"].filter(Boolean).join(" / ");
+      warnings.push(`${c.label}: no es Gherkin completo — falta ${missingParts}. Un criterio sin las tres partes es difícil de volver un test.`);
     }
     if (TECNICAS.test(c.text)) {
       warnings.push(`${c.label}: menciona implementación (${c.text.match(TECNICAS)[0]}). El QUÉ describe comportamiento observable; el CÓMO lo decide el dev.`);

package/cli/lib/us.mjs

@@ -55,17 +55,17 @@ export function renderCoverage(id, r) {
 // llega. Acá se le pone alrededor qué, contra qué, y qué mirar.
 export function explainFetchError(err, { kind, endpoint, id } = {}) {
   const raw = String(err?.message ?? err ?? "").split("\n")[0] || "error desconocido";
-  const donde = [kind, endpoint].filter(Boolean).join(" · ");
-  const cabeza = `no pude consultar ${id ? `la US ${id}` : "el tracker"}${donde ? ` en ${donde}` : ""}: ${raw}`;
+  const where = [kind, endpoint].filter(Boolean).join(" · ");
+  const head = `no pude consultar ${id ? `la US ${id}` : "el tracker"}${where ? ` en ${where}` : ""}: ${raw}`;
   if (/fetch failed|ENOTFOUND|ECONNREFUSED|EAI_AGAIN|ETIMEDOUT|ECONNRESET|certificate|self.signed/i.test(raw)) {
-    return `${cabeza}\n  No llegó a haber respuesta. Revisá la red y el host del backend; si estás detrás de un\n` +
+    return `${head}\n  No llegó a haber respuesta. Revisá la red y el host del backend; si estás detrás de un\n` +
            `  proxy corporativo, declará la CA con NODE_EXTRA_CA_CERTS (nunca NODE_TLS_REJECT_UNAUTHORIZED=0).\n` +
            `  Diagnóstico:  dai doctor`;
   }
   if (/\b40[13]\b|unauthorized|forbidden/i.test(raw)) {
-    return `${cabeza}\n  El tracker rechazó las credenciales: revisá el token del .env.dai (¿venció?) y sus permisos.\n` +
+    return `${head}\n  El tracker rechazó las credenciales: revisá el token del .env.dai (¿venció?) y sus permisos.\n` +
            `  Diagnóstico:  dai doctor`;
   }
-  if (/\b5\d\d\b/.test(raw)) return `${cabeza}\n  El error es del tracker, no tuyo: probá de nuevo en un rato.`;
-  return cabeza;
+  if (/\b5\d\d\b/.test(raw)) return `${head}\n  El error es del tracker, no tuyo: probá de nuevo en un rato.`;
+  return head;
 }

package/docs/adr/0008-estrategia-de-i18n.md

@@ -46,6 +46,64 @@ Adoptamos un modelo de **fuente única + traducciones derivadas**, por superfici
    core (MANIFIESTO, METODOLOGIA, glosario, EJEMPLO, guías) · (3) CLI i18n + skills · (4) el
    resto (detalle/, ADRs, templates). Se prioriza por alcance, no por completitud.
 
+## Estado medido — 2026-09-10
+
+El ADR sigue en **propuesto**; esto es el relevamiento que hace falta para poder ejecutarlo,
+tomado al auditar la convención de naming después de la 0.15.0.
+
+### Cuánto es el trabajo de la fase 3 (CLI)
+
+| Superficie | Volumen |
+|---|---|
+| `ok()` / `info()` / `warn()` / `fail()` en `cli/dai.mjs` | 348 llamadas |
+| `process.stdout.write` con texto en `cli/dai.mjs` | 99 |
+| `cli/lib/help.mjs` (es **todo** texto al usuario) | 524 líneas |
+| `throw new Error(...)` / `fail(...)` en `cli/lib/` | 67 |
+
+Del orden de **mil literales**. Es mecánico, pero confirma lo que el ADR ya anticipaba: se
+hace de una sola vez, no a pedazos. El ciclo de release (0.15.0) le sumó volumen: los
+comandos nuevos, su ayuda y el manifiesto son texto al usuario de punta a punta.
+
+### Lo que ya está resuelto y no hay que rehacer
+
+- **Los identificadores del código están en inglés** (auditado y corregido en la 0.15.x). El
+  refactor de i18n toca strings, no nombres.
+- **Las salidas de máquina ya usan claves en inglés**: el manifiesto de `dai release plan
+  --json` y el payload del webhook genérico.
+- **El glosario ES→EN de §5 ya existe** y se usó: `atrasado → stale` fue el término que se
+  aplicó al renombrar `counts.atrasadas`.
+
+### La decisión de contrato que falta tomar, y su costo real
+
+`coverageStatus()` devuelve valores **en español** —`"al-dia"`, `"atrasado"`, `"sin-us"`,
+`"sin-respuesta"`— y esos valores **salen por `--json`**: son parte de la API que puede estar
+parseando el CI de alguien.
+
+Lo interesante es que el costo interno de cambiarlos es **casi cero**: ya están separados de
+lo que se muestra (`statusLabel()` los traduce a `✅ al día` y compañía), así que el i18n de
+la *presentación* no necesita tocarlos. La única razón para renombrarlos es que una API en
+inglés se lea en inglés.
+
+Entonces la decisión es puramente de contrato, y hay tres caminos:
+
+1. **Dejarlos.** Son un enum opaco; el consumidor los compara, no los lee. Costo cero,
+   inconsistencia visible en cada `--json`.
+2. **Renombrarlos en una major** (`up-to-date`, `stale`, `no-story`, `unreachable`). Limpio,
+   pero obliga a una major solo por esto.
+3. **Emitir los dos** por un tiempo (`status` en inglés + `status_es` deprecado), y sacar el
+   viejo en la próxima major. Es el camino habitual para no romper, y el que menos duele si
+   ya hay alguien parseando.
+
+No se decide acá: se decide **junto con** la fase 3, porque hacer dos cambios de la salida
+`--json` en versiones distintas es peor que hacer uno solo.
+
+### Recomendación de orden
+
+Mantener el orden del ADR y **no empezar por el CLI**. Un CLI traducido con un README en
+español no lo encuentra nadie: lo que abre la herramienta a usuarios anglófonos es la fase 1
+(README + landing), porque es lo que se ve en npm y en GitHub. La fase 3 recién rinde cuando
+ya hay alguien de habla inglesa llegando.
+
 ## Consecuencias
 
 - ✅ Alcance internacional con el README/landing en inglés (fase 1) sin reescribir todo.

package/package.json

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