@dforce2055/dai 0.9.0 → 0.10.0

package/cli/lib/pm-clickup.mjs

@@ -22,7 +22,7 @@ export function clickupTaskToText(json) {
 }
 
 export function clickupAdapter(env) {
-  if (!env.DAI_CLICKUP_TOKEN) throw new Error("falta DAI_CLICKUP_TOKEN en el .env (backend clickup).");
+  if (!env.DAI_CLICKUP_TOKEN) throw new Error("falta DAI_CLICKUP_TOKEN en el .env.dai (backend clickup).");
   return {
     kind: "clickup",
     async fetchUS(id) {
@@ -43,7 +43,7 @@ export function clickupAdapter(env) {
     },
     async createUS({ title, descriptionMarkdown }) {
       const list = env.DAI_CLICKUP_LIST_ID;
-      if (!list) throw new Error("falta DAI_CLICKUP_LIST_ID en el .env (la lista donde crear la tarea).");
+      if (!list) throw new Error("falta DAI_CLICKUP_LIST_ID en el .env.dai (la lista donde crear la tarea).");
       const res = await fetch(`${API}/list/${encodeURIComponent(list)}/task`, {
         method: "POST", headers: clickupAuthHeaders(env),
         body: JSON.stringify({ name: title, markdown_content: descriptionMarkdown }),

package/cli/lib/pm-jira.mjs

@@ -15,7 +15,7 @@ const trim = (b) => String(b || "").replace(/\/+$/, "");
 // error de config más común: `dai init` deja DAI_JIRA_PROJECT vacío y quien lo completa
 // suele pegar la épica que tiene a mano. Jira responde un 400 que no lo explica.
 export function assertProjectKey(key) {
-  if (!key) throw new Error("falta DAI_JIRA_PROJECT en el .env (la clave del proyecto donde crear el issue).");
+  if (!key) throw new Error("falta DAI_JIRA_PROJECT en el .env.dai (la clave del proyecto donde crear el issue).");
   const k = String(key).trim();
   const m = k.match(/^([A-Za-z][A-Za-z0-9_]*)-\d+$/);
   if (m) {
@@ -136,7 +136,7 @@ export function createHint(status, body = "") {
 
 export function jiraAdapter(env) {
   const base = env.DAI_JIRA_BASE_URL;
-  if (!base) throw new Error("falta DAI_JIRA_BASE_URL en el .env (backend jira).");
+  if (!base) throw new Error("falta DAI_JIRA_BASE_URL en el .env.dai (backend jira).");
   return {
     kind: "jira",
     async fetchUS(id) {

package/cli/lib/skills-source.mjs

@@ -15,6 +15,14 @@ export function parseSource(src) {
   const hash = raw.lastIndexOf("#");
   if (hash > 0) { ref = raw.slice(hash + 1) || null; loc = raw.slice(0, hash); }
 
+  // Paquete npm: `npm:@scope/pkg[@version]`. dai hace `npm pack` a un temp, respetando el
+  // `.npmrc` del repo (así resuelve registries privados con scope). La versión va en el
+  // propio spec (`@1.2.3`), no como ref con '#'.
+  if (loc.startsWith("npm:")) {
+    const spec = loc.slice(4).trim();
+    if (!spec) throw new Error("fuente npm vacía (usá npm:@scope/paquete)");
+    return { type: "npm", location: spec, ref: null };
+  }
   // Path local explícito (./ ../ / ~/).
   if (/^(\.\.?\/|\/|~\/)/.test(loc)) return { type: "path", location: loc, ref };
   // git por sintaxis de URL (https, ssh, scp git@host:…).

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,21 +243,26 @@ $ 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.
+
+🔵 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): de acuerdo con el DomainError. Aprobado tras el ajuste.
+👤 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.
 
 ---
 
@@ -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
 

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
 
@@ -122,8 +122,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 +136,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 +180,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 +205,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 +233,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
@@ -48,9 +46,9 @@ dai check                        # ⚠️ ATRASADO (exit 1)  → sugiere: dai li
 dai stamp                        # con md, deja .dai/us/<slug>.coverage.md
 ```
 
-Si esto anda, el flujo está bien. Pasa al tracker real.
+Con esto ya viste el ciclo entero. Ahora conéctalo a tu tracker real.
 
-## Fase 1 — ClickUp real
+## Paso 2 — contra tu tracker real (ClickUp)
 
 **Preparar ClickUp:**
 
@@ -62,7 +60,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
@@ -79,7 +77,8 @@ dai check                        # ⚠️ ATRASADO (lo detectó solo)
 dai stamp                        # deja un COMENTARIO en la tarea con la cobertura
 ```
 
-> 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
 

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. |
+| **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-intent`, `grill-user-story`, `formato-us.md` |
+| **Herramienta** | `grill-user-story`, `grill-intent`, `formato-us.md` |
 | **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.

package/docs/adr/README.md

@@ -22,6 +22,7 @@ decisión cambia, se escribe un ADR nuevo que supersede al viejo. Molde en
 | [0014](0014-copilot-agent-skills.md) | Copilot lee `SKILL.md` nativo (Agent Skills): se elimina el adaptador `.prompt.md` — modifica la 0002 | aceptado |
 | [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 |
 
 > 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

@@ -7,17 +7,18 @@
 El PO llega con una idea (a veces un ticket de una línea). Antes de escribir specs,
 la IA hace dos cosas, en orden:
 
-1. **Gate 0** (`grill-intent`) — desafía el *problema*, no la solución. Veredicto:
-   `a-spec` (seguir), `reframe` (el problema real es otro) o `descartar` (no vale la
-   pena ahora). Un "no lo construyas" es un éxito del gate, no una falla.
-2. **Pulido** (`grill-user-story`) — interroga hasta que la US es **testeable por
+1. **Pulido** (`grill-user-story`) — interroga hasta que la US es **testeable por
    construcción** (INVEST + Gherkin) y la publica en el tracker.
+2. **Gate 0** (`grill-intent`) — con la US ya formada, desafía el *problema* detrás
+   (no la solución). Veredicto: `a-spec` (seguir), `reframe` (el problema real es otro)
+   o `descartar` (no vale la pena ahora). Un "no lo construyas" es un éxito del gate,
+   no una falla.
 
 ## Herramientas
 
-- `/grill-intent` → `openspec/intents/<fecha-slug>/intent.md`
 - `/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`
 - Gate de entrada: [`definition-of-ready.md`](../../templates/definition-of-ready.md).
 
 ## Qué firma el humano

package/docs/detalle/03-ramas.md

@@ -4,7 +4,7 @@
 
 ## En qué consiste en detalle
 
-El dev arranca la implementación **atándola al QUÉ**: la branch y el `implements.yaml`
+El dev empieza la implementación **atándola al QUÉ**: la branch y el `implements.yaml`
 salen del mismo ID del tracker, así el link no puede quedar mal tipeado.
 
 ## Herramientas
@@ -21,7 +21,7 @@ dai link-us ABC-482 --us us.md
 
 ## Qué firma el humano
 
-El dev **elige qué US agarra**. El resto es mecánico y determinista (el CLI), no
+El dev **elige qué US toma**. El resto es mecánico y determinista (el CLI), no
 criterio humano — por eso el key **no se tipea a mano** ([Art. 8](../MANIFIESTO.md#art-8), Art. 9).
 
 ## Antipatrones