@dforce2055/dai 0.9.0 → 0.11.0

package/docs/adr/0018-alcance-de-stamp-y-gate-de-ci.md

@@ -0,0 +1,183 @@
+# ADR-0018 — El alcance de `stamp` lo decide la rama, el gate de CI se ejecuta, y editar el QUÉ es un comando
+
+- **Estado:** aceptado
+- **Fecha:** 2026-07-22
+- **Decide:** lead / arquitecto de la metodología
+
+## Contexto
+
+Tres agujeros con la misma raíz: **dai suponía cosas sobre el QUÉ que nunca escribió en
+ningún lado** — que un repo tiene una sola US viva, que toda rama implementa una US, y que
+la US, una vez publicada, no se vuelve a tocar. Las tres suposiciones fallan en el primer
+sprint real.
+
+### 1. `dai stamp` estampaba todo el repo
+
+`cmdStamp` recorría el repo entero con `discoverImplements(cwd)` —**archivados
+incluidos**— y le dejaba un comentario de cobertura a cada US que encontrara. Cerrar una
+historia dejaba esto en el tracker:
+
+```
+➜  backend git:(feature/331qtr-historia-motor) dai stamp
+✓ 86acme482 → task 86acme482 (comentario)  (✅ al día)
+✓ 86acme483 → task 86acme483 (comentario)  (✅ al día)
+✓ 86acme484 → task 86acme484 (comentario)  (✅ al día)
+✓ 86acme485 → task 86acme485 (comentario)  (✅ al día)
+```
+
+Tres de esos cuatro comentarios son ruido en el ticket de otra persona. Y un comentario
+en un tracker **no se deshace**: queda en el historial de la US, en la notificación por
+mail de quien la sigue, y en el Slack del canal conectado.
+
+Lo llamativo es que `dai check` **ya** filtraba los archivados (`includeArchived: false`,
+ADR-0010) y `stamp` no. La divergencia era un descuido, no una decisión.
+
+### 2. `governance/ci-rules.md` prometía un gate que no existía
+
+El documento decía, en una tabla, que el CI **bloquea** el PR si una rama de producto no
+tiene `implements.yaml`. No había ningún comando que hiciera eso. No estaba en `ci.yml`,
+no estaba en el CLI, no estaba en ningún template. Era una regla escrita que nadie
+aplicaba — el peor estado posible: el equipo cree que está protegido y no lo está.
+
+Y al ir a implementarla apareció el problema real, el que probablemente explica por qué
+nunca se implementó: **la regla como estaba escrita es demasiado dura**. Un `chore/` de
+bump de dependencias, un `docs/` de typo, un `hotfix/` de las tres de la mañana no
+tienen US, no deberían tenerla, y un gate que los bloquea se desactiva la primera semana.
+Un gate desactivado protege exactamente igual que un gate que no existe, pero además
+enseña al equipo que los checks de dai son un obstáculo.
+
+### 3. Editar una US publicada era copiar y pegar
+
+`dai publish` creaba la US y `dai check` detectaba que había cambiado. En el medio no
+había nada: para **editarla** el PO abría el navegador y escribía en un textarea sin
+validación, o el dev editaba el `us.md` local y el tracker quedaba viejo. El formato
+canónico (`templates/formato-us.md`) existía como documento y no como chequeo, así que una
+US podía volver al tracker sin criterios y nadie se enteraba hasta que `dai link-us`
+fallaba, sprints después.
+
+## Decisión
+
+### 1. El alcance de `stamp` sale del nombre de la rama, y ante la duda se pregunta
+
+`dai stamp` deja de recorrer el repo. La decisión vive en un módulo puro
+(`cli/lib/branch-scope.mjs`) que responde **qué estampar y por qué**:
+
+| Situación | Qué hace |
+|---|---|
+| `dai stamp ABC-482` | esas US, aunque el change esté archivado |
+| `dai stamp --all` | todo (el comportamiento viejo, ahora explícito) |
+| la rama nombra una US del repo | **solo esa** |
+| hay una sola US viva | esa |
+| varias US vivas y la rama no dice cuál | **no estampa: pregunta** |
+
+Los changes archivados **salen del default**. Se alcanzan con `--all` o nombrando el ID
+—que es justo el caso de estampar después del merge.
+
+> **El default es preguntar, no estampar de más.** Es la asimetría del costo: no estampar
+> se arregla corriendo el comando otra vez; estampar de más deja cuatro comentarios que
+> no se borran. Cuando no hay TTY (CI), en vez de preguntar **falla** y pide el ID
+> explícito — que es lo que un pipeline debería estar pasando de todos modos.
+
+El matcheo rama↔US es deliberadamente conservador: `feature/331qtr-historia-motor` **no**
+matchea `86acme482` aunque ambos sean alfanuméricos. Se comparan candidatos del nombre
+contra los IDs que el repo realmente declara, y si no hay coincidencia exacta se pregunta.
+
+Para el gate —que no tiene contra qué comparar, justamente porque el `implements.yaml` no
+existe— un key de tracker se reconoce por **MAYÚSCULAS + guion + números** (`ABC-482`). El
+case es lo único que lo separa de una palabra del slug con un número pegado: dogfoodeando
+esto, la rama `feat/issues-22-26` hacía que el gate sugiriera `dai link-us issues-22`, o
+sea mandar al dev a crear un link inventado. `dai link-us` preserva el case del key, y los
+keys de tracker son mayúsculas por convención en Jira, GitLab y Azure Boards.
+
+### 2. El gate es un comando, y sabe qué ramas no exigir
+
+```bash
+dai check --ci     # 0 = pasa · 1 = falta el link · 2 = el QUÉ cambió
+```
+
+Lee el nombre de la rama y aplica `branch-naming.md`:
+
+- `feature/`, `feat/` → **siempre** exige `implements.yaml`
+- `chore/`, `docs/`, `ci/`, `build/`, `test/`, `refactor/`, `style/`, `release/`,
+  `hotfix/`, `revert/` → **exentas**
+- `fix/` y cualquier otro prefijo → exige **solo si el nombre trae un ID** de tracker
+- sin prefijo (`main`, `develop`) → no es rama de trabajo
+
+> El nombre de la rama **es** la declaración del tipo de trabajo. Si el gate te bloquea
+> un chore, la respuesta no es inventarle una US: es renombrar la rama. Esto convierte
+> `branch-naming.md` de convención sugerida en algo con consecuencia, sin agregar
+> ceremonia nueva.
+
+En CI, la rama de una PR no se saca de git: `HEAD` es un merge commit detached. El
+comando lee `GITHUB_HEAD_REF` / `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME` / equivalentes.
+
+### 3. El gate no bloquea por falta de red ni de credencial
+
+`--no-network` valida el link y no compara contra la US viva; es el **default del
+template** (`templates/ci-dai-gate.yml`). Con los secrets del tracker cargados se saca el
+flag y el gate detecta además las US atrasadas.
+
+Mismo criterio dentro del modo completo: si el tracker no responde, **avisa y no
+bloquea**. Un gate que se pone rojo porque venció un token enseña al equipo a mirar para
+otro lado, y ahí perdimos los dos checks — el de red y el que sí importaba.
+
+### 4. Editar el QUÉ es un comando, y el `spec_version` lo decide la persona
+
+El tercer agujero del mismo origen: **la US vivía en el tracker y no había forma de
+editarla sin copiar y pegar.** El PO abría el navegador, escribía en un textarea sin
+validación, y el `.md` del repo quedaba viejo — o al revés. Dos comandos, un camino:
+
+```bash
+dai edit-us <ID>     # la baja del tracker → $EDITOR → valida → preview → guarda   (PO)
+dai update-us <ID>   # ya tenés el .md escrito (lo refinaste implementando) → guarda  (dev)
+```
+
+No son dos implementaciones: `edit-us` termina llamando al mismo tramo que `update-us`
+(`pushUS`), así que las dos puertas dan **el mismo preview y la misma confirmación**. La
+única diferencia es de dónde sale el markdown.
+
+**La validación bloquea tres cosas y avisa del resto.** Frenan: sin título, sin sección
+de criterios, sección vacía. Nada más — y no por permisividad: son exactamente las tres
+sin las cuales no hay `ac_hash`, y sin `ac_hash` no hay link QUÉ↔CÓMO. Que un criterio no
+sea Gherkin completo, o que el título tenga doce palabras, son **avisos**: dai opina en su
+dominio (la trazabilidad) y sugiere en el resto. `--strict` sube los avisos a errores para
+quien quiera esa política; no es el default, porque un gate que rechaza US legítimas se
+esquiva editando en el navegador y volvemos al punto de partida.
+
+Un formato inválido **no tira lo escrito**: te devuelve al editor con los errores a la
+vista, tantas veces como haga falta, y salir sin guardar deja tu `.md` intacto.
+
+**El `spec_version` se propone, no se impone.** Si el `ac_hash` se movió, dai pregunta:
+
+| El PO responde | Qué significa | Qué pasa |
+|---|---|---|
+| `s` | cambio **material** | `v1` → `v2`; los repos con `v1` se marcan atrasados |
+| `n` | cambio **editorial** | se queda en `v1`; nadie se marca atrasado |
+
+Es la línea que ya estaba escrita en [METODOLOGIA §4](../METODOLOGIA.md) —*el número
+comunica, el hash detecta*— llevada a una pregunta concreta. La máquina sabe **que** algo
+cambió; solo la persona sabe **si importa**. Automatizarlo en cualquiera de las dos
+direcciones rompe algo: subirlo siempre infla la versión con cada typo y entrena al equipo
+a ignorar los ⚠️; no subirlo nunca deja el número mintiendo. `--bump` / `--no-bump` cubren
+el caso no interactivo.
+
+## Consecuencias
+
+- `dai stamp` sin argumentos **cambia de comportamiento**: antes estampaba todo, ahora
+  estampa una. Es un cambio incompatible en el papel, pero el comportamiento viejo era el
+  bug; quien lo quiera tiene `--all`. Va en una **minor** por eso.
+- En CI hay que pasar el ID (`dai stamp ABC-482`). `governance/ci-rules.md` lo dice.
+- `branch-naming.md` pasa a tener consecuencia mecánica. Un repo con otras convenciones de
+  prefijo va a ver ramas "exentas" que él considera de producto — el escape es nombrar la
+  rama con el ID, que es lo que `dai link-us` hace solo.
+- El gate no valida tests ni lint: eso ya lo hace el CI del repo y dai no se mete
+  (ver `dai` como herramienta, no como mandato).
+- Los adaptadores de PM ahora devuelven `raw` (el markdown completo de la US) además del
+  parseo. Es lo que `edit-us` abre; antes solo teníamos título + hash, que alcanza para
+  detectar drift pero no para editar.
+- `dai edit-us` le da al **PO** un comando de terminal, cuando hasta ahora su superficie
+  eran skills en el asistente y el tracker. Es opcional —seguir editando en el navegador
+  funciona igual— pero es el único camino donde el formato se valida ANTES de guardar.
+- La validación de formato vive en el CLI (`us-format.mjs`), no en la skill. Es lo
+  mecánico y verificable; el criterio de si un criterio es *bueno* sigue en
+  `/grill-user-story`, que interroga (ADR-0002).

