@dforce2055/dai 0.1.0

package/docs/METODOLOGIA.md

@@ -0,0 +1,254 @@
+# Metodología de Desarrollo Asistido por IA
+
+> **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`,
+> gana este `.md`. Versionado por git para que no driftee.
+
+Una sola metodología para dos escalas opuestas:
+
+- **Organización grande** — muchos procesos, muchos repos y desarrolladores,
+  funcional/PO y devs separados, tracker central (tipo Jira).
+- **Equipo chico** — pocos desarrolladores que suelen usar los dos sombreros
+  (definen el QUÉ y el CÓMO), tracker liviano o ninguno.
+
+No son dos metodologías. Es **un protocolo invariante** con **un dial de tres
+niveles de ceremonia** — **N1** (un dev solo), **N2** (equipo compacto) y **N3**
+(organización grande, federada), que se detallan en la
+[§3](#3-el-dial-tres-niveles-de-ceremonia). El dev que aprende la ceremonia como sólo
+developer o en equipo chico ya tiene todas las herramientas de la escala grande — solo le
+suben la plomería.
+
+---
+
+## 1. Los tres problemas que resolvemos
+
+1. **Trazabilidad** entre especificaciones e implementación, desde el
+   requerimiento hasta el código — y de vuelta.
+2. **Velocidad + calidad** del desarrollo asistido por IA: mejores specs, menos
+   retrabajo.
+3. **No vibe coding**: implementación estructurada y estandarizada, no
+   improvisación. Se logra con una US bien definida + una herramienta de
+   implementación disciplinada (OpenSpec) + TDD.
+
+La idea rectora: **separar el QUÉ del CÓMO** y mantenerlos **linkeados ida y
+vuelta**, *sin importar la herramienta de abajo*.
+
+| | **El QUÉ** | **El CÓMO** |
+|---|---|---|
+| Dueño | funcional / PO | dev / ingeniero |
+| Herramienta | Jira/ClickUp + `grill-user-story` (o el `proposal.md` de OpenSpec en N1) | OpenSpec (o swagger, yml, md…) |
+| Fuente de verdad de… | el contenido funcional | la relación QUÉ↔CÓMO y la implementación |
+
+---
+
+## 2. El protocolo invariante (igual en los tres niveles)
+
+Esto **no cambia nunca**, ni en el equipo chico ni en la organización grande. Es
+lo que hace que sea *una* metodología.
+
+### 2.1 Identidad estable
+
+Todo QUÉ tiene un **ID único e independiente del path o del formato**. No se
+inventa un esquema nuevo: el ID **es** el ticket del gestor (`ABC-###` en Jira,
+el ID de ClickUp) o —en N1— el nombre del change de OpenSpec. El QUÉ nace con
+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.
+
+### 2.3 El link se autora una sola vez, del lado del CÓMO
+
+El código declara `implements: <id>@<version>`. **Es el único link escrito a
+mano.** La dirección inversa (cobertura: "quién implementó este QUÉ") **siempre se
+genera**, nunca se escribe. Si se escribiera en los dos lados, se desincronizan al primer
+cambio.
+
+> **Regla de oro:** el link se escribe en un solo lado; la inversa se deriva. La
+> matriz de trazabilidad no la mantiene nadie — se calcula.
+
+### 2.4 `@version` = número + hash
+
+```
+@version  =  spec_version  +  ac_hash
+             (nº legible)     (hash de los criterios de aceptación)
+```
+
+- **`spec_version`** (`v1`, `v2`…) lo sube la persona para **comunicar** un cambio
+  material del QUÉ.
+- **`ac_hash`** lo calcula la máquina para **detectar**. Es el hash del bloque de
+  *Criterios de aceptación* normalizado (whitespace colapsado, orden estable).
+
+Cuando el QUÉ evoluciona, cambia el `ac_hash`; todos los CÓMO que declaran el hash
+viejo quedan marcados **atrasados** solos. El funcional ve "el backend todavía no
+tomó mi cambio"; el dev ve "el QUÉ que implementé cambió". Nadie avisa a nadie — el
+link versionado lo grita.
+
+- Cambio **material** de los AC → cambia el hash → re-marca repos atrasados.
+- Cambio **editorial** (typo, formato) → la normalización lo absorbe → **no**
+  dispara falso atraso.
+
+### 2.5 Trazabilidad federada de dos niveles
+
+El índice central es un **router, no un almacén**:
+
+```
+NIVEL 1 — Índice (central, grueso, chico, estable)
+  ABC-001  →  implementado en: { backend, bff, frontend } @ v3
+
+NIVEL 2 — Detalle (federado, en cada repo, se resuelve ON-DEMAND)
+  backend  ── resolve implements=ABC-001 ──►  su change / spec técnica
+  bff      ── resolve implements=ABC-001 ──►  su change / spec técnica
+  frontend ── resolve implements=ABC-001 ──►  su change / spec técnica
+```
+
+Una funcionalidad que toca 3 repos **no** genera 3× de mantenimiento central:
+genera **una fila** con 3 destinos. El detalle se lee del repo cuando se necesita,
+siempre fresco.
+
+### 2.6 Granularidad del link: **capacidad entera** (norma)
+
+`implements` es a nivel de **capacidad/US entera**, no criterio-por-criterio.
+Si el QUÉ sabe *quién* lo implementó, obtener el detalle fino es trivial: se
+resuelve el ID en el repo que interese. Criterio-por-criterio es trazabilidad
+quirúrgica pero insostenible con multi-repo. **Decidido: capacidad entera +
+federación.**
+
+### 2.7 TDD como norma de implementació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/`.
+
+---
+
+## 3. El dial: tres niveles de ceremonia
+
+**Misma metodología, distinto nivel según escala.** Cada capa se agrega **cuando
+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 |
+| 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 |
+| Índice central | no hace falta (todo co-localizado) | opcional (ClickUp como vista) | Jira = índice/router de la federación |
+| Roles | 1 persona, ambos sombreros | pocos devs, PO informal | funcional/PO y devs separados |
+| Gates | auto-review | review de un partner | Gate 0 formal + MR review + matriz repo×ambiente |
+| Multi-repo | no | opcional (p. ej. front + back) | sí, es el punto |
+
+### Regla de escala
+
+> Empieza con lo mínimo que funciona (**N1: OpenSpec solo**). Suma ClickUp cuando el
+> equipo lo pida (**N2**). Pasa al modelo federado solo cuando la escala lo
+> justifique (**N3**). No adelantes complejidad.
+
+El equipo chico vive en N1–N2 y quizás nunca necesite N3. La organización grande
+vive en N3. **Ninguno mantiene dos metodologías** — es el mismo protocolo
+(sección 2) con distinta plomería.
+
+### Colapso de roles (clave para equipos chicos)
+
+En un equipo chico una misma persona suele ser autor del QUÉ **y** del CÓMO. La metodología
+lo permite **sin romper la trazabilidad**: el link `implements` sigue existiendo
+aunque `autor_QUÉ == autor_CÓMO`, y los gates se **colapsan** (el Gate 0 y el
+partner-review pasan a ser un auto-check honesto, no una firma de otra persona).
+El artefacto no desaparece; se aligera la ceremonia alrededor.
+
+---
+
+## 4. Responsabilidades (quién autora qué)
+
+| | Autora | Herramienta | Fuente de verdad de… |
+|---|---|---|---|
+| QUÉ | PO / funcional (o el dev en N1) | Jira/ClickUp + `grill-user-story` | el contenido funcional |
+| Link | dev / ingeniero | `implements:` en el código | la relación QUÉ↔CÓMO |
+| Índice / vista inversa | CI (nadie a mano) | generado → publicado al PM | derivado, siempre verdadero |
+| Implementación (CÓMO) | dev / ingeniero | OpenSpec + TDD | el código y su spec técnica |
+
+---
+
+## 5. El flujo, punta a punta
+
+```
+   ①  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),
+                                 publicada en Jira/ClickUp (o .md si no hay MCP)
+   ④  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 despliega            → el CD reporta a qué ambiente (dev/test/pre/prod) fue la versión
+```
+
+- **En N1** los pasos ②–④ se colapsan: el `proposal.md` de OpenSpec **es** el QUÉ,
+  el change **es** el tracker, no hay PM externo.
+- **En N2** aparece ③ (US en ClickUp) y el `implements.yaml` referencia esa US.
+- **En N3** el flujo completo, con los gates formales y el CI/CD estampando estado
+  por repo y por ambiente.
+
+**Implementación ≠ despliegue.** El CI dice "el repo implementó `@v3`"; el CD dice
+"`@v3` está viva en `pre`, todavía no en `prod`". Se rastrea por ambiente.
+
+---
+
+## 6. Las skills del proceso
+
+| Skill | Lado | Qué hace |
+|---|---|---|
+| `grill-intent` | QUÉ | Gate 0: desafía el *problema* antes de escribir spec. Veredicto: a-spec / reframe / descartar. |
+| `grill-user-story` | QUÉ | Interroga hasta producir una US testeable (INVEST + Gherkin). Publica en Jira/ClickUp o deja `.md`. |
+| `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. |
+
+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
+distinto backend — no se bifurca por tamaño de equipo.
+
+---
+
+## 7. Decisiones abiertas (plomería de N3)
+
+El protocolo (sección 2) está cerrado **e implementado** en el CLI `dai`. De la plomería
+de N3 queda **una** decisión sin resolver; el resto se cerró al construir la herramienta.
+
+1. **Reporte de despliegue por ambiente (CD).** Cómo el CD reporta a Jira qué versión vive
+   en cada ambiente (`dev`/`test`/`pre`/`prod`), para la matriz repo×ambiente. dai hoy
+   estampa **cobertura** (implementación), no **despliegue** — *implementación ≠ despliegue*
+   (§2.5). Sigue abierta porque depende del pipeline que cada organización ya tenga; no la
+   fuerza el método ([ADR-0003](adr/0003-deteccion-y-estampado-son-comandos.md)).
+
+**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).
+- **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
+  pisan); superficie de comandos en [ADR-0005](adr/0005-superficie-comandos-y-stamp.md). Una org
+  N3 grande podría preferir un panel/custom-field, pero el mecanismo por defecto está decidido.
+- **`ac_hash`** = algoritmo + tres momentos ([ADR-0001](adr/0001-contrato-ac-hash.md), en `dai ac-hash`) ·
+  **detección/estampado como comandos** ([ADR-0003](adr/0003-deteccion-y-estampado-son-comandos.md)) ·
+  **agnóstico del asistente** ([ADR-0002](adr/0002-agnostico-del-asistente.md)) · granularidad = capacidad
+  entera (§2.6) · colapso de roles (§3) · formato de US + skills del QUÉ.
+
+---
+
+## 8. En resumen (para no técnicos)
+
+El **funcional** dice *qué* hay que hacer, en su herramienta de siempre (Jira),
+sin entrar nunca al editor de código. Una IA lo ayuda a que ese "qué" quede claro y
+testeable. El **dev** dice *cómo* se hace, en su repo, y deja una etiqueta que
+apunta al "qué". A partir de ahí, **una máquina** arma sola el mapa de quién hizo
+qué, contra qué versión, y quién quedó atrasado — sin que nadie lo mantenga a mano.
+Si el funcional cambia el "qué", el mapa marca solo a los que todavía no lo
+tomaron. En un equipo chico la misma persona hace las dos cosas y todo vive en una
+carpeta; en una organización grande hay equipos separados y el mapa lo publica el
+CI en el tracker. **Es el mismo método; cambia cuánta maquinaria le cuelgas.**

package/docs/PROBAR.md

@@ -0,0 +1,91 @@
+# 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).
+
+> 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).
+
+## 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
+
+dai --version
+```
+
+## Fase 0 — sin credenciales (backend `md`)
+
+Valida el loop completo `link-us → check → stamp` sin depender de red ni tokens.
+
+```bash
+# 1. Repo de prueba + bootstrap (dai init deja el .env; 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
+dai init --for both --pm md
+
+# 2. Escribe una US (formato formato-us.md) y publícala con el CLI
+cat > draft.md <<'EOF'
+# Finalizar la compra del carrito
+
+## Criterios de aceptación
+- Dado un carrito vacío, cuando se finaliza, entonces se rechaza
+EOF
+dai publish draft.md             # crea la US → devuelve el key (con md, un slug)
+#   ej: "US publicada en md: finalizar-la-compra-del-carrito"
+
+# 3. El flujo del dev
+dai link-us finalizar-la-compra-del-carrito   # branch + implements.yaml
+git add -A && git commit -m "feat: guard carrito vacío"
+dai check                        # ✅ al día
+
+# 4. La demo del ⚠️: edita el criterio en .dai/us/<slug>.md y vuelve a chequear
+dai check                        # ⚠️ ATRASADO (exit 1)  → sugiere: dai link-us <id> --resync
+dai stamp                        # con md, deja .dai/us/<slug>.coverage.md
+```
+
+Si esto anda, el flujo está bien. Pasa al tracker real.
+
+## Fase 1 — ClickUp real
+
+**Preparar ClickUp:**
+
+1. **La US:** una tarea con los criterios en la **descripción**, bajo un heading que
+   matchee `Criterios de aceptación` (es lo que dai hashea).
+2. **El ID:** en la tarea, `...` → *Copy ID* (tipo `86cxyz`).
+3. **El token:** ClickUp → *Settings → Apps → Generate* (empieza con `pk_...`).
+
+**Config y flujo:**
+
+```bash
+cat > .env <<'EOF'
+DAI_PM=clickup
+DAI_CLICKUP_TOKEN=pk_XXXXXXXX
+DAI_TRACKER_URL_TEMPLATE=https://app.clickup.com/t/{id}
+EOF
+dai doctor                       # confirma DAI_PM=clickup y el token
+
+dai link-us 86cxyz               # trae la US de ClickUp → branch + implements.yaml
+git add -A && git commit -m "feat: ..."
+dai check                        # ✅ al día
+
+# → edita un criterio de la tarea en ClickUp (en el navegador). Después:
+dai check                        # ⚠️ ATRASADO (lo detectó solo)
+dai stamp                        # deja un COMENTARIO en la tarea con la cobertura
+```
+
+> El `.env` está gitignored: el token no se commitea (ADR-0007).
+
+## Troubleshooting
+
+| Síntoma | Causa probable |
+|---|---|
+| `no encontré la US <id>` | ID mal, o el token no ve esa tarea |
+| `clickup 401` | token inválido o expirado |
+| `check` siempre da ⚠️ | editaste la US entre `link-us` y `check` (esperado), **o** los criterios no están bajo el heading `Criterios de aceptación` |
+| `sin US` en `check` | la tarea no tiene el bloque de criterios en la descripción |
+| branch/commit vacíos en el stamp | falta el remoto git (`git remote add origin …`) |

