@saulwade/swl-ses 2.6.1 → 2.8.0

package/scripts/verificar-empaquetado-downstream.js

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Ciclo aislado pack -> install -> doctor -> update -> uninstall sobre el
+ * TARBALL real que `npm pack` produciría — no el árbol fuente. Detecta la
+ * clase de bug histórica "declarado en package.json#files pero el contenido
+ * empaquetado está roto/incompleto" (gateway/ ausente antes de v1.4.0,
+ * ver CLAUDE.md § package.json#files) que ni los tests unitarios ni el
+ * gate de sincronización de manifiestos pueden atrapar, porque ambos leen
+ * el árbol fuente, no lo que realmente viaja en el tarball.
+ *
+ * Fase "update": el subcomando `update` real compara la versión local
+ * contra el registro npm (`npm view`) y, si el paquete local difiere del
+ * publicado, se salta el reinstalo ANTES de evaluar `--force`
+ * (scripts/actualizar.js) — no determinista en desarrollo local con una
+ * versión sin publicar (local 3.0.0 vs. remoto real 2.6.1 al momento de
+ * escribir este script). Ejercitar el subcomando `update` real produciría
+ * un no-op silencioso que fingiría cobertura sin probar nada. Esta fase en
+ * su lugar corre `update --check` (solo lectura, tolerante a falta de red)
+ * MÁS un reinstall en sitio con los mismos flags del install inicial — el
+ * mecanismo real que `update()` invoca internamente (`instalador()` con
+ * `force:true`) cuando SÍ decide actualizar — probando así el camino de
+ * re-aplicación idempotente sin depender del estado del registro npm.
+ *
+ * Exit codes: 0 OK, 1 si cualquier fase falla.
+ *
+ * Uso: node scripts/verificar-empaquetado-downstream.js [--keep-tmp]
+ */
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const { comandoNpm } = require('./lib/npm-version');
+
+const RAIZ = path.resolve(__dirname, '..');
+const KEEP_TMP = process.argv.includes('--keep-tmp');
+
+function log(msg) {
+  console.log(msg);
+}
+
+/**
+ * Invoca `npm <args>` vía `node npm-cli.js` (nunca `npm.cmd` con
+ * `shell:true`): en Windows, `spawnSync('npm.cmd', ...)` sin shell lanza
+ * EINVAL, y `shell:true` reintroduce DEP0190 — mismo problema ya resuelto
+ * en scripts/lib/npm-version.js § comandoNpm.
+ */
+function spawnNpm(args, opts) {
+  const { bin, argsList } = comandoNpm(args);
+  return spawnSync(bin, argsList, opts);
+}
+
+// ---------------------------------------------------------------------------
+// Fase 0: inspección del tarball (dry-run, sin escribir en disco).
+// ---------------------------------------------------------------------------
+
+const RUTAS_REQUERIDAS = [
+  'bin/', 'manifiestos/', 'schemas/', 'agentes/', 'habilidades/',
+  'comandos/', 'hooks/', 'reglas/', 'package.json', 'plugin.json', 'CLAUDE.md',
+];
+// Nombres de ARCHIVO que delatan credenciales reales, no menciones al tema
+// (el paquete incluye legítimamente hooks/skills de escaneo de secretos —
+// "escaneo-secretos.js", "habilidades/iam-secretos/" — que hablan DE
+// seguridad sin filtrar ninguna).
+const PATRONES_PROHIBIDOS = [
+  /^tests\//, /^\.planning\//, /(^|\/)\.env(\.|$)/, /\.pem$/, /\.key$/,
+  /(^|\/)\.npmrc$/, /(^|\/)\.netrc$/,
+  /(^|\/)credentials\.json$/, /(^|\/)secrets\.(json|ya?ml)$/,
+  /^\.git\//, /^temp\//, /^respositorios-git\//,
+];
+
+function faseInspeccion() {
+  log('\n[FASE 0/5] inspección del tarball (npm pack --dry-run --json --ignore-scripts)');
+  const r = spawnNpm(['pack', '--dry-run', '--json', '--ignore-scripts'], {
+    cwd: RAIZ, encoding: 'utf-8',
+  });
+  if (r.status !== 0) {
+    log(`  [FALLA] npm pack --dry-run exit=${r.status}`);
+    log(r.stderr || '');
+    return { ok: false };
+  }
+  let parseado;
+  try {
+    parseado = JSON.parse(r.stdout);
+  } catch (error) {
+    log(`  [FALLA] salida de npm pack --dry-run no es JSON válido: ${error.message}`);
+    return { ok: false };
+  }
+  const entrada = parseado[0];
+  const archivos = (entrada.files || []).map((f) => f.path);
+
+  const faltantes = RUTAS_REQUERIDAS.filter(
+    (req) => !archivos.some((a) => a === req || a.startsWith(req))
+  );
+  if (faltantes.length > 0) {
+    log(`  [FALLA] rutas requeridas ausentes del tarball: ${faltantes.join(', ')}`);
+    return { ok: false };
+  }
+  log(`  [OK] ${RUTAS_REQUERIDAS.length}/${RUTAS_REQUERIDAS.length} rutas requeridas presentes`);
+
+  const prohibidos = archivos.filter((a) => PATRONES_PROHIBIDOS.some((pat) => pat.test(a)));
+  if (prohibidos.length > 0) {
+    log(`  [FALLA] rutas prohibidas presentes en el tarball: ${prohibidos.slice(0, 10).join(', ')}`);
+    return { ok: false };
+  }
+  log(`  [OK] sin fixtures/tests/secretos/evidencia privada (${archivos.length} archivos totales)`);
+  return { ok: true };
+}
+
+// ---------------------------------------------------------------------------
+// Fase 1: pack real + install aislado del tarball vía npm (igual que un
+// consumidor downstream real: `npm install @saulwade/swl-ses`).
+// ---------------------------------------------------------------------------
+
+function fasePackEInstalarPaquete(tmpBase) {
+  log('\n[FASE 1/5] npm pack real + instalación del tarball en prefix aislado');
+  const packDest = path.join(tmpBase, 'pack-dest');
+  const installDest = path.join(tmpBase, 'consumer');
+  fs.mkdirSync(packDest, { recursive: true });
+  fs.mkdirSync(installDest, { recursive: true });
+
+  const pack = spawnNpm(['pack', '--pack-destination', packDest, '--ignore-scripts'], {
+    cwd: RAIZ, encoding: 'utf-8',
+  });
+  if (pack.status !== 0) {
+    log(`  [FALLA] npm pack exit=${pack.status}`);
+    log(pack.stderr || '');
+    return { ok: false };
+  }
+  const tgz = fs.readdirSync(packDest).find((f) => f.endsWith('.tgz'));
+  if (!tgz) {
+    log('  [FALLA] npm pack no produjo ningún .tgz');
+    return { ok: false };
+  }
+  log(`  [OK] tarball producido: ${tgz}`);
+
+  const install = spawnNpm(
+    ['install', '--prefix', installDest, '--no-save', '--ignore-scripts', path.join(packDest, tgz)],
+    { cwd: installDest, encoding: 'utf-8' }
+  );
+  if (install.status !== 0) {
+    log(`  [FALLA] npm install del tarball exit=${install.status}`);
+    log(install.stderr || '');
+    return { ok: false };
+  }
+  const paqueteDir = path.join(installDest, 'node_modules', '@saulwade', 'swl-ses');
+  const cli = path.join(paqueteDir, 'bin', 'swl-ses.js');
+  if (!fs.existsSync(cli)) {
+    log(`  [FALLA] el tarball instalado no contiene ${path.relative(installDest, cli)}`);
+    return { ok: false };
+  }
+  log('  [OK] tarball instalado en prefix aislado; bin/swl-ses.js presente');
+  return { ok: true, cli, paqueteDir };
+}
+
+// ---------------------------------------------------------------------------
+// Fases 2-4: install -> doctor -> update -> uninstall, ejecutando el CLI
+// EMPACADO (no el árbol fuente) contra un HOME aislado.
+// ---------------------------------------------------------------------------
+
+function correrCliEmpacado(cli, args, cwd, env) {
+  const r = spawnSync(process.execPath, [cli, ...args], {
+    cwd, env: { ...process.env, ...env }, encoding: 'utf-8', timeout: 120000,
+  });
+  return {
+    code: r.status, stdout: r.stdout || '', stderr: r.stderr || '',
+    error: r.error ? (r.error.code || r.error.message) : null,
+  };
+}
+
+function faseInstalarDesdeEmpacado(cli, cwd, home) {
+  log('\n[FASE 2/5] install (desde el tarball) --profile completo --global --all-langs');
+  const r = correrCliEmpacado(
+    cli,
+    ['install', '--target', 'claude', '--profile', 'completo', '--global', '--force', '--all-langs'],
+    cwd, { HOME: home, USERPROFILE: home }
+  );
+  if (r.code !== 0) {
+    log(`  [FALLA] install exit=${r.code} spawnError=${r.error || '-'}`);
+    if (r.stderr.trim()) log(r.stderr.split('\n').slice(0, 10).map((l) => `    ${l}`).join('\n'));
+    return { ok: false };
+  }
+  const destino = path.join(home, '.claude');
+  const marcadores = [
+    path.join(destino, 'agents'), path.join(destino, 'skills'),
+    path.join(destino, 'commands'), path.join(destino, 'hooks'),
+    path.join(destino, 'rules'),
+  ];
+  const ausentes = marcadores.filter((m) => !fs.existsSync(m));
+  if (ausentes.length > 0) {
+    log(`  [FALLA] rutas esperadas ausentes tras install: ${ausentes.map((m) => path.relative(destino, m)).join(', ')}`);
+    return { ok: false };
+  }
+  log('  [OK] install terminó sin errores; estructura esperada presente');
+  return { ok: true };
+}
+
+function faseDoctorDesdeEmpacado(cli, cwd, home) {
+  log('\n[FASE 3/5] doctor (desde el tarball)');
+  const r = correrCliEmpacado(cli, ['doctor'], cwd, { HOME: home, USERPROFILE: home });
+  if (r.code !== 0) {
+    log(`  [FALLA] doctor exit=${r.code}`);
+    log(r.stdout.split('\n').slice(-15).map((l) => `    ${l}`).join('\n'));
+    return { ok: false };
+  }
+  const m = r.stdout.match(/(\d+)\s*errores/);
+  if (!m || parseInt(m[1], 10) !== 0) {
+    log('  [FALLA] doctor no reportó "0 errores" en su resumen');
+    log(r.stdout.split('\n').slice(-15).map((l) => `    ${l}`).join('\n'));
+    return { ok: false };
+  }
+  log('  [OK] doctor pasó sin errores');
+  return { ok: true };
+}
+
+function faseActualizarDesdeEmpacado(cli, cwd, home) {
+  log('\n[FASE 4/5] update --check (solo lectura) + reinstall en sitio (mecanismo real de update)');
+  const check = correrCliEmpacado(cli, ['update', '--check'], cwd, { HOME: home, USERPROFILE: home });
+  if (check.code !== 0) {
+    log(`  [FALLA] update --check exit=${check.code}`);
+    log(check.stderr.split('\n').slice(0, 10).map((l) => `    ${l}`).join('\n'));
+    return { ok: false };
+  }
+  log('  [OK] update --check terminó sin errores');
+
+  // Reinstall en sitio con los MISMOS flags del install inicial: el
+  // mecanismo idempotente que update() invoca internamente vía
+  // instalador({..., force:true}) cuando decide actualizar. Prueba que
+  // re-aplicar el mismo perfil sobre una instalación existente no rompe
+  // ni deja archivos a medias — sin depender del registro npm.
+  const reinstall = correrCliEmpacado(
+    cli,
+    ['install', '--target', 'claude', '--profile', 'completo', '--global', '--force', '--all-langs'],
+    cwd, { HOME: home, USERPROFILE: home }
+  );
+  if (reinstall.code !== 0) {
+    log(`  [FALLA] reinstall en sitio exit=${reinstall.code}`);
+    log(reinstall.stderr.split('\n').slice(0, 10).map((l) => `    ${l}`).join('\n'));
+    return { ok: false };
+  }
+  const destino = path.join(home, '.claude');
+  if (!fs.existsSync(path.join(destino, 'agents')) || !fs.existsSync(path.join(destino, 'skills'))) {
+    log('  [FALLA] tras el reinstall en sitio, agents/ o skills/ ya no están presentes');
+    return { ok: false };
+  }
+  log('  [OK] reinstall en sitio (mecanismo de update) terminó sin errores');
+  return { ok: true };
+}
+
+function faseDesinstalarDesdeEmpacado(cli, cwd, home) {
+  log('\n[FASE 5/5] uninstall (desde el tarball)');
+  const r = correrCliEmpacado(cli, ['uninstall', '--target', 'claude', '--global', '--force'], cwd, {
+    HOME: home, USERPROFILE: home,
+  });
+  if (r.code !== 0) {
+    log(`  [FALLA] uninstall exit=${r.code}`);
+    log(r.stderr.split('\n').slice(0, 10).map((l) => `    ${l}`).join('\n'));
+    return { ok: false };
+  }
+  log('  [OK] uninstall terminó sin errores');
+  return { ok: true };
+}
+
+// ---------------------------------------------------------------------------
+// Invariantes que ninguna fase debe romper: los siete claims públicos
+// permanecen unverified y las tres ubicaciones de versión no cambian.
+// ---------------------------------------------------------------------------
+
+function verificarInvariantesDelRepoFuente(snapshotPrevio) {
+  const conformancePath = path.join(RAIZ, 'manifiestos', 'runtime-conformance.json');
+  const conformance = JSON.parse(fs.readFileSync(conformancePath, 'utf8'));
+  const estados = Object.values(conformance.runtimes).map((r) => r.certificationStatus);
+  const noUnverified = estados.filter((e) => e !== 'unverified');
+  if (noUnverified.length > 0) {
+    return { ok: false, motivo: `runtime-conformance.json tiene estados fuera de unverified: ${noUnverified.join(', ')}` };
+  }
+  if (estados.length !== 7) {
+    return { ok: false, motivo: `runtime-conformance.json declara ${estados.length} runtimes, se esperaban 7` };
+  }
+
+  const pkg = JSON.parse(fs.readFileSync(path.join(RAIZ, 'package.json'), 'utf8'));
+  const plugin = JSON.parse(fs.readFileSync(path.join(RAIZ, 'plugin.json'), 'utf8'));
+  const salud = fs.readFileSync(path.join(RAIZ, 'SALUD.md'), 'utf8');
+  if (pkg.version !== snapshotPrevio.pkgVersion) {
+    return { ok: false, motivo: `package.json#version cambió: ${snapshotPrevio.pkgVersion} -> ${pkg.version}` };
+  }
+  if (plugin.version !== snapshotPrevio.pluginVersion) {
+    return { ok: false, motivo: `plugin.json#version cambió: ${snapshotPrevio.pluginVersion} -> ${plugin.version}` };
+  }
+  if (!salud.includes(snapshotPrevio.pkgVersion)) {
+    return { ok: false, motivo: `SALUD.md ya no menciona la versión ${snapshotPrevio.pkgVersion}` };
+  }
+  return { ok: true };
+}
+
+function snapshotVersiones() {
+  const pkg = JSON.parse(fs.readFileSync(path.join(RAIZ, 'package.json'), 'utf8'));
+  const plugin = JSON.parse(fs.readFileSync(path.join(RAIZ, 'plugin.json'), 'utf8'));
+  return { pkgVersion: pkg.version, pluginVersion: plugin.version };
+}
+
+function main() {
+  log('Ciclo aislado de empaquetado downstream (pack -> install -> doctor -> update -> uninstall)');
+  log('═══════════════════════════════════════════\n');
+
+  const snapshotPrevio = snapshotVersiones();
+
+  const inspeccion = faseInspeccion();
+  if (!inspeccion.ok) {
+    log('\n✗ FALLÓ en la fase de inspección — abortando sin tocar disco');
+    process.exit(1);
+  }
+
+  const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), 'swl-pack-cycle-'));
+  const home = path.join(tmpBase, 'home');
+  const cwd = path.join(tmpBase, 'workspace');
+  fs.mkdirSync(home, { recursive: true });
+  fs.mkdirSync(cwd, { recursive: true });
+  log(`TMP: ${tmpBase}`);
+
+  let todoOk = true;
+  try {
+    const paquete = fasePackEInstalarPaquete(tmpBase);
+    if (!paquete.ok) {
+      todoOk = false;
+    } else {
+      const install = faseInstalarDesdeEmpacado(paquete.cli, cwd, home);
+      if (!install.ok) todoOk = false;
+
+      if (install.ok) {
+        const doctor = faseDoctorDesdeEmpacado(paquete.cli, cwd, home);
+        if (!doctor.ok) todoOk = false;
+
+        const update = faseActualizarDesdeEmpacado(paquete.cli, cwd, home);
+        if (!update.ok) todoOk = false;
+
+        const uninstall = faseDesinstalarDesdeEmpacado(paquete.cli, cwd, home);
+        if (!uninstall.ok) todoOk = false;
+      }
+    }
+  } finally {
+    if (!KEEP_TMP) {
+      try {
+        fs.rmSync(tmpBase, { recursive: true, force: true });
+      } catch {
+        /* best-effort: no bloquear el resultado del gate por un residuo de limpieza */
+      }
+    } else {
+      log(`\n(--keep-tmp) directorio preservado en ${tmpBase}`);
+    }
+  }
+
+  log('\n[INVARIANTES] runtime-conformance unverified + versiones sin cambio en el repo fuente');
+  const invariantes = verificarInvariantesDelRepoFuente(snapshotPrevio);
+  if (!invariantes.ok) {
+    log(`  [FALLA] ${invariantes.motivo}`);
+    todoOk = false;
+  } else {
+    log('  [OK] los siete claims siguen unverified; package.json/plugin.json/SALUD.md sin cambio');
+  }
+
+  log('\n═══════════════════════════════════════════');
+  if (todoOk) {
+    log('✓ Ciclo de empaquetado downstream OK');
+    process.exit(0);
+  } else {
+    log('✗ Ciclo de empaquetado downstream FALLÓ — revisar fases arriba');
+    process.exit(1);
+  }
+}
+
+main();

