@saulwade/swl-ses 1.6.3 → 1.6.6

package/scripts/mcp-telemetry.py

@@ -29,6 +29,14 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
+# Permitir importar mcp_config desde scripts/lib/ (consistente con
+# mcp-orchestrator.py:34 y mcp-pool-manager.py:35). Sin esto, el import
+# runtime dentro de MCPTelemetrySession.__aenter__ rompía con
+# ModuleNotFoundError al usarse desde un consumidor que no había configurado
+# scripts/lib/ en sys.path previamente.
+sys.path.insert(0, str(Path(__file__).resolve().parent / "lib"))
+from mcp_config import build_stdio_env  # noqa: E402
+
 # ---------------------------------------------------------------------------
 # Dependencias — raw mcp SDK
 # ---------------------------------------------------------------------------
@@ -36,6 +44,7 @@ try:
     from mcp import ClientSession
     from mcp.client.stdio import stdio_client, StdioServerParameters
     from mcp.client.sse import sse_client
+
     HAS_MCP = True
 except ImportError:
     HAS_MCP = False
@@ -44,9 +53,9 @@ except ImportError:
 # Constantes
 # ---------------------------------------------------------------------------
 
-TRACES_DIR   = Path('.planning') / 'traces'
-MCP_PREFIX   = 'mcp'                          # prefijo de archivos de traza MCP
-TIMEOUT_S    = 15
+TRACES_DIR = Path(".planning") / "traces"
+MCP_PREFIX = "mcp"  # prefijo de archivos de traza MCP
+TIMEOUT_S = 15
 
 # ---------------------------------------------------------------------------
 # Utilidades de traza OTLP-lite
@@ -54,11 +63,11 @@ TIMEOUT_S    = 15
 
 
 def _trace_id() -> str:
-    return secrets.token_hex(16)   # 128 bits, 32 hex chars
+    return secrets.token_hex(16)  # 128 bits, 32 hex chars
 
 
 def _span_id() -> str:
-    return secrets.token_hex(8)    # 64 bits, 16 hex chars
+    return secrets.token_hex(8)  # 64 bits, 16 hex chars
 
 
 def _iso_now() -> str:
@@ -69,15 +78,19 @@ def _ruta_hoy(cwd: Path) -> Path:
     """Ruta del JSONL de trazas MCP del dia actual."""
     directorio = cwd / TRACES_DIR
     directorio.mkdir(parents=True, exist_ok=True)
-    fecha = datetime.now(timezone.utc).strftime('%Y-%m-%d')
-    return directorio / f'{MCP_PREFIX}-{fecha}.jsonl'
-
-
-def registrar_traza(cwd: Path, nombre: str, atributos: dict,
-                    estado: str = 'OK',
-                    inicio_iso: str | None = None,
-                    fin_iso: str | None = None,
-                    duracion_ms: int = 0) -> dict:
+    fecha = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    return directorio / f"{MCP_PREFIX}-{fecha}.jsonl"
+
+
+def registrar_traza(
+    cwd: Path,
+    nombre: str,
+    atributos: dict,
+    estado: str = "OK",
+    inicio_iso: str | None = None,
+    fin_iso: str | None = None,
+    duracion_ms: int = 0,
+) -> dict:
     """Escribe una entrada OTLP-lite al JSONL de trazas del dia.
 
     Parametros:
@@ -93,23 +106,24 @@ def registrar_traza(cwd: Path, nombre: str, atributos: dict,
     """
     ahora = _iso_now()
     traza = {
-        'traceId':    _trace_id(),
-        'spanId':     _span_id(),
-        'nombre':     nombre,
-        'inicio':     inicio_iso or ahora,
-        'fin':        fin_iso or ahora,
-        'duracionMs': duracion_ms,
-        'estado':     estado,
-        'atributos':  atributos,
+        "traceId": _trace_id(),
+        "spanId": _span_id(),
+        "nombre": nombre,
+        "inicio": inicio_iso or ahora,
+        "fin": fin_iso or ahora,
+        "duracionMs": duracion_ms,
+        "estado": estado,
+        "atributos": atributos,
     }
     try:
         ruta = _ruta_hoy(cwd)
