elsabro 2.1.0 → 2.3.0

package/references/error-handling-instructions.md

@@ -19,7 +19,7 @@ Cuando encuentres un error, clasifícalo usando esta escala:
 ```
 
 **Ejemplos:**
-- SESSION.md corrupto o faltante
+- `.elsabro/state.json` corrupto o faltante
 - Archivos de configuración críticos inválidos
 - Dependencias con versiones incompatibles
 - Estado de git inconsistente (detached HEAD, conflictos)
@@ -102,18 +102,18 @@ Usa este formato visual para errores:
 ### Error CRITICAL
 ```
 ╔══════════════════════════════════════════════════╗
-║  🔴 ERROR: SESSION_MISSING                       ║
+║  🔴 ERROR: STATE_MISSING                         ║
 ║  Severity: CRITICAL                              ║
 ╠══════════════════════════════════════════════════╣
 ║                                                  ║
-║  No se encontró el archivo de sesión             ║
+║  No se encontró el archivo de estado             ║
 ║                                                  ║
-║  El archivo .planning/SESSION.md no existe       ║
+║  El archivo .elsabro/state.json no existe        ║
 ║  o está corrupto.                                ║
 ║                                                  ║
 ╠══════════════════════════════════════════════════╣
 ║  ACCIÓN REQUERIDA:                               ║
