openprompt-lang 1.2.7 → 1.4.0

package/docs/02-STANDARDS/ticket-driven-development.md

@@ -0,0 +1,99 @@
+# Ticket-Driven Development con openPrompt-Lang
+
+> **Propósito:** Documentar el proceso de trabajo que combina tickets ágiles, sprints y anotaciones `@learn-error` de OPL. Este documento sirve como referencia obligatoria y como input para mejorar el workflow de OPL en siguientes versiones.
+
+---
+
+## El Workflow: Bug → Ticket → Fix → Learn-Error
+
+### Regla de Oro
+> **No se fixea nada sin un ticket primero.**
+> Todo bug, por mínimo que sea, debe generar un TICKET-NNN antes de escribir código.
+
+### Ciclo Completo
+```
+1. DETECTAR → 2. TICKET → 3. FIX → 4. QA → 5. LEARN → 6. ARCHIVAR
+```
+
+#### Paso 1: Detectar
+- Puede venir de: `npx tsc --noEmit`, `npx openprompt-lang validate`, auditoría manual, QA tests
+
+#### Paso 2: Crear Ticket
+- Ubicación: `docs/04-TICKETS/TICKET-NNN-descripcion.md`
+- Numeración correlativa global
+
+#### Paso 3: Fix
+- Hacer cambios en el código
+- Si se descubre otro bug durante el fix, crear **nuevo ticket**
+
+#### Paso 4: QA
+- `npx tsc --noEmit` — debe pasar sin errores
+- `npx openprompt-lang validate` — debe pasar sin errores
+
+#### Paso 5: Learn-Error
+```typescript
+// @learn-error id=MODULO-NNN
+// input='qué se hizo mal'
+// expected='qué debería pasar'
+// actual='qué pasó realmente'
+// fix='cómo se corrigió'
+// category=dominio
+```
+
+#### Paso 6: Archivar (Opcional)
+- Sprint cerrado = tickets referenciados y archivados
+
+---
+
+## Estructura de Tickets
+
+```markdown
+# TICKET-NNN: Título Descriptivo
+
+> **Sprint:** Sprint-N
+> **Prioridad:** 🔴 Crítica | 🟠 Alta | 🟡 Media | 🟢 Baja
+> **Esfuerzo:** Xh
+
+## Contexto
+[2-3 párrafos explicando el problema]
+
+## Acceptance Criteria
+- [ ] CRITERIO-1: Descripción verificable
+- [ ] CRITERIO-2: Incluye edge cases
+
+## QA Tests
+```bash
+# Test: comando para verificar
+```
+```
+
+---
+
+## Mejoras Propuestas para OPL v2
+
+### 1. Nuevo Workflow "bug → ticket"
+Paso obligatorio `create_ticket` antes de fix en el default workflow.
+
+### 2. Integración de TODO List
+Auto-creación de TODO list al comenzar tarea >3 pasos.
+
+### 3. Anchored Summary Automático
+Al cerrar sesión, generar resumen desde TODOs completados.
+
+### 4. QA Tests Como Comandos
+```yaml
+acceptance:
+  - cmd: "npx tsc --noEmit"
+    expect: "exit code 0"
+```
+
+### 5. Categorías Controladas para @learn-error
+Enum validado por el validador (no strings libres).
+
+### 6. Archivo de Tickets como Formato Reconocido
+OPL debería reconocer `docs/04-TICKETS/TICKET-NNN-*.md` y validar su estructura.
+
+### 7. Cross-Reference entre Tickets y Código
+```typescript
+// @ref-ticket(TICKET-023)
+```

package/docs/04-TICKETS/BOOST-001-profile-registry.md

