don-cheli-sdd 1.13.0

package/scripts/.claude/commands/especdev/cerrar-sesion.md

@@ -0,0 +1,88 @@
+---
+description: Ritual de cierre de sesión con auditoría, calidad, aprendizajes y contexto para la próxima sesión
+i18n: true
+---
+
+# /especdev:cerrar-sesion
+
+## Objetivo
+
+Ritual de fin de sesión que audita cambios, ejecuta checks de calidad, captura aprendizajes y produce un resumen para la próxima sesión. Evita el anti-patrón de cerrar el editor sin guardar contexto.
+
+> Adaptado de `wrap-up` de Pro-Workflow (rohitg00/pro-workflow).
+
+## Uso
+
+```
+/especdev:cerrar-sesion
+```
+
+## Checklist (obligatorio — no saltar pasos)
+
+### 1. 📋 Auditoría de Cambios
+- ¿Qué archivos se modificaron?
+- ¿Hay cambios sin commit?
+- ¿Quedaron TODOs en el código?
+- ¿Hay archivos temporales que limpiar?
+
+### 2. ✅ Check de Calidad
+- Ejecutar lint
+- Ejecutar typecheck
+- Ejecutar tests
+- ¿Todo pasa? ¿Hay warnings?
+
+### 3. 🧠 Captura de Aprendizajes
+- ¿Qué errores se cometieron?
+- ¿Qué patrones funcionaron bien?
+- Formatear como: `[APRENDER] Categoría: Regla`
+
+### 4. 🔮 Contexto para Próxima Sesión
+- ¿Cuál es la siguiente tarea lógica?
+- ¿Hay bloqueantes?
+- ¿Qué contexto preservar?
+
+### 5. 📝 Resumen
+- Un párrafo: qué se logró, estado actual, qué sigue
+
+## Output
+
+```markdown
+# Cierre de Sesión — 2026-03-21 16:45
+
+## Auditoría
+- Archivos modificados: 8
+- Commits: 3
+- Sin commit: 2 archivos (src/auth.ts, tests/auth.test.ts)
+- TODOs encontrados: 1 (src/auth.ts:45 — "TODO: handle refresh token")
+
+## Calidad
+- Lint: ✅ sin errors | ⚠️ 2 warnings
+- TypeCheck: ✅ pasa
+- Tests: ✅ 47/47
+- Coverage: 87%
+
+## Aprendizajes
+- [APRENDER] Testing: Siempre mockear el servicio de email en tests de auth
+- [APRENDER] Git: Hacer commits más pequeños — 3 archivos max
+
+## Próxima Sesión
+- Tarea: Implementar refresh token (TODO en auth.ts:45)
+- Bloqueante: Ninguno
+- Contexto: Branch feature/oauth, PR #23 abierto
+
+## Resumen
+Se completó el login con Google OAuth: 3 endpoints nuevos, 12 tests,
+integración con NextAuth v5. Falta el refresh token (TODO en auth.ts:45).
+PR #23 listo para review excepto por el refresh token.
+
+---
+🛑 ¿Cambios sin commit? Stash o commit antes de cerrar.
+✅ ¿Listo para cerrar sesión?
+```
+
+## Si Tests Fallan
+
+⚠️ **NO cerrar sesión con tests fallando.** Opciones:
+1. Corregir antes de cerrar
+2. Documentar el fallo en el handoff
+3. Crear issue para el próximo que lo agarre

package/scripts/.claude/commands/especdev/clarificar.md

