mcp-efficiency-engine 0.1.0

package/optimization/examples/sla-query.md

@@ -0,0 +1,25 @@
+# Example: SLA Query
+
+## Input
+
+Que dice el SLA.
+
+## Ruta esperada
+
+- `agent`: `rag-azure`
+- `engine`: `Azure RAG Builder`
+- `token_saver_profile`: `evidence-first`
+- `caveman_profile`: `evidence-first` o `lite`
+
+## Validacion rapida
+
+```powershell
+py -3 .\scripts\intake\resolve-routing.py --input "Que dice el SLA sobre incidencias criticas" --intent knowledge-grounded --domain azure-rag --source-type corporate-docs --capability policy-lookup
+```
+
+## Checks
+
+1. `grounded=true`
+1. `sources` no vacio
+1. `prompt.exists=true`
+

package/optimization/optimization-routing.md

@@ -0,0 +1,30 @@
+# Optimization Routing — Always On
+
+## Regla global
+
+Token Saver y Caveman están siempre activos.
+
+Memory MCP y Learning son transversales (always-on), pero la eleccion de engine es propiedad del routing segun intencion/contexto.
+
+## Perfil por tipo de tarea
+
+| Tarea | Token Saver | Caveman |
+| --- | --- | --- |
+| Debug / bug / CLI | strict | full |
+| Refactor | strict | full/lite |
+| Legacy impact | balanced | lite |
+| Arquitectura | balanced | lite |
+| DBA / SQL | strict | full/lite |
+| RAG local | balanced | lite |
+| Azure RAG corporativo | evidence-first | evidence-first |
+| Formación | balanced | didactic-lite |
+| Community content | balanced | lite |
+| Snapshot | strict | lite |
+
+## Prioridad
+
+```txt
+Si requiere fuentes -> evidence-first.
+Si requiere código -> strict.
+Si requiere enseñanza -> didactic-lite.
+```

package/optimization/policies/response-style.policy.md

@@ -0,0 +1,45 @@
+# Response Style Policy — Caveman Always On
+
+## Global
+
+Caveman nunca se desactiva completamente. Cambia de intensidad.
+
+Niveles permitidos:
+
+- `full`
+- `lite`
+- `evidence-first`
+- `didactic-lite`
+
+## Default
+
+```txt
+Resumen corto
+Acción concreta
+Validación
+Riesgo/gap
+```
+
+## Didactic Lite
+
+Para formación/documentación:
+
+- más explicación,
+- ejemplos,
+- estructura clara,
+- sin relleno.
+
+## Evidence-first
+
+Para Azure RAG:
+
+- respuesta breve,
+- fuentes preservadas,
+- gaps explícitos.
+
+## Escalado de estilo
+
+1. Default: `lite`.
+1. Debug/bug-fix: `full`.
+1. Azure RAG/contratos: `evidence-first`.
+1. Formacion: `didactic-lite`.

package/optimization/policies/token-budget.policy.md

@@ -0,0 +1,28 @@
+# Token Budget Policy — Always On
+
+## Global
+
+Token Saver nunca se desactiva.
+
+## Reglas
+
+- Consultar primero índices/grafos/manifests.
+- No leer ficheros completos salvo necesidad.
+- No recuperar más chunks de los necesarios.
+- No combinar motores sin justificación.
+- No generar snapshots globales sin scope.
+- No perder fuentes si hay grounding.
+
+## Señales de cumplimiento
+
+- Uso de indice/grafo antes de lecturas completas.
+- Tool calls acotadas al minimo necesario.
+- Ausencia de retrieval duplicado.
+
+## Señales de fallo
+
+- "leer todo el repo" sin plan por fases.
+- Mezcla de motores sin justificacion.
+- Respuesta sin fuentes en consultas con grounding.
+
+Si una respuesta requiere "mirar todo", primero generar plan de exploracion por fases.

package/optimization/profiles/always-on.profile.md

@@ -0,0 +1,19 @@
+# Always-On Profile
+
+Perfil por defecto para todo el sistema.
+
+```yaml
+token_saver: always_on
+caveman: always_on
+routing: corporate
+fallback: explicit
+grounding: preserve_required_sources
+verbosity: concise_by_default
+```
+
+## Intensidad dinámica
+
+- Debug: strict + full.
+- RAG enterprise: evidence-first + lite.
+- Formación: balanced + didactic-lite.
+- Arquitectura: balanced + structured-lite.

package/optimization/profiles/architecture.profile.md

@@ -0,0 +1,20 @@
+# Architecture Profile
+
+Perfil para analisis de arquitectura y diseño.
+
+## Configuracion
+
+```yaml
+token_saver: always_on
+token_saver_profile: balanced
+caveman: always_on
+caveman_profile: lite
+grounding: preserve_required_sources
+structure: high
+```
+
+## Reglas
+
+1. Priorizar claridad estructural sobre brevedad extrema.
+1. Mantener respuestas directas sin perder contexto tecnico.
+1. Si se requieren fuentes, preservar evidencia.

