mcp-efficiency-engine 0.1.0

package/README.md

@@ -0,0 +1,385 @@
+<!-- markdownlint-disable MD013 -->
+
+# MCP Efficiency Engine
+
+Motor de orquestación para agentes MCP con routing por dominio, optimización always-on y contratos de intake JSON-first.
+
+## Objetivo
+
+Este repositorio centraliza:
+
+- Routing corporativo de intención -> agente -> motor.
+- Ingesta de repos "boost" (locales o GitHub) a capacidades consumibles.
+- Optimización operacional (`token-saver` + `caveman`) sin perder grounding.
+- Observabilidad de decisiones de routing, uso y aprendizaje continuo.
+
+## Arquitectura
+
+```mermaid
+flowchart LR
+  U[Input usuario] --> R[Router corporativo]
+  R --> A[Agente por dominio]
+  A --> O[Always-on optimization]
+  O --> E[Motor de conocimiento principal]
+  E --> X[Respuesta con fuentes + logs]
+
+  O --> TS[token-saver]
+  O --> CV[caveman-mode]
+
+  E --> CG[CodeGraph]
+  E --> GN[GitNexus]
+  E --> GF[Graphify]
+  E --> AZ[Azure RAG Builder]
+  E --> RP[Repomix]
+
+  X --> OBS[observability/logs]
+  X --> INT[repo-intake/generated]
+```
+
+## Flujos Operativos
+
+### Flujo AutoDocs (wiki-agent)
+
+Proyeccion incremental de conocimiento tecnico a Markdown:
+
+```powershell
+py -3 -m scripts.wiki.wiki_compiler
+```
+
+Artefactos de salida:
+
+- `autodocs/generated/unified-graph.json`
+- `autodocs/generated/validation-report.json`
+- `autodocs/site/`
+
+Automatizacion CI:
+
+- `.github/workflows/autodocs-sync.yml`
+
+### Flujo End-to-End De Routing
+
+```mermaid
+sequenceDiagram
+  participant U as Usuario
+  participant RT as Router
+  participant AG as Agente
+  participant OP as Optimization
+  participant EN as Engine
+  participant OB as Observability
+
+  U->>RT: input + intent
+  RT->>RT: resolve domain + capability
+  RT->>AG: asigna agente
+  AG->>OP: aplica token-saver + caveman
+  OP->>EN: consulta principal (CodeGraph/GitNexus/Graphify/Azure/Repomix)
+  EN-->>AG: contexto + evidencia
+  AG-->>U: respuesta grounded
+  AG->>OB: routing-decisions + métricas + feedback
+```
+
+### Flujo De Intake (Registry -> Capability)
+
+```mermaid
+flowchart TD
+  R[repo-registry/repos.yml] --> V[validate-repo-registry]
+  V --> I[repo-intake.py]
+  I --> S{type}
+  S -->|local| L[usar repo local]
+  S -->|github| G[clonar/refrescar cache]
+  L --> A[generar artifacts]
+  G --> A
+  A --> M[manifest.json]
+  A --> C[capability.json]
+  A --> AU[audit-log.jsonl]
+  A --> SU[SUMMARY.json]
+  SU --> OR[router consume capabilities]
+```
+
+### Flujo Diario Recomendado
+
+```mermaid
+flowchart LR
+  H[hi.ps1] --> W[trabajo diario]
+  W --> B[bye.ps1]
+  H --> HC[health checks + intake + evals]
+  B --> BR[refresh contexto + reportes + snapshot]
+```
+
+## Routing Base
+
+Contrato global en `AGENTS.md`:
+
+- `backend` -> `CodeGraph`
+- `frontend-agent` -> `CodeGraph`
+- `legacy` -> `GitNexus`
+- `dba` -> `Graphify`
+- `ux-ui` -> `Graphify`
+- `rag-local` -> `Graphify`
+- `rag-azure` -> `Azure RAG Builder`
+- `iot` -> `GitNexus/CodeGraph + Graphify`
+- `community-manager` -> `Graphify`
+- `snapshot` -> `Repomix`
+
+## Motores Y Herramientas
+
+### Motores Principales
+
+| Motor | Uso principal | Cuándo usarlo |
+|---|---|---|
+| CodeGraph | Código repo único, símbolos y call paths | bug/fix/refactor backend o frontend en un repo |
+| GitNexus | Impacto multi-repo, legacy, dependencias | migraciones legacy, análisis de blast radius, seguridad de cambio |
+| Graphify | Documentación técnica local y relaciones de conocimiento | dba, ux-ui, rag-local, análisis de docs estructurados |
+| Azure RAG Builder | Contexto corporativo y fuentes enterprise | contratos, políticas, evidencia corporativa |
+| Repomix | Snapshot/export de contexto | empaquetado de contexto y handoff portable |
+
+### Tooling Operativo Del Repo
+
+| Tooling | Rol en el sistema |
+|---|---|
+| token-saver-mcp | reducción de contexto y coste sin perder evidencia |
+| caveman-mode | simplificación de salida y disciplina de respuesta |
+| codebase-memory-mcp | memoria persistente para patrones y feedback |
+| scripts/intake/* | validación de registry, generación de capabilities y resolución de routing |
+| scripts/ops/hi.ps1, scripts/ops/bye.ps1 | ciclo operativo de inicio/cierre con checks y refresh |
+| observability/logs/* | trazabilidad de decisiones, métricas y aprendizaje |
+
+### Mapa Rápido Intent -> Motor
+
+```mermaid
+flowchart TB
+  I[Intent detectado] --> D{Dominio}
+  D -->|backend/frontend| CG[CodeGraph]
+  D -->|legacy| GN[GitNexus]
+  D -->|dba/ux-ui/rag-local| GF[Graphify]
+  D -->|azure-rag| AZ[Azure RAG Builder]
+  D -->|snapshot| RP[Repomix]
+```
+
+## Estructura Clave
+
+- `.github/agents/`: definición de agentes por dominio.
+- `.github/skills/`: skills ejecutables y reutilizables.
+- `.github/prompts/`: prompts de routing por caso.
+- `orchestrator/`: reglas corporativas y matriz de decisión.
+- `repo-registry/`: registro de boosts aprobados.
+- `repo-intake/`: generación de manifests/capabilities/audit.
+- `scripts/`: setup, intake, operaciones, contexto y learning.
+- `observability/`: esquemas, métricas y evaluaciones.
+- `projects/`: artefactos operativos por proyecto.
+
+## Quickstart (Windows)
+
+### 1) Setup inicial
+
+```powershell
+.\scripts\setup\setup-prerequisites.ps1
+```
+
+### Alternativa npm
+
+Si quieres dejarlo auto-instalable en cualquier proyecto, el paquete ahora scaffoldéa el engine en el proyecto host durante `npm install` y luego ejecuta el bootstrap allí mismo.
+
+Instalacion directa en un proyecto nuevo o existente:
+
+```powershell
+npm install mcp-efficiency-engine
+```
+
+Comportamiento esperado:
+
+- copia al proyecto host los artefactos canonicos del engine (`scripts`, `.github`, `.vscode`, `repo-intake`, `orchestrator`, `policies`, `observability`, `autodocs/schema`, `memory`, etc.)
+- instala motores y herramientas via bootstrap portable
+- si no existe `repo-registry/repos.yml`, pregunta por owner/prefix y si quieres registrar un repo inicial para intake
+- si no añades repos en ese momento, deja el registry plantilla listo para añadirlos despues y rerun de intake
+
+Tambien puedes relanzar la instalacion manualmente sobre el proyecto actual:
+
+```powershell
+npx mcp-efficiency-engine install
+npx mcp-efficiency-engine validate -PortableMode
+```
+
+Tambien puedes instalarlo globalmente y usar:
+
+```powershell
+npm install -g mcp-efficiency-engine
+mcpee install
+```
+
+### 2) Validación mínima
+
+```powershell
+.\scripts\setup\validate-context.ps1
+.\scripts\intake\run-repo-intake.cmd
+py -3 .\scripts\intake\run-routing-evals.py
+```
+
+### 3) Operación diaria
+
+```powershell
+.\scripts\ops\hi.ps1
+# ... trabajo ...
+.\scripts\ops\bye.ps1
+```
+
+Validación extendida recomendada:
+
+```powershell
+py -3 .\scripts\intake\agent-pipeline-preflight.py
+py -3 .\scripts\intake\validate-repo-registry.py --strict
+```
+
+## Flujo De Intake
+
+`repo-intake` soporta dos modos:
+
+- `type=local`: consume un repo existente en disco.
+- `type=github`: clona/refresca cache local y genera los mismos artefactos.
+
+Artefactos canónicos:
+
+- `repo-intake/generated/<slug>/context-manifests/manifest.json`
+- `repo-intake/generated/<slug>/capabilities/capability.json`
+- `repo-intake/generated/<slug>/audit/audit-log.jsonl`
+- `repo-intake/generated/reports/SUMMARY.json`
+
+## Observabilidad
+
+Registros principales:
+
+- `observability/logs/routing-decisions.jsonl`
+- `observability/logs/iteration-metrics.jsonl`
+- `observability/logs/session/hi-*.json`
+- `observability/logs/session/bye-*.json`
+
+Eventos clave que conviene revisar:
+
+- decisiones de routing: agente, engine, fallback, grounding.
+- requirements runtime por ruta resuelta.
+- métricas por iteración (tokens/coste si se reportan).
+- feedback de learning para mejorar rutas futuras.
+
+### Loop De Observabilidad
+
+```mermaid
+flowchart LR
+  D[Decision de routing] --> L1[routing-decisions.jsonl]
+  E[Ejecución de tarea] --> L2[iteration-metrics.jsonl]
+  S[Inicio/Cierre sesión] --> L3[session hi/bye logs]
+  L1 --> EV[evals y scoring]
+  L2 --> EV
+  L3 --> EV
+  EV --> A[acciones de ajuste]
+  A --> D
+```
+
+## Optimización Always-On
+
+Pilares:
+
+- `token-saver`: reduce contexto sin romper grounding.
+- `caveman`: simplifica salida y reduce ruido operacional.
+- Selección de perfil por tipo de fuente (`code`, `technical-docs`, `corporate-docs`, `snapshot`).
+
+```mermaid
+flowchart TD
+  IN[Input] --> ST[Detectar source_type]
+  ST --> TS[token-saver profile]
+  ST --> CV[caveman profile]
+  TS --> EX[Engine execution]
+  CV --> EX
+  EX --> OUT[Output grounded + conciso]
+  OUT --> FB[feedback loop]
+```
+
+Referencias:
+
+- `optimization/ALWAYS_ON_OPTIMIZATION.md`
+- `optimization/token-saver.md`
+- `optimization/caveman-mode.md`
+
+## Policies Y Guardrails
+
+Políticas activas para gobierno, coste, seguridad y intake:
+
+- `policies/context-policy.md`
+- `policies/cost-policy.md`
+- `policies/security-policy.md`
+- `policies/repo-intake-policy.md`
+
+Reglas operativas clave:
+
+- No mezclar todos los motores a la vez.
+- Priorizar evidencia y fuentes cuando aplique.
+- En cambios de alto impacto, activar confirmación humana (HITL).
+- Mantener outputs de proyecto dentro de `projects/<nombre>/`.
+
+## Tooling Operativo
+
+Mapa de toolchain por fase:
+
+| Fase | Scripts/Tools |
+|---|---|
+| Setup | `scripts/setup/setup-prerequisites.ps1`, `scripts/setup/validate-context.ps1` |
+| Intake | `scripts/intake/validate-repo-registry.py`, `scripts/intake/repo-intake.py`, `scripts/intake/run-repo-intake.cmd` |
+| Routing/Evals | `scripts/intake/resolve-routing.py`, `scripts/intake/run-routing-evals.py`, `scripts/intake/agent-pipeline-preflight.py` |
+| Daily Ops | `scripts/ops/hi.ps1`, `scripts/ops/bye.ps1` |
+| Learning | `scripts/learning/*` |
+
+## Memory Y AutoLearning Loops
+
+### Memory-First
+
+La secuencia efectiva de ejecución sigue este orden:
+
+1. Selección de memoria relevante.
+2. Razonamiento con contexto persistido.
+3. Uso de herramientas si hace falta.
+4. Registro de aprendizaje.
+
+```mermaid
+flowchart LR
+  M[Memory selection] --> R[Reasoning]
+  R --> T[Tool call]
+  T --> F[Feedback]
+  F --> M
+```
+
+### AutoLearning
+
+```mermaid
+flowchart TD
+  X[Resultado de ejecución] --> RF[record-learning-feedback.py]
+  X --> RM[record-iteration-metrics.py]
+  RF --> LR[learning-loop-report.py]
+  RM --> LR
+  LR --> G[autolearning-gate.py]
+  G --> P[ajuste de patrones/routing]
+```
+
+Artefactos y docs relacionadas:
+
+- `autolearning/feedback-loop.md`
+- `memory/cross-memory-reasoning.md`
+- `scripts/learning/learning-loop-report.py`
+- `scripts/learning/autolearning-gate.py`
+
+## Documentación Recomendada
+
+- `FINAL_USAGE_GUIDE.md`
+- `ARCHITECTURE.md`
+- `AGENTS.md`
+- `autodocs/site/guides/01-onboarding.md`
+- `optimization/ALWAYS_ON_OPTIMIZATION.md`
+- `scripts/README.md`
+
+## Convenciones Operativas
+
+- JSON-first para artefactos operativos y reportes.
+- Cambios mínimos y seguros; evitar refactors fuera de scope.
+- Outputs específicos por proyecto dentro de `projects/<nombre>/`.
+- Diagnósticos MCP Efficiency Engine preferentemente en `projects/<nombre>/analysis_mcpee/`.
+
+## Licencia
+
+MIT. Ver `LICENSE`.

package/README_WIKI.md

@@ -0,0 +1,130 @@
+# AutoDocs Projection Engine
+
+AutoDocs es una capacidad nativa de `mcp-efficiency-engine`. Toma
+conocimiento estructurado de artefactos existentes en `repo-intake/generated/`,
+lo normaliza a un modelo wiki canonico, valida calidad estructural y proyecta
+una wiki interna en `autodocs/site/`.
+
+## Flujo operativo
+
+1. `scripts.wiki.wiki_compiler` carga variables de entorno de la sesion.
+2. Registra proveedores con `PluginManager` y ejecuta `gather_knowledge()`
+  de forma segura.
+3. `GraphConsolidator` transforma contratos tecnicos en `raw_nodes` y
+  `wiki_nodes`.
+4. `WikiValidator` valida schema, slugs, relaciones y navegacion.
+5. `IncrementalEngine` calcula nodos nuevos/modificados (dirty) y nodos
+  eliminados.
+6. Solo se renderizan paginas Markdown de nodos dirty; si un nodo desaparece,
+  su `.md` se elimina.
+7. Siempre se regeneran indices, manifests y reportes de validacion.
+8. Se escribe telemetria en:
+   - `observability/logs/iteration-metrics.jsonl`
+   - `observability/logs/routing-decisions.jsonl`
+
+## Ejecutar
+
+```powershell
+py -3 -m scripts.wiki.wiki_compiler
+```
+
+## Actualizacion automatica
+
+La actualizacion puede operar en dos modos:
+
+1. Manual local, ejecutando el comando de compilacion.
+2. Automatica en GitHub Actions con el workflow
+  `.github/workflows/autodocs-sync.yml`.
+
+El workflow recompila AutoDocs en cambios relevantes y publica actualizaciones
+de:
+
+- `autodocs/generated/unified-graph.json`
+- `autodocs/generated/validation-report.json`
+- `autodocs/generated/search-index.json`
+- `autodocs/generated/relations-index.json`
+- `autodocs/site/`
+
+Comportamiento por evento:
+
+1. `pull_request`: valida que los artefactos generados ya estan commiteados.
+2. `push` (main/develop): recompila y auto-commitea cambios si detecta drift.
+
+Nota: la telemetria de `observability/logs/*.jsonl` se escribe en ejecucion,
+pero el workflow no la commitea para evitar ruido.
+
+## Contrato de proveedor
+
+Todo proveedor debe devolver:
+
+```json
+{
+  "provider_id": "string",
+  "entities": [
+    {
+      "id": "string",
+      "type": "string",
+      "checksum": "string",
+      "raw_data": {},
+      "relations": [{ "target": "string", "type": "string" }]
+    }
+  ]
+}
+```
+
+## Como agregar nuevos proveedores
+
+1. Crea un archivo en `scripts/wiki/providers/`, por ejemplo `my_provider.py`.
+2. Hereda de `BaseWikiProvider`.
+3. Define `provider_id` y `gather_knowledge()`.
+4. Reusa artefactos existentes de `repo-intake/generated/` (no reescanear
+  codigo fuente).
+5. Registra el proveedor en `scripts/wiki/compiler_main.py`.
+
+Ejemplo minimo:
+
+```python
+from pathlib import Path
+from scripts.wiki.providers.base_provider import BaseWikiProvider
+
+
+class MyProvider(BaseWikiProvider):
+    provider_id = "my-provider"
+
+    def __init__(self, generated_root: Path) -> None:
+        super().__init__(generated_root)
+
+    def gather_knowledge(self):
+        return {
+            "provider_id": self.provider_id,
+            "entities": [
+                {
+                    "id": "example",
+                    "type": "custom",
+                    "checksum": self._checksum({"example": True}),
+                    "raw_data": {"example": True},
+                    "relations": []
+                }
+            ]
+        }
+```
+
+## Layout de salida
+
+- `autodocs/generated/unified-graph.json`
+- `autodocs/generated/validation-report.json`
+- `autodocs/generated/validation-report.md`
+- `autodocs/generated/search-index.json`
+- `autodocs/generated/relations-index.json`
+- `autodocs/generated/section-manifest.json`
+- `autodocs/site/index.md`
+- `autodocs/site/<section>/*.md`
+
+## Notas de diseno
+
+- Markdown es solo proyeccion visual.
+- El source of truth es el grafo JSON unificado de AutoDocs.
+- El pipeline es incremental para reducir costo y tiempo.
+- Errores de plugin no detienen la ejecucion global; se registran en
+  telemetria.
+- Errores de validacion si bloquean el estado final y hacen fallar CI.

package/autodocs/README.md

@@ -0,0 +1,22 @@
+# AutoDocs
+
+AutoDocs es la wiki interna nativa de `mcp-efficiency-engine`.
+
+## Estructura
+
+- `autodocs/generated/`: grafo unificado, reportes de validacion y manifests
+- `autodocs/schema/`: contratos de schema de la wiki
+- `autodocs/site/`: proyeccion Markdown navegable para personas
+
+## Comando canonico
+
+```powershell
+py -3 -m scripts.wiki.wiki_compiler
+```
+
+## Artefactos clave
+
+- `autodocs/generated/unified-graph.json`
+- `autodocs/generated/validation-report.json`
+- `autodocs/generated/search-index.json`
+- `autodocs/site/index.md`

package/autodocs/schema/wiki-node.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mcp-efficiency-engine.local/autodocs/wiki-node.schema.json",
+  "title": "AutoDocs Wiki Node",
+  "type": "object",
+  "required": [
+    "node_id",
+    "title",
+    "slug",
+    "kind",
+    "summary",
+    "source_refs",
+    "navigation"
+  ],
+  "properties": {
+    "node_id": { "type": "string" },
+    "title": { "type": "string", "minLength": 1 },
+    "slug": { "type": "string", "minLength": 1 },
+    "kind": {
+      "type": "string",
+      "enum": ["agent", "skill", "prompt", "policy", "project", "spec", "report", "capability"]
+    },
+    "summary": { "type": "string", "minLength": 1 },
+    "source_refs": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "relations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["target", "type"],
+        "properties": {
+          "target": { "type": "string" },
+          "type": { "type": "string" }
+        }
+      }
+    },
+    "navigation": {
+      "type": "object",
+      "required": ["section"],
+      "properties": {
+        "section": {
+          "type": "string",
+          "enum": ["capabilities", "agents", "skills", "routing", "projects", "policies", "specs", "observability", "reports", "misc"]
+        },
+        "weight": { "type": "number" },
+        "parent": { "type": "string" },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/autolearning/feedback-loop.md

@@ -0,0 +1,90 @@
+# AutoLearning Loop
+
+## Objetivo
+
+Cerrar el ciclo de mejora continua para que routing, memoria y optimizacion mejoren con evidencia real de ejecucion (no por intuicion).
+
+Nombre operativo: AutoLearning (antes Learning Loop).
+
+## Ciclo operativo
+
+1. Input
+1. Routing decision
+1. Memory usage
+1. Result
+1. Metrics
+1. Improve next execution
+
+## Fuente de verdad actual
+
+- Eventos por ejecucion: observability/logs/routing-decisions.jsonl
+- Campos clave de learning por evento:
+  - learning.used_pattern
+  - learning.success
+  - learning.fallback
+  - learning.confidence
+- Campos de calidad de routing:
+  - fallback
+  - grounded
+  - sources
+  - notes
+
+## Regla de evaluacion
+
+1. Si sube fallback_rate por patron, revisar capability mapping y defaults.
+1. Si baja grounded_rate, revisar fuentes/manifests y cobertura de repos aprobados.
+1. Si confidence media cae, revisar combinacion intent+domain y requirements por engine.
+1. Registrar cambios y revalidar con routing evals antes de merge.
+
+## Automatizacion
+
+- Script: scripts/learning/learning-loop-report.py
+- Script de confirmacion real: scripts/learning/record-learning-feedback.py
+- scripts/intake/run-routing-evals.py confirma automaticamente (source=ci) los eventos de routing que pasan en eval
+- Gate CI: scripts/learning/autolearning-gate.py
+- Salidas:
+  - observability/evals/learning-loop-report.json
+  - observability/evals/learning-loop-report.md
+- Ejecucion recomendada: al cierre (bye.ps1) y en CI si se endurece governance.
+
+## Confirmacion real (post-ejecucion)
+
+El evento de routing nace con `learning.success = null` y `outcome_status = pending`.
+
+Cuando existe resultado real (humano, CI o runtime), confirmar con:
+
+```powershell
+py -3 .\scripts\learning\record-learning-feedback.py --success true --source ci --confidence 0.95 --notes "tests green"
+```
+
+Opcionalmente se puede pasar `--event-id` para fijar un evento concreto.
+
+## Coste y valor por iteracion
+
+Registrar tokens/coste/modelo/herramientas para una iteracion:
+
+```powershell
+py -3 .\scripts\learning\record-iteration-metrics.py --model "GPT-5.3-Codex" --input-tokens 1200 --output-tokens 450 --local-tools 3 --remote-tools 0 --estimated-cost-usd 0.013
+```
+
+Generar reporte de valor operativo:
+
+```powershell
+py -3 .\scripts\learning\iteration-value-report.py
+```
+
+Salidas:
+
+- observability/evals/iteration-value-report.json
+- observability/evals/iteration-value-report.md
+
+Para contrastar planes, creditos incluidos o precio oficial de Copilot cuando sea necesario:
+
+- https://github.com/features/copilot/plans?ref_cta=View+pricing+and+plans&ref_loc=hero&ref_page=%2Ffeatures_copilot_copilot_business&plans=business
+
+## Criterios minimos de salud
+
+1. fallback_rate <= 0.20 (global) salvo dominios de baja cobertura declarados.
+1. grounded_rate >= 0.80 global.
+1. confidence_avg >= 0.80 global.
+1. patrones con peor calidad deben quedar en backlog con accion correctiva.