npm - sinapse-ai - Versions diffs - 5.0.8 → 6.0.1 - Mend

sinapse-ai 5.0.8 → 6.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (660) hide show

package/docs/es/guides/build-recovery-guide.md DELETED Viewed

@@ -1,270 +0,0 @@
-<!--
-  Traduccion: ES
-  Original: /docs/guides/build-recovery-guide.md
-  Ultima sincronizacion: 2026-01-29
--->
-# Guia de Recuperacion de Build
-> **Story:** 8.4 - Build Recovery & Resume
-> **Epic:** Epic 8 - Autonomous Build Engine
----
-## Vision General
-El sistema de Recuperacion de Build permite que los builds autonomos se reanuden desde checkpoints despues de fallos o interrupciones. En lugar de comenzar de nuevo, los builds continuan desde el ultimo punto exitoso.
----
-## Caracteristicas Clave
-| Caracteristica               | Descripcion                                       |
-| ---------------------------- | ------------------------------------------------- |
-| **Checkpoints**              | Auto-guardados despues de cada subtask completada |
-| **Resume**                   | Continuar desde el ultimo checkpoint              |
-| **Monitoreo de Estado**      | Progreso del build en tiempo real                 |
-| **Deteccion de Abandonados** | Alertas para builds inactivos (>1 hora)           |
-| **Notificaciones de Fallo**  | Alertas cuando esta atascado o max iteraciones    |
-| **Registro de Intentos**     | Historial completo para debugging                 |
----
-## Comandos
-### Verificar Estado del Build
-```bash
-# Build individual
-*build-status story-8.4
-# Todos los builds activos
-*build-status --all
-```
-### Reanudar Build Fallido
-```bash
-*build-resume story-8.4
-```
-### Ver Registro de Intentos
-```bash
-*build-log story-8.4
-# Filtrar por subtask
-*build-log story-8.4 --subtask 2.1
-# Limitar salida
-*build-log story-8.4 --limit 20
-```
-### Limpiar Builds Abandonados
-```bash
-*build-cleanup story-8.4
-# Forzar limpieza (incluso builds activos)
-*build-cleanup story-8.4 --force
-```
----
-## Esquema de Estado del Build
-El estado del build se almacena en `plan/build-state.json`:
-```json
-{
-  "storyId": "story-8.4",
-  "status": "in_progress",
-  "startedAt": "2026-01-29T10:00:00Z",
-  "lastCheckpoint": "2026-01-29T11:30:00Z",
-  "currentPhase": "phase-2",
-  "currentSubtask": "2.3",
-  "completedSubtasks": ["1.1", "1.2", "2.1", "2.2"],
-  "checkpoints": [...],
-  "metrics": {
-    "totalSubtasks": 10,
-    "completedSubtasks": 4,
-    "totalAttempts": 6,
-    "totalFailures": 2
-  }
-}
-```
----
-## Valores de Estado
-| Estado        | Descripcion                    |
-| ------------- | ------------------------------ |
-| `pending`     | Build creado pero no iniciado  |
-| `in_progress` | Build actualmente ejecutandose |
-| `paused`      | Build pausado manualmente      |
-| `abandoned`   | Sin actividad por >1 hora      |
-| `failed`      | Build fallo (puede reanudarse) |
-| `completed`   | Build finalizado exitosamente  |
----
-## Sistema de Checkpoints
-Los checkpoints se guardan automaticamente despues de cada subtask completada:
-```
-plan/
-├── build-state.json        # Archivo de estado principal
-├── build-attempts.log      # Registro de intentos
-└── checkpoints/            # Snapshots de checkpoints
-    ├── cp-lxyz123-abc.json
-    ├── cp-lxyz124-def.json
-    └── ...
-```
-Cada checkpoint contiene:
-- Timestamp
-- ID de Subtask
-- Commit de Git (si esta disponible)
-- Archivos modificados
-- Duracion y conteo de intentos
----
-## Integracion con Epic 5
-La Recuperacion de Build se integra con el Sistema de Recuperacion (Epic 5):
-| Componente            | Uso                           |
-| --------------------- | ----------------------------- |
-| `stuck-detector.js`   | Detecta fallos circulares     |
-| `recovery-tracker.js` | Rastrea historial de intentos |
-Cuando los builds quedan atascados (3+ fallos consecutivos), el sistema:
-1. Genera sugerencias basadas en patrones de error
-2. Crea notificacion para revision humana
-3. Marca subtask como "stuck"
----
-## Deteccion de Build Abandonado
-Los builds se marcan como abandonados si:
-- El estado es `in_progress`
-- Sin checkpoint por >1 hora (configurable)
-Para detectar y manejar:
-```bash
-# Verificar si esta abandonado
-*build-status story-8.4  # Muestra advertencia si esta abandonado
-# Limpiar
-*build-cleanup story-8.4
-```
----
-## Uso Programatico
-```javascript
-const { BuildStateManager, BuildStatus } = require('.sinapse-ai/core/execution/build-state-manager');
-// Crear manager
-const manager = new BuildStateManager('story-8.4', {
-  planDir: './plan',
-});
-// Crear o cargar estado
-const state = manager.loadOrCreateState({ totalSubtasks: 10 });
-// Iniciar subtask
-manager.startSubtask('1.1', { phase: 'phase-1' });
-// Completar subtask (auto-checkpoint)
-manager.completeSubtask('1.1', {
-  duration: 5000,
-  filesModified: ['src/file.js'],
-});
-// Registrar fallo
-const result = manager.recordFailure('1.2', {
-  error: 'TypeScript error',
-  attempt: 1,
-});
-// Verificar si esta atascado
-if (result.isStuck) {
-  console.log('Sugerencias:', result.suggestions);
-}
-// Reanudar build
-const context = manager.resumeBuild();
-// Obtener estado
-const status = manager.getStatus();
-console.log(`Progreso: ${status.progress.percentage}%`);
-```
----
-## Configuracion
-La configuracion por defecto puede ser sobrescrita:
-```javascript
-const manager = new BuildStateManager('story-8.4', {
-  config: {
-    maxIterations: 10, // Max intentos por subtask
-    globalTimeout: 1800000, // 30 minutos
-    abandonedThreshold: 3600000, // 1 hora
-    autoCheckpoint: true, // Auto-guardar checkpoints
-  },
-});
-```
----
-## Solucion de Problemas
-### "No build state found"
-El build no ha iniciado aun. Ejecutar `*build story-id` para iniciar.
-### "Build already completed"
-No se pueden reanudar builds completados. Iniciar un nuevo build si es necesario.
-### "Worktree missing"
-El worktree aislado fue eliminado. Opciones:
-1. Recrear worktree y reanudar
-2. Comenzar de nuevo con nuevo build
-### Build Atascado
-Si el build esta atascado (mismo error repitiendose):
-1. Revisar sugerencias en notificaciones
-2. Revisar registro de intentos: `*build-log story-id`
-3. Intentar enfoque diferente o escalar
----
-## Mejores Practicas
-1. **Verificar estado regularmente** durante builds largos
-2. **Revisar logs** al debuggear fallos
-3. **Limpiar builds abandonados** para liberar recursos
-4. **Usar checkpoints** - no deshabilitar auto-checkpoint
-5. **Monitorear notificaciones** para alertas de atascado
----
-_Guia para Story 8.4 - Build Recovery & Resume_
-_Parte de Epic 8 - Autonomous Build Engine_

