mcp-efficiency-engine 0.1.0

package/policies/context-policy.md

@@ -0,0 +1,25 @@
+# Context Policy
+
+## Objetivo
+
+Usar solo el contexto necesario para resolver la tarea con evidencia trazable y sin retrieval redundante.
+
+## Reglas
+
+1. Recuperar primero artefactos estructurados (manifest, grafo, index) antes de lecturas masivas.
+2. Limitar tool calls y chunks al minimo necesario para validar una decision.
+3. Mantener trazabilidad: cuando aplique grounding, citar fuente concreta.
+4. No mezclar motores equivalentes para la misma pregunta salvo justificacion explicita.
+5. Si falta evidencia, declarar gap en lugar de inventar contexto.
+
+## Criterios de validacion
+
+1. El flujo muestra seleccion de una sola fuente primaria por tarea.
+2. Las respuestas con grounding incluyen fuente o ruta verificable.
+3. No hay lectura completa del repo sin plan por fases.
+
+## Senales de fallo
+
+1. Tool thrashing sin mejora de evidencia.
+2. Mezcla de motores sin motivo.
+3. Respuesta con afirmaciones no trazables.

package/policies/cost-policy.md

@@ -0,0 +1,25 @@
+# Cost Policy
+
+## Objetivo
+
+Minimizar coste operativo de tool calls y retrieval sin perder calidad ni trazabilidad.
+
+## Reglas
+
+1. No usar Azure RAG para codigo local del repositorio.
+2. Evitar tool thrashing: cada llamada debe aportar evidencia nueva.
+3. Preferir consultas puntuales a indices/grafos frente a scans globales.
+4. Evitar snapshots globales si el scope real es parcial.
+5. Reutilizar artefactos ya generados antes de relanzar pipelines.
+
+## Criterios de validacion
+
+1. Numero de llamadas acotado al objetivo real.
+2. Sin duplicacion de retrieval para la misma pregunta.
+3. Sin uso de motor premium cuando existe alternativa local valida.
+
+## Senales de fallo
+
+1. Llamadas repetidas con mismo resultado.
+2. Recuperar contexto no utilizado en la respuesta final.
+3. Escalar a motor externo sin razon de negocio o grounding.

package/policies/repo-intake-policy.md

@@ -0,0 +1,36 @@
+# Repo Intake Policy
+
+## Objetivo
+
+Incorporar repos al ecosistema sin clonar dentro de este repositorio y con metadata valida para routing.
+
+## Reglas
+
+1. No copiar repos terceros dentro de este repo.
+2. Registrar cada repo en [repo-registry/repos.yml](repo-registry/repos.yml).
+3. Ejecutar intake para extraer capacidades, dependencias y manifiestos.
+4. Mantener contrato de naming y reglas de governance del registry.
+5. Tratar repos opcionales como warning, no como bloqueo, si asi esta definido.
+6. El trabajo especifico de proyectos gestionados dentro de este repositorio
+   debe vivir bajo `projects/`.
+7. Todo artefacto especifico de un proyecto debe guardarse en
+   `projects/<nombre-proyecto>/` y no en la raiz, salvo artefactos globales de
+   plataforma expresamente definidos.
+
+## Flujo minimo
+
+1. Registrar entrada en repos registry.
+2. Validar registry en modo estricto.
+3. Ejecutar intake y revisar artefactos generados.
+
+## Criterios de validacion
+
+1. Registry valido sin errores bloqueantes.
+2. Artefactos de intake presentes y legibles.
+3. Capacidades disponibles para routing y evaluacion.
+
+## Senales de fallo
+
+1. Repo fuera de registry.
+2. Intake sin artefactos o con metadata incompleta.
+3. Drift entre registry y capacidades detectadas.

package/policies/security-policy.md

