@saulwade/swl-ses 2.4.2 → 2.5.1

package/scripts/auditar-clases-conocidas.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * auditar-clases-conocidas.js — Gate de clases de bug ya documentadas.
+ *
+ * "El conocimiento documentado no previene — solo los gates previenen."
+ * Cada clase de este gate mordió al proyecto en producción pese a estar
+ * escrita como regla/aprendizaje. El gate la vuelve imposible de reintroducir:
+ *
+ *   C1 — Fecha UTC truncada: toISOString + slice(0,10) fecha artefactos
+ *        "mañana" desde México (23 instancias corregidas 2026-07-08/09).
+ *        Correcto: `toLocaleDateString('sv')`. Escape: `// fecha-utc-ok`.
+ *        (El patrón no se escribe literal aquí: el gate escanea este archivo
+ *        también — se auto-detectó en el publish v2.5.1.)
+ *   C2 — Comparación byte a byte en modos --check: comparar texto leído de
+ *        disco sin normalizar EOL revienta con CRLF tras checkout/reset de
+ *        git (tumbó el publish v2.5.0). Un script con modo --check que lee
+ *        texto debe normalizar `\r\n` o comparar estructuras (JSON.parse).
+ *        Escape: `// eol-ok: <razón>`.
+ *   C3 — Bloqueo ciego en hooks: exit(2) sin console.error deja al modelo
+ *        sin la razón del bloqueo (el canal de exit 2 es stderr).
+ *
+ * Alcance: archivos .js versionados en scripts/, hooks/, bin/, gateway/
+ * (tests/ excluido: los tests DEBEN poder citar el patrón para validarlo).
+ * Exit: 0 limpio · 1 con hallazgos.
+ */
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const RAIZ = path.resolve(__dirname, '..');
+
+const RX_UTC = /toISOString\(\)\s*\.\s*(?:slice|substring)\s*\(\s*0\s*,\s*10\s*\)/;
+const RX_ESCAPE_UTC = /fecha-utc-ok/;
+const RX_ESCAPE_EOL = /eol-ok:/;
+
+function archivosObjetivo() {
+  const salida = execFileSync('git', [
+    'ls-files', '--',
+    'scripts/*.js', 'scripts/**/*.js',
+    'hooks/*.js', 'hooks/**/*.js',
+    'bin/*.js',
+    'gateway/*.js', 'gateway/**/*.js',
+  ], { cwd: RAIZ, encoding: 'utf8' });
+  return salida.split(/\r?\n/).filter(f => f && !f.includes('vendor/'));
+}
+
+function auditarUtc(ruta, lineas, hallazgos) {
+  lineas.forEach((linea, i) => {
+    if (RX_UTC.test(linea) && !RX_ESCAPE_UTC.test(linea)) {
+      hallazgos.push(`[C1 fecha-UTC] ${ruta}:${i + 1} — toISOString().slice(0,10) fecha "mañana" desde UTC-6; usar toLocaleDateString('sv') o marcar \`// fecha-utc-ok\` si la semántica UTC es deliberada`);
+    }
+  });
+}
+
+function auditarEolCheck(ruta, contenido, hallazgos) {
+  // Aplica solo a GENERADORES con modo --check (escriben el artefacto y en
+  // check comparan lo regenerado contra disco). Un --check selector de
+  // sub-checks (verificar-docs) no compara texto por igualdad — no aplica.
+  if (!contenido.includes("'--check'") && !contenido.includes('"--check"')) return;
+  if (!/atomicWrite|writeFileSync/.test(contenido)) return;
+  if (!/readFileSync\([^)]*utf-?8/i.test(contenido)) return;
+  const normaliza = contenido.includes('\\r\\n') || contenido.includes('\\r?\\n');
+  const comparaEstructura = contenido.includes('JSON.parse');
+  const escape = RX_ESCAPE_EOL.test(contenido);
+  if (!normaliza && !comparaEstructura && !escape) {
+    hallazgos.push(`[C2 EOL] ${ruta} — modo --check que lee texto sin normalizar \\r\\n ni comparar estructuras: reventará con CRLF tras checkout/reset de git (caso publish v2.5.0). Normalizar EOL antes de comparar o marcar \`// eol-ok: <razón>\``);
+  }
+}
+
+function auditarBloqueoCiego(ruta, contenido, hallazgos) {
+  if (!ruta.startsWith('hooks/') || ruta.startsWith('hooks/lib/')) return;
+  const usaExit2 = /exit\(2\)|exitCode\s*=\s*2/.test(contenido);
+  const escribeStderr = contenido.includes('console.error') || contenido.includes('process.stderr.write');
+  if (usaExit2 && !escribeStderr) {
+    hallazgos.push(`[C3 bloqueo-ciego] ${ruta} — usa exit 2 sin escribir a stderr (console.error/process.stderr.write): el modelo recibe el bloqueo sin la razón`);
+  }
+}
+
+function main() {
+  const hallazgos = [];
+  const archivos = archivosObjetivo();
+  for (const ruta of archivos) {
+    let contenido;
+    try {
+      contenido = fs.readFileSync(path.join(RAIZ, ruta), 'utf8');
+    } catch { continue; }
+    const lineas = contenido.split(/\r?\n/);
+    auditarUtc(ruta, lineas, hallazgos);
+    auditarEolCheck(ruta, contenido, hallazgos);
+    auditarBloqueoCiego(ruta, contenido, hallazgos);
+  }
+
+  if (hallazgos.length === 0) {
+    console.log(`[clases-conocidas] OK — ${archivos.length} archivos, 0 reincidencias de clases documentadas (C1 UTC, C2 EOL, C3 bloqueo ciego)`);
+    return;
+  }
+  console.error(`[clases-conocidas] ${hallazgos.length} reincidencia(s) de clases de bug documentadas:`);
+  for (const h of hallazgos) console.error('  ' + h);
+  process.exitCode = 1;
+}
+
+module.exports = { auditarUtc, auditarEolCheck, auditarBloqueoCiego };
+if (require.main === module) main();