package/docs/adr/README.md

@@ -22,6 +22,8 @@ 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 |
+| [0018](0018-alcance-de-stamp-y-gate-de-ci.md) | El alcance de `dai stamp` lo decide la rama (ante la duda pregunta, no estampa de más), `dai check --ci` ejecuta el gate de governance con ramas exentas, y `dai edit-us`/`update-us` editan el QUÉ validando el formato y proponiendo el `spec_version` | aceptado |
 
 > Estas son las decisiones que cierran las "Decisiones abiertas" de
 > [`METODOLOGIA.md §7`](../METODOLOGIA.md) y las enmiendas al

package/docs/detalle/01-refinamiento.md

@@ -7,17 +7,32 @@
 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.
+
+## Cuando la US ya existe y hay que editarla
+
+El refinamiento no termina cuando la US entra al sprint: aparece un criterio que faltaba,
+o una regla que nadie había dicho. `dai edit-us <ID>` cierra ese ciclo sin copiar y pegar:
+baja la US del tracker, la abre en el editor del PO, **valida el formato** (título +
+criterios + Gherkin completo), muestra qué cambia, pregunta si el cambio es **material**
+(sube `spec_version`, los repos atrasados se marcan solos) o **editorial** (no sube nada),
+y recién con la confirmación escribe.
+
+Si el que refina es el **dev** —un criterio que aparece escribiendo el test— es el mismo
+camino por la otra puerta: `dai update-us <ID>` empuja el `us.md` del change, con el mismo
+preview y la misma confirmación ([ADR-0018](../adr/0018-alcance-de-stamp-y-gate-de-ci.md)).
 
 ## Herramientas
 
