zugzbot-sdd 1.5.0

package/tools/sdd_archive_and_commit.ts

@@ -0,0 +1,207 @@
+import { tool } from "@opencode-ai/plugin"
+import fs from "fs"
+import path from "path"
+import { execSync } from "child_process"
+import sddInstallAutoskills from "./sdd_install_autoskills"
+import { BrainEntry, parseEntries, today, nextId, buildFullBrain, buildIndex, buildEntryBlock, readBrainFile } from "./brain-utils.js"
+
+function bumpVersion(version: string, type: "major" | "minor" | "patch"): string {
+  const parts = version.split(".").map(x => parseInt(x, 10))
+  if (parts.length !== 3 || parts.some(isNaN)) return version
+  if (type === "major") {
+    parts[0]++
+    parts[1] = 0
+    parts[2] = 0
+  } else if (type === "minor") {
+    parts[1]++
+    parts[2] = 0
+  } else if (type === "patch") {
+    parts[2]++
+  }
+  return parts.join(".")
+}
+
+function moveRecursive(src: string, dest: string) {
+  const stats = fs.statSync(src)
+  if (stats.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true })
+    fs.readdirSync(src).forEach(child => {
+      moveRecursive(path.join(src, child), path.join(dest, child))
+    })
+    fs.rmdirSync(src)
+  } else {
+    fs.renameSync(src, dest)
+  }
+}
+
+export default tool({
+  description: "Cierra el ciclo SDD de forma atómica: realiza el bump SemVer, inyecta lecciones en el cerebro, documenta en CHANGELOG, archiva el directorio de cambios y realiza el commit de cierre de Git.",
+  args: {
+    changeName: tool.schema.string().describe("Nombre del cambio activo (carpeta dentro de .openspec/changes/)"),
+    commitMessage: tool.schema.string().describe("Mensaje de commit detallado y semántico (Conventional Commit)"),
+    bumpType: tool.schema.enum(["patch", "minor", "major", "none"]).describe("Tipo de incremento de versión semántica"),
+    category: tool.schema.string().optional().describe("Categoría del aprendizaje para el cerebro"),
+    tag: tool.schema.string().optional().describe("Tag corto del aprendizaje para el cerebro"),
+    problem: tool.schema.string().optional().describe("Problema resuelto (máx 120 caracteres)"),
+    solution: tool.schema.string().optional().describe("Solución aplicada (máx 300 caracteres)")
+  },
+  async execute(args, context) {
+    const projectRoot = context.worktree || context.directory
+    const changeDir = path.join(projectRoot, ".openspec/changes", args.changeName)
+
+    if (!fs.existsSync(changeDir)) {
+      return `[SDD Archive Error] No se encontró la carpeta del cambio activo en: ${changeDir}`
+    }
+
+    const report: string[] = ["━━━ sdd_archive_and_commit ━━━"]
+
+    // 1. SemVer Bump en package.json
+    let versionStr = "1.0.0"
+    const pkgPath = path.join(projectRoot, "package.json")
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"))
+        const oldVer = pkg.version || "1.0.0"
+        if (args.bumpType && args.bumpType !== "none") {
+          versionStr = bumpVersion(oldVer, args.bumpType)
+          pkg.version = versionStr
+          fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8")
+          report.push(`✓ Versión incrementada en package.json: ${oldVer} → ${versionStr}`)
+        } else {
+          versionStr = oldVer
+          report.push(`- Sin cambios en package.json (versión: ${versionStr})`)
+        }
+      } catch (e: any) {
+        report.push(`⚠️ Error leyendo/escribiendo package.json: ${e.message}`)
+      }
+    }
+
+    // 2. Escribir entrada en CHANGELOG.md
+    const changelogPath = path.join(projectRoot, ".openspec/CHANGELOG.md")
+    const dateStr = today()
+    const changelogEntry = `### [${versionStr}] - ${dateStr}\n- ${args.commitMessage.split("\n")[0]}\n`
+    if (fs.existsSync(changelogPath)) {
+      try {
+        let content = fs.readFileSync(changelogPath, "utf-8")
+        const idx = content.indexOf("## ")
+        if (idx !== -1) {
+          content = content.slice(0, idx) + `## Historial de Versiones\n\n${changelogEntry}\n` + content.slice(idx + "## Historial de Versiones\n".length)
+        } else {
+          content = content + `\n${changelogEntry}`
+        }
+        fs.writeFileSync(changelogPath, content, "utf-8")
+        report.push(`✓ Registrada versión en .openspec/CHANGELOG.md`)
+      } catch (e: any) {
+        report.push(`⚠️ Error escribiendo CHANGELOG.md: ${e.message}`)
+      }
+    } else {
+      try {
+        const content = `# 📝 CHANGELOG\n\n## Historial de Versiones\n\n${changelogEntry}`
+        fs.writeFileSync(changelogPath, content, "utf-8")
+        report.push(`✓ Inicializado e indexado .openspec/CHANGELOG.md`)
+      } catch (e: any) {
+        report.push(`⚠️ Error inicializando CHANGELOG.md: ${e.message}`)
+      }
+    }
+
+    // 3. Sincronizar lección técnica con brain.md si se proveen datos
+    if (args.category && args.tag && args.problem && args.solution) {
+      const brainPath = path.join(projectRoot, ".openspec/brain.md")
+      try {
+        let entries: BrainEntry[] = []
+        if (fs.existsSync(brainPath)) {
+          const brainData = readBrainFile(brainPath)
+          entries = brainData.entries
+        }
+
+        const newEntry: BrainEntry = {
+          id: nextId(entries),
+          category: args.category,
+          tag: args.tag,
+          problem: args.problem,
+          solution: args.solution,
+          date: dateStr
+        }
+        entries.push(newEntry)
+        fs.writeFileSync(brainPath, buildFullBrain(entries), "utf-8")
+        report.push(`✓ Lección ${newEntry.id} inyectada con éxito en .openspec/brain.md`)
+      } catch (e: any) {
+        report.push(`⚠️ Error sincronizando cerebro: ${e.message}`)
+      }
+    }
+
+    // 3.5. Sincronizar habilidades de IA (Autoskills) de forma automática
+    try {
+      report.push("▶ Buscando y sincronizando habilidades de IA nuevas en base a tus cambios...")
+      const skillsOutputObj: any = await sddInstallAutoskills.execute({ dryRun: false }, context)
+      const skillsOutputStr = typeof skillsOutputObj === "string" ? skillsOutputObj : (skillsOutputObj?.output || "")
+      const shortSkillsOutput = skillsOutputStr
+        .split("\n")
+        .filter((l: string) => l.trim() && !l.startsWith("▶") && !l.startsWith("━━━"))
+        .map((l: string) => `  ${l}`)
+        .join("\n")
+      report.push(`✓ Sincronización de Habilidades Finalizada:\n${shortSkillsOutput || "  No se encontraron nuevas habilidades que instalar."}`)
+    } catch (e: any) {
+      report.push(`⚠️ Sincronización automática de habilidades fallida o no disponible: ${e.message || e}`)
+    }
+
+    // 4. Escribir commit_message.txt en location TEMPORAL antes de archivar
+    const tempCommitMsgPath = path.join(projectRoot, ".openspec", `commit_msg_${args.changeName}.txt`)
+    try {
+      fs.writeFileSync(tempCommitMsgPath, args.commitMessage + "\n", "utf-8")
+      report.push(`✓ Archivo commit_message.txt generado en location temporal`)
+    } catch (e: any) {
+      report.push(`⚠️ Error escribiendo commit_message.txt: ${e.message}`)
+    }
+
+    // 5. Resetear el lockfile a idle (ANTES del commit para incluirlo en el cierre)
+    const lockfilePath = path.join(projectRoot, ".openspec/sdd-lock.json")
+    if (fs.existsSync(lockfilePath)) {
+      try {
+        const lockfile = JSON.parse(fs.readFileSync(lockfilePath, "utf-8"))
+        lockfile.active_phase = 0
+        lockfile.active_subagent = "sdd-planner"
+        lockfile.status = "idle"
+        lockfile.last_updated = dateStr
+        fs.writeFileSync(lockfilePath, JSON.stringify(lockfile, null, 2), "utf-8")
+        report.push(`✓ Lockfile .openspec/sdd-lock.json restablecido a 'idle'`)
+      } catch (e: any) {
+        report.push(`⚠️ No se pudo restablecer el lockfile: ${e.message}`)
+      }
+    }
+
+    // 6. Confirmación Git Atómica (usa temp commit msg, antes de archivar)
+    if (fs.existsSync(path.join(projectRoot, ".git"))) {
+      try {
+        execSync("git add .", { cwd: projectRoot, stdio: "ignore" })
+        execSync(`git commit -F "${tempCommitMsgPath}"`, { cwd: projectRoot, stdio: "ignore" })
+        report.push(`✓ Commit de Git ejecutado usando el mensaje semántico`)
+      } catch (e: any) {
+        report.push(`⚠️ Git Commit falló o no había cambios pendientes de código: ${e.message}`)
+      }
+    }
+
+    // 8. Archivar la carpeta físicamente (DESPUÉS del commit)
+    const archiveDir = path.join(projectRoot, ".openspec/changes/archive", `${dateStr}-${args.changeName}`)
+    try {
+      if (fs.existsSync(archiveDir)) {
+        fs.rmSync(archiveDir, { recursive: true, force: true })
+      }
+      fs.mkdirSync(path.dirname(archiveDir), { recursive: true })
+      moveRecursive(changeDir, archiveDir)
+      report.push(`✓ Carpeta archivada en: .openspec/changes/archive/${dateStr}-${args.changeName}/`)
+    } catch (e: any) {
+      return `[SDD Archive Error] Error crítico archivando carpetas: ${e.message}`
+    }
+
+    // 9. Limpiar archivo temporal de commit message
+    try {
+      if (fs.existsSync(tempCommitMsgPath)) {
+        fs.unlinkSync(tempCommitMsgPath)
+      }
+    } catch (e: any) {}
+
+    report.push("━━━ finalizado con éxito absoluto ━━━")
+    return report.join("\n")
+  }
+})

