zugzbot-sdd 1.5.0

package/tools/sdd_transition.ts

@@ -0,0 +1,375 @@
+import { tool } from "@opencode-ai/plugin"
+import fs from "fs"
+import path from "path"
+import { execSync } from "child_process"
+import specValidator from "./sdd_spec_validator"
+import regressionDetector from "./sdd_regression_detector"
+import secretScanner from "./sdd_secret_scanner"
+import requirementTracker from "./sdd_requirement_tracker"
+import checkDependencyCooldown from "./check_dependency_cooldown"
+
+const SUBAGENT_MAPPING: { [key: number]: string } = {
+  0: "sdd-explorer",
+  1: "sdd-planner",
+  2: "sdd-builder",
+  3: "sdd-tester",
+  4: "sdd-deployer",
+  5: "sdd-archiver"
+}
+
+const DEFAULT_LOCKFILE = {
+  change_name: "nuevo-cambio",
+  active_phase: 0,
+  active_subagent: "sdd-explorer",
+  status: "idle",
+  auto_pilot: false,
+  iteration: 0,
+  last_updated: "",
+  orchestrator_mode: "delegation_only",
+  direction: "forward" as "forward" | "backward" | "repeat",
+  last_successful_phase: 0,
+  retry_count: 0,
+  corrective_loop_active: false,
+  fresh_task: false,
+  checkpoints: []
+}
+
+export default tool({
+  description: "Tránsiciona de fase en el ciclo Spec-Driven Development (SDD), actualizando el archivo de bloqueo lockfile .openspec/sdd-lock.json de forma segura, e integra control de cambios en Git de forma automática.",
+  args: {
+    nextPhase: tool.schema.number().describe("El número de la siguiente fase del ciclo SDD (0-5)"),
+    status: tool.schema.string().describe("El nuevo estado del ciclo (ej: 'idle', 'in_progress', 'corrective_loop', 'restored')"),
+    reason: tool.schema.string().describe("La justificación o explicación resumida de los cambios logrados en esta fase"),
+    activeSubagent: tool.schema.string().optional().describe("El subagente activo opcional (ej: 'sdd-planner', 'sdd-builder')"),
+    iteration: tool.schema.number().optional().describe("El número de iteración correctiva opcional"),
+    changeName: tool.schema.string().optional().describe("El nombre del cambio de desarrollo activo opcional"),
+    complexity: tool.schema.enum(["low", "high"]).optional().default("high").describe("La complejidad del cambio de desarrollo activo (low o high)"),
+    direction: tool.schema.enum(["forward", "backward", "repeat"]).optional().default("forward").describe("Dirección de la transición: forward (normal), backward (retroceder a fase anterior), repeat (repetir fase actual)")
+  },
+  async execute(args, context) {
+    const projectRoot = context.worktree || context.directory;
+    let lockfilePath = path.join(projectRoot, ".openspec/sdd-lock.json");
+
+    // Validar si existe .openspec/sdd-lock.json o si es openspec/sdd-lock.json
+    if (!fs.existsSync(lockfilePath)) {
+      const altPath = path.join(projectRoot, "openspec/sdd-lock.json");
+      if (fs.existsSync(altPath)) {
+        lockfilePath = altPath;
+      } else {
+        // Si no existe ninguno, creamos el directorio y el archivo por defecto
+        const dirPath = path.join(projectRoot, ".openspec");
+        if (!fs.existsSync(dirPath)) {
+          fs.mkdirSync(dirPath, { recursive: true });
+        }
+      }
+    }
+
+    let lockfile: any = {
+      change_name: "nuevo-cambio",
+      active_phase: 0,
+      active_subagent: "sdd-explorer",
+      status: "idle",
+      auto_pilot: false,
+      iteration: 0,
+      last_updated: ""
+    };
+
+    if (fs.existsSync(lockfilePath)) {
+      try {
+        lockfile = JSON.parse(fs.readFileSync(lockfilePath, "utf-8"));
+        lockfile.orchestrator_mode = lockfile.orchestrator_mode || "delegation_only";
+        lockfile.direction = lockfile.direction || "forward";
+        lockfile.last_successful_phase = lockfile.last_successful_phase || 0;
+        lockfile.retry_count = lockfile.retry_count || 0;
+        lockfile.corrective_loop_active = lockfile.corrective_loop_active || false;
+        lockfile.fresh_task = lockfile.fresh_task || false;
+        lockfile.checkpoints = lockfile.checkpoints || [];
+      } catch (e) {
+        lockfile = { ...DEFAULT_LOCKFILE };
+      }
+    } else {
+      lockfile = { ...DEFAULT_LOCKFILE };
+    }
+
+    const direction = args.direction || lockfile.direction || "forward";
+
+    if (direction === "backward") {
+      const previousPhase = Math.max(0, (args.nextPhase || lockfile.active_phase) - 1);
+      lockfile.last_successful_phase = previousPhase;
+      lockfile.corrective_loop_active = true;
+      lockfile.fresh_task = true;
+      lockfile.retry_count = 0;
+    }
+
+    if (direction === "repeat") {
+      lockfile.retry_count = (lockfile.retry_count || 0) + 1;
+      lockfile.corrective_loop_active = true;
+      lockfile.fresh_task = true;
+      if (lockfile.retry_count > 3) {
+        return `[SDD Transition Blocked] Se excedió el límite de 3 reintentos para esta fase. Escalando a revisión humana.`;
+      }
+    }
+
+    if (direction === "forward") {
+      lockfile.fresh_task = false;
+    }
+
+    const activeChangeName = args.changeName || lockfile.change_name;
+
+    // ── SALVAGUARDAS AUTOMÁTICAS DE METODOLOGÍA SDD ──
+    // 1. Transición a Fase 2 (Construcción): Validar spec.md y parsear la checklist de tareas
+    if (args.nextPhase === 2 && args.status !== "corrective_loop" && direction === "forward") {
+      const specValidationResultObj: any = await specValidator.execute({ changeName: activeChangeName }, context);
+      const specValidationResultStr = typeof specValidationResultObj === "string" ? specValidationResultObj : (specValidationResultObj?.output || "");
+      try {
+        const result = JSON.parse(specValidationResultStr);
+        if (result.status === "FAILED") {
+          return `[SDD Transition Blocked] Transición rechazada por falla de calidad del Plano Técnico:\n\n${result.message}`;
+        }
+      } catch (e) {}
+
+      // Extracción de checklist de tareas desde spec.md para el monitor de estados
+      const specPath = path.join(projectRoot, ".openspec/changes", activeChangeName, "specs/spec.md");
+      if (fs.existsSync(specPath)) {
+        try {
+          const specContent = fs.readFileSync(specPath, "utf-8");
+          const qaSectionIndex = specContent.indexOf("## 5. Criterios de Aceptación");
+          if (qaSectionIndex !== -1) {
+            const qaContent = specContent.substring(qaSectionIndex);
+            const lines = qaContent.split("\n");
+            const parsedTasks: any[] = [];
+            let taskId = 1;
+            for (const line of lines) {
+              if (line.startsWith("##") && !line.includes("## 5.")) {
+                break;
+              }
+              const match = line.match(/^\s*-\s*\[\s*\]\s*(.+)$/i);
+              if (match) {
+                parsedTasks.push({
+                  id: taskId++,
+                  desc: match[1].trim(),
+                  status: "pending"
+                });
+              }
+            }
+            if (parsedTasks.length > 0) {
+              lockfile.tasks = parsedTasks;
+            }
+          }
+        } catch (e) {}
+      }
+    }
+
+    // 2. Transición a Fase 5 (Cierre/Archiver): Validar regresiones de compilación, cobertura de requerimientos, cooldown y actualizar estado de tareas
+    if (args.nextPhase === 5 && args.status !== "corrective_loop") {
+      // Sincronizar checklist de tareas completadas desde el verification_report.md
+      if (lockfile.tasks) {
+        const reportPath = path.join(projectRoot, ".openspec/changes", activeChangeName, "validation_report.md");
+        if (fs.existsSync(reportPath)) {
+          try {
+            const reportContent = fs.readFileSync(reportPath, "utf-8");
+            const qaSectionIndex = reportContent.indexOf("## 3. Correspondencia de Criterios");
+            if (qaSectionIndex !== -1) {
+              const qaContent = reportContent.substring(qaSectionIndex);
+              const lines = qaContent.split("\n");
+              for (const line of lines) {
+                if (line.startsWith("##") && !line.includes("## 3.")) {
+                  break;
+                }
+                const match = line.match(/^\s*-\s*\[(x|\s)\]\s*(.+)$/i);
+                if (match) {
+                  const isCompleted = match[1].toLowerCase() === "x";
+                  const descClean = match[2].replace(/\*/g, "").trim().toLowerCase();
+                  for (const t of lockfile.tasks) {
+                    const taskClean = t.desc.toLowerCase();
+                    if (descClean.includes(taskClean) || taskClean.includes(descClean)) {
+                      t.status = isCompleted ? "completed" : "pending";
+                    }
+                  }
+                }
+              }
+            }
+          } catch (e) {}
+        }
+      }
+
+      // A. Validar regresiones de compilación
+      const regressionResultObj: any = await regressionDetector.execute({ runCheck: true }, context);
+      const regressionResultStr = typeof regressionResultObj === "string" ? regressionResultObj : (regressionResultObj?.output || "");
+      try {
+        const result = JSON.parse(regressionResultStr);
+        if (result.status && result.status.startsWith("FAILED")) {
+          return `[SDD Transition Blocked] Transición rechazada por detección de errores o regresiones de compilación:\n\n${result.message}`;
+        }
+      } catch (e) {}
+
+      // B. Validar cobertura semántica de criterios de aceptación (Requerimientos)
+      const requirementResultObj: any = await requirementTracker.execute({ changeName: activeChangeName }, context);
+      const requirementResultStr = typeof requirementResultObj === "string" ? requirementResultObj : (requirementResultObj?.output || "");
+      try {
+        const result = JSON.parse(requirementResultStr);
+        if (result.status === "FAILED") {
+          return `[SDD Transition Blocked] Transición rechazada por falta de cobertura de pruebas para los criterios de aceptación:\n\n${result.message}`;
+        }
+      } catch (e) {}
+
+      // C. Validar Cooldown de dependencias agregadas en package.json en caliente
+      if (fs.existsSync(path.join(projectRoot, "package.json")) && fs.existsSync(path.join(projectRoot, ".git"))) {
+        try {
+          const diffOutput = execSync("git diff HEAD package.json", { cwd: projectRoot, encoding: "utf-8" });
+          const addedLines = diffOutput.split("\n").filter(l => l.startsWith("+") && !l.startsWith("+++"));
+          const depRegex = /"([^"]+)"\s*:\s*"([^"]+)"/;
+          for (const line of addedLines) {
+            const match = line.match(depRegex);
+            if (match) {
+              const pkg = match[1];
+              const version = match[2].replace(/[\^~>=]/g, ""); // Limpiar rangos
+              if (pkg === "zugzbot-sdd" || pkg.startsWith("@opencode-ai/")) continue;
+
+              const cooldownResultObj: any = await checkDependencyCooldown.execute({ package: pkg, version }, context);
+              const cooldownResultStr = typeof cooldownResultObj === "string" ? cooldownResultObj : (cooldownResultObj?.output || "");
+              try {
+                const cooldownResult = JSON.parse(cooldownResultStr);
+                if (cooldownResult.status === "BLOCKED") {
+                  return `[SDD Transition Blocked] Transición rechazada por violación de la regla de Cooldown de Dependencias de Terceros:\n\n${cooldownResult.message}`;
+                }
+              } catch (e) {}
+            }
+          }
+        } catch (e) {}
+      }
+    }
+
+    // 3. Transición a Fase 0 / Cierre (Commit final): Escanear secretos
+    if (args.nextPhase === 0) {
+      const secretScanResultObj: any = await secretScanner.execute({ scanAll: false }, context);
+      const secretScanResultStr = typeof secretScanResultObj === "string" ? secretScanResultObj : (secretScanResultObj?.output || "");
+      try {
+        const result = JSON.parse(secretScanResultStr);
+        if (result.status === "FAILED") {
+          return `[SDD Transition Blocked] Transición y Git Commit cancelados por advertencia de seguridad (Se encontraron secretos expuestos):\n\n${result.message}`;
+        }
+      } catch (e) {}
+    }
+
+    // Actualizar campos
+    lockfile.direction = direction;
+    lockfile.active_phase = args.nextPhase;
+    lockfile.status = args.status;
+    lockfile.last_updated = new Date().toISOString().split('T')[0];
+
+    if (args.activeSubagent) {
+      lockfile.active_subagent = args.activeSubagent;
+    } else {
+      lockfile.active_subagent = SUBAGENT_MAPPING[args.nextPhase] || "sdd-planner";
+    }
+
+    if (args.iteration !== undefined) {
+      lockfile.iteration = args.iteration;
+    }
+
+    if (args.changeName) {
+      lockfile.change_name = args.changeName;
+    }
+
+    if (args.complexity !== undefined) {
+      lockfile.complexity = args.complexity;
+    }
+
+    // Escribir los cambios
+    fs.writeFileSync(lockfilePath, JSON.stringify(lockfile, null, 2), "utf-8");
+
+    // Escribir en el log o auditoría interna del cambio activo si existe el directorio
+    if (lockfile.change_name && lockfile.change_name !== "nuevo-cambio") {
+      const changeDir = path.join(projectRoot, ".openspec/changes", lockfile.change_name);
+      if (fs.existsSync(changeDir)) {
+        const historyPath = path.join(changeDir, "phase_history.jsonl");
+
+        // Obtener analíticas de tokens y costos de la sesión desde el servidor OpenCode
+        const port = process.env.OPENCODE_PORT || "4096";
+        let tokenStats = { cost: 0, input: 0, output: 0 };
+        const modelsUsed = new Set<string>();
+        try {
+          const url = `http://127.0.0.1:${port}/session/${context.sessionID}/message`;
+          const response = await fetch(url);
+          if (response.ok) {
+            const messages: any = await response.json();
+            const list = Array.isArray(messages) ? messages : (messages?.data || []);
+            list.forEach((msg: any) => {
+              const info = msg.info || msg;
+              if (info && info.role === "assistant") {
+                const cost = typeof info.cost === "number" && Number.isFinite(info.cost) ? info.cost : 0;
+                const input = info.tokens?.input ?? 0;
+                const output = info.tokens?.output ?? 0;
+                tokenStats.cost += cost;
+                tokenStats.input += input;
+                tokenStats.output += output;
+
+                // Extraer identificador de modelo de IA usado
+                const modelVal = info.modelID || (info.model && typeof info.model === "object" ? info.model.modelID : info.model);
+                if (modelVal) {
+                  modelsUsed.add(String(modelVal));
+                }
+              }
+            });
+          }
+        } catch (e) {}
+
+        const logEntry = {
+          timestamp: new Date().toISOString(),
+          phase: args.nextPhase,
+          subagent: lockfile.active_subagent,
+          status: args.status,
+          reason: args.reason,
+          iteration: lockfile.iteration || 0,
+          analytics: {
+            session_id: context.sessionID,
+            models_used: Array.from(modelsUsed),
+            cumulative_cost_usd: tokenStats.cost,
+            cumulative_tokens_input: tokenStats.input,
+            cumulative_tokens_output: tokenStats.output
+          }
+        };
+        fs.appendFileSync(historyPath, JSON.stringify(logEntry) + "\n", "utf-8");
+      }
+    }
+
+    // INTEGRACIÓN AUTOMÁTICA CON GIT
+    let gitStatus = "";
+    if (fs.existsSync(path.join(projectRoot, ".git")) && lockfile.change_name && lockfile.change_name !== "nuevo-cambio") {
+      try {
+        const branchName = `sdd/change-${lockfile.change_name}`;
+        
+        // 1. Chequear rama actual
+        const currentBranch = execSync("git rev-parse --abbrev-ref HEAD", { cwd: projectRoot, encoding: "utf-8" }).trim();
+        
+        if (currentBranch !== branchName) {
+          // Chequear si la rama existe localmente
+          let branchExists = false;
+          try {
+            execSync(`git show-ref --verify --quiet refs/heads/${branchName}`, { cwd: projectRoot });
+            branchExists = true;
+          } catch (e) {}
+
+          if (branchExists) {
+            execSync(`git checkout ${branchName}`, { cwd: projectRoot, stdio: "ignore" });
+          } else {
+            execSync(`git checkout -b ${branchName}`, { cwd: projectRoot, stdio: "ignore" });
+          }
+        }
+
+        // 2. Hacer commit automático de los artefactos .openspec/
+        execSync("git add .openspec/", { cwd: projectRoot, stdio: "ignore" });
+        
+        const commitMsg = `docs(sdd): transition to phase ${args.nextPhase} - ${args.reason.replace(/"/g, '\\"')}`;
+        execSync(`git commit -m "${commitMsg}"`, { cwd: projectRoot, stdio: "ignore" });
+        
+        gitStatus = ` [Git: Rama '${branchName}' actualizada con commit semántico]`;
+      } catch (e: any) {
+        gitStatus = ` [Git Warning: No se pudo realizar commit automático: ${e.message || e}]`;
+      }
+    }
+
+    return `[SDD Tool] Fase transicionada con éxito a Fase ${args.nextPhase} (${lockfile.active_subagent}). Estado: ${args.status}. Motivo: ${args.reason}.${gitStatus}`;
+  }
+})

