@dforce2055/dai 0.10.0 → 0.11.0

package/docs/adr/0018-alcance-de-stamp-y-gate-de-ci.md

@@ -0,0 +1,183 @@
+# ADR-0018 — El alcance de `stamp` lo decide la rama, el gate de CI se ejecuta, y editar el QUÉ es un comando
+
+- **Estado:** aceptado
+- **Fecha:** 2026-07-22
+- **Decide:** lead / arquitecto de la metodología
+
+## Contexto
+
+Tres agujeros con la misma raíz: **dai suponía cosas sobre el QUÉ que nunca escribió en
+ningún lado** — que un repo tiene una sola US viva, que toda rama implementa una US, y que
+la US, una vez publicada, no se vuelve a tocar. Las tres suposiciones fallan en el primer
+sprint real.
+
+### 1. `dai stamp` estampaba todo el repo
+
+`cmdStamp` recorría el repo entero con `discoverImplements(cwd)` —**archivados
+incluidos**— y le dejaba un comentario de cobertura a cada US que encontrara. Cerrar una
+historia dejaba esto en el tracker:
+
+```
+➜  backend git:(feature/331qtr-historia-motor) dai stamp
+✓ 86acme482 → task 86acme482 (comentario)  (✅ al día)
+✓ 86acme483 → task 86acme483 (comentario)  (✅ al día)
+✓ 86acme484 → task 86acme484 (comentario)  (✅ al día)
+✓ 86acme485 → task 86acme485 (comentario)  (✅ al día)
+```
+
+Tres de esos cuatro comentarios son ruido en el ticket de otra persona. Y un comentario
+en un tracker **no se deshace**: queda en el historial de la US, en la notificación por
+mail de quien la sigue, y en el Slack del canal conectado.
+
+Lo llamativo es que `dai check` **ya** filtraba los archivados (`includeArchived: false`,
+ADR-0010) y `stamp` no. La divergencia era un descuido, no una decisión.
+
+### 2. `governance/ci-rules.md` prometía un gate que no existía
+
+El documento decía, en una tabla, que el CI **bloquea** el PR si una rama de producto no
+tiene `implements.yaml`. No había ningún comando que hiciera eso. No estaba en `ci.yml`,
+no estaba en el CLI, no estaba en ningún template. Era una regla escrita que nadie
+aplicaba — el peor estado posible: el equipo cree que está protegido y no lo está.
+
+Y al ir a implementarla apareció el problema real, el que probablemente explica por qué
+nunca se implementó: **la regla como estaba escrita es demasiado dura**. Un `chore/` de
+bump de dependencias, un `docs/` de typo, un `hotfix/` de las tres de la mañana no
+tienen US, no deberían tenerla, y un gate que los bloquea se desactiva la primera semana.
+Un gate desactivado protege exactamente igual que un gate que no existe, pero además
+enseña al equipo que los checks de dai son un obstáculo.
+
+### 3. Editar una US publicada era copiar y pegar
+
+`dai publish` creaba la US y `dai check` detectaba que había cambiado. En el medio no
+había nada: para **editarla** el PO abría el navegador y escribía en un textarea sin
+validación, o el dev editaba el `us.md` local y el tracker quedaba viejo. El formato
+canónico (`templates/formato-us.md`) existía como documento y no como chequeo, así que una
+US podía volver al tracker sin criterios y nadie se enteraba hasta que `dai link-us`
+fallaba, sprints después.
+
+## Decisión
+
+### 1. El alcance de `stamp` sale del nombre de la rama, y ante la duda se pregunta
+
+`dai stamp` deja de recorrer el repo. La decisión vive en un módulo puro
+(`cli/lib/branch-scope.mjs`) que responde **qué estampar y por qué**:
+
+| Situación | Qué hace |
+|---|---|
+| `dai stamp ABC-482` | esas US, aunque el change esté archivado |
+| `dai stamp --all` | todo (el comportamiento viejo, ahora explícito) |
+| la rama nombra una US del repo | **solo esa** |
+| hay una sola US viva | esa |
+| varias US vivas y la rama no dice cuál | **no estampa: pregunta** |
+
+Los changes archivados **salen del default**. Se alcanzan con `--all` o nombrando el ID
+—que es justo el caso de estampar después del merge.
+
+> **El default es preguntar, no estampar de más.** Es la asimetría del costo: no estampar
+> se arregla corriendo el comando otra vez; estampar de más deja cuatro comentarios que
+> no se borran. Cuando no hay TTY (CI), en vez de preguntar **falla** y pide el ID
+> explícito — que es lo que un pipeline debería estar pasando de todos modos.
+
+El matcheo rama↔US es deliberadamente conservador: `feature/331qtr-historia-motor` **no**
+matchea `86acme482` aunque ambos sean alfanuméricos. Se comparan candidatos del nombre
+contra los IDs que el repo realmente declara, y si no hay coincidencia exacta se pregunta.
+
+Para el gate —que no tiene contra qué comparar, justamente porque el `implements.yaml` no
+existe— un key de tracker se reconoce por **MAYÚSCULAS + guion + números** (`ABC-482`). El
+case es lo único que lo separa de una palabra del slug con un número pegado: dogfoodeando
+esto, la rama `feat/issues-22-26` hacía que el gate sugiriera `dai link-us issues-22`, o
+sea mandar al dev a crear un link inventado. `dai link-us` preserva el case del key, y los
+keys de tracker son mayúsculas por convención en Jira, GitLab y Azure Boards.
+
+### 2. El gate es un comando, y sabe qué ramas no exigir
+
+```bash
+dai check --ci     # 0 = pasa · 1 = falta el link · 2 = el QUÉ cambió
+```
+
+Lee el nombre de la rama y aplica `branch-naming.md`:
+
+- `feature/`, `feat/` → **siempre** exige `implements.yaml`
+- `chore/`, `docs/`, `ci/`, `build/`, `test/`, `refactor/`, `style/`, `release/`,
+  `hotfix/`, `revert/` → **exentas**
+- `fix/` y cualquier otro prefijo → exige **solo si el nombre trae un ID** de tracker
+- sin prefijo (`main`, `develop`) → no es rama de trabajo
+
+> El nombre de la rama **es** la declaración del tipo de trabajo. Si el gate te bloquea
+> un chore, la respuesta no es inventarle una US: es renombrar la rama. Esto convierte
+> `branch-naming.md` de convención sugerida en algo con consecuencia, sin agregar
+> ceremonia nueva.
+
+En CI, la rama de una PR no se saca de git: `HEAD` es un merge commit detached. El
+comando lee `GITHUB_HEAD_REF` / `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME` / equivalentes.
+
+### 3. El gate no bloquea por falta de red ni de credencial
+
+`--no-network` valida el link y no compara contra la US viva; es el **default del
+template** (`templates/ci-dai-gate.yml`). Con los secrets del tracker cargados se saca el
+flag y el gate detecta además las US atrasadas.
+
+Mismo criterio dentro del modo completo: si el tracker no responde, **avisa y no
+bloquea**. Un gate que se pone rojo porque venció un token enseña al equipo a mirar para
+otro lado, y ahí perdimos los dos checks — el de red y el que sí importaba.
+
+### 4. Editar el QUÉ es un comando, y el `spec_version` lo decide la persona
+
+El tercer agujero del mismo origen: **la US vivía en el tracker y no había forma de
+editarla sin copiar y pegar.** El PO abría el navegador, escribía en un textarea sin
+validación, y el `.md` del repo quedaba viejo — o al revés. Dos comandos, un camino:
+
+```bash
+dai edit-us <ID>     # la baja del tracker → $EDITOR → valida → preview → guarda   (PO)
+dai update-us <ID>   # ya tenés el .md escrito (lo refinaste implementando) → guarda  (dev)
+```
+
+No son dos implementaciones: `edit-us` termina llamando al mismo tramo que `update-us`
+(`pushUS`), así que las dos puertas dan **el mismo preview y la misma confirmación**. La
+única diferencia es de dónde sale el markdown.
+
+**La validación bloquea tres cosas y avisa del resto.** Frenan: sin título, sin sección
+de criterios, sección vacía. Nada más — y no por permisividad: son exactamente las tres
+sin las cuales no hay `ac_hash`, y sin `ac_hash` no hay link QUÉ↔CÓMO. Que un criterio no
+sea Gherkin completo, o que el título tenga doce palabras, son **avisos**: dai opina en su
+dominio (la trazabilidad) y sugiere en el resto. `--strict` sube los avisos a errores para
+quien quiera esa política; no es el default, porque un gate que rechaza US legítimas se
+esquiva editando en el navegador y volvemos al punto de partida.
+
+Un formato inválido **no tira lo escrito**: te devuelve al editor con los errores a la
+vista, tantas veces como haga falta, y salir sin guardar deja tu `.md` intacto.
+
+**El `spec_version` se propone, no se impone.** Si el `ac_hash` se movió, dai pregunta:
+
+| El PO responde | Qué significa | Qué pasa |
+|---|---|---|
+| `s` | cambio **material** | `v1` → `v2`; los repos con `v1` se marcan atrasados |
+| `n` | cambio **editorial** | se queda en `v1`; nadie se marca atrasado |
+
+Es la línea que ya estaba escrita en [METODOLOGIA §4](../METODOLOGIA.md) —*el número
+comunica, el hash detecta*— llevada a una pregunta concreta. La máquina sabe **que** algo
+cambió; solo la persona sabe **si importa**. Automatizarlo en cualquiera de las dos
+direcciones rompe algo: subirlo siempre infla la versión con cada typo y entrena al equipo
+a ignorar los ⚠️; no subirlo nunca deja el número mintiendo. `--bump` / `--no-bump` cubren
+el caso no interactivo.
+
+## Consecuencias
+
+- `dai stamp` sin argumentos **cambia de comportamiento**: antes estampaba todo, ahora
+  estampa una. Es un cambio incompatible en el papel, pero el comportamiento viejo era el
+  bug; quien lo quiera tiene `--all`. Va en una **minor** por eso.
+- En CI hay que pasar el ID (`dai stamp ABC-482`). `governance/ci-rules.md` lo dice.
+- `branch-naming.md` pasa a tener consecuencia mecánica. Un repo con otras convenciones de
+  prefijo va a ver ramas "exentas" que él considera de producto — el escape es nombrar la
+  rama con el ID, que es lo que `dai link-us` hace solo.
+- El gate no valida tests ni lint: eso ya lo hace el CI del repo y dai no se mete
+  (ver `dai` como herramienta, no como mandato).
+- Los adaptadores de PM ahora devuelven `raw` (el markdown completo de la US) además del
+  parseo. Es lo que `edit-us` abre; antes solo teníamos título + hash, que alcanza para
+  detectar drift pero no para editar.
+- `dai edit-us` le da al **PO** un comando de terminal, cuando hasta ahora su superficie
+  eran skills en el asistente y el tracker. Es opcional —seguir editando en el navegador
+  funciona igual— pero es el único camino donde el formato se valida ANTES de guardar.
+- La validación de formato vive en el CLI (`us-format.mjs`), no en la skill. Es lo
+  mecánico y verificable; el criterio de si un criterio es *bueno* sigue en
+  `/grill-user-story`, que interroga (ADR-0002).

