@dforce2055/dai 0.10.0 → 0.12.0

package/docs/PROBAR.md

@@ -41,11 +41,18 @@ dai link-us finalizar-la-compra-del-carrito   # branch + implements.yaml
 git add -A && git commit -m "feat: guard carrito vacío"
 dai check                        # ✅ al día
 
-# 4. La demo del ⚠️: edita el criterio en .dai/us/<slug>.md y vuelve a chequear
+# 4. La demo del ⚠️: cambia el QUÉ y mira cómo se detecta solo
+dai edit-us finalizar-la-compra-del-carrito   # la trae, la abres, valida, pregunta si sube spec_version
 dai check                        # ⚠️ ATRASADO (exit 1)  → sugiere: dai link-us <id> --resync
+
+# 5. Estampa la cobertura
 dai stamp                        # con md, deja .dai/us/<slug>.coverage.md
 ```
 
+> En el paso 4, `dai edit-us` abre tu `$EDITOR`. Si no tienes uno configurado te pide
+> editar el archivo y volver, así que también funciona con el archivo abierto en tu IDE.
+> Agrega un criterio, guarda, y responde `s` a "¿subo spec_version?" para ver el ⚠️.
+
 Con esto ya viste el ciclo entero. Ahora conéctalo a tu tracker real.
 
 ## Paso 2 — contra tu tracker real (ClickUp)
@@ -75,6 +82,9 @@ dai check                        # ✅ al día
 # → edita un criterio de la tarea en ClickUp (en el navegador). Después:
 dai check                        # ⚠️ ATRASADO (lo detectó solo)
 dai stamp                        # deja un COMENTARIO en la tarea con la cobertura
+
+# ¿Editar la US sin salir de la terminal? La trae, la abres, valida y la devuelve:
+dai edit-us 86cxyz --dry-run     # el preview completo, sin escribir en ClickUp
 ```
 
 > El `.env.dai` **no se versiona**: el token no se commitea, y el `.env` del equipo no se
@@ -86,6 +96,7 @@ dai stamp                        # deja un COMENTARIO en la tarea con la cobertu
 |---|---|
 | `no encontré la US <id>` | ID mal, o el token no ve esa tarea |
 | `clickup 401` | token inválido o expirado |
+| `edit-us` dice que la US no tiene el formato mínimo | le falta el `# Título` o la sección `## Criterios de aceptación`. Sin criterios no hay `ac_hash` y no hay link |
 | `check` siempre da ⚠️ | editaste la US entre `link-us` y `check` (esperado), **o** los criterios no están bajo el heading `Criterios de aceptación` |
 | `sin US` en `check` | la tarea no tiene el bloque de criterios en la descripción |
 | branch/commit vacíos en el stamp | falta el remoto git (`git remote add origin …`) |

package/docs/SCRUM-CON-IA.md

@@ -50,8 +50,8 @@
 | **Clásico** | El PO parte épicas en Historias de Usuario y les pone criterios de aceptación. |
 | **Dolor** | US vagas, no testeables ("el usuario quiere un botón"). El malentendido se descubre tarde, ya implementado. |
 | **Con IA** | `grill-user-story` **interroga** al PO hasta que la US es testeable por construcción (INVEST + Gherkin); y después el Gate 0 de `grill-intent` desafía el *problema* detrás (veredicto: a-spec / reframe / descartar). La IA no *escribe* la US: la *saca a preguntas*. La US nace con ID estable y criterios hasheables. |
-| **Humano (HITL)** | El PO responde y decide. La IA no inventa requerimientos: los pule. |
-| **Herramienta** | `grill-user-story`, `grill-intent`, `formato-us.md` |
+| **Humano (HITL)** | El PO responde y decide. La IA no inventa requerimientos: los pule. Si la US ya existe y hay que retocarla, `dai edit-us <ID>` la baja del tracker, valida el formato al guardar y **pregunta** si el cambio es material (sube `spec_version`) o editorial. |
+| **Herramienta** | `grill-user-story`, `grill-intent`, `formato-us.md`, `dai edit-us` |
 | **Detalle →** | [`detalle/01-refinamiento.md`](detalle/01-refinamiento.md) |
 
 #### 2. Sprint Planning: comprometer US y derivar tareas

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/docs/tutoriales/index.md

@@ -2,6 +2,15 @@
 
 Guías de **setup operativo** — lo que haces una vez por máquina para trabajar con dai.
 
+## De cero a publicar
+
+- [**Setup para analistas funcionales y PMs (Windows)**](./setup-funcional) — el camino
+  completo sin git ni repositorio: Node, dai, las skills en Copilot, el token de Jira y una
+  épica + US de prueba publicadas de verdad.
+- [**Setup para desarrolladores (Windows)**](./setup-dev) — el otro lado: Node, dai, git + SSH
+  + `glab`, las skills en Copilot, OpenSpec y el ciclo completo sobre una US real
+  (`link-us` → `check` → `mr` → `stamp`).
+
 ## Preparar el entorno
 
 - [**Configurar git**](./configurar-git) — tu identidad (nombre + correo) para que los