@dforce2055/dai 0.1.0

package/docs/adr/0002-agnostico-del-asistente.md

@@ -0,0 +1,87 @@
+# ADR-0002 — La metodología es agnóstica del asistente de IA
+
+- **Estado:** aceptado
+- **Fecha:** 2026-07-03
+- **Decide:** lead / arquitecto de la metodología
+
+## Contexto
+
+Las skills están hoy empaquetadas como **skills de Claude Code** (`SKILL.md` en
+`.claude/skills/`). Pero los equipos usan asistentes distintos: una organización usa
+**GitHub Copilot** (nadie usa Claude), otra usa **Claude Code**. Si atamos la
+metodología a un asistente, dejamos afuera a media empresa — y contradecimos el
+principio rector "sin importar la herramienta de abajo" ([Art. 2](../MANIFIESTO.md#art-2)), que ya aplicamos a
+las herramientas de spec (OpenSpec/Swagger/yml). Falta aplicarlo **una capa más
+arriba**: el asistente de IA.
+
+## Decisión
+
+Aplicamos el mismo principio al asistente. Una "skill" se separa en tres capas:
+
+1. **Contenido portable** — la lógica de interrogación, el formato, los cortes. Se
+   escribe **una sola vez**, neutral al asistente. Es la fuente de verdad.
+2. **Acciones deterministas = CLI `dai`** — todo lo mecánico (crear rama,
+   generar `implements.yaml`, calcular `ac_hash`, indexar cobertura) vive en el
+   **CLI**, no en la inteligencia del asistente. `dai link-us ABC-###` anda igual
+   con Claude, con Copilot, o sin ningún asistente. Es la forma más agnóstica de
+   garantizar comportamiento determinista: el asistente solo lo **invoca**.
+3. **Adaptadores por asistente (delgados, generados)** — de la Capa 1 se emiten los
+   wrappers finos de cada asistente:
+   - **Claude Code** → `SKILL.md` en `.claude/skills/`.
+   - **Copilot** → `.github/prompts/*.prompt.md` + `.github/copilot-instructions.md`
+     (este último auto-inyecta el manifiesto en cada chat del repo).
+
+El instalador elige el target: `dai init --for claude` | `--for copilot` | `--for both`.
+Mismo método, misma CLI, distinto wrapper. **`--for` es aditivo, no destructivo**: los
+adaptadores coexisten en el mismo repo (viven en carpetas distintas —
+`.claude/skills/` y `.github/prompts/`— y no se pisan). Un equipo mixto (unos con
+Copilot, otros con Claude) versiona los dos y cada quien usa el suyo. Como lo mecánico
+vive en el CLI, el **output es idéntico** sin importar qué asistente lo disparó: misma
+rama, mismo `implements.yaml`, mismo `ac_hash`. El repo queda consistente aunque el
+equipo esté mezclado.
+
+| Capacidad | Naturaleza | Claude Code | Copilot |
+|---|---|---|---|
+| `grill-intent`, `grill-user-story` | interrogación (prompt puro) | `SKILL.md` | `*.prompt.md` |
+| `link-us`, `ac-hash`, `coverage` | acción mecánica | wrapper → `dai <cmd>` | prompt/CLI → `dai <cmd>` |
+| el manifiesto y las reglas | contexto siempre presente | `CLAUDE.md` / `project.md` | `.github/copilot-instructions.md` |
+
+## Consecuencias
+
+- ✅ La misma metodología corre en una organización con Copilot y en una factory con
+  Claude — "un protocolo, distinta plomería" aplicado al asistente.
+- ✅ Lo mecánico se vuelve **más confiable**: un CLI determinista no alucina.
+- ✅ Los docs (`MANIFIESTO`, `METODOLOGIA`, guías, glosario) ya eran 100% agnósticos:
+  la dualidad solo toca la capa `skills/`.
+- ⚠️ Hay que **construir el CLI `dai`** con los subcomandos mecánicos (hoy esa lógica
+  está descrita dentro de las skills de Claude). Es trabajo nuevo.
+- ⚠️ Las capacidades de agente difieren: los prompts puros portan limpio; las
+  acciones se apoyan en el CLI. Copilot en modo agente puede correr el CLI; en modo
+  chat, el dev lo corre a mano.
+- ⚠️ **Límite de superficie de Copilot (verificado):** los `.github/prompts/*.prompt.md`
+  se invocan **solo en VS Code / Visual Studio / JetBrains** (o, como custom agents, en
+  el **Copilot CLI**). **No** en la app standalone de Copilot ni en el chat de
+  github.com. Claude, en cambio, lee `~/.claude/skills/` tanto en **Claude Code** como
+  en **Claude Desktop**. Consecuencia: el analista funcional "sin IDE" cierra con Claude
+  Desktop; con Copilot necesita VS Code o el Copilot CLI. Es un límite de Copilot, no de
+  dai — el CLI `dai` corre igual en cualquier terminal.
+- ⚠️ Los wrappers se **generan**, no se mantienen a mano — si no, se desincronizan (la misma
+  regla de oro del link).
+
+**Estado de implementación:** `dai init` es un **scaffolder interactivo** (estilo
+`create-vue`): pregunta asistente (`--for claude|copilot|both`) y gestor
+(`--pm md|clickup|jira`), genera los adaptadores (`.claude/skills/` + `CLAUDE.md`;
+`.github/prompts/*.prompt.md` + `.github/copilot-instructions.md`, transformando los
+`SKILL.md` con `cli/lib/bootstrap.mjs`), deja un `.env` configurado, y cierra con
+próximos pasos. **OpenSpec:** se detecta; si falta, se **ofrece instalarlo**
+(`npm i -g @fission-ai/openspec@latest` + `openspec init`) — no se bundlea (Art. 2).
+Con flags o sin TTY corre no-interactivo (defaults `both`/`md`, OpenSpec solo con `--openspec`).
+
+## Alternativas consideradas
+
+- **Mantener skills separadas por asistente a mano** — descartado: desincronización garantizada
+  al primer cambio (viola Art. 9/Art. 10 aplicados al propio paquete).
+- **Atarse solo a Claude** — descartado: deja afuera a la organización que usa
+  Copilot, que es justo uno de los dos casos que el método debe soportar.
+- **Meter toda la lógica mecánica en el asistente (sin CLI)** — descartado: no es
+  portable y es menos confiable (el asistente puede alucinar un paso determinista).

package/docs/adr/0003-deteccion-y-estampado-son-comandos.md

@@ -0,0 +1,73 @@
+# ADR-0003 — La detección y el estampado son comandos, no infraestructura
+
+- **Estado:** aceptado
+- **Fecha:** 2026-07-03
+- **Decide:** lead / arquitecto de la metodología
+
+## Contexto
+
+El ADR-0001 dice que la **autoridad** de la detección de atrasos es "el CI, que
+re-deriva el `ac_hash` de la US viva y compara". Leído literal, suena a que hace
+falta **montar un CI que corra del lado de Jira/ClickUp** antes de poder usar la
+metodología — infraestructura pesada, y una barrera de entrada que contradice el
+[Art. 14](../MANIFIESTO.md#art-14) (*no adelantar complejidad*).
+
+Además, un equipo que ya está en escala N3 (organización grande federada; los niveles
+N1/N2/N3 están en el [glosario](../glosario.md)) puede **no tener** todavía esa
+automatización. La trazabilidad federada tiene que funcionar igual, de forma
+**distribuida**, sin depender de que exista un pipeline corriendo.
+
+El malentendido está en la palabra "CI". Jira/ClickUp **no ejecutan** nada: solo
+**guardan** la US. La detección es comparar dos hashes — eso es un **comando**, no
+un servidor.
+
+## Decisión
+
+La trazabilidad se expone como **comandos del CLI `dai`**, invocables por un humano
+o por un CI indistintamente (mismo binario, mismo output — ADR-0002):
+
+| Comando | Naturaleza | Qué hace |
+|---|---|---|
+| `dai ac-hash <us>` | puro | calcula el hash de los criterios (ADR-0001). |
+| `dai check` | **read-only** | lee el `implements.yaml` del repo + la US viva, re-deriva el hash y **compara**. Reporta al día / ⚠️ atrasado. Exit code ≠ 0 si hay atraso → sirve de **gate de PR**. **No escribe nada.** |
+| `dai stamp` | **write** | calcula la cobertura derivada y la **escribe en el tracker** (la trazabilidad inversa del Art. 10: "`<repo>` @ `<version>` ✅/⚠️"). Requiere token de escritura. |
+
+**El tracker solo almacena y sirve la US.** La lógica corre donde se invoca el
+comando: la máquina del dev, un git-hook, o un pipeline.
+
+### Modo distribuido (sin infraestructura) vs automático
+
+- **Distribuido (default, N1–N2 y N3 sin CI):** el dev corre `dai check` cuando
+  quiere saber si está atrasado, y `dai stamp` después de mergear para publicar su
+  cobertura. **Cero infraestructura nueva.** Depende de disciplina (alguien tiene
+  que correr `dai stamp`), mitigable con un git-hook local.
+- **Automático (N3 maduro):** el CI que la organización **ya tiene** corre
+  `dai check` como gate y `dai stamp` al mergear. La automatización es, literalmente,
+  *"correr los mismos comandos en un hook"* — no hay un código distinto.
+
+Pasar de distribuido a automático es mover la invocación, no reescribir nada.
+
+## Consecuencias
+
+- ✅ **No hace falta ningún CI para empezar.** La metodología arranca con un dev
+  tipeando `dai check` / `dai stamp`. El [Art. 14](../MANIFIESTO.md#art-14) queda respetado.
+- ✅ **Rampa de adopción continua:** manual → git-hook → CI, siempre el mismo comando.
+- ✅ **Honra el [Art. 10](../MANIFIESTO.md#art-10):** el humano *dispara* la derivación; no *escribe a mano* el
+  contenido (eso sigue prohibido). Un `dai stamp` corrido por una persona escribe lo
+  mismo que uno corrido por el CI.
+- ✅ Un equipo N3 sin pipeline tiene trazabilidad federada **distribuida** ya mismo.
+- ⚠️ En modo distribuido, `dai stamp` depende de que alguien lo corra. `dai check`
+  como git-hook o gate de PR reduce el riesgo de olvido.
+- ⚠️ Ambos comandos necesitan **leer** la US viva (y `dai stamp`, escribir): eso es el
+  adaptador de PM (Jira/ClickUp/`.md`), ya implementado en `getAdapter`. Es un token +
+  llamadas HTTP, **no** un CI.
+
+## Alternativas consideradas
+
+- **Exigir un CI corriendo en Jira/ClickUp** — descartado: barrera de entrada que
+  contradice el [Art. 14](../MANIFIESTO.md#art-14) y que además es un fantasma (el tracker no ejecuta nada).
+- **Estampar la cobertura a mano en el tracker** — descartado: viola el [Art. 10](../MANIFIESTO.md#art-10) (el
+  contenido debe derivarse, no escribirse a mano) y se desincroniza.
+- **Un solo comando que compare y escriba a la vez** — descartado: separar `check`
+  (read-only, gate) de `stamp` (write) permite usar `check` como gate de PR sin
+  permisos de escritura, y correr `stamp` solo cuando corresponde.

package/docs/adr/0004-ubicacion-y-schema-implements.md

@@ -0,0 +1,94 @@
+# ADR-0004 — Ubicación y schema del `implements.yaml`
+
+- **Estado:** aceptado
+- **Fecha:** 2026-07-03
+- **Decide:** lead / arquitecto de la metodología
+
+## Contexto
+
+El `implements.yaml` es el **único registro autorado** del link QUÉ↔CÓMO ([Art. 9](../MANIFIESTO.md#art-9)).
+Para que `link-us` lo scaffoldee y `dai check`/`stamp` lo parseen, hay que congelar
+**dónde vive** y **qué campos tiene**. Cierra la decisión abierta de METODOLOGIA §7 sobre el formato del link.
+
+Dos requisitos duros (Art. 9): vive **en el repo de código** y está **versionado por
+git** — así el `ac_hash` estampado viaja con el commit y el link es revisable en el PR.
+
+## Decisión
+
+### Ubicación
+
+- **Co-localizado con la unidad de trabajo** (una US = una capacidad entera = un
+  `implements.yaml`). Default usando OpenSpec: `openspec/changes/<change-id>/implements.yaml`.
+
+El `implements.yaml` vive **junto a los artefactos de OpenSpec** del change, no aparte:
+
+```
+openspec/
+└── changes/
+    └── finalizar-compra/          # el change = el CÓMO (una US = una capacidad entera)
+        ├── proposal.md            # opsx:propose · qué se propone y por qué
+        ├── design.md              # opsx:propose · el diseño técnico
+        ├── tasks.md               # opsx:propose · las tareas (se implementan con TDD)
+        ├── specs/                 # opsx:propose · las deltas de spec
+        │   └── carrito/
+        │       └── spec.md
+        └── implements.yaml        # ★ dai link-us · el link QUÉ↔CÓMO (id + @version + ac_hash)
+```
+
+Los tres primeros los genera **OpenSpec** (`opsx:propose`); el `implements.yaml` lo agrega
+**dai** (`link-us`) en la misma carpeta. Al archivar, el change entero (incluido el
+`implements.yaml`) se mueve a `openspec/changes/archive/` y **sigue contando** para la cobertura.
+
+- **Tool-agnóstico por descubrimiento (Art. 2):** `dai` **no** hardcodea la ruta de
+  OpenSpec. Hace un glob de `**/implements.yaml` (excluyendo `node_modules`, `dist`,
+  etc.). Un equipo con Swagger u otra herramienta lo pone donde quiera y `dai` lo
+  encuentra.
+- **Incluye archivados:** el glob abarca `openspec/changes/archive/**` — un change
+  archivado sigue vivo en el código, así que **cuenta** para la cobertura.
+- **La lista de "qué implementa el repo" es derivada**, no un manifiesto a mano: se
+  arma escaneando los `implements.yaml` co-localizados (Art. 10).
+
+### Schema
+
+```yaml
+change: finalizar-compra          # identidad del CÓMO (nombre local del change/spec).
+                                 # Explícito, NO derivado del path → sobrevive al archivado.
+repo:   frontend            # repo donde vive.
+
+implements:                      # FORWARD: qué QUÉ cumple este change (capacidad entera).
+  - id: ABC-482                 #   ticket de Jira/ClickUp (identidad del QUÉ). No se tipea: lo pone link-us.
+    version: v1                  #   spec_version de la US al implementar (nº legible).
+    ac_hash: 7f3a9c2e            #   snapshot del hash de criterios (lo calcula `dai ac-hash`).
+
+introduces:                      # specs técnicas nuevas que crea este change (opcional).
+  - guard-carrito-vacio
+
+autor: D. Force (dev)            # quién implementa.
+```
+
+- `change` y `repo` son obligatorios y hacen el registro **auto-contenido**: `dai stamp`
+  puede reportar "ABC-482 ← frontend/finalizar-compra @v1" sin parsear rutas.
+- `implements` es una lista (un change podría cumplir más de un QUÉ, aunque el default
+  es uno — capacidad entera, §2.6).
+- El link es **dirigido CÓMO→QUÉ**; la inversa (QUÉ→CÓMO en Jira) la deriva `dai stamp`.
+
+## Consecuencias
+
+- ✅ `link-us` tiene molde exacto para generar; `check`/`stamp` tienen contrato para
+  parsear.
+- ✅ Registro auto-contenido → robusto al archivado y a mover carpetas.
+- ✅ Independiente de OpenSpec: la ubicación es convención, el descubrimiento es glob.
+- ⚠️ El glob debe excluir directorios ruidosos (`node_modules`, `dist`, `vendor`) para no
+  escanear de más.
+- ⚠️ Si un repo tuviera dos `implements.yaml` con el mismo `change`, es un error a
+  detectar (identidad duplicada).
+
+## Alternativas consideradas
+
+- **Un manifiesto único en la raíz (`.dai/implements.yaml`)** — descartado: archivo
+  compartido que todos editan (conflictos de merge), y pierde la co-localización que
+  hace el diff del PR revisable.
+- **Derivar la identidad del CÓMO del path de la carpeta** — descartado: se rompe al
+  archivar/mover; mejor un campo `change` explícito.
+- **Registrar el mapping también a mano en Jira** — descartado: sería un tercer
+  registro que se desincroniza; la inversa se deriva (Art. 10).

package/docs/adr/0005-superficie-comandos-y-stamp.md

@@ -0,0 +1,65 @@
+# ADR-0005 — Superficie de comandos del CLI y contenido del stamp
+
+- **Estado:** aceptado
+- **Fecha:** 2026-07-03
+- **Decide:** lead / arquitecto de la metodología
+
+## Contexto
+
+Los ADR-0001/0003/0004 definieron el hash, el modelo de detección y el schema del
+`implements.yaml`. Falta congelar **qué comandos** expone `dai` para la trazabilidad
+y **qué estampa** exactamente `dai stamp` en el tracker (que es el router de Nivel-1,
+§2.5, y por lo tanto debe llevar links a la implementación).
+
+## Decisión
+
+### Superficie de comandos de trazabilidad
+
+| Comando | Acceso | Qué hace |
+|---|---|---|
+| `dai ac-hash <us>` | local | calcula el hash de criterios (ADR-0001). |
+| `dai ls [--json]` | **local, offline** | escanea `**/implements.yaml`, lista las US que implementa el repo + su link al tracker. Base de los otros dos. |
+| `dai check` | lee la US viva | `ls` + trae la US + compara hashes → al día / ⚠️ atrasado. Exit ≠ 0 si atraso (gate de PR). |
+| `dai stamp` | escribe al tracker | `ls` + trae la US + **escribe la cobertura** (inversa, [Art. 10](../MANIFIESTO.md#art-10)). |
+
+`check` y `stamp` se construyen sobre `ls` (un solo lugar descubre y parsea).
+
+### Contenido del stamp (el router necesita links)
+
+`dai stamp` escribe en el ticket, por cada repo/change que lo implementa:
+
+```
+repo:    <nombre>   → <repo web url>
+branch:  <branch>   → <branch url>     ← link principal (legible)
+commit:  <sha>      → <commit url>     ← ANCLA durable (sobrevive al borrado de branch)
+version: <v> (<ac_hash>)  → ✅ al día | ⚠️ atrasado
+autor:   <dev>
+```
+
+**Los links se derivan de git, sin API del forge ni `--pr`:**
+- repo/branch/commit salen de `git remote get-url origin` + `git rev-parse`.
+- La URL web es **específica del forge** (GitHub `/tree/` `/commit/`; GitLab `/-/tree/`
+  `/-/commit/`; Bitbucket `/src/` `/commits/`): `dai` mapea forge→esquema por el host
+  del remoto.
+
+**Branch + commit-ancla:** la branch es el link legible, pero se borra al mergear; el
+commit es permanente. Guardar los dos evita que el router quede en 404.
+
+## Consecuencias
+
+- ✅ Trazabilidad completa sin API del forge ni flags manuales: todo se deriva de git.
+- ✅ El router (§2.5) siempre tiene un link vivo (el commit) → nunca dead-link.
+- ✅ `dai ls` es offline y read-only → sirve de base barata para todo lo demás.
+- ⚠️ Construir la URL web es forge-específico → lógica a testear (SSH/HTTPS, 3 forges).
+- ⚠️ `dai stamp` (write) y `dai check` (read US viva) dependen del **adaptador de PM**
+  (`getAdapter`, ya implementado). Para el backend `md`, `stamp --format md` emite el bloque para
+  pegar a mano (mismo fallback que `grill-user-story`).
+
+## Alternativas consideradas
+
+- **Link a la PR/MR** — descartado: no es derivable localmente sin API del forge, y en
+  modo distribuido genera fricción (`--pr`). La branch+commit se derivan de git solo.
+- **Solo la branch** — descartado: la branch se borra al mergear → 404. El commit es la
+  ancla durable.
+- **Solo el commit** — viable pero menos legible; la branch le da contexto humano.
+  Guardamos los dos.

package/docs/adr/0006-distribucion-y-licencia.md

@@ -0,0 +1,59 @@
+# ADR-0006 — Distribución y licencia
+
+- **Estado:** aceptado
+- **Fecha:** 2026-07-03
+- **Decide:** autor / mantenedor
+
+## Contexto
+
+`dai` va a distribuirse para que **la comunidad lo use y lo mejore**. Hay que fijar
+dos cosas: bajo qué **licencia** se libera, y por qué **canales** se distribuye. El
+CLI es Node **cero dependencias**, lo que abre canales que no todos los proyectos
+tienen (correr sin `npm install`).
+
+## Decisión
+
+### Licencia: GPLv3 (`GPL-3.0-or-later`)
+
+El objetivo es *libre + que la comunidad ayude a mejorarla*. La garantía **legal**
+más fuerte de eso es el **copyleft**: quien distribuya un `dai` modificado debe
+publicar sus cambios bajo la misma licencia. La GPL convierte "las mejoras vuelven"
+en cláusula, no en deseo.
+
+El downside típico de la GPL **no aplica** acá: `dai` es un **CLI que se ejecuta**,
+no una librería que se embebe. Usar `dai` sobre tu código —aunque sea propietario y
+comercial— **no genera ninguna obligación**; el copyleft solo se activa si alguien
+**forkea y redistribuye** una versión modificada. Y *libre ≠ gratis*: se puede
+cobrar por uso, soporte o desarrollo sobre `dai`.
+
+- SPDX: **`GPL-3.0-or-later`** (recomendación FSF: "v3 o posterior"). Si se prefiere
+  fijar solo v3, cambiar a `GPL-3.0-only`.
+- El texto íntegro va en `LICENSE` (copia verbatim de gnu.org).
+- Los **docs/metodología** quedan cubiertos por la misma licencia por ahora; a
+  futuro podrían migrar a **CC BY-SA** (el copyleft equivalente para texto).
+
+### Distribución
+
+- **npm público** como canal principal (el CLI es cero-dep → `npx dai …` anda sin
+  instalar nada).
+- **git-clone + `install.sh`** y **tarball** como fallback para **redes corporativas
+  cerradas** (proxy/firewall que bloquea el registry).
+- Se saca `"private": true` del `package.json` para habilitar la publicación.
+
+## Consecuencias
+
+- ✅ Los forks públicos de `dai` quedan abiertos para siempre → el commons crece.
+- ✅ Cualquier empresa puede *usar* `dai` sin obligaciones (es un CLI).
+- ✅ El canal cero-dep + fallback cubre tanto factories abiertas como orgs cerradas.
+- ⚠️ `dai` no se podrá **embeber** como librería dentro de software propietario. Si
+  alguna vez hace falta eso, se evaluaría relicenciar una parte como LGPL/MIT.
+- ⚠️ Publicar en npm hace el código **público** — nada de secretos en el repo (ya lo
+  cubre `.gitignore` + `.env`).
+
+## Alternativas consideradas
+
+- **MIT / Apache-2.0 (permisivas)** — máxima adopción y fricción cero, pero **no**
+  obligan a devolver mejoras: se depende de la buena voluntad. Descartadas frente al
+  objetivo explícito de "que la comunidad ayude a mejorarla".
+- **AGPLv3** — extiende el copyleft al uso como servicio en red. Overkill para un CLI
+  local; se descarta salvo que aparezca un caso SaaS.

package/docs/adr/0007-modelo-de-autenticacion.md

@@ -0,0 +1,63 @@
+# ADR-0007 — Modelo de autenticación
+
+- **Estado:** aceptado
+- **Fecha:** 2026-07-03
+- **Decide:** lead / arquitecto + mantenedor
+
+## Contexto
+
+`dai` y sus skills tocan **tres** sistemas externos: los repos de código (git), el
+forge (GitHub/GitLab, para comentar PRs), y el tracker (Jira/ClickUp). Cada uno se
+autentica distinto. Ahora que hay tokens en juego (`dai forge`, adaptador de PM),
+hay que fijar un modelo de auth **antes** de seguir sumando credenciales — para no
+terminar con contraseñas hardcodeadas o secretos en un commit.
+
+Principio rector: **least privilege, sin contraseñas, secretos nunca versionados.**
+
+## Decisión
+
+### Tres credenciales, tres mecanismos (no se mezclan)
+
+| Sistema | Acción | Credencial | Dónde vive |
+|---|---|---|---|
+| **git** | clone / fetch / push | **SSH key** (ssh-agent) | `~/.ssh` — **nunca** en `.env` ni en el repo |
+| **forge** | leer/comentar PR/MR | **token scopeado** (`GITHUB_TOKEN` / `GITLAB_TOKEN`) | `.env` (gitignored) o secret store del CI |
+| **tracker** | leer/escribir US y cobertura | **api_key** (`DAI_JIRA_TOKEN` / `DAI_CLICKUP_TOKEN`) | `.env` o secret store del CI |
+
+### Reglas
+
+1. **Nada de contraseñas.** Ni para git (SSH), ni para las APIs (tokens scopeados y
+   revocables). Prohibido el patrón `https://user:password@host`.
+2. **git es SSH.** El transporte de git (incluido lo que haga un agente o el CLI)
+   usa SSH. Comentar una PR **no** se hace por SSH (SSH solo mueve objetos git): eso
+   es API del forge → token.
+3. **Least privilege.** El token del forge se limita al scope mínimo (PRs/notes), no
+   un PAT con acceso total. Igual para el tracker.
+4. **Secretos fuera del repo.** Solo en `.env` (gitignored) o el secret store del CI.
+   Nunca en el código, ni en `implements.yaml`, ni en un commit. `.env.example`
+   documenta los **nombres** de las variables, jamás los valores.
+5. **Dos caras (ADR-0002).** Las **skills** usan el **MCP** del asistente (que guarda
+   sus propias credenciales); el **CLI** usa los **tokens del `.env`**. Nunca se
+   comparten ni se filtra uno al otro.
+6. **Variables de entorno ganan.** Un token exportado en la shell/CI pisa al `.env`
+   (para que el CI inyecte secretos sin escribir archivos).
+
+## Consecuencias
+
+- ✅ Superficie de secretos mínima y auditable: SSH keys + tokens scopeados, cero
+   contraseñas.
+- ✅ `.gitignore` + `.env.example` ya hacen cumplir "secretos fuera del repo".
+- ✅ Rotar/revocar es trivial: son tokens, no contraseñas de cuenta.
+- ⚠️ Requiere que cada dev tenga su SSH key configurada (ssh-agent) — es el costo de
+   no usar contraseñas. Se documenta en el onboarding.
+- ⚠️ En el CI hay que cargar los tokens desde su secret store, no desde un `.env`
+   commiteado (que no existe).
+
+## Alternativas consideradas
+
+- **Contraseña / PAT embebido en la URL de git** — descartado: viola "sin
+   contraseñas", y termina en el `~/.git-credentials` o en un remoto commiteado.
+- **Un único super-token para todo** — descartado: rompe least privilege; si se
+   filtra, se filtra todo. Un token por sistema y por scope.
+- **Que el CLI use el MCP del asistente** — imposible: el CLI corre standalone, no
+   tiene acceso al MCP. Por eso el CLI usa tokens propios (dos caras).

package/docs/adr/README.md

@@ -0,0 +1,19 @@
+# ADRs — decisiones de fondo de la metodología
+
+Registro de las decisiones estructurales de `dai`. Cada ADR es **inmutable**: si una
+decisión cambia, se escribe un ADR nuevo que supersede al viejo. Molde en
+[`templates/adr.md`](../../templates/adr.md).
+
+| # | Decisión | Estado |
+|---|---|---|
+| [0001](0001-contrato-ac-hash.md) | El contrato del `ac_hash` (normalización + SHA-256, tres momentos) | aceptado |
+| [0002](0002-agnostico-del-asistente.md) | La metodología es agnóstica del asistente (Claude / Copilot) | aceptado |
+| [0003](0003-deteccion-y-estampado-son-comandos.md) | La detección y el estampado son comandos (`dai check` / `dai stamp`), no infraestructura | aceptado |
+| [0004](0004-ubicacion-y-schema-implements.md) | Ubicación (co-localizado + glob) y schema del `implements.yaml` | aceptado |
+| [0005](0005-superficie-comandos-y-stamp.md) | Superficie de comandos (`ls`/`check`/`stamp`) y contenido del stamp (branch + commit-ancla) | aceptado |
+| [0006](0006-distribucion-y-licencia.md) | Distribución (npm + fallback) y licencia (GPLv3) | aceptado |
+| [0007](0007-modelo-de-autenticacion.md) | Modelo de auth: SSH para git, tokens scopeados para forge/tracker, sin contraseñas | aceptado |
+
+> Estas son las decisiones que cierran las "Decisiones abiertas" de
+> [`METODOLOGIA.md §7`](../METODOLOGIA.md) y las enmiendas al
+> [`MANIFIESTO.md`](../MANIFIESTO.md).

package/docs/detalle/01-refinamiento.md

@@ -0,0 +1,33 @@
+# Paso 1 — Refinamiento: de la idea vaga a la US testeable
+
+← vuelve a [`SCRUM-CON-IA.md`](../SCRUM-CON-IA.md)
+
+## En qué consiste en detalle
+
+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
+   construcción** (INVEST + Gherkin) y la publica en el tracker.
+
+## 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).
+- Gate de entrada: [`definition-of-ready.md`](../../templates/definition-of-ready.md).
+
+## Qué firma el humano
+
+El PO **responde y decide**. La IA no inventa requerimientos: los saca a preguntas
+([Art. 4](../MANIFIESTO.md#art-4)). El PO es dueño del contenido funcional.
+
+## Antipatrones
+
+- **US vaga** ("como usuario quiero un botón") → no pasa el pulido.
+- **Criterio no testeable** ("buena experiencia") → se rechaza (Art. 3).
+- **Solución prefijada** en la US (endpoints, tablas) → eso es CÓMO, va después (Art. 1).
+- **Saltearse el Gate 0** → se construye lo que no había que construir.

package/docs/detalle/02-planning.md

@@ -0,0 +1,27 @@
+# Paso 2 — Planning: derivar el CÓMO desde la US
+
+← vuelve a [`SCRUM-CON-IA.md`](../SCRUM-CON-IA.md)
+
+## En qué consiste en detalle
+
+El equipo elige qué US entran al sprint (prioridad + capacidad). Para cada una, el
+dev corre OpenSpec sobre la US: `opsx:explore` (entiende specs + código) y luego
+`opsx:propose`, que **genera** el `design.md`, el `tasks.md` y las deltas de
+`specs/`. El dev valida y ajusta — no acepta a ciegas.
+
+## Herramientas
+
+- `opsx:explore` → mapa de specs y código relevante.
+- `opsx:propose` → `proposal.md` + `design.md` + `tasks.md` + `specs/`.
+
+## Qué firma el humano
+
+El **equipo** decide capacidad y prioridad. El **dev** valida el design y las tareas
+propuestas — son suyas, nacen del CÓMO ([Art. 1](../MANIFIESTO.md#art-1)), no bajadas desde arriba.
+
+## Antipatrones
+
+- **Tareas inventadas por fuera del que implementa** → pierden sentido técnico.
+- **Estimar a ciegas** una US que no cumple el DoR → primero se pule (paso 1).
+- **US demasiado grande** que no entra en el sprint → se parte (INVEST), no se fuerza.
+- **Aceptar el design generado sin leerlo** → el dev es responsable del CÓMO.

package/docs/detalle/03-ramas.md

@@ -0,0 +1,32 @@
+# Paso 3 — Rama: atar el código al QUÉ desde el commit uno
+
+← vuelve a [`SCRUM-CON-IA.md`](../SCRUM-CON-IA.md)
+
+## En qué consiste en detalle
+
+El dev arranca 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
+
+```bash
+dai link-us ABC-482 --us us.md
+# → branch  feature/ABC-482-<slug>
+# → openspec/changes/<change>/implements.yaml  (con el ac_hash ya calculado)
+```
+
+- Convención de rama: [`branch-naming.md`](../../governance/branch-naming.md).
+- Schema del link: [ADR-0004](../adr/0004-ubicacion-y-schema-implements.md).
+- El `ac_hash` lo calcula `dai ac-hash` ([ADR-0001](../adr/0001-contrato-ac-hash.md)).
+
+## Qué firma el humano
+
+El dev **elige qué US agarra**. 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
+
+- **Tipear el key en la branch o el yaml a mano** → error que rompe la trazabilidad.
+- **Branch sin `implements.yaml`** en trabajo de producto → no hay link.
+- **Escribir la cobertura inversa a mano** → se deriva con `dai stamp` (Art. 10).
+- **Una branch para varias US** → una US = una capacidad = un `implements.yaml`.

package/docs/detalle/04-tdd.md

@@ -0,0 +1,35 @@
+# Paso 4 — TDD: test primero, en vertical slices
+
+← 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:
+
+```
+RED   → escribes 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
+```
+
+*Vertical slices* (un test → una implementación → repetir), **no** horizontal
+(todos los tests, después todo el código).
+
+## Herramientas
+
+- Skill [`tdd`](../../skills/tdd/SKILL.md) — 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.
+
+## Antipatrones
+
+- **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
+  al refactorizar aunque el comportamiento no cambió. Testea por la **interfaz pública**.
+- **Codear primero, testear "si queda tiempo"** → vibe coding ([Art. 7](../MANIFIESTO.md#art-7)).
+- **Refactorizar en rojo** → primero llega a verde.

package/docs/detalle/05-smoke.md

@@ -0,0 +1,32 @@
+# Paso 5 — Smoke: el flujo entero, verde
+
+← vuelve a [`SCRUM-CON-IA.md`](../SCRUM-CON-IA.md)
+
+## En qué consiste en detalle
+
+Antes de cerrar la US, se corre un **smoke end-to-end**: ejercita el flujo completo
+—happy path + los guards principales— para confirmar que no se rompió nada grueso.
+No reemplaza a los tests unitarios (paso 4); los complementa a nivel sistema.
+
+```
+✓ happy path → resultado esperado
+✓ guard 1 → rechazado como corresponde
+✓ guard 2 → rechazado como corresponde
+SMOKE OK
+```
+
+## Herramientas
+
+- Skills de smoke por dominio (p. ej. `smoke-<módulo>`), armadas por el equipo.
+
+## Qué firma el humano
+
+El dev **confirma que el escenario refleja el uso real**. Un smoke que no toca el
+flujo que importa da falsa confianza.
+
+## Antipatrones
+
+- **Smoke manual** que se olvida o se saltea bajo presión → automatizarlo (idealmente
+  en el pipeline, ver retro).
+- **Smoke que no ejercita los guards** → pasa en verde y esconde el bug.
+- **Confundir smoke con suite completa** → el smoke es grueso y rápido, a propósito.