@saulwade/swl-ses 2.0.0 → 2.1.0

package/scripts/lib/git-metricas.js

@@ -0,0 +1,257 @@
+'use strict';
+
+/**
+ * git-metricas.js
+ *
+ * Métricas DORA derivables SOLO de git (sin CI), para el proyecto destino donde
+ * SWL está instalado:
+ *   - deployment frequency: tags de release en una ventana -> deploys/semana.
+ *   - lead time for changes: commit más antiguo desde el release previo -> tag
+ *     actual (p50/p95).
+ *   - detección de degradación de entrega: compara ventana actual vs previa
+ *     (consumido por el recolector del briefing — git-only, <200ms, NUNCA gh).
+ *
+ * "deployment" = tag de release que matchea `patronTag` (default /^v?\d+\.\d+\.\d+/).
+ *
+ * Funciones puras zero-deps. git vía execFileSync sin shell, con try/catch que
+ * degrada a `{disponible:false}` (no es repo) o a 0/sinDatos (repo sin tags).
+ * Entrypoint CLI `--json`. Parte de la Fase 15 (ADR-0039).
+ */
+
+const { execFileSync } = require('node:child_process');
+
+const PATRON_TAG_DEFAULT = /^v?\d+\.\d+\.\d+/;
+// Rango git válido: prohíbe `-` inicial en cada extremo (defensa en profundidad
+// contra un refname que git interpretaría como flag de `git log`). Los nombres
+// vienen de `git for-each-ref` —git ya rechaza refs con `-` inicial—, pero la
+// validación local cierra el hueco si el origen del rango cambiara (H-02).
+const RE_RANGO_VALIDO =
+  /^(?!-)[A-Za-z0-9_./@~^][A-Za-z0-9_./@~^-]*(\.\.\.?(?!-)[A-Za-z0-9_./@~^][A-Za-z0-9_./@~^-]*)?$/;
+const MS_DIA = 24 * 60 * 60 * 1000;
+const MS_HORA = 60 * 60 * 1000;
+const GIT_MAX_BUFFER = 8 * 1024 * 1024; // 8 MiB
+const GIT_TIMEOUT_MS = 5000; // evita hangs (H-04); el recolector del briefing degrada si git cuelga
+
+function _git(baseDir, args) {
+  return execFileSync('git', args, {
+    cwd: baseDir,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    maxBuffer: GIT_MAX_BUFFER,
+    timeout: GIT_TIMEOUT_MS,
+  });
+}
+
+/**
+ * Lista tags que matchean patronTag con su fecha de creación.
+ * @returns {Array<{name:string, date:Date}>|null} null si no es repo git.
+ */
+function _gitTagsConFecha(baseDir, patronTag = PATRON_TAG_DEFAULT) {
+  let salida;
+  try {
+    salida = _git(baseDir, [
+      'for-each-ref',
+      '--sort=creatordate',
+      '--format=%(refname:short)|%(creatordate:iso-strict)',
+      'refs/tags',
+    ]);
+  } catch {
+    return null; // no es repo git / git no disponible
+  }
+  const tags = [];
+  for (const linea of salida.split('\n')) {
+    const l = linea.trim();
+    if (!l) continue;
+    const sep = l.lastIndexOf('|');
+    if (sep === -1) continue;
+    const name = l.slice(0, sep);
+    const iso = l.slice(sep + 1);
+    if (!patronTag.test(name)) continue;
+    const t = Date.parse(iso);
+    if (!Number.isFinite(t)) continue;
+    tags.push({ name, date: new Date(t) });
+  }
+  tags.sort((a, b) => a.date - b.date);
+  return tags;
+}
+
+/** ISO del commit más antiguo (primero) de un rango git, o null. */
+function _primerCommitISO(baseDir, rango) {
+  if (!RE_RANGO_VALIDO.test(rango)) return null;
+  let salida;
+  try {
+    salida = _git(baseDir, ['log', rango, '--reverse', '--format=%cI', '--']);
+  } catch {
+    return null;
+  }
+  const primera = salida.split('\n').map((s) => s.trim()).filter(Boolean)[0];
+  return primera || null;
+}
+
+// Nearest-rank (ceil), no interpolación. Con 2 muestras [a,b] y p=50 → a.
+function _percentil(valoresOrdenados, p) {
+  if (valoresOrdenados.length === 0) return null;
+  const idx = Math.ceil((p / 100) * valoresOrdenados.length) - 1;
+  return valoresOrdenados[Math.max(0, Math.min(idx, valoresOrdenados.length - 1))];
+}
+
+function _enVentana(date, desde, hasta) {
+  return date >= desde && date <= hasta;
+}
+
+/**
+ * Deployment frequency en la ventana.
+ * @returns {{disponible:boolean, totalDeploys?:number, deploysPorSemana?:number,
+ *            sinDatos?:boolean, razon?:string}}
+ */
+function deploymentFrequency(baseDir, opts = {}) {
+  const { ventanaDias = 30, hoy = new Date(), patronTag = PATRON_TAG_DEFAULT } = opts;
+  const tags = _gitTagsConFecha(baseDir, patronTag);
+  if (tags === null) return { disponible: false, razon: 'no es un repositorio git' };
+
+  const desde = new Date(hoy.getTime() - ventanaDias * MS_DIA);
+  const enVentana = tags.filter((t) => _enVentana(t.date, desde, hoy));
+  const semanas = ventanaDias / 7;
+  return {
+    disponible: true,
+    totalDeploys: enVentana.length,
+    deploysPorSemana: semanas > 0 ? enVentana.length / semanas : 0,
+    sinDatos: tags.length === 0,
+  };
+}
+
+/** Lead times (horas) commit->tag para tags en [desde,hasta]. */
+function _leadTimesEnVentana(baseDir, tags, desde, hasta) {
+  const horas = [];
+  for (let i = 0; i < tags.length; i++) {
+    const tag = tags[i];
+    if (!_enVentana(tag.date, desde, hasta)) continue;
+    const prev = tags[i - 1];
+    const rango = prev ? `${prev.name}..${tag.name}` : tag.name;
+    const primeroISO = _primerCommitISO(baseDir, rango);
+    if (!primeroISO) continue;
+    const t = Date.parse(primeroISO);
+    if (!Number.isFinite(t)) continue;
+    const h = (tag.date.getTime() - t) / MS_HORA;
+    if (h >= 0) horas.push(h);
+  }
+  return horas.sort((a, b) => a - b);
+}
+
+/**
+ * Lead time for changes (commit->tag) en la ventana.
+ * @returns {{disponible:boolean, p50Horas?:number, p95Horas?:number,
+ *            muestras?:number, sinDatos?:boolean, razon?:string}}
+ */
+function leadTimeForChanges(baseDir, opts = {}) {
+  const { ventanaDias = 30, hoy = new Date(), patronTag = PATRON_TAG_DEFAULT } = opts;
+  const tags = _gitTagsConFecha(baseDir, patronTag);
+  if (tags === null) return { disponible: false, razon: 'no es un repositorio git' };
+
+  const desde = new Date(hoy.getTime() - ventanaDias * MS_DIA);
+  const horas = _leadTimesEnVentana(baseDir, tags, desde, hoy);
+  if (horas.length === 0) {
+    return { disponible: true, sinDatos: true, muestras: 0, p50Horas: null, p95Horas: null };
+  }
+  return {
+    disponible: true,
+    sinDatos: false,
+    muestras: horas.length,
+    p50Horas: _percentil(horas, 50),
+    p95Horas: _percentil(horas, 95),
+  };
+}
+
+/**
+ * Detecta degradación de entrega comparando la ventana actual vs la previa de
+ * igual duración. Git-only y rápido — apto para el recolector del briefing.
+ * Degradación = deploy freq cae >50% O lead time mediano sube >50%.
+ * @returns {{disponible:boolean, degradado:boolean, motivo:(string|null),
+ *            deployFreqActual:number, deployFreqPrevia:number,
+ *            leadTimeP50Actual:(number|null), leadTimeP50Previo:(number|null)}}
+ */
+function detectarDegradacionEntrega(baseDir, opts = {}) {
+  const { ventanaDias = 30, hoy = new Date(), patronTag = PATRON_TAG_DEFAULT } = opts;
+  const tags = _gitTagsConFecha(baseDir, patronTag);
+  if (tags === null) {
+    return {
+      disponible: false,
+      degradado: false,
+      motivo: null,
+      deployFreqActual: 0,
+      deployFreqPrevia: 0,
+      leadTimeP50Actual: null,
+      leadTimeP50Previo: null,
+    };
+  }
+
+  const finActual = hoy;
+  const inicioActual = new Date(hoy.getTime() - ventanaDias * MS_DIA);
+  const inicioPrevio = new Date(hoy.getTime() - 2 * ventanaDias * MS_DIA);
+  const semanas = ventanaDias / 7;
+
+  const deploysActual = tags.filter((t) => _enVentana(t.date, inicioActual, finActual)).length;
+  const deploysPrevio = tags.filter((t) => _enVentana(t.date, inicioPrevio, inicioActual)).length;
+  const deployFreqActual = semanas > 0 ? deploysActual / semanas : 0;
+  const deployFreqPrevia = semanas > 0 ? deploysPrevio / semanas : 0;
+
+  const ltActual = _percentil(_leadTimesEnVentana(baseDir, tags, inicioActual, finActual), 50);
+  const ltPrevio = _percentil(_leadTimesEnVentana(baseDir, tags, inicioPrevio, inicioActual), 50);
+
+  const motivos = [];
+  if (deployFreqPrevia > 0 && deployFreqActual < deployFreqPrevia * 0.5) {
+    motivos.push(
+      `deployment frequency cayó >50% (${deployFreqPrevia.toFixed(2)} → ${deployFreqActual.toFixed(2)} deploys/semana)`
+    );
+  }
+  if (ltPrevio !== null && ltActual !== null && ltActual > ltPrevio * 1.5) {
+    motivos.push(
+      `lead time mediano subió >50% (${ltPrevio.toFixed(1)}h → ${ltActual.toFixed(1)}h)`
+    );
+  }
+
+  return {
+    disponible: true,
+    degradado: motivos.length > 0,
+    motivo: motivos.length > 0 ? motivos.join('; ') : null,
+    deployFreqActual,
+    deployFreqPrevia,
+    leadTimeP50Actual: ltActual,
+    leadTimeP50Previo: ltPrevio,
+  };
+}
+
+module.exports = {
+  deploymentFrequency,
+  leadTimeForChanges,
+  detectarDegradacionEntrega,
+  PATRON_TAG_DEFAULT,
+  _gitTagsConFecha,
+};
+
+// Entrypoint CLI: node scripts/lib/git-metricas.js [--json] [--dias=N] [baseDir]
+if (!require.main || require.main === module) {
+  const args = process.argv.slice(2);
+  const json = args.includes('--json');
+  const diasArg = args.find((a) => a.startsWith('--dias='));
+  const ventanaDias = Math.max(1, Math.min(365, (diasArg ? parseInt(diasArg.slice('--dias='.length), 10) : 30) || 30));
+  const baseDir = args.find((a) => !a.startsWith('--')) || process.cwd();
+
+  const out = {
+    ventana_dias: ventanaDias,
+    deploymentFrequency: deploymentFrequency(baseDir, { ventanaDias }),
+    leadTime: leadTimeForChanges(baseDir, { ventanaDias }),
+    degradacion: detectarDegradacionEntrega(baseDir, { ventanaDias }),
+  };
+
+  if (json) {
+    process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+  } else {
+    const df = out.deploymentFrequency;
+    const lt = out.leadTime;
+    process.stdout.write(`Deployment frequency: ${df.disponible ? (df.sinDatos ? 'sin datos' : df.deploysPorSemana.toFixed(2) + ' deploys/semana') : 'no disponible'}\n`);
+    process.stdout.write(`Lead time (p50/p95): ${lt.disponible && !lt.sinDatos ? `${lt.p50Horas.toFixed(1)}h / ${lt.p95Horas.toFixed(1)}h` : 'sin datos'}\n`);
+    process.stdout.write(`Degradación: ${out.degradacion.degradado ? out.degradacion.motivo : 'no'}\n`);
+  }
+  process.exit(0);
+}