@@ -0,0 +1,98 @@
+---
+description: Detectar ambigüedades en una especificación, ejecutar Auto-QA y registrar respuestas
+i18n: true
+---
+
+# /especdev:clarificar
+
+## Objetivo
+
+Analizar una especificación Gherkin actuando como **Ingeniero QA Estricto**: detectar ambigüedades, ejecutar verificaciones automáticas de consistencia Schema↔Spec, y registrar las respuestas en el archivo `.feature`.
+
+> Mejorado con el protocolo Auto-QA de Specular (constitution.md §VIII)
+
+## Uso
+
+```
+/especdev:clarificar @specs/features/<dominio>/<Feature>.feature
+```
+
+## Comportamiento
+
+### Fase 1: Análisis de Ambigüedades (Original)
+
+1. **Leer** el archivo `.feature`
+2. **Analizar** cada escenario buscando:
+   - Términos ambiguos o no definidos
+   - Casos límite no cubiertos
+   - Validaciones implícitas
+   - Dependencias no mencionadas
+3. **Formular** hasta 5 preguntas dirigidas
+4. **Registrar** las respuestas en el archivo `.feature` como comentarios
+
+### Fase 2: Verificación Auto-QA (De Specular)
+
+Ejecutar automáticamente **SIN pedir instrucciones adicionales**:
+
+#### 2.1 Verificación de Consistencia Schema-Spec (DBML)
+
+- Escanear todos los campos mencionados en el Gherkin
+- Comparar contra el schema DBML en `specs/db_schema/<dominio>.dbml`
+- ❌ Error si nombres de campos no coinciden exactamente (ej: `user_id` vs `userId`)
+- ❌ Error si un campo `NOT NULL` en DBML no tiene escenario de validación en Gherkin
+
+#### 2.2 Verificación de Convención de Nombres
+
+- **Feature COMMAND:** Usar patrón de precondición + postcondición
+- **Feature QUERY:** Usar patrón de precondición + éxito
+
+#### 2.3 Auditoría de Escenarios Auto-Generados
+
+- Revisar escenarios tagueados `@auto_generado`
+- Marcar los que sean redundantes o lógicamente imposibles
+
+### Fase 3: Generar Checklist de Requisitos
+
+Generar automáticamente `requisitos.md` con evidencia citada para cada item.
+
+## Output
+
+```markdown
+=== Reporte Auto-QA ===
+
+Feature: CrearUsuario.feature
+
+## Ambigüedades Detectadas: 3
+1. ¿Qué longitud mínima/máxima debe tener la contraseña?
+2. ¿Se permite registro con proveedores OAuth (Google, GitHub)?
+3. ¿El email de bienvenida es síncrono o asíncrono?
+
+## Verificación Schema-Spec
+✅ PASS: Campo "email" coincide con usuario.dbml
+✅ PASS: Campo "password_hash" tiene escenario de validación
+❌ FAIL: Campo "nombre" en DBML es NOT NULL pero no tiene escenario de validación
+
+## Verificación de Convenciones
+✅ PASS: Feature COMMAND usa patrón precondición/postcondición
+⚠️ WARNING: Escenario "Contraseña débil" no verifica postcondición
+
+## Auditoría Auto-Generado
+✅ PASS: Sin escenarios redundantes
+
+## Resultado
+NO-AVANZAR (1 FAIL)
+→ Acción requerida: Agregar escenario de validación para campo "nombre"
+```
+
+## Transición de Estado
+
+```
+@borrador → (clarificar pasa Auto-QA) → @lista
+@borrador → (clarificar falla Auto-QA) → @borrador (corregir y re-clarificar)
+```
+
+## Puerta de Calidad Asociada
+
+Esta comando implementa la **Puerta 2+3** del pipeline:
+- Puerta 2: El header contiene `@lista` (solo si pasa)
+- Puerta 3: Reporte Auto-QA sin ❌ FALLA

package/scripts/.claude/commands/especdev/comenzar.md