-        with open(ruta, 'a', encoding='utf-8') as fh:
-            fh.write(json.dumps(traza, ensure_ascii=False) + '\n')
+        with open(ruta, "a", encoding="utf-8") as fh:
+            fh.write(json.dumps(traza, ensure_ascii=False) + "\n")
     except Exception as exc:
-        sys.stderr.write(f'[mcp-telemetry] No se pudo escribir traza: {exc}\n')
+        sys.stderr.write(f"[mcp-telemetry] No se pudo escribir traza: {exc}\n")
     return traza
 
+
 # ---------------------------------------------------------------------------
 # Context manager: MCPTelemetrySession
 # ---------------------------------------------------------------------------
@@ -128,33 +142,32 @@ class MCPTelemetrySession:
     """
 
     def __init__(self, cwd: Path, server_name: str, server_cfg: dict) -> None:
-        self.cwd         = cwd
+        self.cwd = cwd
         self.server_name = server_name
-        self.server_cfg  = server_cfg
+        self.server_cfg = server_cfg
         self._session: ClientSession | None = None
         self._ctx_stack: list = []
 
-    async def __aenter__(self) -> 'MCPTelemetrySession':
+    async def __aenter__(self) -> "MCPTelemetrySession":
         if not HAS_MCP:
-            raise RuntimeError('La libreria mcp no esta instalada. Ejecuta: pip install mcp')
+            raise RuntimeError(
+                "La libreria mcp no esta instalada. Ejecuta: pip install mcp"
+            )
 
         cfg = self.server_cfg
-        if 'url' in cfg:
-            transport = sse_client(cfg['url'])
+        if "url" in cfg:
+            transport = sse_client(cfg["url"])
         else:
-            env: dict | None = None
-            if extra := cfg.get('env'):
-                env = {**os.environ, **extra}
             params = StdioServerParameters(
-                command=cfg['command'],
-                args=cfg.get('args', []),
-                env=env,
-                cwd=cfg.get('cwd'),
+                command=cfg["command"],
+                args=cfg.get("args", []),
+                env=build_stdio_env(cfg),
+                cwd=cfg.get("cwd"),
             )
             transport = stdio_client(params)
 
         t_ctx = transport
-        rw    = await t_ctx.__aenter__()
+        rw = await t_ctx.__aenter__()
         self._ctx_stack.append(t_ctx)
 
         sess_ctx = ClientSession(rw[0], rw[1])
@@ -176,7 +189,7 @@ class MCPTelemetrySession:
     async def list_tools(self) -> list:
         """Lista herramientas disponibles en el servidor."""
         if not self._session:
-            raise RuntimeError('Sesion no inicializada — usar como context manager')
+            raise RuntimeError("Sesion no inicializada — usar como context manager")
         resp = await asyncio.wait_for(self._session.list_tools(), timeout=TIMEOUT_S)
         return resp.tools or []
 
@@ -186,51 +199,51 @@ class MCPTelemetrySession:
         Retorna dict con: result (list[str]), is_error (bool), duration_ms (int).
         """
         if not self._session:
-            raise RuntimeError('Sesion no inicializada — usar como context manager')
+            raise RuntimeError("Sesion no inicializada — usar como context manager")
 
         inicio_ts = time.time()
         inicio_iso = _iso_now()
-        estado    = 'OK'
-        resultado: dict = {'result': [], 'is_error': False, 'duration_ms': 0}
+        estado = "OK"
+        resultado: dict = {"result": [], "is_error": False, "duration_ms": 0}
 
         try:
             resp = await asyncio.wait_for(
                 self._session.call_tool(tool, arguments or {}),
                 timeout=TIMEOUT_S,
             )