package/optimization/profiles/debug.profile.md

@@ -0,0 +1,20 @@
+# Debug Profile
+
+Perfil para bug-fix, troubleshooting y loops de validacion rapidos.
+
+## Configuracion
+
+```yaml
+token_saver: always_on
+token_saver_profile: strict
+caveman: always_on
+caveman_profile: full
+grounding: on_demand
+focus: root-cause-first
+```
+
+## Reglas
+
+1. Ir directo a causa -> accion -> validacion.
+1. Evitar lecturas masivas de archivos completos.
+1. Solo incluir fuentes cuando el caso lo exija.

package/optimization/profiles/enterprise-rag.profile.md

@@ -0,0 +1,20 @@
+# Enterprise RAG Profile
+
+Perfil para consultas documentales corporativas con grounding obligatorio.
+
+## Configuracion
+
+```yaml
+token_saver: always_on
+token_saver_profile: evidence-first
+caveman: always_on
+caveman_profile: evidence-first
+grounding: mandatory
+citations: required
+```
+
+## Reglas
+
+1. Nunca responder sin fuentes cuando el caso pide evidencia.
+1. Si faltan fuentes, declarar gap explicitamente.
+1. Si hay impacto alto o fallback, HITL debe activarse.

package/optimization/profiles/training.profile.md

@@ -0,0 +1,20 @@
+# Training Profile
+
+Perfil para onboarding, formacion y material didactico.
+
+## Configuracion
+
+```yaml
+token_saver: always_on
+token_saver_profile: didactic
+caveman: always_on
+caveman_profile: didactic-lite
+verbosity: expanded
+examples: required
+```
+
+## Reglas
+
+1. Mantener explicacion pedagogica, sin relleno.
+1. Caveman no se desactiva: se suaviza a `didactic-lite`.
+1. Preservar fuentes cuando la explicacion las requiera.

package/optimization/token-saver.md

@@ -0,0 +1,58 @@
+# Token Saver
+
+## Definición
+
+Token Saver es la política de optimización de contexto, coste y retrieval.
+
+En este repo también se expone como runtime MCP local vía `token-saver-mcp`.
+
+```txt
+Token Saver = infra / data layer
+```
+
+## Objetivo
+
+Reducir:
+
+- ficheros leídos,
+- chunks recuperados,
+- tool calls,
+- tokens inútiles,
+- contexto duplicado.
+
+## Reglas generales
+
+1. Consultar primero grafo/índice, no ficheros completos.
+2. Preferir símbolos, call paths, snippets y nodos concretos.
+3. Limitar top-k en RAG enterprise.
+4. Evitar combinar motores salvo caso mixto justificado.
+5. Usar Repomix solo para snapshots con scope claro.
+6. Declarar gaps en vez de recuperar “todo”.
+
+## Por motor
+
+### CodeGraph
+
+- Preguntar por símbolo, callers, callees, endpoint o blast radius.
+- Evitar leer archivos completos.
+
+### GitNexus
+
+- Usar para impacto multi-repo o legacy.
+- Pedir flows o dependencias concretas.
+
+### Graphify
+
+- Consultar `graph.json` o `GRAPH_REPORT.md` por tema/nodo.
+- No cargar todo el grafo en conversación.
+
+### Azure RAG Builder
+
+- Recuperar documentos reales con top-k limitado.
+- Pedir citas/fuentes.
+- No usar para código vivo.
+
+### Repomix
+
+- Scope limitado.
+- Ignorar `.env`, builds, node_modules, graphify-out y binarios.

package/orchestrator/corporate-routing.md

@@ -0,0 +1,51 @@
+# Corporate Routing
+
+## Objetivo
+
+Definir reglas corporativas para seleccionar agente y motor principal por tarea sin mezclar engines de forma innecesaria.
+
+## Mapa base
+
+```txt
+Codigo repo unico -> CodeGraph
+Codigo legacy/multi-repo -> GitNexus
+Docs tecnicas/locales -> Graphify
+Docs corporativos reales -> Azure RAG Builder
+Snapshot/export -> Repomix
+```
+
+## Regla de motor unico
+
+1. Seleccionar un motor principal por evento.
+2. Solo en caso mixto justificar apoyo secundario en `notes`.
+3. Si no hay evidencia suficiente, declarar gap y no inventar.
+
+## Caso mixto permitido
+
+```txt
+"Explicame auth y dame documentos reales"
+-> Graphify para explicacion local
+-> Azure RAG Builder para fuentes reales
+```
+
+## Hook Always-On (obligatorio)
+
+Despues de elegir agente/motor, aplicar optimizacion transversal:
+
+```txt
+1. Detectar intencion
+2. Detectar fuente
+3. Elegir agente/motor
+4. Aplicar Token Saver
+5. Aplicar Caveman
+6. Aplicar Memory + Learning
+7. Evaluar HITL
+8. Responder / actuar
+9. Registrar evento
+```
+
+## Validacion minima
+
+1. `prompt.exists=true`
+2. `agent` y `engine` coherentes con dominio/capability
+3. `hitl.required=true` en rutas de alto impacto