-║  → /elsabro:start para iniciar nueva sesión      ║
+║  → /elsabro:start para inicializar proyecto      ║
 ╚══════════════════════════════════════════════════╝
 ```
 
@@ -276,17 +276,31 @@ Attempt 3: Esperar 2s, reintentar
 
 ## Actualización de Estado
 
-Después de cada operación significativa, actualiza `.planning/SESSION-STATE.json`:
+**IMPORTANTE**: El archivo de estado unificado es `.elsabro/state.json` (ver `/references/state-sync.md`).
+
+Después de cada operación significativa, actualiza `.elsabro/state.json`:
 
 ```json
 {
-  "lastUpdated": "2024-01-20T15:30:00Z",
+  "version": "1.0.0",
+  "updated_at": "2024-01-20T15:30:00Z",
+  "current_flow": {
+    "command": "execute",
+    "phase": "executing_wave_2",
+    "started_at": "2024-01-20T15:00:00Z"
+  },
   "context": {
-    "milestone": "M001",
-    "phase": "P3",
-    "progress": 65,
-    "currentTask": "Implement user profile"
+    "project_type": "brownfield",
+    "tech_stack": ["nextjs", "prisma"],
+    "current_feature": "user-profile"
   },
+  "history": [
+    {
+      "command": "plan",
+      "completed_at": "2024-01-20T14:50:00Z",
+      "result": "created"
+    }
+  ],
   "errors": {
     "count": 1,
     "lastError": {
@@ -307,6 +321,6 @@ Antes de reportar "completado":
 
 - [ ] ¿Hubo errores? → Clasificados y reportados
 - [ ] ¿Hubo warnings? → Listados al final
-- [ ] ¿Estado actualizado? → SESSION-STATE.json actualizado
+- [ ] ¿Estado actualizado? → .elsabro/state.json actualizado (ver /references/state-sync.md)
 - [ ] ¿Retry necesario? → Intentado con backoff
 - [ ] ¿Ejecución paralela? → Política aplicada, resultados agregados

package/references/parallel-worktrees.md

@@ -0,0 +1,293 @@
+---
+name: parallel-worktrees
+description: Guia para trabajo paralelo con git worktrees en ELSABRO
+version: 1.0.0
+---
+
+# Trabajo Paralelo con Git Worktrees
+
+## Concepto
+
+Cuando ELSABRO ejecuta multiples agentes en paralelo, cada uno puede trabajar
+en su propio worktree de git para evitar conflictos de archivos.
+
+Un **worktree** es una copia de trabajo adicional del repositorio que comparte
+el mismo directorio `.git` pero tiene su propio directorio de trabajo y branch.
+
+## Beneficios
+
+- **Aislamiento**: Cada agente trabaja en archivos separados
+- **Sin conflictos**: No hay race conditions en archivos
+- **Merge controlado**: Los cambios se integran explicitamente
+- **Rollback facil**: Cada branch puede descartarse independientemente
+
+## Flujo Automatico
+
+```
+1. /elsabro:execute detecta wave con multiples planes
+   |
+2. Crea worktrees automaticos:
+   - elsabro-worktrees/analyst-wt/
+   - elsabro-worktrees/executor-wt/
+   - elsabro-worktrees/verifier-wt/
+   |
+3. Cada agente trabaja en su worktree aislado
+   |
+4. Al completar, merge automatico a branch principal
+   |
+5. Cleanup de worktrees temporales
+```
+
+## Estructura de Directorios
+
+```
+proyecto/                      # Repo principal
+  .git/                        # Git compartido
+  src/
+  ...
+
+elsabro-worktrees/             # Directorio de worktrees (hermano del repo)
+  analyst-wt/                  # Worktree del Analyst
+    src/
+    ...
+  executor-wt/                 # Worktree del Executor
+    src/
+    ...
+  verifier-wt/                 # Worktree del Verifier
+    src/
+    ...
+```
+
+## Comandos del Script
+
+### Crear Worktrees
+
+```bash
+# Crear worktrees para agentes especificos
+./scripts/setup-parallel-worktrees.sh create analyst executor
+
+# Crear worktrees para una wave completa
+./scripts/setup-parallel-worktrees.sh create analyst executor verifier
+```
+
+### Merge Trabajo
+
+```bash
+# Merge trabajo de agentes al branch actual
+./scripts/setup-parallel-worktrees.sh merge analyst executor
+
+# El merge usa --no-edit con mensaje automatico
+# Si hay conflictos, se pausa para resolucion manual
+```
+
+### Completar Wave
+
+```bash
+# Merge Y cleanup de una wave completa
+./scripts/setup-parallel-worktrees.sh complete analyst executor verifier
+
+# Equivalente a:
+#   merge analyst executor verifier
+#   cleanup analyst executor verifier
+```
+
+### Limpiar
+
+```bash
+# Limpiar worktrees especificos
+./scripts/setup-parallel-worktrees.sh cleanup analyst
+
+# Limpiar TODOS los worktrees de ELSABRO
+./scripts/setup-parallel-worktrees.sh cleanup
+```
+
+### Ver Estado
+
+```bash
+# Mostrar status de worktrees y branches
+./scripts/setup-parallel-worktrees.sh status
+
+# Listar worktrees activos (git nativo)
+./scripts/setup-parallel-worktrees.sh list
+```
+
+## Integracion con Orquestador
+
+El `elsabro-orchestrator` usa worktrees automaticamente cuando:
+
+1. **Multiples agentes en wave**: Hay mas de 1 agente en una wave
+2. **Archivos conflictivos**: Los agentes modifican archivos potencialmente compartidos
+3. **Profile careful**: Siempre aislado cuando profile es "careful"
+
+### Configuracion en SESSION-STATE.json
+
+```json
+{
+  "parallel": {
+    "useWorktrees": true,
+    "activeWorktrees": [
+      {
+        "agent": "analyst",
+        "path": "../elsabro-worktrees/analyst-wt",
+        "branch": "elsabro/analyst"
+      },
+      {
+        "agent": "executor",
+        "path": "../elsabro-worktrees/executor-wt",
+        "branch": "elsabro/executor"
+      }
+    ]
+  }
+}
+```
+
+## Resolucion de Conflictos
+
+Si hay conflictos en el merge:
+
+### Flujo Automatico
+
+1. ELSABRO pausa la ejecucion
+2. Muestra los conflictos al usuario
+3. Presenta opciones interactivas
+
+### Opciones del Usuario
+
+```
+Conflictos detectados en merge de 'executor':
+
+Archivos en conflicto:
+  - src/api/user.ts
+  - src/utils/validation.ts
+
+Opciones:
+  [r] Resolver manualmente (abre editor)
+  [k] Keep mine (descartar cambios del agente)
+  [t] Take theirs (aceptar cambios del agente)
+  [a] Abort (cancelar merge, mantener worktree)
+```
+
+### Resolucion Manual
+
+```bash
+# Navegar al repo principal
+cd proyecto
+
+# Ver conflictos
+git status
+
+# Editar archivos conflictivos
+# (buscar marcadores <<<<<<<, =======, >>>>>>>)
+
+# Marcar como resueltos
+git add src/api/user.ts
+
+# Completar merge
+git commit
+```
+
+## Limites y Requisitos
+
+### Requisitos
+
+- **Git >= 2.15**: Soporte completo de worktrees
+- **Espacio en disco**: Cada worktree es una copia de trabajo completa
+- **Permisos**: Escritura en directorio padre del repo
+
+### Limites
+
+| Limite | Valor | Razon |
+|--------|-------|-------|
+| Worktrees simultaneos | 5 | Performance y recursos |
+| Ubicacion | `../elsabro-worktrees/` | Relativo al repo |
+| Branches | `elsabro/*` | Namespace aislado |
+
+### Verificar Requisitos
+
+```bash
+# Version de git
+git --version
+# Debe ser >= 2.15
+
+# Espacio disponible
+df -h .
+
+# Permisos
+ls -la ..
+```
+
+## Troubleshooting
+
+### Worktree Huerfano
+
+```bash
+# Si un worktree queda en estado inconsistente
+git worktree prune
+
+# Forzar cleanup
+./scripts/setup-parallel-worktrees.sh cleanup
+```
+
+### Branch No Existe
+
+```bash
+# Error: Branch elsabro/analyst no existe
+# Solucion: Crear worktree de nuevo
+./scripts/setup-parallel-worktrees.sh create analyst
+```
+
+### Merge Fallido
+
+```bash
+# Cancelar merge en progreso
+git merge --abort
+
+# Limpiar y reintentar
+./scripts/setup-parallel-worktrees.sh cleanup analyst
+./scripts/setup-parallel-worktrees.sh create analyst
+# Re-ejecutar trabajo del agente
+```
+
+### Directorio Base No Existe
+
+```bash
+# El script crea automaticamente el directorio
+# Si hay problemas de permisos:
+mkdir -p ../elsabro-worktrees
+chmod 755 ../elsabro-worktrees
+```
+
+## Ejemplo Completo
+
+```bash
+# 1. Iniciar wave paralela
+./scripts/setup-parallel-worktrees.sh create analyst executor verifier
+
+# 2. Ver estado
+./scripts/setup-parallel-worktrees.sh status
+
+# Worktrees activos:
+# /path/to/project                    abc1234 [main]
+# /path/to/elsabro-worktrees/analyst-wt  abc1234 [elsabro/analyst]
+# /path/to/elsabro-worktrees/executor-wt abc1234 [elsabro/executor]
+# /path/to/elsabro-worktrees/verifier-wt abc1234 [elsabro/verifier]
+
+# 3. Agentes trabajan en sus worktrees...
+
+# 4. Completar wave (merge + cleanup)
+./scripts/setup-parallel-worktrees.sh complete analyst executor verifier
+
+# 5. Verificar
+git log --oneline -5
+# abc1234 Merge: ELSABRO verifier parallel work
+# def5678 Merge: ELSABRO executor parallel work
+# ghi9012 Merge: ELSABRO analyst parallel work
+```
+
+## Mejores Practicas
+
+1. **Siempre usar `complete`**: Combina merge y cleanup en un paso
+2. **Verificar antes de merge**: Revisar cambios con `git diff elsabro/agent`
+3. **Cleanup regular**: No dejar worktrees huerfanos
+4. **Commits atomicos**: Cada agente debe hacer commits completos
+5. **Mensajes descriptivos**: Los commits en worktrees deben ser claros