@dforce2055/dai 0.9.0 → 0.11.0

package/docs/EJEMPLO-END-TO-END.md

@@ -12,10 +12,10 @@
 
 | Paso | Skill / evento | Artefacto que produce |
 |---|---|---|
-| 1 Refinamiento | `grill-intent` → `grill-user-story` | `intent.md` + la **US** (`ABC-482`) |
+| 1 Refinamiento | `grill-user-story` → `grill-intent` (Gate 0) | la **US** (`ABC-482`) + `intent.md` |
 | 2 Planning | `opsx:propose` | `proposal.md` + `design.md` + `tasks.md` + `specs/` |
 | 3 Rama | `link-us` | branch + `implements.yaml` |
-| 4 TDD | `tdd` | test (RED) → código (GREEN) |
+| 4 Implementación | `opsx:apply` (con TDD) | test (RED) → código (GREEN), por el agente |
 | 5 Smoke | skill de smoke | escenario end-to-end verde |
 | 6 Code review | review propio del dev → `dai pr` → partner (con `/dai-review`) | PR (código + spec) + aprobación |
 | 7 Merge | `dai stamp` | cobertura estampada en el tracker |
@@ -37,34 +37,9 @@ ABC-482 · "Arreglar lo del carrito que a veces deja comprar de más"
 
 Impresentable para implementar. Acá entra la IA.
 
-### 1b · Gate 0 — `grill-intent` desafía el problema
+### 1b · `grill-user-story` produce la US
 
