zugzbot-sdd 1.5.26 → 1.5.28

package/.opencode/skills/sdd-auto-api-mocker/SKILL.md

@@ -0,0 +1,62 @@
+# Skill: SDD Automatic API Mocker
+
+Esta habilidad permite al enjambre (`@sdd-builder`, `@sdd-tester`) autogenerar simulaciones (mocks) locales inteligentes de APIs de terceros y objetos globales difíciles de simular (ej. Google Apps Script como `SpreadsheetApp`, clasp, APIs de pago o servicios externos).
+
+## Trigger
+
+Se activa de manera automática en la **Fase 2 (Construcción)** o **Fase 3 (Calidad)** cuando:
+1. El archivo `diagnostics.md` o `spec.md` indica dependencias de APIs o globales inaccesibles localmente.
+2. Los tests unitarios fallan debido a referencias indefinidas (`ReferenceError` o `NetworkError`).
+
+## Directrices de Simulación (Mocks)
+
+Al simular una API, el `@sdd-builder` debe seguir estas reglas estructuradas:
+
+### 1. Inyección de Mocks en Entornos Globales
+Si el host es un entorno web o un sandbox interactivo sin Node.js (ej. Google Apps Script), inyecta los mocks al inicio del archivo de pruebas o mediante un archivo `global_mock.js` aislado:
+
+```javascript
+// global_mock.js
+if (typeof SpreadsheetApp === 'undefined') {
+  globalThis.SpreadsheetApp = {
+    getActiveSpreadsheet: () => ({
+      getActiveSheet: () => ({
+        getName: () => "Sheet1",
+        getDataRange: () => ({
+          getValues: () => [["Encabezado 1", "Encabezado 2"], ["Fila 1 Col 1", "Fila 1 Col 2"]]
+        }),
+        getRange: () => ({
+          setValue: () => {},
+          getValue: () => "CeldaSimulada"
+        })
+      })
+    })
+  };
+}
+```
+
+### 2. Estructura de Aislamiento de Red (Fetch/REST APIs)
+Evita llamadas reales a servicios HTTP/HTTPS externos interceptando `globalThis.fetch` o inyectando simuladores específicos de API:
+
+```javascript
+// mock_fetch.js
+const mockResponses = {
+  "https://api.github.com/repos/": { status: 200, json: async () => ({ name: "zugzbot" }) }
+};
+
+globalThis.fetch = async (url) => {
+  const match = Object.keys(mockResponses).find(k => url.startsWith(k));
+  if (match) return mockResponses[match];
+  throw new Error(`[Mock Error] Llamada a red no mockeada para URL: ${url}`);
+};
+```
+
+## Criterios de Aceptación (QA)
+
+- `[ ]` **No Invasivo:** Ningún mock o código de simulación debe colarse en los archivos de producción final. Deben permanecer exclusivamente bajo la carpeta de pruebas `tests/` o archivos temporales de QA.
+- `[ ]` **Transparencia:** Las aserciones de la UI o lógica del negocio no deben detectar la diferencia entre el entorno mockeado y el real.
+- `[ ]` **Limpieza:** Una vez completada la validación, el `@sdd-tester` debe restaurar los entornos globales modificados.
+
+## Tags
+
+#sdd #mocking #sandbox #isolation #gas #api

package/.opencode/skills/sdd-root-cause-diagnostician/SKILL.md

