@dforce2055/dai 0.14.0 → 0.15.1

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.

package/docs/guias/releases.md

@@ -0,0 +1,156 @@
+# Guía de releases — por qué versionar, y cómo hacerlo sin ceremonia inútil
+
+> En una frase: **desplegar tiene que ser desplegar algo que ya existía y que ya se probó,
+> no armarlo en el momento.** Todo lo demás de esta guía sale de ahí.
+
+Esta guía es el *porqué*. Si ya lo tienes claro y solo quieres los comandos, ve al
+[tutorial del ciclo completo](../tutoriales/ciclo-de-release).
+
+## El problema, tal como se ve por dentro
+
+Hay equipos que no arman ramas de release ni etiquetan versiones. Cuando llega el momento
+de subir a producción, alguien se sienta a recordar qué ramas componen la funcionalidad y
+las va mergeando a la rama de producción, una por una.
+
+Eso falla de tres formas distintas, y las tres duelen:
+
+1. **Se despliega algo 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 de ese momento.
+2. **Nadie puede decir qué hay en producción.** Ni qué funcionalidades comprende. Y cuando
+   algo se rompe de noche, no hay un punto conocido al que volver.
+3. **Se cuelan cosas que no estaban listas**, porque la selección se hace rama por rama, a
+   mano y con prisa.
+
+Si te suena, el resto de la guía es para ti.
+
+## Lo que hay que separar, porque no es lo mismo
+
+La trampa habitual es intentar resolver los tres problemas con un solo mecanismo —
+normalmente "armemos una rama de release". En realidad son tres:
+
+| Problema | Se resuelve con |
+|---|---|
+| **Trazabilidad** — qué código hay en cada ambiente | identidad inmutable: un **tag** y un artefacto |
+| **Selección** — qué funcionalidades van | lo que está integrado, más *feature flags* |
+| **Estabilización** — arreglar sin frenar el desarrollo | **la rama de release**, y solo esto |
+
+La rama de release resuelve el tercero. Si tu equipo no necesita una ventana de
+estabilización, es ceremonia sin beneficio.
+
+## Las dos reglas que valen más que cualquier estrategia de ramas
+
+### 1. Construye una vez, promueve el artefacto
+
+Promover a producción es **desplegar el mismo binario/imagen/paquete** que ya pasó por
+test, con otra configuración. No es reconstruir desde otra rama.
+
+Si en cada ambiente vuelves a construir, probaste una cosa y desplegaste otra. Es el fallo
+más profundo del modelo "una rama por ambiente": el mismo commit produce artefactos
+distintos, y las ramas divergen en silencio cuando alguien olvida un *back-merge*.
+
+### 2. Desplegar no es lanzar
+
+Que el código esté en producción no obliga a que la funcionalidad esté visible. Un *feature
+flag* separa las dos cosas, y con eso desaparece el motivo real por el que se cuelan cosas a
+medias: ya no hace falta retener el código para retener la funcionalidad.
+
+Si algo llega a la rama de integración a medio hacer, ninguna rama de release lo va a
+salvar: vas a terminar sacando cosas *de* la release, que es la misma enfermedad al revés y
+más difícil de revertir. El control real es doble: **nada se integra si no es desplegable**
+(el gate de `dai check --ci`) y lo desplegable-pero-no-lanzable va detrás de un flag.
+
+## Los dos modelos, y la pregunta que elige
+
+**Modelo A — tronco y tag.** Una sola rama de vida larga. Ramas cortas (uno o dos días) con
+PR y gate de CI. Cada integración produce un artefacto; promover a producción es desplegar
+ese artefacto y etiquetar el commit exacto. Los *hotfix* salen del tag que está en
+producción, se etiquetan y se reintegran.
+
+**Modelo B — tronco y rama de release.** Igual que A, pero al cortar se crea
+`release/X.Y.Z` desde integración. Solo entran correcciones, y siempre **arregladas primero
+en integración y llevadas a la release** — nunca al revés, que es como se pierde el
+*back-merge*. Se etiqueta, se despliega, y **la rama se borra**: una rama de release que
+sobrevive a su release es un fork. (`dai release done` la borra solo; `dai release status`
+avisa de las que quedaron de antes.)
+
+> **La pregunta que decide:** ¿cuántos días pasan entre "dejamos de agregar" y "está en
+> producción"? Menos de un día → modelo A, la rama sería ceremonia. Varios días con
+> desarrollo en paralelo (QA de regresión, comité de cambios, ventana fija de despliegue) →
+> modelo B, y ahí la rama se gana su lugar.
+
+Nota incómoda pero honesta: la investigación de entrega de software encuentra que los
+equipos de alto desempeño tienen **ramas de vida corta y pocas ramas de larga vida**. Una
+rama de release que vive semanas correlaciona con peor desempeño, no mejor. Si tu ventana se
+alarga, conviene preguntarse si es porque hay menos que entregar o porque cada release
+duele — la segunda es un síntoma a atacar, no una razón para espaciar más.
+
+## Qué versión poner
+
+Depende de quién consume tu software:
+
+- **Una librería, un SDK, un paquete**: **semver**. El número comunica compatibilidad a
+  quien depende de ti, y eso es un contrato.
+- **Una aplicación interna** que nadie consume como dependencia: semver puede volverse
+  teatro — vas a discutir en reunión si algo es *minor* o *patch* para un número que no le
+  comunica nada a nadie. Ahí lo que necesitas es identidad **inequívoca y ordenada**
+  (`2026.09.1`, o un secuencial) más un manifiesto de qué contiene. El valor está en el
+  manifiesto, no en el número.
+
+Sea cual sea el esquema, **la decisión es de una persona**. dai propone un piso mirando los
+tipos de commit y lo dice; la regla que manda mira el **comportamiento observable**. Un
+cambio que mueve un valor por omisión es *minor* aunque todos los commits digan `fix:`.
+
+## Qué aporta dai
+
+dai no elige tu estrategia de ramas: eso es tuyo. Lo que aporta es el eslabón que falta en
+la trazabilidad.
+
+```
+User Story  →  implements.yaml  →  commit  →  PR  →  VERSIÓN  →  AMBIENTE
+                                                     └── esto es lo que agrega ──┘
+```
+
+Con eso, preguntas que hoy requieren una reunión se contestan desde el ticket:
+
+- **¿Qué entra en la próxima versión?** → `dai release plan`, que además muestra las US
+  cuyos criterios cambiaron después de implementarlas y lo que se coló sin declarar US.
+- **¿Esto ya está en producción?** → el comentario en la propia User Story, con versión,
+  aplicación, ambiente y fecha.
+- **¿Dónde estamos en el ciclo?** → `dai release status`, que también avisa si quedó un
+  *back-merge* pendiente.
+
+Y dos límites deliberados: **dai no despliega** (llega hasta el tag y vuelve a aparecer
+después, estampando) y **no mergea ni publica** — esas son firmas humanas.
+
+## Cómo lo adopta un equipo sin que se abandone en dos sprints
+
+1. **Declara tus dos ramas de vida larga** en el `.env.dai` y deja de discutirlo:
+   `DAI_BRANCH_DEV` (la que integra) y `DAI_BRANCH_PROD` (la que va a producción). Con eso,
+   `dai pr` deduce la base del tipo de rama y avisa cuando apuntas a producción.
+2. **Etiqueta la próxima versión aunque el proceso todavía sea manual.** El tag es lo que te
+   da el punto de retorno; todo lo demás se puede agregar después.
+3. **Corre `dai release plan` antes de cada corte, y léelo en voz alta en la reunión.** Es
+   donde aparecen las sorpresas mientras todavía se pueden arreglar.
+4. **Empieza a estampar solo en producción.** Si estampar en todos los ambientes hace
+   demasiado ruido, con producción alcanza para contestar la pregunta que más se hace.
+5. **Deja el aviso al canal para el final.** Es lo que hace visible el cambio para el resto
+   de la organización, y conviene encenderlo cuando el ciclo ya funciona.
+
+## Preguntas frecuentes
+
+**No usamos npm y no tenemos `package.json`. ¿Sirve igual?**
+Sí. El tag es la versión; los archivos son espejos opcionales. dai actualiza los que
+reconoce, dice cuáles tocó, y no se detiene si no hay ninguno.
+
+**Nuestra rama principal despliega a producción.**
+Decláralo en `DAI_BRANCH_PROD`. dai marcará esa base en el previo de la PR y pedirá una
+confirmación explícita antes de proponer un merge hacia ahí.
+
+**¿Y si no queremos llenar los tickets de comentarios?**
+No estampes. La versión ya está hecha cuando llegas a ese paso: `dai release stamp` es
+opcional y decir que no no rompe nada. Muchos equipos prefieren avisar solo al canal.
+
+**¿Cada cuánto conviene sacar una versión?**
+Tan seguido como el equipo tolere sin dolor. Si la respuesta a "¿por qué no más seguido?" es
+*"no hay tanto que entregar"*, está bien. Si es *"porque cada release cuesta"*, eso es lo que
+hay que arreglar — y espaciar los releases lo empeora, porque agranda el lote.

