sdd-es 2.0.0 → 2.6.0

package/skills/mutation-detector/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: mutation-detector
+model: claude-haiku-4-5
+description: Detecta mutaciones (cambios) en archivos para tracking de calidad
+allowed-tools: Read, Bash
+---
+
+# Skill: Mutation Detector
+
+**Propósito:** Analizar patrones de cambio en archivos para detectar inestabilidad y calcular defect escape rate.
+
+---
+
+## Cómo Funciona
+
+### Ledger de Mutaciones
+
+Cada vez que un agente modifica un archivo (Write, Edit, MultiEdit), el hook registra:
+```json
+{
+  "ts": "2026-06-14T10:30:00Z",
+  "agente": "backend-dev",
+  "archivo": "src/auth.ts",
+  "tool": "Edit",
+  "tipo": "partial"
+}
+```
+
+**Campo `tipo`:**
+- `full` — Write (archivo nuevamente escrito desde cero)
+- `partial` — Edit (cambios parciales al archivo)
+
+### Análisis de Estabilidad
+
+Mutation Detector agrupa por archivo:
+```
+src/auth.ts:
+  - Mutación 1: backend-dev (full)    2026-06-10 10:00
+  - Mutación 2: backend-dev (partial) 2026-06-11 14:30
+  - Mutación 3: tester-qa (partial)   2026-06-11 15:00 (test fail)
+  
+Análisis:
+  - Total mutaciones: 3
+  - Autor principal: backend-dev
+  - Estabilidad: INESTABLE (3 cambios en 2 días)
+  - Defect finder: tester-qa encontró 1 bug
+```
+
+---
+
+## Defect Escape Rate
+
+**Fórmula:**
+```
+Defect Escape Rate = (Bugs encontrados) / (Total bugs presentes)
+
+Ejemplo:
+- Backend Dev escribió src/auth.ts
+- QA ejecutó tests, encontró 4 bugs
+- En producción: 1 bug adicional
+
+Escape Rate = 1 / 5 = 20%
+```
+
+**Tabla por agente:**
+```
+AGENTE         | ARCHIVOS | BUGS ENCONTRADOS | BUGS EN PROD | ESCAPE RATE
+───────────────┼──────────┼──────────────────┼─────────────┼──────────
+backend-dev    | 12       | 4                | 1           | 20%
+frontend-dev   | 8        | 0                | 0           | N/A
+tester-qa      | —        | 4 encontrados    | —           | 100% accuracy
+```
+
+---
+
+## Output: Comando `/sdd.defect-report`
+
+**Resumen ejecutivo:**
+```
+DEFECT REPORT — Sesión 2026-06-14
+
+Archivos modificados: 12
+Bugs encontrados (QA): 4
+Bugs en producción (post-release): 1
+─────────────────────────────────
+Global Escape Rate: 20% (1 de 5)
+
+Por agente:
+  backend-dev:   4 archivos, 3 bugs encontrados → 75% quality score
+  frontend-dev:  8 archivos, 1 bug encontrado   → 88% quality score
+  tester-qa:     Encontró 4 bugs (100% accuracy)
+```
+
+---
+
+## Implementación Técnica
+
+### Ledger: `.sdd/observabilidad/mutaciones.jsonl`
+
+Append-only JSONL donde cada línea es una mutación:
+```json
+{"ts":"2026-06-14T10:30:00Z","agente":"backend-dev","archivo":"src/auth.ts","tool":"Edit","tipo":"partial"}
+{"ts":"2026-06-14T10:35:00Z","agente":"backend-dev","archivo":"src/auth.ts","tool":"Write","tipo":"full"}
+{"ts":"2026-06-14T15:00:00Z","agente":"tester-qa","archivo":"src/auth.test.ts","tool":"Write","tipo":"full"}
+```
+
+### Agregación por archivo
+
+```javascript
+const mutacionesPorArchivo = {};
+for (const mut of mutaciones) {
+  if (!mutacionesPorArchivo[mut.archivo]) {
+    mutacionesPorArchivo[mut.archivo] = [];
+  }
+  mutacionesPorArchivo[mut.archivo].push(mut);
+}
+```
+
+### Cálculo de Inestabilidad
+
+```
+Si archivo tiene >2 mutaciones en <24h → INESTABLE
+Si archivo tiene >5 mutaciones → CRÍTICO
+```
+
+---
+
+## Notas
+
+- Fase 1 (v2.6.0): Solo tracking + informe simple
+- Fase 2 (v2.6.1): Dashboard con gráficos
+- Ledger append-only: nunca sobrescrito, histórico completo
+- Reversible: puedes recalcular estadísticas en cualquier momento
+