package/tools/sdd_bdd_tester.ts

@@ -0,0 +1,163 @@
+import { tool } from "@opencode-ai/plugin"
+import fs from "fs"
+import path from "path"
+import { execSync } from "child_process"
+
+export default tool({
+  description: "Traductor de Living Specs BDD: Parsea escenarios 'Given-When-Then' en spec.md y genera automáticamente esqueletos de pruebas reales en la suite del proyecto destino.",
+  args: {
+    changeName: tool.schema.string().optional().describe("Nombre del cambio en kebab-case. Por defecto se autodetectará del sdd-lock."),
+    runTests: tool.schema.boolean().optional().describe("Si es true, ejecuta la suite de pruebas local tras la generación.")
+  },
+  async execute(args, context) {
+    const projectRoot = context.worktree || context.directory;
+
+    // 1. Detectar 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") {
+      return `[BDD Tester Blocked] Error: No hay un cambio de desarrollo activo especificado o registrado en el sdd-lock.`;
+    }
+
+    // 2. Localizar spec.md
+    const specPath = path.join(projectRoot, ".openspec/changes", changeName, "specs/spec.md");
+    if (!fs.existsSync(specPath)) {
+      return `[BDD Tester Blocked] Error: No se pudo localizar el archivo de especificación en '${path.relative(projectRoot, specPath)}'.`;
+    }
+
+    // 3. Parsear escenarios Given-When-Then
+    const specContent = fs.readFileSync(specPath, "utf-8");
+    const scenarios: Array<{ title: string; steps: string[] }> = [];
+    
+    let currentScenarioTitle = "";
+    let currentSteps: string[] = [];
+
+    const lines = specContent.split("\n");
+    lines.forEach(line => {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("Scenario:") || trimmed.startsWith("Escenario:")) {
+        if (currentScenarioTitle) {
+          scenarios.push({ title: currentScenarioTitle, steps: currentSteps });
+        }
+        currentScenarioTitle = trimmed.substring(trimmed.indexOf(":") + 1).trim();
+        currentSteps = [];
+      } else if (currentScenarioTitle && (trimmed.startsWith("Given") || trimmed.startsWith("When") || trimmed.startsWith("Then") || trimmed.startsWith("And") || trimmed.startsWith("Dado") || trimmed.startsWith("Cuando") || trimmed.startsWith("Entonces") || trimmed.startsWith("Y "))) {
+        currentSteps.push(trimmed);
+      }
+    });
+
+    if (currentScenarioTitle) {
+      scenarios.push({ title: currentScenarioTitle, steps: currentSteps });
+    }
+
+    if (scenarios.length === 0) {
+      return `[BDD Tester Complete] Escaneo terminado: No se encontraron bloques estructurados 'Scenario:' o 'Given-When-Then' en spec.md.`;
+    }
+
+    // 4. Identificar Entorno y Autogenerar Pruebas
+    let testLanguage = "js"; // Default
+    let testFilePath = "";
+    let generatedCode = "";
+
+    if (fs.existsSync(path.join(projectRoot, "package.json"))) {
+      // Node/JS/TS Stack
+      const tsconfig = fs.existsSync(path.join(projectRoot, "tsconfig.json"));
+      testLanguage = tsconfig ? "ts" : "js";
+      
+      const testsDir = path.join(projectRoot, "tests");
+      if (!fs.existsSync(testsDir)) {
+        fs.mkdirSync(testsDir, { recursive: true });
+      }
+
+      testFilePath = path.join(testsDir, `sdd_${changeName.replace(/-/g, "_")}.test.${testLanguage}`);
+
+      // Detectar framework de pruebas en package.json de forma inteligente
+      let testFrameworkImport = "";
+      try {
+        const pkgContent = fs.readFileSync(path.join(projectRoot, "package.json"), "utf-8");
+        if (pkgContent.includes('"vitest"')) {
+          testFrameworkImport = "import { describe, it } from 'vitest';\n";
+        }
+      } catch (e) {}
+
+      generatedCode = `// ==============================================================================
+//  BDD LIVING SPECIFICATION AUTO-GENERATED TEST SUITE
+//  Generated for change: ${changeName}
+// ==============================================================================
+${testFrameworkImport}
+describe('SDD Living Spec: ${changeName}', () => {
+${scenarios.map(s => `  it('Escenario: ${s.title.replace(/'/g, "\\'")}', () => {
+    // BDD Scenario Specification Steps:
+${s.steps.map(step => `    // - ${step}`).join("\n")}
+    
+    // TODO: Implementar validación funcional de código real aquí
+  });`).join("\n\n")}
+});
+`;
+    } else if (fs.existsSync(path.join(projectRoot, "requirements.txt")) || fs.existsSync(path.join(projectRoot, "pyproject.toml"))) {
+      // Python Stack
+      testLanguage = "py";
+      const testsDir = path.join(projectRoot, "tests");
+      if (!fs.existsSync(testsDir)) {
+        fs.mkdirSync(testsDir, { recursive: true });
+      }
+      testFilePath = path.join(testsDir, `test_sdd_${changeName.replace(/-/g, "_")}.py`);
+
+      generatedCode = `"""
+BDD LIVING SPECIFICATION AUTO-GENERATED TEST SUITE
+Generated for change: ${changeName}
+"""
+import unittest
+
+class TestSdd${changeName.replace(/-/g, "").toUpperCase()}(unittest.TestCase):
+${scenarios.map((s, idx) => `    def test_scenario_${idx + 1}(self):
+        """Escenario: ${s.title}"""
+        # BDD Steps:
+${s.steps.map(step => `        # - ${step}`).join("\n")}
+        
+        # TODO: Implementar validación funcional de código real aquí
+        pass`).join("\n\n")}
+
+if __name__ == '__main__':
+    unittest.main()
+`;
+    } else {
+      return `[BDD Tester Blocked] Error: No se pudo determinar el stack del proyecto (falta package.json o requirements.txt).`;
+    }
+
+    fs.writeFileSync(testFilePath, generatedCode, "utf-8");
+
+    let testExecutionOutput = "No ejecutada (runTests = false)";
+    if (args.runTests) {
+      try {
+        if (testLanguage === "ts" || testLanguage === "js") {
+          const pkgContent = fs.readFileSync(path.join(projectRoot, "package.json"), "utf-8");
+          if (pkgContent.includes('"vitest"')) {
+            testExecutionOutput = execSync(`npx vitest run ${testFilePath}`, { encoding: "utf-8" });
+          } else {
+            testExecutionOutput = execSync(`npx jest ${testFilePath}`, { encoding: "utf-8" });
+          }
+        } else if (testLanguage === "py") {
+          testExecutionOutput = execSync(`python3 -m unittest ${testFilePath}`, { encoding: "utf-8" });
+        }
+      } catch (e: any) {
+        testExecutionOutput = `Fallo en ejecución de pruebas: ${e.stdout || e.message || e}`;
+      }
+    }
+
+    return `[BDD Tester Complete] Esqueleto de pruebas BDD autogenerado en: ${path.relative(projectRoot, testFilePath)}. Escenarios detectados: ${scenarios.length}.\n\nSalida de Pruebas:\n${testExecutionOutput}`;
+  }
+})