package/docs/SCRUM-CON-IA.md

@@ -0,0 +1,190 @@
+# Scrum con IA — El puente de adopción
+
+> **Para qué sirve este documento.** Es la pieza de *buy-in*: le muestra al equipo
+> que **no cambiamos su Scrum**. Los mismos pasos, los mismos roles, las mismas
+> ceremonias — solo que en cada paso donde hoy hay fricción o trabajo manual, hay
+> una skill de IA que lo hace por ti o te obliga a hacerlo bien.
+>
+> El protocolo que hay debajo (identidad estable, link QUÉ↔CÓMO, `@version`) vive
+> en [`METODOLOGIA.md`](METODOLOGIA.md). Acá contamos **la ceremonia**, paso a paso.
+
+## La frase para el equipo
+
+> **"Es tu mismo Scrum. Donde hoy haces algo a mano y con fricción, ahora invocas
+> una skill. El esqueleto es el que ya conoces — la curva de aprendizaje es casi
+> cero."**
+
+## Cómo leer la tabla de cada paso
+
+- **Clásico** — qué se hace hoy en Scrum tradicional.
+- **Dolor** — qué duele hoy (incluso sin IA).
+- **Con IA** — el pequeño ajuste potenciado por IA. No reemplaza el paso: lo mejora.
+- **Humano ([`HITL`](glosario.md))** — qué queda en manos de la persona, a propósito, para que el
+  equipo se adueñe del proceso y lo entienda.
+- **Herramienta** — la skill o pieza que lo habilita.
+- **Detalle →** — link al entregable ampliado (uno por paso, para no hacer esto extenso).
+
+---
+
+## Los 10 pasos
+
+```
+  ENTRADA DEL SPRINT          DURANTE EL SPRINT (por cada US)        EVENTOS / CIERRE
+  ┌──────────────────┐        ┌──────────────────────────┐          ┌──────────────────┐
+  │ 1 Refinamiento   │        │ 3 Rama ligada a la US    │          │ 8 Daily (manual) │
+  │ 2 Sprint Planning│   →    │ 4 Implementación TDD     │    →     │ 9 Review / Demo  │
+  └──────────────────┘        │ 5 Smoke test             │          │ 10 Retro (manual)│
+                              │ 6 Code review            │          └──────────────────┘
+                              │ 7 Merge + trazabilidad   │
+                              └──────────────────────────┘
+```
+
+---
+
+### Fase A — Entrada del sprint
+
+#### 1. Refinamiento: de épica a US testeable
+
+| | |
+|---|---|
+| **Clásico** | El PO parte épicas en Historias de Usuario y les pone criterios de aceptación. |
+| **Dolor** | US vagas, no testeables ("el usuario quiere un botón"). El malentendido se descubre tarde, ya implementado. |
+| **Con IA** | `grill-intent` (Gate 0: ¿es el problema correcto? veredicto a-spec / reframe / descartar) y luego `grill-user-story` **interrogan** al PO hasta que la US es testeable por construcción (INVEST + Gherkin). La IA no *escribe* la US: la *saca a preguntas*. La US nace con ID estable y criterios hasheables. |
+| **Humano (HITL)** | El PO responde y decide. La IA no inventa requerimientos: los pule. |
+| **Herramienta** | `grill-intent`, `grill-user-story`, `formato-us.md` |
+| **Detalle →** | [`detalle/01-refinamiento.md`](detalle/01-refinamiento.md) |
+
+#### 2. Sprint Planning: comprometer US y derivar tareas
+
+| | |
+|---|---|
+| **Clásico** | El equipo elige qué US entran al sprint y las rompe en tareas técnicas. |
+| **Dolor** | Las tareas las inventa alguien de arriba o no existen; se estima a ciegas. |
+| **Con IA** | El dev corre `opsx:explore` → `opsx:propose`: OpenSpec **genera el design y las tareas** desde la US. Las tareas nacen del *cómo*, definidas por quien va a implementar. |
+| **Humano (HITL)** | El equipo decide capacidad y prioridad. El dev valida y ajusta el design propuesto. |
+| **Herramienta** | `opsx:explore`, `opsx:propose` |
+| **Detalle →** | [`detalle/02-planning.md`](detalle/02-planning.md) |
+
+---
+
+### Fase B — Durante el sprint (por cada US)
+
+#### 3. Rama ligada a la US
+
+| | |
+|---|---|
+| **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. |
+| **Herramienta** | `link-us` |
+| **Detalle →** | [`detalle/03-ramas.md`](detalle/03-ramas.md) |
+
+#### 4. Implementación 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` |
+| **Detalle →** | [`detalle/04-tdd.md`](detalle/04-tdd.md) |
+
+#### 5. Smoke test de la US
+
+| | |
+|---|---|
+| **Clásico** | Antes de cerrar se verifica que no se rompió nada grueso. |
+| **Dolor** | Smoke manual, se olvida, o no existe. |
+| **Con IA** | La IA arma y corre un smoke del flujo end-to-end como paso de cierre de la US. |
+| **Humano (HITL)** | El dev confirma que el escenario refleja el uso real. |
+| **Herramienta** | skills de smoke por dominio (p. ej. `smoke-*`) |
+| **Detalle →** | [`detalle/05-smoke.md`](detalle/05-smoke.md) |
+
+#### 6. Code review
+
+| | |
+|---|---|
+| **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. |
+| **Humano (HITL)** | El partner aprueba o rechaza. La IA sugiere; la persona decide y firma. |
+| **Herramienta** | `dai-review` |
+| **Detalle →** | [`detalle/06-code-review.md`](detalle/06-code-review.md) |
+
+#### 7. Merge + trazabilidad automática
+
+| | |
+|---|---|
+| **Clásico** | Se mergea y (a veces) alguien actualiza el estado en el tracker. |
+| **Dolor** | El estado del tracker queda desactualizado; se llena a mano o no se llena. |
+| **Con IA** | Al mergear, el CI **estampa la cobertura inversa** en el tracker: qué repo implementó qué US, contra qué `@version`. El estado se *deriva*, no se reporta. El `@version`/`ac_hash` marca solo si el QUÉ cambió y el código quedó atrás. |
+| **Humano (HITL)** | Nadie mantiene la matriz a mano — ese es el punto. |
+| **Herramienta** | CI + `implements.yaml` + índice/router |
+| **Detalle →** | [`detalle/07-merge-trazabilidad.md`](detalle/07-merge-trazabilidad.md) |
+
+---
+
+### Fase C — Eventos y cierre
+
+#### 8. Daily standup — **manual (HITL)**
+
+| | |
+|---|---|
+| **Clásico** | 15 min: qué hice, qué voy a hacer, qué me traba. |
+| **Dolor** | A veces se vuelve reporte de estado en vez de sincronización. |
+| **Con IA** | **Ninguno, a propósito.** Se deja manual para mantener el *human-in-the-loop*: es donde el equipo se apropia del proceso, lo entiende y se coordina de verdad. La IA podría auto-generar el "qué se hizo" desde git, pero eso le sacaría al equipo la propiedad del ritual. |
+| **Humano (HITL)** | Todo. La conversación es el valor. |
+| **Herramienta** | — |
+| **Detalle →** | [`detalle/08-daily.md`](detalle/08-daily.md) |
+
+#### 9. Sprint Review / Demo
+
+| | |
+|---|---|
+| **Clásico** | Se muestra lo terminado al PO y stakeholders; se acepta o rechaza contra criterios. |
+| **Dolor** | "Esto no era lo que pedí". El QUÉ y el CÓMO se desincronizaron sin que nadie lo notara. |
+| **Con IA** | Se valida contra criterios de aceptación que **ya eran tests**. Si el QUÉ evolucionó, el `@version` lo gritó antes de la demo — no hay sorpresas. |
+| **Humano (HITL)** | El PO acepta o rechaza. La demo la corre una persona. |
+| **Herramienta** | criterios Gherkin de la US + `@version` |
+| **Detalle →** | [`detalle/09-review.md`](detalle/09-review.md) |
+
+#### 10. Retrospective — **manual (HITL)**
+
+| | |
+|---|---|
+| **Clásico** | El equipo mira *cómo trabajó* y elige 1–2 mejoras. |
+| **Dolor** | Se mejora "la sensación", sin datos. |
+| **Con IA** | **Ninguno directo, a propósito** — el ritual es humano. Pero la matriz de trazabilidad y las métricas de las US aportan **datos reales** de dónde se trabó el flujo, para que la conversación humana no sea a ciegas. |
+| **Humano (HITL)** | Todo el análisis y las decisiones de mejora. |
+| **Herramienta** | matriz de trazabilidad (input, no reemplazo) |
+| **Detalle →** | [`detalle/10-retro.md`](detalle/10-retro.md) |
+
+---
+
+## Resumen: dónde entra la IA y dónde no
+
+| Paso | IA | Por qué |
+|---|---|---|
+| 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. |
+| 5 Smoke | ●● | Cierre verificable de la US. |
+| 6 Code review | ●● | Primer pase automático, humano decide. |
+| 7 Merge + trazabilidad | ●●● | La matriz se deriva sola. |
+| 8 Daily | ○ | **Manual a propósito** — apropiación del proceso. |
+| 9 Review / Demo | ● | Validación contra criterios que ya eran tests. |
+| 10 Retro | ○ | **Manual a propósito** — la IA solo aporta datos. |
+
+`●●● = la IA hace el trabajo pesado` · `●● = asiste fuerte` · `● = aporta` · `○ = humano puro (HITL)`
+
+---
+
+## El detalle de cada paso
+
+Cada paso `1–10` está ampliado en su propio doc bajo [`detalle/`](detalle/) — para
+que este maestro quede corto y repartible. Cada uno incluye: en qué consiste en detalle, la
+herramienta con ejemplos, qué firma la persona (HITL) y los antipatrones a evitar.
+Ver el índice en [`detalle/README.md`](detalle/README.md).