package/orchestrator/decision-matrix.md

@@ -0,0 +1,33 @@
+# Decision Matrix
+
+Matriz de decision rapida para resolver agente y motor por tipo de entrada.
+
+| Entrada dominante | Dominio | Agente esperado | Motor esperado | Criteria clave |
+| --- | --- | --- | --- | --- |
+| Codigo repo unico | dev | backend | CodeGraph | symbol/callpath/blast radius |
+| Codigo frontend repo unico | frontend | frontend-agent | CodeGraph | componentes/rutas/estado/UI impact |
+| Codigo legacy o multi-repo | legacy | legacy | GitNexus | impacto/dependencias/fallback controlado |
+| Guias UX/UI y design intent | ux-ui | ux-ui | Graphify | patrones UI/reutilizacion/consistencia |
+| Documentacion tecnica local | dba/iot/rag-local | dba / iot / rag-local | Graphify | nodos/relaciones/manifest |
+| Documentacion corporativa | azure-rag | rag-azure | Azure RAG Builder | grounded=true y fuentes |
+| Snapshot/export contexto | snapshot | snapshot | Repomix | scope acotado |
+
+## Frontera frontend vs ux-ui
+
+1. `frontend`: cambios en codigo UI ejecutable (componentes, rutas, estado, handlers, render).
+2. `ux-ui`: auditoria y gobierno de calidad UX/UI (accesibilidad, consistencia, design system, design intent).
+3. Si la entrada es `source_type=technical-docs` y hay ambiguedad, resolver hacia `ux-ui`.
+4. Si la entrada es `source_type=code` con implementacion/fix/refactor UI, resolver hacia `frontend`.
+
+## Regla de desempate
+
+1. Capability exacta solicitada.
+2. Capability por dominio en intake v2.
+3. Default de dominio.
+
+## Condiciones de bloqueo
+
+1. Repo no aprobado -> no enrutar por capability.
+2. Dependencia no resuelta -> fallback de dominio.
+3. Accion destructiva -> HITL bloqueante.
+

package/orchestrator/fallback.md

@@ -0,0 +1,29 @@
+# Fallback Strategy
+
+Fallback: Graphify -> Azure RAG si faltan docs reales; Azure RAG -> Graphify si falta contexto tecnico; CodeGraph <-> GitNexus segun scope; si no hay fuente, gap.
+
+## Triggers
+
+1. Capability no disponible.
+2. Dependencias no resueltas.
+3. Fuente insuficiente para grounding.
+4. Ambiguedad de scope (repo unico vs multi-repo).
+
+## Reglas de degradacion
+
+1. `capability unavailable` -> fallback a dominio.
+2. `dependency unresolved` -> fallback a dominio + warning.
+3. `no sources` en consulta con grounding -> `grounded=false` + gap explicito.
+4. Si el fallback impacta ruta de riesgo -> HITL obligatorio.
+
+## Escalado
+
+1. Primer fallback: continuar con motor alternativo valido.
+2. Fallback repetido del mismo patron: registrar learning y abrir ajuste de routing.
+3. Fallback en accion de alto impacto: bloquear hasta confirmacion humana.
+
+## Validacion
+
+1. `fallback=true` solo cuando aplica razon valida.
+2. `notes` debe incluir causa de fallback.
+3. Eventos de fallback visibles en `observability/logs/routing-decisions.jsonl`.

package/orchestrator/repo-routing.md