package/scripts/verificar-loop-constructor.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Verifica, en modo de sólo lectura, un loop con el gate estructural de un
+ * checkout exacto de constructor-loops.
+ */
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ARGUMENTOS = new Set(['constructor-dir', 'expected-commit', 'loop']);
+const CAMPOS_GATE = new Set(['pass', 'summary', 'findings', 'matchedRules']);
+const SCRIPT_GATE = [
+  "import fs from 'node:fs';",
+  "import { pathToFileURL } from 'node:url';",
+  'const [builderPath, loopPath] = process.argv.slice(1);',
+  'const modulo = await import(pathToFileURL(builderPath).href);',
+  "if (typeof modulo.runStructuralGate !== 'function') {",
+  "  throw new TypeError('runStructuralGate no está exportado');",
+  '}',
+  "const markdown = fs.readFileSync(loopPath, 'utf8');",
+  'const resultado = modulo.runStructuralGate(markdown);',
+  'process.stdout.write(JSON.stringify(resultado));',
+].join('\n');
+
+function parsearArgs(argv) {
+  const opciones = {};
+  for (const argumento of argv) {
+    const separador = argumento.indexOf('=');
+    const clave = separador > 2 ? argumento.slice(2, separador) : '';
+    const valor = separador >= 0 ? argumento.slice(separador + 1) : '';
+    if (!argumento.startsWith('--') || !ARGUMENTOS.has(clave) || !valor) {
+      throw new TypeError(`argumento inválido: ${argumento}`);
+    }
+    if (Object.hasOwn(opciones, clave)) throw new TypeError(`argumento duplicado: --${clave}`);
+    opciones[clave] = valor;
+  }
+  const faltantes = [...ARGUMENTOS].filter((clave) => !Object.hasOwn(opciones, clave));
+  if (faltantes.length > 0) throw new TypeError(`argumentos requeridos: ${faltantes.join(', ')}`);
+  return opciones;
+}
+
+function resolverEntradas(opciones) {
+  const constructorDir = path.resolve(opciones.constructorDir);
+  const loopPath = path.resolve(opciones.loopPath);
+  if (!fs.existsSync(constructorDir) || !fs.statSync(constructorDir).isDirectory()) {
+    throw new Error(`constructor-dir no existe o no es directorio: ${constructorDir}`);
+  }
+  if (!fs.existsSync(loopPath) || !fs.statSync(loopPath).isFile()) {
+    throw new Error(`loop no existe o no es archivo: ${loopPath}`);
+  }
+  const constructorReal = fs.realpathSync(constructorDir);
+  const builderPath = path.join(constructorReal, 'app', 'lib', 'loop-builder.ts');
+  if (!fs.existsSync(builderPath) || !fs.statSync(builderPath).isFile()) {
+    throw new Error(`loop-builder.ts no existe: ${builderPath}`);
+  }
+  if (fs.lstatSync(builderPath).isSymbolicLink()) {
+    throw new Error(`loop-builder.ts no puede ser enlace simbólico: ${builderPath}`);
+  }
+  return { builderPath, constructorDir: constructorReal, loopPath: fs.realpathSync(loopPath) };
+}
+
+function construirEntornoGit(entorno = process.env) {
+  const limpio = Object.fromEntries(Object.entries(entorno).filter(
+    ([clave]) => clave.toUpperCase() !== 'GIT_OPTIONAL_LOCKS'
+  ));
+  return { ...limpio, GIT_OPTIONAL_LOCKS: '0' };
+}
+
+function ejecutarGit(constructorDir, args, descripcion) {
+  try {
+    return execFileSync('git', args, {
+      cwd: constructorDir,
+      encoding: 'utf8',
+      env: construirEntornoGit(),
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim().toLowerCase();
+  } catch (error) {
+    const detalle = String(error.stderr || error.message).trim();
+    throw new Error(`${descripcion}: ${detalle}`);
+  }
+}
+
+function verificarCommit(constructorDir, expectedCommit) {
+  if (!/^[a-f0-9]{7,40}$/i.test(expectedCommit)) {
+    throw new TypeError('expected-commit debe ser un SHA hexadecimal de 7 a 40 caracteres');
+  }
+  const revision = `${expectedCommit}^{commit}`;
+  const esperado = ejecutarGit(
+    constructorDir,
+    ['rev-parse', '--verify', '--end-of-options', revision],
+    'expected-commit no resoluble'
+  );
+  const head = ejecutarGit(constructorDir, ['rev-parse', 'HEAD'], 'HEAD no resoluble');
+  if (esperado !== head) {
+    throw new Error(`commit distinto: esperado ${esperado}; HEAD ${head}`);
+  }
+  const blobEsperado = ejecutarGit(
+    constructorDir,
+    ['rev-parse', 'HEAD:app/lib/loop-builder.ts'],
+    'loop-builder.ts no existe en HEAD'
+  );
+  const blobActual = ejecutarGit(
+    constructorDir,
+    ['hash-object', '--', 'app/lib/loop-builder.ts'],
+    'no se pudo calcular el blob actual de loop-builder.ts'
+  );
+  if (blobEsperado !== blobActual) {
+    throw new Error(`loop-builder.ts tiene cambios fuera de HEAD: ${blobEsperado} != ${blobActual}`);
+  }
+  const estadoCheckout = ejecutarGit(
+    constructorDir,
+    ['status', '--porcelain=v1', '--untracked-files=all'],
+    'no se pudo verificar el checkout completo'
+  );
+  if (estadoCheckout) throw new Error(`checkout tiene cambios fuera de HEAD: ${estadoCheckout}`);
+  return { expectedCommit: esperado, headCommit: head };
+}
+
+function ejecutarGate(builderPath, loopPath) {
+  try {
+    const salida = execFileSync(process.execPath, [
+      '--experimental-strip-types',
+      '--input-type=module',
+      '-e',
+      SCRIPT_GATE,
+      builderPath,
+      loopPath,
+    ], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 1024 * 1024 });
+    return JSON.parse(salida);
+  } catch (error) {
+    const detalle = String(error.stderr || error.stdout || error.message).trim();
+    throw new Error(`falló el gate de constructor-loops: ${detalle}`);
+  }
+}
+
+function validarResultado(resultado) {
+  if (!resultado || typeof resultado !== 'object' || Array.isArray(resultado)) {
+    throw new TypeError('resultado estructural inválido');
+  }
+  const desconocidos = Object.keys(resultado).filter((campo) => !CAMPOS_GATE.has(campo));
+  if (desconocidos.length > 0) {
+    throw new TypeError(`resultado estructural contiene campo desconocido: ${desconocidos[0]}`);
+  }
+  const reglas = resultado.matchedRules;
+  if (resultado.pass !== true) {
+    const hallazgos = Array.isArray(resultado.findings) ? resultado.findings.join('; ') : 'sin detalle';
+    throw new Error(`gate estructural rechazó el loop: ${hallazgos}`);
+  }
+  if (!Array.isArray(resultado.findings) || resultado.findings.length > 0) {
+    throw new Error('gate PASS contiene findings y se rechaza por inconsistencia');
+  }
+  if (typeof resultado.summary !== 'string' || !resultado.summary.trim()) {
+    throw new TypeError('gate PASS no contiene summary válido');
+  }
+  if (!Array.isArray(reglas) || reglas.length !== 10 || new Set(reglas).size !== 10) {
+    throw new Error('gate estructural no devolvió exactamente diez reglas PASS únicas');
+  }
+  if (!reglas.every((regla) => typeof regla === 'string' && regla.trim())) {
+    throw new TypeError('matchedRules contiene una regla inválida');
+  }
+  return resultado;
+}
+
+function verificarLoopConstructor(opciones) {
+  const entradas = resolverEntradas(opciones);
+  const commits = verificarCommit(entradas.constructorDir, opciones.expectedCommit);
+  const gate = validarResultado(ejecutarGate(entradas.builderPath, entradas.loopPath));
+  return {
+    pass: true,
+    expectedCommit: commits.expectedCommit,
+    headCommit: commits.headCommit,
+    summary: gate.summary,
+    findings: gate.findings,
+    matchedRules: gate.matchedRules,
+    ...entradas,
+  };
+}
+
+function imprimirResultado(resultado) {
+  console.log(`[constructor-loop] commit PASS: ${resultado.headCommit}`);
+  for (const regla of resultado.matchedRules) {
+    console.log(`[constructor-loop] regla PASS: ${regla}`);
+  }
+  console.log(`[constructor-loop] resultado PASS: ${resultado.summary}`);
+}
+
+function main(argv = process.argv.slice(2)) {
+  const args = parsearArgs(argv);
+  const resultado = verificarLoopConstructor({
+    constructorDir: args['constructor-dir'],
+    expectedCommit: args['expected-commit'],
+    loopPath: args.loop,
+  });
+  imprimirResultado(resultado);
+  return resultado;
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`[constructor-loop] ERROR: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = {
+  construirEntornoGit,
+  main,
+  parsearArgs,
+  verificarLoopConstructor,
+};

package/scripts/verificar-trazabilidad.js

@@ -18,7 +18,7 @@
  *              calidad-pre-commit) con marker `verifica: REQ-NN`
  *
  * Exit codes:
- *   0 — cadena completa, o CONTEXTO legacy sin REQ-IDs (gracia, con nota)
+ *   0 — cadena completa
  *   1 — huérfanos detectados (REQ sin tarea / sin commit / sin test)
  *   2 — error de invocación o parseo (fase inexistente, args inválidos)
  *
@@ -189,9 +189,16 @@ function validarFase({ cwd, fase, soloPlan }) {
   if (activos.length === 0) {
     return {
       fase: nn,
-      legacy: true,
-      nota: 'CONTEXTO sin REQ-IDs — trazabilidad no exigible (gracia legacy, fases pre-10)',
-      exit: 0,
+      legacy: false,
+      reqs: [],
+      retirados,
+      trazabilidad: {},
+      validaciones: {
+        contexto_sin_req: true,
+        req_sin_tarea: [], req_sin_commit: [], req_sin_test: [],
+        tarea_sin_req: [], headers_malformados: [],
+      },
+      exit: 1,
     };
   }
 
@@ -256,8 +263,8 @@ function imprimirReporte(r) {
     console.error(`ERROR: ${r.error}`);
     return;
   }
-  if (r.legacy) {
-    console.log(`Fase ${r.fase}: ${r.nota}. Exit 0.`);
+  if (r.validaciones.contexto_sin_req) {
+    console.log(`Fase ${r.fase}: CONTEXTO sin REQ explícitos — migración o inferencia legacy no satisface G4.`);
     return;
   }
   console.log(`Trazabilidad REQ→T→commit→test — Fase ${r.fase}${r.soloPlan ? ' (--solo-plan: matriz REQ×T)' : ''}`);