@@ -0,0 +1,66 @@
+# BOOST-001 — Profile Registry + Config Base
+
+## Metadatos
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | BOOST-001 |
+| **Título** | Profile Registry + Config Base |
+| **Épica** | Módulo OPL Boost |
+| **Prioridad** | Alta |
+| **Estado** | ✅ Completado |
+| **Depende de** | — |
+| **Archivos** | `src/boost/profile-registry.js`, `prompt-lang.json` |
+
+## Descripción
+
+Crear el sistema de perfiles de modelo que permite a OPL detectar automáticamente la capacidad del modelo activo (small/medium/large) y configurar las estrategias de boost según el perfil.
+
+Este es el cimiento del módulo Boost — sin esto, ningún otro componente sabe cómo comportarse.
+
+## Criterios de Aceptación
+
+### CA-1: Perfiles definidos
+- [x] Existen 3 perfiles: `small` (8K contexto), `medium` (32K), `large` (128K+)
+- [x] Cada perfil define: `compressionLevel`, `validationLoops`, `microTasks`, `templateHydration`, `fewShot`, `contextWindow`
+- [x] Los valores por defecto son razonables (small: alta compresión, 3 loops; large: sin compresión, 1 loop)
+
+### CA-2: Detección automática
+- [x] Detecta perfil desde `process.env.OPL_BOOST_PROFILE`
+- [x] Detecta perfil desde `process.env.OPL_MODEL` (mapeo por nombre conocido: deepseek-coder → small, qwen2.5-coder → medium, gpt-4 → large)
+- [x] Detecta perfil desde configuración en `prompt-lang.json`
+- [x] Si no hay indicación, default: `medium` (seguro)
+
+### CA-3: API exportable
+- [x] `getProfile()` → devuelve el perfil activo con todos sus valores
+- [x] `setProfile(name)` → fuerza un perfil
+- [x] `listProfiles()` → lista los perfiles disponibles
+- [x] `detectProfile()` → lógica de detección automática
+
+### CA-4: Config en prompt-lang.json
+- [x] Sección `boost` agregada a `prompt-lang.json`
+- [x] `boost.enabled: true/false`
+- [x] `boost.defaultProfile: "auto" | "small" | "medium" | "large"`
+- [x] `boost.profiles` con la configuración de cada perfil
+
+### CA-5: CLI check
+- [x] `opl boost check` muestra diagnóstico: perfil detectado, valores activos, modo
+
+### CA-6: Tests
+- [ ] Tests unitarios para detección de perfil (con variables de entorno mock)
+- [ ] Tests para valores por defecto
+- [ ] Tests para forzar perfil
+
+## Archivos a crear/modificar
+
+| Archivo | Acción |
+|---------|--------|
+| `src/boost/profile-registry.js` | ➕ Crear |
+| `prompt-lang.json` | ✏️ Modificar (sección boost) |
+| `src/cli/commands-boost.js` | ➕ Crear (registro inicial con `opl boost check`) |
+
+## Notas técnicas
+
+- No debe tener dependencias externas más allá de `fs` y `path`
+- El perfil se cachea en memoria para no re-detectar en cada llamada
+- El CLI `opl boost check` debe funcionar incluso si el resto del módulo Boost no está implementado

package/docs/04-TICKETS/BOOST-002-context-compression.md

