@dforce2055/dai 0.14.0 → 0.15.1

package/cli/lib/release-files.mjs

@@ -0,0 +1,119 @@
+// dai · los archivos que toca cortar una versión: dónde vive el número y qué se escribe
+// en el CHANGELOG. Parte pura; los efectos (escribir, commitear, taguear) viven en dai.mjs.
+//
+// Premisa que vale para todo el módulo: **el tag es la fuente de verdad de la versión; los
+// archivos son espejos opcionales.** Un repo Node tiene package.json, dai tiene además un
+// VERSION, y un repo .NET o un frontend corporativo puede no tener ninguno de los dos y
+// versionar igual. Por eso dai actualiza los espejos que RECONOCE, dice cuáles tocó, y no
+// se planta si no encuentra ninguno.
+
+// ── El número, en los archivos que lo espejan ────────────────────────────────
+
+// package.json: se cambia SOLO la línea de la versión.
+//
+// Reserializar el JSON (`JSON.stringify(pkg, null, 2)`) parece más limpio y es peor: te
+// reformatea los objetos compactos (`"repository": { ... }` en una línea) a multi-línea y
+// ensucia el diff de la release con ruido que nadie pidió. El diff de un `chore(release)`
+// tiene que ser tres líneas.
+export function bumpPackageJson(text, version) {
+  const re = /("version"\s*:\s*")([^"]*)(")/;
+  const m = String(text ?? "").match(re);
+  if (!m) return { text, changed: false, from: null };
+  if (m[2] === version) return { text, changed: false, from: m[2] };
+  return { text: text.replace(re, `$1${version}$3`), changed: true, from: m[2] };
+}
+
+// VERSION: el archivo entero es el número. Sin salto final, como lo escribe dai.
+export function bumpVersionFile(text, version) {
+  const from = String(text ?? "").trim().split("\n")[0] || null;
+  if (from === version) return { text, changed: false, from };
+  return { text: version, changed: true, from };
+}
+
+// ── CHANGELOG ────────────────────────────────────────────────────────────────
+// Keep a Changelog. dai escribe el ANDAMIO y el material; la prosa la escribe una persona
+// (o la skill), y esa división no es pereza: dai sabe QUÉ entró, no POR QUÉ importa. Un
+// changelog autogenerado desde los commits es una lista que nadie lee — el de este repo se
+// lee justamente porque cada entrada cuenta qué estaba mal.
+//
+// El material va en un comentario HTML: se ve al editar y desaparece al renderizar, así
+// que si alguien no lo reparte, el archivo publicado no queda con andamio a la vista.
+export const CHANGELOG_MARK = "<!-- dai:manifiesto";
+
+export function changelogEntry({ version, date, manifest = {}, secciones = ["Agregado", "Cambiado", "Corregido", "Interno"] }) {
+  const L = [`## [${version}] — ${date}`, ""];
+  L.push(`${CHANGELOG_MARK} · el material de esta versión. Repartilo abajo y contá el porqué:`);
+  L.push(`     dai sabe qué entró; por qué importa lo sabés vos.`);
+  for (const s of manifest.stories || []) {
+    L.push(`     ${s.id}${s.title ? `  ${s.title}` : ""}${s.status === "atrasado" ? "   ⚠️ ATRASADA" : ""}`);
+  }
+  for (const b of manifest.chores || []) L.push(`     (sin US) ${b}`);
+  for (const b of manifest.orphans || []) L.push(`     (sin US, sin prefijo exento) ${b}`);
+  if (!(manifest.stories || []).length && !(manifest.chores || []).length && !(manifest.orphans || []).length) {
+    L.push(`     (el manifiesto no encontró US ni branches en el rango)`);
+  }
+  L.push(`-->`);
+  L.push("");
+  for (const s of secciones) { L.push(`### ${s}`); L.push(""); }
+  return L.join("\n");
+}
+
+// ¿La entrada quedó con el andamio sin repartir? Mismo espíritu que `bodyGaps` en `dai pr`:
+// publicar el molde es peor que no publicar nada, porque parece que alguien lo escribió.
+// 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 body = String(entry ?? "").replace(/<!--[\s\S]*?-->/g, "");
+  if (String(entry ?? "").includes(CHANGELOG_MARK)) gaps.push("el manifiesto de dai sigue sin repartir");
+  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;
+}
+
+// Inserta la entrada arriba de la primera que ya exista, y agrega el link al pie.
+// Idempotente en lo que importa: si la versión YA está, no la duplica.
+export function insertChangelogEntry(text, entry, { version, repoUrl } = {}) {
+  const s = String(text ?? "");
+  if (version && new RegExp(`^## \\[${version.replace(/\./g, "\\.")}\\]`, "m").test(s)) {
+    return { text: s, changed: false, reason: `el CHANGELOG ya tiene una entrada para ${version}` };
+  }
+  const i = s.search(/^## \[/m);
+  let out = i === -1
+    ? `${s.replace(/\s*$/, "")}\n\n${entry}\n`
+    : `${s.slice(0, i)}${entry}\n${s.slice(i)}`;
+  if (version && repoUrl) {
+    const link = `[${version}]: ${repoUrl.replace(/\/+$/, "")}/releases/tag/v${version}`;
+    if (!out.includes(link)) {
+      // Junto a los otros links del pie si los hay; si no, al final.
+      const j = out.search(/^\[\d+\.\d+\.\d+\]: /m);
+      out = j === -1 ? `${out.replace(/\s*$/, "")}\n\n${link}\n` : `${out.slice(0, j)}${link}\n${out.slice(j)}`;
+    }
+  }
+  return { text: out, changed: true, reason: null };
+}
+
+// El cuerpo de una versión, para reusarlo como release note del forge.
+export function changelogSection(text, version) {
+  const s = String(text ?? "");
+  const re = new RegExp(`^## \\[${String(version).replace(/\./g, "\\.")}\\][^\\n]*\\n`, "m");
+  const m = s.match(re);
+  if (!m) return null;
+  const ini = m.index + m[0].length;
+  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 ──────────────────────────────────────────────────────────────────
+export const releaseBranch = (version) => `release/${version}`;
+export const tagName = (version) => `v${String(version).replace(/^v/, "")}`;
+
+// Normaliza y valida lo que tipeó quien corta la versión. Un tag mal escrito se arrastra a
+// npm, al CHANGELOG y a todos los avisos, y renombrarlo después no existe.
+export function normalizeVersion(input) {
+  const v = String(input ?? "").trim().replace(/^v/i, "");
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.\-+]+)?$/.test(v)) {
+    throw new Error(`'${input}' no es una versión semver (X.Y.Z, opcionalmente -rc.1).`);
+  }
+  return v;
+}

