openprompt-lang 1.2.7 → 1.3.0

package/README.md

@@ -30,6 +30,25 @@ Guarda conceptos visuales o técnicos para que la IA los entienda como tú los e
 ### Repositorio de Conocimiento (Knowledge)
 Almacena, indexa y procesa documentos PDF y fuentes web técnicas. Detecta capítulos automáticamente y los divide en secciones de lectura rápida para que la IA los use. Incluye **33 libros y guías pre-empaquetados** (JavaScript, TypeScript, Rust, React, Node.js, Python, Scrum, accesibilidad, algoritmos, API de pagos, etc.) accesibles sin configuración previa vía MCP (`knowledge_search`, `knowledge_list`, `knowledge_read`, `knowledge_concept`) o CLI (`knowledge search`, `knowledge sync --all`). Genera automáticamente `.openprompt/FRAMEWORK.md` con el manual operativo restrictivo para la IA.
 
+### Búsqueda Semántica por Embeddings (Vector Search)
+Reemplaza el mapa semántico manual con vectores numéricos generados por IA local. Divide documentos en chunks semánticos, los convierte en vectores (768d con Ollama o 384d con Transformers.js), y busca por similitud de coseno. Incluye un pipeline completo: chunker (3 estrategias), embedder (Ollama + Transformers.js con auto-fallback), vector store (SQLite + FTS5), y soporte de búsqueda híbrida (FTS5 + reordenamiento semántico). Se integra con `opl search --mode vector` y el indexado automático tras la ingesta de PDFs.
+
+**Requisitos:**
+- **Primario**: [Ollama](https://ollama.com) con `ollama pull nomic-embed-text` (recomendado)
+- **Fallback**: `@xenova/transformers` (incluido como dependencia opcional, se activa automáticamente si Ollama no está disponible)
+
+**Comandos:**
+```bash
+opl embeddings status                    # Ver estado del índice vectorial
+opl embeddings index <docId>             # Indexar un documento
+opl embeddings remove <docId>            # Eliminar embeddings
+opl embeddings config                    # Ver/configurar proveedor
+opl search "consulta" --mode vector      # Búsqueda semántica
+opl search "consulta" --mode hybrid      # Híbrido (incluye vectorial)
+opl webscrape <url> --domain frontend    # Scrapear web e indexar
+knowledge ingest doc.pdf                 # Ingesta PDF + auto-embedding
+```
+
 ### IA Local (Local Setup)
 Configura un entorno de desarrollo completamente local y desconectado. Prepara la integración con modelos locales en Ollama (como Llama 3 o Qwen 2.5 Coder) y la suite de herramientas OpenCode, permitiendo trabajar sin internet ni costos de API, pero manteniendo el 100% de la precisión del framework.
 
@@ -582,6 +601,25 @@ openPrompt-Lang component list --validated
 | `openPrompt-Lang knowledge rebuild` | Reconstruye el índice general desde metadatos individuales |
 | `openPrompt-Lang knowledge sync [--all]` | Sincroniza libros de la biblioteca empaquetada al proyecto local |
 | `openPrompt-Lang local-setup` | Configura integración con IA local (Ollama + OpenCode) |
+| `opl workflow select <desc>` | Selecciona workflow óptimo según descripción de la tarea (usar SIEMPRE primero) |
+| `opl workflow delivery` | Inicia desarrollo por tickets (E.3) |
+| `opl workflow close` | Cierra sesión activa y genera reporte (E.4) |
+| `opl epic create --title "..." --desc "..."` | Crea épica con tickets generados automáticamente |
+| `opl epic list` | Lista épicas con métricas de progreso |
+| `opl epic show <id>` | Muestra detalle de épica y sus tickets |
+| `opl epic close <id>` | Cierra épica |
+| `opl sprint create <name> --goal "..."` | Crea sprint con duración configurable |
+| `opl sprint list` | Lista sprints con métricas |
+| `opl sprint plan <id> --capacity N` | Planifica sprint automáticamente desde épicas activas |
+| `opl sprint close <id>` | Cierra sprint |
+| `opl ticket create --title "..." --severity ...` | Crea ticket de bug/tarea |
+| `opl ticket list` | Lista tickets del proyecto |
+| `opl ticket close <id>` | Cierra ticket como fixed |
+| `opl embeddings status` | Ver estado del índice vectorial semántico |
+| `opl embeddings index <docId>` | Indexa un documento en el vector store |
+| `opl embeddings remove <docId>` | Elimina embeddings de un documento |
+| `opl embeddings config` | Ver/configurar proveedor de embeddings |
+| `opl webscrape <url>` | Extrae contenido web y lo indexa en knowledge + embeddings |
 
 ### Base de Conocimiento Empaquetada
 
@@ -1128,17 +1166,33 @@ El **Work Context** es un sistema integrado de trazabilidad obligatoria que regi
 | `openPrompt-Lang work-context check` | Verifica consistencia del work-context: valida que `SESSION.json` exista y tenga estructura correcta, detecta sesiones activas olvidadas (>24h), confirma que los planes referenciados existen en disco, valida que `LOG.json` sea un array válido |
 | `validate --work-context` | Incluye la verificación de work-context dentro del pipeline de validación estándar |
 
-### Flujo de trabajo obligatorio
+### Flujo de trabajo obligatorio (v1.3.0)
 
-La IA debe seguir este ciclo en **cada sesión de trabajo**:
+La IA debe seguir este ciclo en **cada sesión de trabajo**. No hay excepciones:
 
 ```
-1. CONTEXT.md + SESSION.json  → restaurar estado o iniciar nuevo
-2. ANALYZE request            → clasificar tipo de tarea
-3. PLAN → `work-context plan new <name> --task "<desc>"` → PLANS/, log en LOG
-4. VALIDATE plan              → contra @kind, @contract, @limit
-5. IMPLEMENT                  → codificar, log cada acción
-6. VALIDATE código            → validate + validate --work-context
+1. → workflow_select          → "opl workflow select <descripción>"
+                               La IA describe su tarea, el sistema selecciona workflow óptimo
+2. → create_ticket             → "opl ticket create --title ... --severity ..."
+                               TODO cambio requiere ticket ANTES de implementar
+3. → check_gates               → workflow_selected ✓, ticket_created ✓, plan_approved ✓
+4. → work_context_plan         → Planificar usando work-context con búsqueda de conocimiento
+5. → implement                 → Codificar con anotaciones OPL primero (@kind → @contract → @limit)
+6. → validate                  → "opl validate" antes de cerrar
+7. → docs_updated              → Actualizar documentación (OBLIGATORIO antes de cerrar)
+8. → work_context_close        → Cerrar sesión y generar reporte
+```
+
+**Reglas inquebrantables:**
+- **Regla #1**: `workflow select` primero — Sin workflow seleccionado no hay implementación
+- **Regla #2**: `ticket create` antes de código — Sin ticket no se escribe código
+- **Regla #3**: `docs_updated` antes de cerrar — Sin documentación actualizada no se cierra sesión
+
+El sistema de gates (`workflow_selected`, `ticket_created`, `plan_approved`, `docs_updated`)
+bloquea herramientas automáticamente si no se cumplen los prerrequisitos (configurable en
+`prompt-lang.json` → `workflow.enforcement`).
+
+Ver también: `AGENTS.md` para instrucciones detalladas de cada paso.
 7. INTEGRATE                  → actualizar AGENTS.md si toca
 8. LEARN + REFERENCES.md      → checklist de referencias seguras
 9. CLOSE                      → reporte, métricas finales

package/docs/EMBEDDINGS.md

@@ -0,0 +1,214 @@
+# Sistema de Embeddings Vectoriales
+
+## 📋 Overview
+
+openPrompt-Lang ahora soporta búsqueda semántica vectorial. En lugar de depender solo de coincidencia de palabras clave (tags, fulltext) o un mapa semántico manual, los documentos se dividen en **chunks semánticos**, cada chunk se convierte en un **vector embedding**, y las consultas se resuelven por **similitud de coseno**.
+
+## 🏗️ Arquitectura
+
+```
+Documento (opl format)
+    │
+    ▼
+┌─────────────────┐
+│   chunker.js    │  Divide: paragraph | section | fixed
+└────────┬────────┘
+         │ chunks[]
+         ▼
+┌─────────────────┐
+│   embedder.js   │  Vectoriza: Ollama | Transformers.js | auto-fallback
+└────────┬────────┘
+         │ vectors[]
+         ▼
+┌─────────────────────┐
+│  vector-store.js    │  Almacena + busca en SQLite
+│  (embeddings table) │
+└────────┬────────────┘
+         │ search(queryVector)
+         ▼
+┌─────────────────┐
+│  index-pipeline │  Orquestador: chunk → embed → store
+└─────────────────┘
+```
+
+## 📦 Módulos
+
+| Módulo | Archivo | Responsabilidad |
+|--------|---------|----------------|
+| Chunker | `src/embeddings/chunker.js` | Divide documentos en chunks semánticos |
+| Embedder | `src/embeddings/embedder.js` | Genera vectores numéricos (embeddings) |
+| Vector Store | `src/embeddings/vector-store.js` | Almacena/consulta vectores en SQLite |
+| Index Pipeline | `src/embeddings/index-pipeline.js` | Orquesta chunk → embed → store |
+
+## 🔧 Comandos CLI
+
+### `opl embeddings index <docId>`
+
+Indexa un documento en el vector store.
+
+```bash
+opl embeddings index react-fullstack-app
+opl embeddings index react-fullstack-app --strategy paragraph
+opl embeddings index react-fullstack-app --provider transformers
+opl embeddings index react-fullstack-app --dry-run  # simular sin persistir
+opl embeddings index react-fullstack-app --resume     # saltar chunks existentes
+```
+
+### `opl embeddings status`
+
+Muestra el estado actual del índice vectorial.
+
+```bash
+opl embeddings status
+# 📊  Estado del índice de embeddings
+#   Chunks indexados:   245
+#   Documentos:         12
+#   Dimensión:          768
+#   Modelo:             nomic-embed-text
+#   Último indexado:    2026-05-24 20:00:00
+#   Almacenamiento:     1.2 MB
+```
+
+### `opl embeddings remove <docId>`
+
+Elimina todos los embeddings de un documento.
+
+```bash
+opl embeddings remove react-fullstack-app
+```
+
+### `opl embeddings config`
+
+Ver o cambiar el proveedor de embeddings.
+
+```bash
+opl embeddings config                              # ver estado
+opl embeddings config --provider transformers      # cambiar a transformers
+opl embeddings config --provider ollama            # cambiar a ollama
+```
+
+### `opl search --mode vector <query>`
+
+Búsqueda semántica con embeddings.
+
+```bash
+opl search "autenticacion react" --mode vector     # solo vectorial
+opl search "pagos chile" --mode hybrid             # híbrido incluye vector
+```
+
+## 🧠 Proveedores de Embeddings
+
+### Ollama (primario, default)
+
+- **Modelo**: `nomic-embed-text` (768 dimensiones)
+- **URL**: `http://localhost:11434`
+- **Requisito**: `ollama pull nomic-embed-text`
+- **Ventaja**: Local, rápido, gratuito
+
+### Transformers.js (fallback)
+
+- **Modelo**: `Xenova/all-MiniLM-L6-v2` (384 dimensiones)
+- **Requisito**: `npm install @xenova/transformers`
+- **Ventaja**: No requiere servidor externo
+
+### Auto-fallback
+
+El embedder intenta Ollama primero. Si no está disponible, cae automáticamente a Transformers.js. Si ningún proveedor funciona, lanza un error instructivo.
+
+## 📐 Estrategias de Chunking
+
+| Estrategia | Descripción | Cuándo usarla |
+|------------|-------------|---------------|
+| `section` (default) | Divide por `##` respetando títulos | Documentos con estructura clara |
+| `paragraph` | Divide por doble salto de línea | Documentos sin estructura jerárquica |
+| `fixed` | Divide por tamaño fijo con solapamiento | Documentos sin estructura detectada |
+
+## 🔍 Búsqueda Híbrida
+
+`hybridSearch` combina FTS5 (texto completo) con reordenamiento semántico:
+
+1. **FTS5**: Busca palabras clave en el índice de texto completo
+2. **Coseno**: Reordena los candidatos por similitud semántica
+
+Esto da lo mejor de ambos mundos: precisión de FTS + semántica de embeddings.
+
+## 💾 Esquema SQLite
+
+```sql
+CREATE TABLE IF NOT EXISTS embeddings (
+    id          TEXT PRIMARY KEY,
+    doc_id      TEXT NOT NULL,
+    doc_title   TEXT NOT NULL DEFAULT '',
+    chapter_idx INTEGER NOT NULL DEFAULT 0,
+    chapter_title TEXT NOT NULL DEFAULT '',
+    chunk_idx   INTEGER NOT NULL DEFAULT 0,
+    content     TEXT NOT NULL,
+    vector      BLOB NOT NULL,
+    dimension   INTEGER NOT NULL DEFAULT 768,
+    tokens      INTEGER NOT NULL DEFAULT 0,
+    model       TEXT NOT NULL DEFAULT '',
+    strategy    TEXT NOT NULL DEFAULT 'section',
+    metadata    TEXT NOT NULL DEFAULT '{}',
+    created_at  TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS embeddings_fts USING fts5(
+    content,
+    content=embeddings,
+    content_rowid=rowid
+);
+```
+
+Los vectores se serializan como BLOB de Float32Array (4 bytes por float).
+
+## 📊 Límites de Escalabilidad
+
+| Métrica | Límite actual | Estrategia futura |
+|---------|--------------|-------------------|
+| Chunks totales | ~5000 | Búsqueda lineal OK |
+| Chunks > 100k | Podría ser lento | Índice HNSW |
+| Dimensión vectores | 768 (Ollama) / 384 (Transformers) | Cualquier dimensión |
+| Latencia búsqueda | < 50ms en 5000 chunks | Indexación en lote |
+
+## ✅ Tests
+
+```bash
+npx vitest run tests/embeddings/   # 87 tests, 4 suites
+```
+
+| Suite | Tests | Cubre |
+|-------|-------|-------|
+| `chunker.test.js` | 20 | Estrategias, límites, edge cases |
+| `embedder.test.js` | 23 | Proveedores, fallback, errores |
+| `vector-store.test.js` | 30 | CRUD, búsqueda, FTS5, híbrida |
+| `index-pipeline.test.js` | 14 | Pipeline completo, reindex, batch |
+
+## 🔗 Integración con OPL Search
+
+El modo `--mode vector` en `opl search`:
+1. Toma la consulta del usuario
+2. La convierte a vector con `embed()`
+3. Busca en el vector store con `hybridSearch()`
+4. Mapea chunks a documentos y muestra resultados
+
+El modo `--mode hybrid` incluye los resultados vectoriales junto con tags, fulltext y semántico.
+
+## ⚡ Auto-embedding
+
+Cuando se ingesta un PDF con `knowledge ingest`, se genera automáticamente el embedding del documento. Para saltar este paso:
+
+```bash
+knowledge ingest mi-documento.pdf --no-embed
+```
+
+## 🚀 Roadmap
+
+- [x] Chunker (3 estrategias)
+- [x] Embedder (Ollama + Transformers.js)
+- [x] Vector Store (SQLite + FTS5)
+- [x] Index Pipeline
+- [x] CLI: `opl embeddings index/status/remove/config`
+- [x] Modo vector en `opl search`
+- [x] Auto-embedding en `knowledge ingest`
+- [ ] Web scraper (`opl webscrape`)
+- [ ] Onboarding workflow en `opl init`

package/docs/ONBOARDING_WORKFLOW.md

@@ -0,0 +1,151 @@
+# 🚀 Onboarding Workflow para IA en openPrompt-Lang
+
+> **Propósito**: Este documento es el punto de entrada OBLIGATORIO para cualquier sesión de IA
+> en un proyecto que ya tiene elementos de openPrompt-Lang.
+>
+> **Generado por**: `opl init` al finalizar la configuración
+> **Versión del documento**: 1.0.0
+> **Última actualización**: {{fecha}}
+
+---
+
+## 📋 Instrucciones para la IA
+
+Al iniciar una sesión en este proyecto, SIGUE ESTE FLUJO ESTRICTAMENTE:
+
+```
+1. LEER este documento (ONBOARDING_WORKFLOW.md) → entender el estado del proyecto
+2. LEER AGENTS.md → stack, convenciones, reglas
+3. LEER docs/AI_CONTEXT.md → memoria del proyecto
+4. EJECUTAR workflow_check → ver qué pasos del workflow OPL faltan
+5. EJECUTAR context_unified → panorama completo del proyecto
+6. CONTINUAR desde el último paso registrado (ver sección "Estado Actual")
+```
+
+---
+
+## 🔍 Detección Automática de Contexto
+
+### ¿Este proyecto ya tiene OPL?
+
+Sí / No (según corresponda)
+
+| Elemento | Estado | Ruta |
+|----------|--------|------|
+| `prompt-lang.json` | ✅ / ❌ | `/ruta` |
+| `AGENTS.md` | ✅ / ❌ | `/ruta` |
+| `docs/AI_CONTEXT.md` | ✅ / ❌ | `/ruta` |
+| `docs/FRAMEWORK.md` | ✅ / ❌ | `/ruta` |
+| `src/` con anotaciones | ✅ / ❌ | `/ruta` |
+| `.opencode/` config | ✅ / ❌ | `/ruta` |
+| `.openprompt/` | ✅ / ❌ | `/ruta` |
+| `knowledge-repo/` | ✅ / ❌ | `/ruta` |
+| Base de conocimiento | ✅ / ❌ | `/ruta` |
+| Sistema de enseñanza | ✅ / ❌ | `/ruta` |
+
+---
+
+## 🧩 Stack del Proyecto
+
+| Componente | Valor |
+|------------|-------|
+| **Framework** | React / Vue / Node.js / Spring Boot |
+| **Lenguaje** | TypeScript / JavaScript / Java |
+| **UI** | Tailwind / shadcn / Mantine / Ninguno |
+| **Base de datos** | Supabase / SQLite / PostgreSQL |
+| **Extensiones** | Supabase, Stripe, Prisma, Ionic, ... |
+| **Módulos OPL activos** | React(23t), Vue(12t), Node(12t), Java(8t) |
+
+---
+
+## 📊 Estado Actual del Proyecto
+
+_Completar durante la última sesión. Esto permite a la próxima IA continuar sin pérdida de contexto._
+
+| Aspecto | Detalle |
+|---------|---------|
+| **Última sesión** | {{fecha}} |
+| **Último comando ejecutado** | `opl ...` |
+| **Fase del proyecto** | Inicial / En desarrollo / Refinamiento / Producción |
+| **Sprint activo** | embeddings-sprint-001 / ninguno |
+| **Ticket en progreso** | TICKET-XXX / ninguno |
+| **Próximo paso** | _Descripción de lo que sigue_ |
+| **Bloqueadores** | _Problemas pendientes_ |
+| **Branch activa** | `main` / `feature/...` |
+
+---
+
+## 🎯 Próximos Pasos Recomendados
+
+1. _Paso 1 — descripción_
+2. _Paso 2 — descripción_
+3. _Paso 3 — descripción_
+
+---
+
+## 🐛 Problemas Conocidos (Academic Issues)
+
+Ver `docs/OPL_ACADEMIC_ISSUES.md` para problemas reportados del sistema de enseñanza.
+
+| # | Título | Severidad | Estado |
+|---|--------|-----------|--------|
+| 1 | Onboarding IA en proyecto existente | 🔴 Alta | Abierto |
+| 2 | `opl rebuild` no detecta OPL | 🟡 Media | Abierto |
+| 3 | Falta documento post-init para IA | 🔴 Alta | Abierto |
+
+---
+
+## 📚 Documentos de Referencia
+
+| Documento | Propósito | Cuándo leerlo |
+|-----------|-----------|---------------|
+| `AGENTS.md` | Stack, convenciones, UI, calidad, reglas | ✅ Siempre — primera lectura |
+| `docs/AI_CONTEXT.md` | Memoria extendida del proyecto | ✅ Siempre — segunda lectura |
+| `docs/FRAMEWORK.md` | Manual completo: anotaciones, CLI, MCP | 🔍 Bajo demanda |
+| `docs/OPL_ACADEMIC_ISSUES.md` | Problemas del sistema de enseñanza | 🔍 Si tocas el módulo académico |
+| `docs/EMBEDDINGS.md` | Sistema de embeddings vectoriales | 🔍 Si tocas búsqueda semántica |
+| `.opencode/work-context/SESSION.json` | Estado actual de la sesión | 🔍 Para restaurar contexto |
+| `.opencode/work-context/LOG.json` | Bitácora de acciones | 🔍 Para auditoría |
+| `prompt-lang.json` | Configuración del proyecto | 🔍 Si necesitas ver config |
+
+---
+
+## ⚡ Comandos Rápidos para la IA
+
+```bash
+# Conocer el proyecto
+npx openprompt-lang context                     # Vista general
+npx openprompt-lang validate                    # Validar anotaciones
+npx openprompt-lang analyze .                   # Auditoría completa
+
+# Búsqueda de conocimiento
+opl index                                       # Navegar conocimiento
+opl search "término" --mode hybrid              # Búsqueda híbrida
+opl read <dominio>/<id> --chapter <n>           # Leer contenido
+
+# Evaluación del proyecto
+opl assess                                      # Production Readiness Assessment
+opl assess --verbose                            # Con detalle de 7 dimensiones
+
+# Sistema de enseñanza
+opl teach progress                              # Progreso de aprendizaje
+opl teach study <concepto>                      # Estudiar un concepto
+opl teach assess <concepto>                     # Evaluar nivel
+
+# Embeddings (si aplica)
+opl embeddings status                           # Estado del índice vectorial
+opl search "término" --mode vector              # Búsqueda semántica
+```
+
+---
+
+## 📝 Notas de la Sesión Actual
+
+```
+Espacio para que la IA o el usuario dejen notas sobre la sesión actual.
+```
+
+---
+
+*Documento generado automáticamente por `opl init`.*
+*Versión: 1.0.0*

package/docs/OPL_ACADEMIC_ISSUES.md

@@ -0,0 +1,158 @@
+# 🎓 OPL Academic — Bitácora de Problemas
+
+> Documento para registrar problemas, fricciones y errores detectados en el sistema de enseñanza (Teaching System) de openPrompt-Lang.
+> Cada entrada documenta: síntoma, causa raíz, impacto, solución propuesta y estado.
+
+---
+
+## 📋 Índice de Problemas
+
+| # | Fecha | Título | Severidad | Estado |
+|---|-------|--------|-----------|--------|
+| 1 | 2026-05-24 | Onboarding IA en proyecto existente | 🔴 Alta | Abierto |
+| 2 | 2026-05-24 | `opl rebuild` no detecta OPL automáticamente | 🟡 Media | Abierto |
+| 3 | 2026-05-24 | Falta documento post-init para IA | 🔴 Alta | Abierto |
+
+---
+
+## 🐛 Problemas Reportados
+
+### P-001: Onboarding IA en proyecto existente
+
+| Campo | Valor |
+|-------|-------|
+| **Fecha** | 2026-05-24 |
+| **Reportado por** | usuario |
+| **Severidad** | 🔴 Alta |
+| **Módulo** | Academic — Init / Onboarding |
+| **Estado** | 🔴 Abierto |
+
+**Síntoma:**
+Al iniciar una sesión con IA en un proyecto existente que ya tiene elementos de OPL, la IA no sabe qué hacer. No hay un punto de entrada claro que le diga "esto ya tiene OPL, aquí está el estado actual, continúa desde aquí".
+
+**Causa raíz:**
+No existe un documento de onboarding generado automáticamente que la IA pueda leer al inicio de cada sesión para restaurar contexto.
+
+**Impacto:**
+- La IA pierde ~15 minutos regenerando contexto cada sesión
+- Toma decisiones inconsistentes porque no conoce el estado real del proyecto
+- El usuario tiene que re-explicar manualmente lo que ya se hizo
+
+**Solución propuesta:**
+- Crear `docs/ONBOARDING_WORKFLOW.md` — documento canónico que la IA lee al iniciar
+- Integrar `opl init` para que genere este documento automáticamente
+- Dos versiones: `INICIAR_NUEVO.md` (proyecto nuevo) e `INICIAR_EXISTENTE.md` (proyecto en curso)
+
+**Referencias:**
+- `erroresDeFlujo.md` (línea 2)
+- Sprint embeddings → TICKET-011 (propuesto)
+
+---
+
+### P-002: `opl rebuild` no detecta OPL automáticamente
+
+| Campo | Valor |
+|-------|-------|
+| **Fecha** | 2026-05-24 |
+| **Reportado por** | usuario |
+| **Severidad** | 🟡 Media |
+| **Módulo** | CLI — rebuild |
+| **Estado** | 🟡 Abierto |
+
+**Síntoma:**
+`opl rebuild` falla o funciona incorrectamente cuando los elementos de OPL no están presentes o no son detectables automáticamente.
+
+**Causa raíz:**
+El comando `rebuild` asume cierta estructura pre-existente en lugar de ser autosuficiente.
+
+**Solución propuesta:**
+Hacer que `rebuild` funciones en dos modos:
+1. **Con detección**: Si encuentra elementos OPL, los respeta y reconstruye
+2. **Sin detección**: Si no encuentra nada, crea la estructura desde cero con defaults inteligentes
+
+**Referencias:**
+- `erroresDeFlujo.md` (línea 4)
+
+---
+
+### P-003: Falta documento post-init para IA
+
+| Campo | Valor |
+|-------|-------|
+| **Fecha** | 2026-05-24 |
+| **Reportado por** | usuario |
+| **Severidad** | 🔴 Alta |
+| **Módulo** | CLI — init |
+| **Estado** | 🔴 Abierto |
+
+**Síntoma:**
+Después de ejecutar `opl init`, no se genera ningún documento que la IA pueda usar para entender el contexto del proyecto. La IA llega "en frío" a cada sesión.
+
+**Causa raíz:**
+`opl init` configura el proyecto (crea prompt-lang.json, AGENTS.md, etc.) pero no genera un punto de entrada específico para la IA que le diga "esto es lo que hay, esto es lo que falta, continúa".
+
+**Solución propuesta:**
+Que `opl init` genere automáticamente:
+- `INICIAR_NUEVO.md` si es proyecto nuevo
+- `INICIAR_EXISTENTE.md` si es proyecto existente con OPL
+
+Estos documentos deben incluir:
+- Stack detectado
+- Estado de la configuración OPL
+- Próximos pasos recomendados
+- Enlace a `AGENTS.md` y `docs/AI_CONTEXT.md`
+
+**Referencias:**
+- `erroresDeFlujo.md` (línea 6)
+- `docs/ONBOARDING_WORKFLOW.md`
+
+---
+
+## 📊 Estadísticas
+
+| Métrica | Valor |
+|---------|-------|
+| Total problemas | 3 |
+| Severidad Alta | 2 |
+| Severidad Media | 1 |
+| Severidad Baja | 0 |
+| Abiertos | 3 |
+| En Progreso | 0 |
+| Resueltos | 0 |
+
+---
+
+## 📝 Cómo Reportar un Problema Nuevo
+
+Usa esta plantilla al añadir una nueva entrada:
+
+```markdown
+### P-XXX: Título descriptivo
+
+| Campo | Valor |
+|-------|-------|
+| **Fecha** | YYYY-MM-DD |
+| **Reportado por** | — |
+| **Severidad** | 🔴 Alta / 🟡 Media / 🟢 Baja |
+| **Módulo** | — |
+| **Estado** | 🔴 Abierto |
+
+**Síntoma:**
+_¿Qué ocurre exactamente?_
+
+**Causa raíz:**
+_¿Por qué ocurre?_
+
+**Impacto:**
+_¿A quién afecta y cómo?_
+
+**Solución propuesta:**
+_¿Cómo se arreglaría?_
+
+**Referencias:**
+- _enlaces a código, docs, commits_
+```
+
+---
+
+*Última actualización: 2026-05-24*