@@ -0,0 +1,77 @@
+---
+description: Iniciar tarea con nivel de complejidad auto-detectado (0-4)
+i18n: true
+---
+
+# /especdev:comenzar
+
+## Objetivo
+
+Iniciar una tarea detectando automáticamente el nivel de complejidad (0-4) y ejecutando el flujo apropiado.
+
+## Uso
+
+```
+/especdev:comenzar <descripción de la tarea>
+```
+
+## Auto-Detección de Nivel
+
+Evaluar cada dimensión de 0 a 4:
+
+```
+Alcance:     0=1 archivo  1=2-3 archivos  2=módulo  3=multi-módulo  4=sistema
+Incógnitas:  0=ninguna    1=menores       2=algunas 3=significativas 4=fundamentales
+Riesgo:      0=trivial    1=bajo          2=medio   3=alto           4=crítico
+Duración:    0=<30min     1=horas         2=días    3=1-2 semanas    4=semanas+
+
+Nivel = max(puntuaciones)  // Conservador: gana la dimensión más alta
+```
+
+## Niveles
+
+| Nivel | Nombre | Proceso |
+|-------|--------|---------|
+| **0** | Atómico | Ejecutar directamente |
+| **P** | PoC | Hipótesis → Construir → Evaluar → Veredicto |
+| **1** | Micro | Planear → Ejecutar → Verificar |
+| **2** | Estándar | 5 fases (sin Descubrimiento/Crecimiento) |
+| **3** | Complejo | 7 fases completas |
+| **4** | Producto | 7 fases + artefactos completos |
+
+**Detección de PoC:** Si la tarea es una pregunta ("¿se puede...?", "¿funciona...?", "¿vale la pena...?") o incluye palabras como "probar", "viabilidad", "validar", "explorar opción" → sugerir `/especdev:poc`.
+
+## Comportamiento
+
+1. **Analizar** la descripción de la tarea
+2. **Evaluar** las 4 dimensiones (alcance, incógnitas, riesgo, duración)
+3. **Determinar** nivel de complejidad
+4. **Mostrar** evaluación al usuario
+5. **Preguntar** si está de acuerdo o desea ajustar
+6. **Iniciar** flujo del nivel correspondiente
+
+## Ejemplo
+
+```bash
+/especdev:comenzar Implementar autenticación JWT con refresh tokens
+
+=== Evaluación de Complejidad ===
+
+Tarea: Implementar autenticación JWT con refresh tokens
+
+Alcance:    3 (multi-módulo: auth, middleware, database)
+Incógnitas: 2 (algunas: estrategia de refresh)
+Riesgo:     3 (alto: seguridad)
+Duración:   2 (días)
+
+→ Nivel detectado: 3 (Complejo)
+→ Proceso: 7 fases completas
+
+¿Proceder con Nivel 3? (s/n/ajustar)
+```
+
+## Escalamiento y Des-escalamiento
+
+- Si durante la ejecución se detecta mayor complejidad → escalar nivel
+- Si la complejidad resulta menor → des-escalar nivel
+- Regla de Desviación 4 → escalar al menos 1 nivel

package/scripts/.claude/commands/especdev/completo.md

@@ -0,0 +1,49 @@
+---
+description: Modo completo para proyectos grandes y complejos (Nivel 3)
+i18n: true
+---
+
+# /especdev:completo
+
+## Objetivo
+
+Iniciar modo completo (Nivel 3 - Complejo) para proyectos que requieren las 7 fases del ciclo de vida.
+
+## Uso
+
+```
+/especdev:completo <descripción del proyecto>
+```
+
+## Las 7 Fases
+
+| Fase | Duración | Actividades |
+|------|----------|-------------|
+| 1. Descubrimiento | 1-2 días | Validar problema, investigar, descubrimientos |
+| 2. Estrategia | 1 día | Hoja de ruta, hitos, decisiones |
+| 3. Diseño | 2-3 días | Arquitectura, UX, especificaciones |
+| 4. Desarrollo | Variable | TDD, implementación, iteración |
+| 5. Calidad | 1-2 días | Testing, validación, rendimiento |
+| 6. Lanzamiento | 1 día | Despliegue, documentación, release |
+| 7. Crecimiento | Continuo | Monitoreo, feedback, iteración |
+
+## Transiciones de Fase
+
+Cada fase requiere criterios de Avance/No-Avance:
+
+```markdown
+## Fase [N] Completada
+
+### Lista de Verificación Avance/No-Avance
+- [ ] Todas las tareas de la fase completadas
+- [ ] Entregables verificados
+- [ ] Sin bloqueadores
+- [ ] Listo para siguiente fase
+
+**Decisión:** AVANZAR / NO-AVANZAR
+**Motivo:** [por qué]
+```
+
+## Des-escalamiento
+
+Si después de la Estrategia el alcance es menor → des-escalar a `/especdev:rapido`

package/scripts/.claude/commands/especdev/continuar.md

