@dforce2055/dai 0.14.0 → 0.15.0

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 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})` };
+  }
+  if (reales.some((c) => c.type === "feat")) {
+    const n = reales.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`
+      : "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 estado = 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: estado,
+    };
+  }).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 EXENTAS = 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; }
+    // "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,
+      atrasadas: 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) {
+  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 = {
+  "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(`    ${ICONO[s.status] || " "} ${String(s.id).padEnd(w)}  ${s.version || "?"}${t}`);
+      if (s.status !== "al-dia") L.push(`       ${" ".repeat(w)}   ${ETIQUETA[s.status]}`);
+    }
+  }
+  if (m.counts.atrasadas > 0) {
+    L.push(``);
+    L.push(`  ⚠ ${m.counts.atrasadas} 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 amb = String(ev.environment ?? "").toUpperCase();
+  const L = [`**${ev.app || "app"} ${v}** desplegada en **${amb}** — ${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 pendientes = [], repetidas = [];
+  for (const s of stories) (stamped.has(s.id) ? repetidas : pendientes).push(s);
+  return { pendientes, repetidas, 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.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`);
+  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.pendientes.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.`;
+}
+
+// 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 =
+  "sin estampar, el ticket no va a decir en qué versión salió: el registro queda solo en el release note.";

package/docs/adr/0019-ciclo-de-version-y-aviso-de-release.md

@@ -0,0 +1,190 @@
+# ADR-0019 — El ciclo de versión: manifiesto de US, dos mitades con una firma en el medio, y el aviso como evento
+
+- **Estado:** aceptado
+- **Fecha:** 2026-09-09
+- **Decide:** lead / arquitecto de la metodología
+
+## Contexto
+
+Hay equipos —grandes y medianos, no solo los desprolijos— que **no arman ramas de release
+ni etiquetan versiones**. Desplegar a producción se vuelve un ejercicio de memoria: hay que
+acordarse de qué ramas componen la funcionalidad y mergearlas a la rama de producción una
+por una, en el momento del despliegue.
+
+Eso tiene tres consecuencias, y las tres se ven en repos reales:
+
+1. **Se despliega una combinación que nunca se probó.** Cada orden de merge produce un
+   árbol distinto; el que llega a producción no existió en ningún ambiente antes.
+2. **No se puede contestar qué hay en cada ambiente.** Ni qué funcionalidades comprende.
+   Cuando algo falla a las tres de la mañana, no hay a qué volver.
+3. **Se cuelan funcionalidades que no estaban listas**, porque la selección de qué va se
+   hace rama por rama y a mano.
+
+dai ya sabía atar una User Story a su código (`implements.yaml`) y a su commit
+(`dai stamp`). Lo que faltaba era el último eslabón: atar la US a la **versión desplegada**.
+Sin eso, la trazabilidad llega hasta la PR y se corta justo donde el negocio pregunta.
+
+## Decisión
+
+### 1. dai aporta el manifiesto, no la estrategia de branching
+
+La estrategia de ramas la elige cada equipo, y dai no opina: es una herramienta, no un
+mandato. Lo que dai aporta es el eje que ya es suyo, extendido un paso:
+
+```
+implements.yaml   →   commit   →   PR   →   VERSIÓN   →   AMBIENTE
+   (ADR-0004)        (ADR-0005)          ←── esto es lo nuevo ──→
+```
+
+`dai release plan` produce el **manifiesto**: qué User Stories entran entre el último tag y
+la rama de integración, en qué estado está cada una, y qué entró **sin** declarar US. Los
+otros comandos son formas distintas de publicar ese mismo dato — el CHANGELOG, el tag, el
+comentario en cada ticket, el aviso al canal.
+
+**Cómo se resuelve qué US entró:** leyendo los `implements.yaml` tal como estaban en cada
+commit del rango, no por el nombre de la rama. El link viaja con el código, así que la
+respuesta sobrevive a que la rama se borre y a que el change se archive — que es
+exactamente el estado del repo cuando se llega a cortar la versión, días después del merge.
+
+**Alternativa descartada:** deducirlo del nombre de la rama en el commit de merge. Es más
+simple y es frágil: desaparece con squash, con rebase, y con cualquier equipo que renombre.
+Se conserva solo como señal secundaria, para detectar lo que entró **sin** link.
+
+### 2. El bump se propone; lo firma una persona
+
+dai deriva un piso del tipo de los commits (`feat:` → minor, `!` → major) y **lo dice**: es
+una propuesta, no un veredicto. La regla que manda mira el **comportamiento observable**.
+
+La evidencia es de este mismo repo: la versión 0.14.0 salió con cuatro commits `fix:` y era
+minor, porque cambió un default que ve quien no configura nada. Cualquier herramienta que
+derive la versión de los tipos de commit —semantic-release, standard-version, Conventional
+Commits puro— habría cortado un patch equivocado.
+
+**Alternativa descartada:** versionado automático desde los commits. Es precisamente el
+pedazo que no hay que automatizar: convierte una decisión de comunicación en un efecto
+secundario de cómo alguien tituló un commit.
+
+### 3. El corte son dos comandos, porque hay una firma humana en el medio
+
+```
+plan ──▶ [FIRMA: la versión] ──▶ cut ──▶ dai pr ──▶ [FIRMA: merge + publicar]
+                                                            │
+                                            done ◀────────┘
+```
+
+`cut` **prepara y no habla hacia afuera**: rama de release, número, entrada de CHANGELOG,
+commit. Ni push, ni tag, ni PR.
+
+`done` **cierra después del merge**: tag anotado, release note, back-merge y aviso. Existe
+como comando separado porque los dos pasos que más se olvidan cuando la ceremonia se hace a
+mano —el release note y el back-merge— viven en esta mitad, la que queda después de la firma.
+
+**Una vez creado el tag, ningún paso posterior aborta.** El tag es la versión: si existe, la
+versión existe. Fallar y salir dejaría el corte a medio camino sin decir en qué mitad quedó,
+así que cada paso reporta y sigue.
+
+### 4. El tag es la versión; los archivos son espejos
+
+`dai release cut` sube el número en `VERSION` y `package.json` **si existen**, informa cuáles
+tocó, y no se planta si no hay ninguno. Un repo .NET o un frontend corporativo versionan
+igual de bien sin ninguno de los dos.
+
+El bump de `package.json` es **quirúrgico** —solo la línea de la versión—: reserializar el
+JSON reformatea los objetos compactos y llena el diff de la release de ruido que nadie pidió.
+
+### 5. El CHANGELOG lo escribe una persona; dai deja el material
+
+`cut` inserta la entrada con las US del manifiesto **en un comentario HTML** (se ve al
+editar, desaparece al renderizar) y las secciones vacías. La prosa no la escribe dai: sabe
+*qué* entró, no *por qué importa*.
+
+**Alternativa descartada:** generar el changelog desde los subjects de los commits. Produce
+una lista que nadie lee, y encima da la sensación de que el trabajo está hecho.
+
+### 6. Estampar la versión en cada US es opcional, y avisa su alcance
+
+`dai release stamp <v> --env <ambiente>` deja en **cada US del release** un comentario con
+versión, app, ambiente y fecha. Con eso el funcional lee el ticket en vez de preguntar, y
+una US federada en varios repos acumula sola su matriz (backend en producción, frontend en
+pre).
+
+Tres cuidados, porque escribe N veces hacia afuera en tickets de gente distinta:
+
+- **Muestra el alcance real antes de escribir** — cuántos comentarios y en qué tickets,
+  descontando los que ya están. Un número inflado enseña a ignorar el aviso.
+- **Es idempotente por `(app, versión, ambiente)`**, con una marca en el propio comentario.
+  Redesplegar no llena el ticket de repetidos; la misma versión en otro ambiente sí es un
+  evento nuevo.
+- **Si no puede leer los comentarios, lo dice** en vez de suponer que no estampó. Es la
+  misma distinción que ADR-0003 hace entre "no hay US" y "no hubo respuesta"; acá afirmar de
+  más se paga en duplicados que nadie puede borrar.
+
+**Decir que no sale con 0.** Para cuando el comando corre, el tag y el release note ya
+existen: la versión está hecha. Que un equipo elija no hacer ruido en veinte tickets es una
+decisión legítima, no un error a corregir.
+
+### 7. El aviso al canal es un tercer adaptador, y su mensaje tiene estructura sin formato
+
+`DAI_NOTIFY` elige el backend igual que `DAI_PM` elige el tracker: `discord`, `slack`,
+`webex`, `telegram`, un `webhook` genérico, o `none` (el default: dai no habla hacia afuera
+sin que se lo pidan).
+
+El mensaje es **uno solo para todos los canales**, con estructura —qué salió, quién, cuándo,
+qué trae, dónde mirar— y **sin formato**. La distinción es de costo, no estética: la
+estructura son saltos de línea y viñetas, y se ve igual en los cinco; el formato son cuatro
+dialectos incompatibles (Discord con `**negrita**` y sin links con nombre, Slack con
+`*negrita*` y `<url|texto>`, Webex con markdown completo, Telegram con `parse_mode` y el
+escapeo de MarkdownV2 que devuelve 400 por un punto suelto). Con esa decisión, el adaptador
+es una tabla de cinco líneas en lugar de un módulo de render.
+
+**Las viñetas son las User Stories, no los subjects de los commits.** Un aviso que dice *"se
+implementa el conversor de propiedades no serializables"* lo entiende quien escribió el
+código; uno que dice *"Checkout sin duplicado"* lo entiende el negocio. Es la misma
+distinción entre el QUÉ y el CÓMO que sostiene el método, aplicada al canal.
+
+**El endpoint es la credencial:** quien lo tiene, postea. Vive en `.env.dai` (ADR-0017) y
+dai muestra el host, nunca la URL — tampoco en los mensajes de error.
+
+**Qué versión hay en cada ambiente NO vive en el repo.** Un despliegue es un evento, no un
+archivo: cambia sin que cambie el código. Guardarlo en un archivo obligaría al CI a
+commitear en cada deploy. Su registro es el stamp en el tracker y el release del forge.
+
+### 8. `done` borra la rama de release que acaba de cerrar
+
+Es el único punto del ciclo donde dai puede **afirmar** que borrarla es seguro: ya está
+mergeada en producción, etiquetada y con el back-merge hecho. Si no se hace ahí, se
+acumulan — este mismo repo tenía cinco cuando se implementó el comando.
+
+La red de seguridad la pone git, no una suposición: `git branch -d` (minúscula) se niega a
+borrar una rama sin mergear. Hay precedente en el CLI: `dai done` ya hace exactamente esto
+con la rama de una US.
+
+**Alternativa descartada:** un `dai release cleanup` que borre ramas de release viejas en
+masa. dai no las creó, no puede saber si alguien conserva una a propósito, y limpiar ramas
+en general no es su dominio. `dai release status` las nombra y deja el comando escrito;
+borrarlas es del equipo.
+
+### 9. Lo que dai NO hace
+
+- **No despliega.** Llega hasta el tag y vuelve a aparecer después, estampando. Quién
+  despliega es el pipeline.
+- **No mergea ni publica.** Son firmas humanas ([Art. 5](../MANIFIESTO.md#art-5)).
+- **No impone un modelo de branching.** La rama de release es opcional (`--no-branch`), y
+  las dos ramas de vida larga las declara el repo (`DAI_BRANCH_DEV` / `DAI_BRANCH_PROD`).
+- **No es un framework de notificaciones.** Avisa eventos de release con su manifiesto.
+
+## Consecuencias
+
+- Un equipo puede contestar, sin reunirse: **qué versión hay en cada ambiente y qué US
+  comprende**. Desde el ticket, no desde un Excel.
+- El manifiesto expone, antes de cortar, **las US atrasadas** y **lo que entró sin link** —
+  la última pantalla donde eso se puede ver.
+- El ciclo funciona igual con rama de release (ventana de estabilización) y sin ella (tag
+  directo desde integración), así que dai no fuerza a nadie a cambiar de estrategia para
+  ganar trazabilidad.
+- Aparecen dos variables nuevas de config (`DAI_NOTIFY`, `DAI_NOTIFY_WEBHOOK`, más
+  `DAI_NOTIFY_CHAT_ID` solo para Telegram) y dos métodos nuevos en el adaptador de PM
+  (`comment`, `listComments`), que cualquier backend nuevo tiene que implementar para
+  soportar el estampado de versión.
+- La skill `/dai-release` conduce el ciclo pero **no recalcula nada**: narra lo que dicen
+  los comandos. Si la skill y el CLI se contradicen, gana el CLI.

package/docs/adr/README.md

@@ -24,6 +24,7 @@ decisión cambia, se escribe un ADR nuevo que supersede al viejo. Molde en
 | [0016](0016-review-inline.md) | Review inline: `review.json` como contrato y puerta humana, el CLI valida las posiciones contra el diff, `--yes` explícito, nunca `APPROVE` | aceptado |
 | [0017](0017-env-dai.md) | La config de dai vive en `.env.dai` (no versionado), no en el `.env` del equipo; el loader lee ambos con precedencia shell > `.env.dai` > `.env` | aceptado |
 | [0018](0018-alcance-de-stamp-y-gate-de-ci.md) | El alcance de `dai stamp` lo decide la rama (ante la duda pregunta, no estampa de más), `dai check --ci` ejecuta el gate de governance con ramas exentas, y `dai edit-us`/`update-us` editan el QUÉ validando el formato y proponiendo el `spec_version` | aceptado |
+| [0019](0019-ciclo-de-version-y-aviso-de-release.md) | El ciclo de versión: el manifiesto de US como dato central, el bump se propone y lo firma una persona, el corte son dos comandos con una firma en el medio, el tag es la versión y los archivos son espejos, estampar es opcional y avisa su alcance, y el canal es un tercer adaptador con estructura sin formato | aceptado |
 
 > Estas son las decisiones que cierran las "Decisiones abiertas" de
 > [`METODOLOGIA.md §7`](../METODOLOGIA.md) y las enmiendas al

package/docs/guias/index.md

@@ -7,6 +7,9 @@ y tu **día a día**.
   porqué, nunca el CÓMO. Entrás por `grill-user-story`, `grill-epic` o `doc-to-backlog`.
 - [**Guía del dev / ingeniero**](./dev) — dueño del **CÓMO** y del **link**: el agente
   implementa con `/opsx:apply`, tú revisas y autoras el `implements.yaml`.
+- [**Guía de releases**](./releases) — el *porqué* del versionado: qué problema resuelve un
+  tag, por qué "una rama por ambiente" falla, los dos modelos y la pregunta que elige entre
+  ellos. Transversal: la lee el lead para decidir y el dev para entender qué firma.
 - [**Guía del lead / SM / arquitecto**](./lead) — custodio de las **invariantes** y del
   **nivel de ceremonia** (N1 / N2 / N3): haces que el método se cumpla y se aligere donde
   corresponde.