don-cheli-sdd 1.13.0

package/scripts/.claude/don-cheli/reglas/puertas-calidad.md

@@ -0,0 +1,87 @@
+# Puertas de Calidad (Quality Gates)
+
+## Cómo Mejoran el Framework
+
+Las puertas de calidad son **puntos de verificación obligatorios** entre fases del pipeline.
+Sin ellas, el pipeline avanza aunque haya problemas. Con ellas, cada fase DEBE cumplir
+criterios formales antes de pasar a la siguiente. Esto es clave para la **trazabilidad**.
+
+> Adaptado de Specular (pei9564/Specular → constitution.md §Quality Gates)
+> Alineado con spec-kit (github/spec-kit) — criterios de completitud y constitution check
+
+---
+
+## Las 6 Puertas
+
+| # | Puerta | Fase | Criterios |
+|---|--------|------|-----------|
+| 1 | **Completitud de Spec** | Después de `/especdev:especificar` | P1 tiene happy + sad path. Criterios de éxito definidos (≥2 medibles). Marcadores `[NECESITA CLARIFICACIÓN]` identificados |
+| 2 | **Estado de Spec** | Antes de `/especdev:planificar-tecnico` | Tag `@lista` presente. Specs `@borrador` NO pueden entrar a fase Plan |
+| 3 | **Verificación Clarify** | Después de `/especdev:clarificar` | Reporte Auto-QA sin ❌ FALLA. Todos los `[NECESITA CLARIFICACIÓN]` resueltos. Auditoría completada |
+| 4 | **Aprobación de Plan** | Después de `/especdev:planificar-tecnico` | Chequeo de constitución pasa (todos ✅). Contexto técnico completo. DBML ratificado. Tracking de complejidad documentado |
+| 5 | **Preparación de Tareas** | Después de `/especdev:desglosar` | Todas las tareas con IDs (`T###`). Rutas de archivos en tareas de implementación. Marcadores `[P]` de paralelismo asignados. 5 fases presentes |
+| 6 | **Merge de Código** | Después de `/especdev:implementar` | Tests verdes, lint limpio, type-check pasa, coverage ≥85%, sin diff no relacionado, regresión cross-fase pasa |
+
+## Verificación Automática
+
+Cada puerta se verifica automáticamente. Si falla, el framework **bloquea** el avance:
+
+```
+/especdev:especificar → [Puerta 1: ¿Completitud?]
+    ├── ✅ PASA → Continuar
+    └── ❌ FALLA → "Faltan escenarios sad path en P1" o "Criterios de éxito no definidos"
+
+/especdev:clarificar → [Puerta 2+3: ¿Estado? ¿Auto-QA?]
+    ├── ✅ PASA → Marcar @lista
+    └── ❌ FALLA → "Quedan 2 [NECESITA CLARIFICACIÓN] sin resolver"
+
+/especdev:planificar-tecnico → [Puerta 4: ¿Aprobación?]
+    ├── ✅ PASA → Continuar a tareas
+    └── ❌ FALLA → "Artículo III de constitución no cumplido" o "DBML provisional no ratificado"
+
+/especdev:desglosar → [Puerta 5: ¿Preparación?]
+    ├── ✅ PASA → Listo para implementar
+    └── ❌ FALLA → "Tarea T008 sin ruta de archivo" o "Falta Fase 5 (Verificación)"
+
+/especdev:implementar → [Puerta 6: ¿Merge?]
+    ├── ✅ PASA → Feature completa
+    └── ❌ FALLA → "3 tests fallan" o "Coverage 72% < 85%"
+```
+
+## Reporte de Puerta
+
+Cada puerta genera un reporte estructurado:
+
+```markdown
+## Puerta de Calidad: Completitud de Spec
+
+✅ PASS: P1 tiene happy path (Registro exitoso)
+✅ PASS: P1 tiene sad path (Email duplicado)
+✅ PASS: Criterios de éxito definidos (4 medibles)
+⚠️ WARNING: P2 solo tiene 1 escenario (recomendado: ≥2)
+✅ PASS: 3 marcadores [NECESITA CLARIFICACIÓN] identificados
+❌ FAIL: P3+ tiene escenario sin criterio de aceptación
+
+**Resultado: NO-AVANZAR (1 FAIL)**
+→ Acción requerida: Agregar Given/When/Then al escenario P3+ "Registro OAuth"
+```
+
+## Regresión Cross-Fase
+
+Al completar la Puerta 6 de una feature, se ejecuta **regresión automática** sobre features anteriores:
+
+```
+Feature actual: CrearUsuario (Puerta 6)
+  │
+  ├── Tests de CrearUsuario: ✅ 21/21
+  ├── Regresión: ListarProductos (feature anterior): ✅ 15/15
+  ├── Regresión: GestionarCarrito (feature anterior): ✅ 18/18
+  └── Resultado: ✅ SIN REGRESIÓN
+
+  ¿Algún test de feature anterior falla?
+  ├── NO → ✅ Puerta 6 pasa
+  └── SÍ → ❌ REGRESIÓN DETECTADA
+       └── Identificar qué test rompió y en qué feature
+```
+
+**Regla:** No se puede mergear código que rompe features anteriores. La regresión cross-fase es parte obligatoria de la Puerta 6.