package/tools/sdd_brain_sync.ts

@@ -0,0 +1,160 @@
+import { tool } from "@opencode-ai/plugin"
+import fs from "fs"
+import path from "path"
+import { BrainEntry, parseEntries, buildFullBrain, readBrainFile, writeBrainFile, nextId, today } from "./brain-utils.js"
+
+const BRAIN_FILE = ".openspec/brain.md"
+const BRAIN_SUBDIR = ".openspec/brain"
+const MAX_ENTRIES = 40
+
+export default tool({
+  description: `Gestiona el cerebro del proyecto (brain.md) con índice indexado, IDs auto-secuenciales y sharding automático.
+  Cualquier agente (incluyendo al Orquestador Zugzbot y todos los subagentes) puede activar esta herramienta en cualquier fase para guardar aprendizajes técnicos valiosos.
+
+  Acciones:
+  - "init": Crea el archivo brain.md si no existe.
+  - "add": Agrega una nueva lección técnica con formato estandarizado.
+  - "list": Lista todas las entradas del cerebro.
+  - "remove": Elimina una entrada por su ID (ej: L001).
+  - "rebuild-index": Reconstruye el índice desde las entradas existentes.
+  - "shard": Fragmenta en archivos por dominio (.openspec/brain/{category}.md).
+
+  USO OBLIGATORIO: Se prohibe la edición directa de brain.md con write/edit. Usar siempre esta herramienta para interactuar con el cerebro.`,
+  args: {
+    action: tool.schema.enum(["init", "add", "list", "remove", "rebuild-index", "shard"])
+      .describe("Acción a ejecutar"),
+    category: tool.schema.string().optional()
+      .describe("Categoría/dominio: frontend, backend, devops, architecture, css, tooling, testing"),
+    tag: tool.schema.string().optional()
+      .describe("Tag corto sin espacios (ej: tailwind-grid-fix, prisma-timezone-workaround)"),
+    problem: tool.schema.string().optional()
+      .describe("Descripción concisa del problema o bug (máx 120 caracteres)"),
+    solution: tool.schema.string().optional()
+      .describe("Descripción concisa de la solución (máx 300 caracteres)"),
+    entryId: tool.schema.string().optional()
+      .describe("ID de entrada a eliminar (ej: L001)")
+  },
+  async execute(args, context) {
+    const projectRoot = context.worktree || context.directory
+    const brainPath = path.join(projectRoot, BRAIN_FILE)
+
+    switch (args.action) {
+      case "init": {
+        if (fs.existsSync(brainPath)) {
+          const { entries } = readBrainFile(brainPath)
+          return `[Brain Sync] ✅ brain.md ya existe (${entries.length} entradas).`
+        }
+        writeBrainFile(brainPath, [])
+        return `[Brain Sync] ✅ brain.md creado en .openspec/brain.md`
+      }
+
+      case "add": {
+        if (!args.category || !args.tag || !args.problem || !args.solution) {
+          return `[Brain Sync] ❌ Error: add requiere category, tag, problem, solution`
+        }
+        if (args.problem.length > 120) {
+          return `[Brain Sync] ❌ Error: problem excede 120 caracteres (tiene ${args.problem.length})`
+        }
+        if (args.solution.length > 300) {
+          return `[Brain Sync] ❌ Error: solution excede 300 caracteres (tiene ${args.solution.length})`
+        }
+
+        const { entries } = readBrainFile(brainPath)
+
+        const dup = entries.find(e => e.tag === args.tag && e.problem === args.problem)
+        if (dup) {
+          return `[Brain Sync] ⚠️ Entrada duplicada: ${dup.id}:${dup.tag}. Se omite inserción.`
+        }
+
+        const newEntry: BrainEntry = {
+          id: nextId(entries),
+          category: args.category,
+          tag: args.tag,
+          problem: args.problem,
+          solution: args.solution,
+          date: today(),
+        }
+        entries.push(newEntry)
+        writeBrainFile(brainPath, entries)
+
+        if (entries.length > MAX_ENTRIES) {
+          return `[Brain Sync] ✅ ${newEntry.id} añadida. ⚠️ Cerebro tiene ${entries.length} entradas. Ejecuta 'shard' para fragmentar.`
+        }
+
+        return `[Brain Sync] ✅ ${newEntry.id} añadida [${args.category}/${args.tag}]. Total: ${entries.length} entradas.`
+      }
+
+      case "list": {
+        const { entries } = readBrainFile(brainPath)
+        if (entries.length === 0) {
+          return `[Brain Sync] 📭 No hay entradas en el cerebro.`
+        }
+        return `[Brain Sync] 📋 ${entries.length} entradas:\n` +
+          entries.map(e =>
+            `  ${e.id} | ${(e.category || "-").padEnd(10)} | ${e.tag.padEnd(22)} | ${e.problem.slice(0, 50)}`
+          ).join("\n")
+      }
+
+      case "remove": {
+        if (!args.entryId) {
+          return `[Brain Sync] ❌ Error: remove requiere entryId`
+        }
+        const { entries } = readBrainFile(brainPath)
+        const idx = entries.findIndex(e => e.id === args.entryId)
+        if (idx === -1) {
+          return `[Brain Sync] ❌ No se encontró entrada ${args.entryId}`
+        }
+        const removed = entries.splice(idx, 1)[0]
+        writeBrainFile(brainPath, entries)
+        return `[Brain Sync] ✅ ${removed.id}:${removed.tag} eliminada. Quedan ${entries.length}.`
+      }
+
+      case "rebuild-index": {
+        const { entries } = readBrainFile(brainPath)
+        writeBrainFile(brainPath, entries)
+        return `[Brain Sync] ✅ Índice reconstruido. ${entries.length} entradas indexadas.`
+      }
+
+      case "shard": {
+        const { entries } = readBrainFile(brainPath)
+        if (entries.length === 0) {
+          return `[Brain Sync] ⚠️ No hay entradas para fragmentar.`
+        }
+
+        const byCat = new Map<string, BrainEntry[]>()
+        for (const e of entries) {
+          const cat = e.category || "general"
+          if (!byCat.has(cat)) byCat.set(cat, [])
+          byCat.get(cat)!.push(e)
+        }
+
+        const brainSubdir = path.join(projectRoot, BRAIN_SUBDIR)
+        fs.mkdirSync(brainSubdir, { recursive: true })
+        for (const [cat, catEntries] of byCat) {
+          writeBrainFile(path.join(brainSubdir, `${cat}.md`), catEntries)
+        }
+
+        const masterLines = [
+          "# 🧠 Cerebro del Proyecto (Fragmentado)",
+          "",
+          "> Fragmentado por dominio para optimizar tokens de contexto.",
+          "",
+          "## Índice de Dominios",
+          "",
+          "| Dominio | Entradas | Archivo |",
+          "| :--- | :--- | :--- |",
+        ]
+        for (const [cat, catEntries] of byCat) {
+          masterLines.push(`| ${cat} | ${catEntries.length} | \`brain/${cat}.md\` |`)
+        }
+        masterLines.push("", "---", "", "Usa `sdd_brain_sync add` con `category` para dirigir al shard correcto.")
+        fs.writeFileSync(brainPath, masterLines.join("\n"), "utf-8")
+
+        return `[Brain Sync] ✅ Fragmentado en ${byCat.size} shards (${entries.length} entradas).`
+      }
+
+      default:
+        return `[Brain Sync] ❌ Acción '${args.action}' no válida.`
+    }
+  }
+})