package/docs/adr/README.md

@@ -23,6 +23,7 @@ decisión cambia, se escribe un ADR nuevo que supersede al viejo. Molde en
 | [0015](0015-jira-corporativo.md) | `dai publish` en Jira corporativo: campos propios declarados, `--parent`/`--issuetype`, TLS con CA (nunca apagar la verificación) | aceptado |
 | [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 |
 
 > Estas son las decisiones que cierran las "Decisiones abiertas" de
 > [`METODOLOGIA.md §7`](../METODOLOGIA.md) y las enmiendas al

package/docs/detalle/01-refinamiento.md

@@ -14,11 +14,25 @@ la IA hace dos cosas, en orden:
    o `descartar` (no vale la pena ahora). Un "no lo construyas" es un éxito del gate,
    no una falla.
 
+## Cuando la US ya existe y hay que editarla
+
+El refinamiento no termina cuando la US entra al sprint: aparece un criterio que faltaba,
+o una regla que nadie había dicho. `dai edit-us <ID>` cierra ese ciclo sin copiar y pegar:
+baja la US del tracker, la abre en el editor del PO, **valida el formato** (título +
+criterios + Gherkin completo), muestra qué cambia, pregunta si el cambio es **material**
+(sube `spec_version`, los repos atrasados se marcan solos) o **editorial** (no sube nada),
+y recién con la confirmación escribe.
+
+Si el que refina es el **dev** —un criterio que aparece escribiendo el test— es el mismo
+camino por la otra puerta: `dai update-us <ID>` empuja el `us.md` del change, con el mismo
+preview y la misma confirmación ([ADR-0018](../adr/0018-alcance-de-stamp-y-gate-de-ci.md)).
+
 ## Herramientas
 
 - `/grill-user-story` → US en formato [`formato-us.md`](../../templates/formato-us.md),
   publicada en Jira/ClickUp (o `.md` de fallback).
 - `/grill-intent` → `openspec/intents/<fecha-slug>/intent.md`
+- `dai edit-us <ID>` → trae la US del tracker, la editas, dai valida el formato y la devuelve.
 - Gate de entrada: [`definition-of-ready.md`](../../templates/definition-of-ready.md).
 
 ## Qué firma el humano

package/docs/detalle/07-merge-trazabilidad.md

@@ -11,13 +11,22 @@ cobertura inversa** en el tracker: qué repo/change implementa la US, contra qu
 versión, con estado ✅/⚠️ y links (branch + commit-ancla).
 
 ```bash
-dai check   # ¿estoy atrasado respecto de la US?  (read-only, gate de PR)
-dai stamp   # escribe la cobertura en el tracker  (branch + commit)
+dai check          # ¿estoy atrasado respecto de la US?  (read-only)
+dai check --ci     # el mismo chequeo como GATE del PR: 0 pasa · 1 falta el link · 2 atrasado
+dai stamp          # escribe la cobertura en el tracker  (branch + commit)
 ```
 
+`dai stamp` sin argumentos deduce **qué US** estampar del nombre de tu rama, y si el repo
+tiene varias vivas y no puede saberlo, **pregunta** antes de escribir: un comentario en un
+tracker no se deshace. **En un pipeline pasá el ID** — `dai stamp ABC-482` — que además es
+lo único que un CI sabe con certeza ([ADR-0018](../adr/0018-alcance-de-stamp-y-gate-de-ci.md)).
+
 ## Herramientas
 
 - `dai check` / `dai stamp` — mismos comandos los corra un humano o el CI.
+- `dai check --ci` — el gate de [`ci-rules.md`](../../governance/ci-rules.md) ejecutable:
+  exige el link en las ramas de producto y deja pasar `chore/`, `docs/`, `release/`…
+  Workflow listo para copiar: [`templates/ci-dai-gate.yml`](../../templates/ci-dai-gate.yml).
 - Contenido del stamp: [ADR-0005](../adr/0005-superficie-comandos-y-stamp.md).
 
 ## Qué firma el humano
@@ -28,6 +37,8 @@ dai stamp   # escribe la cobertura en el tracker  (branch + commit)
 ## Antipatrones
 
 - **Actualizar el estado del ticket a mano** → desincronización garantizada.
+- **`dai stamp --all` en el CI** → le deja un comentario a cada US del repo, incluidas las
+  de sprints viejos. En un pipeline el ID va explícito.
 - **Escribir el link en los dos lados** → se desincroniza al primer cambio (Art. 9).
 - **Guardar solo la branch en el stamp** → 404 al borrarse; va con commit-ancla.
 - **Creer que hace falta "un CI en Jira"** → es un comando; el tracker no ejecuta nada.

package/docs/glosario.md

@@ -54,7 +54,7 @@
 
 | Término | Qué es |
 |---|---|
-| **CI (Integración Continua)** | La automatización que corre en cada *push* / PR: compila, corre los tests y valida el repo. **En dai**, el CI ejecuta `dai check` como *gate* del PR (valida que el link exista y que el `ac_hash` coincida con la US viva) y, al mergear, `dai stamp` (estampa la cobertura inversa en el tracker — nadie la escribe a mano). Qué valida, en [`governance/ci-rules.md`](../governance/ci-rules.md). |
+| **CI (Integración Continua)** | La automatización que corre en cada *push* / PR: compila, corre los tests y valida el repo. **En dai**, el CI ejecuta `dai check --ci` como *gate* del PR (valida que el link exista y que el `ac_hash` coincida con la US viva; las ramas `chore/`/`docs/` quedan exentas) y, al mergear, `dai stamp <ID>` (estampa la cobertura inversa en el tracker — nadie la escribe a mano). Qué valida, en [`governance/ci-rules.md`](../governance/ci-rules.md); workflow listo para copiar en [`templates/ci-dai-gate.yml`](../templates/ci-dai-gate.yml). |
 | **CD (Despliegue Continuo)** | La automatización que lleva la versión a los ambientes (`dev` / `test` / `pre` / `prod`) y reporta a cuál llegó. **En dai**, el CD alimenta la **matriz repo × ambiente**: *implementado ≠ desplegado* — el CI dice "el repo implementó `@v3`", el CD dice "`@v3` está viva en `pre`". |
 | **CI/CD** | Juntos, la "plomería" que **blinda** el método sin depender de que la gente se acuerde (enforcement, no vigilancia). En dai es **opcional** (ADR-0003): aparece sobre todo en **N3** (organización grande). En **N1/N2** los mismos comandos (`dai check`, `dai stamp`) corren a mano o por un git-hook — la trazabilidad es idéntica; solo cambia **quién** los dispara. dai **no trae** su propio CI/CD: se apoya en el pipeline que la organización ya tenga. |
 

package/docs/guias/dev.md

@@ -41,6 +41,9 @@
 8. **Verificas el DoD** → [`definition-of-done.md`](../../templates/definition-of-done.md) antes de mergear.
 9. **Merge → se estampa la cobertura** con `dai stamp` (lo corres tú tras mergear, o el CI
    si la org lo tiene automatizado — mismo comando, ADR-0003). El estado se **deriva** (Art. 10).
+   `dai stamp` deduce **qué US** estampar del nombre de tu rama; si el repo tiene varias
+   vivas y no puede saberlo, te pregunta antes de escribir en el tracker. En un pipeline
+   pasa el ID: `dai stamp ABC-482` ([ADR-0018](../adr/0018-alcance-de-stamp-y-gate-de-ci.md)).
 10. **(Opcional) Limpias la rama** → `dai done` te devuelve a la base (default `main`, o
    `--base develop`), hace `fetch --prune` + `pull` y borra la rama local **solo si está
    mergeada**. Higiene del repo tras el merge, sin riesgo de perder trabajo sin integrar.
@@ -57,6 +60,23 @@ Si el PO sube la US a `v2`, tu `implements.yaml` (que apunta a `v1`) se marca
 **atrasado** solo. Abres una nueva iteración contra `v2` y vuelves al paso 3. Nadie
 te avisa: el link versionado lo hace [Art. 11](../MANIFIESTO.md#art-11).
 
+### Cuando el que cambia el QUÉ eres tú
+
+Implementando aparece un criterio que la US no decía, y lo escribes en el `us.md` del
+change. Ahí el tracker queda viejo y tu `ac_hash` deja de coincidir con nada:
+
+```bash
+dai update-us ABC-482        # empuja tu us.md al tracker + re-estampa el ac_hash local
+```
+
+Te muestra qué va a cambiar allá arriba y **pide confirmación** antes de pisar la US
+(`--dry-run` para solo mirar, `--yes` para saltar la pregunta). Sin `--us` toma el `us.md`
+que está junto a tu `implements.yaml`.
+
+> Que un criterio nuevo pase por el tracker no es burocracia: es lo que hace que el
+> **PO se entere** de que la historia creció. Editar solo el `us.md` local deja el QUÉ
+> partido en dos versiones y ninguna es la buena.
+
 ## Tus herramientas
 
 - `/link-us`
@@ -66,4 +86,5 @@ te avisa: el link versionado lo hace [Art. 11](../MANIFIESTO.md#art-11).
 - `/tdd` — la disciplina TDD que aplica el paso anterior
 - `/dai-review`
 - `dai check` · `dai pr` · `dai stamp` · `dai done` (limpieza, opcional)
+- `dai update-us` — empuja al tracker una US que refinaste implementando
 - `definition-of-done.md`

package/docs/guias/po.md

@@ -31,7 +31,45 @@
    válido es *"no lo construyas"* — eso es el gate haciendo su trabajo (Art. 4).
 4. **Verificas el [DoR](../../templates/definition-of-ready.md)** → antes de que entre al sprint, la US cumple el
    [`definition-of-ready.md`](../../templates/definition-of-ready.md).
-5. **Demo** → aceptas o rechazas contra los mismos criterios que ya eran tests.
+5. **Editas una US que ya existe** → `dai edit-us ABC-482`. La **baja del gestor**, te la
+   abre en tu editor, **valida el formato** cuando guardas, te muestra qué cambia y
+   recién ahí la sube. Ver [Cuando el QUÉ cambia](#cuando-el-que-cambia) abajo.
+6. **Demo** → aceptas o rechazas contra los mismos criterios que ya eran tests.
+
+## Cuando el QUÉ cambia {#cuando-el-que-cambia}
+
+Un criterio que faltaba, una regla que aparece a mitad del sprint. La US **vive en el
+gestor**, no en un `.md` que alguien tiene que acordarse de sincronizar — así que dai la
+trae, te deja editarla y la devuelve:
+
+```bash
+dai edit-us ABC-482
+```
+
+1. **Baja** la US del gestor (Jira / ClickUp) a un `.md`.
+2. **La abre** en tu `$EDITOR`. Escribes en markdown, con el
+   [molde canónico](../../templates/formato-us.md) delante.
+3. **Valida el formato** al guardar: que tenga título, que tenga criterios, y que cada
+   criterio sea Gherkin completo (`Dado / Cuando / Entonces`). Si algo no da, **te
+   devuelve al editor** — no te tira lo escrito.
+4. **Te muestra qué cambia** allá arriba: título, cuántos criterios, el `ac_hash`.
+5. **Te pregunta si subir el `spec_version`** — y esta es la decisión tuya, no de dai:
+
+   | Tu cambio | Respondes | Qué pasa |
+   |---|---|---|
+   | Un criterio nuevo, una regla distinta (**material**) | `s` → `v1` → `v2` | los repos que implementaron `v1` se marcan **atrasados** solos |
+   | Un typo, redacción más clara (**editorial**) | `n` → se queda en `v1` | nadie se marca atrasado |
+
+   dai no puede distinguir las dos cosas mirando el hash: sabe *que* cambió, no *si
+   importa*. Eso lo sabes tú.
+6. **Confirmas** y recién ahí escribe en el gestor. Sin confirmación no se toca nada.
+
+> **`--dry-run`** te muestra todo el preview sin escribir. Úsalo la primera vez.
+
+Solo dos cosas te **frenan**: que la US no tenga título, o que no tenga criterios. Sin
+criterios no hay `ac_hash`, y sin `ac_hash` la US no se puede linkear a ningún repo — no
+es una regla de estilo, es lo que sostiene la trazabilidad. Todo lo demás (un criterio
+que no es Gherkin, un título largo) es un **aviso**: dai te lo dice y sigue.
 
 ## La trampa a evitar
 
@@ -52,5 +90,6 @@ el CI (Art. 10).
 - `/grill-epic` — algo grande → una épica partida en varias US
 - `/grill-user-story` — una US funcional y testeable
 - `/grill-intent` — Gate 0: desafía el problema de la US antes del spec
+- `dai edit-us <ID>` — traes una US del gestor, la editas, dai valida y la devuelve
 - el gestor de proyectos
 - [`definition-of-ready.md`](../../templates/definition-of-ready.md)

package/governance/ci-rules.md

@@ -12,15 +12,45 @@
 
 ## Qué valida el CI en cada PR/MR
 
-| Check | Regla | Si falla |
-|---|---|---|
-| **Link presente** | Toda rama de producto (`feature/ABC-###-*`) tiene `implements.yaml`. | ❌ bloquea el PR |
-| **ID válido** | El `id` matchea el formato del gestor (`ABC-\d+`) y el ID existe. | ❌ bloquea |
-| **`ac_hash` calculado** | El CI (re)calcula el hash de los criterios de la US y lo compara. | ⚠️ marca atrasado si no coincide |
-| **Tests verdes** | La suite de la US pasa. | ❌ bloquea |
-| **Estándares** | Lint + tipos + convenciones del repo. | ❌ bloquea |
+Las dos primeras filas **las ejecuta un comando**, no la buena voluntad:
 
-> Ramas `chore/`/`fix/` sin US no requieren `implements.yaml` (ver `branch-naming.md`).
+```bash
+dai check --ci        # salidas: 0 pasa · 1 falta el link · 2 el QUÉ cambió
+```
+
+Hay un workflow listo para copiar en [`templates/ci-dai-gate.yml`](../templates/ci-dai-gate.yml).
+Si tu CI no es GitHub Actions, el contrato es el mismo: un comando y su código de salida.
+
+| Check | Regla | Quién lo hace | Si falla |
+|---|---|---|---|
+| **Link presente** | Toda rama de producto (`feature/`) tiene `implements.yaml`. | `dai check --ci` | ❌ bloquea (exit 1) |
+| **`ac_hash` al día** | Recalcula el hash de los criterios de la US viva y lo compara. | `dai check --ci` | ❌ bloquea (exit 2) |
+| **ID resoluble** | El `id` del link existe en el gestor. | `dai check --ci` | ❌ bloquea (exit 2) |
+| **Tests verdes** | La suite de la US pasa. | el CI del repo | ❌ bloquea |
+| **Estándares** | Lint + tipos + convenciones del repo. | el CI del repo | ❌ bloquea |
+
+### Qué ramas quedan exentas
+
+Un gate que le exige US a todo se desactiva a la semana, y entonces no protege nada.
+Por eso `dai check --ci` decide **leyendo el nombre de la rama** (`branch-naming.md`):
+
+| Prefijo | ¿Exige `implements.yaml`? |
+|---|---|
+| `feature/`, `feat/` | **Sí, siempre** — es trabajo de producto |
+| `chore/`, `docs/`, `ci/`, `build/`, `test/`, `refactor/`, `style/`, `release/`, `hotfix/`, `revert/` | **No** — trabajo sin US |
+| `fix/` y cualquier otro prefijo | **Solo si el nombre trae un ID** (`fix/ABC-482-…`). Sin ID, no |
+| `main`, `develop` (sin prefijo) | No — no es una rama de trabajo |
+
+> Si tu PR es una corrección o un chore y el gate te lo bloquea, la respuesta **no** es
+> inventarle una US: es renombrar la rama con el prefijo que corresponde. El nombre de la
+> rama es la declaración de qué tipo de trabajo es.
+
+### Sin credenciales del tracker
+
+`dai check --ci --no-network` valida el link y **no** compara contra la US viva. Es el
+default del template: un gate que falla porque un token venció o porque el CI no tiene
+salida a internet enseña al equipo a ignorarlo. Con los secrets cargados, sacá el flag y
+el gate detecta además las US atrasadas.
 
 ## Qué hace el CI al mergear
 
@@ -28,6 +58,15 @@
 2. **Estampa la cobertura inversa** en el gestor: en el ticket `ABC-###`, deja
    "implementado por `<repo>` @ `<version>` (`ac_hash`) ✅". **Nadie lo escribe a
    mano** ([Art. 10](../docs/MANIFIESTO.md#art-10)).
+
+   ```bash
+   dai stamp ABC-482       # explícito: lo que corresponde en CI
+   dai stamp               # local: deduce la US de la rama; si hay varias, pregunta
+   ```
+
+   > En CI **pasá el ID**. `dai stamp` sin argumentos es para el dev en su máquina:
+   > deduce la US del nombre de la rama y, si no puede, pregunta en vez de estampar de
+   > más. Un comentario en el tracker no se deshace.
 3. **Actualiza el índice/router central** de la federación: la fila `ABC-### → { repos }`.
 
 ## Qué hace el CD al desplegar (solo N3 · organización grande)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforce2055/dai",
-  "version": "0.10.0",
+  "version": "0.11.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-review/SKILL.md

@@ -30,7 +30,7 @@ falló. El CLI lo caza antes.
 ### Cómo postear (elige la primera disponible)
 
 1. **`dai forge review <ref> --from <archivo> --yes`** — la forma. Review inline:
-   resumen + un comentario por línea. Usa `GITHUB_TOKEN`/`GITLAB_TOKEN` del `.env`.
+   resumen + un comentario por línea. Usa `GITHUB_TOKEN`/`GITLAB_TOKEN` de `.env.dai` o `.env`.
 2. **MCP del forge / `dai forge comment`** — fallback si no hay token, o si necesitas
    dejar un comentario suelto sin anclar. Pierdes el inline y la validación.
 

package/skills/grill-epic/SKILL.md

@@ -60,11 +60,11 @@ la forma. Nunca reescribas el formato inline.
 1. **Armar la épica** con el formato de `templates/epica.md`: metadata (`ID`, autor,
    estado, US que la componen) + objetivo + alcance (in/out) + lista de US + métricas +
    dependencias.
-2. **Publicar en el tracker.** **No asumas el tracker: lee `DAI_PM` del `.env` primero.**
+2. **Publicar en el tracker.** **No asumas el tracker: lee `DAI_PM` primero**, de `.env.dai` o `.env` (dai lee los dos; `.env.dai` gana clave por clave).
    Tres caminos, mismo contenido:
    - **Con MCP** (`jira` → MCP de Atlassian · `clickup` → MCP de ClickUp): crea el ticket
      de épica; las US hijas se crean como tickets vinculados (o quedan listadas).
-   - **Sin MCP, con token** (`DAI_PM=jira` + token en `.env`): escribe la épica como `.md`
+   - **Sin MCP, con token** (`DAI_PM=jira` + token en `.env.dai` o `.env`): escribe la épica como `.md`
      y publícala con **`dai publish <epica.md> --issuetype Epic`**. Devuelve el key. Si el
      proyecto exige campos propios, van con `--field alias=valor` (los declarados en
      `.dai/jira-fields.json`; `dai doctor` te los lista). Después, cada US hija se cuelga

package/skills/grill-intent/SKILL.md

@@ -36,7 +36,7 @@ Pull *up* from the story's "I want Y" to the problem underneath, and pressure-te
 1. **Read** the user story and the constitution.
 2. **Challenge, one axis at a time.** grill-me discipline: ask, listen, push, move on. Don't dump the five questions at once.
 3. **Reach a verdict** — `a-spec` (problem survived, go to propose), `reframe` (the real problem is different, back to `grill-user-story`), or `descartar` (not worth solving now, stop and record why).
-4. **Emit** the filled `intent.md` (default location `openspec/intents/<YYYYMMDD-slug>/intent.md`; adjust to where the manifesto puts intents). Embed the tracker ID (the issue/task key — Jira or ClickUp, per `DAI_PM` in the repo's `.env`) and the source story.
+4. **Emit** the filled `intent.md` (default location `openspec/intents/<YYYYMMDD-slug>/intent.md`; adjust to where the manifesto puts intents). Embed the tracker ID (the issue/task key — Jira or ClickUp, per `DAI_PM` in the repo's `.env.dai` or `.env` — dai reads both, `.env.dai` wins) and the source story.
 
 ## Hand-off
 

package/skills/grill-user-story/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: grill-user-story
-description: "Interroga a un PO o analista funcional para producir una User Story funcional y testeable siguiendo el formato del modelo de trazabilidad — o pule una US vaga existente. Se queda a nivel funcional/usuario y se niega a derivar en diseño técnico o a emitir una US con criterios no testeables. Al terminar, PUBLICA la US en el tracker configurado del repo (Jira o ClickUp, según DAI_PM del .env) usando su MCP; si no hay MCP/token, deja un .md con el mismo formato para copiar y pegar. Invocar como /grill-user-story, opcionalmente con un título, un ID/URL del tracker, y/o una US rústica existente. Usar antes de opsx:propose, o cuando alguien dice \"necesito una US\", \"convierte esto en una US como corresponde\", o \"esta historia está muy vaga\"."
+description: "Interroga a un PO o analista funcional para producir una User Story funcional y testeable siguiendo el formato del modelo de trazabilidad — o pule una US vaga existente. Se queda a nivel funcional/usuario y se niega a derivar en diseño técnico o a emitir una US con criterios no testeables. Al terminar la PUBLICA en el tracker configurado del repo (Jira o ClickUp, según DAI_PM de su .env.dai o .env): si la US es NUEVA la crea (MCP o `dai publish`); si YA tiene key la actualiza con `dai edit-us --no-editor`, que valida el formato y pregunta si sube el spec_version antes de pisar nada. Sin MCP ni token, deja un .md con el mismo formato para copiar y pegar. Invocar como /grill-user-story, opcionalmente con un título, un ID/URL del tracker, y/o una US rústica existente. Usar antes de opsx:propose, o cuando alguien dice \"necesito una US\", \"convierte esto en una US como corresponde\", o \"esta historia está muy vaga\"."
 ---
 
 # grill-user-story
@@ -31,15 +31,17 @@ Si no viene nada, pedir título y si hay un borrador existente.
 
 1. **Cortar en lo técnico.** Si la charla deriva a tablas, endpoints, migraciones o elección de framework, frenar: "eso es diseño, no ahora". La US nombra *qué necesita el usuario*, nunca *cómo se construye*.
 2. **Cortar en lo no testeable.** Nunca emitir un criterio que no pueda volverse un test. "El usuario tiene una buena experiencia" se rechaza. "Un carrito vacío no se puede finalizar" se acepta — funcional y verificable. Empujar cada AC hasta que sea observable.
-3. **Publicar, no pedir.** Si el tracker está configurado (`DAI_PM=jira|clickup` con token en `.env`), **CREA el ticket tú** (por MCP o con `dai publish`). **Nunca** cierres pidiéndole al usuario que te "pase el ID/URL del ticket" como si ya existiera — el ticket lo creas tú en este paso. Solo pides un ID existente si el usuario dijo explícitamente que está refinando una US ya creada.
+3. **Publicar, no pedir.** Si el tracker está configurado (`DAI_PM=jira|clickup` con token en `.env.dai` o `.env`), **dejá la US publicada tú**. **Nunca** cierres pidiéndole al usuario que te "pase el ID/URL del ticket" como si ya existiera, ni que copie y pegue el markdown al navegador. Dos caminos según si la US ya tiene key:
+   - **No tiene key → la CREÁS** (MCP o `dai publish`).
+   - **Ya tiene key → la ACTUALIZÁS con `dai edit-us <ID> --no-editor`**, nunca pisando el ticket a mano por MCP. El comando valida el formato antes de escribir, muestra qué cambia y pregunta si sube el `spec_version` — controles que por MCP no existen.
 
 ## Proceso
 
-0. **Detectar el tracker (SIEMPRE, antes de nada).** Lee el archivo `.env` del repo y observa `DAI_PM`:
+0. **Detectar el tracker (SIEMPRE, antes de nada).** Lee la config de dai del repo y observa `DAI_PM`. **Está en `.env.dai` o en el `.env` del equipo: mirá los dos.** dai carga ambos, y si una clave está en los dos gana `.env.dai` (ADR-0017). Un repo que tiene todo en `.env` funciona igual — no hace falta migrar nada:
    - `DAI_PM=jira` → publicas en **Jira** (base: `DAI_JIRA_BASE_URL`), vía el MCP de Atlassian/Jira.
    - `DAI_PM=clickup` → publicas en **ClickUp**, vía el MCP de ClickUp.
-   - `DAI_PM=md` (o sin `.env`) → no hay tracker: dejas la US como `.md`.
-   **No asumas el tracker** — depende del `.env`. Si no hay `.env`, pregunta cuál usa el equipo.
+   - `DAI_PM=md` (o sin config) → no hay tracker: dejas la US como `.md`.
+   **No asumas el tracker** — depende de la config. Si no hay `.env.dai` ni `.env`, pregunta cuál usa el equipo.
 1. **Resolver inputs.** Obtener título e ID del tracker (si existe). Si se refina, leer la US y anotar — para uno mismo — qué secciones del formato faltan o están flojas: rol genérico ("el usuario"), falta el "para", sin flujo de excepción, solución prefijada, ACs vagos.
 2. **Grillar, un eje por vez.** No tirar un cuestionario — preguntar, escuchar, profundizar, y seguir. Cubrir en orden:
    - **Título** — corto, **3 a 6 palabras**, nombra la capacidad (de ahí sale la branch). Si el título es una frase larga, acórtalo: el detalle va en la descripción, no en el título. Ej: "Confirmar acciones con consecuencias", no "Confirmación deliberada antes de ejecutar acciones con consecuencias".
@@ -49,11 +51,18 @@ Si no viene nada, pedir título y si hay un borrador existente.
    - **Criterios de aceptación** — convertir cada flujo en una condición funcional y testeable, en Gherkin. Aplicar el corte #2 acá, fuerte.
    - **Fuera de scope** — qué NO hace esta historia (mata el scope creep más adelante).
 3. **Chequeo de tamaño (INVEST).** Si los flujos y ACs desbordan y la historia se dispersa, es demasiado grande para una sola US. No seguir empujando: **promoverla a una épica** con `/grill-epic` (que la parte en varias US independientes) y después volver acá para grillar cada US hija. Una US que no entra en un sprint es la señal de que hay una épica adentro.
-4. **Publicar la US en el tracker (PASO OBLIGATORIO, ver abajo).** No termines con "¿la guardo y/o disparo el siguiente paso?": el trabajo de esta skill **incluye dejar la US publicada** en el tracker (con su key), no solo redactarla.
+4. **Dejar la US en el tracker (PASO OBLIGATORIO, ver abajo).** No termines con "¿la guardo y/o disparo el siguiente paso?": el trabajo de esta skill **incluye dejar la US publicada** en el tracker (con su key), no solo redactarla. Si la US ya existía, actualizarla cuenta como publicarla.
 
-## Salida — publicar en el tracker (según `DAI_PM`), con fallback a .md
+## Salida — dejar la US en el tracker (según `DAI_PM`), con fallback a .md
 
-La US se produce UNA vez con el formato de `../../templates/formato-us.md`. Lo que cambia es **dónde se publica** — lo definió el paso 0:
+La US se produce UNA vez con el formato de `../../templates/formato-us.md`. Lo que cambia es **dónde va** y **si se crea o se actualiza**.
+
+> **Primero: ¿la US ya tiene key?**
+> - **No** (nació en esta sesión) → **CREAR** — pasos 1–4 de abajo.
+> - **Sí** (el usuario trajo `ABC-482`, o vos la creaste antes en esta misma charla) →
+>   **ACTUALIZAR** — saltá a *"Si la US ya existe"*.
+
+### Si la US es nueva (crear)
 
 1. **Armar la US** completa: metadata de trazabilidad (`ID`, `spec_version: v1`, autor, repos esperados) + historia + contexto + casos de uso + criterios Gherkin + fuera de scope + reglas + dependencias + métricas.
 2. **Publicar en el tracker que dice `DAI_PM`:**
@@ -62,10 +71,10 @@ La US se produce UNA vez con el formato de `../../templates/formato-us.md`. Lo q
    - Confirmar al usuario con el link al ticket publicado.
    - **Importante:** los criterios SIEMPRE van bajo `## Criterios de aceptación` en la descripción — así `dai link-us`/`check` los encuentran, sin importar el tracker.
 3. **Fallback SIN MCP → publicar con el CLI (`dai publish`):**
-   - Si NO hay MCP del tracker conectado (pero sí `DAI_PM=jira|clickup` + token en `.env`):
+   - Si NO hay MCP del tracker conectado (pero sí `DAI_PM=jira|clickup` + token en `.env.dai` o `.env`):
      escribe la US como `.md` (formato `formato-us.md`) y publícala con el comando:
      **`dai publish <ruta-del-md>`** → crea el issue/tarea vía REST y devuelve el key.
-     (Jira necesita además `DAI_JIRA_PROJECT` en el `.env` — la clave del **proyecto**,
+     (Jira necesita además `DAI_JIRA_PROJECT` — la clave del **proyecto**,
      `PROJ`, no la de un ticket.)
    - **Si la US pertenece a una épica:** `dai publish <us.md> --parent <KEY-de-la-épica>`.
    - **Si el proyecto exige campos propios** (típico en Jira corporativo): van con
@@ -82,6 +91,45 @@ La US se produce UNA vez con el formato de `../../templates/formato-us.md`. Lo q
    atajo publica igual, pero el `## Criterios de aceptación` puede quedar mal formado y
    **el link QUÉ↔CÓMO se rompe en silencio**. Si el error nombra un campo obligatorio que
    falta, decláralo en `.dai/jira-fields.json` (molde en `.dai/templates/`) y reintenta.
+### Si la US ya existe (refinar) — `dai edit-us`
+
+Cuando la US **ya tiene key**, el trabajo no es crearla sino **pisarla con la versión
+refinada**. Eso NO se hace por MCP ni editando el ticket en el navegador: se hace con
+
+```bash
+dai edit-us <ID> --us <ruta-del-md> --no-editor
+```
+
+Escribí la US refinada al `.md` y pasáselo. `--no-editor` es lo que hace que el comando
+sirva desde una skill: no abre `$EDITOR` (vos ya editaste), pero **conserva todo lo demás**.
+
+Qué te da ese camino, que por MCP no existe:
+
+1. **Valida el formato antes de escribir.** Frena si falta el `# Título`, la sección
+   `## Criterios de aceptación`, o si está vacía — las tres cosas sin las cuales no hay
+   `ac_hash` y el link QUÉ↔CÓMO se rompe. Y **avisa** si un criterio no es Gherkin
+   completo o se metió en el CÓMO. Si frena, **arreglá el `.md` y reintentá**: no busques
+   otra vía para publicar igual, el chequeo está para eso.
+2. **Muestra qué cambia** en el tracker (título, cuántos criterios, `ac_hash`) antes de
+   tocarlo.
+3. **Pregunta si sube el `spec_version`** — y esta pregunta **es de la persona, no tuya**:
+   - **material** (un criterio nuevo, una regla distinta) → sube `v1` → `v2`, y los repos
+     que implementaron `v1` se marcan **atrasados** solos.
+   - **editorial** (typo, redacción más clara) → se queda en `v1`, nadie se marca atrasado.
+
+   Con `--yes` el comando asume material y sube la versión. **No pongas `--yes` sin
+   preguntar**: marcar repos como atrasados de más entrena al equipo a ignorar los ⚠️.
+   Preguntale al PO cuál de las dos es, y recién entonces corré con `--bump` o `--no-bump`.
+4. **Re-estampa el `ac_hash`** del `implements.yaml` si el repo ya implementaba esa US,
+   para que `dai check` no la marque atrasada por la propia edición.
+
+Usá **`--dry-run` primero** para mostrarle el preview a la persona, y corré en firme
+recién cuando lo apruebe. Si el backend es `md` (sin tracker), el mismo comando actualiza
+el `.md` canónico.
+
+> Si preferís no traer nada del tracker porque ya tenés la US entera escrita,
+> `dai update-us <ID> --us <md>` es el mismo camino sin el paso de bajarla.
+
 5. **Estado.** Dejar la US en `pulida`. Ofrecer que el dev siga con `dai link-us <ID>` → `opsx:propose` (lado técnico).
 
 ## Hand-off