package/cli/lib/release-plan.mjs

@@ -0,0 +1,221 @@
+// dai · el manifiesto de una release: qué entra entre el último tag y la integración.
+//
+// Es la pieza de la que dependen los otros comandos de `dai release`, y la que contesta la
+// pregunta que a un equipo sin versiones no le contesta nadie: **¿qué User Stories tiene
+// esta versión?** El resto —el tag, el CHANGELOG, el comentario en cada ticket, el aviso al
+// canal— son formas distintas de publicar ESTE dato.
+//
+// Todo acá es puro: entran las salidas de git ya crudas y sale la decisión. Los efectos
+// (correr git, consultar el tracker) viven en dai.mjs.
+
+import { parseVersion } from "./semver.mjs";
+import { branchType, trackerKeysIn } from "./branch-scope.mjs";
+
+// ── Commits ──────────────────────────────────────────────────────────────────
+// Formato pedido a git: `%H%x1f%s` por línea (sha, US, subject) — el separador es \x1f
+// (unit separator) y no un pipe o un tab porque un subject puede contener cualquiera de
+// esos, y partir mal el log es empezar el manifiesto con datos corridos.
+export function parseCommitLog(raw) {
+  const out = [];
+  for (const line of String(raw ?? "").split("\n")) {
+    if (!line.trim()) continue;
+    const i = line.indexOf("\x1f");
+    if (i === -1) continue;
+    const sha = line.slice(0, i).trim();
+    const subject = line.slice(i + 1);
+    out.push({ sha, subject, ...classifySubject(subject) });
+  }
+  return out;
+}
+
+// Conventional Commits, con la tolerancia justa: el repo puede tener commits que no lo
+// sigan, y un manifiesto que los ignora miente por omisión. Los que no matchean quedan
+// con type null y se cuentan igual.
+const CC = /^(?<type>[a-z]+)(?:\((?<scope>[^)]*)\))?(?<bang>!)?:\s*(?<rest>.+)$/i;
+
+export function classifySubject(subject) {
+  const s = String(subject ?? "");
+  const merge = /^Merge (pull request|branch|remote-tracking)/i.test(s);
+  const m = s.match(CC);
+  if (!m) return { type: null, scope: null, breaking: false, merge };
+  return {
+    type: m.groups.type.toLowerCase(),
+    scope: m.groups.scope || null,
+    breaking: Boolean(m.groups.bang),
+    merge,
+  };
+}
+
+// La branch que trajo un merge commit, cuando el forge la nombra en el subject:
+//   "Merge pull request #47 from dforce2055/fix/pr-base"  → "fix/pr-base"
+//   "Merge branch 'feature/ABC-1-x' into develop"          → "feature/ABC-1-x"
+// Sirve para detectar trabajo que ENTRÓ sin declarar US. Si el equipo hace squash o
+// rebase no hay merge commits y esta señal no existe: por eso es un aviso, no un gate.
+export function mergedBranch(subject) {
+  const s = String(subject ?? "");
+  const pr = s.match(/^Merge pull request #\d+ from [^/\s]+\/(.+?)\s*$/i);
+  if (pr) return pr[1];
+  const br = s.match(/^Merge (?:remote-tracking )?branch '([^']+)'/i);
+  if (br) return br[1].replace(/^origin\//, "");
+  return null;
+}
+
+// ── Bump propuesto ───────────────────────────────────────────────────────────
+// PROPUESTO, no decidido. dai mira los tipos de commit, que es lo único que puede leer
+// sin criterio; la regla del repo mira el COMPORTAMIENTO, y esa diferencia no es teórica:
+// la 0.14.0 salió con cuatro commits `fix:` y era minor, porque cambió un default
+// 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 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 (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: realCommits.length
+      ? `solo hay ${[...new Set(realCommits.map((c) => c.type || "sin-tipo"))].sort().join(", ")}: ningún feat ni breaking`
+      : "no hay commits nuevos",
+  };
+}
+
+// El aviso que acompaña SIEMPRE a la propuesta. No es decoración: es la diferencia entre
+// una sugerencia y una automatización que se equivoca en silencio.
+export const BUMP_CAVEAT =
+  "propuesta a partir de los TIPOS de commit — la regla del repo mira el COMPORTAMIENTO.\n" +
+  "  Si algo mueve un default, agrega un flag o cambia lo que ve quien no configura nada,\n" +
+  "  es minor aunque todo sea `fix:`. Decidilo vos: dai propone, no versiona por su cuenta.";
+
+export function nextVersion(current, bump) {
+  const v = parseVersion(current);
+  if (!v) return null;
+  if (bump === "major") return `${v.major + 1}.0.0`;
+  if (bump === "minor") return `${v.major}.${v.minor + 1}.0`;
+  return `${v.major}.${v.minor}.${v.patch + 1}`;
+}
+
+// ── Manifiesto ───────────────────────────────────────────────────────────────
+// `linked` son las filas de implements.yaml que aparecieron en el rango (las arma dai.mjs
+// leyendo el árbol de cada commit: el link viaja CON el código, así que no depende de que
+// la branch siga existiendo ni de que el change no se haya archivado).
+// `live` es lo que contestó el tracker por id: { [id]: { title, ac_hash, spec_version } }.
+export function buildManifest({ commits = [], linked = [], live = {}, unreachable = false, repoUsesStories = true } = {}) {
+  // Una US puede aparecer en varios commits (se creó el link, después se resincronizó) y
+  // en dos paths (el change y su copia archivada). El manifiesto la nombra UNA vez.
+  const porId = new Map();
+  for (const r of linked) {
+    if (!r?.id) continue;
+    const prev = porId.get(r.id);
+    // Gana la última aparición: es el estado con el que la US entró al release.
+    if (!prev || (r.order ?? 0) >= (prev.order ?? 0)) porId.set(r.id, r);
+  }
+
+  const stories = [...porId.values()].map((r) => {
+    const l = live[r.id];
+    const storyStatus = unreachable || !l ? (unreachable ? "sin-respuesta" : "sin-us")
+      : l.ac_hash === r.ac_hash ? "al-dia" : "atrasado";
+    return {
+      id: r.id,
+      title: l?.title ?? null,
+      version: r.version ?? null,
+      ac_hash: r.ac_hash ?? null,
+      spec_version: l?.spec_version ?? null,
+      change: r.change ?? null,
+      status: storyStatus,
+    };
+  }).sort((a, b) => String(a.id).localeCompare(String(b.id)));
+
+  // Las branches que se mergearon en el rango, separadas en las que declaran US y las que
+  // están exentas por tipo. Las que NO son ninguna de las dos son el hallazgo: entró
+  // 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 EXEMPT_TYPES = new Set(["chore", "docs", "ci", "build", "test", "refactor", "style", "release", "hotfix", "revert"]);
+  const chores = [], orphans = [];
+  for (const b of branches) {
+    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
+    // una branch que NOMBRA un ticket: ahí alguien quiso linkear una US y no lo hizo, y eso
+    // vale como hallazgo aunque el repo no declare ninguna.
+    if (repoUsesStories || trackerKeysIn(b).length > 0) orphans.push(b);
+    else chores.push(b);
+  }
+
+  return {
+    stories,
+    chores,
+    orphans,
+    counts: {
+      commits: commits.filter((c) => !c.merge).length,
+      merges: commits.filter((c) => c.merge).length,
+      stories: stories.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 namesAnyStory(branch, ids) {
+  const b = String(branch).toLowerCase();
+  for (const id of ids) if (b.includes(id)) return true;
+  return false;
+}
+
+// ── Render ───────────────────────────────────────────────────────────────────
+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",
+};
+
+export function renderManifest(m, ctx = {}) {
+  const { from, to, current, proposed, bump, reason } = ctx;
+  const L = [];
+  L.push(`  ── Release a preparar ────────────────────────────────`);
+  L.push(`  desde:    ${from || "(el principio del repo)"}`);
+  L.push(`  hasta:    ${to}`);
+  L.push(`  cambios:  ${m.counts.commits} commit(s) · ${m.counts.merges} merge(s)`);
+  L.push(`  versión:  ${current} → ${proposed || "(sin propuesta)"}  (${bump})`);
+  L.push(`  ─────────────────────────────────────────────────────`);
+
+  if (m.stories.length === 0) {
+    L.push(`  Ninguna US declarada en este rango.`);
+  } else {
+    L.push(`  User Stories que entran (${m.stories.length}):`);
+    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(`    ${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.stale > 0) {
+    L.push(``);
+    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) {
+    L.push(``);
+    L.push(`  Sin US (${m.chores.length}): ${m.chores.slice(0, 6).join(", ")}${m.chores.length > 6 ? "…" : ""}`);
+  }
+  if (m.orphans.length) {
+    L.push(``);
+    L.push(`  ⚠ ${m.orphans.length} branch(es) sin US y sin prefijo exento:`);
+    for (const b of m.orphans) L.push(`      ${b}`);
+    L.push(`    Entró trabajo que nadie va a poder rastrear a una historia. Es la última`);
+    L.push(`    oportunidad de verlo antes de que quede adentro de una versión.`);
+  }
+  L.push(`  ─────────────────────────────────────────────────────`);
+  if (reason) L.push(`  ${bump}: ${reason}`);
+  return L.join("\n");
+}

package/cli/lib/release-stamp.mjs

@@ -0,0 +1,87 @@
+// dai · el comentario que le avisa a cada User Story en qué versión y en qué ambiente salió.
+//
+// Es la vuelta completa de la trazabilidad: el `implements.yaml` ata la US al código, el
+// `dai stamp` de cobertura ata la US al commit, y esto ata la US a la VERSIÓN DESPLEGADA.
+// Con eso, el funcional abre el ticket y ve "esto está en producción desde la v1.2.0" sin
+// preguntarle a nadie — que es exactamente lo que un equipo sin versiones no puede contestar.
+//
+// Dos cuidados que mandan sobre el diseño de este módulo:
+//
+//   1. Escribe N veces hacia afuera, en tickets de gente distinta, y no se deshace. Por eso
+//      el comando muestra el alcance ANTES (cuántos comentarios, en qué tickets) y pide
+//      confirmación. Un susto genérico no sirve: el número tiene que ser el real.
+//   2. Es OPCIONAL. Si alguien no quiere hacer ruido en veinte tickets, la release ya está
+//      hecha: el tag existe, el release note existe. Decir que no no puede romper nada.
+
+// La marca que hace el comentario reconocible para dai mismo. Sin esto no hay forma de
+// saber si ya estampamos: redesplegar la misma versión llenaría el ticket de comentarios
+// idénticos, y un ticket con cuarenta avisos de deploy no lo lee nadie.
+export function releaseMarker({ app, version, environment }) {
+  const v = String(version ?? "").replace(/^v/, "");
+    return `[dai:release app=${app || "?"} version=${v} env=${String(environment ?? "").toLowerCase() || "?"}]`;
+}
+
+// ¿Este comentario ya está puesto? Se compara la marca completa, así que la misma versión
+// en OTRO ambiente (o de otra app) no se confunde con una repetición.
+export function alreadyStamped(comments = [], marker) {
+  return comments.some((c) => String(c ?? "").includes(marker));
+}
+
+// El comentario, en markdown. Los backends lo convierten a lo suyo (Jira lo pasa a ADF,
+// ClickUp lo manda como texto). Corto a propósito: el detalle vive en el release note,
+// 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 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("");
+  L.push(releaseMarker(ev));
+  return L.join("\n");
+}
+
+// El plan del estampado: a quién le toca, a quién no, y por qué. Se calcula ANTES de
+// escribir nada para poder mostrarlo — mostrar "12 US" cuando en realidad se van a escribir
+// 9 comentarios es la clase de aviso que la gente aprende a ignorar.
+//
+//   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 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é
+// tickets, y que no se deshace.
+export function renderStampPlan(plan, { app, version, environment, tracker } = {}) {
+  const v = `v${String(version ?? "").replace(/^v/, "")}`;
+  const L = [];
+  L.push(`  ── Estampar despliegue ───────────────────────────────`);
+  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.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) {
+    L.push(`  ⚠ No pude leer los comentarios del tracker, así que no sé cuáles ya estampé.`);
+    L.push(`    Si esta versión ya se estampó en este ambiente, van a salir repetidos.`);
+  }
+  return L.join("\n");
+}
+
+// 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.pending.length;
+  if (n === 0) return "no hay nada para estampar: todas las US ya tienen esta versión en este ambiente.";
+  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 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.