@dforce2055/dai 0.1.0

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

@@ -0,0 +1,34 @@
+# Paso 6 — Code review: el dev primero, después un partner
+
+← vuelve a [`SCRUM-CON-IA.md`](../SCRUM-CON-IA.md)
+
+## En qué consiste en detalle
+
+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.
+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.
+
+## Herramientas
+
+- Skill [`dai-review`](../../skills/dai-review/SKILL.md) — GitHub y GitLab, postea por
+  MCP del forge o por `dai forge comment` (token).
+- `dai check` ([ADR-0003](../adr/0003-deteccion-y-estampado-son-comandos.md)).
+- Gate de cierre: [`definition-of-done.md`](../../templates/definition-of-done.md).
+
+## Qué firma el humano
+
+El **partner aprueba o rechaza** ([Art. 5](../MANIFIESTO.md#art-5)). La IA comenta y sugiere; **nunca** firma
+la aprobación.
+
+## Antipatrones
+
+- **Rubber-stamp** ("LGTM" sin leer) → el review deja de valer.
+- **Que la IA "apruebe"** → prohibido; aprueba una persona.
+- **Hallazgos abstractos** ("mejorar la calidad") → sin archivo:línea, no es accionable.
+- **Aprobar con `dai check` en ⚠️ atrasado** → se implementó una versión vieja del QUÉ.

package/docs/detalle/07-merge-trazabilidad.md

@@ -0,0 +1,33 @@
+# Paso 7 — Merge: la trazabilidad se estampa sola
+
+← vuelve a [`SCRUM-CON-IA.md`](../SCRUM-CON-IA.md)
+
+## En qué consiste en detalle
+
+Al mergear se corre `dai stamp` (el dev en modo distribuido, o el CI si está
+automatizado — [ADR-0003](../adr/0003-deteccion-y-estampado-son-comandos.md)). Lee el
+`implements.yaml`, compara el hash estampado contra la US viva, y **escribe la
+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)
+```
+
+## Herramientas
+
+- `dai check` / `dai stamp` — mismos comandos los corra un humano o el CI.
+- Contenido del stamp: [ADR-0005](../adr/0005-superficie-comandos-y-stamp.md).
+
+## Qué firma el humano
+
+**Nadie mantiene la matriz a mano** — ese es el punto ([Art. 10](../MANIFIESTO.md#art-10)). El humano a lo sumo
+*dispara* `dai stamp`; el contenido lo deriva la máquina.
+
+## Antipatrones
+
+- **Actualizar el estado del ticket a mano** → desincronización garantizada.
+- **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

@@ -0,0 +1,29 @@
+# Paso 8 — Daily standup (humano, a propósito)
+
+← vuelve a [`SCRUM-CON-IA.md`](../SCRUM-CON-IA.md)
+
+## En qué consiste en detalle
+
+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á
+
+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
+verdad. Automatizarlo le sacaría al equipo la propiedad del ritual ([Art. 6](../MANIFIESTO.md#art-6)).
+
+## Qué firma el humano
+
+Todo. La conversación *es* el valor.
+
+## Dónde sí ayuda la máquina (sin reemplazar el ritual)
+
+Si alguien quiere datos frescos para el daily, `dai ls` / `dai check` muestran en qué
+está cada quien y qué quedó atrasado — como **insumo**, no como reemplazo de la charla.
+
+## Antipatrones
+
+- **Convertirlo en reporte** hacia arriba → deja de ser sincronización.
+- **Automatizar el "qué hice"** → mata la apropiación (por eso es HITL).
+- **Que dure 40 minutos** → no es la reunión de diseño; para eso, otro espacio.

package/docs/detalle/09-review.md

@@ -0,0 +1,25 @@
+# Paso 9 — Sprint Review / Demo
+
+← vuelve a [`SCRUM-CON-IA.md`](../SCRUM-CON-IA.md)
+
+## En qué consiste en detalle
+
+Se muestra lo terminado al PO y stakeholders. La aceptación es **contra los criterios
+de aceptación de la US** — que ya eran tests (paso 4). Si el QUÉ evolucionó mientras
+tanto, el `@version` lo gritó antes (`dai check` en ⚠️), así que **no hay sorpresas**
+del tipo "esto no era lo que pide".
+
+## Herramientas
+
+- Los criterios Gherkin de la US como guion de la demo.
+- `dai check` para confirmar que lo demostrado está **al día** con la US vigente.
+
+## Qué firma el humano
+
+El **PO acepta o rechaza** ([Art. 5](../MANIFIESTO.md#art-5)). La demo la corre una persona.
+
+## Antipatrones
+
+- **Demostrar contra una US atrasada** → aceptas algo que ya no es lo pedido.
+- **Criterios que no eran tests** → la demo se vuelve subjetiva ("a mí me anda").
+- **Descubrir el desajuste en la demo** → tenía que haber saltado con `dai check` antes.

package/docs/detalle/10-retro.md

@@ -0,0 +1,27 @@
+# Paso 10 — Retrospective (humano, con datos)
+
+← vuelve a [`SCRUM-CON-IA.md`](../SCRUM-CON-IA.md)
+
+## En qué consiste en detalle
+
+El equipo mira **cómo trabajó** (no el producto) y elige **1–2 mejoras** para el
+próximo sprint. Es un ritual **humano**. Lo que aporta la máquina son **datos**, no
+conclusiones.
+
+## Dónde ayuda la máquina
+
+La matriz de trazabilidad y las métricas de las US dan evidencia real de dónde se
+trabó el flujo: US que quedaron atrasadas seguido, pasos que siempre se hacen a mano,
+smokes que faltan. `dai ls` / `dai check` sobre los repos son un buen insumo.
+
+## Qué firma el humano
+
+Todo el análisis y las decisiones de mejora. La IA no propone la mejora; el equipo la
+decide con los datos a la vista ([Art. 6](../MANIFIESTO.md#art-6)).
+
+## Antipatrones
+
+- **Mejorar "la sensación"** sin datos → la matriz existe justo para evitar eso.
+- **Automatizar la retro** → es humana, como el daily.
+- **Salir con 10 acciones** → 1–2 mejoras reales valen más que una lista que nadie hace.
+- **No cerrar el loop** → la mejora del sprint pasado debería verse en los datos de este.

package/docs/detalle/README.md

@@ -0,0 +1,20 @@
+# Detalle por paso — la ceremonia con IA, ampliada
+
+El zoom de cada uno de los 10 pasos de [`SCRUM-CON-IA.md`](../SCRUM-CON-IA.md). Cada
+archivo: en qué consiste en detalle, la herramienta con ejemplos, qué firma la persona (HITL) y
+los antipatrones a evitar.
+
+| # | Paso | IA |
+|---|---|---|
+| [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) | ●●● |
+| [05](05-smoke.md) | Smoke end-to-end | ●● |
+| [06](06-code-review.md) | Code review (IA + partner) | ●● |
+| [07](07-merge-trazabilidad.md) | Merge + trazabilidad | ●●● |
+| [08](08-daily.md) | Daily (**humano**) | ○ |
+| [09](09-review.md) | Review / Demo | ● |
+| [10](10-retro.md) | Retro (**humano**) | ○ |
+
+`●●● = la IA hace el trabajo pesado` · `○ = humano puro (HITL)`

package/docs/glosario.md

@@ -0,0 +1,79 @@
+# Glosario — el vocabulario común de dai
+
+> Si el equipo no nombra las cosas igual, no puede razonar junto. Este es el
+> vocabulario **del método**. Cada proyecto además mantiene su **glosario de
+> dominio** (los términos del negocio) — son cosas distintas: este define *cómo
+> trabajamos*, el otro define *sobre qué*.
+
+## Los dos lados
+
+| Término | Qué es |
+|---|---|
+| **QUÉ** | El requerimiento funcional: qué hay que hacer y por qué. Dueño: PO/funcional. |
+| **CÓMO** | La implementación técnica: cómo se construye. Dueño: dev/ingeniero. |
+| **US (User Story)** | La unidad del QUÉ. Formato canónico en `templates/formato-us.md`. |
+| **Criterio de aceptación (AC)** | Condición testeable en Gherkin (Dado/Cuando/Entonces). Si no es un test en potencia, no es un AC. |
+| **Capacidad** | La unidad de linkeo: una US entera. El link es a este nivel, no por AC. |
+
+## El link y la trazabilidad
+
+| Término | Qué es |
+|---|---|
+| **Link (QUÉ↔CÓMO)** | La relación entre un requerimiento y su implementación. |
+| **`implements`** | La declaración `implements: <id>@<version>` en el código. El **único** link autorado a mano. |
+| **`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.)* |
+| **Matriz de trazabilidad** | La vista "repo × versión × estado (al día / atrasado)". Derivada, no mantenida a mano. |
+
+## El versionado
+
+| Término | Qué es |
+|---|---|
+| **`spec_version`** | Número legible (`v1`, `v2`…). Lo sube la persona para **comunicar** un cambio del QUÉ. |
+| **`ac_hash`** | Hash del bloque de criterios normalizado. Lo calcula la máquina para **detectar** cambios. |
+| **`@version`** | El par `spec_version + ac_hash`. Lo que hace que un cambio del QUÉ marque solo a los CÓMO atrasados. |
+| **Atrasado (⚠️)** | Un CÓMO cuyo `ac_hash` ya no coincide con el de la US vigente. |
+
+## El proceso
+
+| Término | Qué es |
+|---|---|
+| **Gate 0** | El desafío al *problema* antes de escribir spec (`grill-intent`). Puede terminar en "no lo construyas". |
+| **DoR (Definition of Ready)** | El contrato de cuándo una US puede entrar a implementarse. |
+| **DoD (Definition of Done)** | El contrato de cuándo el CÓMO está terminado. |
+| **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. |
+| **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ó. |
+
+## La maquinaria (CI/CD)
+
+| 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). |
+| **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. |
+
+## Los principios
+
+| Término | Qué es |
+|---|---|
+| **Artículos (Art. N) / Manifiesto** | Cuando un doc cita "Art. 10" o "Art. 14", se refiere a uno de los **15 artículos** de la constitución del método, en [MANIFIESTO.md](MANIFIESTO.md). Cada `Art. N` linkea directo a su regla (`#art-N`). Son cortos a propósito — un manifiesto que no se cita de memoria no gobierna nada. |
+| **SDD (Spec-Driven Development)** | El paradigma donde la **especificación maneja el código**, no al revés: primero el QUÉ (US) y el diseño, después la implementación. dai —con OpenSpec— es SDD; lo opuesto al *code-first* y al vibe coding. |
+| **PRD / SRS** | El documento monolítico de requisitos (*Product Requirements Document* / *Software Requirements Specification*). **dai no usa uno**: descompone el QUÉ en épica + US testeables (unidades linkeables y hasheables). Si ya tienes un PRD, `doc-to-backlog` lo **ingiere** y lo vuelve backlog — dai consume el documento, no te obliga a mantenerlo. |
+| **HITL (Human-in-the-loop)** | La IA asiste; la persona decide y firma. Los rituales de coordinación son humanos. |
+| **Vibe coding** | Improvisar código sobre una idea vaga. Lo que el método prohíbe ([Art. 7](./MANIFIESTO.md#art-7)). |
+| **Colapso de roles** | Cuando una persona es PO y dev: los gates se aligeran, el link no desaparece. |
+| **Nivel de ceremonia (N1/N2/N3)** | Los tres niveles de "plomería" según el tamaño del equipo. **N1** — un dev solo, todo local, sin herramientas externas. **N2** — equipo compacto, con tracker (Jira/ClickUp) + `implements.yaml`. **N3** — organización grande, federada: muchos repos, equipos separados, CI que estampa. El protocolo QUÉ↔CÓMO es **el mismo** en los tres; solo cambia la maquinaria. Detalle en [METODOLOGIA §3](METODOLOGIA.md). |
+
+## Los roles
+
+| Término | Qué es |
+|---|---|
+| **PO / funcional** | Dueño del QUÉ. Ver `guias/po.md`. |
+| **Dev / ingeniero** | Dueño del CÓMO y del link. Ver `guias/dev.md`. |
+| **Lead / SM / arquitecto** | Custodio de las invariantes y del nivel de ceremonia. Ver `guias/lead.md`. |

package/docs/guias/dev.md

@@ -0,0 +1,66 @@
+# Guía del dev / ingeniero
+
+> Tu trabajo en una frase: **defines e implementas el CÓMO, y autoras el link al QUÉ.**
+> El QUÉ ya viene definido y testeable — tú no lo re-discutes, lo implementas.
+
+## Lo que eres dueño
+
+- El **CÓMO**: diseño técnico, modelo de datos, arquitectura de la solución.
+- Las **tareas técnicas** (las derivas tú, desde la US, con OpenSpec).
+- El **link** (`implements.yaml`): es el **único** que se autora a mano ([Art. 9](../MANIFIESTO.md#art-9)).
+- El **código** y su **spec técnica**.
+
+## Lo que NO tocas
+
+- El contenido funcional de la US ni sus criterios → eso es del PO (Art. 1).
+- Si te parece que el QUÉ está mal, **no lo corrijas por tu cuenta**: devuelve la US
+  al PO (reframe). No decidas negocio desde el código.
+
+## 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
+   `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).
+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**
+   (anti vibe-coding). Ajustas y **commiteas** lo que haga falta.
+6. **Creas la PR** → con el smoke verde y **todo commiteado** (lo que quede sin commitear
+   **no entra** en la PR), corres `dai check` (gate: ¿al día con la US?) y en verde `dai pr`
+   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.
+   *(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).
+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.
+
+## 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
+—US clara → design → test → código— es lo que separa esto de pedirle cosas a un chat.
+
+## Cuando el QUÉ cambia
+
+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).
+
+## Tus herramientas
+
+- `/link-us`
+- `/opsx:explore`
+- `/opsx:propose`
+- `/opsx:apply`
+- `/tdd`
+- `/dai-review`
+- `dai check` · `dai pr` · `dai stamp` · `dai done` (limpieza, opcional)
+- `definition-of-done.md`

package/docs/guias/lead.md

@@ -0,0 +1,53 @@
+# Guía del lead / Scrum Master / arquitecto
+
+> Tu trabajo en una frase: **custodias las invariantes y eliges cuánta ceremonia
+> corre el equipo.** No haces el QUÉ ni el CÓMO — haces que el método se cumpla y
+> se aligere donde corresponde.
+
+## Lo que eres dueño
+
+- **El manifiesto** (`MANIFIESTO.md`): eres el guardián de los 15 artículos. Se
+  enmiendan solo por ADR explícito, nunca en silencio por presión de sprint.
+- **Los ADRs**: registras cada decisión de fondo (las decisiones abiertas de la
+  metodología, la calibración de [DoR](../../templates/definition-of-ready.md)/[DoD](../../templates/definition-of-done.md), la convención de escritura en el gestor).
+- **La calibración del nivel** (N1 / N2 / N3): eliges cuánta plomería corre el
+  equipo, y la subes **solo cuando duele**, no por las dudas ([Art. 14](../MANIFIESTO.md#art-14)).
+- **El governance**: naming de ramas, reglas de CI (`governance/`).
+- **La facilitación** del daily y la retro — que son **humanos a propósito** (Art. 6).
+
+## Lo que NO haces
+
+- No defines el QUÉ por el PO ni el CÓMO por los devs.
+- No conviertes el daily/retro en un reporte automatizado: sacarle al equipo la
+  propiedad del ritual rompe la apropiación (Art. 6).
+
+## Tus decisiones clave
+
+### 1. ¿En qué nivel arranca 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).
+
+Empieza en el más chico que funcione. Sube de nivel cuando el dolor lo justifique.
+
+### 2. ¿Cómo calibras [DoR](../../templates/definition-of-ready.md) y [DoD](../../templates/definition-of-done.md)?
+Ajustas los checklists (`templates/definition-of-*.md`) a tu realidad, **sin tocar
+las invariantes**: criterios testeables (Art. 3), el link autorado una vez (Art. 9)
+y la trazabilidad derivada (Art. 10) no se aflojan en ningún nivel.
+
+### 3. ¿Cuándo se colapsan los roles?
+En equipos chicos una persona es PO y dev. Aligeras los gates (auto-check honesto en
+vez de la firma de otro) **pero el link sigue existiendo** (Art. 15).
+
+## La trampa a evitar
+
+**Adelantar complejidad.** Montar la maquinaria de N3 en un equipo de 3 personas es
+tan dañino como no tener método: agrega fricción sin resolver un dolor real (Art. 14).
+
+## Tus herramientas
+
+- `MANIFIESTO.md`
+- [`METODOLOGIA.md`](../METODOLOGIA.md) (el dial de niveles)
+- `governance/`
+- los ADRs
+- la retro

package/docs/guias/po.md

@@ -0,0 +1,50 @@
+# Guía del PO / funcional
+
+> Tu trabajo en una frase: **defines el QUÉ y el porqué. Nunca el CÓMO.**
+> Trabajas donde ya trabajas (el gestor de proyectos), nunca entras al código.
+
+## Lo que eres dueño
+
+- El **contenido funcional** de cada US: el problema, el usuario, el valor.
+- Los **criterios de aceptación** (qué tiene que cumplirse para aceptar).
+- La **prioridad** y el **spec_version** (subes la versión cuando el QUÉ cambia).
+- La **aceptación** en la demo.
+
+## Lo que NO tocas
+
+- Tablas, endpoints, framework, arquitectura → eso es el CÓMO, del dev.
+- El código, las ramas, el `implements.yaml`.
+- El "cómo se construye". Si te metes ahí, detente: no es tu terreno ([Art. 1](../MANIFIESTO.md#art-1)).
+
+## 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
+   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.
+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.
+
+## La trampa a evitar
+
+**Criterios no testeables.** *"El usuario tiene una buena experiencia"* no es un
+criterio: no se puede volver un test. La skill te va a frenar ahí — déjala. Un buen
+criterio es *"un carrito vacío no se puede finalizar"* (Art. 3).
+
+## Lo que ganas
+
+Cuando cambias el QUÉ (subes a `v2`), **todos los repos que implementaron la versión
+vieja se marcan atrasados solos**. No tienes que perseguir a nadie: el `@version` lo
+grita (Art. 11). Y ves en el ticket quién ya lo implementó, sin preguntar — lo puso
+el CI (Art. 10).
+
+## Tus herramientas
+
+- `/grill-intent`
+- `/grill-user-story`
+- el gestor de proyectos
+- [`definition-of-ready.md`](../../templates/definition-of-ready.md)

package/governance/branch-naming.md

@@ -0,0 +1,36 @@
+# Convención de naming de ramas
+
+> El nombre de la rama **es** el primer eslabón del link. Si es inconsistente, la
+> trazabilidad se rompe desde el commit uno. Por eso lo genera `link-us`, no la mano.
+
+## El formato
+
+```
+feature/ABC-###-<slug>
+└──┬──┘ └──┬───┘ └─┬─┘
+   │       │       └ título de la US, minúsculas, sin acentos, guiones como separador
+   │       └ ID de la US en el gestor (identidad estable del QUÉ)
+   └ tipo de rama
+```
+
+Ejemplo: `feature/ABC-482-finalizar-compra-sin-duplicado`
+
+## Reglas
+
+- El **ID nunca se tipea a mano**: sale del argumento de `/link-us ABC-###`. Elimina
+  el error de tipeo que rompe el link ([Art. 8](../docs/MANIFIESTO.md#art-8), Art. 9).
+- El **slug** deriva del título de la US: minúsculas, sin acentos ni ñ, espacios → `-`.
+- La **base** de la rama sigue la convención del repo (`main` o `develop`).
+- Una rama, una US. Si una US toca varios repos, es una rama por repo, **todas con el
+  mismo `ABC-###`** — así el índice las agrupa en una fila (federación).
+
+## Tipos de rama (opcional, por repo)
+
+| Prefijo | Para |
+|---|---|
+| `feature/` | nueva capacidad (el caso por defecto) |
+| `fix/` | corrección sobre una US ya implementada |
+| `chore/` | trabajo sin US (tooling, deps) — sin `implements`, no cuenta para cobertura |
+
+> Regla de oro: si la rama implementa una US, **su nombre lleva el ID** y existe
+> `implements.yaml`. Si no lleva ID, no es trabajo de producto y el CI no le exige link.

package/governance/ci-rules.md

@@ -0,0 +1,57 @@
+# Reglas de CI — enforcement, no vigilancia
+
+> El método no depende de que la gente "se acuerde". Lo blinda un check: valida el
+> link en cada PR y estampa la cobertura al mergear. La disciplina la sostiene la
+> máquina, no la buena voluntad.
+>
+> **El "CI" no es infraestructura obligatoria (ADR-0003).** Todo lo de acá abajo son
+> los comandos `dai check` (read-only, gate) y `dai stamp` (write, cobertura),
+> corridos por un dev en modo distribuido **o** por el pipeline que la org ya tenga.
+> El tracker solo guarda la US; no ejecuta nada. Un equipo sin CI usa los mismos
+> comandos a mano (o por git-hook) y tiene la misma trazabilidad.
+
+## Qué valida el CI en cada PR/MR
+
+| Check | Regla | Si falla |
+|---|---|---|
+| **Link presente** | Toda rama de producto (`feature/ABC-###-*`) tiene `implements.yaml`. | ❌ bloquea el PR |
+| **ID válido** | El `id` matchea el formato del gestor (`ABC-\d+`) y el ID existe. | ❌ bloquea |
+| **`ac_hash` calculado** | El CI (re)calcula el hash de los criterios de la US y lo compara. | ⚠️ marca atrasado si no coincide |
+| **Tests verdes** | La suite de la US pasa. | ❌ bloquea |
+| **Estándares** | Lint + tipos + convenciones del repo. | ❌ bloquea |
+
+> Ramas `chore/`/`fix/` sin US no requieren `implements.yaml` (ver `branch-naming.md`).
+
+## Qué hace el CI al mergear
+
+1. **Lee** el `implements.yaml` de la rama.
+2. **Estampa la cobertura inversa** en el gestor: en el ticket `ABC-###`, deja
+   "implementado por `<repo>` @ `<version>` (`ac_hash`) ✅". **Nadie lo escribe a
+   mano** ([Art. 10](../docs/MANIFIESTO.md#art-10)).
+3. **Actualiza el índice/router central** de la federación: la fila `ABC-### → { repos }`.
+
+## Qué hace el CD al desplegar (solo N3 · organización grande)
+
+Reporta a qué **ambiente** llegó la versión (`dev` / `test` / `pre` / `prod`), para
+armar la matriz **repo × ambiente**. Implementación ≠ despliegue: el CI dice "se
+implementó `@v3`", el CD dice "`@v3` está viva en `pre`".
+
+## Cómo se calcula el `ac_hash` (contrato)
+
+> Decisión abierta de la metodología — este es el contrato propuesto, a congelar en un ADR.
+
+1. Tomar el bloque **Criterios de aceptación** de la US vigente.
+2. **Normalizar**: colapsar whitespace, orden estable de los AC, quitar marcado
+   editorial (viñetas, énfasis). El objetivo: que un typo **no** dispare un falso atraso.
+3. Hashear el resultado normalizado (p. ej. SHA-256, truncado para legibilidad).
+4. Comparar con el `ac_hash` del `implements.yaml`. Distinto → el repo está atrasado.
+
+## Calibración por nivel
+
+> **N1 / N2 / N3** son los niveles de ceremonia según el tamaño del equipo — **N1**
+> un dev solo, **N2** equipo compacto (con tracker), **N3** organización grande
+> (federada). Ver el [glosario](../docs/glosario.md) o [METODOLOGIA §3](../docs/METODOLOGIA.md).
+
+- **N1** (dev solo)**:** sin CI. La validación es un comando local (`dai` puede ofrecer un pre-commit).
+- **N2** (equipo compacto)**:** CI liviano — valida link + tests, estampa en el gestor si hay adaptador.
+- **N3** (organización grande)**:** CI completo + CD reportando ambientes + índice central publicado.

package/governance/commit-convention.md

@@ -0,0 +1,76 @@
+# Convención de commits — el CÓMO, en pasos legibles
+
+> Un commit es el **paso atómico del CÓMO**. Si el historial se lee, la implementación
+> se entiende sin abrir el diff. Esta convención lo vuelve mecánico — y un hook la
+> blinda, sin depender de que nadie "se acuerde" (mismo espíritu que [`ci-rules.md`](ci-rules.md)).
+
+## Formato
+
+```
+<tipo>(<scope>)!: <resumen>
+
+<cuerpo opcional>
+```
+
+- **tipo** — obligatorio (ver tabla).
+- **scope** — opcional, en minúscula: el módulo o área (`cart`, `auth`, `cli`).
+- **`!`** — opcional, marca un **breaking change** (rompe un contrato).
+- **resumen** — en **imperativo**, minúscula, **sin punto final**, hasta **72** caracteres.
+  "rechaza el carrito vacío", no "Rechazado" ni "se rechaza el carrito".
+- **cuerpo** — opcional: el *por qué*, no el *qué* (el diff ya dice el qué).
+
+| Tipo | Cuándo |
+|---|---|
+| `feat` | nueva funcionalidad |
+| `fix` | corrección de un bug |
+| `docs` | solo documentación |
+| `style` | formato (espacios, comas) sin cambio de comportamiento |
+| `refactor` | reescritura sin feature ni fix |
+| `perf` | mejora de rendimiento |
+| `test` | agrega o corrige tests |
+| `build` | sistema de build o dependencias |
+| `ci` | pipeline de CI/CD |
+| `chore` | mantenimiento (nada de lo anterior) |
+| `revert` | revierte un commit previo |
+
+Se dejan pasar sin validar: `Merge …`, `Revert …`, `fixup!`/`squash!` y commits de bots (`🤖…`).
+
+## Relación con la trazabilidad
+
+El link formal QUÉ↔CÓMO vive en el `implements.yaml` (no en el mensaje del commit). Pero si
+el commit implementa una US, **mencionarla en el cuerpo** hace el historial legible:
+
+```
+feat(cart): rechaza finalizar un carrito vacío
+
+Cubre el criterio AC-2. US: ABC-482.
+```
+
+No es obligatorio y **no** reemplaza al `implements.yaml` — es una ayuda de lectura.
+
+## Cómo instalar el hook
+
+El template [`templates/commit-msg`](../templates/commit-msg) es POSIX sh **sin dependencias**
+(no necesita dai, node ni commitlint). Elige según tu repo:
+
+**Con [husky](https://typicode.github.io/husky/) (si ya lo usas):**
+```bash
+cp templates/commit-msg .husky/commit-msg && chmod +x .husky/commit-msg
+```
+
+**Git hook pelado (sin herramientas):**
+```bash
+cp templates/commit-msg .git/hooks/commit-msg && chmod +x .git/hooks/commit-msg
+```
+
+Para compartirlo con el equipo sin husky, versiona los hooks en el repo y apunta git ahí:
+```bash
+mkdir -p .githooks && cp templates/commit-msg .githooks/ && chmod +x .githooks/commit-msg
+git config core.hooksPath .githooks
+```
+
+## Opt-in ([Art. 14](../docs/MANIFIESTO.md#art-14) — no adelantar complejidad)
+
+El hook es **opcional**. Un equipo chico puede seguir la convención a mano; uno grande la
+blinda con el hook y/o el CI. La convención es la misma en cualquier nivel de ceremonia
+(N1/N2/N3 — ver [glosario](../docs/glosario.md)); solo cambia cuánto se automatiza.