package/scripts/lib/metricas-dora.js

@@ -0,0 +1,204 @@
+'use strict';
+
+/**
+ * metricas-dora.js
+ *
+ * Compone las 4 métricas DORA del proyecto destino y las clasifica en
+ * elite/high/medium/low según los umbrales del DORA Report 2023:
+ *   - deployment frequency + lead time desde git (siempre, git-metricas.js).
+ *   - change failure rate + MTTR desde gh (degrada si ausente, ci-reader.js).
+ *
+ * Persiste el informe en `.planning/evolution/metricas-dora.json` (runtime).
+ * Entrypoint CLI `--json`. Parte de la Fase 15 (ADR-0039).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const gitMetricas = require('./git-metricas');
+const ciReader = require('./ci-reader');
+
+let atomicWriteJSON;
+try {
+  ({ atomicWriteJSON } = require('../../hooks/lib/atomic-write'));
+} catch (err) {
+  if (err.code !== 'MODULE_NOT_FOUND') throw err;
+  atomicWriteJSON = (p, obj) => {
+    const dir = path.dirname(p);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(obj, null, 2), 'utf8');
+  };
+}
+
+const STORAGE_REL = path.join('.planning', 'evolution', 'metricas-dora.json');
+
+/**
+ * Umbrales DORA Report 2023 (Accelerate State of DevOps). Boundaries expresados
+ * en las unidades internas de cada métrica. Ajustar aquí si el reporte cambia.
+ *
+ * - deploymentFrequency (deploys/semana, mayor es mejor):
+ *   elite ≥1/día (7/sem) · high ≥1/mes (0.23/sem) · medium ≥1/semestre (0.038/sem) · low <semestral.
+ * - leadTimeHoras (commit→tag, menor es mejor): elite <1día · high <1sem · medium <1mes · low ≥1mes.
+ * - changeFailureRate (0..1, menor es mejor): elite ≤0.15 · high ≤0.30 · medium ≤0.45 · low >0.45.
+ * - mttrHoras (menor es mejor): elite <1h · high <1día · medium <1sem · low ≥1sem.
+ */
+const UMBRALES_DORA_2023 = {
+  deploymentFrequency: { elite: 7, high: 0.23, medium: 0.038 }, // deploys/semana, mayor mejor
+  leadTimeHoras: { elite: 24, high: 168, medium: 730 }, // menor mejor
+  changeFailureRate: { elite: 0.15, high: 0.3, medium: 0.45 }, // menor mejor
+  mttrHoras: { elite: 1, high: 24, medium: 168 }, // menor mejor
+};
+
+const NIVELES = ['elite', 'high', 'medium', 'low'];
+
+/**
+ * Clasifica un valor de una métrica en elite/high/medium/low.
+ * @param {string} metrica - clave de UMBRALES_DORA_2023.
+ * @param {number|null|undefined} valor
+ * @returns {'elite'|'high'|'medium'|'low'|'sin-datos'}
+ */
+function clasificar(metrica, valor) {
+  const u = UMBRALES_DORA_2023[metrica];
+  if (!u || valor === null || valor === undefined || !Number.isFinite(valor)) return 'sin-datos';
+
+  if (metrica === 'deploymentFrequency') {
+    // mayor es mejor
+    if (valor >= u.elite) return 'elite';
+    if (valor >= u.high) return 'high';
+    if (valor >= u.medium) return 'medium';
+    return 'low';
+  }
+  // menor es mejor (leadTime, cfr, mttr)
+  if (valor < u.elite) return 'elite';
+  if (valor < u.high) return 'high';
+  if (valor < u.medium) return 'medium';
+  return 'low';
+}
+
+/**
+ * Calcula las 4 métricas DORA del proyecto en baseDir.
+ * @returns objeto serializable con generado, ventana_dias y las 4 métricas.
+ */
+function calcularDora(baseDir = process.cwd(), opts = {}) {
+  const { ventanaDias = 30, hoy = new Date(), ejecutorGh } = opts;
+
+  // Git (siempre)
+  const df = gitMetricas.deploymentFrequency(baseDir, { ventanaDias, hoy });
+  const lt = gitMetricas.leadTimeForChanges(baseDir, { ventanaDias, hoy });
+
+  // CI (degrada): una sola llamada a gh. Si no está disponible, NO se re-intenta
+  // — se propaga la razón directamente (evita 3 invocaciones del mismo fallo).
+  const runsBase = ciReader.obtenerRuns({ ejecutorGh, rama: 'main' });
+  const cfr = runsBase.disponible
+    ? ciReader.changeFailureRate({ ventanaDias, hoy, runs: runsBase.runs })
+    : { disponible: false, razon: runsBase.razon };
+  const mttr = runsBase.disponible
+    ? ciReader.meanTimeToRestore({ ventanaDias, hoy, runs: runsBase.runs })
+    : { disponible: false, razon: runsBase.razon };
+
+  const deploymentFrequency = df.disponible
+    ? {
+        disponible: true,
+        valor: df.sinDatos ? null : df.deploysPorSemana,
+        unidad: 'deploys/semana',
+        clasificacion: df.sinDatos ? 'sin-datos' : clasificar('deploymentFrequency', df.deploysPorSemana),
+        sinDatos: !!df.sinDatos,
+      }
+    : { disponible: false, razon: df.razon };
+
+  const leadTime = lt.disponible
+    ? {
+        disponible: true,
+        p50Horas: lt.sinDatos ? null : lt.p50Horas,
+        p95Horas: lt.sinDatos ? null : lt.p95Horas,
+        clasificacion: lt.sinDatos ? 'sin-datos' : clasificar('leadTimeHoras', lt.p50Horas),
+        sinDatos: !!lt.sinDatos,
+      }
+    : { disponible: false, razon: lt.razon };
+
+  const changeFailureRate = cfr.disponible
+    ? {
+        disponible: true,
+        valor: cfr.sinDatos ? null : cfr.cfr,
+        clasificacion: cfr.sinDatos ? 'sin-datos' : clasificar('changeFailureRate', cfr.cfr),
+        sinDatos: !!cfr.sinDatos,
+        totalRuns: cfr.totalRuns,
+        fallidos: cfr.fallidos,
+      }
+    : { disponible: false, razon: cfr.razon };
+
+  const mttrOut = mttr.disponible
+    ? {
+        disponible: true,
+        mttrHoras: mttr.sinDatos ? null : mttr.mttrHoras,
+        clasificacion: mttr.sinDatos ? 'sin-datos' : clasificar('mttrHoras', mttr.mttrHoras),
+        sinDatos: !!mttr.sinDatos,
+        recuperaciones: mttr.recuperaciones,
+      }
+    : { disponible: false, razon: mttr.razon };
+
+  return {
+    generado: hoy.toISOString(),
+    ventana_dias: ventanaDias,
+    deploymentFrequency,
+    leadTime,
+    changeFailureRate,
+    mttr: mttrOut,
+  };
+}
+
+/**
+ * Persiste el informe DORA en `<baseDir>/.planning/evolution/metricas-dora.json`.
+ * `baseDir` se trata como ruta CONFIABLE del invocador (CLI local / cwd); NUNCA
+ * debe propagarse desde input web/HTTP/PR. Aun así se valida contención bajo
+ * baseDir para evitar write-anywhere si el path subiera de nivel (H-01).
+ */
+function persistir(baseDir, dora) {
+  const base = path.resolve(baseDir);
+  const destino = path.resolve(base, STORAGE_REL);
+  if (destino !== base && !destino.startsWith(base + path.sep)) {
+    throw new Error('destino de métricas DORA fuera de baseDir');
+  }
+  atomicWriteJSON(destino, dora);
+  return destino;
+}
+
+module.exports = {
+  clasificar,
+  calcularDora,
+  persistir,
+  UMBRALES_DORA_2023,
+  NIVELES,
+  STORAGE_REL,
+};
+
+// Entrypoint CLI: node scripts/lib/metricas-dora.js [--json] [--dias=N] [baseDir]
+if (!require.main || require.main === module) {
+  const args = process.argv.slice(2);
+  const json = args.includes('--json');
+  const diasArg = args.find((a) => a.startsWith('--dias='));
+  const ventanaDias = Math.max(1, Math.min(365, (diasArg ? parseInt(diasArg.slice('--dias='.length), 10) : 30) || 30));
+  const baseDir = args.find((a) => !a.startsWith('--')) || process.cwd();
+
+  const dora = calcularDora(baseDir, { ventanaDias });
+  try {
+    persistir(baseDir, dora);
+  } catch {
+    /* persistencia best-effort: no romper el informe si el disco falla */
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify(dora, null, 2) + '\n');
+  } else {
+    const fmt = (txt) => process.stdout.write(`${txt}\n`);
+    const df = dora.deploymentFrequency;
+    const lt = dora.leadTime;
+    const cfr = dora.changeFailureRate;
+    const mt = dora.mttr;
+    fmt(`Deployment frequency: ${df.disponible ? (df.sinDatos ? 'sin datos' : `${df.valor.toFixed(2)}/sem [${df.clasificacion}]`) : 'no disponible'}`);
+    fmt(`Lead time (p50): ${lt.disponible ? (lt.sinDatos ? 'sin datos' : `${lt.p50Horas.toFixed(1)}h [${lt.clasificacion}]`) : 'no disponible'}`);
+    fmt(`Change failure rate: ${cfr.disponible ? (cfr.sinDatos ? 'sin datos' : `${(cfr.valor * 100).toFixed(1)}% [${cfr.clasificacion}]`) : 'no disponible (gh ausente)'}`);
+    fmt(`MTTR: ${mt.disponible ? (mt.sinDatos ? 'sin datos' : `${mt.mttrHoras.toFixed(1)}h [${mt.clasificacion}]`) : 'no disponible (gh ausente)'}`);
+  }
+  process.exit(0);
+}