@@ -0,0 +1,25 @@
+# Security Policy
+
+## Objetivo
+
+Evitar exposicion de informacion sensible en indexacion, memoria, logs y respuestas.
+
+## Reglas
+
+1. No indexar .env, secretos, tokens, certificados, claves privadas ni datos personales.
+2. No persistir secretos en memoria de usuario, sesion o repo.
+3. En caso de duda de sensibilidad, no almacenar y declarar gap.
+4. No ejecutar acciones destructivas o de alto impacto sin confirmacion humana.
+5. No incluir credenciales en ejemplos, comandos o artefactos.
+
+## Controles minimos
+
+1. Revisar entradas candidatas antes de indexar o cachear.
+2. Sanitizar salidas que puedan contener valores sensibles.
+3. Mantener trazabilidad de bloqueos por seguridad en logs operativos.
+
+## Senales de fallo
+
+1. Secretos visibles en texto plano.
+2. Datos sensibles en snapshots o indices.
+3. Respuesta final con credenciales o tokens reales.

package/repo-intake/README.md

@@ -0,0 +1,81 @@
+# Repo Intake
+
+Este modulo transforma repos registrados en capacidades consumibles por el routing.
+
+Soporta dos modos de origen:
+
+- `type: local`: usa un repo ya presente en disco.
+- `type: github`: materializa una copia cacheada local desde GitHub y genera los mismos artefactos de intake que el modo local.
+
+## Estructura
+
+- `templates/`: plantillas base (`agent`, `skill`, `context-manifest`).
+- `generated/reports/`: reportes JSON operativos.
+- `generated/<slug>/`: salida canonica JSON-first por repo (sin versionado).
+
+## Nota sobre carpetas vacias
+
+Si ves carpetas antiguas de layouts legacy, se pueden eliminar.
+La salida activa vive en `generated/<slug>/...` y `generated/reports/*.json`.
+
+## Flujo recomendado
+
+1. Validar registry: `pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\intake\validate-repo-registry.ps1 -Strict`
+2. Ejecutar intake: `.\scripts\intake\run-repo-intake.cmd`
+3. Revisar reportes: `repo-intake/generated/reports/`
+
+Registry modes:
+
+- `repo-registry/repos.yml`: modo `enterprise`, con repos reales y validacion estricta.
+- `repo-registry/repos.template.json`: modo `template`, portable, permite `repos: []` mientras se configura el ecosistema.
+
+Bootstrap recomendado para modo portable en Windows:
+
+```powershell
+.\scripts\intake\init-template-registry.cmd
+.\scripts\intake\run-repo-intake.cmd
+```
+
+Si el registry plantilla sigue vacio, el intake no falla: genera reportes con `0` repos y deja el sistema listo para completar `repo-registry/repos.yml` mas tarde.
+
+Al inicializar la plantilla, el script pide interactivamente:
+
+- `owner` del registry
+- prefijo de nombres de repo
+- si quieres crear una primera entrada de repo
+- y, si la creas, nombre, dominio y localizacion
+4. Consumir contratos planos: `repo-intake/generated/<slug>/`
+
+## Registry GitHub (uso real)
+
+Entrada minima para un repo GitHub en `repo-registry/repos.yml`:
+
+```json
+{
+	"name": "boost_backend_remote",
+	"domain": "backend",
+	"type": "github",
+	"repo_url": "https://github.com/your-org/your-repo.git",
+	"branch": "main",
+	"cache_location": ".cache/github-repos/boost_backend_remote",
+	"approval": {
+		"status": "approved",
+		"approved_by": "platform-team",
+		"approved_date": "2026-07-03",
+		"review_ticket": "PLATFORM-GH-001"
+	},
+	"dependencies": [],
+	"engines": {
+		"knowledge": "codegraph",
+		"execution": "none",
+		"snapshot": "repomix"
+	}
+}
+```
+
+Comportamiento operativo:
+
+- `validate-repo-registry.py --strict` exige `repo_url` valido y `git` disponible.
+- `repo-intake.py` clona o refresca el repo en `cache_location`.
+- El routing y los motores consumen los artefactos generados igual que con repos locales.
+- La cache local vive en `.cache/github-repos/` por defecto y no se debe commitear.

package/repo-intake/templates/agent.template.md

@@ -0,0 +1,4 @@
+# {{AGENT_NAME}}
+
+Dominio: {{DOMAIN}}
+Motor: {{PRIMARY_ENGINE}}

