@dforce2055/dai 0.14.0 → 0.15.0

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.0",
   "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/",

package/skills/dai-release/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: dai-release
+description: "Conduce el ciclo de versión de un repo con dai, paso a paso y confirmando cada uno: el manifiesto de qué entra (qué User Stories, cuáles atrasadas, qué se coló sin US), la versión que corresponde, el corte de la release, la redacción del CHANGELOG, el cierre con tag + release note + back-merge, y —opcional— el aviso a cada US de en qué versión y ambiente salió más la notificación al canal del equipo. Se apoya en `dai release plan/cut/done/stamp/status`: NO recalcula nada por su cuenta, narra lo que el CLI dice. Frena en las dos firmas humanas (aprobar la versión; mergear y publicar) y nunca las salta. Invocar como /dai-release, opcionalmente con la versión. Usar cuando alguien dice 'cortemos una versión', 'hay que sacar release', 'promover a producción' o 'qué entra en la próxima'."
+---
+
+# dai-release — conducir el ciclo de versión
+
+Un release tiene doce pasos, dos de ellos son firmas humanas, y los dos que más se olvidan
+están **después** de la firma — el release note y el back-merge. Nadie los recuerda todos, y
+por eso se hacen mal. Esta skill los conduce.
+
+## El reparto: el CLI sabe, tú contás
+
+No calculás el manifiesto ni derivás la versión. Los comandos ya lo hacen, igual con
+Claude, con Copilot o sin ningún asistente ([ADR-0002](../../docs/adr/0002-agnostico-del-asistente.md)):
+
+```
+dai release plan --json   →   vos   →   la persona decide
+qué entró, en qué estado      lo contás     firma o corrige
+```
+
+**Nunca inventes el contenido del manifiesto.** Si `dai release plan` no lista una US, esa
+US no entró — aunque la recuerdes del chat. Si el CLI y tu memoria no coinciden, gana el CLI
+y lo decís en voz alta.
+
+Lo que sí es tuyo, porque ningún comando puede hacerlo:
+
+1. **Proponer el bump mirando el comportamiento.** El CLI lo deriva de los tipos de commit
+   y lo dice: es un piso, no un veredicto. Vos leés el diff. Si algo mueve un default,
+   agrega un flag o cambia lo que ve quien no configura nada, **es minor aunque todo sea
+   `fix:`** — le pasó a este mismo repo en la 0.14.0, cuatro commits `fix:` que eran minor.
+2. **Escribir el CHANGELOG.** El CLI deja el material (las US) y las secciones vacías. La
+   prosa la escribís vos: dai sabe *qué* entró, no *por qué importa*.
+3. **Ver lo que falta.** Una US atrasada en el manifiesto, una branch que entró sin link,
+   el back-merge de la release anterior que nunca se hizo.
+4. **Frenar en las firmas.** Y saber que después de la firma quedan pasos pendientes.
+
+## Antes de empezar
+
+Corré `dai release status`. Te dice dónde está el repo en el ciclo y evita el error más
+común: cortar una versión cuando la anterior quedó a medio cerrar.
+
+## El ciclo
+
+```
+ plan ──▶ [FIRMA 1: la versión] ──▶ cut ──▶ CHANGELOG ──▶ dai pr
+                                                            │
+                              [FIRMA 2: merge + publicar] ◀──┘
+                                        │
+                                        ▼
+                        done ──▶ stamp (opcional) ──▶ aviso (opcional)
+```
+
+### 1 · El manifiesto — `dai release plan`
+
+Corré `dai release plan` y **contá lo que dice**, no lo que esperabas que dijera:
+
+- cuántas US entran y cuáles;
+- **cuáles están ATRASADAS** — el QUÉ cambió después de implementarlas, así que esta
+  versión las llevaría sin cubrir el criterio nuevo. Nombralas una por una;
+- **qué branches entraron sin US y sin prefijo exento** — es la última pantalla donde eso
+  se puede ver antes de que quede adentro de una versión;
+- el bump propuesto y su justificación.
+
+Si hay US atrasadas o branches huérfanas, **preguntá antes de seguir**: *"¿cortamos igual,
+o querés resolver esto primero?"* No decidas vos. Cortar con una US atrasada es legítimo
+—a veces el criterio nuevo va en la próxima— pero tiene que ser una decisión, no un
+descuido.
+
+### 2 · La versión — FIRMA HUMANA
+
+Proponé la versión **con tu propio análisis del comportamiento**, no repitiendo el bump del
+CLI. Decí explícitamente si coincidís con él o no, y por qué:
+
+> El CLI propone `patch` (solo hay commits `fix:`). Yo propongo **minor**: el default de
+> `dai pr` cambió, y quien actualice sin leer el changelog lo va a notar. ¿Vamos con 0.15.0?
+
+**Esperá el sí.** Sin confirmación explícita en este turno, no sigas. Un "dale" de un
+release anterior no cuenta.
+
+### 3 · Cortar — `dai release cut <X.Y.Z>`
+
+Mostrá el preview del comando y confirmá antes de correrlo con `--yes` (o dejá que pregunte
+él). Crea la branch de release, sube el número en los archivos que el repo espeja, escribe
+la entrada del CHANGELOG y commitea. **No habla hacia afuera:** ni push, ni tag, ni PR.
+
+Si el repo trabaja sin branch de release (todo sale de la rama de integración), es
+`--no-branch`. Preguntá cuál es el flujo si no está claro; no lo asumas.
+
+### 4 · El CHANGELOG — tu parte
+
+`cut` deja la entrada con el material en un comentario y las secciones vacías. **Escribila.**
+Mirá cómo están escritas las entradas anteriores del repo y seguí esa voz. Si el repo no
+tiene ninguna, el estándar es:
+
+- abrí con **qué estaba mal o qué cambia**, en una o dos frases, para alguien que no siguió
+  el desarrollo;
+- cada ítem explica **por qué importaba**, no qué archivos se tocaron;
+- repartí las US del comentario en las secciones que correspondan y **borrá el comentario**.
+
+Un changelog que solo lista commits no lo lee nadie. Si no sabés por qué un cambio importa,
+**preguntá** — es exactamente la información que solo tiene una persona.
+
+Después, commiteá el CHANGELOG y abrí la PR con `dai pr`. La base sale sola del mapa de
+ramas: una branch `release/` va contra la rama de producción y pide confirmación explícita.
+
+### 5 · Merge y publicación — FIRMA HUMANA
+
+**Acá parás.** Mergear la PR y publicar (npm, un deploy, lo que este repo use) lo hace una
+persona. Si el repo tiene un `RELEASING.md`, leelo y decí los pasos exactos que le tocan.
+
+Decí claramente que **el ciclo no terminó**: falta el tag, el release note y el back-merge.
+Es justo acá donde se abandonan los releases hechos a mano.
+
+### 6 · Cerrar — `dai release done <X.Y.Z>`
+
+Después del merge. Tag anotado, release note en el forge, back-merge a integración y aviso
+al canal. Cada paso reporta por separado: **si falla la release note, el tag ya existe** —
+decilo, no lo tapes.
+
+También **borra la rama de release** que cerró: ya está mergeada, etiquetada y con el
+back-merge hecho. Si git se niega, es porque tiene commits que no llegaron a producción —
+decilo, no lo tapes con `--keep-branch`.
+
+### 7 · Estampar — `dai release stamp <X.Y.Z> --env <ambiente>` · OPCIONAL
+
+Cuando la versión llega a un ambiente. Le deja a **cada US del release** un comentario
+diciendo en qué versión y ambiente salió, y con eso el funcional lee el ticket en vez de
+preguntar.
+
+**Antes de correrlo, avisá el alcance en voz alta**: *"esto va a escribir N comentarios en
+N tickets, que puede tocar a varias personas del equipo, y no se deshace"*. El comando
+muestra el detalle y confirma; tu trabajo es que nadie llegue a esa pantalla sin saber qué
+va a pasar.
+
+**Si dicen que no, seguí adelante.** No es un error ni hay que insistir: la versión ya está
+hecha. Decí una vez qué se pierde (el ticket no va a registrar en qué versión salió) y
+ofrecé la alternativa: *"¿preferís que solo avise al canal?"*. Muchos equipos no quieren
+hacer ruido en veinte tickets, y es una decisión legítima.
+
+### 8 · El aviso al canal · OPCIONAL
+
+Sale solo con `done` y con `stamp` si el repo declaró `DAI_NOTIFY`. Mostrá el mensaje
+exacto antes de mandarlo. Si el repo no lo declaró y el equipo quiere avisar, `dai release
+notify --test` prueba el canal antes de depender de él.
+
+## Reglas que no se negocian
+
+- **No mergeás, no publicás, no desplegás.** Esas son firmas humanas
+  ([Art. 5](../../docs/MANIFIESTO.md#art-5) del manifiesto).
+- **No inventás el manifiesto ni la versión.** El manifiesto sale del CLI; la versión la
+  firma una persona.
+- **No escribís un CHANGELOG que no entendés.** Preguntá.
+- **No estampás sin avisar el alcance**, y un "no" se acepta sin insistir.
+- **No cierres el ciclo sin el release note y el back-merge.** Son los dos que se olvidan.
+- **Nada de datos de terceros** en el CHANGELOG, el release note ni el aviso: ni nombres de
+  empresas, ni de personas ajenas al repo, ni URLs corporativas. Si el material que tenés a
+  mano los trae, traducilos.
+
+## Cuando algo no cierra
+
+- **El tracker no responde** → el manifiesto sale igual con `--no-network`, diciendo que no
+  pudo verificar. Es preferible a no tener manifiesto; decilo al contarlo.
+- **`done` falla a mitad de camino** → mirá qué reportó cada paso. Si el tag salió, la
+  versión existe: lo que falta es la nota o el back-merge, y se completan a mano.
+- **El repo no tiene VERSION ni package.json** → normal. El tag es la versión; `cut` lo dice.
+- **No hay tags todavía** → el manifiesto arranca desde el principio del repo. Es correcto.