package/docs/adr/0001-contrato-ac-hash.md

@@ -0,0 +1,86 @@
+# ADR-0001 — El contrato del `ac_hash`
+
+- **Estado:** aceptado
+- **Fecha:** 2026-07-03
+- **Decide:** lead / arquitecto de la metodología
+
+## Contexto
+
+El `@version` del link ([Art. 11](../MANIFIESTO.md#art-11) del manifiesto) es lo que hace que un cambio del QUÉ
+marque solo a los CÓMO atrasados. Ese mecanismo depende del `ac_hash`: un hash de
+los criterios de aceptación. Hasta ahora el `ac_hash` figuraba como "autogenerado"
+pero ninguna skill ni CI lo calculaba de verdad — con lo cual el versionado era
+decorativo. Sin un algoritmo definido, dos problemas: un typo dispararía un falso
+atraso, y distintas implementaciones (skill vs CI) podrían calcular hashes distintos.
+
+Y un tercero, más profundo: **el QUÉ muta después de publicarse, y no siempre por la
+skill.** Un PO edita un criterio a mano en Jira. Si el `ac_hash` se calculara **una
+sola vez** (al publicar la US), quedaría stale ante esa edición y la detección de
+atrasos se rompería en silencio — justo el pecado que la metodología existe para
+evitar. Por lo tanto el hash **no puede ser un evento de autoría**: tiene que
+re-derivarse de la US viva en el momento de la verificación.
+
+## Decisión
+
+### El algoritmo (una sola implementación: `dai ac-hash`)
+
+1. Tomar el bloque **Criterios de aceptación** de la US.
+2. **Normalizar**: remover marcado editorial (checkboxes, viñetas, numeración,
+   etiquetas `AC-N`, énfasis, headings) y colapsar todo el whitespace. Objetivo: que
+   un cambio *editorial* no cambie el hash.
+3. Hashear el texto normalizado con **SHA-256**, truncado a 8 hex (`7f3a9c2e`).
+4. El **orden** de los criterios es significativo: reordenar cambia el hash (por eso
+   el formato de US pide orden estable). No se ordena en la normalización.
+
+Existe **una sola** implementación canónica: el comando `dai ac-hash` (CLI, cero
+dependencias). Nadie más calcula el hash: todos lo **invocan**. En particular, una
+skill (un LLM) **nunca** computa el hash por su cuenta — sería no determinista y
+daría distinto al CI (ver ADR-0002: lo mecánico vive en el CLI).
+
+### Los tres momentos (y quién es la autoridad)
+
+| Momento | Quién | Qué hace con el hash |
+|---|---|---|
+| **Publicar la US** | `grill-user-story` → invoca `dai ac-hash` | *(opcional)* muestra/embebe el hash de nacimiento (v1). **Conveniencia, no verdad.** |
+| **Implementar** | `link-us` → invoca `dai ac-hash` | estampa en `implements.yaml` el hash que el CÓMO **declara** implementar. |
+| **Verificar** | CI / indexador → `dai ac-hash` sobre la US **viva** | re-deriva y **compara** con `implements.yaml`. Distinto → ⚠️ atrasado. |
+
+**La única fuente de verdad de la detección es el tercer momento**: el CI re-deriva el
+hash leyendo la US como está *ahora*, no una copia estampada en el pasado. Los otros
+dos son declaraciones/cortesías.
+
+### El artefacto-QUÉ (matiz de niveles)
+
+La detección exige un **artefacto-QUÉ con identidad estable y criterios testeables**,
+no necesariamente una US publicada en un tracker. En N3/N2 es la US en Jira/ClickUp;
+en N1 es el `proposal.md` de OpenSpec (los niveles de ceremonia N1/N2/N3 — dev solo /
+equipo compacto / organización grande — están en el [glosario](../glosario.md)). El `ac_hash` se calcula igual sobre cualquiera
+de los tres — no forzamos tracker externo donde el Art. 14 dice no adelantar
+complejidad.
+
+## Consecuencias
+
+- ✅ El versionado deja de ser decorativo: los atrasos se detectan solos.
+- ✅ Cambios editoriales (typos, reformatos) **no** disparan falsos atrasos.
+- ✅ Una edición manual de la US en Jira **sí** se detecta, porque el CI re-deriva del
+  vivo — no depende de que alguien vuelva a correr una skill.
+- ⚠️ La **normalización** es crítica: una sola implementación (`dai ac-hash`), y el CI
+  debe usar exactamente ese binario/lógica, nunca reimplementarlo. Es lo más testeado.
+- ⚠️ Reordenar criterios **sí** cambia el hash — por eso el formato de US pide orden
+  estable. Es una obligación nueva para el PO.
+- ⚠️ El CI necesita **leer la US viva** (API de Jira/ClickUp o el `.md`) para
+  re-derivar. Ese es el punto donde el link toca la distribución (ver METODOLOGIA §7).
+
+## Alternativas consideradas
+
+- **Calcular el hash en `grill-user-story` al publicar (una vez)** — descartado: la US
+  muta después, fuera de la skill; el hash estampado quedaría stale y la detección se
+  rompería en silencio. La skill puede *invocar* `dai ac-hash` como cortesía, pero no
+  es la autoridad.
+- **Que la skill (LLM) compute el hash** — descartado: no determinista, daría distinto
+  al CI. Lo mecánico va al CLI (ADR-0002).
+- **Hash del texto crudo (sin normalizar)** — descartado: cualquier typo dispararía un
+  falso atraso, y el ruido mataría la confianza en el ⚠️.
+- **Solo `spec_version` manual, sin hash** — descartado: depende de que la persona se
+  acuerde de bumpear; el hash detecta aunque se olvide (el número comunica, el hash
+  detecta).