package/scripts/.claude/don-cheli/reglas/reglas-desviacion.md

@@ -0,0 +1,36 @@
+# Reglas de Desviación
+
+## Las 5 Reglas
+
+Cuando encuentras algo inesperado durante la ejecución:
+
+| Regla | Disparador | Acción |
+|:-----:|-----------|--------|
+| **1** | Bug encontrado | 🔧 Auto-corregir inmediatamente |
+| **2** | Falta algo crítico (deps, config) | ➕ Auto-agregar inmediatamente |
+| **3** | Bloqueador (impide progreso) | 🚧 Auto-desbloquear inmediatamente |
+| **4** | Cambio arquitectónico | ⛔ **PARAR Y PREGUNTAR** |
+| **5** | Mejora (nice-to-have) | 📝 Registrar en ISSUES.md |
+
+## Distribución de Autonomía
+
+```
+AUTÓNOMO (solo hacerlo):
+├── Regla 1: Bug → Corregir
+├── Regla 2: Faltante → Agregar
+├── Regla 3: Bloqueador → Desbloquear
+└── Regla 5: Mejora → Registrar
+
+HUMANO REQUERIDO (parar y preguntar):
+└── Regla 4: Cambio arquitectónico
+```
+
+## Guía Rápida de Decisión
+
+```
+¿Puedo corregir esto en < 5 min sin cambiar cómo las cosas trabajan juntas?
+├── SÍ → Reglas 1, 2 o 3 (auto-manejar)
+└── NO → ¿Necesita una decisión de diseño?
+          ├── SÍ → Regla 4 (PARAR y PREGUNTAR)
+          └── NO → Regla 5 (Registrar y continuar)
+```

package/scripts/.claude/don-cheli/reglas/reglas-trabajo-globales.md