@@ -0,0 +1,48 @@
+# Skill: SDD Root Cause Diagnostician
+
+Esta habilidad dota al enjambre de Inteligencia Artificial de capacidades explicativas profundas al detectar fallas en las Fases de Calidad (F3) y Construcción (F2), impidiendo bucles correctivos infinitos mediante el aislamiento del error real y la inyección de guías de remediación inmediatas.
+
+## Trigger
+
+Se activa cuando:
+1. `tools/sdd_regression_detector` retorna `status: "FAILED"` o `status: "FAILED_LOCAL"`.
+2. Las pruebas unitarias o linters fallan de manera persistente tras un reintento.
+
+## Proceso de Diagnóstico Semántico
+
+Al ocurrir una falla, el `@sdd-tester` o `@sdd-builder` debe invocar este proceso cognitivo:
+
+### 1. Extracción del Sintoma vs Causa
+No asumas que el primer error en la pila de llamadas (stacktrace) es el origen real.
+* **Acción:** Busca la línea superior del stacktrace que pertenezca a los archivos modificados listados en `spec.md`. Compara los tipos de parámetros esperados con los provistos.
+
+### 2. Generación del Reporte de Causa Raíz
+Crea un archivo temporal `.openspec/diagnostics/root_cause.md` detallando de forma directa y visual el origen del quiebre:
+
+```markdown
+# 🔍 Diagnóstico de Causa Raíz: [nombre-falla]
+
+## 1. El Quiebre Detectado
+- **Síntoma:** `TypeError: Cannot read properties of undefined (reading 'getName')`
+- **Ubicación:** `src/components/Sidebar.tsx:L45`
+
+## 2. El Origen Real (Causa Raíz)
+El objeto `activeSheet` se consulta de forma asíncrona sin un bloque guardián. En entornos locales mockeados, esta resolución tarda 5ms más de lo esperado, haciendo que la llamada posterior se ejecute sobre un valor `null`.
+
+## 3. Pista de Remediación (Remediation Hint)
+Asegurar la validación del objeto antes de invocar propiedades:
+```typescript
+const sheetName = activeSheet ? activeSheet.getName() : "Sin Nombre";
+```
+
+### 3. Inyección en el Bucle de Retorno
+Cuando el ciclo correctivo transicione la fase hacia atrás (Fase 2) o repita la actual, el orquestador `@zugzbot` debe inyectar este archivo `root_cause.md` como entrada prioritaria de contexto en el chat "lienzo en blanco" del `@sdd-builder`.
+
+## Criterios de Aceptación (QA)
+
+- `[ ]` **Precisión:** El reporte de causa raíz debe contener una pista de remediación de código lista para ser asimilada por el constructor.
+- `[ ]` **Sin Bucles:** Ningún corrective loop debe superar las 3 iteraciones una vez inyectadas las pistas de causa raíz.
+
+## Tags
+
+#sdd #corrective-loops #debugging #diagnostics #root-cause #recovery

package/.opencode/skills/sdd-semantic-context-pruner/SKILL.md

@@ -0,0 +1,45 @@
+# Skill: SDD Semantic Context Pruning
+
+Esta habilidad define las reglas y heurísticas de ingeniería de prompts para recortar selectivamente los cuerpos de las funciones y código irrelevante en las solicitudes al LLM. Esto reduce el consumo de tokens de entrada hasta en un 70% y mejora sustancialmente la precisión y velocidad de los agentes.
+
+## Trigger
+
+Se ejecuta activamente en la **Fase 0 (Explorer)**, **Fase 1 (Planner)** y al delegar tareas a subagentes de **Construcción (F2)**.
+
+## Reglas Operativas de Poda de Contexto
+
+El planificador u orquestador debe seguir estas directivas antes de inyectar archivos grandes en el contexto del LLM:
+
+### 1. Poda por Dependencia Localizada (Impacto Acotado)
+No inyectes archivos completos si no están listados en el `spec.md` o en las líneas directamente afectadas obtenidas por `git diff`.
+* **Acción:** Si una función del archivo A llama a una función del archivo B, pero el cambio solo afecta a A, inyecta el archivo A completo y **únicamente la firma de la función** del archivo B.
+
+### 2. Estructura de Poda de Código (Signatures Only)
+Cuando debas referenciar módulos externos gigantes, reemplaza el cuerpo del método por un comentario descriptivo:
+
+```typescript
+// ANTES (Cargar todo es ruidoso y costoso):
+export function processTransaction(tx: Transaction) {
+  // ... 300 líneas de lógica de validación, firma, logs, db calls, etc. ...
+}
+
+// DESPUÉS (Firma limpia y tipada):
+/**
+ * Procesa una transacción financiera en base a reglas de negocio.
+ * @param tx Objeto de transacción tipado.
+ */
+export function processTransaction(tx: Transaction): TransactionResult; // [Cuerpo omitido por Poda Semántica]
+```
+
+### 3. Poda Incremental de Archivos de Historial
+Evita enviar historiales acumulados enteros de fallas de compilación o conversaciones previas largas.
+* **Acción:** Provee únicamente el último log de error y el archivo `sdd-lock.json` actualizado para dotar al subagente de un hilo limpio (lienzo en blanco).
+
+## Criterios de Aceptación (QA)
+
+- `[ ]` **Eficiencia:** Las delegaciones de prompts a subagentes complejos no deben exceder el 30% del tamaño total del repositorio.
+- `[ ]` **Sin Amnesia:** La información requerida de tipos, parámetros de retorno y convenciones del repositorio (`AGENTS.md`) debe preservarse de forma compacta en todo momento.
+
+## Tags
+
+#sdd #context-pruning #prompt-engineering #token-economy #optimization

package/.opencode/tools/gas_clasp_tools.js

@@ -0,0 +1,97 @@
+import { tool } from "@opencode-ai/plugin";
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+export default tool({
+    description: "Herramienta premium de integración con Google Apps Script (GAS) a través de Clasp. Permite realizar push, pull, consultar despliegues y verificar configuraciones de clasp de forma nativa.",
+    args: {
+        action: tool.schema.enum(["push", "pull", "status", "deployments"]).describe("La acción de clasp a realizar: push (subir cambios a GAS), pull (descargar cambios de GAS), status (verificar archivos subibles/ignorados), deployments (listar despliegues y URLs)"),
+        changeName: tool.schema.string().optional().describe("Nombre del cambio activo en .openspec/changes/ para verificar logs de QA previos")
+    },
+    async execute(args, context) {
+        const projectRoot = context.worktree || context.directory;
+        const claspConfigPath = path.join(projectRoot, ".clasp.json");
+        if (!fs.existsSync(claspConfigPath)) {
+            return JSON.stringify({
+                status: "FAILED",
+                reason: "❌ ERROR: No se encontró el archivo de configuración '.clasp.json' en la raíz del proyecto. ¿Es este un proyecto de Google Apps Script válido?"
+            }, null, 2);
+        }
+        let claspJson = {};
+        try {
+            claspJson = JSON.parse(fs.readFileSync(claspConfigPath, "utf-8"));
+        }
+        catch (e) {
+            return JSON.stringify({
+                status: "FAILED",
+                reason: "❌ ERROR: El archivo de configuración '.clasp.json' tiene un formato JSON inválido."
+            }, null, 2);
+        }
+        const scriptId = claspJson.scriptId;
+        if (!scriptId) {
+            return JSON.stringify({
+                status: "FAILED",
+                reason: "❌ ERROR: No se definió 'scriptId' en '.clasp.json'."
+            }, null, 2);
+        }
+        try {
+            // 1. Configurar comandos clasp
+            let claspCmd = "npx clasp";
+            if (args.action === "push") {
+                const output = execSync(`${claspCmd} push`, { cwd: projectRoot, encoding: "utf-8", stdio: "pipe" });
+                return JSON.stringify({
+                    status: "SUCCESS",
+                    action: "push",
+                    scriptId,
+                    message: "✅ CLASP PUSH EXITOSO: Los archivos locales se han subido a Google Apps Script sin colisiones.",
+                    output: output.trim()
+                }, null, 2);
+            }
+            if (args.action === "pull") {
+                const output = execSync(`${claspCmd} pull`, { cwd: projectRoot, encoding: "utf-8", stdio: "pipe" });
+                return JSON.stringify({
+                    status: "SUCCESS",
+                    action: "pull",
+                    scriptId,
+                    message: "✅ CLASP PULL EXITOSO: El código remoto de Google Apps Script se ha descargado a local.",
+                    output: output.trim()
+                }, null, 2);
+            }
+            if (args.action === "status") {
+                const output = execSync(`${claspCmd} status`, { cwd: projectRoot, encoding: "utf-8", stdio: "pipe" });
+                return JSON.stringify({
+                    status: "SUCCESS",
+                    action: "status",
+                    scriptId,
+                    message: "✅ CLASP STATUS:",
+                    output: output.trim()
+                }, null, 2);
+            }
+            if (args.action === "deployments") {
+                const output = execSync(`${claspCmd} deployments`, { cwd: projectRoot, encoding: "utf-8", stdio: "pipe" });
+                const webAppUrl = `https://script.google.com/macros/s/${scriptId}/exec`;
+                return JSON.stringify({
+                    status: "SUCCESS",
+                    action: "deployments",
+                    scriptId,
+                    webAppUrl,
+                    message: "✅ DESPLIEGUES ACTIVOS OBTENIDOS:",
+                    output: output.trim()
+                }, null, 2);
+            }
+        }
+        catch (err) {
+            const stderr = err.stderr?.toString() || err.message || "";
+            return JSON.stringify({
+                status: "FAILED",
+                action: args.action,
+                scriptId,
+                reason: `❌ ERROR de ejecución de clasp ${args.action}: ${stderr.trim()}`
+            }, null, 2);
+        }
+        return JSON.stringify({
+            status: "FAILED",
+            reason: "Acción no reconocida."
+        }, null, 2);
+    }
+});

