@dforce2055/dai 0.14.0 → 0.15.1

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/branch-scope.mjs

@@ -194,16 +194,31 @@ export function prScope({ branch, rows, allRows = rows, ids = [] }) {
   if (req.kind === "exempt") {
     return { mode: "exempt", target: null, candidates: rows, reason: `${req.reason} y su nombre no nombra ninguna US` };
   }
-  // El repo no tiene NINGUNA US viva. Exigirle un link a una branch que el propio
-  // branch-naming declara exenta es pedir algo que no existe: `fix/lo-que-sea` (sin ID en
-  // el nombre) terminaba con "corré dai link-us primero" y el consejo de renombrarla a
-  // `chore/`, que para un fix es directamente el consejo equivocado. Le pasa a cualquier
-  // repo de tooling — al de dai, sin ir más lejos, que no se trackea a sí mismo con US.
-  if (rows.length === 0) {
-    return req.required
-      ? { mode: "none", target: null, candidates: [], reason: "no hay implements.yaml vivo en el repo" }
-      : { mode: "exempt", target: null, candidates: [], reason: `${req.reason}, y el repo no declara ninguna US` };
+  // El repo no tiene NINGUNA US viva. Exigir un link acá es pedir algo que no existe: le
+  // pasa a cualquier repo de tooling —al de dai, sin ir más lejos, que no se trackea a sí
+  // mismo con US— y el mensaje terminaba mandando a renombrar la branch a `chore/`, que
+  // para un fix o una feature es el consejo equivocado.
+  //
+  // Lo que SÍ distingue un olvido de un repo sin US es si la branch NOMBRA UN TICKET: con
+  // `feature/ABC-482-checkout` alguien quiso implementar una US y no corrió `link-us`, y
+  // ahí el link falta de verdad. Sin key en el nombre no hay nada que reclamar.
+  //
+  // Esto no afloja ningún gate: el gate es `dai check --ci`, que sigue mirando requiresLink.
+  // Acá solo se decide con qué titular una PR.
+  // Se mira `allRows` (archivados incluidos), no `rows`: un repo con US archivadas SÍ
+  // trabaja con User Stories, así que una `feature/` sin link ahí es un olvido, no un repo
+  // de tooling. La exención es para el repo que nunca declaró una.
+  if (allRows.length === 0 && trackerKeysIn(branch).length === 0) {
+    return {
+      mode: "exempt", target: null, candidates: [],
+      // Si branch-naming ya tiene un motivo (chore/ exenta por tipo, fix/ sin ID), se usa
+      // ese: es más específico y es el que el equipo puede ir a leer.
+      reason: req.required
+        ? "la branch no nombra ninguna US y el repo no declara ninguna"
+        : `${req.reason}, y el repo no declara ninguna US`,
+    };
   }
+  if (rows.length === 0) return { mode: "none", target: null, candidates: [], reason: "no hay implements.yaml vivo en el repo" };
   if (rows.length === 1) return { mode: "only", target: rows[0], candidates: rows, reason: "es la única US viva del repo" };
   return { mode: "ambiguous", target: null, candidates: rows, reason: `hay ${rows.length} US vivas y la branch '${branch}' no dice cuál` };
 }

package/cli/lib/help.mjs

@@ -227,6 +227,74 @@ Ejemplo:
   dai pr --base develop --description-file notas.md
 `,
 
+  release: `dai release — el ciclo de versión: qué entra, cortarla, cerrarla, contarla
+
+Uso:
+  dai release plan   [--from <ref>] [--to <rama>] [--json] [--no-network]
+  dai release cut    <X.Y.Z> [--no-branch] [--yes] [--dry-run]
+  dai release done   <X.Y.Z> [--app <n>] [--no-release] [--no-notify] [--yes] [--dry-run]
+  dai release stamp  <X.Y.Z> --env <ambiente> [--app <n>] [--url <u>] [--yes] [--dry-run]
+  dai release status [--no-network]
+  dai release notify --test
+
+El ciclo, con la firma humana en el medio:
+
+  plan  ──▶  cut  ──▶  dai pr  ──▶  [ merge + publicar: lo firma una persona ]
+                                                │
+                                                ▼
+                                            done  ──▶  stamp (opcional)
+
+plan — el MANIFIESTO: qué hay entre el último tag y la rama de integración, qué User
+  Stories entran y en qué estado, qué branches entraron sin US, y qué bump PROPONE.
+  Propone, no decide: dai lee los tipos de commit y la regla del repo mira el
+  comportamiento. Algo que mueve un default es minor aunque todo sea \`fix:\`.
+
+cut — prepara la versión: crea \`release/X.Y.Z\`, sube el número en los archivos que este
+  repo espeja (VERSION, package.json — si no hay ninguno, la versión es el tag), escribe
+  la entrada del CHANGELOG con el material para repartir, y commitea. No habla hacia
+  afuera: ni push, ni tag, ni PR. La prosa del CHANGELOG la escribís vos: dai sabe qué
+  entró, no por qué importa.
+  --no-branch   taguea desde la rama de integración, sin branch de release
+
+done — cierra la versión DESPUÉS del merge, igual que \`dai done\` cierra el trabajo de una
+  branch: tag anotado, release note en el forge,
+  back-merge a la rama de integración y aviso al canal. Es la mitad que se olvida cuando
+  la ceremonia se hace a mano. Cada paso reporta por separado: si falla la release note,
+  el tag YA existe y hay que saberlo.
+  --app <nombre>   con qué nombre aparece la app (default: el del repo)
+  --no-release     no publica la nota en el forge
+  --no-notify      no avisa al canal (DAI_NOTIFY)
+  --keep-branch    conserva la rama release/X.Y.Z (por default la borra: ya está mergeada,
+                   tagueada y con el back-merge hecho, y una que sobrevive a su release
+                   es un fork). git se niega a borrar una sin mergear.
+
+stamp — le avisa a CADA User Story del release en qué versión y ambiente salió. Es el
+  comando que más cuidado necesita: escribe N veces hacia afuera, en tickets de gente
+  distinta, y no se deshace. Por eso muestra el alcance REAL antes —cuántos comentarios,
+  en qué tickets, cuáles se saltean por estar ya estampados— y pide confirmación.
+  Es OPCIONAL: decir que no sale con 0 y no rompe nada, porque la versión ya está hecha.
+  Idempotente por (app, versión, ambiente): redesplegar no llena el ticket de repetidos.
+  --env <ambiente>  obligatorio. El que uses (prod, pre, test, uat-2): dai no tiene catálogo
+  --url <u>         link al release, para que el comentario lleve a algún lado
+
+status — dónde estás en el ciclo: versión declarada vs último tag, cuánto hay sin promover,
+  si falta el back-merge, branches de release abiertas y el canal configurado.
+  Lo que NO contesta es qué versión hay en cada ambiente: eso es un evento, no un archivo
+  del repo, y su registro son los stamps de las US.
+
+notify --test — postea un mensaje de prueba al canal. Un webhook no se puede validar sin
+  postear, y fingir que sí sería justo lo que dai no hace: avisa antes y pide confirmación.
+
+Config del repo (.env.dai):
+  DAI_BRANCH_DEV / DAI_BRANCH_PROD   las dos ramas de vida larga
+  DAI_NOTIFY=discord|slack|webex|telegram|webhook|none  ·  DAI_NOTIFY_WEBHOOK=<endpoint>
+
+Ejemplo:
+  dai release plan
+  dai release cut 1.2.0
+  dai release done 1.2.0
+`,
+
   done: `dai done — cierra la US: vuelve a la base, actualiza y borra la branch local
 
 Uso:
@@ -411,6 +479,14 @@ export function globalUsage() {
     "  stamp [<ID>…] [--all]        estampa la cobertura en el tracker (ADR-0005)\n" +
     "                               sin ID: la US de esta branch; si hay varias, pregunta\n" +
     "  done [--base b] [--force]    cierra la US: vuelve a la base, actualiza y borra la branch local\n" +
+    "  release plan [--from r] [--to b] [--json]   el manifiesto de la próxima versión: qué US entran,\n" +
+    "                               qué entró sin US, y qué bump propone (propone: firmás vos)\n" +
+    "  release cut <X.Y.Z> [--no-branch]   prepara la versión: branch + bump + entrada del CHANGELOG + commit\n" +
+    "  release done <X.Y.Z>       tras el merge: tag + release note + back-merge + aviso al canal\n" +
+    "      [--app n] [--no-release] [--no-notify]\n" +
+    "  release stamp <X.Y.Z> --env <amb>   avisa a cada US en qué versión y ambiente salió\n" +
+    "                               (muestra el alcance y confirma · opcional: decir que no no rompe nada)\n" +
+    "  release status · release notify --test   dónde estás en el ciclo · probar el canal\n" +
     "  archive [<change>] [--skip-specs]   funde los delta specs del change en las specs canónicas y lo archiva (lo corre el aprobador en la PR)\n" +
     "  pr (alias mr) [--assignee u] [--base b] [--draft] [--yes]   crea o ACTUALIZA TU PR/MR precargada (muestra + confirma)\n" +
     "      [--us <ID>] [--title t]  la US la resuelve la branch; si hay varias, pregunta (sin TTY, falla)\n" +

package/cli/lib/notify.mjs

@@ -0,0 +1,205 @@
+// dai · aviso de release a un canal de equipo (opcional, opt-in, default apagado).
+//
+// Tercer adaptador del CLI, con la misma anatomía que los dos que ya existen: una variable
+// que elige el backend (DAI_NOTIFY, como DAI_PM) y las variables propias de ese backend.
+//
+// El mensaje es UNO SOLO para todos los canales: con ESTRUCTURA (qué salió, quién, cuándo,
+// qué trae, dónde mirar) pero SIN FORMATO. Esa distinción es la que hace que esto sea una
+// tabla y no un módulo de render:
+//
+//   · la estructura son saltos de línea y viñetas, y se ve igual en los cinco canales,
+//   · el formato son cuatro dialectos incompatibles (Discord **negrita** sin links con
+//     nombre, Slack *negrita* con <url|texto>, Webex markdown completo, Telegram con su
+//     parse_mode y el escapeo de MarkdownV2 que devuelve 400 por un punto suelto),
+//   · una URL pelada se vuelve clickeable sola en los cuatro,
+//   · y lo único que queda distinto entre proveedores es EN QUÉ CAMPO del JSON va el string.
+//
+// Las viñetas se cortan en MAX_BULLETS, así que el mensaje no se acerca al límite de
+// ningún canal (el más chico es Discord, 2000) y no hay nada que recortar a mano.
+//
+// El detalle del release vive en el ticket (dai release stamp) y en el release note. El
+// canal avisa y linkea: un chat no es un registro, a los dos días nadie lo encuentra.
+//
+// Lo que esto NO es: un framework de notificaciones. dai avisa eventos de release con su
+// manifiesto. Mandar mensajes arbitrarios a un canal no es dai.
+
+import { daiFetch } from "./http.mjs";
+
+// El envelope de cada canal. Esto es el adaptador entero.
+const CHANNELS = {
+  discord:  (msg) => ({ content: msg }),
+  slack:    (msg) => ({ text: msg }),
+  webex:    (msg) => ({ markdown: msg }),
+  telegram: (msg, cfg) => ({ chat_id: cfg.chatId, text: msg }),
+  // Genérico: los campos estructurados MÁS el texto ya armado. Una integración propia usa
+  // los campos; cualquier endpoint estilo Slack (Mattermost, Rocket.Chat, un webhook de
+  // Teams) levanta el `text` sin configurar nada. No cuesta una línea más soportar los dos.
+  webhook:  (msg, cfg, ev) => ({ ...eventFields(ev), text: msg }),
+};
+
+export const VALID_CHANNELS = Object.keys(CHANNELS);
+
+// ── Config ───────────────────────────────────────────────────────────────────
+// Devuelve null cuando el repo no declaró canal: no avisar es el default, y un default
+// que habla hacia afuera sería una sorpresa desagradable.
+export function notifyConfig(env = {}) {
+  const channel = String(env.DAI_NOTIFY ?? "").trim().toLowerCase();
+  if (channel === "" || channel === "none") return null;
+  if (!CHANNELS[channel]) {
+    throw new Error(
+      `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.`,
+    );
+  }
+  const endpoint = String(env.DAI_NOTIFY_WEBHOOK ?? "").trim();
+  if (!endpoint) {
+    throw new Error(
+      `DAI_NOTIFY=${channel} pero falta DAI_NOTIFY_WEBHOOK en el .env.dai (el endpoint del canal).\n` +
+      `  Ese endpoint ES la credencial: quien lo tiene, postea. Nunca lo commitees.`,
+    );
+  }
+  const chatId = String(env.DAI_NOTIFY_CHAT_ID ?? "").trim();
+  // Telegram es el raro de los cuatro: no tiene webhooks de entrada. Es token de bot +
+  // chat_id, y el token vale para el bot entero, no para un canal — por eso hace falta
+  // decir a qué chat. Si falta, el POST sale igual y la API contesta un 400 que no lo explica.
+  if (channel === "telegram" && !chatId) {
+    throw new Error(
+      "DAI_NOTIFY=telegram necesita además DAI_NOTIFY_CHAT_ID (a qué chat postear).\n" +
+      "  Telegram no usa webhooks de entrada: el endpoint es el bot y el chat_id el destino.",
+    );
+  }
+  return { channel, endpoint, chatId: chatId || null };
+}
+
+// Qué se le muestra al usuario como destino. NUNCA la URL entera: el endpoint es la
+// credencial, y un webhook filtrado en una captura de pantalla es un canal comprometido.
+export function describeTarget(cfg) {
+  if (!cfg) return "sin canal (DAI_NOTIFY no declarado)";
+  let host = "(endpoint ilegible)";
+  try { host = new URL(cfg.endpoint).host; } catch { /* URL rara: no la mostramos igual */ }
+  return `${cfg.channel} · ${host}${cfg.chatId ? ` · chat ${cfg.chatId}` : ""}`;
+}
+
+// ── El mensaje ───────────────────────────────────────────────────────────────
+// Un evento de release: qué app, qué versión, a dónde fue, y qué US lleva adentro.
+//   event: "released"  → se publicó la versión (dai release done)
+//   event: "deployed"  → esa versión llegó a un ambiente (dai release stamp --env X)
+//   event: "test"      → prueba de canal (dai release notify --test)
+function eventFields(ev = {}) {
+  return {
+    event: `release.${ev.event || "released"}`,
+    app: ev.app ?? null,
+    version: ev.version ?? null,
+    environment: ev.environment ?? null,
+    url: ev.url ?? null,
+    stories: (Array.isArray(ev.stories) ? ev.stories : []).map((s) => (typeof s === "string" ? { id: s, title: null } : { id: s.id, title: s.title ?? null })),
+  };
+}
+
+// El texto, uno solo para todos los canales. Con ESTRUCTURA (qué salió, quién, cuándo,
+// qué trae, dónde mirar) pero SIN FORMATO: ni negritas ni links con nombre.
+//
+// La diferencia no es estética, es de costo. La estructura son saltos de línea y viñetas,
+// que se ven igual en los cinco canales. El formato son cuatro dialectos incompatibles:
+// Discord usa **negrita** y no soporta links con nombre; Slack usa *negrita* de un
+// asterisco y <url|texto>; Webex quiere markdown completo; Telegram exige parse_mode y
+// escapar media docena de caracteres o devuelve 400. Una URL pelada, en cambio, se vuelve
+// clickeable sola en los cuatro.
+//
+//   🎉 Nuevo release · backend v1.2.0
+//   Autor: Ada Lovelace · Fecha: 09/09/2026 08:12 · Ambiente: PRODUCCIÓN
+//
+//   Cambios principales:
+//    • ACME-482  Checkout sin duplicado
+//    • ACME-491  Alta de póliza sin duplicar cliente
+//
+//   Ver release: https://…/releases/v1.2.0
+//
+// Las viñetas salen de las US del manifiesto, no de los subjects de los commits: lo que
+// el equipo quiere leer es qué valor salió, no qué archivos se tocaron. Es la misma
+// diferencia entre el QUÉ y el CÓMO que sostiene todo el método.
+const MAX_BULLETS = 8;
+
+const pad2 = (n) => String(n).padStart(2, "0");
+export function formatFecha(d = new Date()) {
+  return `${pad2(d.getDate())}/${pad2(d.getMonth() + 1)}/${d.getFullYear()} ` +
+         `${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
+}
+
+export function renderNotice(ev = {}) {
+  if (ev.event === "test") {
+    return "✅ Prueba de canal · dai\nSi ves esto, el canal está bien configurado.";
+  }
+  const app = ev.app ? `${ev.app} ` : "";
+  const version = ev.version ? `v${String(ev.version).replace(/^v/, "")}` : "(sin versión)";
+  const L = [];
+  L.push(ev.environment
+    ? `🚀 Release desplegada · ${app}${version} → ${String(ev.environment).toUpperCase()}`
+    : `🎉 Nuevo release · ${app}${version}`);
+
+  // Segunda línea: quién y cuándo. Sale de git y del reloj — nada que configurar.
+  const meta = [];
+  if (ev.author) meta.push(`Autor: ${ev.author}`);
+  meta.push(`Fecha: ${ev.date || formatFecha()}`);
+  L.push(meta.join(" · "));
+
+  const stories = Array.isArray(ev.stories) ? ev.stories : [];
+  if (stories.length) {
+    L.push("");
+    L.push("Cambios principales:");
+    for (const s of stories.slice(0, MAX_BULLETS)) {
+      const id = typeof s === "string" ? s : s.id;
+      const title = typeof s === "string" ? null : s.title;
+      L.push(` • ${id}${title ? `  ${title}` : ""}`);
+    }
+    if (stories.length > MAX_BULLETS) L.push(` • …y ${stories.length - MAX_BULLETS} más`);
+  }
+  if (ev.url) { L.push(""); L.push(`Ver release: ${ev.url}`); }
+  return L.join("\n");
+}
+
+// El cuerpo que se le manda al canal.
+export function payloadFor(cfg, ev) {
+  const envelope = CHANNELS[cfg.channel];
+  if (!envelope) throw new Error(`canal desconocido: ${cfg.channel}`);
+  return envelope(renderNotice(ev), cfg, ev);
+}
+
+// ── Efecto de red ────────────────────────────────────────────────────────────
+// Un aviso que no sale NO puede voltear una release: para cuando esto corre, el tag ya
+// existe y las US ya están estampadas. Por eso devuelve el error en vez de tirarlo —
+// quien llama lo reporta como advertencia y sigue.
+export async function sendNotice(cfg, ev) {
+  try {
+    const res = await daiFetch(cfg.endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payloadFor(cfg, ev)),
+    });
+    if (!res.ok) {
+      const body = (await res.text().catch(() => "")).slice(0, 300);
+      return { ok: false, status: res.status, error: explainNotifyError(cfg, res.status, body) };
+    }
+    return { ok: true, status: res.status, error: null };
+  } catch (e) {
+    // El mensaje de daiFetch ya explica el caso de TLS corporativo; acá solo se le pone
+    // alrededor qué se estaba haciendo, sin filtrar el endpoint.
+    return { ok: false, status: null, error: `no pude avisar a ${describeTarget(cfg)}: ${String(e.message).split("\n")[0]}` };
+  }
+}
+
+export function explainNotifyError(cfg, status, body = "") {
+  const target = describeTarget(cfg);
+  if (status === 401 || status === 403) {
+    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 `${target} no existe (404). El webhook fue borrado, o la URL está mal copiada.`;
+  }
+  if (status === 429) {
+    return `${target} te frenó por rate limit (429). El aviso no salió; el release sí está hecho.`;
+  }
+  return `${target} respondió ${status}.${body ? `\n  ${body}` : ""}`;
+}