@@ -0,0 +1,59 @@
+---
+description: Recuperar sesión previa y generar reporte de puesta al día
+i18n: true
+---
+
+# /especdev:continuar
+
+## Objetivo
+
+Recuperar el contexto de una sesión previa y generar un reporte de puesta al día.
+
+## Uso
+
+```
+/especdev:continuar
+```
+
+## Comportamiento
+
+1. **Detectar** directorio `.especdev/` existente
+2. **Leer** archivos de contexto
+3. **Generar** Reporte de Puesta al Día:
+
+```markdown
+## 🔄 Recuperación de Sesión
+
+**Proyecto:** api-pagos
+**Última Sesión:** 2026-03-21 15:30
+
+**Estado Actual:**
+- Fase: 3/7 (Diseño)
+- Tarea: Diseñar esquema de base de datos
+- Progreso: 40%
+
+**Hallazgos Recientes:**
+- JWT preferido sobre sesiones
+- La API legacy tiene vulnerabilidades
+
+**Próximos Pasos:**
+1. Completar esquema de base de datos
+2. Agregar reset de contraseña
+```
+
+## Test de 5 Preguntas
+
+Para verificar que el contexto está completo:
+
+| # | Pregunta | Fuente | Estado |
+|---|----------|--------|--------|
+| 1 | ¿Dónde estoy? | `estado.md` | Fase actual |
+| 2 | ¿A dónde voy? | `plan.md` | Fases restantes |
+| 3 | ¿Cuál es la meta? | `config.yaml` | Objetivo del proyecto |
+| 4 | ¿Qué he aprendido? | `hallazgos.md` | Descubrimientos clave |
+| 5 | ¿Qué he hecho? | `progreso.md` | Acciones recientes |
+
+**Estado del Contexto:**
+- ✅ Completo (5/5) → Listo para continuar
+- ⚠️ Parcial (3-4/5) → Proceder con precaución
+- ❌ Incompleto (0-2/5) → Ejecutar `/especdev:iniciar --reparar`

package/scripts/.claude/commands/especdev/contrato-api.md