-- `/grill-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`
+- `dai edit-us <ID>` → trae la US del tracker, la editas, dai valida el formato y la devuelve.
 - Gate de entrada: [`definition-of-ready.md`](../../templates/definition-of-ready.md).
 
 ## Qué firma el humano

package/docs/detalle/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/07-merge-trazabilidad.md

@@ -11,13 +11,22 @@ cobertura inversa** en el tracker: qué repo/change implementa la US, contra qu
 versión, con estado ✅/⚠️ y links (branch + commit-ancla).
 
 ```bash
-dai check   # ¿estoy atrasado respecto de la US?  (read-only, gate de PR)
-dai stamp   # escribe la cobertura en el tracker  (branch + commit)
+dai check          # ¿estoy atrasado respecto de la US?  (read-only)
+dai check --ci     # el mismo chequeo como GATE del PR: 0 pasa · 1 falta el link · 2 atrasado
+dai stamp          # escribe la cobertura en el tracker  (branch + commit)
 ```
 
+`dai stamp` sin argumentos deduce **qué US** estampar del nombre de tu rama, y si el repo
+tiene varias vivas y no puede saberlo, **pregunta** antes de escribir: un comentario en un
+tracker no se deshace. **En un pipeline pasá el ID** — `dai stamp ABC-482` — que además es
+lo único que un CI sabe con certeza ([ADR-0018](../adr/0018-alcance-de-stamp-y-gate-de-ci.md)).
+
 ## Herramientas
 
 - `dai check` / `dai stamp` — mismos comandos los corra un humano o el CI.