-            resultado['is_error'] = bool(getattr(resp, 'isError', False))
-            resultado['result']   = [
-                c.text if hasattr(c, 'text') else str(c)
-                for c in (resp.content or [])
+            resultado["is_error"] = bool(getattr(resp, "isError", False))
+            resultado["result"] = [
+                c.text if hasattr(c, "text") else str(c) for c in (resp.content or [])
             ]
-            if resultado['is_error']:
-                estado = 'ERROR'
+            if resultado["is_error"]:
+                estado = "ERROR"
         except Exception as exc:
-            resultado['error'] = str(exc)
-            estado = 'ERROR'
+            resultado["error"] = str(exc)
+            estado = "ERROR"
         finally:
-            fin_ts  = time.time()
-            dur_ms  = int((fin_ts - inicio_ts) * 1000)
+            fin_ts = time.time()
+            dur_ms = int((fin_ts - inicio_ts) * 1000)
             fin_iso = _iso_now()
-            resultado['duration_ms'] = dur_ms
+            resultado["duration_ms"] = dur_ms
 
             registrar_traza(
-                cwd       = self.cwd,
-                nombre    = f'mcp:call_tool',
-                atributos = {
-                    'server':      self.server_name,
-                    'tool':        tool,
-                    'args_keys':   list((arguments or {}).keys()),
-                    'duration_ms': dur_ms,
+                cwd=self.cwd,
+                nombre=f"mcp:call_tool",
+                atributos={
+                    "server": self.server_name,
+                    "tool": tool,
+                    "args_keys": list((arguments or {}).keys()),
+                    "duration_ms": dur_ms,
                 },
-                estado      = estado,
-                inicio_iso  = inicio_iso,
-                fin_iso     = fin_iso,
-                duracion_ms = dur_ms,
+                estado=estado,
+                inicio_iso=inicio_iso,
+                fin_iso=fin_iso,
+                duracion_ms=dur_ms,
             )
 
         return resultado
 
+
 # ---------------------------------------------------------------------------
 # CLI helpers
 # ---------------------------------------------------------------------------
@@ -243,10 +256,10 @@ def _leer_trazas_mcp(cwd: Path, dias: int = 1) -> list:
         return []
 
     trazas: list = []
-    archivos = sorted(directorio.glob(f'{MCP_PREFIX}-*.jsonl'), reverse=True)[:dias]
+    archivos = sorted(directorio.glob(f"{MCP_PREFIX}-*.jsonl"), reverse=True)[:dias]
     for archivo in archivos:
         try:
-            for linea in archivo.read_text(encoding='utf-8').splitlines():
+            for linea in archivo.read_text(encoding="utf-8").splitlines():
                 linea = linea.strip()
                 if linea:
                     try:
@@ -259,79 +272,81 @@ def _leer_trazas_mcp(cwd: Path, dias: int = 1) -> list:
 
 
 def _cmd_report(cwd: Path, dias: int, as_json: bool) -> None:
-    out    = sys.stdout.write
+    out = sys.stdout.write
     trazas = _leer_trazas_mcp(cwd, dias)
 
     if as_json:
-        out(json.dumps(trazas, ensure_ascii=False, indent=2) + '\n')
+        out(json.dumps(trazas, ensure_ascii=False, indent=2) + "\n")
         return
 
     if not trazas:
-        out(f'Sin trazas MCP en los ultimos {dias} dia(s).\n')
-        out(f'Directorio: {cwd / TRACES_DIR}\n')
+        out(f"Sin trazas MCP en los ultimos {dias} dia(s).\n")
+        out(f"Directorio: {cwd / TRACES_DIR}\n")
         return
 
-    out(f'\nTrazas MCP ({len(trazas)} entradas, ultimos {dias} dia(s)):\n')
-    out('-' * 72 + '\n')
-    for t in trazas[-50:]:        # mostrar ultimas 50
-        estado = t.get('estado', '?')
-        nombre = t.get('nombre', '?')
-        dur    = t.get('duracionMs', 0)
-        attrs  = t.get('atributos', {})
-        server = attrs.get('server', '')
-        tool   = attrs.get('tool', '')
-        ts     = t.get('inicio', '')[:19]
-        out(f'  {ts}  {estado:<5}  {nombre:<20}  {server}/{tool}  {dur}ms\n')
+    out(f"\nTrazas MCP ({len(trazas)} entradas, ultimos {dias} dia(s)):\n")
+    out("-" * 72 + "\n")
+    for t in trazas[-50:]:  # mostrar ultimas 50
+        estado = t.get("estado", "?")
+        nombre = t.get("nombre", "?")
+        dur = t.get("duracionMs", 0)
+        attrs = t.get("atributos", {})
+        server = attrs.get("server", "")
+        tool = attrs.get("tool", "")
+        ts = t.get("inicio", "")[:19]
+        out(f"  {ts}  {estado:<5}  {nombre:<20}  {server}/{tool}  {dur}ms\n")
 
 
 def _cmd_stats(cwd: Path, dias: int, as_json: bool) -> None:
-    out    = sys.stdout.write
+    out = sys.stdout.write
     trazas = _leer_trazas_mcp(cwd, dias)
 
     # Agregar por servidor y herramienta
-    stats: dict = {}   # server -> {tool -> {count, ok, errors, total_ms}}
+    stats: dict = {}  # server -> {tool -> {count, ok, errors, total_ms}}
     for t in trazas:
-        attrs  = t.get('atributos', {})
-        server = attrs.get('server', 'desconocido')
-        tool   = attrs.get('tool', 'desconocido')
-        estado = t.get('estado', 'OK')
-        dur    = t.get('duracionMs', 0)
+        attrs = t.get("atributos", {})
+        server = attrs.get("server", "desconocido")
+        tool = attrs.get("tool", "desconocido")
+        estado = t.get("estado", "OK")
+        dur = t.get("duracionMs", 0)
 
         if server not in stats:
             stats[server] = {}
         if tool not in stats[server]:
-            stats[server][tool] = {'count': 0, 'ok': 0, 'errors': 0, 'total_ms': 0}
+            stats[server][tool] = {"count": 0, "ok": 0, "errors": 0, "total_ms": 0}
 
         s = stats[server][tool]
-        s['count']    += 1
-        s['total_ms'] += dur
-        if estado == 'OK':
-            s['ok'] += 1
+        s["count"] += 1
+        s["total_ms"] += dur
+        if estado == "OK":
+            s["ok"] += 1
         else:
-            s['errors'] += 1
+            s["errors"] += 1
 
     # Calcular promedio
     for server in stats:
         for tool in stats[server]:
             s = stats[server][tool]
-            s['avg_ms'] = int(s['total_ms'] / s['count']) if s['count'] else 0
+            s["avg_ms"] = int(s["total_ms"] / s["count"]) if s["count"] else 0
 
     if as_json:
-        out(json.dumps(stats, ensure_ascii=False, indent=2) + '\n')
+        out(json.dumps(stats, ensure_ascii=False, indent=2) + "\n")
         return
 
     if not stats:
-        out(f'Sin datos de uso MCP en los ultimos {dias} dia(s).\n')
+        out(f"Sin datos de uso MCP en los ultimos {dias} dia(s).\n")
         return
 
-    out(f'\nEstadisticas MCP — ultimos {dias} dia(s) ({len(trazas)} trazas):\n')
-    out('-' * 72 + '\n')
-    out(f'  {"Servidor":<22} {"Herramienta":<24} {"Calls":>6} {"OK":>4} {"Err":>4} {"Avg ms":>7}\n')
-    out('-' * 72 + '\n')
+    out(f"\nEstadisticas MCP — ultimos {dias} dia(s) ({len(trazas)} trazas):\n")
+    out("-" * 72 + "\n")
+    out(
+        f'  {"Servidor":<22} {"Herramienta":<24} {"Calls":>6} {"OK":>4} {"Err":>4} {"Avg ms":>7}\n'
+    )
+    out("-" * 72 + "\n")
     for server, tools in sorted(stats.items()):
         for tool, s in sorted(tools.items()):
             out(
-                f'  {server:<22} {tool:<24}'
+                f"  {server:<22} {tool:<24}"
                 f' {s["count"]:>6} {s["ok"]:>4} {s["errors"]:>4} {s["avg_ms"]:>7}\n'
             )
 
@@ -342,37 +357,41 @@ def _cmd_stats(cwd: Path, dias: int, as_json: bool) -> None:
 
 
 def main() -> None:
-    if hasattr(sys.stdout, 'reconfigure'):
-        sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
 
     parser = argparse.ArgumentParser(
-        description='Trazabilidad OTLP-lite para sesiones MCP en swl-ses'
+        description="Trazabilidad OTLP-lite para sesiones MCP en swl-ses"
     )
-    parser.add_argument('--json', action='store_true', help='Salida en formato JSON')
-    parser.add_argument('--cwd',  default='.', help='Directorio raiz del proyecto')
+    parser.add_argument("--json", action="store_true", help="Salida en formato JSON")
+    parser.add_argument("--cwd", default=".", help="Directorio raiz del proyecto")
 
-    sub = parser.add_subparsers(dest='cmd')
+    sub = parser.add_subparsers(dest="cmd")
 
-    p_rep = sub.add_parser('report', help='Muestra trazas MCP recientes')
-    p_rep.add_argument('--days', type=int, default=1,
-                       help='Numero de dias hacia atras (default: 1)')
+    p_rep = sub.add_parser("report", help="Muestra trazas MCP recientes")
+    p_rep.add_argument(
+        "--days", type=int, default=1, help="Numero de dias hacia atras (default: 1)"
+    )
 
-    p_stats = sub.add_parser('stats', help='Estadisticas de uso por servidor/herramienta')
-    p_stats.add_argument('--days', type=int, default=7,
-                         help='Numero de dias hacia atras (default: 7)')
+    p_stats = sub.add_parser(
+        "stats", help="Estadisticas de uso por servidor/herramienta"
+    )
+    p_stats.add_argument(
+        "--days", type=int, default=7, help="Numero de dias hacia atras (default: 7)"
+    )
 
     args = parser.parse_args()
-    cwd  = Path(args.cwd).resolve()
+    cwd = Path(args.cwd).resolve()
 
-    as_json = bool(getattr(args, 'json', False))
+    as_json = bool(getattr(args, "json", False))
 
-    if args.cmd == 'report':
+    if args.cmd == "report":
         _cmd_report(cwd, args.days, as_json)
-    elif args.cmd == 'stats':
+    elif args.cmd == "stats":
         _cmd_stats(cwd, args.days, as_json)
     else:
         parser.print_help()
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     main()

package/scripts/verificar-release.js

@@ -272,6 +272,19 @@ function main() {
     fallasObligatorias++;
   }
 
+  // Gate de consistencia cross-manifest del campo description:
+  // valida que package.json#description y plugin.json#description tengan
+  // las mismas cifras (60 agentes / N habilidades / M comandos / K reglas / L hooks)
+  // Y que esas cifras coincidan con los conteos reales de INVENTARIO.md.
+  // Origen: bug v1.6.4 — package.json#description quedó con cifras stale de v1.6.2
+  // (162/67/41 + ADR-0025) mientras plugin.json#description se actualizó correctamente
+  // a (171/69/42 + ADR-0028). Ni el gate de contadores ni el de versión lo detectaron
+  // porque solo escanean .md, no campos `description` de manifiestos JSON.
+  const gateDescription = ejecutarGateDescription(gateContadores.contadoresReales);
+  if (gateDescription.disponible && gateDescription.discrepancias.length > 0) {
+    fallasObligatorias++;
+  }
+
   // Gate opt-in de AI-isms sobre CHANGELOG.md + RELEASE_NOTES.md
   // Se activa solo cuando SWL_AIISMS_GATE=1 y bloquea si encuentra P0.
   let aiismsGate = null;
@@ -291,6 +304,7 @@ function main() {
       warnings_opcionales: warningsOpcionales,
       contadores_gate: gateContadores,
       bin_imports_gate: gateBinImports,
+      description_gate: gateDescription,
       aiisms_gate: aiismsGate,
       resultados: resultados.map(({ entrada, resultado }) => ({
         archivo: entrada.archivo,
@@ -364,6 +378,32 @@ function main() {
       process.stdout.write('\n');
       process.stdout.write('Gate de bin-imports: no disponible — ' + gateBinImports.error + '\n');
     }
+    if (gateDescription.disponible) {
+      process.stdout.write('\n');
+      process.stdout.write('Gate de description (package.json vs plugin.json vs INVENTARIO.md):\n');
+      process.stdout.write('  package.json#description:  ' +
+        formatearCifras(gateDescription.cifrasPackage) + '\n');
+      process.stdout.write('  plugin.json#description:   ' +
+        formatearCifras(gateDescription.cifrasPlugin) + '\n');
+      if (gateDescription.contadoresReales) {
+        process.stdout.write('  Reales (INVENTARIO.md):    ' +
+          formatearCifras(gateDescription.contadoresReales) + '\n');
+      }
+      if (gateDescription.discrepancias.length === 0) {
+        process.stdout.write('  [OK] description consistente cross-manifest y vs INVENTARIO.md\n');
+      } else {
+        for (const d of gateDescription.discrepancias) {
+          process.stdout.write('  [FALLA] ' + d + '\n');
+        }
+        process.stdout.write(
+          '  Bloqueo: actualiza description en package.json y/o plugin.json. ' +
+          'Las cifras deben coincidir entre sí Y con INVENTARIO.md.\n'
+        );
+      }
+    } else if (gateDescription.error) {
+      process.stdout.write('\n');
+      process.stdout.write('Gate de description: no disponible — ' + gateDescription.error + '\n');
+    }
     if (aiismsGate) {
       process.stdout.write('\n');
       process.stdout.write('Gate AI-isms (SWL_AIISMS_GATE=1):\n');
@@ -603,6 +643,164 @@ function ejecutarGateAiisms() {
   return { disponible: true, archivos, p0Total };
 }
 
+/**
+ * Extrae cifras cuantificadas del campo description de un manifiesto JSON.
+ *
+ * Busca patrones del tipo "N agentes", "N habilidades|skills", "N comandos",
+ * "N reglas", "N hooks" en cualquier orden y los devuelve como objeto.
+ *
+ * Devuelve null para cualquier categoría que no aparezca — el caller decide
+ * si tratar la ausencia como falla o como tolerable.
+ *
+ * @param {string} description - Texto del campo description.
+ * @returns {{agentes:number|null, skills:number|null, comandos:number|null, reglas:number|null, hooks:number|null}}
+ */
+function extraerCifrasDescription(description) {
+  if (typeof description !== 'string' || description.trim() === '') {
+    return { agentes: null, skills: null, comandos: null, reglas: null, hooks: null };
+  }
+  const extraer = (regex) => {
+    const m = description.match(regex);
+    return m ? parseInt(m[1], 10) : null;
+  };
+  return {
+    agentes:  extraer(/(\d+)\s+agentes\b/i),
+    // "habilidades" o "skills" — ambos válidos en descriptions del proyecto
+    skills:   extraer(/(\d+)\s+(?:habilidades|skills)\b/i),
+    comandos: extraer(/(\d+)\s+comandos\b/i),
+    reglas:   extraer(/(\d+)\s+reglas\b/i),
+    hooks:    extraer(/(\d+)\s+hooks\b/i),
+  };
+}
+
+/**
+ * Formatea un objeto de cifras como "A agentes / S skills / C cmds / R reglas / H hooks"
+ * usando "?" cuando la cifra es null (no encontrada en el texto).
+ */
+function formatearCifras(c) {
+  if (!c) return '(no extraído)';
+  const fmt = (v) => v == null ? '?' : String(v);
+  return `${fmt(c.agentes)} agentes / ${fmt(c.skills)} skills / ${fmt(c.comandos)} cmds / ${fmt(c.reglas)} reglas / ${fmt(c.hooks)} hooks`;
+}
+
+/**
+ * Gate de consistencia cross-manifest del campo description:
+ *
+ * 1. Lee package.json#description y plugin.json#description.
+ * 2. Extrae cifras (agentes, skills, comandos, reglas, hooks) de ambas.
+ * 3. Valida que las cifras coincidan entre los 2 manifiestos.
+ * 4. Si se pasa `contadoresReales` (de INVENTARIO.md), valida también que
+ *    coincidan con la fuente de verdad estructural del disco.
+ *
+ * Solo reporta discrepancias para categorías donde AMBOS lados tienen cifra
+ * (si una description no menciona "hooks", no falla — solo se reporta como
+ * info en el campo cifrasPackage/cifrasPlugin).
+ *
+ * Origen: bug v1.6.4 — package.json#description quedó stale con (162 skills,
+ * 67 reglas, 41 hooks, ADR-0025) mientras plugin.json#description se
+ * actualizó a (171 skills, 69 reglas, 42 hooks, ADR-0028). El bug pasó por
+ * los otros 3 gates porque ninguno escaneaba campos JSON descriptivos.
+ *
+ * @param {object|null} contadoresReales - Output de contadoresLib.parsearInventario, opcional.
+ * @returns {{disponible:boolean, error?:string, cifrasPackage?:object, cifrasPlugin?:object, contadoresReales?:object, discrepancias:string[]}}
+ */
+function ejecutarGateDescription(contadoresReales) {
+  let pkg, plugin;
+  try {
+    pkg = JSON.parse(fs.readFileSync(path.join(CWD, 'package.json'), 'utf-8'));
+  } catch (e) {
+    return { disponible: false, error: 'package.json no se pudo leer/parsear', discrepancias: [] };
+  }
+  try {
+    plugin = JSON.parse(fs.readFileSync(path.join(CWD, 'plugin.json'), 'utf-8'));
+  } catch (e) {
+    return { disponible: false, error: 'plugin.json no se pudo leer/parsear', discrepancias: [] };
+  }
+
+  const cifrasPackage = extraerCifrasDescription(pkg.description);
+  const cifrasPlugin = extraerCifrasDescription(plugin.description);
+  const discrepancias = [];
+
+  // Validación cross-manifest: package.json#description vs plugin.json#description
+  const categorias = ['agentes', 'skills', 'comandos', 'reglas', 'hooks'];
+  for (const cat of categorias) {
+    const v1 = cifrasPackage[cat];
+    const v2 = cifrasPlugin[cat];
+    // Solo comparar cuando AMBOS lados tienen cifra explícita
+    if (v1 != null && v2 != null && v1 !== v2) {
+      discrepancias.push(
+        `${cat}: package.json#description=${v1} vs plugin.json#description=${v2} ` +
+        `(deben coincidir)`
+      );
+    }
+  }
+
+  // Validación contra INVENTARIO.md (fuente de verdad estructural).
+  //
+  // Nota: NO usar truthy checks (`&& contadoresReales.agentes`) — `parsearInventario`
+  // devuelve 0 cuando una sección está ausente del INVENTARIO (línea
+  // `resumen['Agentes SWL'] || 0` en contadores-inventario.js). Un truthy
+  // check sobre 0 salta la validación y oculta INVENTARIO corrupto.
+  // Verificación por tipo (`typeof === 'number'`) distingue "campo ausente"
+  // de "campo presente con valor 0".
+  if (contadoresReales && typeof contadoresReales === 'object') {
+    const mapa = {
+      agentes: contadoresReales.agentes,
+      skills: contadoresReales.skills,
+      comandos: contadoresReales.comandos,
+      reglas: contadoresReales.reglas,
+      hooks: contadoresReales.hooks,
+    };
+    // Sanidad: un INVENTARIO con TODAS las cifras = 0 indica parsing fallido
+    // (el sistema real nunca tiene 0 agentes/skills). Reportar como
+    // discrepancia explícita en lugar de saltar silenciosamente.
+    const algunaCifraValida = Object.values(mapa).some(
+      v => typeof v === 'number' && v > 0
+    );
+    if (!algunaCifraValida) {
+      discrepancias.push(
+        'INVENTARIO.md parece corrupto o no parseable (todas las cifras = 0). ' +
+        'Regenera con `node scripts/generar-inventario.js` antes de release. ' +
+        'La validación cross-manifest sigue siendo válida; solo se salta ' +
+        'la comparación vs INVENTARIO hasta que sea legible.'
+      );
+    } else {
+      for (const cat of categorias) {
+        const real = mapa[cat];
+        // Solo saltar si el campo NO es número (ausente/undefined).
+        // Aceptar 0 como cifra válida — la comparación detectará discrepancias.
+        if (typeof real !== 'number') continue;
+        if (cifrasPackage[cat] != null && cifrasPackage[cat] !== real) {
+          discrepancias.push(
+            `${cat}: package.json#description=${cifrasPackage[cat]} vs INVENTARIO=${real} ` +
+            `(description debe reflejar conteo real)`
+          );
+        }
+        if (cifrasPlugin[cat] != null && cifrasPlugin[cat] !== real) {
+          discrepancias.push(
+            `${cat}: plugin.json#description=${cifrasPlugin[cat]} vs INVENTARIO=${real} ` +
+            `(description debe reflejar conteo real)`
+          );
+        }
+      }
+    }
+  }
+
+  return {
+    disponible: true,
+    cifrasPackage,
+    cifrasPlugin,
+    contadoresReales: contadoresReales || null,
+    discrepancias,
+  };
+}
+
 if (require.main === module) main();
 
-module.exports = { CHECKLIST, verificarEntrada, versionObjetivo };
+module.exports = {
+  CHECKLIST,
+  verificarEntrada,
+  versionObjetivo,
+  extraerCifrasDescription,
+  ejecutarGateDescription,
+};