package/cli/lib/pm-adapter.mjs

@@ -9,6 +9,8 @@
 // Interfaz (fetchUS/stamp pueden ser sync o async — el CLI siempre await-ea):
 //   fetchUS(id)          → { id, title, spec_version, ac_hash, url, raw } | null
 //   stamp(id, record)    → destino donde quedó la cobertura
+//   comment(id, markdown)→ comentario libre en la US    (lo usa `dai release stamp`)
+//   listComments(id)     → [texto]  para reconocer los comentarios que dai ya puso
 //   createUS({...})      → { id, url }            (opcional: `dai publish`)
 //   updateUS(id, {...})  → { id, url }            (opcional: `dai update-us`)
 //   kind                 → nombre del backend
@@ -57,6 +59,20 @@ function mdAdapter(env) {
       const raw = readFileSync(p, "utf8");
       return { id, ...parseUS(raw), raw };
     },
+    // Sin tracker, un "comentario" es una línea más en el registro de despliegues de esa US.
+    // Se APÉNDEA (no se pisa): el archivo es la bitácora, y una bitácora que se sobrescribe
+    // no es una bitácora.
+    comment(id, markdown) {
+      const p = join(dir, `${id}.deploys.md`);
+      mkdirSync(dirname(p), { recursive: true });
+      const previousTag = existsSync(p) ? readFileSync(p, "utf8") : `# Despliegues de ${id}\n`;
+      writeFileSync(p, `${previousTag.replace(/\s*$/, "")}\n\n${markdown}\n`);
+      return p;
+    },
+    listComments(id) {
+      const p = join(dir, `${id}.deploys.md`);
+      return existsSync(p) ? [readFileSync(p, "utf8")] : [];
+    },
     stamp(id, record) {
       const p = join(dir, `${id}.coverage.md`);
       mkdirSync(dirname(p), { recursive: true });

package/cli/lib/pm-clickup.mjs

@@ -35,6 +35,23 @@ export function clickupAdapter(env) {
       // `url` es la canónica (/t/<team_id>/<id>): la sabe ClickUp, no la deducimos.
       return { id, ...parseUS(raw), url: j.url || null, raw };
     },
+    // Comentario libre (lo usa `dai release stamp`). ClickUp toma texto directamente.
+    async comment(id, markdown) {
+      const res = await fetch(clickupCommentUrl(id), {
+        method: "POST", headers: clickupAuthHeaders(env),
+        body: JSON.stringify({ comment_text: markdown }),
+      });
+      if (!res.ok) throw new Error(`clickup ${res.status}: ${await res.text()}`);
+      return `task ${id} (comentario)`;
+    },
+    // Los comentarios como texto, para reconocer los que dai ya puso por su marca.
+    async listComments(id) {
+      const res = await fetch(clickupCommentUrl(id), { headers: clickupAuthHeaders(env) });
+      if (res.status === 404) return [];
+      if (!res.ok) throw new Error(`clickup ${res.status}: ${await res.text()}`);
+      const j = await res.json();
+      return (j.comments || []).map((c) => c.comment_text || c.text_content || "");
+    },
     async stamp(id, record) {
       const res = await fetch(clickupCommentUrl(id), {
         method: "POST", headers: clickupAuthHeaders(env),

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 };
 }
@@ -147,6 +211,26 @@ export function jiraAdapter(env) {
       const raw = jiraIssueToText(await res.json());
       return { id, ...parseUS(raw), url: `${trim(base)}/browse/${id}`, raw };
     },
+    // Comentario libre en markdown (lo usa `dai release stamp`). Jira Cloud pide ADF, así
+    // que se convierte con el mismo parser que ya usa la descripción de la US.
+    async comment(id, markdown) {
+      const res = await daiFetch(jiraCommentUrl(base, id), {
+        method: "POST", headers: jiraAuthHeaders(env),
+        body: JSON.stringify({ body: markdownToAdf(markdown) }),
+      });
+      if (!res.ok) throw new Error(`jira ${res.status}: ${await res.text()}`);
+      return `${trim(base)}/browse/${id}`;
+    },
+    // Los comentarios como texto plano, para que dai reconozca los suyos por la marca y no
+    // vuelva a estampar lo mismo. Los más nuevos primero: la marca que buscamos, si está,
+    // es reciente. 100 alcanza de sobra y evita paginar un ticket con años de historia.
+    async listComments(id) {
+      const res = await daiFetch(`${jiraCommentUrl(base, id)}?maxResults=100&orderBy=-created`, { headers: jiraAuthHeaders(env) });
+      if (res.status === 404) return [];
+      if (!res.ok) throw new Error(`jira ${res.status}: ${await res.text()}`);
+      const j = await res.json();
+      return (j.comments || []).map((c) => (typeof c.body === "string" ? c.body : adfToMarkdown(c.body)));
+    },
     async stamp(id, record) {
       const res = await daiFetch(jiraCommentUrl(base, id), {
         method: "POST", headers: jiraAuthHeaders(env),

package/cli/lib/pr-remote.mjs

@@ -53,6 +53,20 @@ export function updatePrCmd(tool, { number, title, body, bodyFile }) {
   return ["mr", "update", String(number), "--title", title, "--description", body, "--yes"];
 }
 
+// Plan B para actualizar, cuando el comando de alto nivel falla por algo que no tiene que
+// ver con la edición. Pasa de verdad: `gh pr edit` consulta GraphQL y arrastra campos
+// deprecados del servidor —hoy, `projectCards` de Projects (classic)— así que devuelve un
+// error sobre proyectos cuando lo único que querías era cambiar el body. La API REST no
+// pasa por ahí, y `gh api` usa la misma autenticación: no hace falta un token nuevo.
+//
+// Devuelve null si no sabemos hacer el plan B para esa herramienta (glab actualiza por REST
+// de entrada, así que no lo necesita).
+export function updatePrApiCmd(tool, { number, title, bodyFile, projectPath }) {
+  if (tool !== "gh" || !projectPath) return null;
+  return ["api", "--method", "PATCH", `repos/${projectPath}/pulls/${number}`,
+          "-F", `body=@${bodyFile}`, "-f", `title=${title}`];
+}
+
 // ── "ya existe una PR para esta branch" ──────────────────────────────────────
 // El forge lo dice de formas distintas y en inglés. Se reconoce para poder pasar al camino
 // de actualizar en vez de morir con el comando crudo en pantalla.