@dforce2055/dai 0.10.0 → 0.12.0

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

package/templates/ci-dai-gate.yml

@@ -0,0 +1,50 @@
+# Gate de trazabilidad de dai — la regla de governance/ci-rules.md, ejecutable.
+#
+# Qué hace: en cada PR, verifica que una branch de producto declare qué US implementa
+# (implements.yaml) y que ese link no haya quedado atrasado contra la US viva.
+#
+# Qué NO hace: exigirle US a todo. `chore/`, `docs/`, `ci/`, `build/`, `test/`,
+# `refactor/`, `style/`, `release/`, `hotfix/` y `revert/` pasan sin link — son trabajo
+# legítimo sin ticket (governance/branch-naming.md). Un gate que bloquea esas branches
+# se termina desactivando, y entonces no protege nada.
+#
+# Cómo se instala: copialo a .github/workflows/ de tu repo. Si tu CI no es GitHub
+# Actions, el contrato es el mismo en cualquier runner — es un solo comando:
+#
+#     npx --yes @dforce2055/dai check --ci
+#
+# Códigos de salida:  0 = pasa · 1 = falta el link · 2 = el QUÉ cambió (US atrasada)
+
+name: dai · trazabilidad
+
+on:
+  pull_request:
+
+jobs:
+  link:
+    name: link QUÉ↔CÓMO
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      # `dai check --ci` detecta solo la branch de la PR (GITHUB_HEAD_REF): en una PR,
+      # HEAD es un merge commit detached y `git rev-parse --abbrev-ref HEAD` diría "HEAD".
+      #
+      # Sin secrets del tracker, el gate valida el LINK y no compara contra la US viva
+      # (--no-network). Con secrets, sacá el flag y además detecta las US atrasadas.
+      - name: Gate de trazabilidad
+        run: npx --yes @dforce2055/dai check --ci --no-network
+
+      # Variante con tracker — descomentala y cargá los secrets del repo para que el
+      # gate marque también las US ATRASADAS (salida 2). Comentá el paso de arriba.
+      #
+      # - name: Gate de trazabilidad (con tracker)
+      #   env:
+      #     DAI_PM: jira                                  # o clickup
+      #     DAI_JIRA_BASE_URL: ${{ vars.DAI_JIRA_BASE_URL }}
+      #     DAI_JIRA_EMAIL: ${{ secrets.DAI_JIRA_EMAIL }}
+      #     DAI_JIRA_TOKEN: ${{ secrets.DAI_JIRA_TOKEN }}
+      #   run: npx --yes @dforce2055/dai check --ci