@@ -0,0 +1,58 @@
+# BOOST-002 — Context Compression Engine
+
+## Metadatos
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | BOOST-002 |
+| **Título** | Context Compression Engine |
+| **Épica** | Módulo OPL Boost |
+| **Prioridad** | Alta |
+| **Estado** | ✅ Completado |
+| **Depende de** | BOOST-001 |
+| **Archivos** | `src/boost/context-compressor.js` |
+
+## Descripción
+
+Motor que comprime el contexto (AGENTS.md, reglas, documentación) a solo las secciones relevantes para la tarea actual. Un modelo small recibe ~20% del contexto original, eliminando secciones irrelevantes.
+
+La compresión es adaptativa según el perfil: small comprime 80%, medium 50%, large 0%.
+
+## Criterios de Aceptación
+
+### CA-1: Compresión por tarea
+- [ ] `compressContext(task, fullContext, profile)` → devuelve contexto comprimido
+- [ ] El task description se usa para hacer keyword matching contra secciones
+- [ ] Solo incluye secciones con score de relevancia > umbral (configurable por perfil)
+
+### CA-2: Modos de compresión
+- [ ] **Modo seguro** (default): siempre incluye reglas de enforcement (@limit, @kind, NUNCA)
+- [ ] **Modo agresivo**: solo incluye lo estrictamente relevante a la tarea
+- [ ] **Modo desactivado**: pasa el contexto completo sin modificar
+
+### CA-3: Compresión cuantificable
+- [ ] Retorna métricas: `{ originalChars, compressedChars, reductionPercent, sectionsKept, sectionsRemoved }`
+- [ ] Las métricas son accesibles vía `opl boost check`
+
+### CA-4: Preservación de estructura
+- [ ] No rompe bloques de código, tablas, o listas
+- [ ] Preserva la sección de NUNCA y ENFORCEMENT siempre (modo seguro)
+- [ ] El output sigue siendo markdown válido
+
+### CA-5: Tests
+- [ ] Test con AGENTS.md completo: verify reduction % según perfil
+- [ ] Test que preserve sectiones críticas (ENFORCEMENT, NUNCA)
+- [ ] Test de keyword matching con diferentes task descriptions
+
+## Archivos a crear/modificar
+
+| Archivo | Acción |
+|---------|--------|
+| `src/boost/context-compressor.js` | ➕ Crear |
+
+## Notas técnicas
+
+- Implementar como función pura (sin side effects) para testabilidad
+- El matching de secciones se hace por: título de sección (##, ###), palabras clave, y contexto
+- Secciones protegidas: `ENFORCEMENT`, `NUNCA`, `REGLA ABSOLUTA`, `@limit`
+- No necesita leer archivos — recibe el contexto como string

package/docs/04-TICKETS/BOOST-003-template-hydration.md

@@ -0,0 +1,69 @@
+# BOOST-003 — Template Hydration System
+
+## Metadatos
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | BOOST-003 |
+| **Título** | Template Hydration System |
+| **Épica** | Módulo OPL Boost |
+| **Prioridad** | Alta |
+| **Estado** | ✅ Completado |
+| **Depende de** | BOOST-001 |
+| **Archivos** | `src/boost/hydrator.js`, `src/boost/skeletons/*` |
+
+## Descripción
+
+Sistema que proporciona esqueletos de código (skeletons) por @kind (hook, component, page, service, store) donde el modelo solo rellena la lógica de negocio (~10%). OPL se encarga de armar el código final con imports, tipos, anotaciones OPL y exports correctos.
+
+Esto reduce drásticamente los errores de estructura típicos de modelos pequeños.
+
+## Criterios de Aceptación
+
+### CA-1: Skeletons por @kind
+- [ ] Existen skeletons para: `hook`, `component`, `page`, `service`, `store`
+- [ ] Cada skeleton incluye: imports base, estructura OPL (@use, @kind, @limit), tipo/interface, función placeholder, export
+- [ ] Los skeletons respetan los límites de líneas de AGENTS.md (hook:80, component:120, etc.)
+
+### CA-2: Hydration
+- [ ] `hydrate(kind, businessLogic)` → devuelve archivo completo con anotaciones
+- [ ] El business logic del modelo se inyecta en el placeholder correcto
+- [ ] Se agregan anotaciones @use con los valores correctos
+- [ ] Se agrega @limit según el @kind
+- [ ] Se agrega @contract (hooks/services) o @props (components) según el tipo
+
+### CA-3: Validación post-hydration
+- [ ] El archivo resultante pasa `npx openprompt-lang validate` sin errores
+- [ ] El archivo resultante tiene TypeScript válido
+
+### CA-4: CLI generate
+- [ ] `opl boost generate "hook useAuth"` → hydrata un hook
+- [ ] `opl boost generate "component Button" --kind component` → hydrata un componente
+- [ ] Opción `--dry-run` muestra el skeleton sin rellenar
+- [ ] Opción `--kind` para especificar tipo (auto-detecta si se omite)
+
+### CA-5: Tests
+- [ ] Test de hydratación para cada @kind
+- [ ] Test que el output pase validate
+- [ ] Test que el output tenga TypeScript válido (si tsc está disponible)
+- [ ] Test con business logic mínimo
+
+## Archivos a crear/modificar
+
+| Archivo | Acción |
+|---------|--------|
+| `src/boost/hydrator.js` | ➕ Crear |
+| `src/boost/skeletons/hook.skeleton.js` | ➕ Crear |
+| `src/boost/skeletons/component.skeleton.js` | ➕ Crear |
+| `src/boost/skeletons/page.skeleton.js` | ➕ Crear |
+| `src/boost/skeletons/service.skeleton.js` | ➕ Crear |
+| `src/boost/skeletons/store.skeleton.js` | ➕ Crear |
+| `src/boost/skeletons/index.js` | ➕ Crear (export unificado) |
+
+## Notas técnicas
+
+- Los skeletons son archivos JavaScript/TypeScript válidos con marcadores `{{PLACEHOLDER_LOGIC}}`
+- La hydratación es un simple string replace + wrapper injection
+- Los skeletons deben seguir las convenciones de OPL (named exports, anotaciones primero)
+- Para `component`: incluir estructura cva + cn() como en shadcn/ui
+- Para `hook`: incluir estructura de estado + efecto + retorno tipado

package/docs/04-TICKETS/BOOST-004-fewshot-engine.md

@@ -0,0 +1,58 @@
+# BOOST-004 — Few-Shot Example Engine
+
+## Metadatos
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | BOOST-004 |
+| **Título** | Few-Shot Example Engine |
+| **Épica** | Módulo OPL Boost |
+| **Prioridad** | Media |
+| **Estado** | ✅ Completado |
+| **Depende de** | BOOST-001 |
+| **Archivos** | `src/boost/fewshot-retriever.js` |
+
+## Descripción
+
+Motor que busca ejemplos relevantes en el knowledge-repo y los injecta en el prompt como few-shot examples antes de que el modelo genere código. Los modelos pequeños mejoran dramáticamente cuando tienen ejemplos concretos del mismo dominio y @kind.
+
+## Criterios de Aceptación
+
+### CA-1: Búsqueda de ejemplos
+- [ ] `retrieveExamples(kind, domain, query)` → devuelve 2-3 ejemplos relevantes
+- [ ] Busca en templates de OPL (p.ej., hooks existentes en src/)
+- [ ] Busca en knowledge-repo (documentación, ejemplos de código)
+- [ ] Filtra por @kind (solo ejemplos del mismo tipo)
+
+### CA-2: Ranking de relevancia
+- [ ] Ordena resultados por: matching de dominio > matching de @kind > frescura (fecha)
+- [ ] Devuelve máximo 3 ejemplos para no saturar el contexto del modelo
+
+### CA-3: Inyección en prompt
+- [ ] `buildFewShotPrompt(examples, userPrompt)` → prompt completo con ejemplos antes de la instrucción
+- [ ] Los ejemplos se envuelven en bloques con metadata (archivo, @kind, propósito)
+- [ ] El prompt resultante tiene estructura clara: [instrucción] → [ejemplos] → [tarea]
+
+### CA-4: Configuración por perfil
+- [ ] Perfil `small`: siempre busca ejemplos (fewShot: true)
+- [ ] Perfil `medium`: busca ejemplos si hay matching > 70%
+- [ ] Perfil `large`: no busca ejemplos (fewShot: false)
+
+### CA-5: Tests
+- [ ] Test de búsqueda con diferentes queries
+- [ ] Test que no retorne más de 3 ejemplos
+- [ ] Test de formato del prompt inyectado
+- [ ] Test con knowledge-repo vacío (debe fallar graceful)
+
+## Archivos a crear/modificar
+
+| Archivo | Acción |
+|---------|--------|
+| `src/boost/fewshot-retriever.js` | ➕ Crear |
+
+## Notas técnicas
+
+- La búsqueda en knowledge-repo puede ser básica (grep/búsqueda textual) o usando los embeddings existentes
+- Priorizar búsqueda textual simple para no depender de embeddings
+- Los ejemplos deben ser cortos (máximo 50 líneas cada uno)
+- Incluir metadata de cada ejemplo: tipo, dominio, propósito

package/docs/04-TICKETS/BOOST-005-agent-pool.md

@@ -0,0 +1,69 @@
+# BOOST-005 — Agent Pool + Ollama Connector
+
+## Metadatos
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | BOOST-005 |
+| **Título** | Agent Pool + Ollama Connector |
+| **Épica** | Módulo OPL Boost |
+| **Prioridad** | Alta |
+| **Estado** | ✅ Completado |
+| **Depende de** | BOOST-001 |
+| **Documento** | `docs/00-ARCHITECTURE/OPL-BOOST-MULTI-AGENT.md` |
+
+## Descripción
+
+Infraestructura que permite a OPL llamar a modelos locales vía Ollama. El Agent Pool gestiona una cola de solicitudes, maneja reintentos, timeouts y formatea los prompts según el rol del agente. Es el núcleo que permite el modelo de orquestación interna (Modelo A).
+
+## Criterios de Aceptación
+
+### CA-1: Conector Ollama
+- [x] `callOllama(prompt, options)` → llama a `http://localhost:11434/api/generate`
+- [x] Soporta: `model`, `temperature`, `maxTokens`, `stream` (false por defecto)
+- [x] Timeout configurable (default: 30s)
+- [x] Manejo de errores: conexión rechazada, timeout, respuesta inválida
+
+### CA-2: Pool de agentes
+- [x] `AgentPool` clase que mantiene cola de solicitudes
+- [x] `pool.submit(role, input, profile)` → encola y retorna promesa
+- [x] Modo cola: una solicitud a la vez (FIFO)
+- [x] Modo paralelo: múltiples solicitudes simultáneas (configurable via perfil)
+
+### CA-3: Formateo de prompts por rol
+- [x] `buildPrompt(role, input)` → arma el prompt según el rol del agente
+- [x] Roles iniciales: `types`, `state`, `logic`, `cleaner`, `validate`
+- [x] Cada rol tiene: system prompt + template de input + formato de output esperado
+
+### CA-4: Detección de Ollama
+- [x] `checkOllama()` → verifica si Ollama está corriendo
+- [x] `listModels()` → lista modelos disponibles en Ollama
+- [x] `selectBestModel(profile)` → selecciona el mejor modelo según perfil
+
+### CA-5: Integración con perfil
+- [x] Lee configuración de `profile.agentPool` (mode, modelName, temperature)
+- [x] Si Ollama no está disponible, falla graceful con mensaje claro
+
+### CA-6: Tests
+- [ ] Test de formateo de prompts por rol
+- [ ] Test de cola FIFO
+- [ ] Test de timeout y errores
+- [ ] Test de detección de Ollama (mock)
+
+## Archivos
+
+| Archivo | Acción |
+|---------|--------|
+| `src/boost/agent-pool.js` | ➕ Crear (conector + pool + prompts) |
+| `src/boost/agents/agent-types.js` | ➕ Crear |
+| `src/boost/agents/agent-state.js` | ➕ Crear |
+| `src/boost/agents/agent-logic.js` | ➕ Crear |
+| `src/boost/agents/agent-validate.js` | ➕ Crear |
+| `src/boost/agents/agent-cleaner.js` | ➕ Crear |
+| `src/boost/agents/index.js` | ➕ Crear (export unificado) |
+
+## Notas
+
+- Node 18+ tiene `fetch` nativo — no necesita dependencias externas
+- La URL de Ollama es configurable via `OLLAMA_HOST` env var (default: `http://localhost:11434`)
+- Los prompts deben ser cortos (< 500 chars) para que quepan en contexto small

package/docs/04-TICKETS/BOOST-006-specialized-agents.md

@@ -0,0 +1,53 @@
+# BOOST-006 — Agentes Especializados (Types, State, Logic, Cleaner, Validate)
+
+## Metadatos
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | BOOST-006 |
+| **Título** | Agentes Especializados |
+| **Épica** | Módulo OPL Boost |
+| **Prioridad** | Alta |
+| **Estado** | ✅ Completado |
+| **Depende de** | BOOST-005 |
+| **Archivos** | `src/boost/agents/index.js`, `src/boost/agent-pool.js` |
+
+## Descripción
+
+Registro de agentes especializados que envuelven los prompts del Agent Pool (BOOST-005) con lógica de validación y parseo de output. Cada agente tiene un rol específico en el pipeline de generación de código.
+
+## Implementación
+
+Los 5 agentes están implementados en `src/boost/agents/index.js`:
+
+| Rol | ID | Validación |
+|-----|-----|-----------|
+| **Type Designer** | `types` | Output debe contener `interface` o `type ` |
+| **State Architect** | `state` | Output debe contener `useState`, `useEffect`, o `useReducer` |
+| **Logic Implementer** | `logic` | Output debe tener más de 50 caracteres |
+| **Context Cleaner** | `cleaner` | Output debe ser más corto que el input |
+| **Code Validator** | `validate` | Output debe tener más de 20 caracteres |
+
+## Criterios de Aceptación
+
+### CA-1: Agentes registrados
+- [x] 5 roles definidos en `AGENTS` registry: types, state, logic, cleaner, validate
+- [x] Cada agente exporta: `role`, `label`, `description`, `buildPrompt`, `validateOutput`, `parseOutput`
+- [x] `getAgent(role)` → obtiene agente por ID
+- [x] `listAgents()` → lista todos los agentes disponibles
+
+### CA-2: Validación de output
+- [x] `validateOutput(text)` → verifica que el output tenga sentido para el rol
+- [x] Si un agente produce output inválido, se puede reintentar
+- [x] Validación específica por tipo de agente
+
+### CA-3: Tests
+- [ ] Test unitario para cada agente
+- [ ] Test de validación de output
+- [ ] Test que `getAgent` falla con rol desconocido
+
+## Notas
+
+- Los prompts de sistema viven en `agent-pool.js` (buildPrompt), el registry en `agents/index.js`
+- Cada agente usa `buildPrompt(role, input)` del Agent Pool
+- No hay archivos individuales por agente — todo está en el registry centralizado con agent-pool.js

package/docs/04-TICKETS/BOOST-007-validation-loop.md

@@ -0,0 +1,56 @@
+# BOOST-007 — Validation Loop + Agent Validate
+
+## Metadatos
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | BOOST-007 |
+| **Título** | Validation Loop + Agent Validate |
+| **Épica** | Módulo OPL Boost |
+| **Prioridad** | Alta |
+| **Estado** | ✅ Completado |
+| **Depende de** | BOOST-006 |
+| **Archivos** | `src/boost/validation-loop.js` |
+
+## Descripción
+
+Sistema post-generación que ejecuta validación OPL y TypeScript sobre el código generado, retroalimentando errores específicos al agente `validate` para que los corrija. Los modelos pequeños son significativamente mejores corrigiendo errores específicos que generando código correcto la primera vez.
+
+Si tras N reintentos el código sigue fallando, escala hacia abajo la complejidad.
+
+## Criterios de Aceptación
+
+### CA-1: Validación post-generación
+- [ ] `validate(code, kind)` → ejecuta validación OPL sobre código generado
+- [ ] Detecta: errores de anotaciones, violaciones de @limit, errores de sintaxis
+- [ ] Retorna array de errores con: tipo, mensaje, línea, sugerencia de fix
+
+### CA-2: Feedback loop con agente validate
+- [ ] `feedbackLoop(code, errors, profile)` → itera: feedback → agente validate → re-validar
+- [ ] El feedback dice exactamente qué está mal + sugerencia
+- [ ] Número de reintentos según perfil: small=3, medium=2, large=1
+
+### CA-3: Escalado de complejidad
+- [ ] Si tras reintentos el código sigue fallando, reduce complejidad
+- [ ] Estrategias: simplificar lógica, usar skeleton más básico, dividir en micro-tareas
+- [ ] `escalateDown(task, attempt)` → versión simplificada de la tarea
+
+### CA-4: Reporte de calidad
+- [ ] `generateReport(codeHistory, errors)` → cuántos intentos tomó, qué errores se corrigieron
+
+### CA-5: Tests
+- [ ] Test de detección de errores de anotaciones
+- [ ] Test de feedback loop con mock
+- [ ] Test de escalado tras N reintentos fallidos
+
+## Archivos a crear
+
+| Archivo | Acción |
+|---------|--------|
+| `src/boost/validation-loop.js` | ➕ Crear |
+
+## Notas técnicas
+
+- La validación OPL se hace invocando `npx openprompt-lang validate` o usando el módulo de validación directamente
+- El feedback loop necesita acceso al modelo vía agent-pool.js para re-generar
+- El escalado de complejidad es determinista (no necesita IA)

package/docs/04-TICKETS/BOOST-008-orchestrator.md

@@ -0,0 +1,71 @@
+# BOOST-008 — Orchestrator (Pipeline Unificado)
+
+## Metadatos
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | BOOST-008 |
+| **Título** | Orchestrator — Pipeline Unificado |
+| **Épica** | Módulo OPL Boost |
+| **Prioridad** | Alta |
+| **Estado** | ✅ Completado |
+| **Depende de** | BOOST-007 |
+| **Archivos** | `src/boost/orchestrator.js`, `src/boost/task-dispatcher.js`, `src/boost/index.js` |
+
+## Descripción
+
+Orquestador multi-etapa que coordina todos los componentes Boost en un flujo coherente. Incluye el **Task Dispatcher** que descompone tareas en un DAG de pasos con dependencias, y el **Orchestrator** que ejecuta el pipeline completo.
+
+El pipeline completo:
+1. **Profile detect** → carga perfil activo
+2. **Context compress** → reduce contexto según perfil
+3. **Few-shot retrieve** → busca ejemplos relevantes
+4. **Task dispatch** → descompone en DAG
+5. **Agent pool execute** → ejecuta agentes según dependencias
+6. **Hydrate** → ensambla código final (usa BOOST-003)
+7. **Validate loop** → corrige errores (usa BOOST-007)
+8. **Output** → código listo
+
+## Criterios de Aceptación
+
+### CA-1: Task Dispatcher (DAG)
+- [ ] `plan(task, kind)` → devuelve DAG con nodos y dependencias
+- [ ] Nodos sin dependencias → paralelo; con dependencias → secuencial
+- [ ] DAG serializable a JSON para cache/debug
+- [ ] Soporta: hooks, components, pages, services, stores
+
+### CA-2: Orchestrator unificado
+- [ ] `boost(task, options)` → orquesta pipeline completo
+- [ ] `options.profile` → perfil a usar
+- [ ] `options.kind` → tipo de archivo
+- [ ] `options.dryRun` → mostrar plan sin ejecutar
+- [ ] `options.output` → archivo de salida
+- [ ] Retorna: `{ code, metadata, report }`
+
+### CA-3: Metadata de ejecución
+- [ ] `{ profile, stages: [{name, duration, result}], totalTime, compressionRatio, validationAttempts }`
+- [ ] Exportable como JSON para diagnóstico
+
+### CA-4: Modo dry-run
+- [ ] `boost(task, { dryRun: true })` → muestra DAG, skeletons, ejemplos sin ejecutar
+
+### CA-5: Tests
+- [ ] Test de planificación DAG para cada @kind
+- [ ] Test de pipeline completo con mock de modelo
+- [ ] Test de dry-run
+- [ ] Test de metadata de ejecución
+
+## Archivos a crear
+
+| Archivo | Acción |
+|---------|--------|
+| `src/boost/orchestrator.js` | ➕ Crear (pipeline unificado) |
+| `src/boost/task-dispatcher.js` | ➕ Crear (DAG planner) |
+| `src/boost/index.js` | ➕ Crear (API público del módulo) |
+
+## Notas técnicas
+
+- El `index.js` es el API público del módulo Boost (`import { boost } from './boost/index.js'`)
+- Cada etapa del pipeline se puede ejecutar independientemente
+- Si una etapa falla, el pipeline devuelve error con estado parcial
+- Los tiempos de cada etapa se registran para diagnóstico

package/docs/04-TICKETS/BOOST-009-cache-system.md

@@ -0,0 +1,56 @@
+# BOOST-009 — Cache System
+
+## Metadatos
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | BOOST-009 |
+| **Título** | Cache System para Boost |
+| **Épica** | Módulo OPL Boost |
+| **Prioridad** | Media |
+| **Estado** | ✅ Completado |
+| **Depende de** | BOOST-008 |
+| **Archivos** | `src/boost/cache.js` |
+
+## Descripción
+
+Sistema de caché para resultados parciales de agentes Boost. Evita re-ejecutar agentes cuando el mismo input ya fue procesado, ahorrando tiempo y recursos.
+
+## Criterios de Aceptación
+
+### CA-1: Caché por clave/valor
+- [ ] `cache.get(key)` → obtiene valor cacheado
+- [ ] `cache.set(key, value, ttl)` → guarda valor con TTL
+- [ ] `cache.has(key)` → verifica si existe y no ha expirado
+- [ ] `cache.delete(key)` → elimina entrada
+- [ ] `cache.clear()` → limpia toda la caché
+
+### CA-2: Claves de caché predefinidas
+| Clave | TTL | Beneficio |
+|-------|-----|-----------|
+| `compress:{task.kind}` | 1 hora | No re-comprimir contexto |
+| `fewshot:{kind}:{domain}` | 1 día | No re-buscar ejemplos |
+| `agent:{role}:{input_hash}` | 5 min | No re-ejecutar mismo input |
+| `dag:{task_hash}` | 5 min | No re-planificar tarea igual |
+
+### CA-3: Persistencia
+- [ ] Caché en disco: `.opencode/boost/cache/`
+- [ ] Limpieza automática al expirar TTL
+- [ ] `opl boost cache clear` → comando para limpiar manualmente
+
+### CA-4: Tests
+- [ ] Test de set/get/delete/clear
+- [ ] Test de expiración por TTL
+- [ ] Test de persistencia en disco
+
+## Archivos a crear
+
+| Archivo | Acción |
+|---------|--------|
+| `src/boost/cache.js` | ➕ Crear |
+
+## Notas técnicas
+
+- Implementación simple: archivos JSON en `.opencode/boost/cache/`
+- Hash de input: `crypto.createHash('md5').update(input).digest('hex')`
+- No necesita dependencias externas