sdd-es 2.5.0 → 2.6.0

package/claude-hooks/pre-tool-guard.js

@@ -14,6 +14,8 @@
  */
 
 import { createInterface } from "node:readline";
+import { existsSync, mkdirSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
 
 const rl = createInterface({ input: process.stdin, terminal: false });
 let raw = "";
@@ -116,14 +118,36 @@ function main(raw) {
   const cmd = String(toolInput?.command ?? "").trim();
   if (!cmd) process.exit(0);
 
+  // ── 0. NUEVO: Verificar permisos por agente ─────────────────────────────
+  const agentName = process.env.CLAUDE_AGENT_NAME;
+  if (agentName) {
+    // Agentes read-only que NO pueden usar Write/Edit
+    const readOnlyAgents = [
+      'arquitecto', 'asesor-datos', 'critico', 'seguridad',
+      'investigador', 'revisor', 'disenador-api'
+    ];
+
+    // Si es agente read-only e intenta usar Write/Edit, bloquea
+    if (readOnlyAgents.includes(agentName) &&
+        (toolName === 'Write' || toolName === 'Edit')) {
+      process.stderr.write(
+        `FORGE detuvo esta acción: el agente "${agentName}" solo puede leer, no modificar archivos.\n` +
+        `Si necesitas que este agente escriba código, cambia su rol en la configuración.\n`
+      );
+      process.exit(2);
+    }
+
+    // Auditoría de intentos de tool por agente (log a .sdd/observabilidad/)
+    logAgentToolAttempt(agentName, toolName, cmd);
+  }
+
   // ── 1. Verificar prohibidos ─────────────────────────────────────────────
   for (const re of PROHIBIDOS) {
     if (re.test(cmd)) {
       process.stderr.write(
-        `🚫 BLOQUEADO por guardia de seguridad SDD-ES\n` +
-        `   Comando: ${cmd.slice(0, 120)}\n` +
-        `   Razón: coincide con patrón prohibido (${re.source.slice(0, 60)})\n` +
-        `   Esta operación nunca debe ejecutarse automáticamente.\n`
+        `FORGE evitó esta acción porque podría borrar o dañar archivos importantes de forma irreversible.\n` +
+        `Si estás completamente seguro de lo que haces, ejecuta el comando manualmente en tu terminal.\n` +
+        `Comando bloqueado: ${cmd.slice(0, 120)}\n`
       );
       process.exit(2);
     }
@@ -133,9 +157,9 @@ function main(raw) {
   for (const re of SECRET_PATTERNS) {
     if (re.test(cmd)) {
       process.stderr.write(
-        `🚫 BLOQUEADO — secret hardcodeado detectado en el comando\n` +
-        `   Patrón: ${re.source.slice(0, 60)}\n` +
-        `   Usa variables de entorno o un secret manager.\n`
+        `FORGE detectó que este comando incluye una contraseña o clave secreta escrita directamente.\n` +
+        `Para proteger tu seguridad, usa variables de entorno en lugar de escribir credenciales en el código.\n` +
+        `Ejemplo: usa process.env.MI_CLAVE en vez de escribir el valor directamente.\n`
       );
       process.exit(2);
     }
@@ -146,8 +170,8 @@ function main(raw) {
     if (re.test(cmd)) {
       // Escribir a stderr — Claude Code lo muestra como contexto antes de pedir permiso
       process.stderr.write(
-        `⚠️  Operación sensible detectada: ${msg}\n` +
-        `   Comando: ${cmd.slice(0, 120)}\n`
+        `Atención: esto va a realizar una acción que no se puede deshacer fácilmente (${msg}).\n` +
+        `Revisa el comando antes de confirmar: ${cmd.slice(0, 120)}\n`
       );
       // Exit 0 — dejamos que el flujo normal de permisos de Claude Code actúe
       process.exit(0);
@@ -157,3 +181,31 @@ function main(raw) {
   // Todo bien
   process.exit(0);
 }
+
+/**
+ * Registra intentos de tool por agente para auditoría
+ */
+function logAgentToolAttempt(agentName, toolName, cmd) {
+  try {
+    // Intenta grabar en .sdd/observabilidad/ en formato JSONL (append-only)
+    const auditDir = '.sdd/observabilidad';
+    const auditFile = join(auditDir, 'agent-tool-audit.jsonl');
+
+    // Crea dir si no existe
+    if (!existsSync(auditDir)) {
+      mkdirSync(auditDir, { recursive: true });
+    }
+
+    const record = {
+      timestamp: new Date().toISOString(),
+      agent: agentName,
+      tool: toolName,
+      cmd_preview: cmd.slice(0, 120),
+      pid: process.pid
+    };
+
+    appendFileSync(auditFile, JSON.stringify(record) + '\n', 'utf8');
+  } catch {
+    // Silenciosamente ignorar fallos de auditoría (no bloquear ejecución)
+  }
+}

package/commands/sdd.adr.md

@@ -0,0 +1,196 @@
+---
+description: Indexar, listar y gestionar decisiones arquitectónicas (ADRs)
+allowed-tools: Read, Write, Bash
+---
+
+# /sdd.adr
+
+Gestiona Architecture Decision Records (ADRs) — registro de decisiones arquitectónicas.
+
+## Modos
+
+### `/sdd.adr list`
+
+Lista todas las decisiones registradas.
+
+```
+ID | DECISION                  | CONTEXT            | STATUS
+───┼───────────────────────────┼────────────────────┼──────────
+1  | Use PostgreSQL            | ACID needed        | accepted
+2  | Cache with Redis          | Performance        | accepted
+3  | JWT for auth              | Stateless API      | accepted
+4  | Validate user input       | Security           | accepted
+5  | HTTPS only                | Compliance         | accepted
+```
+
+**Opciones:**
+```
+/sdd.adr list --status=accepted      # Solo aceptadas
+/sdd.adr list --status=rejected       # Solo rechazadas
+/sdd.adr list --status=deprecated     # Obsoletas
+```
+
+---
+
+### `/sdd.adr new`
+
+Captura una nueva decisión de forma interactiva.
+
+```
+Pregunta 1: ¿Cuál es la decisión?
+> Use DynamoDB para analytics
+
+Pregunta 2: ¿Por qué? (contexto)
+> Scale infinitamente, baja latencia de queries
+
+Pregunta 3: ¿Qué alternativas consideraste?
+> PostgreSQL partitioning, BigQuery, Redshift
+
+Pregunta 4: ¿Status? (accepted/rejected/deprecated/superseded)
+> accepted
+
+✅ ADR guardado en .sdd/arquitectura/ADRs.jsonl
+```
+
+---
+
+### `/sdd.adr search "patrón"`
+
+Busca ADRs por palabra clave.
+
+```
+/sdd.adr search "database"
+
+RESULTADO:
+ID | DECISION              | CONTEXT
+───┼───────────────────────┼────────────────
+1  | Use PostgreSQL        | ACID needed
+2  | Use Redis cache       | Performance
+
+/sdd.adr search "security"
+
+RESULTADO:
+ID | DECISION                  | CONTEXT
+───┼───────────────────────────┼──────────────────
+3  | Validate user input       | Prevent injection
+4  | HTTPS only                | Compliance
+```
+
+---
+
+### `/sdd.adr edit [ID]`
+
+Editar una decisión existente.
+
+```
+/sdd.adr edit 1
+
+ADR #1: Use PostgreSQL
+Context: ACID needed
+Alternatives: MongoDB, Firebase
+Status: accepted
+
+¿Modificar? (y/n) > y
+Nuevo status: deprecated
+
+✅ ADR #1 actualizado
+```
+
+---
+
+## Ficheros
+
+**Ledger:** `.sdd/arquitectura/ADRs.jsonl` (append-only)
+
+Cada línea es un ADR en JSON:
+```json
+{
+  "ts": "2026-06-14T10:30:00Z",
+  "decision": "Use PostgreSQL",
+  "context": "ACID transactions required",
+  "alternatives": ["MongoDB", "Firebase"],
+  "status": "accepted",
+  "archivo": "src/database.ts",
+  "linea": 42,
+  "agente": "arquitecto"
+}
+```
+
+---
+
+## Uso en Auditoría
+
+**Para auditor externo:**
+
+```bash
+/sdd.adr list --status=accepted
+→ Todas las decisiones aceptadas documentadas
+
+/sdd.adr search "security"
+→ Todas las decisiones de seguridad con contexto
+
+/sdd.adr search "compliance"
+→ Todas las decisiones de compliance (GDPR, PCI-DSS, etc.)
+```
+
+**Resultado:** Auditor confía porque ve trazabilidad completa.
+
+---
+
+## Batch Scan
+
+Para proyectos existentes, scan automático:
+
+```bash
+node utils/adr-parser.js . src/**/*.ts --update-ledger
+→ Encuentra todos los ADRs en codebase
+→ Añade al ledger si no existen
+```
+
+---
+
+## Ejemplo Real
+
+### Código con ADR Incrustado
+
+```typescript
+// ADR: {"decision": "Use TypeScript", "context": "Type safety, IDE support", "status": "accepted"}
+import * as express from "express";
+
+// ADR: {"decision": "Use dependency injection", "context": "Testability", "status": "accepted"}
+class Database {
+  constructor(private config: Config) {}
+}
+
+// ADR: {"decision": "Validate all inputs with Zod", "context": "Security", "status": "accepted"}
+const userSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8)
+});
+```
+
+### Ejecutar Scan
+
+```bash
+/sdd.adr new  (o node utils/adr-parser.js . src/**/*.ts)
+↓
+✅ 3 ADRs encontrados y registrados
+```
+
+### Verificar
+
+```bash
+/sdd.adr list
+→ Ver todas las decisiones documentadas
+```
+
+---
+
+## Notas
+
+- **Automático:** Hook captura ADRs al escribir código
+- **Manual:** `/sdd.adr new` para decisiones no en código
+- **Buscable:** `/sdd.adr search` por palabra clave
+- **Auditables:** Cada ADR tiene timestamp, autor, contexto
+- **Seguro:** JSON validado, error silencioso si inválido
+

package/commands/sdd.ayuda.md

@@ -61,12 +61,23 @@ Muestra esta guía formateada:
    /sdd.release --preview            Ver qué entraría sin modificar nada
 
 🏭 FÁBRICA (idea → producto instalable)
+   /sdd.interpretar [idea]           Interpretar idea en bruto y generar IR (Interpreted Requirement)
+   /sdd.diseñar                      Elegir dirección visual y generar ProductDesign
+   /sdd.construir                    Pipeline completo automático: diseño + código + deploy
+   /sdd.exportar                     Empaquetar el proyecto actual como bundle descargable
    /sdd.crear-app [idea]             Generar app web o CLI desde una descripción en lenguaje natural
    /sdd.crear-mcp [descripción]      Generar servidor MCP empaquetado (.mcpb) desde una descripción
 
+🏛️  CALIDAD Y COMPLIANCE
+   /sdd.compliance                   Reporte de cumplimiento regulatorio (GDPR, SOC2, ISO 27001, HIPAA)
+   /sdd.adr                          Registrar decisión de arquitectura (Architecture Decision Record)
+   /sdd.defect-report                Reporte de defectos y tasa de bugs del proyecto
+
 ⚙️  UTILIDADES
    /sdd.mapear                       Indexar estructura, símbolos y dependencias del proyecto
    /sdd.comprimir                    Comprimir archivos de memoria para ahorrar tokens
+   /sdd.optimizar                    Optimizar artefactos SDD para reducir uso de contexto
+   /sdd.optimizar-memoria            Compactar la memoria del agente activo
 
 ═══════════════════════════════════════════════════════════════════════
   🔄 FLUJOS RECOMENDADOS
@@ -110,6 +121,8 @@ FLUJO CALIDAD MÁXIMA (features grandes, producto enterprise)
 
 DISEÑO Y ARQUITECTURA
    arquitecto             Decisiones técnicas, diseño de alto nivel
+   product-designer       Diseño de producto: pantallas, user flow, MVP
+   architecture-designer  Stack técnico: frontend, backend, BD, deploy
    disenador-api          Contratos: OpenAPI, GraphQL, gRPC, eventos
    asesor-datos           Esquemas, queries, índices, migraciones
 

package/commands/sdd.compliance.md

@@ -1,3 +1,8 @@
+---
+description: Genera reporte de cumplimiento regulatorio (GDPR, SOC2, ISO 27001, HIPAA) contra el estado actual del proyecto.
+allowed-tools: Read, Bash
+---
+
 # /sdd.compliance — Reporte de Cumplimiento Regulatorio
 
 ## Descripción

package/commands/sdd.configurar.md

@@ -60,7 +60,7 @@ Calidad: cobertura 75% · warnings: no · funciones ≤50 líneas
 ¿Aplicar este preset? Los valores que hayas personalizado se sobreescribirán.
 ```
 
-Si el usuario confirma, mezcla los valores del preset sobre el `sdd.config.yaml` existente (preserva secciones como `figma:`, `mapeos:`, `compresion:` que el preset no toca).
+Si el usuario confirma, mezcla los valores del preset sobre el `sdd.config.yaml` existente (preserva secciones como `mapeos:`, `compresion:` que el preset no toca).
 
 ## PASO 3 — Modo: Mostrar
 

package/commands/sdd.crear-mcp.md

@@ -12,6 +12,8 @@ handoffs:
 
 Eres el **Generador de MCP**. Tomas una descripción en lenguaje natural y produces un servidor MCP completo: tools definidas, empaquetado, instrucciones de instalación de una línea. El resultado lo puede instalar alguien que no sabe programar.
 
+> **MCP integrado en v2.6.0:** Playwright (navegación y QA automatizado).
+
 ## PASO 1 — Entender qué capacidades se quieren publicar
 
 Lee el argumento del comando. Si el usuario escribió algo como:

package/commands/sdd.defect-report.md

@@ -0,0 +1,134 @@
+---
+description: Generar reporte de calidad con escape rate y mutaciones
+allowed-tools: Read, Bash
+---
+
+# /sdd.defect-report
+
+Genera un reporte de calidad basado en mutaciones (cambios) de archivos encontrados por QA.
+
+## Uso
+
+```
+/sdd.defect-report
+```
+
+## Qué Muestra
+
+### Resumen Ejecutivo
+
+```
+╔═══════════════════════════════════════════════════════════╗
+║         DEFECT ESCAPE RATE REPORT — 2026-06-14           ║
+╠═══════════════════════════════════════════════════════════╣
+║                                                           ║
+║  Archivos modificados:  12                                ║
+║  Bugs encontrados (QA): 4                                 ║
+║  Bugs en producción:    1                                 ║
+║  ─────────────────────────────────────                    ║
+║  Global Escape Rate:    20% (1 de 5)                      ║
+║                                                           ║
+║  Interpretación:                                          ║
+║    ✅ Muy bien  (1-10%): Calidad excelente               ║
+║    ⚠️  OK       (11-30%): Calidad buena                  ║
+║    🔴 Malo     (31%+):   Calidad baja                    ║
+║                                                           ║
+╚═══════════════════════════════════════════════════════════╝
+```
+
+### Por Agente
+
+```
+AGENTE         | ARCHIVOS | MUTACIONES | BUGS ENCONTRADOS | QUALITY
+───────────────┼──────────┼────────────┼──────────────────┼─────────
+backend-dev    | 12       | 15         | 3                | 75%
+frontend-dev   | 8        | 12         | 1                | 88%
+tester-qa      | 5        | 8          | 4 (encontrados)  | QA
+revisor        | 3        | 4          | 2                | 67%
+```
+
+### Archivos Inestables
+
+```
+🚨 CRÍTICOS (>5 mutaciones):
+  - src/auth.ts         (7 mutaciones en 2 días)
+  - src/database.ts     (6 mutaciones en 3 días)
+
+⚠️  INESTABLES (2-5 mutaciones):
+  - src/validators.ts   (3 mutaciones)
+  - src/payments.ts     (4 mutaciones)
+```
+
+### Agentes con Mejora Necesaria
+
+```
+📊 ESCALA DE CALIDAD:
+  backend-dev:    ████████░ 75% — Aumentar coverage de tests
+  frontend-dev:   █████████ 88% — Excelente
+  revisor:        ██████░░░ 67% — Revisar proceso de verificación
+```
+
+---
+
+## Interpretación de Resultados
+
+### Escape Rate Bajo (1-10%)
+```
+✅ QA es efectivo, código es estable
+  → Confiable para producción
+  → Clientes confían en calidad
+```
+
+### Escape Rate Medio (11-30%)
+```
+⚠️  QA encuentra mayoría de bugs, pero algunos escapan
+  → Aumentar cobertura de tests
+  → Mejorar criterios de aceptación
+```
+
+### Escape Rate Alto (31%+)
+```
+🔴 Problemas serios de calidad
+  → Tests insuficientes
+  → Falta validación
+  → Riesgo de producción
+```
+
+---
+
+## Ejemplo Real
+
+**Sesión 1 (2026-06-10):**
+- Backend Dev escribe src/auth.ts (Write)
+- Frontend Dev modifica src/ui.tsx (Edit)
+- Tester QA ejecuta tests, encuentra 2 bugs en auth.ts
+
+**Sesión 2 (2026-06-11):**
+- Backend Dev reescribe src/auth.ts (Write) — 2 bugs solucionados + 1 nuevo
+- Tester QA ejecuta tests, encuentra 2 bugs (1 viejo, 1 nuevo)
+- 1 bug anterior escapó a producción
+
+**Reporte Final:**
+```
+Archivos: 2
+Bugs encontrados: 4
+Bugs en prod: 1
+─────────────────
+Escape Rate: 25%
+
+Por agente:
+  backend-dev: 6 mutaciones, 3 bugs encontrados → 50% quality
+  frontend-dev: 1 mutación, 0 bugs → 100% quality
+  tester-qa: 100% accuracy (encontró todos excepto 1 que escapó)
+```
+
+---
+
+## Datos Fuente
+
+Utiliza:
+- `.sdd/observabilidad/mutaciones.jsonl` — cambios a archivos
+- `.sdd/observabilidad/consumo.jsonl` — timestamps de eventos
+
+**Nota:** En v2.6.1 se agregará integración con resultados reales de QA (Playwright).
+

package/commands/sdd.descubrir.md

@@ -32,8 +32,27 @@ cat .sdd/memoria/constitucion.md 2>/dev/null | head -10 && echo "EXISTE_CONSTITU
 # ¿Es un proyecto existente? Si hay código, invocar al investigador antes de preguntar
 ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null | head -5
 ls src/ app/ lib/ 2>/dev/null | head -3
+
+# ¿Hay perfil configurado?
+PERFIL=$(grep -o '"perfil": *"[^"]*"' .sdd/estado.json 2>/dev/null | cut -d'"' -f4)
+[ -z "$PERFIL" ] && PERFIL=$(grep '^perfil:' .sdd/sdd.config.yaml 2>/dev/null | cut -d':' -f2 | tr -d ' ')
+echo "PERFIL=${PERFIL:-guiado}"
 ```
 
+### Detección de usuario nuevo
+
+Si NO existe `.sdd/estado.json` ni `.sdd/sdd.config.yaml` y no hay código previo en el proyecto:
+
+**→ Usuario nuevo detectado. Usa modo guiado.**
+
+No pidas que editen archivos ni que ejecuten comandos. Saluda en lenguaje natural:
+
+> ¡Hola! Cuéntame qué quieres construir — una frase es suficiente. No necesitas saber nada técnico para empezar.
+
+Si existe `.sdd/sdd.config.yaml` con `perfil: experto` explícito:
+
+**→ Usuario avanzado. Usa modo experto** (muestra comandos, rutas, estado técnico).
+
 Si el proyecto ya tiene código (existe `src/`, `app/`, o un archivo de manifiesto), invoca al agente **investigador** antes del PASO 1:
 
 > `@investigador` Analiza el proyecto existente y genera el informe de contexto técnico. Quiero usarlo como base antes de especificar algo nuevo.

package/commands/sdd.estado.md

@@ -28,7 +28,57 @@ fi
    Ejecuta:  /sdd.constitucion
 ```
 
-## PASO 3 — Generar dashboard completo
+## PASO 2.5 — Detectar perfil y elegir formato de dashboard
+
+```bash
+PERFIL=$(grep -o '"perfil": *"[^"]*"' .sdd/estado.json 2>/dev/null | cut -d'"' -f4)
+[ -z "$PERFIL" ] && PERFIL=$(grep '^perfil:' .sdd/sdd.config.yaml 2>/dev/null | cut -d':' -f2 | tr -d ' ')
+echo "PERFIL=${PERFIL:-guiado}"
+```
+
+- Si `PERFIL=guiado` (o no hay perfil): mostrar **dashboard de producto** (PASO 3A).
+- Si `PERFIL=experto` y no hay modo explícito `pm`/`arq`/`dev`: mostrar **dashboard técnico** (PASO 3B).
+
+## PASO 3A — Dashboard de producto (modo guiado, por defecto)
+
+Muestra el estado en lenguaje natural, sin jerga técnica:
+
+```
+Tu proyecto: [Nombre del proyecto]
+
+[Si hay feature activa:]
+Estás trabajando en: [título de la spec en lenguaje natural]
+Progreso: [N]% listo ([N] de [M] pasos completados)
+[████████████░░░░░░░░]
+
+¿Qué queda por hacer?
+  ✅ [descripción natural del paso completado más reciente]
+  → Próximo paso: [descripción natural de lo que sigue]
+
+[Si hay bloqueos:]
+  ⚠️  Hay un problema que necesita tu atención: [descripción natural del bloqueo]
+
+[Si no hay feature activa:]
+¡Listo para empezar! ¿Qué quieres construir ahora?
+```
+
+Reglas para el dashboard de producto:
+- Nunca mostrar IDs internos (`2026-06-14-auth`, `pipeline_step`, `T003`).
+- Nunca mencionar nombres de comandos a menos que el usuario los pida.
+- Usar "feature", "funcionalidad" o "lo que estás construyendo" en vez de "spec" o "especificación".
+- Traducir las fases del pipeline a lenguaje natural:
+  | Fase interna | Texto para usuario |
+  |---|---|
+  | `especificacion` | "Definiendo los detalles" |
+  | `plan` | "Planificando cómo construirlo" |
+  | `plan_aprobado` | "Plan listo, preparando tareas" |
+  | `tareas_generadas` | "Tareas listas, empezando a construir" |
+  | `implementacion` | "Construyendo..." |
+  | `implementacion_completa` | "Construcción lista, verificando" |
+  | `verificada` | "Verificado y funcionando" |
+  | `completado` | "¡Listo! Feature entregada" |
+
+## PASO 3B — Dashboard técnico (modo experto o modo `dev`)
 
 ```
 ╔════════════════════════════════════════════════════════════════╗
@@ -100,7 +150,7 @@ fi
 ╚════════════════════════════════════════════════════════════════╝
 ```
 
-## PASO 4 — Determinar próximo paso según fase
+## PASO 4 — Determinar próximo paso según fase (para ambos modos)
 
 | Fase actual | Próximo paso |
 |-------------|--------------|