package/skills/observabilidad-consumo/SKILL.md

@@ -0,0 +1,164 @@
+---
+description: Lee .sdd/observabilidad/consumo.jsonl y genera un reporte de actividad de agentes — invocaciones por agente, archivos tocados, picos y señales de fan-out excesivo. Referencia cruzada con orquestacion-ptc y compresion-tokens.
+model: haiku
+allowed-tools: Read, Bash
+---
+
+# Skill: Observabilidad de Consumo
+
+## Propósito
+
+Convertir el ledger de consumo en información accionable: ver cuántos agentes se activaron, qué archivos tocaron, en qué momentos hubo picos de actividad y si hay señales de fan-out excesivo que conviene corregir.
+
+El ledger es un proxy de magnitud (bytes escritos), no una facturación exacta de tokens — Claude Code no expone el conteo real de tokens al hook. Pero es suficiente para detectar patrones problemáticos.
+
+---
+
+## Lo que lees
+
+```bash
+# Ledger completo
+cat .sdd/observabilidad/consumo.jsonl 2>/dev/null || echo "SIN_LEDGER"
+
+# Conteo rápido de líneas
+wc -l .sdd/observabilidad/consumo.jsonl 2>/dev/null || echo "0"
+```
+
+---
+
+## Análisis que produces
+
+### 1. Resumen por agente
+
+```
+node -e "
+const fs = require('fs');
+const path = '.sdd/observabilidad/consumo.jsonl';
+if (!fs.existsSync(path)) { console.log('Sin datos aún.'); process.exit(0); }
+
+const lineas = fs.readFileSync(path, 'utf8').trim().split('\n').filter(Boolean);
+const porAgente = {};
+for (const l of lineas) {
+  try {
+    const e = JSON.parse(l);
+    const a = e.agente || 'main';
+    if (!porAgente[a]) porAgente[a] = { invocaciones: 0, bytes: 0, archivos: new Set() };
+    porAgente[a].invocaciones++;
+    porAgente[a].bytes += e.bytes || 0;
+    porAgente[a].archivos.add(e.archivo);
+  } catch {}
+}
+
+console.log('AGENTE              | INVOC | BYTES  | ARCHIVOS ÚNICOS');
+console.log('-'.repeat(60));
+for (const [a, d] of Object.entries(porAgente).sort((x,y) => y[1].invocaciones - x[1].invocaciones)) {
+  console.log(\`\${a.padEnd(19)} | \${String(d.invocaciones).padStart(5)} | \${String(d.bytes).padStart(6)} | \${d.archivos.size}\`);
+}
+console.log('');
+console.log('Total eventos:', lineas.length);
+"
+```
+
+### 2. Detección de fan-out excesivo
+
+Umbrales por defecto (ajustables en `.sdd/sdd.config.yaml`):
+
+| Señal | Umbral | Acción sugerida |
+|-------|--------|-----------------|
+| >5 agentes distintos en una fase | Alto | Revisar si la orquestación PTC puede colapsar en menos agentes |
+| >20 invocaciones de un mismo agente | Medio | Revisar si el agente entra en loop o hace trabajo redundante |
+| >500 KB de bytes escritos totales | Informativo | Considerar comprimir memoria con `compresion-tokens` |
+
+```
+node -e "
+const fs = require('fs');
+const path = '.sdd/observabilidad/consumo.jsonl';
+if (!fs.existsSync(path)) process.exit(0);
+
+const lineas = fs.readFileSync(path, 'utf8').trim().split('\n').filter(Boolean);
+const agentes = new Set();
+const invocPorAgente = {};
+let bytesTotal = 0;
+
+for (const l of lineas) {
+  try {
+    const e = JSON.parse(l);
+    const a = e.agente || 'main';
+    agentes.add(a);
+    invocPorAgente[a] = (invocPorAgente[a] || 0) + 1;
+    bytesTotal += e.bytes || 0;
+  } catch {}
+}
+
+const alertas = [];
+if (agentes.size > 5) alertas.push('⚠️  Fan-out alto: ' + agentes.size + ' agentes distintos activos');
+for (const [a, n] of Object.entries(invocPorAgente)) {
+  if (n > 20) alertas.push('⚠️  Agente en loop posible: ' + a + ' (' + n + ' invocaciones)');
+}
+if (bytesTotal > 500_000) alertas.push('ℹ️  Escritura alta: ' + Math.round(bytesTotal/1024) + ' KB — considera compresion-tokens');
+
+if (alertas.length === 0) {
+  console.log('✅ Sin alertas de fan-out');
+} else {
+  for (const a of alertas) console.log(a);
+}
+"
+```
+
+### 3. Picos de actividad (top 5 momentos)
+
+```
+node -e "
+const fs = require('fs');
+const path = '.sdd/observabilidad/consumo.jsonl';
+if (!fs.existsSync(path)) process.exit(0);
+
+const lineas = fs.readFileSync(path, 'utf8').trim().split('\n').filter(Boolean);
+const parsed = lineas.map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+
+// Agrupar por minuto
+const porMinuto = {};
+for (const e of parsed) {
+  const minuto = e.ts?.slice(0,16) || 'desconocido';
+  porMinuto[minuto] = (porMinuto[minuto] || 0) + 1;
+}
+
+const top = Object.entries(porMinuto).sort((a,b) => b[1] - a[1]).slice(0, 5);
+console.log('TOP 5 MINUTOS DE MAYOR ACTIVIDAD:');
+for (const [m, n] of top) console.log('  ' + m + '  →  ' + n + ' eventos');
+"
+```
+
+---
+
+## Formato del reporte completo
+
+```
+╔══════════════════════════════════════════════════════╗
+║         📊 CONSUMO DE AGENTES — SDD-ES               ║
+╠══════════════════════════════════════════════════════╣
+║  AGENTE              | INVOC | BYTES  | ARCHIVOS     ║
+║  [tabla generada]                                    ║
+╠══════════════════════════════════════════════════════╣
+║  ALERTAS DE FAN-OUT                                  ║
+║  [alertas o "✅ Sin alertas"]                        ║
+╠══════════════════════════════════════════════════════╣
+║  TOP MOMENTOS DE ACTIVIDAD                           ║
+║  [top 5 minutos]                                     ║
+╠══════════════════════════════════════════════════════╣
+║  RECOMENDACIONES                                     ║
+║  → Si fan-out alto: revisar skill orquestacion-ptc   ║
+║  → Si bytes altos:  ejecutar /sdd.comprimir          ║
+║  → Si loop agente:  revisar el agente con /sdd.estado║
+╚══════════════════════════════════════════════════════╝
+```
+
+---
+
+## Notas
+
+- El ledger se escribe en tiempo real por el hook `agent-memory.js` (PostToolUse)
+- Los `bytes` miden el contenido de cada escritura — son un **proxy de magnitud**, no el consumo real de tokens del modelo
+- Para vaciar el ledger al inicio de una sesión nueva: `echo "" > .sdd/observabilidad/consumo.jsonl`
+- Cruzar con `orquestacion-ptc` para decidir cuándo paralelizar vs. serializar agentes
+- Cruzar con `compresion-tokens` para decidir cuándo comprimir los archivos `.sdd/memoria/`