@@ -0,0 +1,171 @@
+# Reglas de Trabajo Globales
+
+## Cómo Mejoran el Framework
+
+Estas reglas establecen un **estándar profesional de desarrollo** que se aplica a todos los proyectos que usen Don Cheli. Mientras que la constitución define los *principios*, estas reglas definen las *prácticas* concretas. El framework las carga automáticamente y las aplica en cada sesión, eliminando la necesidad de repetir instrucciones manualmente.
+
+> **Uso:** Estas reglas se cargan automáticamente al ejecutar `/especdev:iniciar`. Se pueden personalizar por proyecto en `.especdev/config.yaml`.
+
+---
+
+## Principios Generales
+
+- Todo desarrollo debe ser **retrocompatible** a menos que se indique explícitamente lo contrario.
+- Responder de forma directa y concisa, sin preámbulos innecesarios.
+
+---
+
+## Idioma
+
+| Contexto | Idioma |
+|----------|--------|
+| Código (variables, funciones, comentarios) | **Inglés** |
+| Commits y PR descriptions | **Español** |
+| Respuestas al usuario | **Español** (salvo que pida otro) |
+| Documentación (spec.md, tech.md) | **Español** |
+
+---
+
+## Precedencia de Configuración
+
+```
+.especdev/config.yaml (proyecto) > reglas-trabajo-globales.md (framework)
+```
+
+Si el proyecto tiene su propio `.especdev/config.yaml` o `CLAUDE.md`, sus reglas **prevalecen** sobre este archivo en caso de conflicto.
+
+---
+
+## Contexto del Repositorio
+
+- Antes de empezar cualquier tarea, buscar y leer el `CLAUDE.md` del proyecto si existe.
+- Si el repo tiene un `docs/index.md`, consultarlo como mapa de navegación antes de buscar archivos sueltos.
+
+---
+
+## Branches y Naming
+
+| Tipo | Formato | Origen |
+|------|---------|--------|
+| Feature | `feature/<nombre-abreviado>` | `develop` (o rama principal) |
+| Fix | `fix/<nombre>` | `develop` |
+| Hotfix | `hotfix/<nombre>` | `main`/`production` |
+
+---
+
+## Commits
+
+```
+<type>: <descripción corta en español>
+```
+
+**Types válidos:** `feat`, `fix`, `hotfix`, `refactor`, `docs`, `test`, `chore`
+
+Ejemplo: `feat: agregar componente carrusel de productos`
+
+---
+
+## Tamaño de PRs
+
+- Un PR = **un único cambio lógico**.
+- Si el scope crece → proponer al usuario dividir en PRs incrementales.
+
+---
+
+## Documentación Obligatoria por PR
+
+| Tipo de PR | Documentación Requerida |
+|-----------|------------------------|
+| Feature con lógica de negocio o cambio de arquitectura | `spec.md` + `tech.md` en `/docs/specs/<feature>/` |
+| Feature menor (<3 archivos, sin lógica nueva) | Descripción del PR es suficiente |
+| Fixes, bumps de versión, config, wordings | **Exentos** de spec/tech |
+
+- Antes de redactar el spec, **aclarar todas las dudas con el usuario**.
+- Todo PR debe evaluar si los cambios requieren **actualizar `.md` existentes**.
+
+---
+
+## Cobertura de Código
+
+- Mínimo **85% de coverage** sobre el código introducido en el PR (unit tests).
+- El `.especdev/config.yaml` del proyecto puede definir otro umbral o eximirlo.
+
+---
+
+## Verificaciones de Calidad
+
+### Antes de cada commit
+- [ ] Ejecutar linter y corregir errores
+- [ ] Ejecutar tests y verificar que pasen
+- [ ] Verificar que compile sin errores
+
+### Antes de abrir PR (adicional)
+- [ ] Revisar diff completo: code smells, variables sin usar, imports innecesarios
+- [ ] Verificar coherencia con `spec.md` (si existe)
+- [ ] Verificar coverage mínimo sobre código introducido
+
+---
+
+## Tareas Complejas
+
+- Refactors >5 archivos, cambios de arquitectura o migraciones → **presentar plan y esperar confirmación** antes de ejecutar.
+- Paralelizar subtareas independientes siempre que sea posible.
+
+---
+
+## Límites de Autonomía
+
+| Situación | Acción |
+|-----------|--------|
+| Cambios afectan >10 archivos no previstos | **Confirmar con el usuario** |
+| Ambigüedad significativa | **Preguntar**, no asumir |
+| Test no pasa después de 2 intentos de fix | Reportar con error completo |
+| Dependencia no resuelve | Preguntar, no buscar workarounds |
+| Build falla por razones externas | Notificar y continuar |
+
+---
+
+## Subagentes y Selección de Modelos
+
+| Tipo de Tarea | Modelo |
+|--------------|--------|
+| Q&A, formateo, resúmenes, scripting, batch | `haiku` |
+| Código, bug fixes, tests, code review | `sonnet` |
+| Arquitectura, razonamiento complejo, seguridad | `opus` |
+
+**Reglas:**
+- **Default: Haiku.** Subir solo si la calidad del output es insuficiente.
+- **Nunca** usar Opus sin confirmación explícita del usuario.
+- Subtareas independientes → subagentes **en paralelo** (nunca secuenciales).
+- Subagente de exploración/búsqueda → siempre Haiku.
+
+---
+
+## Gestión de Contexto y Tokens
+
+- **Leer archivos bajo demanda**: no cargar lo que no sea necesario.
+- **No re-leer lo que ya está en contexto**: referenciar, no repetir.
+- **System prompts < 500 tokens**: mover reglas poco usadas a skills.
+- **Outputs estructurados desde el inicio**: JSON o formato concreto = menos iteraciones.
+- **Subagente para contexto grande**: si un resultado supera ~10K tokens, aislarlo en subagente.
+
+---
+
+## Dependencias
+
+- Antes de agregar una dependencia externa, buscar alternativas internas.
+- Si no existe alternativa, documentar la justificación en la descripción del PR.
+
+---
+
+## Seguridad
+
+- **Nunca** exponer credenciales en código fuente.
+- Usar siempre herramientas de gestión de secretos.
+
+---
+
+## Documentación Generada
+
+- Archivos `.md` concisos: preferir bullets sobre párrafos, máximo ~200 líneas.
+- No duplicar información entre archivos. Un dato en un solo lugar; en los demás, referenciar.

package/scripts/.claude/don-cheli/scripts/bucle.sh

