@dforce2055/dai 0.13.3 → 0.15.0

package/.env.dai.example

@@ -12,6 +12,37 @@ DAI_PM=md
 # Si dai no puede saber el link, avisa y deja la PR sin él — nunca escribe el id pelado.
 # DAI_TRACKER_URL_TEMPLATE=https://jira.miempresa.com/browse/{id}
 
+# ── Flujo de branches (dai pr · dai done) ────────────────────────────────────
+# Las DOS ramas de vida larga del repo. No se configura "la base" de las PR: la base sale
+# del TIPO de branch, y con eso dai deja de adivinar.
+#   feature/ · fix/     → PR contra DAI_BRANCH_DEV
+#   release/ · hotfix/  → PR contra DAI_BRANCH_PROD, con confirmación explícita
+#
+# Rama que INTEGRA el desarrollo (la que se despliega a test). Sin declarar, dai usa la
+# rama default del remoto (origin/HEAD) y avisa que la está adivinando.
+# DAI_BRANCH_DEV=testing
+
+# Rama que DESPLIEGA A PRODUCCIÓN. `dai pr` la marca en el preview y pide confirmación
+# antes de publicar; con --yes hace falta --to-prod. Sin declarar, dai no marca ninguna
+# rama como producción: no adivina cuál es.
+# DAI_BRANCH_PROD=main
+
+# ── Aviso de release a un canal de equipo (opcional) ─────────────────────────
+# Tercer adaptador de dai, con la misma forma que DAI_PM: una variable elige el canal y el
+# canal trae las suyas. Por default no hay aviso: dai no habla hacia afuera sin pedirlo.
+#   discord | slack | webex | telegram | webhook | none
+# `webhook` es el genérico: manda los campos del release en JSON a cualquier endpoint
+# (Teams, Mattermost, un sistema interno) e incluye además el texto ya armado.
+# DAI_NOTIFY=webex
+
+# El endpoint del canal. ⚠️ ES LA CREDENCIAL: quien lo tiene, puede postear. Nunca lo
+# commitees; dai muestra el host, nunca la URL. Probalo con `dai release notify --test`.
+# DAI_NOTIFY_WEBHOOK=
+
+# Solo para telegram: no tiene webhooks de entrada, así que el endpoint es el bot y hace
+# falta decir a qué chat va el mensaje.
+# DAI_NOTIFY_CHAT_ID=
+
 # ── Backend md (local, offline) ──────────────────────────────────────────────
 # Carpeta donde viven las US como <ID>.md (p. ej. ABC-482.md).
 DAI_MD_US_DIR=.dai/us

package/CHANGELOG.md

