elsabro 2.3.0 → 3.8.0

package/references/checkpointing.md

@@ -0,0 +1,595 @@
+---
+name: checkpointing
+description: Sistema de checkpointing persistente inspirado en LangGraph
+version: 1.0.0
+---
+
+# ELSABRO Persistent Checkpointing System
+
+## Vision General
+
+El sistema de checkpointing permite guardar y restaurar el estado completo de ejecución en cualquier momento, habilitando:
+- **Recuperación de sesiones** después de interrupciones
+- **Time-travel debugging** para analizar decisiones pasadas
+- **Rollback** a cualquier punto anterior
+- **Resume from interrupt** después de pausas manuales
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│                    CHECKPOINT LIFECYCLE                               │
+├──────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│    START                                                             │
+│      │                                                               │
+│      ▼                                                               │
+│  ┌─────────┐    auto-save     ┌─────────┐    complete    ┌────────┐ │
+│  │  INIT   │ ──────────────►  │ ACTIVE  │ ────────────►  │  DONE  │ │
+│  └─────────┘                  └─────────┘                └────────┘ │
+│                                    │                                 │
+│                              interrupt/error                         │
+│                                    │                                 │
+│                                    ▼                                 │
+│                              ┌──────────┐                           │
+│                              │ PAUSED   │                           │
+│                              └──────────┘                           │
+│                                    │                                 │
+│                               resume                                 │
+│                                    │                                 │
+│                                    ▼                                 │
+│                              ┌──────────┐                           │
+│                              │ ACTIVE   │ (restored)                │
+│                              └──────────┘                           │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Estructura del Checkpoint
+
+### checkpoint-state.json
+
+```json
+{
+  "version": "3.0.0",
+  "checkpointId": "chk_2024012015300001",
+  "sessionId": "ses_abc123",
+  "createdAt": "2024-01-20T15:30:00.000Z",
+  "updatedAt": "2024-01-20T15:45:32.000Z",
+
+  "execution": {
+    "status": "ACTIVE",
+    "currentPhase": "implementation",
+    "currentWave": 2,
+    "totalWaves": 4,
+    "progress": 0.45
+  },
+
+  "graph": {
+    "nodes": [
+      {"id": "n1", "type": "agent", "agent": "elsabro-analyst", "status": "COMPLETE"},
+      {"id": "n2", "type": "agent", "agent": "elsabro-planner", "status": "COMPLETE"},
+      {"id": "n3", "type": "agent", "agent": "elsabro-executor", "status": "ACTIVE"},
+      {"id": "n4", "type": "agent", "agent": "elsabro-qa", "status": "PENDING"}
+    ],
+    "edges": [
+      {"from": "n1", "to": "n2"},
+      {"from": "n2", "to": "n3"},
+      {"from": "n3", "to": "n4"}
+    ],
+    "currentNode": "n3"
+  },
+
+  "state": {
+    "variables": {
+      "projectName": "my-app",
+      "targetFramework": "nextjs",
+      "currentFile": "src/components/Auth.tsx"
+    },
+    "memory": {
+      "shortTerm": [],
+      "decisions": [],
+      "artifacts": []
+    }
+  },
+
+  "history": [
+    {
+      "checkpointId": "chk_2024012015300000",
+      "at": "2024-01-20T15:30:00.000Z",
+      "event": "INIT",
+      "hash": "abc123"
+    },
+    {
+      "checkpointId": "chk_2024012015300001",
+      "at": "2024-01-20T15:45:32.000Z",
+      "event": "PHASE_COMPLETE",
+      "phase": "planning",
+      "hash": "def456"
+    }
+  ],
+
+  "interrupts": {
+    "pending": [],
+    "history": []
+  }
+}
+```
+
+---
+
+## Tipos de Checkpoints
+
+### 1. Auto Checkpoints (Automáticos)
+
+Se crean automáticamente en momentos clave:
+
+| Trigger | Descripción |
+|---------|-------------|
+| `PHASE_START` | Al iniciar una nueva fase |
+| `PHASE_COMPLETE` | Al completar una fase |
+| `WAVE_COMPLETE` | Al completar una wave paralela |
+| `AGENT_COMPLETE` | Al completar cada agente (opcional) |
+| `INTERVAL` | Cada N minutos (configurable) |
+| `FILE_MODIFY` | Después de modificar archivos importantes |
+
+### 2. Manual Checkpoints
+
+Creados explícitamente por el usuario o sistema:
+
+```
+/elsabro:checkpoint save "antes de refactor"
+/elsabro:checkpoint list
+/elsabro:checkpoint restore chk_abc123
+```
+
+### 3. Interrupt Checkpoints
+
+Creados automáticamente cuando hay interrupciones:
+
+- Error no recuperable
+- Timeout de sesión
+- Usuario cancela
+- Sistema requiere input
+
+---
+
+## API de Checkpointing
+
+### CheckpointManager
+
+```javascript
+/**
+ * CheckpointManager
+ * Gestiona checkpoints persistentes para recuperación y time-travel
+ */
+class CheckpointManager {
+  constructor(storageDir = '.planning/checkpoints') {
+    this.storageDir = storageDir;
+    this.currentCheckpoint = null;
+    this.config = {
+      autoSaveInterval: 5 * 60 * 1000,  // 5 minutos
+      maxCheckpoints: 50,
+      compressionEnabled: true,
+      triggers: ['PHASE_START', 'PHASE_COMPLETE', 'WAVE_COMPLETE', 'INTERRUPT']
+    };
+  }
+
+  /**
+   * Inicializa o carga checkpoint existente
+   */
+  async initialize(sessionId) {
+    const existing = await this.findLatestCheckpoint(sessionId);
+
+    if (existing) {
+      return this.loadCheckpoint(existing.checkpointId);
+    }
+
+    return this.createCheckpoint({
+      sessionId,
+      execution: { status: 'INIT', currentPhase: null, currentWave: 0 },
+      graph: { nodes: [], edges: [], currentNode: null },
+      state: { variables: {}, memory: { shortTerm: [], decisions: [], artifacts: [] } },
+      history: [],
+      interrupts: { pending: [], history: [] }
+    });
+  }
+
+  /**
+   * Crea un nuevo checkpoint
+   */
+  async createCheckpoint(data, event = 'MANUAL') {
+    const checkpointId = this.generateCheckpointId();
+    const hash = this.computeHash(data);
+
+    const checkpoint = {
+      version: '3.0.0',
+      checkpointId,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      ...data,
+      history: [
+        ...(data.history || []),
+        {
+          checkpointId,
+          at: new Date().toISOString(),
+          event,
+          hash
+        }
+      ]
+    };
+
+    await this.persistCheckpoint(checkpoint);
+    this.currentCheckpoint = checkpoint;
+
+    return checkpoint;
+  }
+
+  /**
+   * Actualiza el checkpoint actual
+   */
+  async updateCheckpoint(updates, event = 'UPDATE') {
+    if (!this.currentCheckpoint) {
+      throw new Error('No active checkpoint');
+    }
+
+    const updated = {
+      ...this.currentCheckpoint,
+      ...updates,
+      updatedAt: new Date().toISOString()
+    };
+
+    // Agregar al historial si es evento significativo
+    if (this.config.triggers.includes(event)) {
+      updated.history.push({
+        checkpointId: this.currentCheckpoint.checkpointId,
+        at: new Date().toISOString(),
+        event,
+        hash: this.computeHash(updated)
+      });
+    }
+
+    await this.persistCheckpoint(updated);
+    this.currentCheckpoint = updated;
+
+    return updated;
+  }
+
+  /**
+   * Guarda estado de interrupción para resume
+   */
+  async saveInterrupt(reason, context = {}) {
+    const interrupt = {
+      id: `int_${Date.now()}`,
+      reason,
+      context,
+      savedAt: new Date().toISOString(),
+      resumable: true
+    };
+
+    await this.updateCheckpoint({
+      execution: {
+        ...this.currentCheckpoint.execution,
+        status: 'PAUSED'
+      },
+      interrupts: {
+        pending: [...this.currentCheckpoint.interrupts.pending, interrupt],
+        history: this.currentCheckpoint.interrupts.history
+      }
+    }, 'INTERRUPT');
+
+    return interrupt;
+  }
+
+  /**
+   * Resume desde interrupción
+   */
+  async resumeFromInterrupt(interruptId) {
+    const interrupt = this.currentCheckpoint.interrupts.pending.find(
+      i => i.id === interruptId
+    );
+
+    if (!interrupt) {
+      throw new Error(`Interrupt ${interruptId} not found`);
+    }
+
+    await this.updateCheckpoint({
+      execution: {
+        ...this.currentCheckpoint.execution,
+        status: 'ACTIVE'
+      },
+      interrupts: {
+        pending: this.currentCheckpoint.interrupts.pending.filter(
+          i => i.id !== interruptId
+        ),
+        history: [
+          ...this.currentCheckpoint.interrupts.history,
+          { ...interrupt, resumedAt: new Date().toISOString() }
+        ]
+      }
+    }, 'RESUME');
+
+    return interrupt.context;
+  }
+
+  /**
+   * Rollback a un checkpoint anterior
+   */
+  async rollbackTo(checkpointId) {
+    const checkpoint = await this.loadCheckpoint(checkpointId);
+
+    if (!checkpoint) {
+      throw new Error(`Checkpoint ${checkpointId} not found`);
+    }
+
+    // Marcar el checkpoint actual como rolled back
+    if (this.currentCheckpoint) {
+      await this.updateCheckpoint({
+        execution: {
+          ...this.currentCheckpoint.execution,
+          status: 'ROLLED_BACK'
+        }
+      }, 'ROLLBACK');
+    }
+
+    // Crear nuevo checkpoint basado en el histórico
+    return this.createCheckpoint({
+      ...checkpoint,
+      history: [
+        ...checkpoint.history,
+        {
+          checkpointId: checkpoint.checkpointId,
+          at: new Date().toISOString(),
+          event: 'ROLLBACK_TARGET',
+          hash: this.computeHash(checkpoint)
+        }
+      ]
+    }, 'ROLLBACK');
+  }
+
+  /**
+   * Lista todos los checkpoints disponibles
+   */
+  async listCheckpoints(sessionId, options = {}) {
+    const { limit = 20, offset = 0 } = options;
+    const files = await this.listCheckpointFiles(sessionId);
+
+    return files
+      .sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt))
+      .slice(offset, offset + limit)
+      .map(f => ({
+        checkpointId: f.checkpointId,
+        createdAt: f.createdAt,
+        event: f.lastEvent,
+        status: f.status
+      }));
+  }
+
+  /**
+   * Time-travel: obtener estado en un punto específico
+   */
+  async getStateAt(checkpointId) {
+    const checkpoint = await this.loadCheckpoint(checkpointId);
+
+    return {
+      checkpointId,
+      timestamp: checkpoint.createdAt,
+      execution: checkpoint.execution,
+      state: checkpoint.state,
+      graph: checkpoint.graph
+    };
+  }
+
+  /**
+   * Diff entre dos checkpoints
+   */
+  async diffCheckpoints(checkpointId1, checkpointId2) {
+    const cp1 = await this.loadCheckpoint(checkpointId1);
+    const cp2 = await this.loadCheckpoint(checkpointId2);
+
+    return {
+      execution: this.diffObjects(cp1.execution, cp2.execution),
+      state: this.diffObjects(cp1.state, cp2.state),
+      graph: this.diffObjects(cp1.graph, cp2.graph),
+      timeSpan: {
+        from: cp1.createdAt,
+        to: cp2.createdAt
+      }
+    };
+  }
+
+  // ==================== Helpers ====================
+
+  generateCheckpointId() {
+    const timestamp = new Date().toISOString().replace(/[-:T.Z]/g, '');
+    const random = Math.random().toString(36).substring(2, 6);
+    return `chk_${timestamp}_${random}`;
+  }
+
+  computeHash(data) {
+    // Simplified hash - in production use crypto
+    return Buffer.from(JSON.stringify(data)).toString('base64').substring(0, 12);
+  }
+
+  async persistCheckpoint(checkpoint) {
+    const filePath = `${this.storageDir}/${checkpoint.checkpointId}.json`;
+    // Write to file system
+    return checkpoint;
+  }
+
+  async loadCheckpoint(checkpointId) {
+    const filePath = `${this.storageDir}/${checkpointId}.json`;
+    // Read from file system
+    return null;
+  }
+
+  async findLatestCheckpoint(sessionId) {
+    // Find most recent checkpoint for session
+    return null;
+  }
+
+  async listCheckpointFiles(sessionId) {
+    // List all checkpoint files for session
+    return [];
+  }
+
+  diffObjects(obj1, obj2) {
+    // Deep diff two objects
+    return { added: [], removed: [], changed: [] };
+  }
+}
+```
+
+---
+
+## Integración con ELSABRO
+
+### Auto-Checkpoint en Comandos
+
+```javascript
+// En cada comando principal de ELSABRO
+async function executeCommand(command, args) {
+  const checkpointManager = new CheckpointManager();
+
+  // Cargar o crear checkpoint
+  await checkpointManager.initialize(currentSessionId);
+
+  try {
+    // Checkpoint antes de empezar
+    await checkpointManager.updateCheckpoint({
+      execution: { status: 'ACTIVE', currentPhase: command }
+    }, 'PHASE_START');
+
+    // Ejecutar comando
+    const result = await runCommand(command, args);
+
+    // Checkpoint al completar
+    await checkpointManager.updateCheckpoint({
+      execution: { status: 'COMPLETE', currentPhase: command }
+    }, 'PHASE_COMPLETE');
+
+    return result;
+
+  } catch (error) {
+    // Checkpoint de error para recovery
+    await checkpointManager.saveInterrupt('ERROR', {
+      command,
+      args,
+      error: error.message,
+      stack: error.stack
+    });
+
+    throw error;
+  }
+}
+```
+
+### Resume Automático
+
+```javascript
+// Al iniciar /elsabro:resume-work
+async function resumeWork() {
+  const checkpointManager = new CheckpointManager();
+  const checkpoint = await checkpointManager.initialize(currentSessionId);
+
+  if (checkpoint.interrupts.pending.length > 0) {
+    const lastInterrupt = checkpoint.interrupts.pending[0];
+
+    console.log(`
+╔════════════════════════════════════════════════════════╗
+║  SESIÓN INTERRUMPIDA DETECTADA                         ║
+╠════════════════════════════════════════════════════════╣
+║                                                        ║
+║  Última actividad: ${checkpoint.updatedAt}             ║
+║  Fase: ${checkpoint.execution.currentPhase}            ║
+║  Progreso: ${Math.round(checkpoint.execution.progress * 100)}%              ║
+║                                                        ║
+║  Razón de interrupción:                                ║
+║  > ${lastInterrupt.reason}                             ║
+║                                                        ║
+╠════════════════════════════════════════════════════════╣
+║  [r] Resumir desde donde quedó                         ║
+║  [s] Ver estado guardado                               ║
+║  [n] Empezar de nuevo                                  ║
+╚════════════════════════════════════════════════════════╝
+    `);
+
+    // Si usuario elige resumir
+    const context = await checkpointManager.resumeFromInterrupt(lastInterrupt.id);
+    return continueExecution(context);
+  }
+
+  return startFresh();
+}
+```
+
+---
+
+## Comandos de Usuario
+
+### /elsabro:checkpoint
+
+```
+/elsabro:checkpoint save [nombre]     - Guardar checkpoint manual
+/elsabro:checkpoint list              - Listar checkpoints
+/elsabro:checkpoint restore <id>      - Restaurar checkpoint
+/elsabro:checkpoint diff <id1> <id2>  - Comparar checkpoints
+/elsabro:checkpoint delete <id>       - Eliminar checkpoint
+```
+
+### Ejemplos de Uso
+
+```bash
+# Guardar antes de cambio riesgoso
+/elsabro:checkpoint save "antes de refactor auth"
+
+# Ver historial
+/elsabro:checkpoint list
+# Output:
+# ID                  | Fecha              | Evento         | Estado
+# chk_20240120_a1b2   | 2024-01-20 15:45   | PHASE_COMPLETE | planning
+# chk_20240120_c3d4   | 2024-01-20 15:30   | PHASE_START    | research
+# chk_20240120_e5f6   | 2024-01-20 15:00   | INIT           | init
+
+# Rollback si algo sale mal
+/elsabro:checkpoint restore chk_20240120_c3d4
+```
+
+---
+
+## Configuración
+
+### .planning/checkpoint-config.json
+
+```json
+{
+  "checkpointing": {
+    "enabled": true,
+    "autoSave": {
+      "enabled": true,
+      "intervalMinutes": 5,
+      "triggers": ["PHASE_START", "PHASE_COMPLETE", "WAVE_COMPLETE", "FILE_MODIFY"]
+    },
+    "storage": {
+      "directory": ".planning/checkpoints",
+      "maxCheckpoints": 50,
+      "retentionDays": 30,
+      "compression": true
+    },
+    "recovery": {
+      "autoPromptOnStart": true,
+      "keepInterruptedSessions": 7
+    }
+  }
+}
+```
+
+---
+
+## Notas de Implementación
+
+1. **Serialización**: Todo el estado debe ser JSON-serializable
+2. **Idempotencia**: Restaurar un checkpoint debe ser idempotente
+3. **Atomicidad**: Writes deben ser atómicos (write-rename pattern)
+4. **Limpieza**: Auto-cleanup de checkpoints antiguos
+5. **Performance**: Lazy loading de checkpoints grandes