@@ -0,0 +1,58 @@
+# Repo Routing
+
+Repo Routing base: dba->Graphify, iot->Graphify+GitNexus/CodeGraph, azure-rag->Azure RAG Builder, dev->CodeGraph, frontend->CodeGraph, legacy->GitNexus, ux-ui->Graphify.
+
+## Routing por capacidades (v2)
+
+Orden de decisión:
+
+1. Capability exacta solicitada
+2. Capability por dominio desde índice generado
+3. Default de dominio
+
+Fuente de verdad:
+
+- `repo-registry/repos.yml` (approval, dependencies, optional)
+- `repo-intake/generated/<slug>/context-manifests/manifest.json`
+- `repo-intake/generated/<slug>/capabilities/capability.json`
+
+Regla de alcance para proyectos locales:
+
+- Si el repositorio contiene proyectos en `projects/`, esos son el perimetro
+  canonico para trabajo especifico de proyecto dentro de esta plataforma.
+- Los artefactos, reportes y documentacion especificos de cada proyecto deben
+  quedar en `projects/<nombre-proyecto>/`.
+- Los analisis y reportes generados por MCP Efficiency Engine deben ir, por
+  defecto, a `projects/<nombre-proyecto>/analysis_mcpee/`.
+- El routing o los subagentes no deben promover escritura de artefactos
+  especificos de proyecto en la raiz del repo salvo que se trate de artefactos
+  globales de plataforma.
+
+Regla de primera pasada por capability o boost:
+
+- La primera pasada de analisis sobre una capability o boost nuevo debe usar
+  onboarding profundo antes de optimizar.
+- Debe resolver primero la fuente canonica en `repo-intake/generated/<slug>/`
+  y luego consumir la maxima evidencia relevante del proyecto: docs,
+  instrucciones, skills, prompts y agentes locales.
+- Si existen agentes o subagentes especializados para ese boost, deben usarse
+  cuando el entorno lo permita; si no, sus definiciones deben leerse y
+  aplicarse como contrato operativo.
+
+Reglas de bloqueo:
+
+- Repos no aprobados (`approval.status != approved`) no se enrutan.
+- Dependencias no resueltas bloquean capability y fuerzan fallback de dominio.
+- Repos opcionales ausentes (`optional: true`) no bloquean el sistema; generan warning.
+
+Política de degradación:
+
+- `capability unavailable` -> fallback a dominio (fallback=true en evento)
+- `dependency unresolved` -> fallback a dominio (fallback=true)
+- `repo not approved` -> fallback a dominio (fallback=true)
+
+Resolución operativa:
+
+```powershell
+python .\scripts\intake\resolve-routing.py --input "Analiza schema" --intent analysis --domain dba --source-type technical-docs --capability database-analysis
+```

package/orchestrator/router.md

@@ -0,0 +1,75 @@
+## Memory-first + Learning
+
+Pipeline actualizado:
+
+1. Detect intent
+2. Detect domain
+3. **Select memory (memory layer)**
+4. **Apply cross-memory reasoning if multi-domain**
+5. Route to agent
+6. Execute tool (if needed)
+7. Register feedback (learning layer)
+
+Clasifica intención y enruta a agente/motor según AGENTS.md y optimization-routing.md.
+
+## Contrato operativo de routing (implementado)
+
+Pipeline operativo:
+
+1. Detect intent
+2. Detect domain
+3. Select memory
+4. Route by capability (si existe) o por default de dominio
+5. Emitir evento estructurado JSON (observability)
+6. Registrar feedback
+
+Dependencia Memory y CodeGraph en flujo de código:
+
+1. Memory selecciona alcance y señales (repo-memory, routing-memory, code-memory)
+2. CodeGraph resuelve simbolos/callpaths para retrieval estructural
+3. codebase-memory conserva patrones y contexto persistente
+
+Requirements operativos (runtime):
+
+- MCP server activo: `codegraph` en `.vscode/mcp.json`
+- Comando disponible: `codegraph --version`
+- Repo inicializado: `codegraph status` debe reportar index up to date
+- Preflight recomendado: `.\scripts\setup\validate-context.ps1`
+
+Comando de resolución y emisión de evento:
+
+```powershell
+python .\scripts\intake\resolve-routing.py --input "Arregla bug de login" --intent bug-fix --domain dev --source-type code --capability dev-coding
+```
+
+Salida:
+
+- Evento append en `observability/logs/routing-decisions.jsonl`
+- Estructura validable contra `observability/logs.schema.json`
+
+Campos mínimos del evento:
+
+- `timestamp`
+- `input`
+- `intent`
+- `source_type`
+- `agent`
+- `engine`
+- `optimization_profile`
+- `fallback`
+- `grounded`
+- `sources`
+
+Extensiones always-on:
+
+- `optimization` (token saver + caveman)
+- `memory` (selección previa)
+- `learning` (feedback)
+
+## Production guardrails (anti-expectation drift)
+
+- Routing debe declarar un engine principal por evento.
+- Si el evento termina en fallback sin `repo` asociado, marcar `grounded=false`.
+- `requirements` se calculan por engine real elegido (no solo por source_type).
+- Cuando exista ruta mixta (por ejemplo IoT), declarar un engine principal y el resto como apoyo en `notes`.
+- Nunca asumir evidencia: si no hay `sources`, declarar gap.

package/orchestrator/wiki/__init__.py

@@ -0,0 +1,5 @@
+from .graph_consolidator import GraphConsolidator
+from .incremental_engine import IncrementalEngine
+from .plugin_manager import PluginManager
+
+__all__ = ["PluginManager", "IncrementalEngine", "GraphConsolidator"]