package/.opencode/tools/index.js

@@ -21,3 +21,4 @@ export { default as sdd_test_scaffold_generator } from './sdd_test_scaffold_gene
 export { default as sdd_spec_compliance_linter } from './sdd_spec_compliance_linter.js';
 export { default as sdd_sandbox_patcher } from './sdd_sandbox_patcher.js';
 export { default as sdd_context_pruner } from './sdd_context_pruner.js';
+export { default as gas_clasp_tools } from './gas_clasp_tools.js';

package/.opencode/tools/sdd_checkpoint.js

@@ -10,9 +10,15 @@ export default tool({
     },
     async execute(args, context) {
         const projectRoot = context.worktree || context.directory;
-        const lockfilePath = path.join(projectRoot, ".openspec/sdd-lock.json");
+        let lockfilePath = path.join(projectRoot, ".openspec/sdd-lock.json");
         if (!fs.existsSync(lockfilePath)) {
-            return "[SDD Checkpoint] ERROR: No existe sdd-lock.json. No se puede crear checkpoint.";
+            const altLockPath = path.join(projectRoot, "openspec/sdd-lock.json");
+            if (fs.existsSync(altLockPath)) {
+                lockfilePath = altLockPath;
+            }
+            else {
+                return "[SDD Checkpoint] ERROR: No existe sdd-lock.json. No se puede crear checkpoint.";
+            }
         }
         let lockfile = {};
         try {

package/.opencode/tools/sdd_regression_detector.js

@@ -74,13 +74,18 @@ function sanitizeGitPath(line) {
 // Analiza los errores de una salida de compilador y los mapea de forma limpia
 function parseCompilerErrors(errorOutput) {
     const errors = new Set();
-    const lines = errorOutput.split("\n").filter(l => l.trim());
+    const lines = errorOutput.split("\n").map(l => l.trim()).filter(Boolean);
+    let currentFile = "";
     lines.forEach(line => {
-        // Captura líneas que parezcan errores de compilador (archivo con número de línea y mensaje)
-        const fileMatch = line.match(/^([a-zA-Z0-9_\-./]+)\(/) || line.match(/^([a-zA-Z0-9_\-./]+):\d+/) || line.match(/in\s+([a-zA-Z0-9_\-./]+\.py)/);
+        // Captura líneas que parezcan referirse a un archivo con error
+        const fileMatch = line.match(/^([a-zA-Z0-9_\-./]+\.[a-zA-Z0-9]+)/i);
         if (fileMatch) {
-            // Normalizar simplificando detalles variables de error
-            errors.add(line.trim());
+            currentFile = fileMatch[1];
+        }
+        // Si la línea contiene palabras clave de error o aviso típico de compilación
+        if (line.includes("error") || line.includes("warning") || line.includes("Failed") || line.includes("Mismatched") || line.includes("Unclosed")) {
+            const errorMsg = currentFile ? `[${currentFile}] ${line}` : line;
+            errors.add(errorMsg);
         }
     });
     return errors;
@@ -103,6 +108,7 @@ export default tool({
         const hasGit = fs.existsSync(path.join(projectRoot, ".git"));
         if (hasGit) {
             try {
+                execSync("git config core.quotepath false", { cwd: projectRoot, stdio: "ignore" });
                 const gitOutput = execSync("git status --porcelain", { cwd: projectRoot, encoding: "utf-8" });
                 gitOutput.split("\n").forEach(line => {
                     if (!line || line.length < 4)

package/.opencode/tools/sdd_requirement_tracker.js

@@ -150,36 +150,47 @@ export default tool({
         }
         const auditResults = [];
         criteria.forEach(crit => {
-            // Extraer palabras clave de más de 3 letras ignorando conectores
-            const keywords = crit
-                .toLowerCase()
-                .replace(/[^a-záéíóúñü0-9\s]/g, "")
-                .split(/\s+/)
-                .filter(word => word.length > 3 && !["debe", "para", "como", "esta", "este", "consecuente"].includes(word));
+            // Verificar si el criterio individual tiene un bypass manual explícito
+            const isManualCrit = crit.toLowerCase().includes("[manual]") ||
+                crit.toLowerCase().includes("[e2e]") ||
+                crit.toLowerCase().includes("[qa manual]");
             let matched = false;
             let matchedFile = "";
             let matchedSnippet = "";
-            for (const testFile of testFiles) {
-                try {
-                    const testContent = fs.readFileSync(testFile, "utf-8");
-                    const testLines = testContent.split("\n");
-                    // Búsqueda aproximada: comprobar si el test contiene palabras clave del criterio
-                    for (let i = 0; i < testLines.length; i++) {
-                        const line = testLines[i].toLowerCase();
-                        // Si coincide con más del 60% de las palabras clave de un criterio en la misma línea
-                        const matchCount = keywords.filter(keyword => line.includes(keyword)).length;
-                        const threshold = Math.max(1, Math.floor(keywords.length * 0.5));
-                        if (matchCount >= threshold && threshold > 0) {
-                            matched = true;
-                            matchedFile = path.basename(testFile);
-                            matchedSnippet = `Línea ${i + 1}: ${testLines[i].trim()}`;
-                            break;
+            if (isManualCrit) {
+                matched = true;
+                matchedFile = "QA Manual / E2E Bypass";
+                matchedSnippet = "Validación manual explícita declarada en spec.md";
+            }
+            else {
+                // Extraer palabras clave de más de 3 letras ignorando conectores
+                const keywords = crit
+                    .toLowerCase()
+                    .replace(/[^a-záéíóúñü0-9\s]/g, "")
+                    .split(/\s+/)
+                    .filter(word => word.length > 3 && !["debe", "para", "como", "esta", "este", "consecuente"].includes(word));
+                for (const testFile of testFiles) {
+                    try {
+                        const testContent = fs.readFileSync(testFile, "utf-8");
+                        const testLines = testContent.split("\n");
+                        // Búsqueda aproximada: comprobar si el test contiene palabras clave del criterio
+                        for (let i = 0; i < testLines.length; i++) {
+                            const line = testLines[i].toLowerCase();
+                            // Si coincide con más del 60% de las palabras clave de un criterio en la misma línea
+                            const matchCount = keywords.filter(keyword => line.includes(keyword)).length;
+                            const threshold = Math.max(1, Math.floor(keywords.length * 0.5));
+                            if (matchCount >= threshold && threshold > 0) {
+                                matched = true;
+                                matchedFile = path.basename(testFile);
+                                matchedSnippet = `Línea ${i + 1}: ${testLines[i].trim()}`;
+                                break;
+                            }
                         }
+                        if (matched)
+                            break;
                     }
-                    if (matched)
-                        break;
+                    catch (e) { }
                 }
-                catch (e) { }
             }
             auditResults.push({
                 criterio: crit,

package/.opencode/tools/sdd_spec_compliance_linter.js

@@ -11,7 +11,11 @@ export default tool({
         const report = [];
         report.push(`━━━ sdd_spec_compliance_linter: ${args.changeName} ━━━`);
         const openspecDir = path.join(projectRoot, ".openspec");
-        const specFile = path.join(openspecDir, "changes", args.changeName, "spec.md");
+        const changeDir = path.join(openspecDir, "changes", args.changeName);
+        let specFile = path.join(changeDir, "specs/spec.md");
+        if (!fs.existsSync(specFile)) {
+            specFile = path.join(changeDir, "spec.md");
+        }
         let specContent = "";
         if (fs.existsSync(specFile)) {
             specContent = fs.readFileSync(specFile, "utf-8");
@@ -24,7 +28,12 @@ export default tool({
         }
         if (!specContent) {
             report.push("⚠ No se encontró ningún archivo `spec.md` activo para el cambio. Imposible realizar cruce de especificaciones.");
-            return report.join("\n");
+            return JSON.stringify({
+                status: "FAILED",
+                complianceRate: 0,
+                message: "No se encontró el archivo spec.md.",
+                report: report.join("\n")
+            }, null, 2);
         }
         // Extraer requerimientos
         const requirements = [];
@@ -108,6 +117,10 @@ export default tool({
         else {
             report.push("⚠ Atención: Completa los requerimientos huérfanos indicados arriba para evitar regresiones lógicas.");
         }
-        return report.join("\n");
+        return JSON.stringify({
+            status: complianceRate === 100 ? "APPROVED" : "FAILED",
+            complianceRate,
+            report: report.join("\n")
+        }, null, 2);
     }
 });

package/.opencode/tools/sdd_spec_validator.js

@@ -40,13 +40,13 @@ export default tool({
         const specContent = fs.readFileSync(specPath, "utf-8");
         // Secciones requeridas y sus expresiones regulares de validación según complejidad
         const requiredSections = [
-            { name: "Plano Técnico / Título", regex: /^# Plano Técnico de Especificación/m },
-            { name: "1. Diagnóstico y Archivos Afectados", regex: /^## 1\. Diagnóstico/m },
-            { name: "3. Propuesta de Solución y Arquitectura", regex: /^## 3\. Propuesta/m },
-            { name: "5. Criterios de Aceptación y Calidad", regex: /^## 5\. Criterios/m }
+            { name: "Plano Técnico / Título", regex: /^#\s*Plano\s+Técnico/mi },
+            { name: "1. Diagnóstico y Archivos Afectados", regex: /^##\s*1\.\s*Diagnóstico/mi },
+            { name: "3. Propuesta de Solución y Arquitectura", regex: /^##\s*3\.\s*Propuesta/mi },
+            { name: "5. Criterios de Aceptación y Calidad", regex: /^##\s*5\.\s*Criterios/mi }
         ];
         if (complexity !== "low") {
-            requiredSections.push({ name: "2. Consenso de Encuesta con el Usuario", regex: /^## 2\. Consenso/m }, { name: "4. Especificaciones BDD (Comportamiento)", regex: /^## 4\. Especificaciones BDD|Feature:/m });
+            requiredSections.push({ name: "2. Consenso de Encuesta con el Usuario", regex: /^##\s*2\.\s*Consenso/mi }, { name: "4. Especificaciones BDD (Comportamiento)", regex: /^##\s*4\.\s*Especificaciones BDD|Feature:/mi });
         }
         const missingSections = [];
         requiredSections.forEach(section => {

package/.opencode/tools/sdd_transition.js

@@ -128,7 +128,7 @@ export default tool({
             if (fs.existsSync(specPath)) {
                 try {
                     const specContent = fs.readFileSync(specPath, "utf-8");
-                    const qaSectionIndex = specContent.indexOf("## 5. Criterios de Aceptación");
+                    const qaSectionIndex = specContent.search(/##\s*5\s*[\.\s-]?\s*Criterios/i);
                     if (qaSectionIndex !== -1) {
                         const qaContent = specContent.substring(qaSectionIndex);
                         const lines = qaContent.split("\n");
@@ -165,9 +165,9 @@ export default tool({
                         const reportContent = fs.readFileSync(reportPath, "utf-8");
                         // Buscar sección QA con fallback: probar ## QA (template tester) primero,
                         // luego ## 3. Correspondencia de Criterios (template anterior), luego buscar - [x] en cualquier parte
-                        let qaSectionIndex = reportContent.indexOf("## QA");
+                        let qaSectionIndex = reportContent.search(/##\s*QA/i);
                         if (qaSectionIndex === -1) {
-                            qaSectionIndex = reportContent.indexOf("## 3. Correspondencia de Criterios");
+                            qaSectionIndex = reportContent.search(/##\s*3\s*[\.\s-]?\s*Correspondencia/i);
                         }
                         if (qaSectionIndex !== -1) {
                             const qaContent = reportContent.substring(qaSectionIndex);
@@ -370,9 +370,16 @@ export default tool({
                 }
                 // 2. Hacer commit automático de los artefactos .openspec/
                 execSync("git add .openspec/", { cwd: projectRoot, stdio: "ignore" });
-                const commitMsg = `docs(sdd): transición a fase ${args.nextPhase} - ${args.reason.replace(/"/g, '\\"')}`;
-                execSync(`git commit -m "${commitMsg}"`, { cwd: projectRoot, stdio: "ignore" });
-                gitStatus = ` [Git: Rama '${branchName}' actualizada con commit semántico]`;
+                // Verificar si hay cambios reales preparados en el stage (staged changes)
+                const hasStagedChanges = execSync("git diff --cached --name-only", { cwd: projectRoot, encoding: "utf-8" }).trim().length > 0;
+                if (hasStagedChanges) {
+                    const commitMsg = `docs(sdd): transición a fase ${args.nextPhase} - ${args.reason.replace(/"/g, '\\"')}`;
+                    execSync(`git commit -m "${commitMsg}"`, { cwd: projectRoot, stdio: "ignore" });
+                    gitStatus = ` [Git: Rama '${branchName}' actualizada con commit semántico]`;
+                }
+                else {
+                    gitStatus = ` [Git: Sin cambios nuevos en especificaciones para archivar]`;
+                }
             }
             catch (e) {
                 gitStatus = ` [Git Warning: No se pudo realizar commit automático: ${e.message || e}]`;

package/.opencode/tools/sdd_ui_auditor.js

@@ -77,7 +77,6 @@ function checkHtmlTagBalance(filePath, content) {
         return [];
     }
     const issues = [];
-    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, "");
@@ -87,22 +86,43 @@ function checkHtmlTagBalance(filePath, content) {
     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++;
+    // Strip TypeScript generic type arguments from function calls or declarations (e.g. createSignal<string[]>)
+    // JSX tags are never directly preceded by a word character (like \w+), whereas TS generics are.
+    cleaned = cleaned.replace(/(\w+)<([A-Za-z0-9_\[\]\s|]+)>/g, '$1');
+    const tagRegex = /<(\/?[a-zA-Z0-9:-]+)(?:\s+[^>]*?)?>/g;
+    const stack = [];
+    const selfClosingTags = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr']);
+    let match;
+    while ((match = tagRegex.exec(cleaned)) !== null) {
+        const fullTag = match[0];
+        const tagName = match[1].toLowerCase();
+        if (fullTag.endsWith('/>'))
+            continue;
+        if (selfClosingTags.has(tagName))
+            continue;
+        if (fullTag.startsWith('<?') || fullTag.endsWith('?>'))
+            continue;
+        if (fullTag.startsWith('<!'))
+            continue;
+        if (tagName.startsWith('/')) {
+            const closingName = tagName.substring(1);
+            if (stack.length === 0) {
+                issues.push(`Etiqueta de cierre sin apertura: </${closingName}>`);
+                break;
+            }
+            const lastOpen = stack.pop();
+            if (lastOpen !== closingName) {
+                issues.push(`Anidamiento roto: se esperaba </${lastOpen}> pero se encontró </${closingName}>`);
+                break;
+            }
         }
-        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.`);
+        else {
+            stack.push(tagName);
         }
     }
+    if (stack.length > 0 && issues.length === 0) {
+        issues.push(`Etiquetas sin cerrar: <${stack.join('>, <')}>`);
+    }
     return issues;
 }
 export default tool({

package/AGENTS.md

@@ -204,7 +204,13 @@ Feature: [Breve descripción de la funcionalidad]
 2. **🛡️ Cooldown de Dependencias**:
    - Cualquier dependencia agregada debe tener al menos **3 días de publicada** en el registro oficial. Carga la habilidad `sdd-dependency-cooldown` para verificar su antigüedad antes de cualquier importación.
 
-3. **🔬 Estructura Estándar de Testing Agnóstico**:
+3. **⚡ Directivas de Activación y Uso de Skills Premium**:
+   El enjambre cuenta con habilidades premium cargadas dinámicamente en `.opencode/skills/`. Todos los agentes deben invocar y apegarse estrictamente a estas guías bajo las siguientes condiciones:
+   - **`sdd-auto-api-mocker` (Triggers: Fase 2 / Fase 3)**: Si el proyecto host contiene APIs inaccesibles localmente (como objetos globales de Google Apps Script `SpreadsheetApp`, clasp, APIs REST de terceros, bases de datos remotas), el `@sdd-builder` y `@sdd-tester` deben activar esta habilidad para simular mocks de red y sandbox locales no invasivos.
+   - **`sdd-semantic-context-pruner` (Triggers: Fase 0 / Fase 1 / Fase 2)**: Al indexar archivos o delegar tareas, los agentes deben usar poda semántica para eliminar cuerpos de métodos no afectados y enviar únicamente declaraciones de firmas/tipos para optimizar el consumo de tokens en un 70%.
+   - **`sdd-root-cause-diagnostician` (Trigger: Fallo de validación en F3 / F2)**: Ante cualquier error de linter o compilación, el `@sdd-tester` debe ejecutar esta habilidad para redactar un diagnóstico de causa raíz accionable en `.openspec/diagnostics/root_cause.md`, eliminando bucles infinitos de fallas.
+
+4. **🔬 Estructura Estándar de Testing Agnóstico**:
    - Todo proyecto gestionado por el arnés debe estructurar su carpeta de pruebas `tests/` en tres subdirectorios específicos:
      * `tests/unit/`: Para pruebas unitarias de funciones aisladas.
      * `tests/static/`: Para validadores estáticos universales y agnósticos (ej: balance de etiquetas HTML en `tag_balance.js`, detección de IDs duplicados en `dom_structure.js`).