@dforce2055/dai 0.8.2 → 0.10.0

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/0016-review-inline.md

@@ -0,0 +1,128 @@
+# ADR-0016 — Review inline: el `review.json` como puerta humana, y el CLI como validador
+
+- **Estado:** aceptado
+- **Fecha:** 2026-07-17
+- **Decide:** lead / arquitecto de la metodología
+
+## Contexto
+
+`dai-review` dejaba **un comentario al final del hilo** de la PR con todos los hallazgos
+en una lista. El reviewer humano tenía que leer "`src/checkout.ts:42` — el guard falla
+abierto", abrir el archivo, buscar la línea, y reconstruir el contexto a mano. Por cada
+hallazgo.
+
+El review de Copilot, con todos sus defectos, hace algo mejor: deja **un comentario
+anclado a cada `archivo:línea`**, clasificado `Low`/`Medium`/`High`, más un resumen
+arriba. El hallazgo aparece **al lado del código del que habla**.
+
+Técnicamente el gap era chico y estaba en un solo lugar: `dai forge comment` postea al
+endpoint de **issues** (el hilo). El review inline es otro endpoint. No hacía falta una
+arquitectura nueva.
+
+Pero al abrirlo aparecieron tres problemas que sí son de diseño:
+
+1. **El modelo inventa líneas.** Un LLM revisando código produce `path:line` que no
+   existen en el diff con una facilidad pasmosa. El forge responde `422` sin decir cuál
+   de los seis comentarios falló, y en GitHub el review es atómico: **un hallazgo
+   inventado tira los cinco buenos**.
+2. **La skill posteaba sin gate** (ver 0.8.2). Con un comentario suelto ya era grave.
+   Con seis comentarios inline **firmados con el token del humano** —el forge los
+   atribuye a él como usuario, sin badge de bot— pesa mucho más.
+3. **"Desatendido" no puede significar "sin criterio".** Hacía falta una forma de que un
+   review simple salga solo sin que eso implique postear cualquier cosa.
+
+## Decisión
+
+### 1. El contrato es un archivo, y ese archivo es la puerta humana
+
+La skill deja de componer markdown y escribe un **`review.json`** en `.dai/reviews/<n>.json`.
+El CLI lo valida y lo postea.
+
+```
+skill (criterio)        →  .dai/reviews/22.json  →  dai forge review (mecánico)
+hallazgos + severidad      el humano lo edita        valida vs. diff, filtra, postea
+```
+
+Es la [ADR-0002](0002-agnostico-del-asistente.md) aplicada al review: el criterio es de
+la skill, lo determinista es del CLI.
+
+**Por qué un archivo y no una TUI.** Evaluamos [hunk](https://github.com/modem-dev/hunk),
+que resuelve esto con una sesión interactiva en la terminal donde el humano navega los
+hunks y el agente le anota comentarios. Lo bueno de robar es el **contrato**: el agente
+emite un lote estructurado y la publicación es un paso aparte. Lo que no robamos es la
+TUI: construirla es un proyecto entero y **ata el flujo a que el humano esté en tu
+terminal** — justo lo contrario de la 0002. Un JSON es diff-eable, editable a mano,
+auditable, y anda igual en Claude, Copilot o Cursor.
+
+### 2. El CLI valida contra el diff antes de salir a la red
+
+`dai forge review` trae el diff con **git** (local, por SSH — no gasta rate limit ni
+depende de la API) y verifica que cada `path:line` **exista de verdad en el hunk**, del
+lado declarado. Lo que no apunta al diff **no se postea**.
+
+Esto es lo que más valor tiene del comando, más que postear. Es la diferencia entre un
+review que entra y un `422` críptico que se lleva puestos los hallazgos buenos.
+
+### 3. Nada se cae en silencio
+
+Un hallazgo descartado o filtrado **se reporta**: en el preview del CLI y en un
+`<details>` del propio resumen posteado. Un tope (`--max-comments`) que corta en silencio
+se lee como "revisé todo" cuando no. Si dai suprime algo, lo dice.
+
+### 4. `--yes` explícito; el desatendido es una excepción que se pide
+
+Sin `--yes` no se postea nada, nunca: se muestra el preview y se corta. El modo
+desatendido existe —`--yes --min-severity medium --min-confidence 0.8 --max-comments N`—
+pero es una **excepción que el humano tipea**, no un default al que se llega por descuido.
+
+`confidence` es lo que lo hace usable: por debajo del umbral el hallazgo no se postea y
+queda listado. Es el equivalente honesto del *"Comments suppressed due to low confidence"*
+de Copilot.
+
+### 5. `event: COMMENT`, nunca `APPROVE`
+
+Ni siquiera en desatendido, ni por configuración. dai comenta; la aprobación la firma un
+humano ([Art. 5](../MANIFIESTO.md#art-5)).
+
+### 6. Cada comentario inline lleva marca de dai
+
+El review sale con el token del humano, así que el forge lo atribuye a él **sin badge de
+bot** — a diferencia de Copilot, que postea vía GitHub App y muestra el badge `AI`. Sin
+una marca en el cuerpo, el compañero ve seis juicios sobre su código firmados por una
+persona, sin forma de saber que los escribió una máquina. Cada comentario cierra con una
+línea que lo dice.
+
+## Consecuencias
+
+**A favor**
+
+- El hallazgo aparece al lado del código. El reviewer humano deja de reconstruir contexto.
+- El validador de posiciones convierte el error más común del LLM en un descarte legible,
+  antes de la red.
+- El `review.json` es auditable y editable: el humano puede bajar una severidad o borrar
+  un hallazgo sin pelearse con un prompt.
+- Sirve igual en GitHub y GitLab, y con cualquier asistente.
+
+**En contra / a asumir**
+
+- **GitLab no es atómico, y no lo podemos fingir.** GitHub postea resumen + N inline en
+  un solo `POST` (o entra todo o no entra nada). GitLab necesita 1 nota para el resumen y
+  N `discussions` separadas: si la tercera falla, las dos primeras **ya están
+  publicadas**. Se mitiga validando todo antes de la primera llamada, pero cuando falla
+  igual, el CLI **reporta qué entró y qué no** en vez de prometer una atomicidad que no
+  tiene.
+- GitLab exige los tres shas de `diff_refs` en cada comentario: `getPR` tuvo que dejar de
+  descartarlos.
+- Un `review.json` a medio editar no debe commitearse: `dai init` agrega `.dai/reviews/`
+  al `.gitignore` del repo (`.dai/` sigue versionándose — ahí vive `jira-fields.json`).
+
+**Fuera de alcance, a propósito**
+
+- **Bloques `suggestion`** (el botón "Apply suggestion"). Son valiosos pero la sintaxis
+  difiere entre GitHub y GitLab; el schema queda abierto para sumarlos después.
+- **Cuenta bot / GitHub App** para que los reviews salgan marcados como IA como los de
+  Copilot. Una cuenta bot es solo **otro token en el `.env`** (cero código); una GitHub
+  App sí es trabajo real (JWT + installation token). Es una decisión de operación del
+  equipo, no del CLI, y por eso no la cierra esta ADR.
+- **La calidad del review en sí.** dai no compite en catálogos de bugs ni reglas: eso no
+  es su dominio. Lo suyo es la trazabilidad y que el hallazgo aterrice donde sirve.

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

@@ -21,6 +21,8 @@ decisión cambia, se escribe un ADR nuevo que supersede al viejo. Molde en
 | [0013](0013-skills-externas-install-from.md) | `dai skills install --from`: skills externas por-stack, sin registro ni gatekeeping | aceptado |
 | [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

package/docs/detalle/04-tdd.md

@@ -1,32 +1,38 @@
-# Paso 4 — TDD: test primero, en vertical slices
+# Paso 4 — Implementación: el agente construye con TDD (`/opsx:apply`)
 
 ← vuelve a [`SCRUM-CON-IA.md`](../SCRUM-CON-IA.md)
 
 ## En qué consiste en detalle
 
-El CÓMO se construye con **test primero**, un comportamiento a la vez:
+El CÓMO **lo implementa el agente** con `/opsx:apply`: aplica las tareas que salieron de
+`opsx:propose`, escribiendo **test primero**, un comportamiento a la vez:
 
 ```
-RED   → escribes UN test que falla (un criterio de aceptación)
+RED   → el agente escribe UN test que falla (un criterio de aceptación)
 GREEN → el código mínimo para que pase
-REFACTOR → limpias, con los tests en verde
+REFACTOR → limpia, con los tests en verde
 ```
 
 *Vertical slices* (un test → una implementación → repetir), **no** horizontal
-(todos los tests, después todo el código).
+(todos los tests, después todo el código). Se verifica por la **interfaz pública**.
 
 ## Herramientas
 
-- Skill [`tdd`](../../skills/tdd/SKILL.md) — el loop red-green-refactor y qué es un
-  buen test.
+- **`/opsx:apply`** — el paso donde el agente implementa las tareas del change.
+- Skill [`tdd`](../../skills/tdd/SKILL.md) — la disciplina que `/opsx:apply` sigue: el
+  loop red-green-refactor y qué es un buen test.
 
 ## Qué firma el humano
 
-El dev **decide qué comportamientos importa testear** (no se testea todo) y revisa
-cada slice. La IA escribe el test como spec ejecutable, el dev valida.
+El agente escribe el test y el código; el **dev decide qué comportamientos importa
+testear** (no se testea todo), valida cada slice, y **es responsable del resultado — no
+la IA** ([Art. 7](../MANIFIESTO.md#art-7)). Ese es el antídoto del vibe coding: la
+revisión minuciosa de lo que produjo el agente (paso 6, code review propio).
 
 ## Antipatrones
 
+- **Aceptar lo que sale sin revisarlo** → vibe coding con otra cara. El agente propone;
+  el dev responde por el código.
 - **Horizontal slicing** (todos los tests juntos) → tests de la *forma imaginada*, no
   del comportamiento real.
 - **Testear lo interno** (mocks de colaboradores, métodos privados) → el test se rompe

package/docs/detalle/06-code-review.md

@@ -8,16 +8,19 @@ Dos revisiones distintas:
 
 1. **El dev revisa su propia implementación** — la que produjo la IA, minucioso y con
    criterio (correctitud, casos borde, seguridad, calidad). Es responsable del código, no
-   la IA (anti vibe-coding). Recién con eso en orden, y todo **commiteado**, crea la PR.
+   la IA (anti vibe-coding). Solo con eso en orden, y todo **commiteado**, crea la PR.
 2. **Un partner revisa la PR** y **firma** aprobación/rechazo. Se apoya en la skill
    `dai-review` para un primer pase consciente de la metodología: corre `dai check` (¿la US
-   quedó atrasada?), valida el DoD, revisa el código (🔴 errores / 🟡 mejoras / ✅ bien) y
-   deja un **comentario estándar** en la PR/MR — le saca el ruido para que firme lo que importa.
+   quedó atrasada?), valida el DoD, revisa el código (severidad low/medium/high) y deja un
+   **review inline** — un resumen + **un comentario anclado a cada `archivo:línea`**. La
+   skill valida cada posición contra el diff (descarta lo que el modelo inventó), te muestra
+   el preview y **espera tu OK antes de postear** ([ADR-0016](../adr/0016-review-inline.md)).
 
 ## Herramientas
 
-- Skill [`dai-review`](../../skills/dai-review/SKILL.md) — GitHub y GitLab, postea por
-  MCP del forge o por `dai forge comment` (token).
+- Skill [`dai-review`](../../skills/dai-review/SKILL.md) — GitHub y GitLab. Postea el review
+  inline por el MCP del forge o por `dai forge review <ref> --from <review.json>` (token);
+  `dai forge comment` queda como fallback simple sin anclar.
 - `dai check` ([ADR-0003](../adr/0003-deteccion-y-estampado-son-comandos.md)).
 - Gate de cierre: [`definition-of-done.md`](../../templates/definition-of-done.md).
 

package/docs/detalle/08-daily.md

@@ -7,7 +7,7 @@
 15 minutos: qué hice, qué voy a hacer, qué me traba. Es **sincronización**, no
 reporte de estado. Se hace **a mano, sin IA, a propósito**.
 
-## Por qué no metemos IA acá
+## Por qué no metemos IA aquí
 
 La IA *podría* auto-generar el "qué se hizo" desde git + el tracker. **No lo hacemos**:
 el daily es donde el equipo se **apropia** del proceso, lo entiende y se coordina de

package/docs/detalle/README.md

@@ -9,7 +9,7 @@ los antipatrones a evitar.
 | [01](01-refinamiento.md) | Refinamiento (idea → US testeable) | ●●● |
 | [02](02-planning.md) | Planning (derivar el CÓMO) | ●● |
 | [03](03-ramas.md) | Rama ligada al QUÉ | ●●● |
-| [04](04-tdd.md) | TDD (test primero) | ●●● |
+| [04](04-tdd.md) | Implementación (`/opsx:apply`, con TDD) | ●●● |
 | [05](05-smoke.md) | Smoke end-to-end | ●● |
 | [06](06-code-review.md) | Code review (IA + partner) | ●● |
 | [07](07-merge-trazabilidad.md) | Merge + trazabilidad | ●●● |

package/docs/glosario.md

@@ -24,7 +24,7 @@
 | **`implements.yaml`** | El archivo, en el change del repo, que contiene ese link. Lo genera `link-us`. Ejemplo lleno + árbol de dónde vive entre los artefactos de OpenSpec: [ADR-0004](adr/0004-ubicacion-y-schema-implements.md). |
 | **Trazabilidad inversa / cobertura** | El mapa "quién implementó este QUÉ". **Se genera, nunca se escribe.** |
 | **Índice / router** | La tabla central que dice qué ID vive en qué repos. Es un router, **no un almacén**: no guarda el detalle. |
-| **Federación (dos niveles)** | Cómo se guarda la trazabilidad a escala: Nivel 1 = índice central chico; Nivel 2 = detalle en cada repo, resuelto on-demand. *(Es un eje distinto de los niveles de ceremonia N1/N2/N3: acá "nivel" es dónde vive el dato, no el tamaño del equipo.)* |
+| **Federación (dos niveles)** | Cómo se guarda la trazabilidad a escala: Nivel 1 = índice central chico; Nivel 2 = detalle en cada repo, resuelto on-demand. *(Es un eje distinto de los niveles de ceremonia N1/N2/N3: aquí "nivel" es dónde vive el dato, no el tamaño del equipo.)* |
 | **Matriz de trazabilidad** | La vista "repo × versión × estado (al día / atrasado)". Derivada, no mantenida a mano. |
 
 ## El versionado
@@ -46,7 +46,7 @@
 | **PR / MR (Pull / Merge Request)** | La unidad revisable del CÓMO. En dai lleva **dos activos**, y el review cubre ambos: (1) la **implementación** (el código) y (2) el **spec trazable** (el `implements.yaml` con el link a la US y el `@version` verificado). Sin el segundo, el CI bloquea el PR. Template en `../templates/pull-request.md`. |
 | **Change** | La unidad de trabajo de OpenSpec (proposal + design + tasks + specs). |
 | **ADR (Architecture Decision Record)** | El registro de una decisión estructural: contexto, decisión, consecuencias. Chico e **inmutable** — si algo cambia, se escribe uno nuevo que supersede al viejo. Template en `../templates/adr.md`; los de dai, en [`adr/`](adr/). |
-| **TDD (Test-Driven Development)** | Escribir el test **antes** que el código: RED (test que falla) → GREEN (código mínimo) → REFACTOR. En dai cada AC se vuelve un test (skill `tdd`); es el antídoto del vibe coding. |
+| **TDD (Test-Driven Development)** | Escribir el test **antes** que el código: RED (test que falla) → GREEN (código mínimo) → REFACTOR. En dai lo aplica el **agente** dentro de `/opsx:apply` (disciplina de la skill `tdd`): cada AC se vuelve un test. El dev valida y es responsable. Es el antídoto del vibe coding. |
 | **Vertical slice** | Un test → una implementación → repetir. Lo opuesto a "todos los tests, después todo el código". |
 | **Smoke** | Escenario end-to-end que verifica que el flujo grueso no se rompió. |
 

package/docs/guias/dev.md

@@ -18,12 +18,14 @@
 
 ## Tu día a día
 
-1. **Agarras una US** que cumple el [DoR](../../templates/definition-of-ready.md) → `/link-us ABC-###`. Crea la rama y el
+1. **Tomas una US** que cumple el [DoR](../../templates/definition-of-ready.md) → `/link-us ABC-###`. Crea la rama y el
    `implements.yaml` **desde el ID, sin que tipees el key a mano** (Art. 8, Art. 9).
 2. **Armas el CÓMO** → `opsx:explore` → `opsx:propose`. OpenSpec genera
    `design.md`/`tasks.md`; tú validas y ajustas. Las tareas nacen del cómo.
-3. **Implementas con TDD** → `/tdd`. Un test a la vez, vertical slices: RED → GREEN
-   → refactor. Verificas por la **interfaz pública**, no espías lo interno (Art. 7).
+3. **El agente implementa el CÓMO** → `/opsx:apply`. Aplica las tareas escribiendo
+   test-primero (TDD, vertical slices: RED → GREEN → refactor), por la **interfaz
+   pública** (Art. 7). Tú decides qué comportamientos importa testear; el agente los
+   construye.
 4. **Smoke** → ejecutas el escenario end-to-end del flujo.
 5. **Revisas la implementación de la IA** (code review propio) → minucioso y con criterio:
    correctitud, casos borde, seguridad, calidad. **Eres responsable del código, no la IA**
@@ -33,7 +35,8 @@
    arma la PR **precargada** (US + estado del check + links; los **dos activos**: código +
    spec trazable) y la asignas a un partner.
 7. **Review de un partner** → un compañero revisa tu PR y **firma** aprobación/rechazo
-   (Art. 5). Se apoya en la skill `/dai-review` para un primer pase con comentario estándar.
+   (Art. 5). Se apoya en la skill `/dai-review` para un primer pase: un **review inline**
+   (resumen + un comentario por línea), que le muestra el preview y espera su OK antes de postear.
    *(Tu PR la revisas tú en el paso 5; la de un compañero, lo ayudas con la skill.)*
 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
@@ -45,7 +48,7 @@
 ## La trampa a evitar
 
 **Vibe coding.** Nada de codear sobre una idea vaga o "improvisar y después vemos".
-Si no hay US con criterios testeables, no arranques: falta el [DoR](../../templates/definition-of-ready.md). La disciplina
+Si no hay US con criterios testeables, no empieces: falta el [DoR](../../templates/definition-of-ready.md). La disciplina
 —US clara → design → test → código— es lo que separa esto de pedirle cosas a un chat.
 
 ## Cuando el QUÉ cambia
@@ -59,8 +62,8 @@ te avisa: el link versionado lo hace [Art. 11](../MANIFIESTO.md#art-11).
 - `/link-us`
 - `/opsx:explore`
 - `/opsx:propose`
-- `/opsx:apply`
-- `/tdd`
+- `/opsx:apply` — el agente implementa las tareas (con TDD)
+- `/tdd` — la disciplina TDD que aplica el paso anterior
 - `/dai-review`
 - `dai check` · `dai pr` · `dai stamp` · `dai done` (limpieza, opcional)
 - `definition-of-done.md`

package/docs/guias/index.md

@@ -0,0 +1,12 @@
+# Guías por rol
+
+Un camino corto según quién eres. Cada guía te dice de qué eres **dueño**, qué **no tocas**,
+y tu **día a día**.
+
+- [**Guía del PO / funcional**](./po) — dueño del **QUÉ**: defines las User Stories y el
+  porqué, nunca el CÓMO. Entrás por `grill-user-story`, `grill-epic` o `doc-to-backlog`.
+- [**Guía del dev / ingeniero**](./dev) — dueño del **CÓMO** y del **link**: el agente
+  implementa con `/opsx:apply`, tú revisas y autoras el `implements.yaml`.
+- [**Guía del lead / SM / arquitecto**](./lead) — custodio de las **invariantes** y del
+  **nivel de ceremonia** (N1 / N2 / N3): haces que el método se cumpla y se aligere donde
+  corresponde.

package/docs/guias/lead.md

@@ -23,7 +23,7 @@
 
 ## Tus decisiones clave
 
-### 1. ¿En qué nivel arranca el equipo?
+### 1. ¿En qué nivel empieza el equipo?
 - **1 dev / 1 repo →** N1 (OpenSpec solo, cero herramientas externas).
 - **Equipo compacto →** N2 (US en el gestor + `implements.yaml`).
 - **Muchos repos + equipos separados →** N3 (Jira hub, CI estampa, matriz de ambientes).

package/docs/guias/po.md

@@ -18,13 +18,17 @@
 
 ## Tu día a día
 
-1. **Nace una idea** → creas el ticket en el gestor (nace con ID, aunque sea vago).
-2. **Gate 0** → ejecutas `/grill-intent`. La IA te desafía el *problema*: ¿es el
-   correcto? ¿quién lo sufre? ¿qué pasa si no lo hacemos? Un veredicto válido es
-   *"no lo construyas"* — eso es el gate haciendo su trabajo (Art. 4).
-3. **Pulir el QUÉ** → ejecutas `/grill-user-story`. La IA te **interroga** hasta que
+1. **Nace una idea — o llega un documento** → creas el ticket en el gestor (nace con ID,
+   aunque sea vago). Si en cambio partes de un **documento de análisis** (PDF, Word),
+   `/doc-to-backlog` lo convierte en un **backlog candidato** de épicas + US para que
+   priorices y valides. Y si algo es **demasiado grande** para una sola US,
+   `/grill-epic` lo parte en varias.
+2. **Pulir el QUÉ** → ejecutas `/grill-user-story`. La IA te **interroga** hasta que
    la US es testeable (INVEST + Gherkin) y la publica en el gestor. La IA no
    inventa requerimientos: te los saca a preguntas. Tú respondes y decides.
+3. **Gate 0** → ejecutas `/grill-intent` sobre la US ya formada. La IA te desafía el
+   *problema*: ¿es el correcto? ¿quién lo sufre? ¿qué pasa si no lo hacemos? Un veredicto
+   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.
@@ -44,7 +48,9 @@ el CI (Art. 10).
 
 ## Tus herramientas
 
-- `/grill-intent`
-- `/grill-user-story`
+- `/doc-to-backlog` — un documento (PDF/Word) → backlog candidato de épicas + US
+- `/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
 - el gestor de proyectos
 - [`definition-of-ready.md`](../../templates/definition-of-ready.md)

package/docs/index.md

@@ -0,0 +1,35 @@
+---
+layout: home
+
+hero:
+  name: dai
+  text: Desarrollo Asistido por IA
+  tagline: La documentación del método — el manifiesto, las decisiones (ADRs) y las guías por rol. Todo buscable con ⌘K.
+  actions:
+    - theme: brand
+      text: Empezar
+      link: /PROBAR
+    - theme: alt
+      text: El manifiesto
+      link: /MANIFIESTO
+    - theme: alt
+      text: ↩ Volver a la landing
+      link: https://dforce2055.github.io/dai/
+
+features:
+  - icon: 📐
+    title: El método
+    details: Manifiesto, metodología y el Scrum con IA en 10 pasos. El porqué antes que el cómo.
+    link: /MANIFIESTO
+    linkText: Leer el manifiesto
+  - icon: 🧭
+    title: Las decisiones (ADRs)
+    details: Cada decisión de diseño, registrada — del contrato del ac_hash al review inline. Por qué dai es como es.
+    link: /adr/
+    linkText: Ver los ADRs
+  - icon: 🧑‍💻
+    title: Guías por rol
+    details: Caminos cortos según quién sos — PO / analista, dev, o lead. Directo a lo que te toca.
+    link: /guias/dev
+    linkText: Ir a las guías
+---

package/docs/public/favicon.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+    <defs><radialGradient id="favc" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="0.35" stop-color="#F4B41A"/><stop offset="1" stop-color="#D98E04"/>
+    </radialGradient></defs>
+    <g fill="url(#favc)"><path d="M50.00 4.00 L52.00 29.00 L48.00 29.00 Z"/><path d="M67.60 7.50 L59.88 31.36 L56.19 29.83 Z"/><path d="M82.53 17.47 L66.26 36.56 L63.44 33.74 Z"/><path d="M92.50 32.40 L70.17 43.81 L68.64 40.12 Z"/><path d="M96.00 50.00 L71.00 52.00 L71.00 48.00 Z"/><path d="M92.50 67.60 L68.64 59.88 L70.17 56.19 Z"/><path d="M82.53 82.53 L63.44 66.26 L66.26 63.44 Z"/><path d="M67.60 92.50 L56.19 70.17 L59.88 68.64 Z"/><path d="M50.00 96.00 L48.00 71.00 L52.00 71.00 Z"/><path d="M32.40 92.50 L40.12 68.64 L43.81 70.17 Z"/><path d="M17.47 82.53 L33.74 63.44 L36.56 66.26 Z"/><path d="M7.50 67.60 L29.83 56.19 L31.36 59.88 Z"/><path d="M4.00 50.00 L29.00 48.00 L29.00 52.00 Z"/><path d="M7.50 32.40 L31.36 40.12 L29.83 43.81 Z"/><path d="M17.47 17.47 L36.56 33.74 L33.74 36.56 Z"/><path d="M32.40 7.50 L43.81 29.83 L40.12 31.36 Z"/></g>
+    
+    <circle cx="50" cy="50" r="19" fill="none" stroke="#74ACDF" stroke-width="2.3"/>
+    <circle cx="50" cy="50" r="15" fill="#14305C"/><path d="M43.5 44.9 L39.5 50 L43.5 55.1
+      M56.5 44.9 L60.5 50 L56.5 55.1
+      M51.8 44.4 L48.2 55.6"
+      fill="none" stroke="#EAF4FB" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+  </svg>

package/docs/public/logo-link.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+    <defs><radialGradient id="sol-link" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="0.35" stop-color="#F4B41A"/><stop offset="1" stop-color="#D98E04"/>
+    </radialGradient></defs>
+    <g fill="url(#sol-link)"><path d="M50.00 6.00 L51.12 32.00 L48.88 32.00 Z"/><path d="M57.61 11.75 L54.61 32.56 L52.41 32.13 Z"/><path d="M66.84 9.35 L57.92 33.80 L55.85 32.94 Z"/><path d="M71.67 17.57 L60.93 35.66 L59.07 34.41 Z"/><path d="M81.11 18.89 L63.52 38.06 L61.94 36.48 Z"/><path d="M82.43 28.33 L65.59 40.93 L64.34 39.07 Z"/><path d="M90.65 33.16 L67.06 44.15 L66.20 42.08 Z"/><path d="M88.25 42.39 L67.87 47.59 L67.44 45.39 Z"/><path d="M94.00 50.00 L68.00 51.12 L68.00 48.88 Z"/><path d="M88.25 57.61 L67.44 54.61 L67.87 52.41 Z"/><path d="M90.65 66.84 L66.20 57.92 L67.06 55.85 Z"/><path d="M82.43 71.67 L64.34 60.93 L65.59 59.07 Z"/><path d="M81.11 81.11 L61.94 63.52 L63.52 61.94 Z"/><path d="M71.67 82.43 L59.07 65.59 L60.93 64.34 Z"/><path d="M66.84 90.65 L55.85 67.06 L57.92 66.20 Z"/><path d="M57.61 88.25 L52.41 67.87 L54.61 67.44 Z"/><path d="M50.00 94.00 L48.88 68.00 L51.12 68.00 Z"/><path d="M42.39 88.25 L45.39 67.44 L47.59 67.87 Z"/><path d="M33.16 90.65 L42.08 66.20 L44.15 67.06 Z"/><path d="M28.33 82.43 L39.07 64.34 L40.93 65.59 Z"/><path d="M18.89 81.11 L36.48 61.94 L38.06 63.52 Z"/><path d="M17.57 71.67 L34.41 59.07 L35.66 60.93 Z"/><path d="M9.35 66.84 L32.94 55.85 L33.80 57.92 Z"/><path d="M11.75 57.61 L32.13 52.41 L32.56 54.61 Z"/><path d="M6.00 50.00 L32.00 48.88 L32.00 51.12 Z"/><path d="M11.75 42.39 L32.56 45.39 L32.13 47.59 Z"/><path d="M9.35 33.16 L33.80 42.08 L32.94 44.15 Z"/><path d="M17.57 28.33 L35.66 39.07 L34.41 40.93 Z"/><path d="M18.89 18.89 L38.06 36.48 L36.48 38.06 Z"/><path d="M28.33 17.57 L40.93 34.41 L39.07 35.66 Z"/><path d="M33.16 9.35 L44.15 32.94 L42.08 33.80 Z"/><path d="M42.39 11.75 L47.59 32.13 L45.39 32.56 Z"/></g>
+    
+    <circle cx="50" cy="50" r="15.5" fill="none" stroke="#74ACDF" stroke-width="2.3"/>
+    <circle cx="50" cy="50" r="12" fill="#14305C"/>
+    <line x1="45" y1="50" x2="55" y2="50" stroke="#EAF4FB" stroke-width="2.2" stroke-linecap="round"/>
+    <circle cx="45" cy="50" r="2.5" fill="#EAF4FB"/>
+    <circle cx="55" cy="50" r="2.5" fill="#EAF4FB"/>
+  </svg>

package/docs/public/logo.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+    <defs><radialGradient id="sol-code" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="0.35" stop-color="#F4B41A"/><stop offset="1" stop-color="#D98E04"/>
+    </radialGradient></defs>
+    <g fill="url(#sol-code)"><path d="M50.00 6.00 L51.12 32.00 L48.88 32.00 Z"/><path d="M57.61 11.75 L54.61 32.56 L52.41 32.13 Z"/><path d="M66.84 9.35 L57.92 33.80 L55.85 32.94 Z"/><path d="M71.67 17.57 L60.93 35.66 L59.07 34.41 Z"/><path d="M81.11 18.89 L63.52 38.06 L61.94 36.48 Z"/><path d="M82.43 28.33 L65.59 40.93 L64.34 39.07 Z"/><path d="M90.65 33.16 L67.06 44.15 L66.20 42.08 Z"/><path d="M88.25 42.39 L67.87 47.59 L67.44 45.39 Z"/><path d="M94.00 50.00 L68.00 51.12 L68.00 48.88 Z"/><path d="M88.25 57.61 L67.44 54.61 L67.87 52.41 Z"/><path d="M90.65 66.84 L66.20 57.92 L67.06 55.85 Z"/><path d="M82.43 71.67 L64.34 60.93 L65.59 59.07 Z"/><path d="M81.11 81.11 L61.94 63.52 L63.52 61.94 Z"/><path d="M71.67 82.43 L59.07 65.59 L60.93 64.34 Z"/><path d="M66.84 90.65 L55.85 67.06 L57.92 66.20 Z"/><path d="M57.61 88.25 L52.41 67.87 L54.61 67.44 Z"/><path d="M50.00 94.00 L48.88 68.00 L51.12 68.00 Z"/><path d="M42.39 88.25 L45.39 67.44 L47.59 67.87 Z"/><path d="M33.16 90.65 L42.08 66.20 L44.15 67.06 Z"/><path d="M28.33 82.43 L39.07 64.34 L40.93 65.59 Z"/><path d="M18.89 81.11 L36.48 61.94 L38.06 63.52 Z"/><path d="M17.57 71.67 L34.41 59.07 L35.66 60.93 Z"/><path d="M9.35 66.84 L32.94 55.85 L33.80 57.92 Z"/><path d="M11.75 57.61 L32.13 52.41 L32.56 54.61 Z"/><path d="M6.00 50.00 L32.00 48.88 L32.00 51.12 Z"/><path d="M11.75 42.39 L32.56 45.39 L32.13 47.59 Z"/><path d="M9.35 33.16 L33.80 42.08 L32.94 44.15 Z"/><path d="M17.57 28.33 L35.66 39.07 L34.41 40.93 Z"/><path d="M18.89 18.89 L38.06 36.48 L36.48 38.06 Z"/><path d="M28.33 17.57 L40.93 34.41 L39.07 35.66 Z"/><path d="M33.16 9.35 L44.15 32.94 L42.08 33.80 Z"/><path d="M42.39 11.75 L47.59 32.13 L45.39 32.56 Z"/></g>
+    
+    <circle cx="50" cy="50" r="16" fill="none" stroke="#74ACDF" stroke-width="2.3"/>
+    <circle cx="50" cy="50" r="12.8" fill="#14305C"/><path d="M44.5 46.43 L40.5 50 L44.5 53.57
+      M55.5 46.43 L59.5 50 L55.5 53.57
+      M51.8 45.93 L48.2 54.07"
+      fill="none" stroke="#EAF4FB" stroke-width="2.1" stroke-linecap="round" stroke-linejoin="round"/>
+  </svg>