-La skill no acepta el ticket: interroga el *problema* detrás (contra el
-[`MANIFIESTO.md`](MANIFIESTO.md)).
-
-```
-IA:  ¿Qué duele HOY, concretamente? "Comprar de más" es un síntoma.
-PO:  Un cliente finalizó la compra de un producto que ya no tenía stock, y quedó
-     una orden que no podemos cumplir. También pasa que finalizan con el carrito
-     vacío y se genera una orden fantasma.
-IA:  ¿Quién siente el dolor? "El sistema" no es un usuario.
-PO:  El comprador (recibe un error después de comprar) y depósito, que recibe
-     órdenes que no puede despachar.
-IA:  ¿Y si no lo hacemos? (costo de no actuar)
-PO:  Órdenes que se cancelan a mano, clientes enojados. Pasó bastante el último mes.
-IA:  La solución implícita es "validar el carrito al finalizar". ¿Es el salto correcto,
-     o el problema real es que el stock que muestra el carrito no es confiable?
-PO:  No, validar al finalizar es lo correcto: el stock ya existe, falta chequearlo
-     en el momento de la compra.
-
-Veredicto: a-spec  ✅  (problema real, usuario concreto, costo claro, sin solution-lock)
-```
-
-→ produce `openspec/intents/20260703-checkout-invalido/intent.md` con ese veredicto.
-
-### 1c · `grill-user-story` produce la US
-
-Con el problema validado, la skill interroga hasta que la US es **testeable por
+Acá entra la IA: `grill-user-story` interroga al PO hasta que la US es **testeable por
 construcción** ([`formato-us.md`](../templates/formato-us.md)) y la publica en el gestor:
 
 ```markdown
@@ -113,6 +88,33 @@ para **recibir los productos que elijo sin sorpresas**.
 > Nota que la US **no dice** tablas, endpoints ni framework — solo el QUÉ. Y cada
 > AC es un test en potencia ([Art. 3](./MANIFIESTO.md#art-3) del manifiesto).
 
+### 1c · Gate 0 — `grill-intent` desafía el problema
+
+Con la US ya formada, **antes** de invertir en el spec, el Gate 0 cuestiona el *problema*
+detrás (contra el [`MANIFIESTO.md`](MANIFIESTO.md)):
+
+```
+IA:  ¿Qué duele HOY, concretamente? "Comprar de más" es un síntoma.
+PO:  Un cliente finalizó la compra de un producto que ya no tenía stock, y quedó
+     una orden que no podemos cumplir. También pasa que finalizan con el carrito
+     vacío y se genera una orden fantasma.
+IA:  ¿Quién siente el dolor? "El sistema" no es un usuario.
+PO:  El comprador (recibe un error después de comprar) y depósito, que recibe
+     órdenes que no puede despachar.
+IA:  ¿Y si no lo hacemos? (costo de no actuar)
+PO:  Órdenes que se cancelan a mano, clientes enojados. Pasó bastante el último mes.
+IA:  La solución implícita es "validar el carrito al finalizar". ¿Es el salto correcto,
+     o el problema real es que el stock que muestra el carrito no es confiable?
+PO:  No, validar al finalizar es lo correcto: el stock ya existe, falta chequearlo
+     en el momento de la compra.
+
+Veredicto: a-spec  ✅  (problema real, usuario concreto, costo claro, sin solution-lock)
+```
+
+→ produce `openspec/intents/20260703-checkout-invalido/intent.md` con ese veredicto. Si
+hubiera dado *reframe* o *don't build*, la US volvería al PO **antes** de gastar un solo
+artefacto de spec — ese es el punto del Gate 0.
+
 ---
 
 ## Paso 2 — Planning: `opsx:propose` deriva el CÓMO
@@ -175,9 +177,10 @@ autor: D. Force (dev)
 
 ---
 
-## Paso 4 — TDD: un test a la vez (RED → GREEN)
+## Paso 4 — Implementación: el agente construye con TDD (`/opsx:apply`)
 
-Vertical slice del AC-2 (el guard del carrito vacío). **Primero el test (RED):**
+`/opsx:apply` implementa las tareas del change, un test a la vez. Vertical slice del AC-2
+(el guard del carrito vacío). **Primero el test (RED):**
 
 ```typescript
 test("un carrito vacío no se puede finalizar", async () => {
@@ -205,8 +208,9 @@ export async function finalizarCompra(id: CarritoId) {
 // ▶ VERDE. Repetir el ciclo para AC-1 y AC-3.
 ```
 
-> El test verifica por la **interfaz pública** (`finalizarCompra`, `ordenesDe`), no
-> espía lo interno. Sobrevive a un refactor (Art. 7 + skill `tdd`).
+> El test (que escribió el agente) verifica por la **interfaz pública**
+> (`finalizarCompra`, `ordenesDe`), no espía lo interno. Sobrevive a un refactor
+> (Art. 7 + skill `tdd`). El dev revisa cada slice: es responsable del código.
 
 ---
 
@@ -239,29 +243,34 @@ $ dai pr --assignee mgomez
 ✓ PR #123 creada → …/pull/123   (base: main · US: ABC-482 @ v1 · dai check ✅)
 ```
 
-El **partner** revisa la PR. Se apoya en la skill `/dai-review` para un primer pase con
-comentario estándar, y **firma** aprobación o rechazo:
+El **partner** revisa la PR. Se apoya en la skill `/dai-review` para un primer pase: deja
+un **review inline** (resumen + un comentario anclado por línea, low/medium/high). La skill
+le muestra el preview y **espera su OK antes de postear**; después el partner **firma**
+aprobación o rechazo:
 
 ```
-🤖 /dai-review (primer pase, ayuda al partner)
-  · AC-2 cubierto y verificado (no se crea orden con carrito vacío). ✓
-  · Sugerencia: CarritoVacioError y SinStockError deberían extender un DomainError
-    común, como el resto del módulo.
-  · Sin problemas de correctitud.
+🤖 /dai-review — resumen
+  US: ABC-482 @ v1 · dai check: ✅ al día · DoD: 5/5
+  1 comentario en línea: 1 🔵 Low.
 
-👤 M. Gómez (partner): de acuerdo con el DomainError. Aprobado tras el ajuste.
+🔵 Low — src/checkout/errors.ts:12
+  CarritoVacioError y SinStockError podrían extender un DomainError común,
+  como el resto del módulo.
+
+👤 M. Gómez (partner): reviso el preview, lo posteo, y apruebo tras el ajuste.
 ```
 
 > El dev revisa su propio código; un partner distinto revisa la PR y **firma** (Art. 5).
-> La skill `/dai-review` le saca el ruido al partner, pero la aprobación la firma la persona.
+> El review sale con el nombre y el token del partner (nunca `APPROVE` automático): la
+> skill asiste, la persona firma.
 
 ---
 
 ## Paso 7 — Merge: la trazabilidad se estampa sola
 
 Al mergear, se corre `dai stamp` (el dev, o el CI si está automatizado — ADR-0003).
-Lee el `implements.yaml` y **estampa la cobertura inversa** en el ticket `ABC-482`,
-con links a la implementación:
+Deduce que la US de esta rama es `ABC-482`, lee el `implements.yaml` y **estampa la
+cobertura inversa** en el ticket, con links a la implementación:
 
 ```
 ABC-482 · implementado por  (lo estampó dai stamp)
@@ -282,7 +291,7 @@ ABC-482 · implementado por  (lo estampó dai stamp)
 ## Paso 8 — Daily *(humano, a propósito)*
 
 > *"Ayer cerré ABC-482, la validación del checkout con el guard de carrito. Hoy
-> agarro ABC-490. Sin trabas."* — La IA no genera esto; el equipo se sincroniza (Art. 6).
+> tomo ABC-490. Sin trabas."* — La IA no genera esto; el equipo se sincroniza (Art. 6).
 
 ## Paso 9 — Review / Demo
 
@@ -303,7 +312,30 @@ AC-3 verdes → **US aceptada**. Cero sorpresas: si el QUÉ hubiera cambiado, el
 
 Dos sprints después, el PO agrega un criterio a `ABC-482` (ahora exige **avisar al
 comprador qué productos quedaron sin stock, sin cancelar el resto del carrito**).
-Sube la US a **v2** → cambia el `ac_hash`.
+
+Lo hace con `dai edit-us ABC-482`: la baja del tracker, la abre en su editor, valida el
+formato cuando guarda, y le pregunta si el cambio es material o editorial.
+
+```
+  ── formato de la US (.dai/us/ABC-482.md) ────────────
+  ✓ formato válido — 4 criterio(s), 4 en Gherkin completo
+
+  Cambiaron los criterios (ac_hash 7f3a9c2e → b81d40f5).
+    s = cambio material: subo spec_version a v2 y los repos con v1 se marcan ATRASADOS
+    n = cambio editorial (typo, redacción): se queda en v1
+  ¿Subo spec_version a v2? (S/n) s
+
+  ── ABC-482 · qué cambia en jira ────────────
+  título:     Finalizar la compra del carrito  (sin cambios)
+  criterios:  4
+  version:    v1 → v2
+  ac_hash:    7f3a9c2e → b81d40f5
+  ──────────────────────────────────────
+  Esto PISA la US ABC-482 en jira. ¿Guardo? (s/N) s
+✓ ABC-482 actualizada en jira  →  https://acme.atlassian.net/browse/ABC-482
+```
+
+La US sube a **v2** → cambia el `ac_hash`.
 
 ```
 ABC-482 · implementado por

package/docs/MANIFIESTO.md

@@ -3,7 +3,7 @@
 > **Qué es esto.** La *constitución* de la metodología: los principios inmutables
 > contra los que se mide toda decisión. Cuando `grill-intent` desafía un problema,
 > lo hace contra estos artículos. Cuando dudas si algo "va con el método", la
-> respuesta está acá. Es corto a propósito — un manifiesto que no se puede citar de
+> respuesta está aquí. Es corto a propósito — un manifiesto que no se puede citar de
 > memoria no gobierna nada.
 >
 > **Cómo se usa.** Es el input de constitución que las skills asumen (junto con
@@ -56,7 +56,7 @@ El *daily* y la *retro* se hacen a mano, a propósito. Son donde el equipo se
 apropia del proceso y lo entiende. La IA puede darles datos; no los reemplaza.
 
 <a id="art-7"></a>**Art. 7 — No vibe coding.**
-No se improvisa código sobre una idea vaga. Toda implementación arranca de una US
+No se improvisa código sobre una idea vaga. Toda implementación parte de una US
 bien definida, pasa por un design, y se construye con tests. La disciplina no es
 opcional: es lo que separa este método de "pedirle cosas a un chat".
 

package/docs/METODOLOGIA.md

@@ -2,7 +2,7 @@
 
 > **Fuente de verdad única.** Este documento es el maestro. Los dos HTML
 > (`desarrollo-asistido-por-ia.html` federado y `-equipos-compactos.html`) son
-> **vistas de presentación** derivadas de acá — si algo contradice a este `.md`,
+> **vistas de presentación** derivadas de aquí — si algo contradice a este `.md`,
 > gana este `.md`. Versionado por git para que no driftee.
 
 Una sola metodología para dos escalas opuestas:
@@ -57,9 +57,9 @@ identidad el día que se crea el ticket/change.
 ### 2.2 Formato linkeable garantizado
 
 El QUÉ se produce con una forma mínima **testeable**: `id · spec_version · autor ·
-criterios de aceptación en Gherkin`. Es exactamente lo que aseguran las skills
-`grill-intent` → `grill-user-story` (ver `formato-us.md`). Sin esa forma, no hay
-a qué linkear.
+criterios de aceptación en Gherkin`. Es exactamente lo que asegura la skill
+`grill-user-story` (y después el Gate 0 de `grill-intent` desafía el problema; ver
+`formato-us.md`). Sin esa forma, no hay a qué linkear.
 
 ### 2.3 El link se autora una sola vez, del lado del CÓMO
 
@@ -83,6 +83,11 @@ cambio.
 - **`ac_hash`** lo calcula la máquina para **detectar**. Es el hash del bloque de
   *Criterios de aceptación* normalizado (whitespace colapsado, orden estable).
 
+> El reparto no es decorativo: la máquina sabe **que** algo cambió, la persona sabe **si
+> importa**. Un typo corregido mueve el hash igual que un criterio nuevo, y solo un humano
+> distingue el uno del otro. Por eso `dai edit-us` / `dai update-us` **proponen** subir el
+> `spec_version` cuando el hash se mueve, y esperan un sí o un no — nunca lo deciden solos.
+
 Cuando el QUÉ evoluciona, cambia el `ac_hash`; todos los CÓMO que declaran el hash
 viejo quedan marcados **atrasados** solos. El funcional ve "el backend todavía no
 tomó mi cambio"; el dev ve "el QUÉ que implementé cambió". Nadie avisa a nadie — el
@@ -122,8 +127,10 @@ federación.**
 
 El CÓMO se construye con **test primero**, en *vertical slices* (un test → una
 implementación → repetir), verificando por la **interfaz pública**, no espiando lo
-interno. Un buen test lee como una spec y sobrevive a un refactor. Ver
-`skills/tdd/`.
+interno. Un buen test lee como una spec y sobrevive a un refactor. **Quien lo ejecuta
+es el agente**, dentro de `/opsx:apply` (la disciplina la encapsula la skill `tdd`); el
+dev decide qué comportamientos importa testear y es responsable de revisar el resultado
+([Art. 7](MANIFIESTO.md#art-7)). Ver `skills/tdd/`.
 
 ---
 
@@ -134,7 +141,7 @@ duele, no antes.**
 
 | | **N1 · Solo / 1 repo** | **N2 · Equipo compacto** | **N3 · Federado** |
 |---|---|---|---|
-| Caso típico | equipo chico arrancando, un dev | equipo chico | organización grande |
+| Caso típico | equipo chico empezando, un dev | equipo chico | organización grande |
 | El QUÉ vive en | `proposal.md` de OpenSpec | ClickUp (US) → el change la referencia | Jira (`ABC-###`, hub) |
 | El link vive en | la carpeta del change (co-localizado) | `implements.yaml` en el repo | `implements.yaml` versionado |
 | Inversa la genera | un comando local | comando / CI liviano | CI estampa cobertura + CD reporta ambiente |
@@ -178,13 +185,13 @@ El artefacto no desaparece; se aligera la ceremonia alrededor.
 
 ```
    ①  Nace la idea            → ticket vago en el PM (o intención suelta en N1)
-   ②  Gate 0: ¿problema OK?   → /grill-intent  → veredicto: a-spec / reframe / descartar
-   ③  Se pule el QUÉ          → /grill-user-story → US testeable (formato-us.md),
+   ②  Se pule el QUÉ          → /grill-user-story → US testeable (formato-us.md),
                                  publicada en Jira/ClickUp (o .md si no hay MCP)
+   ③  Gate 0: ¿problema OK?   → /grill-intent  → veredicto: a-spec / reframe / descartar
    ④  Se abre el CÓMO         → /link-us ABC-###  → branch + implements.yaml ligados al ID
    ⑤  Se arma el change       → opsx:explore → opsx:propose (proposal/design/tasks + specs)
-   ⑥  Se implementa           → TDD (red → green → refactor), vertical slices
-   ⑦  Se promueve             → opsx:apply → opsx:archive; el CI estampa cobertura en el PM
+   ⑥  Se implementa           → opsx:apply → el agente aplica las tareas con TDD (red→green→refactor)
+   ⑦  Se promueve             → opsx:archive; el CI estampa cobertura en el PM
    ⑧  Se despliega            → el CD reporta a qué ambiente (dev/test/pre/prod) fue la versión
 ```
 
@@ -203,11 +210,14 @@ El artefacto no desaparece; se aligera la ceremonia alrededor.
 
 | Skill | Lado | Qué hace |
 |---|---|---|
-| `grill-intent` | QUÉ | Gate 0: desafía el *problema* antes de escribir spec. Veredicto: a-spec / reframe / descartar. |
+| `doc-to-backlog` | QUÉ | Un documento (PDF/Word) → backlog candidato de épicas + US para priorizar. |
+| `grill-epic` | QUÉ | Algo grande → una épica partida en varias US. |
 | `grill-user-story` | QUÉ | Interroga hasta producir una US testeable (INVEST + Gherkin). Publica en Jira/ClickUp o deja `.md`. |
+| `grill-intent` | QUÉ | Gate 0: con la US ya formada, desafía el *problema* antes de escribir spec. Veredicto: a-spec / reframe / descartar. |
 | `link-us` | CÓMO | Crea branch + `implements.yaml` desde el ID del PM. El link, correcto por construcción. |
-| `tdd` | CÓMO | Red-green-refactor en vertical slices, tests por interfaz pública. |
-| `opsx:*` | CÓMO | OpenSpec: explore → propose → apply → archive. Lo provee OpenSpec. |
+| `opsx:*` | CÓMO | OpenSpec: explore → propose → apply (el agente implementa con TDD) → archive. Lo provee OpenSpec. |
+| `tdd` | CÓMO | La disciplina red-green-refactor (vertical slices, tests por interfaz pública) que aplica `opsx:apply`. |
+| `dai-review` | CÓMO | Review inline de una PR/MR ajena: resumen + un comentario por línea, con gate humano de OK antes de postear. |
 
 El **adaptador de PM** es un seam único: las skills del QUÉ publican en Jira **o**
 ClickUp **o** dejan un `.md` según qué MCP/token haya. Es la **misma** skill con
@@ -228,7 +238,7 @@ de N3 queda **una** decisión sin resolver; el resto se cerró al construir la h
 
 **Ya resueltas** (al construir dai):
 - **Adaptador de PM configurable** → `getAdapter` (backends `md`/`jira`/`clickup`, token del
-  `.env`); modelo de auth en [ADR-0007](adr/0007-modelo-de-autenticacion.md).
+  `.env.dai` no versionado — [ADR-0017](adr/0017-env-dai.md)); modelo de auth en [ADR-0007](adr/0007-modelo-de-autenticacion.md).
 - **Formato de `implements.yaml`** → congelado en [ADR-0004](adr/0004-ubicacion-y-schema-implements.md)
   (schema + ubicación + descubrimiento por glob).
 - **Escritura multi-repo en el tracker** → `dai stamp` deja un **comentario por repo** (no se

package/docs/PROBAR.md

@@ -1,8 +1,8 @@
 # Probar dai
 
-No hace falta publicar en npm para probarlo. Se prueba local. Recomendado: hacer la
-**Fase 0** (backend `md`, sin credenciales) para validar el flujo, y después la
-**Fase 1** (ClickUp real).
+La forma más rápida de conocer dai: instala el CLI y corre el ciclo completo en tu
+máquina. Empieza **sin credenciales** (backend `md`) para ver el flujo entero en un par de
+minutos, y después pruébalo **contra tu tracker real** (ClickUp o Jira).
 
 > Esto es la guía para **usar** dai por primera vez. Para verlo funcionando sobre una
 > US real (narrado), mira [`EJEMPLO-END-TO-END.md`](EJEMPLO-END-TO-END.md).
@@ -10,19 +10,17 @@ No hace falta publicar en npm para probarlo. Se prueba local. Recomendado: hacer
 ## Instalar el CLI
 
 ```bash
-npm i -g @dforce2055/dai        # desde npm
-# — o, si clonaste el repo —
-git clone https://github.com/dforce2055/dai && cd dai && npm link
-
+npm i -g @dforce2055/dai
 dai --version
 ```
 
-## Fase 0 — sin credenciales (backend `md`)
+## Paso 1 — sin credenciales (backend `md`)
 
-Valida el loop completo `link-us → check → stamp` sin depender de red ni tokens.
+Recorre el loop completo `link-us → check → stamp` sin red ni tokens: todo local. Perfecto
+para ver cómo funciona antes de conectar nada.
 
 ```bash
-# 1. Repo de prueba + bootstrap (dai init deja el .env; elige "md" cuando pregunte)
+# 1. Repo de prueba + bootstrap (dai init deja el .env.dai; elige "md" cuando pregunte)
 mkdir /tmp/dai-test && cd /tmp/dai-test
 git init && git commit --allow-empty -m init
 git remote add origin git@github.com:TU-USUARIO/dai-test.git   # para los links de branch/commit
@@ -43,14 +41,21 @@ 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
 ```
 
-Si esto anda, el flujo está bien. Pasa al tracker real.
+> 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 ⚠️.
 
-## Fase 1 — ClickUp real
+Con esto ya viste el ciclo entero. Ahora conéctalo a tu tracker real.
+
+## Paso 2 — contra tu tracker real (ClickUp)
 
 **Preparar ClickUp:**
 
@@ -62,7 +67,7 @@ Si esto anda, el flujo está bien. Pasa al tracker real.
 **Config y flujo:**
 
 ```bash
-cat > .env <<'EOF'
+cat > .env.dai <<'EOF'
 DAI_PM=clickup
 DAI_CLICKUP_TOKEN=pk_XXXXXXXX
 EOF
@@ -77,9 +82,13 @@ 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` está gitignored: el token no se commitea (ADR-0007).
+> El `.env.dai` **no se versiona**: el token no se commitea, y el `.env` del equipo no se
+> toca ([ADR-0017](adr/0017-env-dai.md); modelo de auth en [ADR-0007](adr/0007-modelo-de-autenticacion.md)).
 
 ## Troubleshooting
 
@@ -87,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

@@ -49,9 +49,9 @@
 |---|---|
 | **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-intent` (Gate 0: ¿es el problema correcto? veredicto a-spec / reframe / descartar) y luego `grill-user-story` **interrogan** al PO hasta que la US es testeable por construcción (INVEST + Gherkin). 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-intent`, `grill-user-story`, `formato-us.md` |
+| **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. 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
@@ -76,19 +76,19 @@
 | **Clásico** | El dev crea una rama para trabajar la US. |
 | **Dolor** | Nombres inconsistentes, ramas que no se sabe a qué US pertenecen → trazabilidad rota desde el commit uno. |
 | **Con IA** | `link-us ABC-###` crea la rama **desde el ID de la US, sin tipearlo a mano**, y genera el `implements.yaml`. La rama *es* el link: correcto por construcción. |
-| **Humano (HITL)** | El dev elige qué US agarra. |
+| **Humano (HITL)** | El dev elige qué US toma. |
 | **Herramienta** | `link-us` |
 | **Detalle →** | [`detalle/03-ramas.md`](detalle/03-ramas.md) |
 
-#### 4. Implementación con TDD
+#### 4. Implementación (`/opsx:apply`, con TDD)
 
 | | |
 |---|---|
 | **Clásico** | El dev codea. Idealmente con tests. |
 | **Dolor** | Se codea primero y se testea "si queda tiempo" (nunca queda). Vibe coding. |
-| **Con IA** | La skill `tdd` fuerza test→código en *vertical slices* (un test → una implementación → repetir). La IA escribe el test como spec ejecutable **antes** del código, verificando por la interfaz pública. Anti vibe-coding real. |
-| **Humano (HITL)** | El dev decide qué comportamientos importa testear y revisa cada slice. |
-| **Herramienta** | `tdd` |
+| **Con IA** | El **agente implementa** con `/opsx:apply`: aplica las tareas de `opsx:propose` en *vertical slices* (un test → el código mínimo → repetir), escribiendo el test como spec ejecutable **antes** del código y verificando por la interfaz pública (la disciplina TDD la encapsula la skill `tdd`). Anti vibe-coding real. |
+| **Humano (HITL)** | El dev decide qué comportamientos importa testear, valida cada slice y **es responsable del código** (no la IA) — lo revisa en el paso 6. |
+| **Herramienta** | `opsx:apply` (con la disciplina de `tdd`) |
 | **Detalle →** | [`detalle/04-tdd.md`](detalle/04-tdd.md) |
 
 #### 5. Smoke test de la US
@@ -108,9 +108,9 @@
 |---|---|
 | **Clásico** | Un compañero revisa el PR/MR antes de mergear. |
 | **Dolor** | Depende de que el partner tenga tiempo y ganas; reviews superficiales que dejan pasar lo importante. |
-| **Con IA** | La IA hace el **primer pase** (correctitud + estándares del repo) antes del humano. El partner revisa lo que importa, no el ruido. |
+| **Con IA** | La IA hace el **primer pase**: un **review inline** (corre `dai check` + valida el DoD, y deja un resumen + **un comentario por línea**, low/medium/high). Muestra el preview y **espera el OK del partner antes de postear**; el partner revisa lo que importa, no el ruido. |
 | **Humano (HITL)** | El partner aprueba o rechaza. La IA sugiere; la persona decide y firma. |
-| **Herramienta** | `dai-review` |
+| **Herramienta** | `dai-review` (`dai forge review`) |
 | **Detalle →** | [`detalle/06-code-review.md`](detalle/06-code-review.md) |
 
 #### 7. Merge + trazabilidad automática
@@ -170,7 +170,7 @@
 | 1 Refinamiento | ●●● | La US testeable es la base de todo. |
 | 2 Planning | ●● | El design y las tareas se derivan de la US. |
 | 3 Rama | ●●● | El link correcto por construcción. |
-| 4 TDD | ●●● | El corazón del anti vibe-coding. |
+| 4 Implementación | ●●● | El agente construye con TDD; el corazón del anti vibe-coding. |
 | 5 Smoke | ●● | Cierre verificable de la US. |
 | 6 Code review | ●● | Primer pase automático, humano decide. |
 | 7 Merge + trazabilidad | ●●● | La matriz se deriva sola. |

package/docs/adr/0003-deteccion-y-estampado-son-comandos.md

@@ -49,7 +49,7 @@ Pasar de distribuido a automático es mover la invocación, no reescribir nada.
 
 ## Consecuencias
 
-- ✅ **No hace falta ningún CI para empezar.** La metodología arranca con un dev
+- ✅ **No hace falta ningún CI para empezar.** La metodología empieza con un dev
   tipeando `dai check` / `dai stamp`. El [Art. 14](../MANIFIESTO.md#art-14) queda respetado.
 - ✅ **Rampa de adopción continua:** manual → git-hook → CI, siempre el mismo comando.
 - ✅ **Honra el [Art. 10](../MANIFIESTO.md#art-10):** el humano *dispara* la derivación; no *escribe a mano* el

package/docs/adr/0006-distribucion-y-licencia.md

@@ -20,7 +20,7 @@ más fuerte de eso es el **copyleft**: quien distribuya un `dai` modificado debe
 publicar sus cambios bajo la misma licencia. La GPL convierte "las mejoras vuelven"
 en cláusula, no en deseo.
 
-El downside típico de la GPL **no aplica** acá: `dai` es un **CLI que se ejecuta**,
+El downside típico de la GPL **no aplica** aquí: `dai` es un **CLI que se ejecuta**,
 no una librería que se embebe. Usar `dai` sobre tu código —aunque sea propietario y
 comercial— **no genera ninguna obligación**; el copyleft solo se activa si alguien
 **forkea y redistribuye** una versión modificada. Y *libre ≠ gratis*: se puede

package/docs/adr/0013-skills-externas-install-from.md

@@ -18,11 +18,17 @@ dueño ni gatekeeper de ellas.
 
 ## Decisión
 
-Agregamos **`dai skills install --from <git-url|path>[#ref]`**: instala skills
-**externas** desde un repo/dir (con estructura `skills/<nombre>/SKILL.md`, la misma
+Agregamos **`dai skills install --from <git-url|npm:pkg|path>[#ref]`**: instala skills
+**externas** desde un repo/dir/paquete (con estructura `skills/<nombre>/SKILL.md`, la misma
 de dai), **convertidas para los 3 asistentes** (Claude copia · Cursor `skillToCursor`
 · Copilot `skillToPrompt` → `.github/prompts/`).
 
+- **Tres fuentes:** un **git URL** (`github.com/org/skills[#ref]` → clone), un **path
+  local**, o un **paquete npm** (`npm:@scope/pkg[@version]` → `npm pack` a un temp,
+  respetando el `.npmrc` del cwd, así resuelve registries privados con scope). Es común
+  distribuir skills como paquete npm (una org publica sus componentes + skills juntas);
+  materializarlo a mano era fricción de más.
+
 - **`dai skills` es el namespace canónico** de las operaciones de skills, consistente
   con `dai forge <verb>`. `dai skills install` (sin `--from`) instala las de dai;
   **`dai install` queda como alias** silencioso (backward-compatible).
@@ -42,8 +48,9 @@ de dai), **convertidas para los 3 asistentes** (Claude copia · Cursor `skillToC
 - **Se acepta pagar:** es **one-off** (dai no mantiene esas skills al día; re-corrés
   `--from`). **Sin registro** → dai no sabe qué repos tienen skills externas, a
   propósito: cero gatekeeping, bajo riesgo del equipo. Las fuentes remotas dependen de
-  git/red, y la **auth se delega en git** (público sin más; privado por SSH o credential
-  helper — dai no autentica): *si podés `git clone` la fuente, dai instala desde ahí*.
+  git/red/npm, y la **auth se delega en la herramienta** (git: SSH o credential helper;
+  npm: el `.npmrc` del repo — dai no autentica): *si puedes `git clone` o `npm pack` la
+  fuente, dai instala desde ahí*.
 
 ## Alternativas consideradas
 

package/docs/adr/0015-jira-corporativo.md

@@ -89,7 +89,7 @@ error de config más común. El mensaje da los dos caminos: `DAI_JIRA_PROJECT=PR
 - **`dai doctor`** valida la clave de proyecto y que el archivo de campos parsee. Sigue
   **sin** verificar que el token sirva — eso es red, y lo dice `dai publish`. El chequeo
   ahora lo admite en voz alta en vez de dar un ✓ engañoso.
-- **ClickUp queda con el mismo hueco de TLS.** `daiFetch` está listo para adoptarse allá
+- **ClickUp queda con el mismo hueco de TLS.** `daiFetch` está listo para adoptarse allí
   con un import; no lo hicimos ahora por alcance.
 
 ## Alternativas descartadas

package/docs/adr/0017-env-dai.md

@@ -0,0 +1,64 @@
+# ADR-0017 — La config de dai vive en `.env.dai`, no en el `.env` del equipo
+
+- **Estado:** aceptado
+- **Fecha:** 2026-07-18
+- **Decide:** lead / arquitecto de la metodología
+
+## Contexto
+
+dai guarda su config y sus secretos (token del tracker, email, plantilla de URL) en
+variables de entorno, y hasta ahora las escribía en el `.env` del repo, con la premisa de
+que ese `.env` está **gitignored** (por eso `dai init` lo agregaba al `.gitignore` y el
+loader avisaba "NUNCA commitees tokens").
+
+Esa premisa se rompe en muchas empresas: **versionan el `.env`** como política (mismas
+variables públicas para todo el equipo y el CI). Pasó de verdad en un repo de frontend
+corporativo: el `.env` estaba trackeado con `VITE_*` públicas, y `dai init`
+
+1. le **inyectaba** sus claves `DAI_*` a un archivo compartido del equipo, y
+2. le agregaba `.env` al `.gitignore` — inútil, porque git no ignora un archivo ya
+   trackeado, y encima confuso (parece que lo protege y no lo hace).
+
+El día que un dev completara `DAI_JIRA_TOKEN` en ese `.env` versionado, git lo marcaba
+para commit: **un secreto a un empujón de filtrarse** al historial del repo corporativo.
+
+## Decisión
+
+dai deja de tocar el `.env` del equipo. Toda su config vive en archivos **propios**:
+
+| Archivo | Versionado | Quién lo maneja | Contenido |
+|---|---|---|---|
+| `.env` | según el equipo | el equipo | dai **no lo escribe**; solo lo **lee** (compat) |
+| `.env.dai` | **no** (gitignored) | cada dev | config + secretos de dai (token, email) |
+| `.env.dai.example` | sí | dai / el equipo | plantilla: mismas claves, valores vacíos |
+
+- **`dai init`** crea `.env.dai` (real, ignorado) y `.env.dai.example` (plantilla
+  versionada), de forma aditiva, y **nunca** modifica `.env`/`.env.example`.
+- **`reconcileGitignore`** ignora `.env.dai` (su archivo), **no** `.env`: el `.env` del
+  equipo es del equipo, y muchas orgs lo versionan a propósito. `.env.dai.example` no
+  matchea el patrón exacto `.env.dai`, así que se versiona sin negación extra.
+- **El loader** (`loadDaiEnv`) lee `.env.dai` **y** `.env`. Precedencia:
+  **entorno (shell/CI) > `.env.dai` > `.env`**. Se logra cargando `.env.dai` primero,
+  porque el loader es "primero-gana". Seguir leyendo `.env` mantiene compatibilidad con
+  repos previos que tienen los `DAI_*` ahí — no se rompe nada.
+
+## Consecuencias
+
+- **A favor:** dai no ensucia ni pone en riesgo un archivo compartido del equipo. El
+  secreto vive en un archivo que git ignora de verdad (no trackeado). Funciona igual en
+  equipos que versionan el `.env` y en los que no. Los repos viejos siguen andando (se
+  lee `.env`).
+- **En contra:** una convención más de archivos (`.env.dai`, `.env.dai.example`) que
+  documentar. Un repo que ya tenía `DAI_*` en un `.env` gitignored puede migrarlos a
+  `.env.dai` cuando quiera; no es urgente, porque el loader sigue leyendo `.env`.
+- **Vite:** el nombre `.env.dai` solo lo cargaría Vite con `vite --mode dai` (raro), y
+  las claves de dai no llevan prefijo `VITE_`, así que nunca van al bundle del cliente.
+
+## Alternativas descartadas
+
+- **Destrackear el `.env`** (`git rm --cached`): rompe la convención del equipo y les saca
+  del control de versiones las `VITE_*` públicas que comparten a propósito.
+- **Secreto solo por variable de shell:** anda hoy (el loader no pisa el entorno), pero
+  obliga a `source` en cada sesión: fricción para todo el equipo, sin plantilla que guíe.
+- **Seguir usando `.env` y forzar el `.gitignore`:** es justo lo que fallaba — inerte
+  sobre un archivo ya trackeado, y peligroso el día que alguien escribe el token.