package/skills/token-budget/SKILL.md

@@ -0,0 +1,177 @@
+---
+description: Dado el estado actual del proyecto (fase, tareas pendientes, historial de consumo), estima el presupuesto de tokens por fase restante y recomienda si usar PTC paralelo o serial. Reutiliza criterios de orquestacion-ptc para la recomendación de paralelización.
+model: haiku
+allowed-tools: Read
+---
+
+# Skill: Token Budget
+
+## Propósito
+
+Antes de lanzar una fase costosa (planificación, análisis 7-dimensiones, implementación de 10+ tareas), esta skill proyecta el costo estimado en tokens y recomienda la estrategia de ejecución más eficiente. Evita sorpresas de presupuesto a mitad de un proyecto largo.
+
+---
+
+## Lo que lees
+
+```bash
+# Estado general del proyecto
+cat .sdd/estado.json
+
+# Tareas pendientes de la spec activa
+SPEC_ID=$(grep -o '"especificacion_activa": "[^"]*"' .sdd/estado.json 2>/dev/null | cut -d'"' -f4)
+[ -n "$SPEC_ID" ] && cat ".sdd/especificaciones/${SPEC_ID}/.estado-tareas.json" 2>/dev/null
+
+# Historial de consumo (para calcular velocidad real de la sesión)
+cat .sdd/observabilidad/consumo.jsonl 2>/dev/null | tail -50 || echo "SIN_HISTORIAL"
+
+# Configuración de agentes habilitados
+cat .sdd/sdd.config.yaml 2>/dev/null | head -30 || echo "SIN_CONFIG"
+```
+
+---
+
+## Modelo de estimación
+
+### Costos de referencia por fase (en unidades de "peso relativo")
+
+Las unidades son relativas entre sí — no son tokens reales, ya que Claude Code no expone el conteo exacto. Se calibran con los datos del ledger si están disponibles.
+
+| Fase | Agentes activos | Peso base | Factor por tarea |
+|---|---|---|---|
+| `especificacion` | arquitecto (Opus) | 8 | +1 por cada requisito ambiguo |
+| `aclaracion` | ninguno dedicado | 2 | fijo |
+| `checklist` | ninguno dedicado | 2 | fijo |
+| `planificacion` | arquitecto, critico (Opus) | 10 | +2 por cada riesgo identificado |
+| `tareas` | ninguno dedicado | 3 | +0.5 por tarea a generar |
+| `analisis` (7 dims) | critico, seguridad (Opus) | 12 | fijo (siempre 7 dimensiones) |
+| `implementacion` | 1-5 agentes (Sonnet) | 4 | ×N tareas pendientes |
+| `verificacion` | ninguno dedicado | 4 | ×N CAs a verificar |
+| `qa` | tester (Sonnet) | 5 | ×N flows a probar |
+| `deploy` | operaciones (Haiku) | 2 | fijo |
+
+### Calibración con ledger histórico
+
+Si existe `consumo.jsonl` con datos de la sesión actual:
+
+```
+node -e "
+const fs = require('fs');
+const path = '.sdd/observabilidad/consumo.jsonl';
+if (!fs.existsSync(path)) { console.log('SIN_DATOS'); process.exit(0); }
+
+const lineas = fs.readFileSync(path, 'utf8').trim().split('\n').filter(Boolean);
+const parsed = lineas.map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+
+// Bytes totales por fase (agrupando por agente que los escribió)
+const porAgente = {};
+for (const e of parsed) {
+  const a = e.agente || 'main';
+  porAgente[a] = (porAgente[a] || 0) + (e.bytes || 0);
+}
+
+const totalBytes = Object.values(porAgente).reduce((s,v) => s+v, 0);
+console.log('Bytes totales sesión: ' + totalBytes);
+console.log('Velocidad promedio: ' + Math.round(totalBytes / lineas.length) + ' bytes/evento');
+console.log('Eventos totales: ' + lineas.length);
+"
+```
+
+Usar la velocidad promedio como factor de calibración: si el historial muestra >1000 bytes/evento, los pesos base ×1.5.
+
+---
+
+## Recomendación de paralelización (reutiliza orquestacion-ptc)
+
+Regla del criterio de independencia (de `orquestacion-ptc`):
+
+**Usar PTC paralelo cuando:**
+- Las tareas no se bloquean entre sí (salida de A no es entrada de B)
+- Hay ≥3 tareas del mismo tipo para el mismo agente
+- Las tareas son verificaciones (sin efectos secundarios que se pisen)
+- Ahorro esperado: −70 a −85% en tokens del orquestador
+
+**Usar serial cuando:**
+- La tarea N+1 depende del resultado de la tarea N
+- Son acciones sobre infraestructura (migrations, deploys) donde el orden importa
+- Solo hay 1-2 tareas (overhead de PTC no vale)
+
+Para la fase `implementacion` con N tareas pendientes:
+
+| N tareas pendientes | Estrategia recomendada | Ahorro estimado |
+|---|---|---|
+| 1-2 | Serial (directo) | — |
+| 3-5 independientes | PTC paralelo (lote de 3-5) | ~70% |
+| 6-10 independientes | PTC en 2 lotes de 5 | ~65% |
+| >10 independientes | PTC en lotes de 5 + agrupación por agente | ~60% |
+| Cualquier N con deps | Serial (respetar grafo de dependencias) | — |
+
+---
+
+## Señal de alerta: presupuesto proyectado < 20%
+
+Tras calcular el peso total estimado de las fases restantes y compararlo con el presupuesto disponible (calibrado con el ledger), si **el presupuesto proyectado restante cae por debajo del 20%**, emite una alerta destacada antes de cualquier recomendación:
+
+```
+⚠️  ALERTA DE PRESUPUESTO — proyección < 20% disponible
+
+   Presupuesto proyectado restante: {X}%  (umbral crítico: 20%)
+   Fases que aún no caben con el margen actual: {lista}
+
+   ACCIONES RECOMENDADAS (de mayor a menor impacto):
+   1. Ejecutar /sdd.comprimir aplicar para liberar contexto ahora.
+   2. Degradar modelos con effort-router en las fases restantes.
+   3. Paralelizar con PTC las tareas independientes (ahorro del orquestador).
+   4. Dividir la fase de implementación: ejecutar por lotes y comprimir entre lotes.
+```
+
+Cómo se calcula el porcentaje proyectado: `(peso_disponible − peso_total_estimado_fases_restantes) / peso_disponible × 100`. Si no hay historial para fijar `peso_disponible`, usa el umbral conservador del ledger (velocidad observada × eventos restantes estimados) y marca la alerta como **estimación sin calibrar**.
+
+La alerta es informativa y no bloquea: el usuario decide. Pero debe mostrarse SIEMPRE que la proyección cruce el umbral del 20%.
+
+---
+
+## Output que produces
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║           💰 TOKEN BUDGET — Proyección de Fases Restantes        ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Fase actual: {fase}  |  Spec: {SPEC_ID}                        ║
+╠══════════════════════════════════════════════════════════════════╣
+║  FASES RESTANTES      | PESO EST. | ESTRATEGIA    | AGENTES     ║
+║  ─────────────────────┼───────────┼───────────────┼──────────── ║
+║  implementacion       | ████ 40   | PTC × 3 lotes | 3 agentes   ║
+║    └─ {N} tareas pend.|           | serial internamente         ║
+║  verificacion         | ██ 16     | Serial (deps) | —           ║
+║  qa                   | ██ 10     | PTC × flows   | tester      ║
+║  deploy               | █ 4       | Serial        | operaciones ║
+║  ─────────────────────┼───────────┼───────────────┼──────────── ║
+║  TOTAL ESTIMADO       | ████████  | 70            |             ║
+╠══════════════════════════════════════════════════════════════════╣
+║  📊 CALIBRACIÓN CON HISTORIAL                                    ║
+║                                                                  ║
+║  {datos del ledger o "Sin historial — usando pesos base"}        ║
+╠══════════════════════════════════════════════════════════════════╣
+║  🚀 RECOMENDACIÓN DE EJECUCIÓN                                   ║
+║                                                                  ║
+║  1. {fase más costosa}: usar effort-router para degradar         ║
+║     modelos donde sea posible (ahorro ~{%}% estimado)            ║
+║                                                                  ║
+║  2. {fase con tareas independientes}: usar PTC con lotes         ║
+║     de {N} → comando: /sdd.implementar ptc={N}                   ║
+║                                                                  ║
+║  3. Si el presupuesto es ajustado: comprimir memoria antes       ║
+║     de lanzar la fase de implementación                          ║
+╚══════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Notas
+
+- Los pesos son relativos, no tokens reales. Claude Code no expone el conteo exacto de tokens al contexto.
+- La calibración con el ledger mejora la precisión: si la sesión actual ya tiene datos, los pesos se ajustan a la velocidad real observada.
+- Para proyectos con presupuesto de API estricto, usar junto con `effort-router` para maximizar el ahorro antes de lanzar fases costosas.
+- Esta skill se invoca desde `/sdd.optimizar presupuesto` y como PASO 6 de `/sdd.optimizar`.
+- Reutiliza los criterios de independencia de `orquestacion-ptc` — si esa skill tiene más detalle sobre cuándo paralelizar, referenciarlo directamente.