package/scripts/tui/ejecutores.js

@@ -47,7 +47,7 @@ function _calcularTotalesDelPlan(opciones) {
   // mediante resolverPerfil, que devuelve { perfil, modulos, archivos, warnings }.
   try {
     const { resolverPerfil } = require('../lib/manifiestos');
-    const resolucion = resolverPerfil(opciones.profile || 'core', {});
+    const resolucion = resolverPerfil(opciones.profile || 'completo', {});
     if (!resolucion || !Array.isArray(resolucion.archivos)) return {};
     const totales = {};
     for (const archivo of resolucion.archivos) {

package/scripts/validar-manifest.js

@@ -149,6 +149,88 @@ function verificarModulosReferenciadosPorPerfil(modulos, perfiles) {
   return false;
 }
 
+function fragmentosDeclaradosEnAgente(contenido) {
+  // Extrae los nombres de fragmento (_x) del frontmatter `fragmentos:` de un
+  // agente. Soporta lista multilínea (`fragmentos:\n  - _x`) e inline
+  // (`fragmentos: [_x, _y]`).
+  const fm = contenido.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fm) return [];
+  const lineas = fm[1].split(/\r?\n/);
+  const out = [];
+  let dentro = false;
+  for (const l of lineas) {
+    const inline = l.match(/^fragmentos:\s*\[(.*)\]\s*$/);
+    if (inline) {
+      inline[1].split(',').forEach(s => { const t = s.trim(); if (t) out.push(t); });
+      dentro = false;
+      continue;
+    }
+    if (/^fragmentos:\s*$/.test(l)) { dentro = true; continue; }
+    if (dentro) {
+      const m = l.match(/^\s*-\s*(_[a-z][a-z0-9-]*)\s*$/);
+      if (m) { out.push(m[1]); continue; }
+      if (/^\S/.test(l)) dentro = false; // siguiente clave de primer nivel
+    }
+  }
+  return out;
+}
+
+function verificarFragmentos(declarados) {
+  // DT-FRAGMENTOS-VALIDACION (Fase 13): dos invariantes que la regla
+  // fragmentos-compartidos.md declara y que antes no se enforzaban:
+  //   1. Todo fragmento agentes/_*.md debe estar referenciado por ≥2 agentes.
+  //   2. Ningún fragmento agentes/_*.md debe aparecer en modulos.json (no es agente).
+  const base = path.join(RAIZ, 'agentes');
+  if (!fs.existsSync(base)) {
+    log('  [OK]    fragmentos: sin directorio agentes/ (nada que validar)');
+    return true;
+  }
+  const fragmentos = fs.readdirSync(base)
+    .filter(f => f.startsWith('_') && f.endsWith('.md'))
+    .map(f => f.replace(/\.md$/, '')); // '_propose-step'
+
+  // Contar referencias por fragmento en los agentes reales (no fragmentos).
+  const referencias = new Map(fragmentos.map(f => [f, 0]));
+  const agentes = fs.readdirSync(base)
+    .filter(f => f.endsWith('.md') && !f.startsWith('_'));
+  for (const ag of agentes) {
+    const refs = fragmentosDeclaradosEnAgente(fs.readFileSync(path.join(base, ag), 'utf-8'));
+    for (const r of refs) {
+      if (referencias.has(r)) referencias.set(r, referencias.get(r) + 1);
+    }
+  }
+
+  let ok = true;
+
+  // Check 1: ≥2 referencias.
+  const subreferenciados = fragmentos.filter(f => referencias.get(f) < 2);
+  if (subreferenciados.length === 0) {
+    log(`  [OK]    fragmentos: ${fragmentos.length}/${fragmentos.length} referenciados por ≥2 agentes`);
+  } else {
+    ok = false;
+    log(`  [FALLA] fragmentos: ${subreferenciados.length} referenciado(s) por <2 agentes`);
+    for (const f of subreferenciados) {
+      log(`          → agentes/${f}.md (referencias: ${referencias.get(f)})`);
+      errores.push({ categoria: 'fragmentos', archivo: `agentes/${f}.md`, tipo: 'fragmento_subreferenciado' });
+    }
+  }
+
+  // Check 2: no en modulos.json.
+  const enModulos = fragmentos.filter(f => declarados.has(`agentes/${f}.md`));
+  if (enModulos.length === 0) {
+    log('  [OK]    fragmentos: ninguno declarado como agente en modulos.json');
+  } else {
+    ok = false;
+    log(`  [FALLA] fragmentos: ${enModulos.length} declarado(s) en modulos.json (no son agentes)`);
+    for (const f of enModulos) {
+      log(`          → agentes/${f}.md`);
+      errores.push({ categoria: 'fragmentos', archivo: `agentes/${f}.md`, tipo: 'fragmento_en_modulos' });
+    }
+  }
+
+  return ok;
+}
+
 function verificarDeclarados1a1ExistenEnDisco(declarados) {
   // Caso inverso: declarados en manifest pero no presentes en disco
   const rotos = [];
@@ -205,6 +287,9 @@ function main() {
   const perfilOk = verificarModulosReferenciadosPorPerfil(modulos, perfiles);
   if (!perfilOk) todoOk = false;
 
+  const fragmentosOk = verificarFragmentos(declarados);
+  if (!fragmentosOk) todoOk = false;
+
   const inversoOk = verificarDeclarados1a1ExistenEnDisco(declarados);
   if (!inversoOk) todoOk = false;
 
@@ -219,6 +304,8 @@ function main() {
     log('  - "no_declarado_hooks_config": registrar el hook en manifiestos/hooks-config.json');
     log('  - "modulo_huerfano_sin_perfil": agregar el módulo al array `modulos` de al menos un perfil en manifiestos/perfiles.json');
     log('  - "declarado_no_existe": eliminar la ruta de modulos.json (archivo borrado) o crear el archivo');
+    log('  - "fragmento_subreferenciado": el fragmento agentes/_*.md debe ser usado por ≥2 agentes (declararlo en su frontmatter `fragmentos:`) o re-incrustarlo en el único agente que lo usa');
+    log('  - "fragmento_en_modulos": quitar el fragmento agentes/_*.md de modulos.json (no es un agente routable)');
   }
 
   if (salidaJson) {
@@ -228,4 +315,8 @@ function main() {
   process.exit(todoOk ? 0 : 1);
 }
 
-main();
+if (require.main === module) {
+  main();
+}
+
+module.exports = { fragmentosDeclaradosEnAgente };

package/scripts/verificar-evolucion.js

@@ -33,6 +33,26 @@ const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 
+/**
+ * Detecta si `dir` es la raíz del paquete swl-ses (repo madre).
+ *
+ * Espeja la excepción de `markAsEvolved` (hooks/lib/evolution-tracker.js):
+ * en el repo madre los cambios del mantenedor se rastrean por git + bump de
+ * `version`, NO por metadatos `evolved-*` — el tracker se NIEGA a marcarlos.
+ * Antes de este fix, los CHECKs 2/3 exigían aquí lo que el tracker rechaza
+ * escribir → el gate del Paso 6 de /swl:aprender era insatisfacible en el
+ * repo madre (detectado 2026-06-12, aprendizaje M4). El set de nombres debe
+ * mantenerse alineado con `isPackageRoot` del tracker.
+ */
+function esRaizDelPaquete(dir) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir || process.cwd(), 'package.json'), 'utf8'));
+    return pkg.name === '@saulwade/swl-ses' || pkg.name === 'swl-ses';
+  } catch {
+    return false;
+  }
+}
+
 /** Extrae el bloque de frontmatter YAML del inicio del archivo. */
 function extraerFrontmatter(contenido) {
   const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(contenido);
@@ -132,8 +152,16 @@ function archivosModificados(since) {
   }
 }
 