@@ -3,6 +3,137 @@
 Formato basado en [Keep a Changelog](https://keepachangelog.com/). Versionado semver
 (ver `VERSION`).
 
+## [0.15.0] — 2026-09-09
+
+**Un equipo puede tener el link QUÉ↔CÓMO perfecto y seguir sin poder contestar la pregunta
+que hace el negocio: "¿esto ya está en producción?". La trazabilidad llegaba hasta la PR y
+se cortaba justo ahí. Esta versión agrega el último eslabón — la versión desplegada — y con
+él, el ciclo completo para cortarla, cerrarla y contarla.**
+
+### Agregado
+- **`dai release plan` — el manifiesto de la versión.** 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. Resuelve las US 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 branch se borre y a que el change se archive — el estado
+  normal del repo cuando llegás a cortar, días después del merge. Es el dato del que
+  dependen los otros cuatro comandos; `--json` es lo que consume la skill.
+- **`dai release cut <X.Y.Z>` — preparar, sin hablar hacia afuera.** Rama de release, número
+  en los archivos que el repo espeja, entrada del CHANGELOG y commit. Ni push, ni tag, ni
+  PR: todo lo que pasa ANTES de la firma humana.
+- **`dai release done <X.Y.Z>` — cerrar, después del merge.** Tag anotado, release note en
+  el forge, back-merge a integración, borrado de la rama de release y aviso al canal. Existe
+  como comando separado porque los dos pasos que más se olvidan cuando la ceremonia se hace
+  a mano viven en esta mitad, la que queda después de la firma. Se llama `done` y no
+  `finish` por lo mismo que `dai done` cierra el trabajo de una branch: mismo verbo, distinto
+  sustantivo.
+- **`dai release stamp <X.Y.Z> --env <ambiente>` — que cada US sepa dónde está.** Deja en
+  cada historia del release un comentario con versión, app, ambiente y fecha, y con eso el
+  funcional lee el ticket en vez de preguntar. Una US federada en varios repos acumula sola
+  su matriz. Es **opcional** y decir que no sale con 0: cuando el comando corre, el tag ya
+  existe y la versión está hecha.
+- **`dai release status`** — dónde estás en el ciclo: versión declarada vs último tag, qué
+  falta promover, si quedó un back-merge pendiente, qué ramas de release sobrevivieron.
+  **`dai release notify --test`** — probar el canal antes de depender de él, porque un
+  webhook no se puede validar sin postear y fingir que sí sería justo lo que dai no hace.
+- **Aviso de release a un canal de equipo** (`DAI_NOTIFY`): discord, slack, webex, telegram
+  o un `webhook` genérico para Teams, Mattermost o un sistema interno. Apagado por default:
+  dai no habla hacia afuera sin que se lo pidan. El endpoint **es la credencial**, así que
+  vive en el `.env.dai` y dai muestra el host, nunca la URL — tampoco en los errores.
+- **Skill `/dai-release`** — conduce el ciclo confirmando paso a paso. No recalcula el
+  manifiesto: lo pide y lo narra. Si su memoria y el CLI se contradicen, gana el CLI.
+- **[Guía de releases](docs/guias/releases.md)** con el *porqué* y
+  **[tutorial del ciclo completo](docs/tutoriales/ciclo-de-release.md)**. Una estrategia de
+  branching que el equipo no entiende se abandona en dos sprints, así que la documentación
+  entra en la misma versión que los comandos, no después.
+
+### Corregido
+- **`dai pr` no podía abrir la PR de una `feature/` en un repo sin User Stories.** Le pasa a
+  cualquier repo de tooling o librería interna que use dai para versionar sin gestionar sus
+  propias historias — a este, sin ir más lejos, donde el mensaje mandaba a renombrar la
+  branch a `chore/`. Lo que distingue un olvido de un repo que no trabaja así es si la
+  branch **nombra un ticket**. El gate de CI no se toca.
+- **Un aviso que aparece siempre no avisa nada.** El manifiesto marcaba cada branch sin US
+  como "entró trabajo sin link", incluso en repos donde ninguna branch va a declarar una
+  jamás. Ahora el hallazgo se reporta solo si el repo trabaja con User Stories — salvo que
+  la branch nombre un ticket, que ahí sí es un olvido.
+- **`dai pr` fallaba al actualizar una PR por un motivo que no era suyo.** `gh pr edit`
+  resuelve por GraphQL y arrastra campos deprecados del servidor, así que devolvía un error
+  sobre *Projects (classic)* cuando lo único que se quería era cambiar el body. Ahora
+  reintenta por REST con la misma autenticación; se intenta callado y solo se reporta si el
+  plan B también falla.
+
+### Interno
+- **475 tests** (+68 desde la 0.14.0): el manifiesto y su resolución por commit, el corte y
+  el cierre, el gate de alcance del estampado y su idempotencia por (app, versión,
+  ambiente), y el adaptador de canal — incluidos tres tests que fallan si el endpoint se
+  filtra en algún mensaje.
+- El adaptador de PM suma `comment(id, markdown)` y `listComments(id)` en los tres backends:
+  sin poder leer sus propios comentarios, dai no puede saber qué ya estampó.
+- Esta versión se cortó con los comandos nuevos, y el dogfooding devolvió tres de las
+  correcciones de arriba.
+
+## [0.14.0] — 2026-09-08
+
+**`dai pr` proponía mergear a `main` en un repo donde `main` despliega a producción, y el
+preview no lo destacaba de ninguna forma. Tirando de ese hilo apareció que el problema no
+era el default: era pedirle a alguien que configure "la base", cuando la base no es una
+constante — es consecuencia del tipo de branch. Y de yapa, el hallazgo más caro de la
+versión: `dai <comando> --help` no imprimía ayuda, ejecutaba el comando.**
+
+### Cambiado
+- **La base de una PR sale del mapa de ramas del repo, no de un `main` fijo.** Se declaran
+  las **dos ramas de vida larga** en el `.env.dai` —`DAI_BRANCH_DEV` (la que integra) y
+  `DAI_BRANCH_PROD` (la que despliega a producción)— y `dai pr` deriva la base del **tipo de
+  branch**: `feature/` y `fix/` integran, `release/` y `hotfix/` van contra producción.
+  `--base` gana siempre. Sin nada declarado, dai cae a la rama default del remoto
+  (`origin/HEAD`) **y avisa que la está adivinando** — antes decía `main` sin más.
+  `dai done` usa el mismo mapa (tenía el mismo `main` hardcodeado) y `dai doctor` lo reporta.
+  El preview ahora dice **de dónde salió** la base, que era la mitad que faltaba
+  ([#46](https://github.com/dforce2055/dai/issues/46)).
+- **Apuntarle a producción pide confirmación explícita.** Si la base es `DAI_BRANCH_PROD`,
+  el preview la marca `⚠️ DESPLIEGA A PRODUCCIÓN` y hay que **escribir el nombre de la rama**
+  para seguir; con `--yes` hace falta `--to-prod`. Sin la variable declarada dai no marca
+  ninguna rama como producción: no adivina cuál es, y un gate inventado sobre una suposición
+  es peor que no tenerlo.
+- **`dai <comando> --help` imprime ayuda en vez de ejecutar el comando.** Vale para todos:
+  `dai help`, `dai --help`, `dai -h`, `dai help <cmd>`, `dai <cmd> --help`, `dai <cmd> -h` y
+  `dai <cmd> help`. Siempre por `stdout` y siempre con código 0; un comando desconocido sigue
+  saliendo por `stderr` con código ≠ 0, que es lo que deja `dai foo --help` usable dentro de
+  un script. Cada comando tiene ayuda propia (qué hace, uso, opciones, ejemplo).
+
+### Corregido
+- **`dai pr` dejaba una MR con el diff al día y la descripción vieja.** Con una MR ya abierta
+  pusheaba la branch, fallaba al crear porque la MR existía, y la única señal era el comando
+  crudo del forge. Quedaba una MR que **miente sobre lo que contiene**, que es peor que un
+  error porque parece que salió bien. Ahora la detecta **antes** de pushear
+  (`gh pr list --head` / `glab mr list --source-branch`), el preview dice
+  `── Pull Request a ACTUALIZAR (#12) ──` y actualiza título y descripción. Si la detección no
+  pudo correr y el forge responde *"already exists"*, la busca y la actualiza igual; si tampoco
+  puede, lo dice con todas las letras: *"NO toqué su descripción: quedó la vieja"*. También
+  avisa si la MR abierta apunta a otra base que la pedida ([#46](https://github.com/dforce2055/dai/issues/46)).
+- **`dai link-us` estampaba `version: v1` en una US que declaraba `v4`.** El regex del
+  `spec_version` exigía separador y la US lo escribía pegado (`specversion`) — y estaba
+  **duplicado en dos módulos**, que es exactamente por qué se podía arreglar en uno y seguir
+  roto en el otro. Ahora vive en un solo lugar y tolera `spec_version`, `spec version`,
+  `spec-version` y `specversion`. Sin `spec_version` declarado **no se inventa un `v1`**: queda
+  `pendiente` con aviso, porque ese número se publica en el cuerpo de la PR y se estampa en el
+  tracker como si fuera un dato. `dai check` además avisa cuando el número del link no coincide
+  con el de la US viva ([#46](https://github.com/dforce2055/dai/issues/46)).
+- **`dai pr` no podía abrir la PR de un repo sin US.** En un repo que no se trackea a sí mismo
+  con User Stories —el de dai, sin ir más lejos— una branch `fix/` sin ID moría pidiendo un
+  link que no puede existir, y aconsejaba renombrarla a `chore/`, que para un fix es el consejo
+  equivocado. Ahora, si la branch no exige link **y** el repo no declara ninguna US, la PR sale
+  "Sin US" con el motivo. Una `feature/` sin link sigue fallando: ahí falta de verdad.
+- **`.env.dai` no estaba en el `.gitignore` de este repo**, aunque `dai init` lo agrega en todos
+  los que scaffoldea. Faltaba justo en el que se publica en npm.
+
+### Interno
+- **408 tests** (+41): el mapa de ramas y la derivación por tipo de branch, la detección y
+  actualización de una PR existente en los dos forges, las variantes del `spec_version`, y la
+  convención de ayuda — con un test que recorre los `case` del dispatcher y **falla si alguno se
+  agrega sin ayuda**, para que la convención no dependa de acordarse.
+
 ## [0.13.3] — 2026-09-02
 
 **Una PR de dai se abría diciendo, en el mismo párrafo, dos cosas que no encajaban: que el
@@ -857,6 +988,8 @@ ClickUp y Jira Cloud.
 - Tests de las rutas de red (jira/clickup/forge) con `fetch` mockeado. Sin links rotos;
   `files` de npm sin tests ni secretos.
 
+[0.15.0]: https://github.com/dforce2055/dai/releases/tag/v0.15.0
+[0.14.0]: https://github.com/dforce2055/dai/releases/tag/v0.14.0
 [0.13.3]: https://github.com/dforce2055/dai/releases/tag/v0.13.3
 [0.13.2]: https://github.com/dforce2055/dai/releases/tag/v0.13.2
 [0.13.1]: https://github.com/dforce2055/dai/releases/tag/v0.13.1

package/README.md

@@ -202,13 +202,15 @@ flowchart TD
 | `dai link-us <ID> --resync` | re-estampa el `ac_hash` contra la US viva (tras un ⚠️ de check) |
 | `dai check` | compara tu código vs la US viva → ✅ al día / ⚠️ atrasado (exit code = gate de PR) |
 | `dai ls [--json]` | lista las US que implementa el repo + su link al tracker |
-| `dai pr [--assignee u] [--base b] [--draft] [--yes] [--us ID] [--title t] [--description t\|--description-file f] [--changes t\|--changes-file f]` · alias **`dai mr`** | crea TU PR/MR precargada: pregunta la branch base (default `main`), muestra el texto y confirma antes de publicar. Detecta el forge (GitHub→PR con `gh` · GitLab→MR con `glab`); `mr` es el mismo comando, más natural en GitLab. **La US la resuelve la branch** (la nombra `dai link-us`): si hay varias vivas y ninguna coincide, **pregunta** en vez de elegir por vos (sin TTY falla pidiendo `--us <ID>`), y una branch `chore/`/`docs/` sale **sin US** en lugar de heredar la de otro. **La descripción la escribís vos (o tu agente) con `--description`**: dai llena la US, los commits y los links, pero no inventa el propósito de un cambio — si "Descripción" o "Cambios realizados" quedarían con el molde del template, con `--yes` o sin TTY **no publica** y te dice qué falta |
+| `dai pr [--assignee u] [--base b] [--draft] [--yes] [--us ID] [--title t] [--description t\|--description-file f] [--changes t\|--changes-file f]` · alias **`dai mr`** | crea **o actualiza** TU PR/MR precargada: propone la branch base **según el tipo de rama** (`feature/`/`fix/` → `DAI_BRANCH_DEV` · `release/`/`hotfix/` → `DAI_BRANCH_PROD`; `--base` gana, y si no hay nada declarado cae a la rama default del remoto **avisando que adivina**), muestra el texto y confirma antes de publicar. Contra la rama de producción pide una **confirmación explícita** (escribir el nombre de la rama; con `--yes` hace falta `--to-prod`). Si la branch **ya tiene una PR/MR abierta**, actualiza su título y su descripción en lugar de fallar dejando el diff al día y el body viejo. Detecta el forge (GitHub→PR con `gh` · GitLab→MR con `glab`); `mr` es el mismo comando, más natural en GitLab. **La US la resuelve la branch** (la nombra `dai link-us`): si hay varias vivas y ninguna coincide, **pregunta** en vez de elegir por vos (sin TTY falla pidiendo `--us <ID>`), y una branch `chore/`/`docs/` sale **sin US** en lugar de heredar la de otro. **La descripción la escribís vos (o tu agente) con `--description`**: dai llena la US, los commits y los links, pero no inventa el propósito de un cambio — si "Descripción" o "Cambios realizados" quedarían con el molde del template, con `--yes` o sin TTY **no publica** y te dice qué falta |
 | `dai stamp` | estampa la cobertura inversa en el tracker (branch + commit-ancla) |
-| `dai done [--base main] [--force]` | cierra la US: vuelve a la base, `fetch --prune` + `pull`, y borra la branch local **si está mergeada** (chequeo estricto; `--force` la borra igual). Redes: no estar en la base, sin cambios sueltos, sin commits sin pushear |
+| `dai done [--base b] [--force]` | cierra la US: vuelve a la base (se resuelve igual que en `dai pr`), `fetch --prune` + `pull`, y borra la branch local **si está mergeada** (chequeo estricto; `--force` la borra igual). Redes: no estar en la base, sin cambios sueltos, sin commits sin pushear |
 | `dai archive [<change>] [--skip-specs]` | **funde los delta specs del change en las specs canónicas** (`openspec/specs/`) y lo archiva. Lo corre el **aprobador** de la PR (gate de aprobación, [ADR-0011](docs/adr/0011-archive-gate-de-aprobacion.md)); detecta el change activo o le pasás el nombre. Envuelve `openspec archive` |
 | `dai forge review <ref> --from <review.json>` `[--dry-run\|--yes]` | **review inline**: un resumen + un comentario anclado a cada `archivo:línea`, clasificado low/medium/high. **Valida cada posición contra el diff** (descarta lo que el modelo inventó) antes de postear; sin `--yes` muestra el preview y no postea nada. Modo desatendido: `--min-severity`/`--min-confidence`/`--max-comments`. El review sale con `event: COMMENT`, nunca `APPROVE` ([ADR-0016](docs/adr/0016-review-inline.md)) |
 | `dai forge comment <ref> --body-file <f>` · `dai forge pr <ref>` | comentar / leer una PR/MR (GitHub/GitLab) — el fallback simple, sin anclar |
 | `dai ac-hash <us.md>` | calcula el hash de los criterios de aceptación de una US |
+| `dai release plan` · `cut <X.Y.Z>` · `done <X.Y.Z>` · `stamp <X.Y.Z> --env <amb>` · `status` · `notify --test` | **el ciclo de versión** ([ADR-0019](docs/adr/0019-ciclo-de-version-y-aviso-de-release.md)). `plan` arma el **manifiesto**: qué US entran, cuáles quedaron **atrasadas** y qué se coló **sin US** — más el bump que **propone** (la versión la firma una persona: un cambio de default es minor aunque todo sea `fix:`). `cut` prepara (rama, número, entrada del CHANGELOG con el material para repartir, commit) y **no habla hacia afuera**; `done` cierra tras el merge (tag + release note + back-merge + aviso) — los dos pasos que más se olvidan. `stamp` le avisa a **cada US** en qué versión y ambiente salió: muestra el alcance real, es **idempotente** por (app, versión, ambiente) y **es opcional** (decir que no sale con 0). El tag es la versión; `VERSION`/`package.json` son espejos y puede no haber ninguno. Guía: [releases](docs/guias/releases.md) · Tutorial: [ciclo de release](docs/tutoriales/ciclo-de-release.md) |
+| `dai help [<comando>]` · `dai <comando> --help` | ayuda del CLI. Pedir ayuda **nunca ejecuta el comando**: sale por `stdout` y termina con 0. Valen `--help`, `-h` y `dai <comando> help` — las tres formas, en todos los comandos |
 | `dai doctor` · `dai docs <dest>` · `dai version` | diagnóstico del entorno (incluye **version-drift** del scaffold) · copiar la doc (sin los assets del sitio; los links a las capturas apuntan al sitio publicado) · versión (`dai version` avisa si tu repo quedó atrás) |
 
 > **🆕 Mantené tu repo al día — `dai sync`.** Las skills, la constitución y los templates son un
@@ -242,7 +244,7 @@ flowchart TD
 > en [`skills/`](skills/).
 
 Skills (se invocan en el asistente): `/doc-to-backlog` · `/grill-intent` · `/grill-epic` · `/grill-user-story` · `/link-us` ·
-`/tdd` · `/dai-review`. Config del tracker (`md`\|`jira`\|`clickup`) y tokens: en `.env.dai`
+`/tdd` · `/dai-review` · `/dai-release`. Config del tracker (`md`\|`jira`\|`clickup`) y tokens: en `.env.dai`
 (no versionado; el `.env` del equipo no se toca — [ADR-0017](docs/adr/0017-env-dai.md)) —
 ver [`.env.dai.example`](.env.dai.example). Auth (SSH + tokens): [ADR-0007](docs/adr/0007-modelo-de-autenticacion.md).
 
@@ -278,7 +280,7 @@ mi-repo/
 ├── CLAUDE.md                       · Constitución del proyecto (auto-cargada por Claude)
 ├── .env.dai                        · tu tracker (NO versionado, completa el token) + .env.dai.example (plantilla, sí versionada)
 ├── .claude/skills/                 · Las skills, locales al repo (el equipo las hereda)
-│   └── doc-to-backlog · grill-intent · grill-epic · grill-user-story · link-us · tdd · dai-review
+│   └── doc-to-backlog · grill-intent · grill-epic · grill-user-story · link-us · tdd · dai-review · dai-release
 ├── .github/
 │   ├── copilot-instructions.md     · La constitución, auto-inyectada en cada chat de Copilot
 │   ├── skills/                     · Las mismas skills, en formato Copilot nativo (SKILL.md)

package/VERSION

@@ -1 +1 @@
-0.13.3
+0.15.0