package/scripts/bootstrap-instintos.js

@@ -159,7 +159,7 @@ function truncate(s, n) {
 }
 
 function generarInstintos(entradas) {
-  const hoy = new Date().toISOString().slice(0, 10);
+  const hoy = new Date().toLocaleDateString('sv');
   return entradas.map((e, idx) => {
     const { confidence, tags } = detectarConfidence(e.seccion);
     const pattern = truncate(e.titulo, 200);
@@ -190,7 +190,7 @@ function generarInstintos(entradas) {
 }
 
 function serializarYaml(instintos) {
-  const fechaActual = new Date().toISOString().slice(0, 10);
+  const fechaActual = new Date().toLocaleDateString('sv');
   const header = `# Instintos del Proyecto — SWL-SES
 # Generado automáticamente por scripts/bootstrap-instintos.js desde .planning/APRENDIZAJES.md
 # Formato estandarizado v1.0

package/scripts/canario-hooks.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * canario-hooks.js — Canario de hooks: prueba que cada hook es viable y visible.
+ *
+ * Clase que cierra: "hook que funciona perfecto y nadie ve". Dos muertes
+ * silenciosas documentadas: (a) check-update requería libs de scripts/lib/ no
+ * distribuidas — MODULE_NOT_FOUND tragado por el wrapper en TODA instalación
+ * destino desde su creación; (b) avisos emitidos por stderr con exit 0 (canal
+ * invisible). La (b) la cubre auditar-clases-conocidas C3; este canario cubre
+ * la (a) y la ejecución real.
+ *
+ * Modo default (rápido — test:all):
+ *   Por cada hook ejecutable de hooks/*.js, extrae su grafo de requires
+ *   relativos (transitivo) y verifica que todo archivo que EXISTE en el repo
+ *   esté registrado en manifiestos/modulos.json — si no, el instalador no lo
+ *   distribuye y el hook muere en silencio en el destino. Paths de fallback
+ *   que no existen en el repo (patrón de require tolerante) se omiten.
+ *
+ * Modo --smoke (test:release):
+ *   Además EJECUTA cada hook en un sandbox temporal (cwd aislado — las
+ *   escrituras de telemetría van al sandbox) con un evento JSON mínimo por
+ *   stdin. FALLA si el hook crashea (exit ≠ 0 y ≠ 2). Timeout (5s) es WARN
+ *   informativo, no fallo: un hook lento no rompe la sesión (el harness lo
+ *   corta), pero un hook que crashea al cargar es la clase (a) viva.
+ *   Reporta tabla de visibilidad (bytes stdout/stderr) para auditoría humana.
+ *
+ * Exit: 0 limpio · 1 con fallas.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const RAIZ = path.resolve(__dirname, '..');
+const SMOKE = process.argv.includes('--smoke');
+const RX_REQUIRE = /require\(\s*['"](\.[^'"]+)['"]\s*\)/g;
+
+function hooksEjecutables() {
+  // Forward slashes SIEMPRE: se comparan contra modulos.json (formato repo).
+  return fs.readdirSync(path.join(RAIZ, 'hooks'))
+    .filter(f => f.endsWith('.js'))
+    .map(f => `hooks/${f}`);
+}
+
+function archivosRegistrados() {
+  const m = JSON.parse(fs.readFileSync(path.join(RAIZ, 'manifiestos', 'modulos.json'), 'utf8'));
+  const set = new Set();
+  for (const mod of Object.values(m.modulos || {})) {
+    for (const a of mod.archivos || []) set.add(a.replace(/\\/g, '/'));
+  }
+  return set;
+}
+
+/** Resuelve un require relativo a .js real (agrega .js / index.js). */
+function resolverRequire(desdeArchivo, spec) {
+  const base = path.resolve(RAIZ, path.dirname(desdeArchivo), spec);
+  for (const cand of [base, `${base}.js`, path.join(base, 'index.js'), `${base}.json`]) {
+    if (fs.existsSync(cand) && fs.statSync(cand).isFile()) {
+      return path.relative(RAIZ, cand).replace(/\\/g, '/');
+    }
+  }
+  return null; // fallback de require tolerante que solo existe en el destino
+}
+
+/** Grafo transitivo de requires relativos que existen en el repo. */
+function grafoRequires(archivoInicial) {
+  const vistos = new Set();
+  const pila = [archivoInicial];
+  while (pila.length > 0) {
+    const actual = pila.pop();
+    if (vistos.has(actual)) continue;
+    vistos.add(actual);
+    let contenido;
+    try { contenido = fs.readFileSync(path.join(RAIZ, actual), 'utf8'); } catch { continue; }
+    for (const m of contenido.matchAll(RX_REQUIRE)) {
+      const resuelto = resolverRequire(actual, m[1]);
+      if (resuelto && !vistos.has(resuelto)) pila.push(resuelto);
+    }
+  }
+  vistos.delete(archivoInicial);
+  return [...vistos];
+}
+
+function verificarDistribucion(hooks, registrados, fallas) {
+  for (const hook of hooks) {
+    if (!registrados.has(hook)) {
+      fallas.push(`${hook} — el hook mismo no está registrado en modulos.json (no se distribuye)`);
+    }
+    for (const dep of grafoRequires(hook)) {
+      if (dep.endsWith('.json')) continue; // datos empaquetados aparte
+      if (!registrados.has(dep)) {
+        fallas.push(`${hook} — requiere ${dep}, que existe en el repo pero NO está en modulos.json: en el destino el require lanza MODULE_NOT_FOUND y el wrapper lo traga (clase check-update)`);
+      }
+    }
+  }
+}
+
+const EVENTO_MINIMO = JSON.stringify({
+  session_id: 'canario-smoke',
+  hook_event_name: 'PostToolUse',
+  tool_name: 'Write',
+  tool_input: { file_path: 'canario.md', content: 'canario' },
+  tool_response: { success: true },
+});
+
+function smokeEjecutar(hooks, fallas) {
+  const sandbox = fs.mkdtempSync(path.join(os.tmpdir(), 'swl-canario-'));
+  const tabla = [];
+  try {
+    for (const hook of hooks) {
+      const r = spawnSync(process.execPath, [path.join(RAIZ, hook)], {
+        cwd: sandbox,
+        input: EVENTO_MINIMO,
+        encoding: 'utf8',
+        timeout: 5000,
+        env: { ...process.env, SWL_CANARIO_SMOKE: '1' },
+      });
+      const nombre = path.basename(hook);
+      if (r.error && r.error.code === 'ETIMEDOUT') {
+        tabla.push(`  [WARN timeout] ${nombre} — >5s con evento mínimo (no rompe la sesión, pero revisar)`);
+        continue;
+      }
+      const exit = r.status;
+      if (exit !== 0 && exit !== 2) {
+        const stderr = (r.stderr || '').split(/\r?\n/).find(l => l.trim()) || 'sin stderr';
+        fallas.push(`${hook} — crasheó con exit ${exit} ante evento mínimo: ${stderr.slice(0, 140)}`);
+        continue;
+      }
+      const out = (r.stdout || '').length;
+      const err = (r.stderr || '').length;
+      tabla.push(`  [ok exit ${exit}] ${nombre} — stdout:${out}B stderr:${err}B${exit === 0 && out === 0 && err > 0 ? '  ← solo stderr con exit 0: si esto es un aviso al usuario, es invisible (C3-runtime)' : ''}`);
+    }
+  } finally {
+    try { fs.rmSync(sandbox, { recursive: true, force: true }); } catch { /* mejor esfuerzo */ }
+  }
+  return tabla;
+}
+
+function main() {
+  const hooks = hooksEjecutables();
+  const registrados = archivosRegistrados();
+  const fallas = [];
+
+  verificarDistribucion(hooks, registrados, fallas);
+
+  let tabla = [];
+  if (SMOKE) tabla = smokeEjecutar(hooks, fallas);
+
+  if (tabla.length > 0) {
+    console.log('[canario-hooks] Visibilidad por hook (smoke en sandbox):');
+    for (const l of tabla) console.log(l);
+  }
+  if (fallas.length === 0) {
+    console.log(`[canario-hooks] OK — ${hooks.length} hooks: grafo de requires distribuido completo${SMOKE ? ' + smoke sin crashes' : ''}`);
+    return;
+  }
+  console.error(`[canario-hooks] ${fallas.length} falla(s):`);
+  for (const f of fallas) console.error('  - ' + f);
+  process.exitCode = 1;
+}
+
+module.exports = { grafoRequires, resolverRequire };
+if (require.main === module) main();

package/scripts/cli/configurar-ci.js

@@ -6,7 +6,7 @@
  * relativos al proyecto (rotos downstream; ver docs/invocacion-cli-cross-scope.md).
  *
  * Ops (todas imprimen el resultado como JSON para que el comando lo inspeccione):
- *   init      [--no-security] [--no-ci] [--with-release-please] [--dry-run] [--force]
+ *   init      [--no-security] [--no-ci] [--with-release-please] [--with-devsecops] [--dry-run] [--force]
  *   status    (default)
  *   uninstall [--confirmar]
  */
@@ -21,6 +21,7 @@ function configurarCi(opciones = {}) {
       withSecurity: !opciones['no-security'],
       withCi: !opciones['no-ci'],
       withReleasePlease: !!opciones['with-release-please'],
+      withDevsecops: !!opciones['with-devsecops'],
       dryRun: !!opciones['dry-run'],
       force: !!opciones.force,
     });

package/scripts/evidencia-valor.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * evidencia-valor.js — CLI `swl-ses valor`: panel de evidencia de valor del
+ * harness en el proyecto downstream actual.
+ *
+ * Uso:
+ *   swl-ses valor                # panel legible (ventana 30 días)
+ *   swl-ses valor --dias 90      # ventana distinta
+ *   swl-ses valor --json         # salida JSON para tooling
+ *
+ * Reglas duras del panel (docs/evidencia-valor.md):
+ *   - Cada métrica declara su PROCEDENCIA (git / GitHub / hook-event) y su
+ *     CARÁCTER (evidencia | proxy | contexto). Nunca scores autodeclarados.
+ *   - Todo se lee LOCAL. El repo madre no lee estos datos.
+ */
+
+const { panelEvidencia } = require('./lib/evidencia-valor.js');
+
+function main() {
+  const argv = process.argv.slice(2);
+  const json = argv.includes('--json');
+  const idx = argv.indexOf('--dias');
+  const ventanaDias = idx !== -1 ? parseInt(argv[idx + 1], 10) || 30 : 30;
+
+  const p = panelEvidencia(process.cwd(), { ventanaDias });
+
+  if (json) {
+    console.log(JSON.stringify(p, null, 2));
+    return;
+  }
+
+  console.log(`Evidencia de valor — ventana ${p.ventanaDias} días (${p.generado})`);
+  console.log(`  ${p.frontera}`);
+  console.log('');
+
+  const i = p.intercepciones;
+  console.log('1. Intercepciones de gates [evidencia · hook-event]');
+  if (!i.disponible) {
+    console.log(`   no disponible — ${i.razon}`);
+  } else {
+    console.log(`   intervenciones: ${i.intervenciones} de ${i.totalEventos} eventos`);
+    const tipos = Object.entries(i.porTipo).sort((a, b) => b[1] - a[1]).slice(0, 6);
+    for (const [t, n] of tipos) console.log(`     - ${t}: ${n}`);
+  }
+  console.log('');
+
+  const d = p.defectos;
+  console.log('2. Presión de defectos [proxy · git log]');
+  if (!d.disponible) {
+    console.log(`   no disponible — ${d.razon}`);
+  } else {
+    console.log(`   commits: ${d.commits} | fix: ${d.fixes} | feat: ${d.feats} | ratio fix/feat: ${d.ratioFixFeat ?? 'n/a'}`);
+    if (d.escapes.disponible) {
+      console.log(`   escapes: ${d.escapes.fixesTrasUltimaVerificacion} fix tras la última verificación (${d.escapes.ultimaVerificacion}) — ${d.escapes.nota}`);
+    } else {
+      console.log(`   escapes: no disponible — ${d.escapes.razon}`);
+    }
+  }
+  console.log('');
+
+  const dc = p.doraCi;
+  console.log('3. DORA-lite + CI [evidencia de tendencia · git + GitHub]');
+  if (!dc.disponible) {
+    console.log(`   no disponible — ${dc.razon}`);
+  } else {
+    const dora = dc.dora;
+    const nd = m => `n/d (${(m && m.razon) || 'sin datos'})`;
+    const df = dora.deploymentFrequency;
+    console.log(`   deployment frequency: ${df && df.disponible !== false && df.valor != null ? `${df.valor} deploys/semana [${df.clasificacion}]` : nd(df)}`);
+    const lt = dora.leadTime;
+    console.log(`   lead time: ${lt && lt.disponible !== false && lt.p50Horas != null ? `p50 ${(+lt.p50Horas).toFixed(1)}h / p95 ${(+lt.p95Horas).toFixed(1)}h [${lt.clasificacion}]` : nd(lt)}`);
+    const cfr = dora.changeFailureRate;
+    console.log(`   change failure rate: ${cfr && cfr.disponible !== false && cfr.valor != null ? `${cfr.valor}% [${cfr.clasificacion || ''}]` : nd(cfr)}`);
+    const mt = dora.mttr;
+    console.log(`   mttr: ${mt && mt.disponible !== false && mt.mttrHoras != null ? `${mt.mttrHoras}h` : nd(mt)}`);
+    console.log('   (correlación con la adopción del flujo — no causalidad)');
+  }
+  console.log('');
+
+  const u = p.uso;
+  console.log('4. Uso del sistema [contexto · telemetría]');
+  if (!u.disponible) {
+    console.log(`   no disponible — ${u.razon}`);
+  } else {
+    console.log(`   invocaciones de skills: ${u.invocaciones} | top: ${u.top5.join(', ')}`);
+  }
+  console.log('');
+  console.log('Compartir agregados con el autor (opt-in): swl-ses field-report — ver docs/evidencia-valor.md');
+}
+
+main();

package/scripts/field-report.js

@@ -163,7 +163,7 @@ function generarReporte() {
   const sorted = (obj) => Object.entries(obj).sort((a, b) => b[1] - a[1]);
 
   console.log('# Reporte de Validación en Campo — swl-ses');
-  console.log(`\n**Fecha**: ${new Date().toISOString().slice(0, 10)}`);
+  console.log(`\n**Fecha**: ${new Date().toLocaleDateString('sv')}`);
   console.log(`**Sesiones analizadas**: ${totales.sesiones}`);
   console.log(`**Proyectos**: ${totales.proyectos.size}`);
   console.log(`**Tool calls totales**: ${totales.toolCalls}`);

package/scripts/generar-comandos.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * generar-comandos.js — Regenera los bloques de catálogo de comandos /swl:*
+ * en COMANDOS.md y AGENTS.md desde el frontmatter de comandos/swl/*.md.
+ *
+ * La fuente de verdad es el frontmatter (name, description, argument-hint);
+ * mantener las tablas a mano acumuló drift recurrente (auditoría 2026-07-08:
+ * 6 comandos ausentes en AGENTS.md, flags desactualizados en COMANDOS.md).
+ * Solo se reescribe el contenido entre los marcadores:
+ *
+ *   <!-- BEGIN:CATALOGO-COMANDOS ... -->
+ *   <!-- END:CATALOGO-COMANDOS -->
+ *
+ * La prosa de decisión (matriz situación→comando, gates) queda fuera de los
+ * marcadores y se mantiene a mano.
+ *
+ * Uso:
+ *   node scripts/generar-comandos.js            # regenera ambos archivos
+ *   node scripts/generar-comandos.js --check    # exit 2 si hay drift (uso CI)
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const { leerFrontmatter, resumir } = require('./lib/frontmatter-md.js');
+
+const RAIZ = path.resolve(__dirname, '..');
+
+let atomicWriteSync;
+try {
+  ({ atomicWriteSync } = require(path.join(RAIZ, 'hooks', 'lib', 'atomic-write.js')));
+} catch {
+  atomicWriteSync = (p, c, e) => fs.writeFileSync(p, c, e);
+}
+
+const CHECK = process.argv.includes('--check');
+const MARCA_INICIO = /<!-- BEGIN:CATALOGO-COMANDOS[^>]*-->/;
+const MARCA_FIN    = '<!-- END:CATALOGO-COMANDOS -->';
+
+function recolectarComandos() {
+  const dir = path.join(RAIZ, 'comandos', 'swl');
+  return fs.readdirSync(dir)
+    .filter(f => f.endsWith('.md'))
+    .map(f => {
+      const fm = leerFrontmatter(path.join(dir, f));
+      return {
+        archivo: f,
+        name: fm.name || `swl:${f.replace('.md', '')}`,
+        description: fm.description || '',
+        argumentHint: fm['argument-hint'] || fm.argument_hint || '—',
+      };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Tabla completa para COMANDOS.md: comando + argumentos/flags + descripción. */
+function bloqueComandosMd(comandos) {
+  const L = [];
+  L.push(`Catálogo de los ${comandos.length} comandos, generado desde el frontmatter`);
+  L.push('de `comandos/swl/*.md` (fuente de verdad de flags y semántica).');
+  L.push('');
+  L.push('| Comando | Argumentos y flags | Descripción |');
+  L.push('|---------|--------------------|-------------|');
+  for (const c of comandos) {
+    L.push(`| \`/${c.name}\` | \`${resumir(c.argumentHint, 120)}\` | ${resumir(c.description, 260)} |`);
+  }
+  return L.join('\n');
+}
+
+/** Tabla compacta para AGENTS.md: comando + propósito. */
+function bloqueAgentsMd(comandos) {
+  const L = [];
+  L.push(`Los ${comandos.length} comandos del sistema, generados desde el frontmatter`);
+  L.push('de `comandos/swl/*.md`. Detalle de flags: `COMANDOS.md`; operación: `MANUAL_USO.md`.');
+  L.push('');
+  L.push('| Comando | Propósito |');
+  L.push('|---------|-----------|');
+  for (const c of comandos) {
+    L.push(`| \`/${c.name}\` | ${resumir(c.description, 200)} |`);
+  }
+  return L.join('\n');
+}
+
+/** Reemplaza el contenido entre marcadores. Devuelve null si faltan marcadores. */
+function inyectar(contenido, bloque) {
+  const ini = contenido.search(MARCA_INICIO);
+  const fin = contenido.indexOf(MARCA_FIN);
+  if (ini === -1 || fin === -1 || fin < ini) return null;
+  const finMarcaIni = contenido.indexOf('-->', ini) + 3;
+  return contenido.slice(0, finMarcaIni) + '\n\n' + bloque + '\n\n' + contenido.slice(fin);
+}
+
+/**
+ * Aplica el bloque al contenido crudo del archivo, tolerante a EOL.
+ *
+ * La comparación se hace SIEMPRE en LF: con `core.autocrlf=true` git puede
+ * reescribir el working tree con CRLF sin que el contenido cambie (checkout,
+ * reset, stash) — un compare byte a byte reporta DRIFT falso con catálogo
+ * idéntico (caso real: reventó el `prepublishOnly` del publish v2.5.0). La
+ * salida preserva el EOL dominante del archivo para no producir mixtos.
+ *
+ * @returns {{estado: 'sin-marcadores'|'sin-cambios'|'drift', salida?: string}}
+ */
+function aplicarBloque(crudo, bloque) {
+  const eol = crudo.includes('\r\n') ? '\r\n' : '\n';
+  const actual = crudo.replace(/\r\n/g, '\n');
+  const nuevo = inyectar(actual, bloque);
+  if (nuevo === null) return { estado: 'sin-marcadores' };
+  if (nuevo === actual) return { estado: 'sin-cambios' };
+  return { estado: 'drift', salida: eol === '\r\n' ? nuevo.replace(/\n/g, '\r\n') : nuevo };
+}
+
+function procesar(archivo, bloque) {
+  const ruta = path.join(RAIZ, archivo);
+  const crudo = fs.readFileSync(ruta, 'utf8');
+  const r = aplicarBloque(crudo, bloque);
+  if (r.estado === 'sin-marcadores') {
+    console.error(`[generar-comandos] ${archivo}: faltan los marcadores BEGIN/END:CATALOGO-COMANDOS`);
+    process.exitCode = 1;
+    return false;
+  }
+  if (r.estado === 'sin-cambios') {
+    console.log(`[generar-comandos] ${archivo}: sin cambios`);
+    return true;
+  }
+  if (CHECK) {
+    console.error(`[generar-comandos] DRIFT en ${archivo}: el catálogo no coincide con el frontmatter. Regenerar con \`node scripts/generar-comandos.js\`.`);
+    process.exitCode = 2;
+    return false;
+  }
+  atomicWriteSync(ruta, r.salida, 'utf8');
+  console.log(`[generar-comandos] ${archivo}: catálogo regenerado (${bloque.split('\n').length} líneas)`);
+  return true;
+}
+
+module.exports = { inyectar, aplicarBloque };
+
+if (require.main === module) {
+  const comandos = recolectarComandos();
+  procesar('COMANDOS.md', bloqueComandosMd(comandos));
+  procesar('AGENTS.md', bloqueAgentsMd(comandos));
+}