package/docs/es/guides/contextual-greeting-system-guide.md DELETED Viewed

@@ -1,387 +0,0 @@
-<!--
-  Traducción: ES
-  Original: /docs/en/guides/contextual-greeting-system-guide.md
-  Última sincronización: 2026-01-26
--->
-# Guía del Sistema de Saludo Contextual
-> 🌐 [EN](../../guides/contextual-greeting-system-guide.md) | [PT](../../pt/guides/contextual-greeting-system-guide.md) | **ES**
----
-**Story:** 6.1.2.5 - Contextual Agent Load System
-**Estado:** Componentes Implementados, Integración Pendiente
-**Fecha:** 2025-01-15
----
-## Descripción General
-El Sistema de Saludo Contextual es una mejora de UX que hace que los saludos de los agentes SINAPSE sean inteligentes y adaptativos, mostrando información y comandos relevantes basados en el contexto de la sesión.
-## Lo Que Se Ha Implementado
-### Componentes Core (Story 6.1.2.5)
-1. **ContextDetector** (`.sinapse-ai/core/session/context-detector.js`)
-   - Detecta tipo de sesión: `new`, `existing`, o `workflow`
-   - Enfoque híbrido: historial de conversación (preferido) + archivo de sesión (fallback)
-   - TTL de 1 hora para sesiones inactivas
-2. **GitConfigDetector** (`.sinapse-ai/infrastructure/scripts/git-config-detector.js`)
-   - Detecta configuración de git del proyecto
-   - Caché con TTL de 5 minutos
-   - Protección de timeout de 1000ms
-3. **GreetingBuilder** (`.sinapse-ai/development/scripts/greeting-builder.js`)
-   - Construye saludos contextuales basados en el tipo de sesión
-   - Filtra comandos por visibilidad (full/quick/key)
-   - Timeout de 150ms con fallback elegante
-4. **WorkflowNavigator** (`.sinapse-ai/development/scripts/workflow-navigator.js`)
-   - Detecta estado del workflow actual
-   - Sugiere próximos comandos basado en el estado
-   - Pre-popula comandos con contexto (story path, branch)
-5. **Workflow Patterns** (`.sinapse-ai/data/workflow-patterns.yaml`)
-   - 10 workflows comunes definidos
-   - Transiciones de estado con sugerencias de próximos pasos
-   - Patrones validados contra uso real del proyecto
-### Pendiente (Story Futura - 6.1.4 o 6.1.6)
-**Integración con Proceso de Activación:**
-- Interceptar activación del agente (cuando escribes `@dev`, `@po`, etc.)
-- Llamar GreetingBuilder automáticamente
-- Inyectar saludo contextual en lugar del saludo estándar
-## Tipos de Sesión
-### 1. New Session (Sesión Nueva)
-**Cuándo:** Primera interacción o después de 1 hora de inactividad
-**Características:**
-- Presentación completa (greeting archetypal)
-- Descripción del rol del agente
-- Estado del proyecto (si git está configurado)
-- Comandos completos (hasta 12 comandos con visibility=full)
-**Ejemplo:**
-```
-💻 Dex (Builder) ready. Let's build something solid!
-**Role:** Full Stack Developer specializing in clean, maintainable code
-📊 Project Status:
-🌿 main
-📝 5 modified files
-📦 Last commit: feat: implement greeting system
-**Available Commands:**
-   - `*help`: Show all available commands
-   - `*develop`: Implement story tasks
-   - `*review-code`: Review code changes
-   - `*run-tests`: Execute test suite
-   - `*build`: Build for production
-   ... (hasta 12 comandos)
-```
-### 2. Existing Session (Sesión Existente)
-**Cuándo:** Continuando trabajo en la misma sesión
-**Características:**
-- Presentación resumida (greeting named)
-- Estado del proyecto
-- Contexto actual (última acción)
-- Comandos rápidos (6-8 comandos con visibility=quick)
-**Ejemplo:**
-```
-💻 Dex (Builder) ready.
-📊 Project Status:
-🌿 feature/story-6.1.2.5
-📝 3 modified files
-📌 **Last Action:** review-code
-**Quick Commands:**
-   - `*help`: Show help
-   - `*develop`: Implement story
-   - `*review-code`: Review code
-   - `*run-tests`: Run tests
-   - `*qa-gate`: Run quality gate
-   ... (6-8 comandos más usados)
-```
-### 3. Workflow Session (Sesión en Workflow)
-**Cuándo:** En medio de un workflow activo (ej: después de validar story)
-**Características:**
-- Presentación mínima (greeting minimal)
-- Estado condensado del proyecto
-- Contexto del workflow (working on X)
-- **Sugerencias de próximos pasos** (NUEVO!)
-- Comandos clave (3-5 comandos con visibility=key)
-**Ejemplo:**
-```
-⚖️ Pax ready.
-📊 🌿 main | 📝 5 modified | 📖 STORY-6.1.2.5
-📌 **Context:** Working on Story 6.1.2.5
-**Story validated! Next steps:**
-1. `*develop-yolo story-6.1.2.5.md` - Autonomous mode (no interruptions)
-2. `*develop-interactive story-6.1.2.5.md` - Interactive mode with checkpoints
-3. `*develop-preflight story-6.1.2.5.md` - Plan first, then execute
-**Key Commands:**
-   - `*help`: Show help
-   - `*validate-story-draft`: Validate story
-   - `*backlog-summary`: Quick backlog status
-```
-## Sistema de Visibilidad de Comandos
-### Metadatos de Comandos
-Cada comando ahora tiene un atributo `visibility` que controla cuándo aparece:
-```yaml
-commands:
-  - name: help
-    visibility: [full, quick, key]  # Siempre visible
-    description: "Show all available commands"
-  - name: develop
-    visibility: [full, quick, key]  # Comando principal
-    description: "Implement story tasks"
-  - name: review-code
-    visibility: [full, quick]  # Usado frecuentemente, pero no crítico
-    description: "Review code changes"
-  - name: build
-    visibility: [full]  # Menos usado, solo en new session
-    description: "Build for production"
-  - name: qa-gate
-    visibility: [key]  # Crítico en workflows, pero no siempre necesario
-    description: "Run quality gate"
-```
-### Guías de Categorización
-**`full` (12 comandos)** - New Session
-- Todos los comandos disponibles
-- Muestra capacidades completas del agente
-- Ideal para descubrimiento
-**`quick` (6-8 comandos)** - Existing Session
-- Comandos usados frecuentemente
-- Enfocado en productividad
-- Elimina comandos raramente usados
-**`key` (3-5 comandos)** - Workflow Session
-- Comandos críticos para el workflow actual
-- Mínima distracción
-- Máxima eficiencia
-## Navegación de Workflows
-### Workflows Definidos
-**10 workflows comunes:**
-1. **story_development** - Validate -> Develop -> QA -> Deploy
-2. **epic_creation** - Create epic -> Create stories -> Validate
-3. **backlog_management** - Review -> Prioritize -> Schedule
-4. **architecture_review** - Analyze -> Document -> Review
-5. **git_workflow** - Quality gate -> PR -> Merge
-6. **database_workflow** - Design -> Migrate -> Test
-7. **code_quality_workflow** - Assess -> Refactor -> Test
-8. **documentation_workflow** - Research -> Document -> Sync
-9. **ux_workflow** - Design -> Implement -> Validate
-10. **research_workflow** - Brainstorm -> Analyze -> Document
-### Transiciones de Estado
-Cada workflow define transiciones entre estados con:
-- **Trigger:** Comando que se completa exitosamente
-- **Greeting Message:** Mensaje contextual
-- **Next Steps:** Sugerencias de próximos comandos con args pre-populados
-**Ejemplo (Story Development):**
-```yaml
-story_development:
-  transitions:
-    validated:
-      trigger: "validate-story-draft completed successfully"
-      greeting_message: "Story validated! Ready to implement."
-      next_steps:
-        - command: develop-yolo
-          args_template: "${story_path}"
-          description: "Autonomous YOLO mode (no interruptions)"
-        - command: develop-interactive
-          args_template: "${story_path}"
-          description: "Interactive mode with checkpoints (default)"
-        - command: develop-preflight
-          args_template: "${story_path}"
-          description: "Plan everything upfront, then execute"
-```
-## Cómo Probar Ahora
-### Opción 1: Script de Prueba Automático
-```bash
-node .sinapse-ai/development/scripts/test-greeting-system.js
-```
-Este script prueba los 4 escenarios:
-1. New session greeting (Dev)
-2. Existing session greeting (Dev)
-3. Workflow session greeting (PO)
-4. Simple greeting fallback
-### Opción 2: Prueba Manual via Node REPL
-```javascript
-const GreetingBuilder = require('./.sinapse-ai/development/scripts/greeting-builder');
-const builder = new GreetingBuilder();
-// Mock agent
-const mockAgent = {
-  name: 'Dex',
-  icon: '💻',
-  persona_profile: {
-    greeting_levels: {
-      named: '💻 Dex (Builder) ready!'
-    }
-  },
-  persona: { role: 'Developer' },
-  commands: [
-    { name: 'help', visibility: ['full', 'quick', 'key'] }
-  ]
-};
-// Test new session
-builder.buildGreeting(mockAgent, { conversationHistory: [] })
-  .then(greeting => console.log(greeting));
-```
-### Opción 3: Esperar Integración Completa
-Cuando la integración con el proceso de activación esté implementada (Story 6.1.4/6.1.6), el sistema funcionará automáticamente al activar cualquier agente:
-```
-@dev              → Saludo contextual automático
-@po               → Saludo contextual automático
-@qa               → Saludo contextual automático
-```
-## Archivos Relacionados
-### Scripts Core
-- `.sinapse-ai/core/session/context-detector.js` - Detección de tipo de sesión
-- `.sinapse-ai/infrastructure/scripts/git-config-detector.js` - Detección de git config
-- `.sinapse-ai/development/scripts/greeting-builder.js` - Construcción del saludo
-- `.sinapse-ai/development/scripts/workflow-navigator.js` - Navegación de workflow
-- `.sinapse-ai/development/scripts/agent-exit-hooks.js` - Hooks de salida (para persistencia)
-### Archivos de Datos
-- `.sinapse-ai/data/workflow-patterns.yaml` - Definiciones de workflows
-### Tests
-- `tests/unit/context-detector.test.js` - 23 tests
-- `tests/unit/git-config-detector.test.js` - 19 tests
-- `tests/unit/greeting-builder.test.js` - 23 tests
-- `tests/integration/performance.test.js` - Validación de rendimiento
-### Configuración
-- `.sinapse-ai/core-config.yaml` - Configuración global (secciones git + agentIdentity)
-### Agentes (Actualizados)
-- `.sinapse-ai/agents/dev.md` - Metadatos de visibilidad de comandos
-- `.sinapse-ai/agents/po.md` - Metadatos de visibilidad de comandos
-- `.sinapse-ai/agents/*.md` - 9 agentes restantes (actualización pendiente)
-## Próximos Pasos
-### Inmediato (Arreglar Problemas de Tests)
-1. Arreglar problemas de configuración de tests (1-2 horas)
-2. Ejecutar suite completa de tests
-3. Ejecutar tests de rendimiento
-### Corto Plazo (Story 6.1.4 o 6.1.6)
-1. Implementar integración con proceso de activación de agentes
-2. Actualizar los 9 agentes restantes con metadatos de visibilidad de comandos
-3. Probar con activaciones reales de agentes
-### Largo Plazo (Story 6.1.2.6)
-1. Implementar aprendizaje dinámico de patrones de workflow
-2. Agregar priorización de comandos basada en uso
-3. Implementar hints de colaboración entre agentes
-## Métricas de Rendimiento
-**Objetivo (de Story 6.1.2.5):**
-- Latencia P50: <100ms
-- Latencia P95: <130ms
-- Latencia P99: <150ms (límite duro)
-**Esperado (basado en revisión de código):**
-- Git config (cache hit): <5ms
-- Git config (cache miss): <50ms
-- Detección de contexto: <50ms
-- I/O de archivo de sesión: <10ms
-- Matching de workflow: <20ms
-- **Total P99:** ~100-120ms (bien por debajo del límite)
-**Optimizaciones:**
-- Ejecución paralela (Promise.all)
-- Caching basado en TTL
-- Protección de timeout
-- Salida temprana en cache hit
-## Compatibilidad Hacia Atrás
-**100% Compatible Hacia Atrás:**
-- Agentes sin metadatos de visibilidad muestran todos los comandos (máximo 12)
-- Fallback elegante a saludo simple en cualquier error
-- Cero cambios breaking en el proceso de activación
-- Migración gradual (Fase 1: dev/po -> Fase 2: 9 restantes)
-## Preguntas Frecuentes
-**P: ¿Por qué el saludo no es contextual cuando activo un agente ahora?**
-R: La integración con el proceso de activación aún no se ha implementado. Los componentes existen pero no se llaman automáticamente todavía.
-**P: ¿Cuándo se hará la integración?**
-R: En una story futura (probablemente 6.1.4 o 6.1.6). Depende del sistema de configuración de agentes.
-**P: ¿Cómo puedo probar ahora?**
-R: Usa el script de prueba: `node .sinapse-ai/development/scripts/test-greeting-system.js`
-**P: ¿Qué pasa si un agente no tiene metadatos de visibilidad?**
-R: Fallback: muestra todos los comandos (máximo 12). No rompe nada.
-**P: ¿Cómo agrego metadatos de visibilidad a mis comandos?**
-R: Mira la sección "Sistema de Visibilidad de Comandos" arriba y los ejemplos en los agentes dev.md y po.md.
-**P: ¿Puedo deshabilitar el saludo contextual?**
-R: Sí, via config: `core-config.yaml` -> `agentIdentity.greeting.contextDetection: false`
----
-**Documento Actualizado:** 2025-01-15
-**Autor:** Quinn (QA) + Dex (Dev)
-**Story:** 6.1.2.5 - Contextual Agent Load System