+- `dai check --ci` — el gate de [`ci-rules.md`](../../governance/ci-rules.md) ejecutable:
+  exige el link en las ramas de producto y deja pasar `chore/`, `docs/`, `release/`…
+  Workflow listo para copiar: [`templates/ci-dai-gate.yml`](../../templates/ci-dai-gate.yml).
 - Contenido del stamp: [ADR-0005](../adr/0005-superficie-comandos-y-stamp.md).
 
 ## Qué firma el humano
@@ -28,6 +37,8 @@ dai stamp   # escribe la cobertura en el tracker  (branch + commit)
 ## Antipatrones
 
 - **Actualizar el estado del ticket a mano** → desincronización garantizada.
+- **`dai stamp --all` en el CI** → le deja un comentario a cada US del repo, incluidas las
+  de sprints viejos. En un pipeline el ID va explícito.
 - **Escribir el link en los dos lados** → se desincroniza al primer cambio (Art. 9).
 - **Guardar solo la branch en el stamp** → 404 al borrarse; va con commit-ancla.
 - **Creer que hace falta "un CI en Jira"** → es un comando; el tracker no ejecuta nada.

package/docs/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ó. |
 
@@ -54,7 +54,7 @@
 
 | Término | Qué es |
 |---|---|
-| **CI (Integración Continua)** | La automatización que corre en cada *push* / PR: compila, corre los tests y valida el repo. **En dai**, el CI ejecuta `dai check` como *gate* del PR (valida que el link exista y que el `ac_hash` coincida con la US viva) y, al mergear, `dai stamp` (estampa la cobertura inversa en el tracker — nadie la escribe a mano). Qué valida, en [`governance/ci-rules.md`](../governance/ci-rules.md). |
+| **CI (Integración Continua)** | La automatización que corre en cada *push* / PR: compila, corre los tests y valida el repo. **En dai**, el CI ejecuta `dai check --ci` como *gate* del PR (valida que el link exista y que el `ac_hash` coincida con la US viva; las ramas `chore/`/`docs/` quedan exentas) y, al mergear, `dai stamp <ID>` (estampa la cobertura inversa en el tracker — nadie la escribe a mano). Qué valida, en [`governance/ci-rules.md`](../governance/ci-rules.md); workflow listo para copiar en [`templates/ci-dai-gate.yml`](../templates/ci-dai-gate.yml). |
 | **CD (Despliegue Continuo)** | La automatización que lleva la versión a los ambientes (`dev` / `test` / `pre` / `prod`) y reporta a cuál llegó. **En dai**, el CD alimenta la **matriz repo × ambiente**: *implementado ≠ desplegado* — el CI dice "el repo implementó `@v3`", el CD dice "`@v3` está viva en `pre`". |
 | **CI/CD** | Juntos, la "plomería" que **blinda** el método sin depender de que la gente se acuerde (enforcement, no vigilancia). En dai es **opcional** (ADR-0003): aparece sobre todo en **N3** (organización grande). En **N1/N2** los mismos comandos (`dai check`, `dai stamp`) corren a mano o por un git-hook — la trazabilidad es idéntica; solo cambia **quién** los dispara. dai **no trae** su propio CI/CD: se apoya en el pipeline que la organización ya tenga. |
 

package/docs/guias/dev.md

@@ -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,11 +35,15 @@
    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
    si la org lo tiene automatizado — mismo comando, ADR-0003). El estado se **deriva** (Art. 10).
+   `dai stamp` deduce **qué US** estampar del nombre de tu rama; si el repo tiene varias
+   vivas y no puede saberlo, te pregunta antes de escribir en el tracker. En un pipeline
+   pasa el ID: `dai stamp ABC-482` ([ADR-0018](../adr/0018-alcance-de-stamp-y-gate-de-ci.md)).
 10. **(Opcional) Limpias la rama** → `dai done` te devuelve a la base (default `main`, o
    `--base develop`), hace `fetch --prune` + `pull` y borra la rama local **solo si está
    mergeada**. Higiene del repo tras el merge, sin riesgo de perder trabajo sin integrar.
