@saulwade/swl-ses 1.0.0

package/scripts/auditar-cobertura-frameworks.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * scripts/auditar-cobertura-frameworks.js
+ * Recorre habilidades/ y reporta la cobertura agregada del sistema por
+ * framework de seguridad (NIST CSF, NIST AI RMF, MITRE ATLAS/ATT&CK/D3FEND).
+ *
+ * Zero-deps. Salida: JSON por stdout + resumen por stderr.
+ *
+ * Uso:
+ *   node scripts/auditar-cobertura-frameworks.js            # JSON a stdout
+ *   node scripts/auditar-cobertura-frameworks.js --resumen  # tabla a stderr
+ *   node scripts/auditar-cobertura-frameworks.js --save     # persiste en .planning/evolucion/
+ *   node scripts/auditar-cobertura-frameworks.js --framework=nist_csf  # solo un framework
+ *
+ * No falla si un skill no tiene mapeos — solo los skills del dominio de
+ * seguridad deberían declararlos (ver reglas/skills-estandar.md seccion
+ * "Mapeo a frameworks de seguridad").
+ *
+ * Referencia: REC-C01 del reporte
+ * .planning/knowledge/outputs/analisis-anthropic-cybersecurity-skills-2026-04-20.md
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const RAIZ_SKILLS = path.resolve(__dirname, '..', 'habilidades');
+const DESTINO = path.resolve(
+  __dirname, '..', '.planning', 'evolucion', 'cobertura-frameworks.json'
+);
+
+const CAMPOS_FRAMEWORK = Object.freeze([
+  'nist_csf',
+  'nist_ai_rmf',
+  'atlas_techniques',
+  'attack_techniques',
+  'd3fend_techniques',
+]);
+
+// Etiqueta humana por framework
+const ETIQUETAS = Object.freeze({
+  nist_csf: 'NIST CSF 2.0',
+  nist_ai_rmf: 'NIST AI RMF 1.0',
+  atlas_techniques: 'MITRE ATLAS v5.4',
+  attack_techniques: 'MITRE ATT&CK v18',
+  d3fend_techniques: 'MITRE D3FEND v1.3',
+});
+
+// Soporta LF y CRLF
+const PATRON_FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+/**
+ * Parser YAML minimalista para frontmatter de skills. Solo soporta los
+ * formatos que el schema de swl-ses usa: strings, arrays inline [a, b, c]
+ * y arrays indentados con guion.
+ *
+ * Si el frontmatter tiene formatos más complejos, devuelve el campo como
+ * string raw — suficiente para contar tokens en los arrays.
+ *
+ * @param {string} raw
+ * @returns {Record<string, unknown>}
+ */
+function parsearFrontmatter(raw) {
+  const lineas = raw.split(/\r?\n/);
+  const salida = {};
+  let i = 0;
+  while (i < lineas.length) {
+    const linea = lineas[i];
+    const match = linea.match(/^([a-zA-Z_][\w-]*):\s*(.*)$/);
+    if (!match) { i++; continue; }
+    const clave = match[1];
+    const valor = match[2].trim();
+    if (valor === '') {
+      // Array indentado con guiones en líneas siguientes
+      const items = [];
+      let j = i + 1;
+      while (j < lineas.length) {
+        const sub = lineas[j].match(/^\s+-\s*(.+)$/);
+        if (!sub) break;
+        items.push(sub[1].replace(/^["']|["']$/g, ''));
+        j++;
+      }
+      salida[clave] = items.length > 0 ? items : '';
+      i = j;
+      continue;
+    }
+    if (valor.startsWith('[') && valor.endsWith(']')) {
+      // Array inline
+      const contenido = valor.slice(1, -1).trim();
+      if (contenido === '') {
+        salida[clave] = [];
+      } else {
+        salida[clave] = contenido.split(',').map(s => s.trim().replace(/^["']|["']$/g, ''));
+      }
+    } else {
+      salida[clave] = valor.replace(/^["']|["']$/g, '');
+    }
+    i++;
+  }
+  return salida;
+}
+
+function listarSkills() {
+  if (!fs.existsSync(RAIZ_SKILLS)) return [];
+  return fs.readdirSync(RAIZ_SKILLS, { withFileTypes: true })
+    .filter(d => d.isDirectory())
+    .map(d => d.name);
+}
+
+function leerMapeos(nombre) {
+  const ruta = path.join(RAIZ_SKILLS, nombre, 'SKILL.md');
+  if (!fs.existsSync(ruta)) return null;
+  const contenido = fs.readFileSync(ruta, 'utf8');
+  const m = contenido.match(PATRON_FRONTMATTER);
+  if (!m) return null;
+  const fm = parsearFrontmatter(m[1]);
+  const mapeos = {};
+  for (const campo of CAMPOS_FRAMEWORK) {
+    const valor = fm[campo];
+    mapeos[campo] = Array.isArray(valor) ? valor.filter(Boolean) : [];
+  }
+  return mapeos;
+}
+
+function auditar(filtroFramework) {
+  const skills = listarSkills();
+  const resultado = {
+    timestamp: new Date().toISOString(),
+    total_skills: skills.length,
+    skills_con_mapeos: 0,
+    por_skill: [],
+    por_framework: {},
+    controles_unicos: {},
+  };
+
+  // Inicializar estructuras agregadas
+  for (const campo of CAMPOS_FRAMEWORK) {
+    if (filtroFramework && filtroFramework !== campo) continue;
+    resultado.por_framework[campo] = {
+      etiqueta: ETIQUETAS[campo],
+      skills_que_lo_usan: 0,
+      controles_distintos: new Set(),
+      top_controles: {},
+    };
+    resultado.controles_unicos[campo] = new Set();
+  }
+
+  for (const nombre of skills) {
+    const mapeos = leerMapeos(nombre);
+    if (!mapeos) continue;
+    let tieneAlgunMapeo = false;
+    const entrada = { nombre, mapeos: {} };
+    for (const campo of CAMPOS_FRAMEWORK) {
+      if (filtroFramework && filtroFramework !== campo) continue;
+      const ids = mapeos[campo];
+      if (ids.length === 0) continue;
+      tieneAlgunMapeo = true;
+      entrada.mapeos[campo] = ids;
+      resultado.por_framework[campo].skills_que_lo_usan++;
+      for (const id of ids) {
+        resultado.por_framework[campo].controles_distintos.add(id);
+        resultado.por_framework[campo].top_controles[id] =
+          (resultado.por_framework[campo].top_controles[id] || 0) + 1;
+      }
+    }
+    if (tieneAlgunMapeo) {
+      resultado.skills_con_mapeos++;
+      resultado.por_skill.push(entrada);
+    }
+  }
+
+  // Serializar Sets a arrays ordenados para el JSON
+  for (const campo of Object.keys(resultado.por_framework)) {
+    const info = resultado.por_framework[campo];
+    info.controles_distintos_count = info.controles_distintos.size;
+    info.controles_distintos = Array.from(info.controles_distintos).sort();
+    info.top_controles = Object.entries(info.top_controles)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 10)
+      .map(([id, count]) => ({ id, count }));
+  }
+
+  return resultado;
+}
+
+function imprimirResumen(r) {
+  const total = r.total_skills;
+  const con = r.skills_con_mapeos;
+  const pct = total > 0 ? ((con / total) * 100).toFixed(1) : '0.0';
+
+  process.stderr.write(`\nCobertura de frameworks de seguridad — ${r.timestamp}\n`);
+  process.stderr.write(`  Skills totales:               ${total}\n`);
+  process.stderr.write(`  Skills con al menos 1 mapeo:  ${con} (${pct}%)\n\n`);
+
+  for (const campo of CAMPOS_FRAMEWORK) {
+    const info = r.por_framework[campo];
+    if (!info) continue;
+    process.stderr.write(`  ${info.etiqueta}\n`);
+    process.stderr.write(`    skills que lo mapean:   ${info.skills_que_lo_usan}\n`);
+    process.stderr.write(`    controles distintos:    ${info.controles_distintos_count}\n`);
+    if (info.top_controles.length > 0) {
+      const top3 = info.top_controles.slice(0, 3)
+        .map(c => `${c.id} (×${c.count})`).join(', ');
+      process.stderr.write(`    top 3 controles:        ${top3}\n`);
+    }
+    process.stderr.write('\n');
+  }
+
+  if (r.skills_con_mapeos === 0) {
+    process.stderr.write(`  Nota: ningún skill declara mapeos. Solo skills de dominio\n`);
+    process.stderr.write(`  seguridad necesitan declararlos. Ver reglas/skills-estandar.md\n`);
+    process.stderr.write(`  sección "Mapeo a frameworks de seguridad (REC-C01)".\n\n`);
+  }
+}
+
+const argv = process.argv.slice(2);
+const filtro = (argv.find(a => a.startsWith('--framework=')) || '').split('=')[1] || null;
+
+if (filtro && !CAMPOS_FRAMEWORK.includes(filtro)) {
+  process.stderr.write(`Framework desconocido: "${filtro}". Opciones válidas:\n`);
+  for (const c of CAMPOS_FRAMEWORK) {
+    process.stderr.write(`  --framework=${c}   (${ETIQUETAS[c]})\n`);
+  }
+  process.exit(1);
+}
+
+const resultado = auditar(filtro);
+
+if (argv.includes('--resumen')) {
+  imprimirResumen(resultado);
+} else if (argv.includes('--save')) {
+  const dir = path.dirname(DESTINO);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(DESTINO, JSON.stringify(resultado, null, 2), 'utf8');
+  imprimirResumen(resultado);
+  process.stderr.write(`Inventario persistido en: ${DESTINO}\n`);
+} else {
+  process.stdout.write(JSON.stringify(resultado, null, 2));
+  imprimirResumen(resultado);
+}

package/scripts/auditar-skills-gaps.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * scripts/auditar-skills-gaps.js
+ * Audita los skills de habilidades/ y detecta gaps segun los patrones SAP
+ * (Skill Authoring Patterns): Exclusion Clause, Gotchas, herramientasPermitidas.
+ * Zero-deps. Salida: JSON por stdout + resumen por stderr.
+ *
+ * Uso:
+ *   node scripts/auditar-skills-gaps.js             # JSON a stdout
+ *   node scripts/auditar-skills-gaps.js --resumen   # solo tabla a stderr
+ *   node scripts/auditar-skills-gaps.js --save      # persiste en .planning/evolucion/
+ *   node scripts/auditar-skills-gaps.js --incluir-excepciones  # incluye gaps excusados en el total
+ *
+ * Excepciones documentadas: lista inline de skills con gaps justificados por ADR.
+ * Se separan del conteo de "gaps reales" para evitar ruido recurrente.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const RAIZ_SKILLS = path.resolve(__dirname, '..', 'habilidades');
+const DESTINO_PLANNING = path.resolve(
+  __dirname, '..', '.planning', 'evolucion', 'audit-skills-gaps.json'
+);
+
+// Patrones de detección
+const PATRON_EXCLUSION = /cu[aá]ndo no|no cargar|no usar|no invocar|NO se debe/i;
+const PATRON_GOTCHAS = /gotcha|errores comunes|trampas|errores no obvios|fallas conocidas/i;
+// Soporta LF y CRLF (Windows). Sin \r en el patrón, aceptando \r?\n.
+const PATRON_FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+/**
+ * Excepciones documentadas por ADR.
+ * Clave: nombre-skill. Valor: objeto con gaps excusados + ADR + razón breve.
+ * Se filtran del conteo "gaps_reales" y se reportan en "excepciones_documentadas".
+ * Agregar nuevas excepciones SOLO tras ADR explícito.
+ */
+const EXCEPCIONES_DOCUMENTADAS = Object.freeze({
+  'auto-evolucion-protocolo': {
+    gaps_excusados: ['sin-gotchas'],
+    adr: 'ADR-0003',
+    razon: 'Gotchas extraídos byte-a-byte 2026-04-20 (ADR-0003 supersede Opción B del ADR-0002); excepción se mantiene como guardrail contra regresión en skill evolvable:false.',
+  },
+  'privacy-memoria': {
+    gaps_excusados: ['sin-gotchas'],
+    adr: 'ADR-0003',
+    razon: 'Gotchas extraídos byte-a-byte 2026-04-20 (ADR-0003 supersede Opción B del ADR-0002); excepción se mantiene como guardrail contra regresión en skill evolvable:false.',
+  },
+  'seguridad-skills-ia': {
+    gaps_excusados: ['sin-gotchas'],
+    adr: 'ADR-0003',
+    razon: 'Gotchas extraídos byte-a-byte 2026-04-20 (ADR-0003 supersede Opción B del ADR-0002); excepción se mantiene como guardrail contra regresión en skill evolvable:false.',
+  },
+});
+
+function listarSkills() {
+  if (!fs.existsSync(RAIZ_SKILLS)) return [];
+  return fs.readdirSync(RAIZ_SKILLS, { withFileTypes: true })
+    .filter(d => d.isDirectory())
+    .map(d => d.name);
+}
+
+function leerSkill(nombre) {
+  const ruta = path.join(RAIZ_SKILLS, nombre, 'SKILL.md');
+  if (!fs.existsSync(ruta)) return null;
+  const contenido = fs.readFileSync(ruta, 'utf8');
+  const fmMatch = contenido.match(PATRON_FRONTMATTER);
+  const frontmatterRaw = fmMatch ? fmMatch[1] : '';
+  const cuerpo = fmMatch ? contenido.slice(fmMatch[0].length) : contenido;
+  return { ruta, contenido, frontmatterRaw, cuerpo };
+}
+
+function detectarGaps(skill) {
+  const gaps = [];
+
+  // Exclusion clause — busca en frontmatter (campo 'exclusiones') o en cuerpo
+  const tieneExclusionFm = /^exclusiones:\s*\[?[^\]]*\]?/im.test(skill.frontmatterRaw);
+  const tieneExclusionCuerpo = PATRON_EXCLUSION.test(skill.cuerpo);
+  if (!tieneExclusionFm && !tieneExclusionCuerpo) {
+    gaps.push('sin-exclusion');
+  }
+
+  // Gotchas
+  if (!PATRON_GOTCHAS.test(skill.cuerpo)) {
+    gaps.push('sin-gotchas');
+  }
+
+  // herramientasPermitidas o allowed-tools en frontmatter
+  const tieneTools = /^(allowed-tools|herramientasPermitidas):/im.test(skill.frontmatterRaw);
+  if (!tieneTools) {
+    gaps.push('sin-herramientas-permitidas');
+  }
+
+  return gaps;
+}
+
+/**
+ * Separa los gaps detectados en dos buckets: gaps reales y gaps excusados por ADR.
+ * Si un skill solo tiene gaps en la lista de excepciones, no cuenta como "con gaps reales".
+ */
+function clasificarGaps(nombre, gaps) {
+  const excepcion = EXCEPCIONES_DOCUMENTADAS[nombre];
+  if (!excepcion) return { reales: gaps, excusados: [] };
+
+  const excusadosSet = new Set(excepcion.gaps_excusados);
+  const reales = gaps.filter(g => !excusadosSet.has(g));
+  const excusados = gaps.filter(g => excusadosSet.has(g));
+  return { reales, excusados, adr: excepcion.adr, razon: excepcion.razon };
+}
+
+function auditar(opts = {}) {
+  const incluirExcepciones = opts.incluirExcepciones === true;
+  const skills = listarSkills();
+  const resultado = {
+    timestamp: new Date().toISOString(),
+    total_skills: skills.length,
+    skills_con_gaps: [],
+    excepciones_documentadas: [],
+    resumen: {
+      sin_exclusion: 0,
+      sin_gotchas: 0,
+      sin_herramientas_permitidas: 0,
+      excepciones_activas: 0,
+    },
+  };
+
+  for (const nombre of skills) {
+    const skill = leerSkill(nombre);
+    if (!skill) continue;
+    const gaps = detectarGaps(skill);
+    if (gaps.length === 0) continue;
+
+    const { reales, excusados, adr, razon } = clasificarGaps(nombre, gaps);
+
+    // Registro de gaps reales (pueden requerir acción)
+    if (reales.length > 0) {
+      resultado.skills_con_gaps.push({ nombre, gaps: reales });
+      if (reales.includes('sin-exclusion')) resultado.resumen.sin_exclusion++;
+      if (reales.includes('sin-gotchas')) resultado.resumen.sin_gotchas++;
+      if (reales.includes('sin-herramientas-permitidas')) resultado.resumen.sin_herramientas_permitidas++;
+    }
+
+    // Registro de excepciones documentadas (no cuentan en gaps reales)
+    if (excusados.length > 0) {
+      resultado.excepciones_documentadas.push({
+        nombre,
+        gaps_excusados: excusados,
+        adr,
+        razon,
+      });
+      resultado.resumen.excepciones_activas++;
+
+      // Si el usuario pidió --incluir-excepciones, sumarlas también al conteo de gaps reales
+      if (incluirExcepciones) {
+        if (excusados.includes('sin-exclusion')) resultado.resumen.sin_exclusion++;
+        if (excusados.includes('sin-gotchas')) resultado.resumen.sin_gotchas++;
+        if (excusados.includes('sin-herramientas-permitidas')) resultado.resumen.sin_herramientas_permitidas++;
+      }
+    }
+  }
+
+  return resultado;
+}
+
+function imprimirResumen(r) {
+  const total = r.total_skills;
+  const pctExcl = total > 0 ? ((r.resumen.sin_exclusion / total) * 100).toFixed(1) : '0.0';
+  const pctGotchas = total > 0 ? ((r.resumen.sin_gotchas / total) * 100).toFixed(1) : '0.0';
+  const pctTools = total > 0 ? ((r.resumen.sin_herramientas_permitidas / total) * 100).toFixed(1) : '0.0';
+  const conGaps = r.skills_con_gaps.length;
+
+  process.stderr.write(`\nAuditoría de ${total} skills — ${r.timestamp}\n`);
+  process.stderr.write(`  Sin Exclusion Clause:        ${r.resumen.sin_exclusion}/${total} (${pctExcl}%)\n`);
+  process.stderr.write(`  Sin Gotchas:                 ${r.resumen.sin_gotchas}/${total} (${pctGotchas}%)\n`);
+  process.stderr.write(`  Sin herramientasPermitidas:  ${r.resumen.sin_herramientas_permitidas}/${total} (${pctTools}%)\n`);
+  process.stderr.write(`  Skills con al menos 1 gap:   ${conGaps}/${total}\n`);
+
+  if (r.resumen.excepciones_activas > 0) {
+    process.stderr.write(`  Excepciones documentadas:    ${r.resumen.excepciones_activas} (no cuentan en gaps reales)\n`);
+    for (const e of r.excepciones_documentadas) {
+      process.stderr.write(`    - ${e.nombre}: ${e.gaps_excusados.join(', ')} [${e.adr}]\n`);
+    }
+  }
+  process.stderr.write('\n');
+}
+
+const argv = process.argv.slice(2);
+const opts = {
+  incluirExcepciones: argv.includes('--incluir-excepciones'),
+};
+const resultado = auditar(opts);
+
+if (argv.includes('--resumen')) {
+  imprimirResumen(resultado);
+} else if (argv.includes('--save')) {
+  const dir = path.dirname(DESTINO_PLANNING);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(DESTINO_PLANNING, JSON.stringify(resultado, null, 2), 'utf8');
+  imprimirResumen(resultado);
+  process.stderr.write(`Inventario persistido en: ${DESTINO_PLANNING}\n`);
+} else {
+  process.stdout.write(JSON.stringify(resultado, null, 2));
+  imprimirResumen(resultado);
+}

package/scripts/bootstrap-instintos.js

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * bootstrap-instintos.js
+ *
+ * Pobla instintos/proyecto.yaml inicial a partir de las entradas de
+ * .planning/APRENDIZAJES.md. Cada entrada `### [YYYY-MM-DD] título` se
+ * convierte en un instinto con confidence inicial según la sección que lo
+ * contiene:
+ *
+ *   ## Anti-patrones detectados  → confidence 0.7, tags: [anti-patron]
+ *   ## Patrones exitosos         → confidence 0.6, tags: [patron]
+ *   ## Decisiones de arquitectura → confidence 0.8, tags: [decision, arquitectura]
+ *   ## Gotchas                    → confidence 0.6, tags: [gotcha]
+ *   default                       → confidence 0.5
+ *
+ * Uso:
+ *   node scripts/bootstrap-instintos.js          — dry run (imprime resumen)
+ *   node scripts/bootstrap-instintos.js --write  — escribe instintos/proyecto.yaml
+ *   node scripts/bootstrap-instintos.js --force  — sobreescribe aunque existan instintos
+ *
+ * Zero-deps.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const CWD = process.cwd();
+const APRENDIZAJES_PATH = path.join(CWD, '.planning', 'APRENDIZAJES.md');
+const INSTINTOS_PATH = path.join(CWD, 'instintos', 'proyecto.yaml');
+
+const flags = {
+  write: process.argv.includes('--write'),
+  force: process.argv.includes('--force'),
+};
+
+// ---------------------------------------------------------------------------
+// Config de secciones → confidence/tags
+// ---------------------------------------------------------------------------
+
+const SECCIONES = [
+  { regex: /anti[-\s]?patrones?/i,                  confidence: 0.7, tags: ['anti-patron'] },
+  { regex: /patrones?\s+exitosos?/i,                confidence: 0.6, tags: ['patron'] },
+  { regex: /decisiones?\s+de\s+arquitectura/i,      confidence: 0.8, tags: ['decision', 'arquitectura'] },
+  { regex: /gotchas?/i,                             confidence: 0.6, tags: ['gotcha'] },
+  { regex: /patrones?/i,                            confidence: 0.6, tags: ['patron'] },
+  { regex: /reglas?\s+de\s+proyecto/i,              confidence: 0.8, tags: ['regla-proyecto'] },
+];
+
+function detectarConfidence(seccion) {
+  for (const s of SECCIONES) {
+    if (s.regex.test(seccion)) return { confidence: s.confidence, tags: [...s.tags] };
+  }
+  return { confidence: 0.5, tags: [] };
+}
+
+// ---------------------------------------------------------------------------
+// Parser de APRENDIZAJES.md
+// ---------------------------------------------------------------------------
+
+/**
+ * Parsea el markdown en objetos de instinto.
+ * Formato esperado por entrada:
+ *   ## Sección
+ *   ### [YYYY-MM-DD] Título
+ *   Párrafo de descripción (puede ser multi-línea hasta el siguiente ###)
+ */
+function parsearAprendizajes(texto) {
+  const lineas = texto.split(/\r?\n/);
+  const entradas = [];
+  let seccionActual = '';
+  let actual = null;
+
+  const flushActual = () => {
+    if (actual) {
+      actual.description = actual._descParts.join(' ').replace(/\s+/g, ' ').trim();
+      delete actual._descParts;
+      entradas.push(actual);
+      actual = null;
+    }
+  };
+
+  for (const raw of lineas) {
+    const linea = raw.replace(/\s+$/, '');
+
+    // Sección (##)
+    const mSec = linea.match(/^##\s+(.+)$/);
+    if (mSec && !linea.startsWith('###')) {
+      flushActual();
+      seccionActual = mSec[1].trim();
+      continue;
+    }
+
+    // Entrada (### [YYYY-MM-DD] Título)
+    const mEntry = linea.match(/^###\s+\[(\d{4}-\d{2}-\d{2})\]\s+(.+)$/);
+    if (mEntry) {
+      flushActual();
+      actual = {
+        fecha: mEntry[1],
+        titulo: mEntry[2].trim(),
+        seccion: seccionActual,
+        _descParts: [],
+      };
+      continue;
+    }
+
+    // Acumular descripción si tenemos entrada activa
+    if (actual) {
+      const t = linea.trim();
+      if (t && !t.startsWith('#') && !t.startsWith('---')) {
+        actual._descParts.push(t);
+      }
+    }
+  }
+
+  flushActual();
+  return entradas;
+}
+
+// ---------------------------------------------------------------------------
+// Generación de instintos YAML
+// ---------------------------------------------------------------------------
+
+function escapeYaml(s) {
+  // YAML-safe: double quote con escape mínimo
+  return `"${String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+function truncate(s, n) {
+  if (s.length <= n) return s;
+  return s.slice(0, n - 3).trim() + '...';
+}
+
+function generarInstintos(entradas) {
+  const hoy = new Date().toISOString().slice(0, 10);
+  return entradas.map((e, idx) => {
+    const { confidence, tags } = detectarConfidence(e.seccion);
+    const pattern = truncate(e.titulo, 200);
+    const description = truncate(e.description || e.titulo, 500);
+    return {
+      id: `inst-${String(idx + 1).padStart(3, '0')}`,
+      pattern,
+      description,
+      confidence,
+      scope: 'project',
+      source: 'APRENDIZAJES.md',
+      evidence_count: 1,
+      last_validated: e.fecha,
+      last_validated_at: e.fecha,
+      contradictions: 0,
+      status: 'active',
+      tags,
+      created_at: hoy,
+      seccion_origen: e.seccion,
+      decay_half_life_days: 90,
+      helpful_count: 0,
+      harmful_count: 0,
+      source_sessions: [],
+      source_agents: [],
+    };
+  });
+}
+
+function serializarYaml(instintos) {
+  const fechaActual = new Date().toISOString().slice(0, 10);
+  const header = `# Instintos del Proyecto — SWL-SES
+# Generado automáticamente por scripts/bootstrap-instintos.js desde .planning/APRENDIZAJES.md
+# Formato estandarizado v1.0
+
+version: "1.0"
+generado: "${fechaActual}"
+total_instintos: ${instintos.length}
+
+instintos:
+`;
+  const body = instintos.map(i => {
+    return [
+      `  - id: ${i.id}`,
+      `    pattern: ${escapeYaml(i.pattern)}`,
+      `    description: ${escapeYaml(i.description)}`,
+      `    confidence: ${i.confidence}`,
+      `    scope: ${i.scope}`,
+      `    source: ${escapeYaml(i.source)}`,
+      `    evidence_count: ${i.evidence_count}`,
+      `    last_validated: "${i.last_validated}"`,
+      `    last_validated_at: "${i.last_validated_at}"`,
+      `    contradictions: ${i.contradictions}`,
+      `    status: ${i.status}`,
+      `    tags: [${i.tags.map(t => `"${t}"`).join(', ')}]`,
+      `    created_at: "${i.created_at}"`,
+      `    seccion_origen: ${escapeYaml(i.seccion_origen)}`,
+      `    decay_half_life_days: ${i.decay_half_life_days}`,
+      `    helpful_count: ${i.helpful_count}`,
+      `    harmful_count: ${i.harmful_count}`,
+      `    source_sessions: [${(i.source_sessions || []).map(s => `"${s}"`).join(', ')}]`,
+      `    source_agents: [${(i.source_agents || []).map(a => `"${a}"`).join(', ')}]`,
+    ].join('\n');
+  }).join('\n\n');
+  return header + body + '\n';
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  if (!fs.existsSync(APRENDIZAJES_PATH)) {
+    console.error('FAIL: no existe', APRENDIZAJES_PATH);
+    process.exit(1);
+  }
+
+  const texto = fs.readFileSync(APRENDIZAJES_PATH, 'utf8');
+  const entradas = parsearAprendizajes(texto);
+
+  if (entradas.length === 0) {
+    console.log('No se detectaron entradas en APRENDIZAJES.md (patrón "### [YYYY-MM-DD] Título").');
+    return;
+  }
+
+  const instintos = generarInstintos(entradas);
+
+  // Agrupar stats por sección
+  const porSeccion = {};
+  for (const i of instintos) {
+    porSeccion[i.seccion_origen] = (porSeccion[i.seccion_origen] || 0) + 1;
+  }
+
+  console.log(`Entradas detectadas: ${entradas.length}`);
+  console.log('Por sección:');
+  for (const [s, n] of Object.entries(porSeccion)) {
+    console.log(`  ${n.toString().padStart(3)} × ${s}`);
+  }
+
+  if (!flags.write) {
+    console.log('\n(dry run — pasar --write para persistir en instintos/proyecto.yaml)');
+    return;
+  }
+
+  // Verificar si ya hay instintos existentes
+  if (fs.existsSync(INSTINTOS_PATH) && !flags.force) {
+    const actual = fs.readFileSync(INSTINTOS_PATH, 'utf8');
+    const mTotal = actual.match(/^total_instintos:\s*(\d+)/m);
+    const totalActual = mTotal ? parseInt(mTotal[1], 10) : 0;
+    if (totalActual > 0) {
+      console.error(`FAIL: instintos/proyecto.yaml ya tiene ${totalActual} instintos.`);
+      console.error('      Usa --force para sobreescribir (o consolida manualmente).');
+      process.exit(2);
+    }
+  }
+
+  const yaml = serializarYaml(instintos);
+  fs.writeFileSync(INSTINTOS_PATH, yaml, 'utf8');
+  console.log(`\nOK: ${instintos.length} instintos escritos en ${INSTINTOS_PATH}`);
+}
+
+if (require.main === module) main();
+
+module.exports = { parsearAprendizajes, generarInstintos, detectarConfidence };