package/repo-intake/templates/context-manifest.template.md

@@ -0,0 +1,4 @@
+# Context Manifest — {{REPO_NAME}}
+
+Dominio: {{DOMAIN}}
+Ubicación: {{LOCATION}}

package/repo-intake/templates/skill.template.md

@@ -0,0 +1,3 @@
+# {{SKILL_NAME}}
+
+Dominio: {{DOMAIN}}

package/repo-registry/repos.schema.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mcp-first-enterprise/repo-registry/repos.schema.json",
+  "title": "Repo Registry Schema",
+  "description": "Schema for hybrid repo registry with local and GitHub-backed sources.",
+  "type": "object",
+  "required": ["repos"],
+  "properties": {
+    "registry_mode": {
+      "type": "string",
+      "enum": ["enterprise", "template"]
+    },
+    "schema_version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+$"
+    },
+    "governance": {
+      "type": "object",
+      "properties": {
+        "owner": { "type": "string", "minLength": 1 },
+        "approval_required": { "type": "boolean" },
+        "repo_name_prefix": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": true
+    },
+    "repos": {
+      "type": "array",
+      "minItems": 0,
+      "items": {
+        "type": "object",
+        "required": ["name", "domain", "type"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "domain": {
+            "type": "string",
+            "enum": ["backend", "frontend", "community-content", "legacy", "dba", "iot", "ux-ui", "azure-rag", "rag"]
+          },
+          "location": { "type": "string", "minLength": 1 },
+          "type": { "type": "string", "enum": ["local", "github"] },
+          "repo_url": { "type": "string", "minLength": 1 },
+          "branch": { "type": "string", "minLength": 1 },
+          "cache_location": { "type": "string", "minLength": 1 },
+          "optional": { "type": "boolean" },
+          "engines": {
+            "type": "object",
+            "properties": {
+              "knowledge": { "type": "string" },
+              "execution": { "type": "string" },
+              "snapshot": { "type": "string" }
+            },
+            "additionalProperties": true
+          },
+          "dependencies": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["ref"],
+              "properties": {
+                "ref": { "type": "string", "minLength": 1 }
+              },
+              "additionalProperties": true
+            }
+          },
+          "approval": {
+            "type": "object",
+            "properties": {
+              "status": { "type": "string", "enum": ["approved", "pending", "rejected"] },
+              "approved_by": { "type": "string" },
+              "approved_date": { "type": "string" },
+              "review_ticket": { "type": "string" }
+            },
+            "additionalProperties": true
+          }
+        },
+        "allOf": [
+          {
+            "if": {
+              "properties": {
+                "type": { "const": "local" }
+              }
+            },
+            "then": {
+              "required": ["location"]
+            }
+          },
+          {
+            "if": {
+              "properties": {
+                "type": { "const": "github" }
+              }
+            },
+            "then": {
+              "required": ["repo_url"]
+            }
+          }
+        ],
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/repo-registry/repos.template.json

@@ -0,0 +1,26 @@
+{
+  "registry_mode": "template",
+  "schema_version": "2.0",
+  "governance": {
+    "owner": "your-team",
+    "approval_required": false,
+    "repo_name_prefix": "your-prefix_"
+  },
+  "repos": [],
+  "repo_examples": {
+    "local": {
+      "name": "your-prefix_backend_local",
+      "domain": "backend",
+      "type": "local",
+      "location": "../your-backend-repo"
+    },
+    "github": {
+      "name": "your-prefix_backend_remote",
+      "domain": "backend",
+      "type": "github",
+      "repo_url": "https://github.com/your-org/your-repo.git",
+      "branch": "main",
+      "cache_location": ".cache/github-repos/your-prefix_backend_remote"
+    }
+  }
+}

package/requirements.txt

@@ -0,0 +1 @@
+graphifyy[mcp]

package/scripts/README.md

@@ -0,0 +1,109 @@
+# Scripts Index
+
+Indice operativo de scripts del repositorio. Objetivo: crecer sin caos, con un punto unico de entrada.
+
+## Estructura canonica (viva)
+
+- `scripts/setup/*`: bootstrap y validacion de entorno.
+- `scripts/intake/*`: registry, intake, routing y preflight.
+- `scripts/ops/*`: arranque y cierre diario.
+- `scripts/discovery/*`: descubrimiento y notas de proyecto.
+- `scripts/context/*`: construccion de contexto (Graphify/Repomix/Azure adapter).
+- `scripts/learning/*`: feedback, metricas y gates de aprendizaje.
+
+Todas las ejecuciones deben usar rutas canonicas por subcarpeta.
+
+## Convenciones
+
+- Preferir `cmd` wrappers en Windows cuando exista equivalente (`run-repo-intake.cmd`).
+- Scripts de verificacion y pipeline deben ser idempotentes.
+- Evitar rutas hardcodeadas fuera del repo.
+
+## Setup y bootstrap
+
+- `bootstrap-portable.ps1`: orquesta setup portable + validacion + init registry + intake.
+- `bootstrap-portable.cmd`: wrapper CMD unico recomendado en Windows para bootstrap portable completo.
+- `setup/setup-prerequisites.ps1`: instala y prepara dependencias base (MCP + tooling).
+- `setup/setup-codegraph.ps1`: setup de CodeGraph.
+- `setup/setup-gitnexus.ps1`: setup de GitNexus.
+- `setup/optimize-engines.ps1`: auditoria/optimizacion exhaustiva de motores MCP (CodeGraph, GitNexus, Graphify, Repomix).
+- `setup/start-gitnexus.ps1`: indexa si hace falta, levanta backend web y abre UI local.
+- `setup/setup-graphify.ps1`: setup de Graphify.
+- `setup/validate-context.ps1`: verificacion de prerequisitos locales.
+- `../tooling/tooling.manifest.json`: fuente de verdad de CLIs externos requeridos.
+
+## Repo intake y routing
+
+- `intake/validate-repo-registry.py`: valida `repo-registry/repos.yml` (strict opcional). Soporta `type=local` y `type=github`.
+- `intake/validate-repo-registry.ps1`: wrapper PowerShell de validacion del registry.
+- `intake/init-template-registry.ps1`: inicializa `repo-registry/repos.yml` desde la plantilla portable.
+- `intake/init-template-registry.cmd`: wrapper CMD recomendado en Windows para inicializar el registry plantilla.
+- `intake/repo-intake.py`: genera artefactos intake por repo. Para `type=github` materializa/actualiza una cache local y luego genera manifests/capabilities igual que para repos locales.
+- `intake/run-repo-intake.cmd`: wrapper recomendado en Windows para intake.
+- `intake/run-repo-intake.ps1`: wrapper PowerShell para intake.
+- `intake/resolve-routing.py`: resuelve ruta por capabilities/engine/fallback y puede registrar metricas de tokens por llamada con `--input-tokens --output-tokens`.
+- `intake/run-routing-evals.py`: ejecuta casos de prueba de routing.
+- `intake/agent-pipeline-preflight.py`: chequea integridad agente -> skills -> repos.
+
+## Operacion diaria
+
+- `ops/hi.ps1`: preflight de inicio (contexto, intake, routing, salud).
+- `ops/bye.ps1`: cierre con refreshes, reportes y retencion automatica de logs de sesion (`observability/logs/session`) con `RetentionDays=15` por defecto.
+
+## Descubrimiento y sincronizacion
+
+- `discovery/discover-boost-repos.py`: descubrimiento de repos boost.
+- `discovery/discover-boost-repos.cmd`: wrapper CMD para descubrimiento.
+- `discovery/refresh-project-notes.py`: refresca notas de proyecto desde observabilidad.
+
+## Contexto y snapshots
+
+- `context/build-graphify.ps1`: reconstruye salida de Graphify.
+- `context/build-repomix.ps1`: genera snapshot Repomix.
+- `context/azure-rag-mcp-adapter.py`: adaptador para flujo Azure RAG MCP.
+
+## Learning y observabilidad
+
+- `learning/record-learning-feedback.py`: registro de feedback de ejecucion.
+- `learning/record-iteration-metrics.py`: registro de metricas por iteracion.
+- `learning/ingest-copilot-session-usage.py`: ingesta best-effort de uso de tokens desde logs de sesion de VS Code Copilot hacia `iteration-metrics.jsonl` (incluye `copilot_credits` cuando el log lo expone).
+- `learning/chat-token-usage-report.py`: reporte agregado de tokens y costo en creditos solo de chat (`usage.source=copilot-session`) con salida JSON+Markdown. Soporta `--plan` (`free|pro|pro+|max|business|enterprise`) y `--seats` para calcular presupuesto mensual incluido y sobreconsumo. Referencia oficial de planes/precio cuando haga falta validar creditos incluidos: https://github.com/features/copilot/plans?ref_cta=View+pricing+and+plans&ref_loc=hero&ref_page=%2Ffeatures_copilot_copilot_business&plans=business
+- `learning/learning-loop-report.py`: reporte de aprendizaje continuo.
+- `learning/iteration-value-report.py`: reporte de valor por iteracion.
+- `learning/autolearning-gate.py`: gate automatizado de aprendizaje.
+
+## Flujos recomendados
+
+Setup inicial:
+
+```powershell
+.\scripts\bootstrap-portable.cmd
+.\scripts\setup\setup-prerequisites.ps1
+.\scripts\setup\validate-context.ps1
+.\scripts\setup\optimize-engines.ps1 -InstallMissing
+```
+
+Optimización profunda (skills + embeddings en GitNexus):
+
+```powershell
+.\scripts\setup\optimize-engines.ps1 -DeepGitNexus
+```
+
+Validacion operativa minima:
+
+```powershell
+pwsh -ExecutionPolicy Bypass -NoProfile -File .\scripts\setup\validate-context.ps1 -PortableMode
+.\scripts\intake\init-template-registry.cmd
+py -3 .\scripts\intake\validate-repo-registry.py --strict
+.\scripts\intake\run-repo-intake.cmd
+py -3 .\scripts\intake\agent-pipeline-preflight.py
+py -3 .\scripts\intake\run-routing-evals.py
+```
+
+Operacion diaria:
+
+```powershell
+.\scripts\ops\hi.ps1
+# ... trabajo ...
+.\scripts\ops\bye.ps1
+```

package/scripts/bootstrap-portable.cmd

@@ -0,0 +1,4 @@
+@echo off
+setlocal
+pwsh -NoProfile -ExecutionPolicy Bypass -File "%~dp0bootstrap-portable.ps1" %*
+exit /b %ERRORLEVEL%

package/scripts/bootstrap-portable.ps1

@@ -0,0 +1,90 @@
+param(
+  [switch]$ForceTemplateRegistry,
+  [switch]$SkipCodebaseMemory,
+  [switch]$SkipTokenSaver,
+  [switch]$SkipCodegraph,
+  [switch]$SkipGitnexus,
+  [switch]$SkipGraphify,
+  [switch]$SkipRepomix,
+  [string]$Owner,
+  [string]$RepoNamePrefix,
+  [string]$InitialRepoName,
+  [string]$InitialRepoDomain,
+  [string]$InitialRepoLocation,
+  [switch]$SkipInitialRepo
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path
+Set-Location $repoRoot
+
+$registryPath = Join-Path $repoRoot 'repo-registry\repos.yml'
+$summaryReportPath = Join-Path $repoRoot 'repo-intake\generated\reports\SUMMARY.json'
+$initRegistryArgs = @('.\scripts\intake\init-template-registry.ps1')
+if (-not [string]::IsNullOrWhiteSpace($Owner)) { $initRegistryArgs += @('-Owner', $Owner) }
+if (-not [string]::IsNullOrWhiteSpace($RepoNamePrefix)) { $initRegistryArgs += @('-RepoNamePrefix', $RepoNamePrefix) }
+if (-not [string]::IsNullOrWhiteSpace($InitialRepoName)) { $initRegistryArgs += @('-InitialRepoName', $InitialRepoName) }
+if (-not [string]::IsNullOrWhiteSpace($InitialRepoDomain)) { $initRegistryArgs += @('-InitialRepoDomain', $InitialRepoDomain) }
+if (-not [string]::IsNullOrWhiteSpace($InitialRepoLocation)) { $initRegistryArgs += @('-InitialRepoLocation', $InitialRepoLocation) }
+if ($SkipInitialRepo) { $initRegistryArgs += '-SkipInitialRepo' }
+
+Write-Host '== Portable bootstrap ==' 
+
+pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup\setup-prerequisites.ps1 `
+  -PortableMode `
+  -SkipCodebaseMemory:$SkipCodebaseMemory `
+  -SkipTokenSaver:$SkipTokenSaver `
+  -SkipCodegraph:$SkipCodegraph `
+  -SkipGitnexus:$SkipGitnexus `
+  -SkipGraphify:$SkipGraphify `
+  -SkipRepomix:$SkipRepomix
+if ($LASTEXITCODE -ne 0) {
+  throw 'Portable setup prerequisites failed.'
+}
+
+pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup\validate-context.ps1 -PortableMode
+if ($LASTEXITCODE -ne 0) {
+  throw 'Portable context validation failed.'
+}
+
+if (-not (Test-Path $registryPath)) {
+  Write-Host 'No repo registry found. Initializing portable template registry...'
+  pwsh -NoProfile -ExecutionPolicy Bypass -File @initRegistryArgs
+  if ($LASTEXITCODE -ne 0) {
+    throw 'Template registry initialization failed.'
+  }
+}
+elseif ($ForceTemplateRegistry) {
+  Write-Host 'Forcing template registry initialization...'
+  pwsh -NoProfile -ExecutionPolicy Bypass -File @($initRegistryArgs + '-Force')
+  if ($LASTEXITCODE -ne 0) {
+    throw 'Forced template registry initialization failed.'
+  }
+}
+else {
+  Write-Host 'Registry already exists. Reusing current repo-registry\repos.yml.'
+}
+
+pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\intake\run-repo-intake.ps1
+if ($LASTEXITCODE -ne 0) {
+  throw 'Repo intake failed during portable bootstrap.'
+}
+
+Write-Host ''
+Write-Host 'Portable bootstrap completed.'
+if (Test-Path $registryPath) {
+  $registry = Get-Content -Raw -Path $registryPath | ConvertFrom-Json -Depth 20
+  $registryMode = if (($registry.PSObject.Properties.Name -contains 'registry_mode') -and -not [string]::IsNullOrWhiteSpace([string]$registry.registry_mode)) { [string]$registry.registry_mode } else { 'enterprise' }
+  $repoCount = if (($registry.PSObject.Properties.Name -contains 'repos') -and $null -ne $registry.repos) { @($registry.repos).Count } else { 0 }
+  Write-Host "Registry summary: mode=$registryMode, repos=$repoCount"
+}
+if (Test-Path $summaryReportPath) {
+  $summary = Get-Content -Raw -Path $summaryReportPath | ConvertFrom-Json -Depth 20
+  Write-Host "Intake summary: generated for $($summary.repos_count) repos"
+}
+Write-Host 'Artifacts:'
+Write-Host '  - repo-intake/generated/reports/setup-validation.json'
+Write-Host '  - repo-intake/generated/reports/repo-registry-validation.json'
+Write-Host '  - repo-intake/generated/reports/SUMMARY.json'

package/scripts/context/azure-rag-mcp-adapter.py

@@ -0,0 +1 @@
+print("Placeholder adapter for RAG-Azure-Builder. Wire to CLI/API if needed.")

package/scripts/context/build-graphify.ps1

@@ -0,0 +1 @@
+graphify . --update

package/scripts/context/build-repomix.ps1

@@ -0,0 +1 @@
+npx repomix@latest --config context/repomix/repomix.config.json

package/scripts/discovery/discover-boost-repos.cmd

@@ -0,0 +1,4 @@
+@echo off
+setlocal
+python "%~dp0discover-boost-repos.py" %*
+exit /b %ERRORLEVEL%