-/** Verifica un archivo concreto. Devuelve `{ archivo, problemas[], info }`. */
-function verificarArchivo(filePath) {
+/**
+ * Verifica un archivo concreto. Devuelve `{ archivo, problemas[], info }`.
+ * @param {object} [opts] - `opts.raizPaquete` fuerza/inyecta la detección de
+ *   repo madre (default: `esRaizDelPaquete(process.cwd())`). En repo madre los
+ *   CHECKs 2/3 (evolved) se omiten — solo aplican version presente + bump.
+ */
+function verificarArchivo(filePath, opts = {}) {
+  const raizPaquete = opts.raizPaquete !== undefined
+    ? opts.raizPaquete
+    : esRaizDelPaquete(process.cwd());
   const resultado = { archivo: filePath, problemas: [], info: {} };
 
   if (!fs.existsSync(filePath)) {
@@ -186,7 +214,15 @@ function verificarArchivo(filePath) {
   // CHECK 2: evolved = true (en frontmatter o en .evolved.json)
   // v1.6.1 (Cabo A4): exento si deprecated:true — no tiene sentido exigir
   // metadatos de evolución para componentes que se van a eliminar.
-  if (ev.evolved !== 'true' && !esDeprecated) {
+  // Exento también en el repo madre: markAsEvolved se NIEGA a marcar ahí
+  // (los cambios del mantenedor se rastrean por git + bump de version), así
+  // que exigirlo haría el gate insatisfacible. Ver esRaizDelPaquete().
+  if (raizPaquete) {
+    resultado.info.notas = resultado.info.notas || [];
+    resultado.info.notas.push(
+      'raíz del paquete: checks evolved omitidos (cambios del mantenedor = git + bump)'
+    );
+  } else if (ev.evolved !== 'true' && !esDeprecated) {
     resultado.problemas.push(
       '`evolved` no encontrado (ni en frontmatter ni en .evolved.json del directorio)'
     );
@@ -284,6 +320,13 @@ function main() {
     archivos = args.filter(a => !a.startsWith('--'));
   }
 
+  if (esRaizDelPaquete(process.cwd())) {
+    process.stdout.write(
+      '[nota] Raíz del paquete swl-ses: los checks de `evolved` se omiten — ' +
+      'los cambios del mantenedor se rastrean por git + bump de `version`.\n'
+    );
+  }
+
   let fallos = 0;
   for (const archivo of archivos) {
     const r = verificarArchivo(archivo);
@@ -302,4 +345,11 @@ function main() {
 
 if (require.main === module) main();
 
-module.exports = { verificarArchivo, extraerFrontmatter, leerCampo, obtenerVersionEnHEAD, main };
+module.exports = {
+  verificarArchivo,
+  extraerFrontmatter,
+  leerCampo,
+  obtenerVersionEnHEAD,
+  esRaizDelPaquete,
+  main,
+};