package/tools/sdd_ui_auditor.ts

@@ -0,0 +1,310 @@
+import { tool } from "@opencode-ai/plugin"
+import fs from "fs"
+import path from "path"
+import { execSync } from "child_process"
+
+function decodeGitPath(gitPath: string): string {
+  let cleaned = gitPath.replace(/^"|"$/g, "")
+  if (cleaned.includes("\\")) {
+    try {
+      const bytes: number[] = []
+      let i = 0
+      while (i < cleaned.length) {
+        if (cleaned[i] === "\\" && i + 3 < cleaned.length && /^[0-7]{3}$/.test(cleaned.substring(i + 1, i + 4))) {
+          const octalVal = cleaned.substring(i + 1, i + 4)
+          bytes.push(parseInt(octalVal, 8))
+          i += 4
+        } else {
+          if (cleaned[i] === "\\" && i + 1 < cleaned.length) {
+            const next = cleaned[i + 1]
+            if (next === "n") { bytes.push(10); i += 2 }
+            else if (next === "t") { bytes.push(9); i += 2 }
+            else if (next === "\\") { bytes.push(92); i += 2 }
+            else if (next === "\"") { bytes.push(34); i += 2 }
+            else { bytes.push(cleaned.charCodeAt(i)); i++ }
+          } else {
+            const code = cleaned.charCodeAt(i)
+            if (code < 128) {
+              bytes.push(code)
+            } else {
+              const buf = Buffer.from(cleaned[i], "utf-8")
+              for (let b = 0; b < buf.length; b++) {
+                bytes.push(buf[b])
+              }
+            }
+            i++
+          }
+        }
+      }
+      return Buffer.from(bytes).toString("utf-8")
+    } catch (e) {
+      return cleaned.replace(/\\([0-7]{3})/g, (match, octal) => {
+        return String.fromCharCode(parseInt(octal, 8))
+      })
+    }
+  }
+  return cleaned
+}
+
+function sanitizeGitPath(line: string): string {
+  const content = line.substring(3).trim()
+  if (content.includes(" -> ")) {
+    const parts = content.split(" -> ")
+    return decodeGitPath(parts[1])
+  }
+  return decodeGitPath(content)
+}
+
+function checkHtmlTagBalance(filePath: string, content: string): string[] {
+  const ext = path.extname(filePath).toLowerCase();
+  if (![".html", ".tsx", ".jsx", ".ts", ".js"].includes(ext)) {
+    return [];
+  }
+
+  const issues: string[] = [];
+  const tagsToCheck = ["div", "span", "section", "p", "button", "main", "header", "footer", "a", "ul", "ol", "li"];
+  
+  let cleaned = content;
+  if (ext === ".html") {
+    cleaned = content.replace(/<!--[\s\S]*?-->/g, "");
+    cleaned = cleaned.replace(/<script[\s\S]*?<\/script>/gi, "");
+    cleaned = cleaned.replace(/<style[\s\S]*?<\/style>/gi, "");
+  } else {
+    cleaned = content.replace(/\/\*[\s\S]*?\*\/|\/\/.*/g, ""); // JS/TS comments
+  }
+
+  for (const tag of tagsToCheck) {
+    const openRegex = new RegExp(`<${tag}\\b[^>]*[^/]>`, "gi");
+    const closeRegex = new RegExp(`</${tag}\\s*>`, "gi");
+
+    let openCount = 0;
+    let closeCount = 0;
+
+    let match;
+    while ((match = openRegex.exec(cleaned)) !== null) {
+      openCount++;
+    }
+    while ((match = closeRegex.exec(cleaned)) !== null) {
+      closeCount++;
+    }
+
+    if (openCount !== closeCount) {
+      issues.push(
+        `Desbalance en etiquetas '<${tag}>': Encontradas ${openCount} de apertura y ${closeCount} de cierre. Esto puede quebrar el DOM global de la aplicación.`
+      );
+    }
+  }
+
+  return issues;
+}
+
+export default tool({
+  description: "Audita la estética de la interfaz de usuario en busca de colores genéricos, fuentes predeterminadas del navegador y verifica el cumplimiento de las directrices visuales premium (sdd-ux-premium) de forma localizada.",
+  args: {
+    changeName: tool.schema.string().optional().describe("El nombre del cambio activo en kebab-case. Si no se provee, se detectará automáticamente."),
+    localPort: tool.schema.number().optional().describe("Puerto del servidor de desarrollo local (ej: 3000) para intentar capturar screenshot opcional.")
+  },
+  async execute(args, context) {
+    const projectRoot = context.worktree || context.directory;
+    
+    // 1. Detectar el cambio activo
+    let changeName = args.changeName;
+    if (!changeName) {
+      const lockfilePath = path.join(projectRoot, ".openspec/sdd-lock.json");
+      const altLockPath = path.join(projectRoot, "openspec/sdd-lock.json");
+      let activeLockPath = fs.existsSync(lockfilePath) ? lockfilePath : (fs.existsSync(altLockPath) ? altLockPath : null);
+      if (activeLockPath) {
+        try {
+          const lockObj = JSON.parse(fs.readFileSync(activeLockPath, "utf-8"));
+          if (lockObj.change_name && lockObj.change_name !== "nuevo-cambio") {
+            changeName = lockObj.change_name;
+          }
+        } catch (e) {}
+      }
+    }
+
+    if (!changeName) {
+      changeName = "nuevo-cambio";
+    }
+
+    const reportDir = path.join(projectRoot, ".openspec/changes", changeName);
+    if (!fs.existsSync(reportDir)) {
+      fs.mkdirSync(reportDir, { recursive: true });
+    }
+
+    const reportPath = path.join(reportDir, "ui_report.md");
+
+    // 2. Recopilar archivos a auditar de forma localizada (Regla de Impacto Localizado)
+    const filesToAudit = new Set<string>();
+
+    // A. Buscar archivos modificados en Git que sean de UI
+    if (fs.existsSync(path.join(projectRoot, ".git"))) {
+      try {
+        const gitOutput = execSync("git status --porcelain", { cwd: projectRoot, encoding: "utf-8" });
+        gitOutput.split("\n").forEach(line => {
+          if (!line || line.length < 4) return;
+          const filePathRel = sanitizeGitPath(line);
+          const ext = path.extname(filePathRel).toLowerCase();
+          if ([".css", ".tsx", ".jsx", ".html"].includes(ext)) {
+            filesToAudit.add(filePathRel);
+          }
+        });
+      } catch (e) {}
+    }
+
+    // B. Buscar archivos listados en el spec.md activo
+    const specPath = path.join(projectRoot, ".openspec/changes", changeName, "specs/spec.md");
+    if (fs.existsSync(specPath)) {
+      try {
+        const specContent = fs.readFileSync(specPath, "utf-8");
+        const fileRegex = /[`']([^`']+\.(css|tsx|jsx|html))[`']/gi;
+        let match;
+        while ((match = fileRegex.exec(specContent)) !== null) {
+          const matchedFile = match[1].trim();
+          if (fs.existsSync(path.join(projectRoot, matchedFile))) {
+            filesToAudit.add(matchedFile);
+          }
+        }
+      } catch (e) {}
+    }
+
+    // 3. Escaneo de las clases y estilos UI
+    const nonPremiumColors = [
+      /\b(red|blue|green|yellow|black|white|purple|orange|pink|gray|grey)\b/i,
+      /#(ff0000|0000ff|00ff00|ffff00|000000|ffffff)\b/i
+    ];
+
+    const premiumFonts = ["Inter", "Outfit", "Roboto", "Sans-Serif", "system-ui", "sans-serif"];
+
+    interface FileFinding {
+      file: string;
+      colorIssues: string[];
+      fontIssues: string[];
+      hasTransitions: boolean;
+      structuralIssues: string[];
+    }
+
+    const findings: FileFinding[] = [];
+
+    filesToAudit.forEach(fileRel => {
+      const fullPath = path.join(projectRoot, fileRel);
+      if (!fs.existsSync(fullPath)) return;
+      try {
+        const content = fs.readFileSync(fullPath, "utf-8");
+        const colorIssues: string[] = [];
+        const fontIssues: string[] = [];
+        let hasTransitions = false;
+
+        // Analizar líneas
+        const lines = content.split("\n");
+        lines.forEach((line, index) => {
+          // Chequear colores
+          if (line.includes("color") || line.includes("bg-") || line.includes("background") || line.includes("border")) {
+            nonPremiumColors.forEach(reg => {
+              const match = line.match(reg);
+              if (match) {
+                colorIssues.push(`Línea ${index + 1}: ${line.trim()} (Detectado color genérico '${match[0]}')`);
+              }
+            });
+          }
+          
+          // Chequear transiciones
+          if (line.includes("transition") || line.includes("cubic-bezier") || line.includes("animate-")) {
+            hasTransitions = true;
+          }
+        });
+
+        // Chequear fuentes
+        if (content.includes("font-family")) {
+          const hasPremium = premiumFonts.some(f => content.includes(f));
+          if (!hasPremium) {
+            fontIssues.push("Define 'font-family' pero no incluye fuentes premium recomendadas (Inter, Outfit, etc.).");
+          }
+        }
+
+        // Chequear balance estructural HTML/DOM
+        const structuralIssues = checkHtmlTagBalance(fileRel, content);
+
+        if (colorIssues.length > 0 || fontIssues.length > 0 || !hasTransitions || structuralIssues.length > 0) {
+          findings.push({
+            file: fileRel,
+            colorIssues: colorIssues.slice(0, 5), // Limitar a 5 por archivo
+            fontIssues,
+            hasTransitions,
+            structuralIssues
+          });
+        }
+      } catch (e) {}
+    });
+
+    // 4. Intento de Screenshot Headless (Opcional si provee puerto)
+    let screenshotStatus = "No ejecutado (Puerto no provisto o dev server inactivo)";
+    let screenshotPathRel = "";
+    if (args.localPort) {
+      try {
+        const screenshotFile = path.join(reportDir, "screenshot_ui.png");
+        execSync(`npx -y playwright-cli screenshot http://localhost:${args.localPort} ${screenshotFile} --timeout 5000`, { stdio: "ignore" });
+        if (fs.existsSync(screenshotFile)) {
+          screenshotStatus = `Captura realizada con éxito en puerto ${args.localPort}!`;
+          screenshotPathRel = `./screenshot_ui.png`;
+        }
+      } catch (e: any) {
+        screenshotStatus = `Intento fallido de captura: ${e.message || e}`;
+      }
+    }
+
+    // 5. Escribir reporte markdown premium
+    let totalIssues = 0;
+    findings.forEach(f => totalIssues += f.colorIssues.length + f.fontIssues.length + f.structuralIssues.length + (f.hasTransitions ? 0 : 1));
+
+    const markdown = `# 🎨 Reporte de Auditoría Estética y Estructural UI/UX: ${changeName}
+
+Este reporte ha sido autogenerado por la herramienta premium **sdd_ui_auditor** para auditar el cumplimiento estricto de las directrices de percepción visual **sdd-ux-premium** y balance estructural de marcado de manera focalizada.
+
+> [!NOTE]
+> **Resumen del Diagnóstico Estético y Estructural (Impacto Localizado):**
+> - **Total de Errores/Advertencias:** ${totalIssues}
+> - **Archivos de UI Auditados con Observaciones:** ${findings.length}
+> - **Captura de Pantalla Visual:** ${screenshotStatus}
+
+${screenshotPathRel ? `### 📸 Captura de Pantalla Realizada\n![UI Realtime Live](${screenshotPathRel})\n` : ""}
+
+## 📊 Detalle de Archivos Escaneados
+
+${findings.length === 0 ? "### ¡Felicidades! 🎉 No se encontraron problemas estéticos ni de marcado en los archivos modificados. Tu UI sigue las directrices premium al 100%." : findings.map(f => `
+### 📁 Archivo: \`${f.file}\`
+- **Micro-animaciones / Transiciones:** ${f.hasTransitions ? "🟢 Detectadas" : "🟡 **FALTAN TRANSICIONES SUAVES** (Agrega cubic-bezier o transition)"}
+${f.structuralIssues.length > 0 ? `- **Errores de Marcado Estructural (DOM):**\n${f.structuralIssues.map(s => `  - 🔴 ${s}`).join("\n")}` : "🟢 Balance de etiquetas HTML correcto"}
+${f.colorIssues.length > 0 ? `- **Colores Genéricos Detectados:**\n${f.colorIssues.map(c => `  - ${c}`).join("\n")}` : "🟢 Colores correctos"}
+${f.fontIssues.length > 0 ? `- **Estilo Tipográfico:**\n${f.fontIssues.map(fi => `  - ${fi}`).join("\n")}` : "🟢 Tipografía correcta o heredada correctamente"}
+`).join("\n---\n")}
+
+---
+
+## 💡 Recomendaciones para Diseño Premium
+
+1. **Reemplazo de Colores Planos:**
+   - En lugar de usar colores puros o genéricos (como rojo, azul o gris plano), define una paleta HSL adaptada.
+   - *Ejemplo:* Usa HSL con tonos pastel sofisticados o grises de base carbón (\`hsl(220, 15%, 16%)\`).
+
+2. **Tipografía moderna en CSS:**
+   - Asegura la importación de una tipografía de alta fidelidad:
+     \`\`\`css
+     @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;600&display=swap');
+     body {
+       font-family: 'Inter', sans-serif;
+     }
+     \`\`\`
+
+3. **Curvas de Transición Suaves:**
+   - En efectos hover o interactivos, evita transiciones secas de 0.1s. Utiliza:
+     \`\`\`css
+     transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+     \`\`\`
+`;
+
+    fs.writeFileSync(reportPath, markdown, "utf-8");
+
+    return `[SDD UI Auditor] Reporte de estética UI generado con éxito en ${path.relative(projectRoot, reportPath)}. Total advertencias: ${totalIssues}.`;
+  }
+})