@@ -45,7 +51,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
@@ -54,13 +60,31 @@ Si el PO sube la US a `v2`, tu `implements.yaml` (que apunta a `v1`) se marca
 **atrasado** solo. Abres una nueva iteración contra `v2` y vuelves al paso 3. Nadie
 te avisa: el link versionado lo hace [Art. 11](../MANIFIESTO.md#art-11).
 
+### Cuando el que cambia el QUÉ eres tú
+
+Implementando aparece un criterio que la US no decía, y lo escribes en el `us.md` del
+change. Ahí el tracker queda viejo y tu `ac_hash` deja de coincidir con nada:
+
+```bash
+dai update-us ABC-482        # empuja tu us.md al tracker + re-estampa el ac_hash local
+```
+
+Te muestra qué va a cambiar allá arriba y **pide confirmación** antes de pisar la US
+(`--dry-run` para solo mirar, `--yes` para saltar la pregunta). Sin `--us` toma el `us.md`
+que está junto a tu `implements.yaml`.
+
+> Que un criterio nuevo pase por el tracker no es burocracia: es lo que hace que el
+> **PO se entere** de que la historia creció. Editar solo el `us.md` local deja el QUÉ
+> partido en dos versiones y ninguna es la buena.
+
 ## Tus herramientas
 
 - `/link-us`
 - `/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)
+- `dai update-us` — empuja al tracker una US que refinaste implementando
 - `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,16 +18,58 @@
 
 ## 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.
+5. **Editas una US que ya existe** → `dai edit-us ABC-482`. La **baja del gestor**, te la
+   abre en tu editor, **valida el formato** cuando guardas, te muestra qué cambia y
+   recién ahí la sube. Ver [Cuando el QUÉ cambia](#cuando-el-que-cambia) abajo.
+6. **Demo** → aceptas o rechazas contra los mismos criterios que ya eran tests.
+
+## Cuando el QUÉ cambia {#cuando-el-que-cambia}
+
+Un criterio que faltaba, una regla que aparece a mitad del sprint. La US **vive en el
+gestor**, no en un `.md` que alguien tiene que acordarse de sincronizar — así que dai la
+trae, te deja editarla y la devuelve:
+
+```bash
+dai edit-us ABC-482
+```
+
+1. **Baja** la US del gestor (Jira / ClickUp) a un `.md`.
+2. **La abre** en tu `$EDITOR`. Escribes en markdown, con el
+   [molde canónico](../../templates/formato-us.md) delante.
+3. **Valida el formato** al guardar: que tenga título, que tenga criterios, y que cada
+   criterio sea Gherkin completo (`Dado / Cuando / Entonces`). Si algo no da, **te
+   devuelve al editor** — no te tira lo escrito.
+4. **Te muestra qué cambia** allá arriba: título, cuántos criterios, el `ac_hash`.
+5. **Te pregunta si subir el `spec_version`** — y esta es la decisión tuya, no de dai:
+
+   | Tu cambio | Respondes | Qué pasa |
+   |---|---|---|
+   | Un criterio nuevo, una regla distinta (**material**) | `s` → `v1` → `v2` | los repos que implementaron `v1` se marcan **atrasados** solos |
+   | Un typo, redacción más clara (**editorial**) | `n` → se queda en `v1` | nadie se marca atrasado |
+
+   dai no puede distinguir las dos cosas mirando el hash: sabe *que* cambió, no *si
+   importa*. Eso lo sabes tú.
+6. **Confirmas** y recién ahí escribe en el gestor. Sin confirmación no se toca nada.
+
+> **`--dry-run`** te muestra todo el preview sin escribir. Úsalo la primera vez.
+
+Solo dos cosas te **frenan**: que la US no tenga título, o que no tenga criterios. Sin
+criterios no hay `ac_hash`, y sin `ac_hash` la US no se puede linkear a ningún repo — no
+es una regla de estilo, es lo que sostiene la trazabilidad. Todo lo demás (un criterio
+que no es Gherkin, un título largo) es un **aviso**: dai te lo dice y sigue.
 
 ## La trampa a evitar
 
@@ -44,7 +86,10 @@ 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
+- `dai edit-us <ID>` — traes una US del gestor, la editas, dai valida y la devuelve
 - el gestor de proyectos
 - [`definition-of-ready.md`](../../templates/definition-of-ready.md)

package/docs/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
+---