@@ -0,0 +1,103 @@
+#!/bin/bash
+# Don Cheli - Bucle Autónomo
+# Ejecuta historias de usuario en contexto fresco hasta completar
+
+set -euo pipefail
+
+# Colores
+VERDE='\033[0;32m'
+AMARILLO='\033[1;33m'
+ROJO='\033[0;31m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+# Configuración
+HERRAMIENTA="${1:-claude}"
+MAX_ITERACIONES="${2:-10}"
+PRD_FILE=".especdev/sesion/prd.json"
+PROGRESO_FILE=".especdev/progreso.md"
+
+# Validate MAX_ITERACIONES is a positive integer
+if ! [[ "$MAX_ITERACIONES" =~ ^[0-9]+$ ]]; then
+    echo -e "${ROJO}Error: MAX_ITERACIONES debe ser un entero positivo, recibido: '$MAX_ITERACIONES'${NC}"
+    exit 1
+fi
+
+echo "╔═══════════════════════════════════════╗"
+echo "║       Don Cheli - Bucle Autónomo        ║"
+echo "╚═══════════════════════════════════════╝"
+echo ""
+
+# Verificar prerrequisitos
+if [ ! -f "$PRD_FILE" ]; then
+    echo -e "${ROJO}Error: $PRD_FILE no encontrado${NC}"
+    echo "Ejecuta /historias-generar primero para crear el PRD."
+    exit 1
+fi
+
+# Contar historias
+TOTAL=$(python3 -c "import json,sys; d=json.load(sys.stdin); print(len(d.get('historiasUsuario', d.get('userStories', []))))" < "$PRD_FILE" 2>/dev/null || echo "0")
+PENDIENTES=$(python3 -c "import json,sys; d=json.load(sys.stdin); stories=d.get('historiasUsuario', d.get('userStories', [])); print(len([s for s in stories if not s.get('pasa', s.get('passes', False))]))" < "$PRD_FILE" 2>/dev/null || echo "0")
+
+echo -e "${CYAN}=== Bucle Don Cheli Iniciado ===${NC}"
+echo "Herramienta: $HERRAMIENTA"
+echo "Historias: $PENDIENTES pendientes, $((TOTAL - PENDIENTES)) completadas"
+echo "Máximo iteraciones: $MAX_ITERACIONES"
+echo ""
+
+# Verificar si hay trabajo
+if [ "$PENDIENTES" -eq 0 ]; then
+    echo -e "${VERDE}Todas las historias ya están completadas. Nada que hacer.${NC}"
+    exit 0
+fi
+
+# Bucle principal
+for i in $(seq 1 "$MAX_ITERACIONES"); do
+    echo -e "${CYAN}--- Iteración $i/$MAX_ITERACIONES ---${NC}"
+    
+    # Seleccionar siguiente historia (sanitize: strip control chars)
+    HISTORIA_RAW=$(python3 -c "
+import json, sys, re
+d = json.load(sys.stdin)
+stories = d.get('historiasUsuario', d.get('userStories', []))
+for s in sorted(stories, key=lambda x: x.get('prioridad', x.get('priority', 99))):
+    if not s.get('pasa', s.get('passes', False)):
+        title = re.sub(r'[\x00-\x1f\x7f]', '', f\"{s.get('id', 'HU-???')} {s.get('titulo', s.get('title', 'Sin titulo'))}\")
+        print(title)
+        break
+" < "$PRD_FILE" 2>/dev/null)
+    HISTORIA="${HISTORIA_RAW:-}"
+    
+    if [ -z "$HISTORIA" ]; then
+        echo -e "${VERDE}=== COMPLETO ===${NC}"
+        echo "Todas las historias pasaron en $i iteraciones."
+        echo "Ver progreso: $PROGRESO_FILE"
+        exit 0
+    fi
+    
+    echo "Historia: $HISTORIA"
+    
+    # Ejecutar con el agente seleccionado (contexto fresco)
+    case "$HERRAMIENTA" in
+        claude)
+            echo "Ejecutando con Claude (contexto fresco)..."
+            # claude --print "Implementa la siguiente historia de usuario: $HISTORIA. Lee .especdev/sesion/prd.json para los criterios de aceptación." 2>/dev/null || true
+            ;;
+        codex)
+            echo "Ejecutando con Codex (contexto fresco)..."
+            ;;
+        amp)
+            echo "Ejecutando con Amp (contexto fresco)..."
+            ;;
+    esac
+    
+    # Registrar progreso
+    echo "### Iteración $i - $(date)" >> "$PROGRESO_FILE"
+    echo "- Historia: $HISTORIA" >> "$PROGRESO_FILE"
+    echo "" >> "$PROGRESO_FILE"
+    
+    echo ""
+done
+
+echo -e "${AMARILLO}Máximo de iteraciones ($MAX_ITERACIONES) alcanzado.${NC}"
+echo "Historias restantes pueden necesitar intervención manual."