sdd-es 2.0.0

package/cli/index.js

@@ -0,0 +1,401 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * SDD-ES — CLI de instalación multiplataforma (Windows / macOS / Linux).
+ *
+ * Reemplaza a instalar.sh (bash-only) con Node puro, cero dependencias.
+ * Comparte la misma lógica de copia idempotente.
+ *
+ * Uso:
+ *   npx sdd-es init            instala en el proyecto actual (.claude/ + .sdd/)
+ *   npx sdd-es init --global   instala en $HOME/.claude (todos los proyectos)
+ *   npx sdd-es update          re-copia commands/agents/skills/hooks sin tocar .sdd/ ni settings
+ *   npx sdd-es doctor          diagnostica la instalación
+ *   npx sdd-es --version       muestra la versión
+ */
+
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { execSync } from "node:child_process";
+
+// ─── Paths ────────────────────────────────────────────────────────────────────
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Raíz del plugin (un nivel arriba de cli/). */
+const PLUGIN_DIR = join(__dirname, "..");
+
+// ─── Colores (degradan a texto plano si no hay TTY) ─────────────────────────────
+
+const tty = process.stdout.isTTY;
+const c = {
+  verde: (s) => (tty ? `\x1b[0;32m${s}\x1b[0m` : s),
+  amarillo: (s) => (tty ? `\x1b[1;33m${s}\x1b[0m` : s),
+  rojo: (s) => (tty ? `\x1b[0;31m${s}\x1b[0m` : s),
+  azul: (s) => (tty ? `\x1b[0;34m${s}\x1b[0m` : s),
+};
+
+const info = (msg) => console.log(`${c.verde("✓")} ${msg}`);
+const aviso = (msg) => console.log(`${c.amarillo("⚠")}  ${msg}`);
+const titulo = (msg) => console.log(`${c.azul("❯")} ${msg}`);
+function error(msg) {
+  console.error(`${c.rojo("✗")} ${msg}`);
+  process.exit(1);
+}
+
+// ─── Utilidades de copia ────────────────────────────────────────────────────────
+
+/** Copia todos los .md de un directorio origen a uno destino. Devuelve cuántos. */
+function copyMd(srcDir, destDir) {
+  mkdirSync(destDir, { recursive: true });
+  const archivos = readdirSync(srcDir).filter((f) => f.endsWith(".md"));
+  for (const f of archivos) {
+    cpSync(join(srcDir, f), join(destDir, f));
+  }
+  return archivos.length;
+}
+
+/** Copia un directorio completo (recursivo). */
+function copyDir(srcDir, destDir) {
+  mkdirSync(destDir, { recursive: true });
+  cpSync(srcDir, destDir, { recursive: true });
+}
+
+/** Lee la versión declarada en package.json del plugin. */
+function pluginVersion() {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(join(PLUGIN_DIR, "package.json"), "utf8")
+    );
+    return pkg.version || "desconocida";
+  } catch {
+    return "desconocida";
+  }
+}
+
+/** ¿Está `claude` en el PATH? */
+function claudeEnPath() {
+  try {
+    execSync(process.platform === "win32" ? "where claude" : "command -v claude", {
+      stdio: "ignore",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Banner ─────────────────────────────────────────────────────────────────────
+
+function banner() {
+  console.log("");
+  console.log("  ╔══════════════════════════════════════════════════════╗");
+  console.log("  ║                                                      ║");
+  console.log("  ║          SDD-ES — Instalación del Plugin v2.0        ║");
+  console.log("  ║                                                      ║");
+  console.log("  ╚══════════════════════════════════════════════════════╝");
+  console.log("");
+}
+
+// ─── Copia núcleo (commands/agents/skills/hooks) ────────────────────────────────
+
+/**
+ * Copia los artefactos del plugin a CLAUDE_DIR.
+ * @param {string} claudeDir destino (.claude del proyecto o global)
+ */
+function copiarNucleo(claudeDir) {
+  titulo("Copiando comandos...");
+  const nCmd = copyMd(join(PLUGIN_DIR, "commands"), join(claudeDir, "commands"));
+  info(`Comandos instalados (${nCmd} archivos)`);
+
+  titulo("Copiando agentes...");
+  const nAg = copyMd(join(PLUGIN_DIR, "agents"), join(claudeDir, "agents"));
+  info(`Agentes instalados (${nAg} archivos)`);
+
+  titulo("Copiando skills...");
+  // Skills planas (.md) + skills en formato carpeta (SKILL.md)
+  const skillsSrc = join(PLUGIN_DIR, "skills");
+  const skillsDest = join(claudeDir, "skills");
+  mkdirSync(skillsDest, { recursive: true });
+  let nSk = 0;
+  for (const entry of readdirSync(skillsSrc, { withFileTypes: true })) {
+    if (entry.isFile() && entry.name.endsWith(".md")) {
+      cpSync(join(skillsSrc, entry.name), join(skillsDest, entry.name));
+      nSk++;
+    } else if (entry.isDirectory()) {
+      // skill en formato carpeta (contiene SKILL.md + recursos)
+      copyDir(join(skillsSrc, entry.name), join(skillsDest, entry.name));
+      nSk++;
+    }
+  }
+  info(`Skills instaladas (${nSk} entradas)`);
+
+  titulo("Instalando hooks de Claude Code...");
+  const hooksSrc = join(PLUGIN_DIR, "claude-hooks");
+  const hooksDest = join(claudeDir, "hooks");
+  mkdirSync(hooksDest, { recursive: true });
+  for (const f of readdirSync(hooksSrc).filter((f) => f.endsWith(".js"))) {
+    cpSync(join(hooksSrc, f), join(hooksDest, f));
+  }
+  info(`Hooks instalados (${hooksDest})`);
+}
+
+// ─── settings.json (no sobreescribe) ────────────────────────────────────────────
+
+function copiarSettings(claudeDir) {
+  const dest = join(claudeDir, "settings.json");
+  const src = join(PLUGIN_DIR, ".claude", "settings.json");
+  if (!existsSync(dest)) {
+    cpSync(src, dest);
+    info(`Settings de seguridad instalados (${dest})`);
+  } else {
+    aviso(`settings.json ya existe en ${claudeDir} — no se sobreescribe`);
+    aviso(`Revisa manualmente: ${src}`);
+  }
+}
+
+// ─── Estructura .sdd/ del proyecto ──────────────────────────────────────────────
+
+const HOOKS_README = `# Hooks personalizados de SDD-ES
+
+Coloca aquí tus scripts ejecutables para integrar tu workflow con SDD.
+
+## Hooks por fase
+
+- \`antes_constitucion.sh\`    \`despues_constitucion.sh\`
+- \`antes_especificar.sh\`     \`despues_especificar.sh\`
+- \`antes_aclarar.sh\`         \`despues_aclarar.sh\`
+- \`antes_planificar.sh\`      \`despues_planificar.sh\`
+- \`antes_tareas.sh\`          \`despues_tareas.sh\`
+- \`antes_analizar.sh\`        \`despues_analizar.sh\`
+- \`antes_implementar.sh\`     \`despues_implementar.sh\`
+- \`antes_cada_tarea.sh\`      \`despues_cada_tarea.sh\`  (recibe T_ID como arg)
+- \`antes_verificar.sh\`       \`despues_verificar.sh\`
+- \`antes_importar.sh\`
+
+Recuerda dar permiso de ejecución a tus hooks en sistemas Unix:
+\`chmod +x .sdd/hooks/tu-hook.sh\`
+
+Ver más ejemplos en docs/EJEMPLOS.md del plugin.
+`;
+
+function configurarSdd(claudeDir) {
+  titulo("Configurando estructura .sdd/ del proyecto...");
+
+  const sub = [
+    "memoria",
+    "especificaciones",
+    "cambios",
+    "arquitectura",
+    join("dominio", "definiciones"),
+    "hooks",
+    "plantillas",
+  ];
+  for (const d of sub) {
+    mkdirSync(join(process.cwd(), ".sdd", d), { recursive: true });
+  }
+
+  // Plantillas
+  copyMd(join(PLUGIN_DIR, "plantillas"), join(process.cwd(), ".sdd", "plantillas"));
+  info("Plantillas copiadas a .sdd/plantillas/");
+
+  // Config (no sobreescribe)
+  const configDest = join(process.cwd(), ".sdd", "sdd.config.yaml");
+  if (!existsSync(configDest)) {
+    cpSync(
+      join(PLUGIN_DIR, "configuracion-ejemplo", "sdd.config.yaml"),
+      configDest
+    );
+    info("Configuración por defecto copiada (.sdd/sdd.config.yaml)");
+  } else {
+    aviso("Configuración ya existe — no se sobreescribe");
+  }
+
+  // README de hooks (no sobreescribe)
+  const hooksReadme = join(process.cwd(), ".sdd", "hooks", "README.md");
+  if (!existsSync(hooksReadme)) {
+    writeFileSync(hooksReadme, HOOKS_README);
+    info("README de hooks creado (.sdd/hooks/README.md)");
+  }
+
+  // Documentación local (opcional)
+  const docsDest = join(process.cwd(), ".sdd", "docs");
+  if (!existsSync(docsDest)) {
+    copyMd(join(PLUGIN_DIR, "docs"), docsDest);
+    info("Documentación copiada a .sdd/docs/");
+  }
+}
+
+// ─── Fin ─────────────────────────────────────────────────────────────────────────
+
+function pasosFinales() {
+  console.log("");
+  console.log("  ╔══════════════════════════════════════════════════════╗");
+  console.log("  ║              ✅ Instalación completada               ║");
+  console.log("  ╠══════════════════════════════════════════════════════╣");
+  console.log("  ║   PRÓXIMO PASO:                                      ║");
+  console.log("  ║      Abre Claude Code y ejecuta:  /sdd.constitucion  ║");
+  console.log("  ║   Para ver todos los comandos:    /sdd.ayuda         ║");
+  console.log("  ╚══════════════════════════════════════════════════════╝");
+  console.log("");
+}
+
+// ─── Comandos ───────────────────────────────────────────────────────────────────
+
+function cmdInit(global) {
+  banner();
+  const claudeDir = global
+    ? join(homedir(), ".claude")
+    : join(process.cwd(), ".claude");
+  console.log(`  Modo: ${global ? "GLOBAL" : "PROYECTO"} (${claudeDir})`);
+  console.log("");
+
+  if (!claudeEnPath()) {
+    aviso("Claude Code CLI no detectado en PATH. Los archivos se instalarán de todos modos.");
+  }
+
+  copiarNucleo(claudeDir);
+  copiarSettings(claudeDir);
+
+  if (!global) {
+    configurarSdd(claudeDir);
+  }
+
+  pasosFinales();
+}
+
+function cmdUpdate(global) {
+  banner();
+  const claudeDir = global
+    ? join(homedir(), ".claude")
+    : join(process.cwd(), ".claude");
+  console.log(`  Actualizando núcleo en: ${claudeDir}`);
+  console.log("  (.sdd/ y settings.json del usuario NO se tocan)");
+  console.log("");
+
+  if (!existsSync(claudeDir)) {
+    error(`No existe ${claudeDir}. Ejecuta 'npx sdd-es init' primero.`);
+  }
+
+  copiarNucleo(claudeDir);
+  info("Núcleo actualizado. Tu .sdd/ y settings.json se conservan.");
+  console.log("");
+}
+
+function cmdDoctor() {
+  banner();
+  console.log("  Diagnóstico de SDD-ES");
+  console.log("");
+
+  let problemas = 0;
+
+  // Node
+  const nodeMajor = Number(process.versions.node.split(".")[0]);
+  if (nodeMajor >= 18) {
+    info(`Node ${process.versions.node} (>=18 requerido) ✓`);
+  } else {
+    aviso(`Node ${process.versions.node} es < 18. Actualiza Node.`);
+    problemas++;
+  }
+
+  // Claude CLI
+  if (claudeEnPath()) {
+    info("Claude Code CLI detectado en PATH ✓");
+  } else {
+    aviso("Claude Code CLI no está en PATH (instala desde claude.ai/code)");
+  }
+
+  // Versión del plugin
+  info(`Versión del plugin: ${pluginVersion()}`);
+
+  // Integridad del plugin
+  titulo("Verificando integridad del plugin...");
+  for (const dir of ["commands", "agents", "skills", "plantillas", "claude-hooks"]) {
+    const p = join(PLUGIN_DIR, dir);
+    if (existsSync(p)) {
+      const n = readdirSync(p).length;
+      info(`${dir}/ (${n} entradas)`);
+    } else {
+      aviso(`falta ${dir}/ en el plugin`);
+      problemas++;
+    }
+  }
+
+  // ¿Instalado en el proyecto actual?
+  titulo("Instalación en el proyecto actual...");
+  const localClaude = join(process.cwd(), ".claude", "commands");
+  const localSdd = join(process.cwd(), ".sdd");
+  if (existsSync(localClaude)) {
+    info(`.claude/commands/ presente (${readdirSync(localClaude).length} comandos)`);
+  } else {
+    aviso(".claude/commands/ no encontrado — ejecuta 'npx sdd-es init'");
+  }
+  if (existsSync(localSdd)) {
+    info(".sdd/ presente");
+  } else {
+    aviso(".sdd/ no encontrado — ejecuta 'npx sdd-es init'");
+  }
+
+  console.log("");
+  if (problemas === 0) {
+    info("Diagnóstico OK — sin problemas críticos.");
+  } else {
+    aviso(`${problemas} problema(s) detectado(s). Revisa arriba.`);
+  }
+  console.log("");
+}
+
+function uso() {
+  console.log(`
+SDD-ES — CLI de instalación (v${pluginVersion()})
+
+Uso:
+  npx sdd-es init [--global]   Instala el plugin (proyecto o global)
+  npx sdd-es update [--global] Re-copia núcleo sin tocar tu .sdd/ ni settings
+  npx sdd-es doctor            Diagnostica la instalación
+  npx sdd-es --version         Muestra la versión
+
+Tras instalar, abre Claude Code y ejecuta /sdd.constitucion
+`);
+}
+
+// ─── Entry point ────────────────────────────────────────────────────────────────
+
+function main() {
+  const args = process.argv.slice(2);
+  const comando = args[0];
+  const global = args.includes("--global") || args.includes("-g");
+
+  switch (comando) {
+    case "init":
+      cmdInit(global);
+      break;
+    case "update":
+      cmdUpdate(global);
+      break;
+    case "doctor":
+      cmdDoctor();
+      break;
+    case "--version":
+    case "-v":
+      console.log(pluginVersion());
+      break;
+    case "--help":
+    case "-h":
+    case undefined:
+      uso();
+      break;
+    default:
+      error(`Comando desconocido: '${comando}'. Usa 'npx sdd-es --help'.`);
+  }
+}
+
+main();

package/commands/sdd.aclarar.md

@@ -0,0 +1,200 @@
+---
+description: Identifica y resuelve marcadores [NECESITA_ACLARACION] y ambigüedades en la spec activa. Hace preguntas estructuradas por categoría.
+allowed-tools: Read, Write, Edit, Bash
+handoffs:
+  - etiqueta: "Validar calidad"
+    comando: sdd.checklist
+  - etiqueta: "Planificar"
+    comando: sdd.planificar
+---
+
+# /sdd.aclarar — Resolver Ambigüedades
+
+Eres el **Analista de Ambigüedad**. Tu trabajo es encontrar TODO lo que pueda interpretarse de múltiples formas y resolverlo antes de pasar al plan.
+
+## PASO 1 — Cargar contexto
+
+```bash
+SPEC_ID=$(grep -o '"especificacion_activa": "[^"]*"' .sdd/estado.json | cut -d'"' -f4)
+
+if [ -z "$SPEC_ID" ]; then
+  echo "ERROR: no hay especificación activa. Ejecuta /sdd.especificar primero."
+  exit 1
+fi
+
+SPEC_FILE=".sdd/especificaciones/${SPEC_ID}/spec.md"
+cat "$SPEC_FILE"
+cat .sdd/memoria/constitucion.md | head -50
+cat .sdd/dominio/glosario.md 2>/dev/null
+```
+
+## PASO 2 — Detección sistemática de ambigüedad
+
+Analiza la spec aplicando estas categorías. **Sé exhaustivo** — encontrar 0 ambigüedades en una spec compleja es señal de revisión superficial.
+
+### Categoría A — Marcadores explícitos (críticos)
+Busca con `grep`: `[NECESITA_ACLARACION]`, `[POR_DECIDIR]`, `[PENDIENTE]`, `[TODO]`, `???`.
+
+### Categoría B — Criterios no testeables (críticos)
+Busca palabras que sugieren ambigüedad en CAs y requisitos:
+- "rápido", "lento", "eficiente", "óptimo"
+- "fácil", "intuitivo", "amigable", "moderno"
+- "muchos", "varios", "algunos", "pocos"
+- "generalmente", "usualmente", "a veces"
+- "etc.", "entre otros"
+- "debería" sin métrica (¿debería cuándo? ¿cómo medirlo?)
+
+### Categoría C — Actores y permisos (importante)
+- ¿Quién PUEDE ejecutar cada acción?
+- ¿Quién NO puede?
+- ¿Qué pasa con usuarios no autenticados / con permisos parciales?
+
+### Categoría D — Datos y formatos (importante)
+- Validaciones de input (longitud, formato, rangos)
+- Comportamiento ante valores nulos/vacíos/cero/negativos
+- Codificación, idioma, zonas horarias
+- Unidades de medida
+
+### Categoría E — Estados y transiciones (importante)
+- Estados posibles del recurso
+- Transiciones válidas entre estados
+- Comportamiento ante transiciones inválidas
+
+### Categoría F — Casos borde (importante)
+- ¿Qué pasa con el primer elemento? ¿El último?
+- ¿Qué pasa cuando la lista está vacía?
+- ¿Concurrencia? ¿Qué si dos usuarios hacen X al mismo tiempo?
+- ¿Idempotencia? ¿Qué si se repite la operación?
+
+### Categoría G — Integraciones externas (importante)
+- ¿Qué pasa si el servicio externo está caído?
+- Timeouts, reintentos, fallbacks
+- Consistencia eventual vs fuerte
+
+### Categoría H — Performance y escala (medio)
+- Volumen esperado de datos
+- Frecuencia de uso
+- Latencia aceptable
+
+## PASO 3 — Formular preguntas
+
+Agrupa las preguntas por categoría. **Máximo 5 preguntas por ronda** para no abrumar.
+
+Formato:
+
+```
+🔴 ACLARACIONES CRÍTICAS
+
+**1. [Categoría]** — [pregunta concreta]
+
+   ¿Cuál se aplica?
+   a) [opción A con consecuencia]
+   b) [opción B con consecuencia]
+   c) [opción C con consecuencia]
+   d) Otra (describe)
+
+**2. [Categoría]** — [pregunta]
+   ...
+
+Por favor responde con el número y la letra (ej: "1.a, 2.c").
+```
+
+Para preguntas no críticas, indica "(puedes responder 'cualquiera' si no te importa)".
+
+### Adaptación al perfil guiado
+
+```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 ' ')
+```
+
+Si `PERFIL=guiado`, activa la skill `modo-guiado` y reformula **todas** las preguntas sin jerga técnica:
+
+- Nada de "ISO 8601", "endpoint", "payload", "nullable", "idempotencia". Traduce a lenguaje cotidiano con opciones concretas.
+- Reduce el número de preguntas al mínimo imprescindible (resuelve tú lo técnico con defaults sensatos; pregunta solo lo que afecta lo que el usuario *quiere*, no lo que afecta *cómo se implementa*).
+- Una pregunta a la vez si son varias.
+
+Ejemplo de traducción:
+
+> ❌ Técnico: "¿El campo `vence_en` acepta null y qué zona horaria usa?"
+> ✅ Guiado: "¿Las tareas tienen fecha límite? a) Sí b) No, solo si está hecha o no"
+
+## PASO 4 — Aplicar respuestas a la spec
+
+Por cada respuesta:
+
+1. Localiza la sección de la spec donde se aplica
+2. Reemplaza el marcador `[NECESITA_ACLARACION]` o frase ambigua con texto preciso
+3. Si la respuesta agrega un criterio de aceptación nuevo, añádelo a la sección correspondiente con ID nuevo
+4. Si introduce un término del dominio, márcalo para añadir al glosario
+
+## PASO 5 — Documentar las decisiones
+
+Añade o actualiza la sección "Aclaraciones" al final de la spec:
+
+```markdown
+## 14. Historial de Aclaraciones
+
+| # | Categoría | Pregunta | Decisión | Fecha |
+|---|-----------|----------|----------|-------|
+| 1 | [cat] | [pregunta resumida] | [respuesta] | {FECHA} |
+| 2 | [cat] | [pregunta] | [respuesta] | {FECHA} |
+```
+
+## PASO 6 — Detección de términos del dominio
+
+Si las aclaraciones introdujeron términos nuevos del dominio (ej: "membresía Gold", "factura cerrada"), pregunta:
+
+> Detecté nuevos términos del dominio: [lista].
+> ¿Quieres añadirlos al glosario? Ejecutaré `/sdd.glosario` para cada uno.
+
+## PASO 7 — Verificar completitud
+
+Después de aplicar todas las respuestas:
+
+```bash
+# Verificar que no quedan marcadores críticos
+grep -c "[NECESITA_ACLARACION]" "$SPEC_FILE"
+```
+
+Si quedan marcadores, hay 2 opciones:
+1. **Nueva ronda** de preguntas (si son críticos)
+2. **Diferir** explícitamente (si son menores) — convertir a `[POR_DECIDIR]` con justificación
+
+## PASO 8 — Resumen
+
+```
+✅ Spec aclarada
+📁 .sdd/especificaciones/{ID}/spec.md
+📋 {N} preguntas respondidas
+🏷️  {M} términos del dominio identificados
+⚠️  {K} pendientes diferidos (no críticos)
+
+SIGUIENTES PASOS:
+   /sdd.checklist     — validar calidad formal
+   /sdd.planificar    — pasar al plan técnico
+   /sdd.glosario      — añadir términos al glosario
+```
+
+## VALIDACIÓN DE SALIDA
+
+Antes de entregar al usuario, verifica que la spec quedó limpia:
+
+```bash
+SPEC_ID=$(grep -o '"especificacion_activa": "[^"]*"' .sdd/estado.json 2>/dev/null | cut -d'"' -f4)
+SPEC_FILE=".sdd/especificaciones/${SPEC_ID}/spec.md"
+
+# No deben quedar marcadores críticos sin resolver
+PENDIENTES=$(grep -c "\[NECESITA_ACLARACION\]" "$SPEC_FILE" 2>/dev/null || echo 0)
+[ "$PENDIENTES" -gt 0 ] && echo "ADVERTENCIA: $PENDIENTES marcadores [NECESITA_ACLARACION] sin resolver"
+
+# El historial de aclaraciones debe existir
+grep -q "Historial de Aclaraciones" "$SPEC_FILE" || echo "FALTA: sección Historial de Aclaraciones"
+
+echo "Validación completada — marcadores pendientes: $PENDIENTES"
+```
+
+Si quedan marcadores críticos, hacer nueva ronda de preguntas antes de habilitar el handoff a `/sdd.planificar`.
+
+---
+**HOOK:** `.sdd/hooks/despues_aclarar.sh`