package/docs/tutoriales/ciclo-de-release.md

@@ -0,0 +1,266 @@
+# Ciclo de release, paso a paso
+
+De "hay cosas para sacar" a "producción sabe qué versión tiene y cada User Story lo dice".
+Unos 15 minutos la primera vez.
+
+El *porqué* de todo esto está en la [guía de releases](../guias/releases). Acá van los
+comandos.
+
+> **Lo hace la persona, no el agente.** dai prepara, muestra y confirma; mergear, publicar y
+> desplegar los firmas tú. Si prefieres que un asistente te acompañe paso a paso, invoca la
+> skill `/dai-release` — usa exactamente estos comandos y frena en las mismas firmas.
+
+## Antes de empezar
+
+Declara las dos ramas de vida larga de tu repositorio en el `.env.dai`. Es lo único que
+tienes que configurar, y se hace una sola vez:
+
+```bash
+# .env.dai  (no se versiona)
+DAI_BRANCH_DEV=develop     # la rama que integra el desarrollo
+DAI_BRANCH_PROD=main       # la rama que despliega a producción
+```
+
+Comprueba que dai las ve:
+
+```bash
+dai release status
+```
+
+```
+› versión declarada: 0.4.2  (VERSION)
+› último tag: v0.4.2
+⚠ 'develop' tiene 6 commit(s) sin promover · 3 US · bump propuesto: minor.
+    Ver el detalle:  dai release plan
+```
+
+Si dice que falta un *back-merge* de la versión anterior, resuélvelo antes de seguir: cortar
+una versión sobre otra a medio cerrar arrastra el problema.
+
+## Paso 1 · Qué entra — `dai release plan`
+
+```bash
+dai release plan
+```
+
+```
+  ── Release a preparar ────────────────────────────────
+  desde:    v0.4.2
+  hasta:    develop
+  cambios:  6 commit(s) · 5 merge(s)
+  versión:  0.4.2 → 0.5.0  (minor)
+  ─────────────────────────────────────────────────────
+  User Stories que entran (3):
+    ✅ ACME-482  v2  Checkout sin duplicado
+    ⚠️  ACME-491  v1  Alta de póliza sin duplicar cliente
+                  ATRASADA
+    ✅ ACME-503  v3  Recordar medio de pago
+
+  ⚠ 1 US ATRASADA(S): el QUÉ cambió después de implementarlo.
+    Esta release las llevaría sin cubrir el criterio nuevo. Revisalas antes de cortar.
+
+  Sin US, por tipo de branch (1): chore/deps
+
+  ⚠ 1 branch(es) sin US y sin prefijo exento:
+      arreglo-rapido
+```
+
+**Esta es la pantalla importante del ciclo.** Léela entera antes de seguir:
+
+- **US atrasadas** — alguien cambió los criterios de aceptación después de que se
+  implementaran. Puedes cortar igual (a veces el criterio nuevo va en la próxima versión),
+  pero que sea una decisión y no un descuido.
+- **Ramas sin US y sin prefijo exento** — entró trabajo que nadie va a poder rastrear a una
+  historia. Es la última oportunidad de verlo.
+
+Con `--json` sale el mismo manifiesto estructurado, para scripts o para un asistente.
+
+## Paso 2 · La versión — la firmas tú
+
+dai **propone** un piso mirando los tipos de commit y lo dice:
+
+```
+  minor: 3 commit(s) feat: agregan funcionalidad
+  propuesta a partir de los TIPOS de commit — la regla del repo mira el COMPORTAMIENTO.
+```
+
+La regla que manda mira el **comportamiento observable**: si algo mueve un valor por
+omisión, agrega una opción o cambia lo que ve quien no configura nada, es *minor* aunque
+todos los commits digan `fix:`. Esa decisión es tuya.
+
+## Paso 3 · Cortar — `dai release cut`
+
+```bash
+dai release cut 0.5.0
+```
+
+Crea la rama `release/0.5.0`, sube el número en los archivos que tu repositorio espeja,
+escribe la entrada del CHANGELOG y hace el commit. **No habla hacia afuera**: no hay *push*,
+ni tag, ni PR.
+
+```
+✓ branch release/0.5.0
+✓ VERSION: 0.4.2 → 0.5.0
+✓ package.json: 0.4.2 → 0.5.0
+✓ CHANGELOG.md: entrada para 0.5.0
+✓ commit chore(release): v0.5.0
+```
+
+> ¿Tu repositorio no tiene `VERSION` ni `package.json`? No pasa nada: el tag es la versión y
+> dai te lo dice. ¿Trabajas sin rama de release, etiquetando directamente desde integración?
+> Usa `--no-branch`.
+
+## Paso 4 · El CHANGELOG — lo escribes tú
+
+dai deja el material y las secciones vacías:
+
+```markdown
+## [0.5.0] — 2026-09-09
+
+<!-- dai:manifiesto · el material de esta versión. Repartilo abajo y contá el porqué:
+     dai sabe qué entró; por qué importa lo sabés vos.
+     ACME-482  Checkout sin duplicado
+     ACME-491  Alta de póliza sin duplicar cliente
+-->
+
+### Agregado
+### Cambiado
+### Corregido
+### Interno
+```
+
+Reparte las historias en las secciones que correspondan, **explica por qué importaba cada
+una** y borra el comentario. Un changelog que solo lista lo que entró no lo lee nadie; uno
+que cuenta qué estaba mal se lee seis meses después.
+
+Luego, el commit y la PR:
+
+```bash
+git add CHANGELOG.md && git commit -m "docs(changelog): reparte el manifiesto de la 0.5.0"
+dai pr --description-file notas.md
+```
+
+La base sale sola: una rama `release/` va contra tu rama de producción, y dai te lo marca y
+te pide que escribas el nombre de la rama para confirmar.
+
+## Paso 5 · Merge y publicación — tu firma
+
+Apruebas y mergeas la PR, y ejecutas lo que tu repositorio use para publicar (`npm publish`,
+un despliegue, lo que sea). **El ciclo no terminó acá**: faltan el tag, la nota de release y
+el *back-merge* — los tres pasos que más se olvidan cuando esto se hace de memoria.
+
+## Paso 6 · Cerrar — `dai release done`
+
+```bash
+dai release done 0.5.0
+```
+
+```
+  ── Cerrar la versión 0.5.0 ──────────────────────────
+  tag:      v0.5.0 → main @ 177719f3
+  release:  nota en el forge
+  back-merge: main → develop
+  aviso:    webex · webexapis.com
+  ─────────────────────────────────────────────────────
+✓ tag v0.5.0 creado y publicado
+✓ release note publicada
+✓ back-merge main → develop
+```
+
+Y borra la rama `release/0.5.0` (local y remota): ya está mergeada, etiquetada y con el
+back-merge hecho, así que no tiene más razón de existir — una rama de release que sobrevive
+a su release es un fork. Si quieres conservarla, `--keep-branch`. Si git se niega a
+borrarla, es porque tiene commits que no llegaron a producción: revísala.
+
+Cada paso se reporta por separado a propósito: **una vez creado el tag, la versión existe**.
+Si falla la nota de release, dai te lo dice y aclara que el tag ya está publicado, para que
+completes solo lo que falta.
+
+## Paso 7 · Estampar el despliegue — opcional
+
+Cuando la versión llega a un ambiente:
+
+```bash
+dai release stamp 0.5.0 --env prod --app acme-backend
+```
+
+```
+  ── Estampar despliegue ───────────────────────────────
+  versión:  v0.5.0     app: acme-backend     ambiente: PROD
+  tracker:  jira · 3 User Storie(s) en el release
+  ─────────────────────────────────────────────────────
+    ACME-482  Checkout sin duplicado
+    ACME-491  Alta de póliza sin duplicar cliente
+    ACME-503  Recordar medio de pago
+  ─────────────────────────────────────────────────────
+⚠ esto escribe 3 comentario(s) en el tracker de todo el equipo. No se deshace.
+  ¿Estampo 3 comentario(s)? (s/N)
+```
+
+Cada User Story recibe un comentario con versión, aplicación, ambiente y fecha. Desde ese
+momento, el funcional abre el ticket y sabe dónde está su historia sin preguntar. Si una US
+se implementa en varios repositorios, el ticket va acumulando la matriz: *backend en
+producción, frontend en pre*.
+
+**Es opcional.** Decir que no sale con código 0 y no rompe nada: la versión ya está hecha.
+Si tu equipo prefiere no llenar los tickets, avisa solo al canal.
+
+Volver a ejecutarlo **no duplica**: dai reconoce sus propios comentarios por
+`(aplicación, versión, ambiente)` y saltea los que ya están. La misma versión en otro
+ambiente sí es un evento nuevo y se estampa.
+
+## Paso 8 · El aviso al equipo — opcional
+
+Si declaras un canal, `done` y `stamp` avisan solos:
+
+```bash
+# .env.dai
+DAI_NOTIFY=webex               # discord | slack | webex | telegram | webhook | none
+DAI_NOTIFY_WEBHOOK=https://…   # SECRETO: quien lo tiene, puede publicar
+```
+
+Antes de depender de él, pruébalo:
+
+```bash
+dai release notify --test
+```
+
+El mensaje que sale es siempre el mismo, en cualquier canal:
+
+```
+🚀 Release desplegada · acme-backend v0.5.0 → PROD
+Autor: Ada Lovelace · Fecha: 09/09/2026 09:15
+
+Cambios principales:
+ • ACME-482  Checkout sin duplicado
+ • ACME-491  Alta de póliza sin duplicar cliente
+ • ACME-503  Recordar medio de pago
+
+Ver release: https://…/releases/v0.5.0
+```
+
+Las viñetas son las **User Stories**, no los commits: lo que el equipo quiere leer es qué
+valor salió, no qué archivos se tocaron.
+
+## El ciclo entero, resumido
+
+```bash
+dai release status                        # ¿dónde estoy?
+dai release plan                          # ¿qué entra?  ← la pantalla importante
+dai release cut 0.5.0                     # rama + número + CHANGELOG + commit
+# … escribes el CHANGELOG …
+dai pr                                    # PR a producción (te pide confirmación)
+# … mergeas y publicas: tu firma …
+dai release done 0.5.0                  # tag + nota + back-merge + aviso
+dai release stamp 0.5.0 --env prod        # opcional: avisar a cada US
+```
+
+## Si algo sale mal
+
+| Síntoma | Qué hacer |
+|---|---|
+| `no existe el tag vX.Y.Z` al estampar | Cierra la versión primero (`dai release done`), o trae los tags con `git fetch --tags`. |
+| `done` creó el tag pero falló la nota | El tag ya está: la versión existe. Publica la nota a mano con el comando que dai te deja impreso. |
+| El manifiesto no muestra ninguna US | ¿Las ramas tenían `implements.yaml`? Sin link no hay trazabilidad que reportar. |
+| El tracker no responde | `dai release plan --no-network` sale igual, avisando que no pudo verificar. |
+| Salieron comentarios repetidos | dai no pudo leer los comentarios previos y lo avisó. Revisa el token del tracker. |

package/docs/tutoriales/index.md

@@ -11,6 +11,12 @@ Guías de **setup operativo** — lo que haces una vez por máquina para trabaja
   + `glab`, las skills en Copilot, OpenSpec y el ciclo completo sobre una US real
   (`link-us` → `check` → `mr` → `stamp`).
 
+## El día a día
+
+- [**Ciclo de release**](./ciclo-de-release) — de "hay cosas para sacar" a "producción sabe
+  qué versión tiene y cada User Story lo dice": manifiesto, corte, tag, nota de release y el
+  aviso a cada historia. El *porqué* está en la [guía de releases](../guias/releases).
+
 ## Preparar el entorno
 
 - [**Configurar git**](./configurar-git) — tu identidad (nombre + correo) para que los

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforce2055/dai",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "description": "Metodología de desarrollo asistido por IA — CLI de acciones deterministas (trazabilidad QUÉ↔CÓMO).",
   "repository": { "type": "git", "url": "git+https://github.com/dforce2055/dai.git" },
   "homepage": "https://dforce2055.github.io/dai/",