package/tools/sdd_checkpoint.ts

@@ -0,0 +1,142 @@
+import { tool } from "@opencode-ai/plugin"
+import fs from "fs"
+import path from "path"
+
+interface Checkpoint {
+  id: number
+  timestamp: string
+  phase: number
+  active_subagent: string
+  change_name: string
+  status: string
+  iteration: number
+  lock_snapshot: any
+}
+
+export default tool({
+  description: "Guarda checkpoint del estado actual del ciclo SDD antes de transiciones, o restaura desde un checkpoint anterior. Permite repetir o retroceder fases sin perder contexto.",
+  args: {
+    action: tool.schema.enum(["save", "restore", "list", "clear"]).describe("Accion a realizar: save (guardar checkpoint), restore (restaurar desde checkpoint), list (ver checkpoints guardados), clear (limpiar checkpoints antiguos)"),
+    phase: tool.schema.number().optional().describe("Fase desde la cual guardar checkpoint o a la cual restaurar"),
+    checkpointId: tool.schema.number().optional().describe("ID especifico del checkpoint a restaurar (para action=restore)")
+  },
+  async execute(args, context) {
+    const projectRoot = context.worktree || context.directory
+    const 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."
+    }
+
+    let lockfile: any = {}
+    try {
+      lockfile = JSON.parse(fs.readFileSync(lockfilePath, "utf-8"))
+    } catch (e) {
+      return "[SDD Checkpoint] ERROR: No se pudo leer el lockfile."
+    }
+
+    const checkpointsDir = path.join(projectRoot, ".openspec/checkpoints")
+    if (!fs.existsSync(checkpointsDir)) {
+      fs.mkdirSync(checkpointsDir, { recursive: true })
+    }
+
+    if (args.action === "save") {
+      const checkpoint: Checkpoint = {
+        id: Date.now(),
+        timestamp: new Date().toISOString(),
+        phase: lockfile.active_phase || 0,
+        active_subagent: lockfile.active_subagent || "sdd-planner",
+        change_name: lockfile.change_name || "nuevo-cambio",
+        status: lockfile.status || "idle",
+        iteration: lockfile.iteration || 0,
+        lock_snapshot: { ...lockfile }
+      }
+
+      const historyPath = path.join(checkpointsDir, "checkpoint_history.jsonl")
+      fs.appendFileSync(historyPath, JSON.stringify(checkpoint) + "\n", "utf-8")
+
+      const lockWithCheckpoint = { ...lockfile, last_checkpoint_id: checkpoint.id }
+      fs.writeFileSync(lockfilePath, JSON.stringify(lockWithCheckpoint, null, 2), "utf-8")
+
+      return `[SDD Checkpoint] Guardado checkpoint #${checkpoint.id} para fase ${checkpoint.phase} (${checkpoint.active_subagent}). Timestamp: ${checkpoint.timestamp}`
+    }
+
+    if (args.action === "list") {
+      const historyPath = path.join(checkpointsDir, "checkpoint_history.jsonl")
+      if (!fs.existsSync(historyPath)) {
+        return "[SDD Checkpoint] No hay checkpoints guardados."
+      }
+
+      const lines = fs.readFileSync(historyPath, "utf-8").split("\n").filter(l => l.trim())
+      const checkpoints: Checkpoint[] = lines.map(line => {
+        try { return JSON.parse(line) } catch { return null }
+      }).filter(Boolean)
+
+      if (checkpoints.length === 0) {
+        return "[SDD Checkpoint] No hay checkpoints guardados."
+      }
+
+      const list = checkpoints.slice(-10).reverse().map((cp: Checkpoint) =>
+        `  [${cp.id}] Fase ${cp.phase} (${cp.active_subagent}) - ${cp.change_name} @ ${cp.timestamp}`
+      ).join("\n")
+
+      return `[SDD Checkpoint] Ultimos ${checkpoints.length} checkpoints:\n${list}`
+    }
+
+    if (args.action === "restore") {
+      const historyPath = path.join(checkpointsDir, "checkpoint_history.jsonl")
+      if (!fs.existsSync(historyPath)) {
+        return "[SDD Checkpoint] ERROR: No hay checkpoints para restaurar."
+      }
+
+      const lines = fs.readFileSync(historyPath, "utf-8").split("\n").filter(l => l.trim())
+      const checkpoints: Checkpoint[] = lines.map(line => {
+        try { return JSON.parse(line) } catch { return null }
+      }).filter(Boolean)
+
+      let targetCheckpoint: Checkpoint | null = null
+
+      if (args.checkpointId !== undefined) {
+        targetCheckpoint = checkpoints.find(cp => cp.id === args.checkpointId) || null
+      } else if (args.phase !== undefined) {
+        const candidates = checkpoints.filter(cp => cp.phase === args.phase)
+        targetCheckpoint = candidates[candidates.length - 1] || null
+      } else {
+        targetCheckpoint = checkpoints[checkpoints.length - 1] || null
+      }
+
+      if (!targetCheckpoint) {
+        return `[SDD Checkpoint] ERROR: No se encontro checkpoint para los parametros dados.`
+      }
+
+      const restoredLock = {
+        ...targetCheckpoint.lock_snapshot,
+        active_phase: args.phase ?? targetCheckpoint.phase,
+        status: "restored_from_checkpoint",
+        last_restored_from: targetCheckpoint.id
+      }
+
+      fs.writeFileSync(lockfilePath, JSON.stringify(restoredLock, null, 2), "utf-8")
+
+      return `[SDD Checkpoint] Restaurado checkpoint #${targetCheckpoint.id} (Fase ${targetCheckpoint.phase}). Estado del lockfile restaurado.`
+    }
+
+    if (args.action === "clear") {
+      const historyPath = path.join(checkpointsDir, "checkpoint_history.jsonl")
+      if (fs.existsSync(historyPath)) {
+        const lines = fs.readFileSync(historyPath, "utf-8").split("\n").filter(l => l.trim())
+        const checkpoints: Checkpoint[] = lines.map(line => {
+          try { return JSON.parse(line) } catch { return null }
+        }).filter(Boolean)
+
+        const lastPhase = checkpoints.length > 0 ? checkpoints[checkpoints.length - 1].phase : 0
+        const recentCheckpoints = checkpoints.filter(cp => cp.phase >= lastPhase - 1)
+
+        fs.writeFileSync(historyPath, recentCheckpoints.map(cp => JSON.stringify(cp)).join("\n") + "\n", "utf-8")
+      }
+      return "[SDD Checkpoint] Checkpoints antiguos limpiados. Se conservaron los 2 mas recientes por fase."
+    }
+
+    return "[SDD Checkpoint] Accion no reconocida. Use: save, restore, list, o clear."
+  }
+})