@@ -0,0 +1,223 @@
+---
+description: Diseñar contratos de API, webhooks e integraciones con manejo de errores y reintentos
+i18n: true
+---
+
+# /especdev:contrato-api
+
+## Objetivo
+
+Diseñar contratos de API completos (REST o GraphQL), definir webhooks, planificar manejo de errores y reintentos para asegurar la resiliencia de integraciones con plataformas externas.
+
+## Uso
+
+```
+/especdev:contrato-api <descripción de la integración>
+/especdev:contrato-api --tipo rest "Integración con Stripe para pagos"
+/especdev:contrato-api --tipo graphql "API de catálogo de productos"
+/especdev:contrato-api --tipo webhook "Recibir eventos de Shopify"
+```
+
+## Diferencia con `/especdev:planificar-tecnico`
+
+| Aspecto | `planificar-tecnico` | `contrato-api` |
+|---------|---------------------|----------------|
+| **Alcance** | Blueprint completo de una feature | Solo el contrato de API/integración |
+| **Profundidad** | Contrato básico (request/response) | Contrato completo (errores, reintentos, webhooks, idempotencia) |
+| **Cuándo** | Después de spec | Cuando la integración es el foco principal |
+
+## Output para API REST
+
+```markdown
+## Contrato API: Integración de Pagos con Stripe
+
+### Endpoints
+
+#### POST /api/v1/pagos
+**Propósito:** Crear un cobro
+**Auth:** Bearer token (JWT)
+**Rate limit:** 100 req/min por usuario
+**Idempotencia:** Sí (header `Idempotency-Key`)
+
+**Request:**
+```json
+{
+  "monto": 5000,          // centavos, min: 100, max: 99999900
+  "moneda": "USD",        // ISO 4217
+  "cliente_id": "uuid",
+  "metodo_pago_id": "pm_xxx",
+  "descripcion": "Pedido #1234",
+  "metadata": {}          // opcional, max 50 keys
+}
+```
+
+**Responses:**
+| Status | Significado | Body |
+|--------|------------|------|
+| 201 | Cobro creado | `{ id, status, monto, stripe_id, created_at }` |
+| 400 | Datos inválidos | `{ error, field, message }` |
+| 402 | Pago rechazado | `{ error, decline_code, message }` |
+| 409 | Idempotency conflict | `{ error, original_id }` |
+| 429 | Rate limit | `{ error, retry_after }` |
+| 500 | Error interno | `{ error, request_id }` |
+
+**Headers de respuesta:**
+```
+X-Request-Id: uuid          // Para soporte/debugging
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1616544000
+```
+
+### Webhooks (recibir desde Stripe)
+
+#### POST /api/v1/webhooks/stripe
+**Verificación:** HMAC-SHA256 con `Stripe-Signature` header
+**Tolerancia de timestamp:** 300 segundos (5 min)
+**Respuesta esperada:** 200 OK (body vacío) en < 5s
+
+**Eventos soportados:**
+| Evento | Acción | Idempotente |
+|--------|--------|-------------|
+| `payment_intent.succeeded` | Marcar pedido como pagado | Sí |
+| `payment_intent.payment_failed` | Notificar al usuario | Sí |
+| `charge.refunded` | Procesar reembolso | Sí |
+| `charge.dispute.created` | Alertar al equipo | Sí |
+
+**Procesamiento:**
+```
+1. Verificar firma HMAC
+2. Parsear evento
+3. Verificar idempotencia (event.id en tabla processed_events)
+4. Responder 200 INMEDIATAMENTE
+5. Procesar en cola async (no bloquear respuesta)
+6. Registrar en audit log
+```
+
+### Manejo de Errores
+
+**Errores del cliente (4xx):**
+```json
+{
+  "error": {
+    "tipo": "validation_error",
+    "mensaje": "El monto debe ser mayor a $1.00",
+    "campo": "monto",
+    "codigo": "MONTO_INVALIDO"
+  }
+}
+```
+
+**Errores del servidor (5xx):**
+```json
+{
+  "error": {
+    "tipo": "internal_error",
+    "mensaje": "Error procesando el pago",
+    "request_id": "req_abc123"
+  }
+}
+```
+
+**Códigos de error consistentes:**
+| Código | Significado | HTTP |
+|--------|------------|------|
+| `MONTO_INVALIDO` | Monto fuera de rango | 400 |
+| `MONEDA_NO_SOPORTADA` | Moneda no en whitelist | 400 |
+| `PAGO_RECHAZADO` | Tarjeta rechazada | 402 |
+| `DUPLICADO` | Idempotency conflict | 409 |
+| `RATE_LIMIT` | Demasiadas requests | 429 |
+| `STRIPE_ERROR` | Error de comunicación con Stripe | 502 |
+
+### Política de Reintentos
+
+```
+Estrategia: Exponential backoff con jitter
+
+Intento 1: inmediato
+Intento 2: 1s + jitter (0-500ms)
+Intento 3: 2s + jitter (0-1000ms)
+Intento 4: 4s + jitter (0-2000ms)
+Max intentos: 4
+
+Reintentar en:
+  ✅ 429 (rate limit) — respetar Retry-After header
+  ✅ 500, 502, 503, 504 (errores transitorios)
+  ❌ 400, 401, 402, 403, 404, 409 (errores definitivos)
+
+Circuit breaker:
+  - Abrir después de 5 fallos consecutivos
+  - Half-open después de 30 segundos
+  - Cerrar después de 2 éxitos consecutivos
+```
+
+### Timeouts
+
+| Operación | Timeout | Acción si timeout |
+|-----------|---------|-------------------|
+| Crear cobro | 10s | Reintentar (idempotente) |
+| Verificar webhook | 2s | Rechazar (400) |
+| Procesar evento async | 30s | Cola de dead-letter |
+```
+
+## Output para GraphQL
+
+```markdown
+### Schema GraphQL
+
+```graphql
+type Mutation {
+  crearPago(input: CrearPagoInput!): PagoResult!
+  reembolsar(pagoId: ID!, monto: Int): ReembolsoResult!
+}
+
+type Query {
+  pago(id: ID!): Pago
+  pagos(filtro: PagoFiltro, paginacion: Paginacion): PagoConnection!
+}
+
+input CrearPagoInput {
+  monto: Int!          # centavos
+  moneda: Moneda!
+  clienteId: ID!
+  metodoPagoId: String!
+  descripcion: String
+}
+
+type PagoResult {
+  pago: Pago
+  error: APIError
+}
+```
+```
+
+## Almacenamiento
+
+```
+specs/api/
+├── openapi.yaml            # Spec completa (auto-generada)
+├── contratos/
+│   ├── pagos.contrato.md   # Contrato de pagos
+│   ├── webhooks.contrato.md
+│   └── catalogo.contrato.md
+└── postman/
+    └── coleccion.json      # Colección Postman exportada
+```
+
+## Integración con Pipeline
+
+```
+/especdev:contrato-api → contrato + OpenAPI parcial
+  → /especdev:planificar-tecnico → incorpora contrato al plan
+  → /especdev:desglosar → tareas incluyen implementación del contrato
+  → Documentación Viva → actualiza OpenAPI global
+```
+
+## Guardrails
+
+- **Nunca** diseñar API sin definir manejo de errores
+- **Nunca** omitir idempotencia en operaciones de escritura
+- **Nunca** confiar en input externo sin validación
+- **Siempre** definir timeouts y política de reintentos
+- **Siempre** incluir `request_id` en respuestas de error
+- **Siempre** verificar firma de webhooks antes de procesar
+- **Siempre** responder rápido a webhooks (< 5s), procesar async