@saulwade/swl-ses 2.6.1 → 2.8.0

package/scripts/generar-claims-runtime.js

@@ -0,0 +1,1342 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Proyecta el bootstrap canónico de claims runtime sobre superficies públicas.
+ * La migración legacy es explícita y transaccional; el modo estable nunca
+ * inserta marcadores faltantes ni busca secciones por aproximación.
+ */
+
+const crypto = require('node:crypto');
+const childProcess = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { atomicWriteSync } = require('../hooks/lib/atomic-write');
+const {
+  cargarConformance,
+  derivarSupportLabel,
+  validarConformance,
+} = require('./lib/runtime-conformance');
+
+const RAIZ = path.resolve(__dirname, '..');
+const MARCA_INICIO = '<!-- BEGIN:RUNTIME-CONFORMANCE (generado por scripts/generar-claims-runtime.js; no editar) -->';
+const MARCA_FIN = '<!-- END:RUNTIME-CONFORMANCE -->';
+const EXTENSIONES_ESCANEADAS = new Set(['.md', '.json', '.js']);
+const PATRON_RUNTIME = new RegExp([
+  String.raw`(?<![.\p{L}\p{N}_-])`,
+  String.raw`(?:claude(?:[- ]code)?|openclaude|open[- ]?code|gemini(?:[- ]cli)?|`,
+  String.raw`cursor|codex(?:[- ]cli)?|github[- ]copilot|copilot)`,
+  String.raw`(?![.\p{L}\p{N}_-])`,
+].join(''), 'iu');
+const PATRON_ESTADO = new RegExp([
+  String.raw`(?<![\p{L}\p{N}_])`,
+  String.raw`(?:soporte\s+(?:completo|parcial)|completo|parcial|experimental|`,
+  String.raw`no[_ -]?soportado)(?![\p{L}\p{N}_])`,
+].join(''), 'iu');
+const PATRON_CONTEXTO_CLAIM = new RegExp([
+  String.raw`(?:soporte|compatibilidad|conformidad|certificaci[oó]n|`,
+  String.raw`support(?:label)?|certificationstatus|(?:estado|status)\s*[:=])`,
+].join(''), 'iu');
+const PREFIJOS_EXCLUIDOS = Object.freeze([
+  '.planning/adrs/',
+  '.planning/audit/',
+  '.planning/archive/',
+  'releases/',
+  'temp/',
+  'respositorios-git/',
+]);
+const DESCRIPCION = [
+  'Sistema de ingeniería de software auto-evolutivo para proyectos downstream, políglota en',
+  '11 lenguajes, con 61 agentes, 181 habilidades, 48 comandos, 77 reglas, 49 hooks, instalación',
+  'multi-target, MCP, gateway y auditoría Nemesis. Siete targets runtime con compatibilidad',
+  'experimental y certificación pendiente de evidencia externa.',
+].join(' ');
+const CLAIM_README_LEGACY = [
+  'Soporta 7 runtimes de IA: Claude Code, OpenClaude, OpenCode y Gemini CLI (soporte completo);',
+  'Cursor, Codex CLI y GitHub Copilot (soporte parcial — reglas + MCP server o consolidación en',
+  'archivo de instrucciones según el runtime). Incluye sistema de transformadores que adapta el',
+  'formato canónico SWL al formato nativo de cada runtime, **multi-target install**',
+  '(`--target=claude,cursor,codex` en una sola invocación), y **`swl-mcp-server` v1.0.0** con auth',
+  'opt-in para que Cursor, Codex y otros clientes MCP consulten la memoria SWL (aprendizajes,',
+  'instintos, sesiones).',
+].join(' ');
+const CLAIM_README_DOWNSTREAM = [
+  'SWL reconoce siete targets de instalación de IA. La disponibilidad de un transformador no',
+  'certifica conformidad con el harness; los estados públicos se derivan del manifiesto canónico.',
+  'Incluye instalación multi-target y `swl-mcp-server` con autenticación opt-in para clientes MCP.',
+].join(' ');
+const INTRO_AGENTS_DOWNSTREAM = [
+  'Sistema de ingeniería de software auto-evolutivo para proyectos downstream que cubre el SDLC',
+  'completo.',
+].join(' ');
+const REGISTRO_SUPERFICIES = Object.freeze({
+  markdown: [
+    {
+      path: 'README.md',
+      strategy: 'markdown-block',
+      migration: {
+        startAnchor: '### Targets soportados',
+        endAnchor: '### Ejemplos',
+        sha256: '3e15271b46c9b82d72a1555526a3d0935ff39264c05b5bafcfb2d2e9aede946b',
+        neutralizations: [{
+          text: CLAIM_README_LEGACY,
+          sha256: 'd6829938f987fdc340a2ca86074e1cdbae1dcc822e2fef9c9003591204a8e8f5',
+          replacement: CLAIM_README_DOWNSTREAM,
+        }],
+      },
+    },
+    {
+      path: 'COMANDOS.md',
+      strategy: 'markdown-block',
+      migration: {
+        startAnchor: '## Sistema de transformadores (multi-runtime)',
+        endAnchor: '## Comandos desde Claude Code (`/swl:*`)',
+        sha256: '41f95080021404ff7954a7f6a768dd1c0f720019f76f8d728dd38fa0b9b156d5',
+        neutralizations: [],
+      },
+    },
+    {
+      path: 'MANUAL_USO.md',
+      strategy: 'markdown-block',
+      migration: {
+        startAnchor: '### Runtimes soportados (`--target`)',
+        endAnchor: '#### Multi-target install (v1.5.0+) — un solo comando para varios editores',
+        sha256: '45cde0f47be17cd24df4265c1ae30eaecd150f2dd2b68d483e582ac3547b98c7',
+        neutralizations: [],
+      },
+    },
+    {
+      path: 'INSTALACION.md',
+      strategy: 'markdown-block',
+      migration: {
+        startAnchor: '### 3.5 Targets soportados y transformaciones',
+        endAnchor: '#### Codex CLI — detalle de instalación',
+        sha256: 'fa8ea3ce43d1037d4e8110b9b2c671d9892ee411c17c701b478e55a62839aac0',
+        neutralizations: [],
+      },
+    },
+    {
+      path: 'AGENTS.md',
+      strategy: 'markdown-block',
+      migration: {
+        startAnchor: '7 runtimes:',
+        endAnchor: '**Idioma**',
+        sha256: 'a6f55cb3b999f163cf366933520018855e4e0b4c44b8d5ca391146c584f0c1ee',
+        neutralizations: [{
+          text: 'Sistema de ingeniería de software auto-evolutivo multi-runtime polyglot que cubre el SDLC completo.',
+          sha256: 'b942a36a79101a5a10928d5398155217357eca33f7bfd9fd5ae1c43c039326f9',
+          replacement: INTRO_AGENTS_DOWNSTREAM,
+        }],
+      },
+    },
+  ],
+  json: [
+    { path: 'package.json', strategy: 'json-description', jsonPath: ['description'] },
+    { path: 'plugin.json', strategy: 'json-description', jsonPath: ['description'] },
+  ],
+  managed: [
+    { path: 'INVENTARIO.md', strategy: 'generar-inventario' },
+  ],
+  operational: [
+    { path: 'scripts/lib/detectar-runtime.js', strategy: 'derived-label' },
+    { path: 'scripts/comandos/install-asistido.js', strategy: 'derived-label' },
+    { path: 'scripts/tui/pantallas/install-wizard.js', strategy: 'derived-label' },
+    { path: 'scripts/instalador.js', strategy: 'derived-label' },
+  ],
+});
+
+class ErrorDrift extends Error {}
+
+function sha256(contenido) {
+  return crypto.createHash('sha256').update(contenido).digest('hex');
+}
+
+function contar(contenido, texto) {
+  return contenido.split(texto).length - 1;
+}
+
+function detectarEol(contenido) {
+  return contenido.includes('\r\n') ? '\r\n' : '\n';
+}
+
+function usarEol(contenido, eol) {
+  return contenido.replace(/\r?\n/g, eol);
+}
+
+function cargarContrato(opciones) {
+  if (opciones.conformance) return validarConformance(opciones.conformance);
+  return cargarConformance({ manifestPath: opciones.manifestPath });
+}
+
+function renderBloque(opciones = {}) {
+  const conformance = cargarContrato(opciones);
+  const lineas = [
+    MARCA_INICIO,
+    '',
+    '### Conformidad de runtimes',
+    '',
+    '> Estado bootstrap: disponibilidad de instalación no equivale a certificación del harness.',
+    '',
+    '| Runtime | Target | Soporte público | Certificación |',
+    '|---|---|---|---|',
+  ];
+  for (const runtime of conformance.runtimes) {
+    lineas.push(`| ${runtime.id} | ${runtime.installerTarget} | ${derivarSupportLabel(runtime)} | ${runtime.certificationStatus} |`);
+  }
+  lineas.push('', MARCA_FIN);
+  return lineas.join('\n');
+}
+
+function resolverRuta(root, rutaRelativa) {
+  const rootReal = fs.realpathSync(root);
+  const absoluta = path.resolve(root, rutaRelativa);
+  const relativa = path.relative(root, absoluta);
+  if (relativa.startsWith('..') || path.isAbsolute(relativa)) {
+    throw new TypeError(`superficie fuera de root: ${rutaRelativa}`);
+  }
+  const padreReal = fs.realpathSync(path.dirname(absoluta));
+  validarConfinamiento(rootReal, padreReal, rutaRelativa);
+  if (fs.existsSync(absoluta)) {
+    validarConfinamiento(rootReal, fs.realpathSync(absoluta), rutaRelativa);
+  }
+  return absoluta;
+}
+
+function crearResolvedorConfinado(root) {
+  const rootReal = fs.realpathSync(root);
+  const padresReales = new Map();
+  return (rutaRelativa) => {
+    const absoluta = path.resolve(root, rutaRelativa);
+    const relativa = path.relative(root, absoluta);
+    if (relativa.startsWith('..') || path.isAbsolute(relativa)) {
+      throw new TypeError(`superficie fuera de root: ${rutaRelativa}`);
+    }
+    const padre = path.dirname(absoluta);
+    const padreReal = padresReales.get(padre) || fs.realpathSync(padre);
+    padresReales.set(padre, padreReal);
+    validarConfinamiento(rootReal, padreReal, rutaRelativa);
+    if (fs.lstatSync(absoluta).isSymbolicLink()) {
+      validarConfinamiento(rootReal, fs.realpathSync(absoluta), rutaRelativa);
+    }
+    return absoluta;
+  };
+}
+
+function validarConfinamiento(rootReal, rutaReal, rutaRelativa) {
+  const relativa = path.relative(rootReal, rutaReal);
+  if (relativa.startsWith('..') || path.isAbsolute(relativa)) {
+    throw new TypeError(`superficie resuelve fuera de root: ${rutaRelativa}`);
+  }
+}
+
+function reemplazarBloque(contenido, bloque) {
+  if (contar(contenido, MARCA_INICIO) !== 1 || contar(contenido, MARCA_FIN) !== 1) {
+    throw new ErrorDrift('se requiere exactamente un par de marcadores runtime');
+  }
+  const inicio = contenido.indexOf(MARCA_INICIO);
+  const fin = contenido.indexOf(MARCA_FIN, inicio);
+  if (fin < inicio) throw new ErrorDrift('orden de marcadores runtime inválido');
+  const eol = detectarEol(contenido);
+  const despues = fin + MARCA_FIN.length;
+  return contenido.slice(0, inicio) + usarEol(bloque, eol) + contenido.slice(despues);
+}
+
+function validarAnclas(contenido, migracion) {
+  const inicios = contar(contenido, migracion.startAnchor);
+  const finales = contar(contenido, migracion.endAnchor);
+  if (inicios !== 1 || finales !== 1) throw new TypeError('anclas legacy ausentes o ambiguas');
+  const inicio = contenido.indexOf(migracion.startAnchor);
+  const fin = contenido.indexOf(migracion.endAnchor, inicio + migracion.startAnchor.length);
+  if (fin < inicio) throw new TypeError('orden de anclas legacy inválido');
+  return { inicio, fin };
+}
+
+function neutralizarClaims(contenido, neutralizaciones) {
+  let salida = contenido;
+  for (const regla of neutralizaciones || []) {
+    if (sha256(regla.text) !== regla.sha256 || contar(salida, regla.text) !== 1) {
+      throw new TypeError('claim introductorio no coincide con su hash exacto');
+    }
+    salida = salida.replace(regla.text, regla.replacement);
+  }
+  return salida;
+}
+
+function validarNeutralizacionesMigradas(contenido, neutralizaciones) {
+  for (const regla of neutralizaciones || []) {
+    const configValida = sha256(regla.text) === regla.sha256;
+    const estadoValido = contar(contenido, regla.text) === 0
+      && contar(contenido, regla.replacement) === 1;
+    if (!configValida || !estadoValido) {
+      throw new TypeError('claim introductorio pre-marcado no está neutralizado');
+    }
+  }
+}
+
+function validarEstadoMigrado(contenido, superficie, bloque) {
+  const inicio = contenido.indexOf(MARCA_INICIO);
+  const fin = contenido.indexOf(MARCA_FIN, inicio) + MARCA_FIN.length;
+  const bloqueActual = contenido.slice(inicio, fin).replace(/\r\n/g, '\n');
+  if (bloqueActual !== bloque) {
+    throw new TypeError(`bloque pre-marcado no es canónico: ${superficie.path}`);
+  }
+  const migracion = superficie.migration;
+  if (contar(contenido, migracion.startAnchor) !== 0
+    || contar(contenido, migracion.endAnchor) !== 1) {
+    throw new TypeError(`estado posmigración inválido: ${superficie.path}`);
+  }
+  validarNeutralizacionesMigradas(contenido, migracion.neutralizations);
+  return contenido;
+}
+
+function migrarMarkdown(contenido, superficie, bloque) {
+  const tieneInicio = contar(contenido, MARCA_INICIO);
+  const tieneFin = contar(contenido, MARCA_FIN);
+  if (tieneInicio === 1 && tieneFin === 1) {
+    if (!superficie.migration) throw new TypeError(`migración no registrada: ${superficie.path}`);
+    return validarEstadoMigrado(contenido, superficie, bloque);
+  }
+  if (tieneInicio !== 0 || tieneFin !== 0) throw new TypeError('migración encontró marcadores parciales');
+  if (!superficie.migration) throw new TypeError(`migración no registrada: ${superficie.path}`);
+  const { inicio, fin } = validarAnclas(contenido, superficie.migration);
+  const region = contenido.slice(inicio, fin);
+  if (sha256(region) !== superficie.migration.sha256) {
+    throw new TypeError(`hash legacy distinto: ${superficie.path}`);
+  }
+  const eol = detectarEol(contenido);
+  const reemplazado = contenido.slice(0, inicio) + usarEol(`${bloque}\n\n`, eol) + contenido.slice(fin);
+  return neutralizarClaims(reemplazado, superficie.migration.neutralizations);
+}
+
+function actualizarJson(contenido, superficie) {
+  const documento = JSON.parse(contenido);
+  if (JSON.stringify(superficie.jsonPath) !== JSON.stringify(['description'])) {
+    throw new TypeError(`ruta JSON no permitida: ${superficie.path}`);
+  }
+  if (!Object.hasOwn(documento, 'description')) {
+    throw new ErrorDrift(`description ausente: ${superficie.path}`);
+  }
+  documento.description = DESCRIPCION;
+  const eol = detectarEol(contenido);
+  return usarEol(`${JSON.stringify(documento, null, 2)}\n`, eol);
+}
+
+function prepararCambios(opciones, modo) {
+  const root = path.resolve(opciones.root || RAIZ);
+  const registry = opciones.registry || REGISTRO_SUPERFICIES;
+  const bloque = renderBloque(opciones);
+  const cambios = [];
+  for (const superficie of registry.markdown || []) {
+    const ruta = resolverRuta(root, superficie.path);
+    const original = fs.readFileSync(ruta, 'utf8');
+    const salida = modo === 'migrate'
+      ? migrarMarkdown(original, superficie, bloque)
+      : reemplazarBloque(original, bloque);
+    cambios.push({ ruta, original, salida });
+  }
+  for (const superficie of registry.managed || []) {
+    const ruta = resolverRuta(root, superficie.path);
+    const original = fs.readFileSync(ruta, 'utf8');
+    cambios.push({ ruta, original, salida: reemplazarBloque(original, bloque) });
+  }
+  for (const superficie of registry.json || []) {
+    const ruta = resolverRuta(root, superficie.path);
+    const original = fs.readFileSync(ruta, 'utf8');
+    cambios.push({ ruta, original, salida: actualizarJson(original, superficie) });
+  }
+  return cambios;
+}
+
+function intentarPreparar(opciones, modo) {
+  try {
+    return { ok: true, cambios: prepararCambios(opciones, modo), errors: [] };
+  } catch (error) {
+    const code = error instanceof ErrorDrift ? 2 : 1;
+    return { ok: false, cambios: [], errors: [error.message], code };
+  }
+}
+
+function revertirCambios(aplicados) {
+  const errores = [];
+  for (const cambio of [...aplicados].reverse()) {
+    try {
+      const actual = fs.readFileSync(cambio.ruta, 'utf8');
+      if (actual === cambio.salida) atomicWriteSync(cambio.ruta, cambio.original, 'utf8');
+      else errores.push(`rollback CAS rechazado: ${cambio.ruta}`);
+    } catch (error) {
+      errores.push(`rollback falló: ${cambio.ruta}: ${error.message}`);
+    }
+  }
+  return errores;
+}
+
+function adquirirLock(root) {
+  const ruta = path.join(fs.realpathSync(root), '.swl-runtime-claims.lock');
+  let descriptor;
+  try {
+    descriptor = fs.openSync(ruta, 'wx', 0o600);
+    fs.writeFileSync(descriptor, `${JSON.stringify({ pid: process.pid })}\n`, 'utf8');
+  } catch (error) {
+    if (descriptor !== undefined) {
+      try { fs.closeSync(descriptor); } catch {}
+      try { fs.unlinkSync(ruta); } catch {}
+    }
+    throw new TypeError(`no se pudo adquirir lock transaccional: ${error.message}`);
+  }
+  return () => {
+    fs.closeSync(descriptor);
+    fs.unlinkSync(ruta);
+  };
+}
+
+function aplicarCambios(preparacion, opciones = {}) {
+  if (!preparacion.ok) return { ok: false, changed: 0, errors: preparacion.errors };
+  const distintos = preparacion.cambios.filter(({ original, salida }) => original !== salida);
+  if (distintos.length === 0) return { ok: true, changed: 0, errors: [] };
+  const writeFile = opciones.writeFile || atomicWriteSync;
+  const aplicados = [];
+  let liberarLock;
+  let resultado;
+  try {
+    liberarLock = adquirirLock(path.resolve(opciones.root || RAIZ));
+    for (const cambio of distintos) {
+      if (fs.readFileSync(cambio.ruta, 'utf8') !== cambio.original) {
+        throw new TypeError(`CAS rechazado por edición concurrente: ${cambio.ruta}`);
+      }
+      writeFile(cambio.ruta, cambio.salida, 'utf8');
+      aplicados.push(cambio);
+    }
+    resultado = { ok: true, changed: distintos.length, errors: [] };
+  } catch (error) {
+    const erroresRollback = revertirCambios(aplicados);
+    resultado = { ok: false, changed: 0, errors: [error.message, ...erroresRollback] };
+  }
+  try {
+    if (liberarLock) liberarLock();
+  } catch (error) {
+    resultado = { ok: false, changed: 0, errors: [...resultado.errors, error.message] };
+  }
+  return resultado;
+}
+
+function migrarBootstrap(opciones = {}) {
+  return aplicarCambios(intentarPreparar(opciones, 'migrate'), opciones);
+}
+
+function escribirClaims(opciones = {}) {
+  return aplicarCambios(intentarPreparar(opciones, 'stable'), opciones);
+}
+
+function normalizarRuta(rutaRelativa) {
+  return rutaRelativa.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function esRutaExcluida(rutaRelativa) {
+  const normalizada = normalizarRuta(rutaRelativa).toLowerCase();
+  if (normalizada === 'changelog.md') return true;
+  if (PREFIJOS_EXCLUIDOS.some((prefijo) => normalizada.startsWith(prefijo))) return true;
+  return /(^|\/)(?:tests?|node_modules|fixtures?|__fixtures__)(?:\/|$)/u.test(normalizada);
+}
+
+function ejecutarArchivoSinShell(...args) {
+  return childProcess.execFileSync(...args);
+}
+
+function listarCandidatos(root, opciones = {}) {
+  if (Array.isArray(opciones.trackedFiles)) return [...opciones.trackedFiles];
+  const ejecutar = opciones.execFile || ejecutarArchivoSinShell;
+  const salida = ejecutar('git', ['ls-files', '-z'], {
+    cwd: root,
+    encoding: 'utf8',
+    windowsHide: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return salida.split('\0').filter(Boolean);
+}
+
+function preservarSaltos(contenido) {
+  return contenido.replace(/[^\r\n]/gu, ' ');
+}
+
+function esComentarioHistorico(comentario) {
+  if (/\b(?:ahora|actualmente|hoy|ya|en la actualidad)\b/iu.test(comentario)) return false;
+  if (/(?:hist[oó]ric[oa]|legacy)/iu.test(comentario)) return true;
+  const runtime = comentario.match(PATRON_RUNTIME);
+  const estado = comentario.match(PATRON_ESTADO);
+  if (!runtime || !estado || runtime.index >= estado.index) return false;
+  const relacion = comentario.slice(runtime.index + runtime[0].length, estado.index);
+  return /\b(?:era|fue|ten[ií]a|contaba con)\b/iu.test(relacion);
+}
+
+function avanzarDelimitado(contenido, inicio, delimitador) {
+  let indice = inicio + 1;
+  while (indice < contenido.length) {
+    if (contenido[indice] === '\\') indice += 2;
+    else if (contenido[indice] === delimitador) return indice + 1;
+    else indice += 1;
+  }
+  return contenido.length;
+}
+
+function avanzarRegexJs(contenido, inicio) {
+  let indice = inicio + 1;
+  let enClase = false;
+  while (indice < contenido.length) {
+    if (contenido[indice] === '\\') indice += 2;
+    else if (contenido[indice] === '[') { enClase = true; indice += 1; }
+    else if (contenido[indice] === ']') { enClase = false; indice += 1; }
+    else if (contenido[indice] === '/' && !enClase) {
+      indice += 1;
+      while (/\p{L}/u.test(contenido[indice] || '')) indice += 1;
+      return indice;
+    } else indice += 1;
+  }
+  return contenido.length;
+}
+
+function obtenerPalabraSignificativa(contenido, ultimoSignificativo) {
+  if (ultimoSignificativo < 0) return '';
+  let inicio = ultimoSignificativo;
+  while (inicio >= 0 && /[\p{L}\p{N}_$]/u.test(contenido[inicio])) inicio -= 1;
+  if (contenido[inicio] === '.') return '';
+  return contenido.slice(inicio + 1, ultimoSignificativo + 1);
+}
+
+function esAperturaControl(contenido, ultimoSignificativo) {
+  const palabra = obtenerPalabraSignificativa(contenido, ultimoSignificativo);
+  return /^(?:if|while|for|with|switch|catch)$/u.test(palabra);
+}
+
+function puedeIniciarRegex(contenido, indice, ultimoSignificativo, cierresControl) {
+  if (ultimoSignificativo < 0) return true;
+  if ('=(:,![{;?&|+-*%~<>^'.includes(contenido[ultimoSignificativo])) return true;
+  if (cierresControl.has(ultimoSignificativo)) return true;
+  const palabra = obtenerPalabraSignificativa(contenido, ultimoSignificativo);
+  if (/^(?:return|case|throw|delete|typeof|void|new|await|yield|else|do)$/u.test(palabra)) {
+    return true;
+  }
+  if (contenido.slice(Math.max(0, ultimoSignificativo - 1), ultimoSignificativo + 1)
+    === '=>') return true;
+  return false;
+}
+
+function crearToken(contenido, tipo, inicio, fin) {
+  return { tipo, inicio, fin, texto: contenido.slice(inicio, fin) };
+}
+
+function reconocerDelimitadoJs(contenido, indice) {
+  const delimitador = contenido[indice];
+  if (!'"\'`'.includes(delimitador)) return null;
+  const fin = avanzarDelimitado(contenido, indice, delimitador);
+  const tipo = delimitador === '`' ? 'template' : 'string';
+  return crearToken(contenido, tipo, indice, fin);
+}
+
+function reconocerComentarioLineaJs(contenido, indice) {
+  if (contenido.slice(indice, indice + 2) !== '//') return null;
+  const salto = contenido.indexOf('\n', indice + 2);
+  const fin = salto < 0 ? contenido.length : salto;
+  return crearToken(contenido, 'comment', indice, fin);
+}
+
+function reconocerComentarioBloqueJs(contenido, indice) {
+  if (contenido.slice(indice, indice + 2) !== '/*') return null;
+  const cierre = contenido.indexOf('*/', indice + 2);
+  const fin = cierre < 0 ? contenido.length : cierre + 2;
+  return crearToken(contenido, 'comment', indice, fin);
+}
+
+function reconocerComentarioJs(contenido, indice) {
+  return reconocerComentarioLineaJs(contenido, indice)
+    || reconocerComentarioBloqueJs(contenido, indice);
+}
+
+function reconocerRegexJs(contenido, estado) {
+  if (contenido[estado.indice] !== '/') return null;
+  const esRegex = puedeIniciarRegex(
+    contenido,
+    estado.indice,
+    estado.ultimoSignificativo,
+    estado.cierresControl
+  );
+  if (!esRegex) return null;
+  const fin = avanzarRegexJs(contenido, estado.indice);
+  return crearToken(contenido, 'regex', estado.indice, fin);
+}
+
+function reconocerTokenJs(contenido, estado) {
+  return reconocerDelimitadoJs(contenido, estado.indice)
+    || reconocerComentarioJs(contenido, estado.indice)
+    || reconocerRegexJs(contenido, estado);
+}
+
+function consumirTokenJs(estado, token) {
+  estado.tokens.push(token);
+  if (token.tipo !== 'comment') estado.ultimoSignificativo = token.fin - 1;
+  estado.indice = token.fin;
+}
+
+function avanzarEstructuraJs(contenido, estado) {
+  const actual = contenido[estado.indice];
+  if (actual === '(') {
+    estado.parentesis.push(esAperturaControl(contenido, estado.ultimoSignificativo));
+  }
+  if (actual === ')' && estado.parentesis.pop()) estado.cierresControl.add(estado.indice);
+  if (!/\s/u.test(actual)) estado.ultimoSignificativo = estado.indice;
+  estado.indice += 1;
+}
+
+function tokenizarJs(contenido) {
+  const estado = {
+    tokens: [],
+    indice: 0,
+    ultimoSignificativo: -1,
+    parentesis: [],
+    cierresControl: new Set(),
+  };
+  while (estado.indice < contenido.length) {
+    const token = reconocerTokenJs(contenido, estado);
+    if (token) consumirTokenJs(estado, token);
+    else avanzarEstructuraJs(contenido, estado);
+  }
+  return estado.tokens;
+}
+
+function enmascararTokens(contenido, tokens) {
+  const fragmentos = [];
+  let cursor = 0;
+  for (const token of tokens) {
+    fragmentos.push(contenido.slice(cursor, token.inicio));
+    fragmentos.push(preservarSaltos(contenido.slice(token.inicio, token.fin)));
+    cursor = token.fin;
+  }
+  fragmentos.push(contenido.slice(cursor));
+  return fragmentos.join('');
+}
+
+function ocultarComentariosHistoricosJs(contenido) {
+  const historicos = tokenizarJs(contenido)
+    .filter(({ tipo }) => tipo === 'comment')
+    .flatMap(expandirLiteralJs)
+    .filter(({ texto }) => esComentarioHistorico(texto));
+  return enmascararTokens(contenido, historicos);
+}
+
+function ocultarComentariosHistoricosMarkdown(contenido) {
+  const comentarios = [...contenido.matchAll(/<!--[\s\S]*?-->/gu)]
+    .map((coincidencia) => ({
+      tipo: 'comment',
+      inicio: coincidencia.index,
+      fin: coincidencia.index + coincidencia[0].length,
+      texto: coincidencia[0],
+    }))
+    .flatMap(expandirLiteralJs)
+    .filter(({ texto }) => esComentarioHistorico(texto));
+  return enmascararTokens(contenido, comentarios);
+}
+
+function ocultarHistoria(contenido, extension) {
+  let salida = contenido;
+  if (extension === '.js') salida = ocultarComentariosHistoricosJs(salida);
+  if (extension === '.md') salida = ocultarComentariosHistoricosMarkdown(salida);
+  return salida.replace(
+    /const\s+CLAIM_README_LEGACY\s*=\s*\[[\s\S]*?\]\.join\([^;]+;/gu,
+    preservarSaltos
+  );
+}
+
+function neutralizarNombresTecnicos(unidad) {
+  return unidad.replace(
+    /(?:--)?(?:perfil|profile)[`"']?(?:\s+|\s*[:=]\s*)[`"']?completo[`"']?/giu,
+    'perfil'
+  );
+}
+
+function tieneRelacionDeClaim(evaluable, runtime, estado) {
+  if (PATRON_CONTEXTO_CLAIM.test(evaluable)) return true;
+  const runtimeFin = runtime.index + runtime[0].length;
+  const estadoFin = estado.index + estado[0].length;
+  if (runtime.index < estado.index) {
+    if (/^[\s"'`]*:\s*\[?\s*["'`]*$/u.test(evaluable.slice(runtimeFin, estado.index))) {
+      return true;
+    }
+    return /^(?:[\s"'`]*)(?:(?:es|est[aá]|figura como|queda(?: como)?|se considera)|[:=—-])(?:[\s"'`]*)$/iu
+      .test(evaluable.slice(runtimeFin, estado.index));
+  }
+  return /^(?:[\s"'`]*)(?:para(?: el runtime)?|[:=—-])(?:[\s"'`]*)$/iu
+    .test(evaluable.slice(estadoFin, runtime.index));
+}
+
+function obtenerCoincidencias(texto, patron) {
+  const flags = patron.flags.includes('g') ? patron.flags : `${patron.flags}g`;
+  return [...texto.matchAll(new RegExp(patron.source, flags))];
+}
+
+function detectarClaim(unidad, forzarContexto = false) {
+  const evaluable = neutralizarNombresTecnicos(unidad);
+  const runtimes = obtenerCoincidencias(evaluable, PATRON_RUNTIME);
+  const estados = obtenerCoincidencias(evaluable, PATRON_ESTADO);
+  const pares = runtimes.flatMap((runtime) => estados.map((estado) => ({ runtime, estado })))
+    .sort((a, b) => Math.abs(a.runtime.index - a.estado.index)
+      - Math.abs(b.runtime.index - b.estado.index));
+  const par = pares.find(({ runtime, estado }) => (
+    forzarContexto || tieneRelacionDeClaim(evaluable, runtime, estado)
+  ));
+  if (!par) return null;
+  const runtimeOrdinal = runtimes.filter((runtime) => (
+    runtime.index <= par.runtime.index
+      && runtime[0].toLowerCase() === par.runtime[0].toLowerCase()
+  )).length - 1;
+  return {
+    runtime: par.runtime[0],
+    estado: par.estado[0],
+    runtimeOrdinal,
+  };
+}
+
+function obtenerIndiceOcurrencia(contenido, texto, ordinal = 0, desde = 0) {
+  let indice = desde - 1;
+  for (let actual = 0; actual <= ordinal; actual += 1) {
+    indice = contenido.toLowerCase().indexOf(texto.toLowerCase(), indice + 1);
+    if (indice < 0) return -1;
+  }
+  return indice;
+}
+
+function obtenerLineaEnIndice(contenido, indice) {
+  if (indice < 0) return 1;
+  return contenido.slice(0, indice).split(/\r?\n/u).length;
+}
+
+function obtenerLinea(contenido, texto, desde = 0) {
+  return obtenerLineaEnIndice(contenido, obtenerIndiceOcurrencia(contenido, texto, 0, desde));
+}
+
+function crearHallazgo(rutaRelativa, line, claim) {
+  return {
+    path: rutaRelativa,
+    line,
+    runtime: claim.runtime,
+    estado: claim.estado,
+  };
+}
+
+function segmentarOracionesConOffset(texto) {
+  const oraciones = [];
+  let inicio = 0;
+  let indice = 0;
+  while (indice < texto.length) {
+    if (!'.!?'.includes(texto[indice])) {
+      indice += 1;
+      continue;
+    }
+    while (indice < texto.length && '.!?'.includes(texto[indice])) indice += 1;
+    oraciones.push({ inicio, texto: texto.slice(inicio, indice) });
+    inicio = indice;
+  }
+  if (inicio < texto.length) oraciones.push({ inicio, texto: texto.slice(inicio) });
+  return oraciones;
+}
+
+function segmentarLinea(linea) {
+  return segmentarOracionesConOffset(linea).map(({ texto }) => texto).filter(Boolean);
+}
+
+function esFilaTabla(linea) {
+  return linea.includes('|');
+}
+
+function esSeparadorTabla(linea) {
+  const celdas = obtenerCeldasTabla(linea);
+  return celdas.length > 0 && celdas.every((celda) => /^:?-+:?$/u.test(celda));
+}
+
+function normalizarCelda(celda) {
+  const sinMarkdown = normalizarMarkdown(celda).trim();
+  return sinMarkdown.replace(/^(["'])(.*)\1$/u, '$2').trim();
+}
+
+function normalizarMarkdown(texto) {
+  return texto
+    .replace(/!?\[([^\]]+)\]\([^)]+\)/gu, '$1')
+    .replace(/<\/?[\p{L}][^>]*>/gu, '')
+    .replace(/(?<![\p{L}\p{N}])_+(?=[\p{L}\p{N}])/gu, '')
+    .replace(/(?<=[\p{L}\p{N}])_+(?![\p{L}\p{N}])/gu, '')
+    .replace(/[*`~]/gu, '');
+}
+
+function coincideCompleto(valor, patron) {
+  const coincidencia = valor.match(patron);
+  return coincidencia?.index === 0 && coincidencia[0].length === valor.length;
+}
+
+function obtenerCeldasTabla(linea) {
+  const celdas = linea.split('|');
+  if (celdas[0].trim() === '') celdas.shift();
+  if (celdas.at(-1)?.trim() === '') celdas.pop();
+  return celdas.map(normalizarCelda);
+}
+
+function obtenerIndiceTarea(celdas) {
+  const normalizadas = celdas.map((celda) => celda.toLowerCase());
+  if (!normalizadas.includes('id')) return -1;
+  return normalizadas.indexOf('tarea');
+}
+
+function esFilaTareaDeFase(celdas, rutaRelativa, indiceTarea) {
+  return rutaRelativa.startsWith('.planning/fases/')
+    && indiceTarea >= 0
+    && /^\d+(?:\.\d+)*$/u.test(celdas[0] || '');
+}
+
+function detectarClaimEnFila(linea, rutaRelativa, indiceTarea) {
+  const celdas = obtenerCeldasTabla(linea);
+  const esTarea = esFilaTareaDeFase(celdas, rutaRelativa, indiceTarea);
+  const evaluables = esTarea
+    ? celdas.filter((_, indice) => indice !== indiceTarea)
+    : celdas;
+  for (const celda of evaluables) {
+    const claim = detectarClaim(celda);
+    if (claim) return claim;
+  }
+  const runtime = evaluables.find((celda) => coincideCompleto(celda, PATRON_RUNTIME));
+  const estado = evaluables.find((celda) => coincideCompleto(celda, PATRON_ESTADO));
+  return runtime && estado ? { runtime, estado } : null;
+}
+
+function rangoCanonico(contenido) {
+  const inicio = contenido.indexOf(MARCA_INICIO);
+  const fin = contenido.indexOf(MARCA_FIN, inicio);
+  if (inicio < 0 || fin < inicio) return null;
+  return {
+    inicio: obtenerLinea(contenido, MARCA_INICIO),
+    fin: obtenerLinea(contenido, MARCA_FIN, inicio),
+  };
+}
+
+function escanearTextoPorLinea(contenido, rutaRelativa, rango, esMarkdown) {
+  const hallazgos = [];
+  const lineas = contenido.split(/\r?\n/u);
+  let indiceTarea = -1;
+  for (let indice = 0; indice < lineas.length; indice += 1) {
+    const linea = lineas[indice];
+    const numero = indice + 1;
+    if (rango && numero >= rango.inicio && numero <= rango.fin) {
+      indiceTarea = -1;
+      continue;
+    }
+    if (esMarkdown && esSeparadorTabla(linea)) continue;
+    if (esMarkdown && esFilaTabla(linea)) {
+      const celdas = obtenerCeldasTabla(linea);
+      if (esSeparadorTabla(lineas[indice + 1] || '')) {
+        indiceTarea = obtenerIndiceTarea(celdas);
+        continue;
+      }
+      const claim = detectarClaimEnFila(linea, rutaRelativa, indiceTarea);
+      if (claim) hallazgos.push(crearHallazgo(rutaRelativa, numero, claim));
+      continue;
+    }
+    indiceTarea = -1;
+    for (const unidad of segmentarLinea(normalizarMarkdown(linea))) {
+      const claim = detectarClaim(unidad);
+      if (!claim) continue;
+      hallazgos.push(crearHallazgo(rutaRelativa, numero, claim));
+    }
+  }
+  return hallazgos;
+}
+
+function escanearParrafo(lineas, inicio, rutaRelativa) {
+  const texto = normalizarMarkdown(lineas.join('\n'));
+  const hallazgos = [];
+  for (const oracion of segmentarOracionesConOffset(texto)) {
+    const claim = detectarClaim(oracion.texto);
+    if (!claim) continue;
+    const indiceRuntime = obtenerIndiceOcurrencia(
+      oracion.texto,
+      claim.runtime,
+      claim.runtimeOrdinal
+    );
+    const offset = oracion.inicio + indiceRuntime;
+    const line = inicio + texto.slice(0, offset).split('\n').length - 1;
+    hallazgos.push(crearHallazgo(rutaRelativa, line, claim));
+  }
+  return hallazgos;
+}
+
+function escanearParrafosMarkdown(contenido, rutaRelativa, rango) {
+  const hallazgos = [];
+  let lineas = [];
+  let inicio = 1;
+  const vaciar = () => {
+    hallazgos.push(...escanearParrafo(lineas, inicio, rutaRelativa));
+    lineas = [];
+  };
+  contenido.split(/\r?\n/u).forEach((linea, indice) => {
+    const numero = indice + 1;
+    const seOmite = !linea.trim() || esFilaTabla(linea) || /^[\p{L}\p{N}_-]+:\s/iu.test(linea)
+      || (rango && numero >= rango.inicio && numero <= rango.fin);
+    if (seOmite) return vaciar();
+    if (lineas.length === 0) inicio = numero;
+    lineas.push(linea);
+  });
+  vaciar();
+  return hallazgos;
+}
+
+function escanearBloquesClaveValorMarkdown(contenido, rutaRelativa, rango) {
+  const hallazgos = [];
+  let entradas = [];
+  const vaciar = () => {
+    const relevantes = entradas.filter(({ clave }) => (
+      /^(?:runtime|target|soporte|support|estado|status|compatibilidad|conformidad|certificaci[oó]n)$/iu
+        .test(clave)
+    ));
+    const unidad = relevantes.map(({ clave, valor }) => `${clave}:${valor}`).join('\n');
+    const claim = detectarClaim(unidad, true);
+    const entradaRuntime = relevantes.find(({ valor }) => PATRON_RUNTIME.test(valor));
+    if (claim && entradaRuntime) {
+      hallazgos.push(crearHallazgo(rutaRelativa, entradaRuntime.linea, claim));
+    }
+    entradas = [];
+  };
+  contenido.split(/\r?\n/u).forEach((linea, indice) => {
+    const numero = indice + 1;
+    const coincidencia = linea.match(/^\s*([\p{L}\p{N}_-]+):\s*(.*?)\s*$/u);
+    if (!coincidencia || (rango && numero >= rango.inicio && numero <= rango.fin)) {
+      vaciar();
+      return;
+    }
+    entradas.push({ clave: coincidencia[1], valor: coincidencia[2], linea: numero });
+  });
+  vaciar();
+  return hallazgos;
+}
+
+function crearMascaraEstructuralJs(contenido, tokens) {
+  return enmascararTokens(contenido, tokens);
+}
+
+function esInicioObjetoJs(mascara, indice) {
+  let cursor = indice - 1;
+  while (cursor >= 0 && /\s/u.test(mascara[cursor])) cursor -= 1;
+  const anterior = mascara[cursor] || '';
+  const prefijo = mascara.slice(Math.max(0, cursor - 80), cursor + 1);
+  if (/tiposSoportados\s*=\s*$/u.test(prefijo)) return false;
+  return '=([,:'.includes(anterior) || /\b(?:return|default)$/u.test(prefijo);
+}
+
+function extraerObjetosJs(contenido, tokens) {
+  const mascara = crearMascaraEstructuralJs(contenido, tokens);
+  const pila = [];
+  const objetos = [];
+  for (let indice = 0; indice < mascara.length; indice += 1) {
+    if (mascara[indice] === '{') {
+      pila.push({ inicio: indice, esObjeto: esInicioObjetoJs(mascara, indice) });
+    }
+    if (mascara[indice] !== '}' || pila.length === 0) continue;
+    const actual = pila.pop();
+    if (actual.esObjeto) {
+      objetos.push({
+        tipo: 'object',
+        inicio: actual.inicio,
+        texto: contenido.slice(actual.inicio, indice + 1),
+      });
+    }
+  }
+  return objetos;
+}
+
+function encontrarFinValorJs(texto, inicio, tokens) {
+  let profundidad = 0;
+  let indiceToken = 0;
+  for (let indice = inicio; indice < texto.length; indice += 1) {
+    while (tokens[indiceToken]?.fin <= indice) indiceToken += 1;
+    const token = tokens[indiceToken];
+    if (token && token.inicio === indice) {
+      indice = token.fin - 1;
+      continue;
+    }
+    const caracter = texto[indice];
+    if ('[{('.includes(caracter)) profundidad += 1;
+    else if (']})'.includes(caracter)) {
+      if (profundidad === 0) return indice;
+      profundidad -= 1;
+    } else if (',;'.includes(caracter) && profundidad === 0) return indice;
+  }
+  return texto.length;
+}
+
+function esNombreTecnico(nombre) {
+  return /^(?:tiposSoportados|profiles?|perfiles?)$/iu.test(nombre);
+}
+
+function quitarRangosSolapados(rangos) {
+  const noSolapados = [];
+  for (const rango of rangos) {
+    if (rango.inicio >= (noSolapados.at(-1)?.fin || 0)) noSolapados.push(rango);
+  }
+  return noSolapados;
+}
+
+function ocultarSubarbolesTecnicosJs(texto) {
+  const tokens = tokenizarJs(texto);
+  const rangos = [];
+  const patronTecnico = new RegExp(
+    String.raw`(?<![\p{L}\p{N}_$])(?:tiposSoportados|profiles?|perfiles?)`,
+    'giu'
+  );
+  for (const coincidencia of texto.matchAll(patronTecnico)) {
+    const resto = texto.slice(coincidencia.index + coincidencia[0].length);
+    const separador = resto.match(/^["'`]?\s*\]?\s*[:=]/u);
+    if (!separador) continue;
+    const inicioValor = coincidencia.index + coincidencia[0].length + separador[0].length;
+    rangos.push({
+      inicio: coincidencia.index,
+      fin: encontrarFinValorJs(texto, inicioValor, tokens),
+    });
+  }
+  return enmascararTokens(texto, quitarRangosSolapados(rangos));
+}
+
+function ocultarSubarbolesTecnicosJsonFuente(texto) {
+  const tokens = tokenizarJs(texto);
+  const rangos = [];
+  for (const token of tokens.filter(({ tipo }) => tipo === 'string')) {
+    let clave;
+    try { clave = JSON.parse(token.texto); } catch { continue; }
+    if (!esNombreTecnico(clave)) continue;
+    const resto = texto.slice(token.fin);
+    const separador = resto.match(/^\s*:/u);
+    if (!separador) continue;
+    const inicioValor = token.fin + separador[0].length;
+    rangos.push({
+      inicio: token.inicio,
+      fin: encontrarFinValorJs(texto, inicioValor, tokens),
+    });
+  }
+  return enmascararTokens(texto, quitarRangosSolapados(rangos));
+}
+
+function esInicioClaveRuntimeJs(texto, runtime) {
+  let indice = runtime.index - 1;
+  while (indice >= 0 && /\s/u.test(texto[indice])) indice -= 1;
+  return indice < 0 || '{,\'"`'.includes(texto[indice]);
+}
+
+function detectarMapeoRuntimeJs(texto) {
+  if (!neutralizarNombresTecnicos(texto)) return null;
+  const tokens = tokenizarJs(texto);
+  for (const runtime of obtenerCoincidencias(texto, PATRON_RUNTIME)) {
+    if (!esInicioClaveRuntimeJs(texto, runtime)) continue;
+    const resto = texto.slice(runtime.index + runtime[0].length);
+    const separador = resto.match(/^["'`]?\s*\]?\s*:/u);
+    if (!separador) continue;
+    const inicioValor = runtime.index + runtime[0].length + separador[0].length;
+    const finValor = encontrarFinValorJs(texto, inicioValor, tokens);
+    const valor = neutralizarNombresTecnicos(texto.slice(inicioValor, finValor));
+    const estado = valor.match(PATRON_ESTADO);
+    if (estado) {
+      return {
+        runtime: runtime[0],
+        estado: estado[0],
+        runtimeIndex: runtime.index,
+      };
+    }
+  }
+  return null;
+}
+
+function escanearUnidadesJs(contenido, rutaRelativa, unidades) {
+  const hallazgos = [];
+  for (const { tipo, inicio, texto } of unidades) {
+    const claim = tipo === 'object'
+      ? detectarMapeoRuntimeJs(texto) || detectarClaim(texto)
+      : detectarClaim(texto);
+    if (!claim) continue;
+    const indiceLocal = claim.runtimeIndex ?? obtenerIndiceOcurrencia(
+      texto,
+      claim.runtime,
+      claim.runtimeOrdinal
+    );
+    hallazgos.push(crearHallazgo(
+      rutaRelativa,
+      obtenerLineaEnIndice(contenido, inicio + indiceLocal),
+      claim
+    ));
+  }
+  return hallazgos;
+}
+
+function expandirLiteralJs(token) {
+  return segmentarOracionesConOffset(token.texto)
+    .map((oracion) => ({
+      tipo: token.tipo,
+      inicio: token.inicio + oracion.inicio,
+      fin: token.inicio + oracion.inicio + oracion.texto.length,
+      texto: oracion.texto,
+    }));
+}
+
+function escanearJs(contenido, rutaRelativa, tokens) {
+  const literales = tokens
+    .filter(({ tipo }) => ['string', 'template', 'comment'].includes(tipo))
+    .flatMap(expandirLiteralJs);
+  const objetos = extraerObjetosJs(contenido, tokens);
+  return escanearUnidadesJs(
+    contenido,
+    rutaRelativa,
+    [...literales, ...objetos]
+  );
+}
+
+function colectarUnidadesJson(valor, unidades = []) {
+  if (!valor || typeof valor !== 'object') return unidades;
+  if (Array.isArray(valor)) {
+    valor.forEach((elemento) => colectarUnidadesJson(elemento, unidades));
+    return unidades;
+  }
+  unidades.push(valor);
+  Object.entries(valor).forEach(([clave, elemento]) => {
+    if (!esNombreTecnico(clave)) {
+      colectarUnidadesJson(elemento, unidades);
+    }
+  });
+  return unidades;
+}
+
+function detectarMapeoRuntimeJson(valor, ordinales = new Map()) {
+  if (!valor || typeof valor !== 'object') return null;
+  if (Array.isArray(valor)) {
+    for (const elemento of valor) {
+      const claim = detectarMapeoRuntimeJson(elemento, ordinales);
+      if (claim) return claim;
+    }
+    return null;
+  }
+  for (const [clave, descendiente] of Object.entries(valor)) {
+    const esRuntime = coincideCompleto(clave, PATRON_RUNTIME);
+    if (esRuntime) {
+      const identificador = clave.toLowerCase();
+      const runtimeKeyOrdinal = ordinales.get(identificador) || 0;
+      ordinales.set(identificador, runtimeKeyOrdinal + 1);
+      const serializado = neutralizarNombresTecnicos(JSON.stringify(descendiente));
+      const estado = serializado.match(PATRON_ESTADO);
+      if (estado) return { runtime: clave, estado: estado[0], runtimeKeyOrdinal };
+    }
+    const claimAnidado = detectarMapeoRuntimeJson(descendiente, ordinales);
+    if (claimAnidado) return claimAnidado;
+  }
+  return null;
+}
+
+function analizarClavesJson(contenido) {
+  const tokens = tokenizarJs(contenido);
+  const scopes = [];
+  const claves = [];
+  let indiceToken = 0;
+  for (let indice = 0; indice < contenido.length; indice += 1) {
+    const token = tokens[indiceToken];
+    if (token && token.inicio === indice) {
+      if (token.tipo === 'string') {
+        let cursor = token.fin;
+        while (/\s/u.test(contenido[cursor] || '')) cursor += 1;
+        if (contenido[cursor] === ':') {
+          const clave = JSON.parse(token.texto);
+          const scope = scopes.at(-1);
+          if (scope?.has(clave)) throw new Error(`clave JSON duplicada: ${clave}`);
+          scope?.add(clave);
+          claves.push({ clave, index: token.inicio });
+        }
+      }
+      indice = token.fin - 1;
+      indiceToken += 1;
+      continue;
+    }
+    if (contenido[indice] === '{') scopes.push(new Set());
+    else if (contenido[indice] === '}') scopes.pop();
+  }
+  return claves;
+}
+
+function obtenerLineaClaveJson(contenido, runtime, ordinal) {
+  const claves = analizarClavesJson(contenido)
+    .filter(({ clave }) => clave.toLowerCase() === runtime.toLowerCase());
+  return obtenerLineaEnIndice(contenido, claves[ordinal]?.index ?? -1);
+}
+
+function eliminarSubarbolesTecnicosJson(valor) {
+  if (!valor || typeof valor !== 'object') return;
+  if (Array.isArray(valor)) {
+    valor.forEach(eliminarSubarbolesTecnicosJson);
+    return;
+  }
+  for (const [clave, descendiente] of Object.entries(valor)) {
+    if (esNombreTecnico(clave)) delete valor[clave];
+    else eliminarSubarbolesTecnicosJson(descendiente);
+  }
+}
+
+function escanearJson(contenido, rutaRelativa, esJsonRegistrado) {
+  analizarClavesJson(contenido);
+  const fuenteEscaneable = ocultarSubarbolesTecnicosJsonFuente(contenido);
+  const documento = JSON.parse(contenido);
+  eliminarSubarbolesTecnicosJson(documento);
+  if (esJsonRegistrado) delete documento.description;
+  const serializada = JSON.stringify(documento);
+  const mapeo = detectarMapeoRuntimeJson(documento);
+  const claim = mapeo || detectarClaim(serializada);
+  if (!claim) return [];
+  const line = mapeo
+    ? obtenerLineaClaveJson(fuenteEscaneable, claim.runtime, claim.runtimeKeyOrdinal)
+    : obtenerLineaEnIndice(
+      fuenteEscaneable,
+      obtenerIndiceOcurrencia(fuenteEscaneable, claim.runtime, claim.runtimeOrdinal)
+    );
+  return [crearHallazgo(rutaRelativa, line, claim)];
+}
+
+function deduplicarHallazgos(hallazgos) {
+  const unicos = new Map();
+  for (const hallazgo of hallazgos) {
+    const clave = `${hallazgo.path}:${hallazgo.line}`;
+    if (!unicos.has(clave)) unicos.set(clave, hallazgo);
+  }
+  return [...unicos.values()];
+}
+
+function estaRegistrada(rutaRelativa, superficies) {
+  return (superficies || []).some(({ path: ruta }) => ruta === rutaRelativa);
+}
+
+function escanearArchivoMarkdown(contenido, rutaRelativa, registry) {
+  const superficies = [...(registry.markdown || []), ...(registry.managed || [])];
+  const rango = estaRegistrada(rutaRelativa, superficies) ? rangoCanonico(contenido) : null;
+  return [
+    ...escanearTextoPorLinea(contenido, rutaRelativa, rango, true),
+    ...escanearParrafosMarkdown(contenido, rutaRelativa, rango),
+    ...escanearBloquesClaveValorMarkdown(contenido, rutaRelativa, rango),
+  ];
+}
+
+function escanearArchivoJavaScript(contenido, rutaRelativa) {
+  const escaneable = ocultarSubarbolesTecnicosJs(contenido);
+  const tokens = tokenizarJs(escaneable);
+  const sinRegex = enmascararTokens(
+    escaneable,
+    tokens.filter(({ tipo }) => tipo === 'regex')
+  );
+  return [
+    ...escanearTextoPorLinea(sinRegex, rutaRelativa, null, false),
+    ...escanearJs(escaneable, rutaRelativa, tokens),
+  ];
+}
+
+function escanearArchivo(
+  root,
+  rutaRelativa,
+  registry,
+  resolver = (ruta) => resolverRuta(root, ruta)
+) {
+  const extension = path.extname(rutaRelativa).toLowerCase();
+  const contenido = ocultarHistoria(
+    fs.readFileSync(resolver(rutaRelativa), 'utf8'),
+    extension
+  );
+  if (extension === '.json') {
+    return escanearJson(contenido, rutaRelativa, estaRegistrada(rutaRelativa, registry.json));
+  }
+  if (extension === '.md') return escanearArchivoMarkdown(contenido, rutaRelativa, registry);
+  if (extension === '.js') return escanearArchivoJavaScript(contenido, rutaRelativa);
+  return [];
+}
+
+function escanearClaimsLegacy(opciones = {}) {
+  const root = path.resolve(opciones.root || RAIZ);
+  if (!Array.isArray(opciones.trackedFiles)) {
+    const trackedFiles = listarCandidatos(root, opciones);
+    return escanearClaimsLegacy({ ...opciones, root, trackedFiles });
+  }
+  const registry = opciones.registry || REGISTRO_SUPERFICIES;
+  const candidatos = listarCandidatos(root, opciones)
+    .map(normalizarRuta)
+    .filter((ruta) => EXTENSIONES_ESCANEADAS.has(path.extname(ruta).toLowerCase()))
+    .filter((ruta) => !esRutaExcluida(ruta));
+  const hallazgos = [];
+  const resolver = crearResolvedorConfinado(root);
+  candidatos.forEach((ruta) => {
+    hallazgos.push(...escanearArchivo(root, ruta, registry, resolver));
+  });
+  return deduplicarHallazgos(hallazgos);
+}
+
+function verificarClaims(opciones = {}) {
+  const preparacion = intentarPreparar(opciones, 'stable');
+  if (!preparacion.ok) return {
+    ok: false,
+    code: preparacion.code,
+    errors: preparacion.errors,
+  };
+  const drift = preparacion.cambios.filter(({ original, salida }) => original !== salida);
+  try {
+    const claimsLegacy = escanearClaimsLegacy(opciones);
+    const ok = drift.length === 0 && claimsLegacy.length === 0;
+    const errors = claimsLegacy.map(({ path: ruta, line }) => `claim legacy: ${ruta}:${line}`);
+    return { ok, code: ok ? 0 : 2, drift, claimsLegacy, errors };
+  } catch (error) {
+    return { ok: false, code: 1, drift, claimsLegacy: [], errors: [error.message] };
+  }
+}
+
+function parsearArgs(argv) {
+  const opciones = {};
+  const modos = new Set(['--migrate-bootstrap', '--write', '--check']);
+  const prefijos = ['--root=', '--manifest='];
+  const desconocido = argv.find((argumento) => (
+    !modos.has(argumento) && !prefijos.some((prefijo) => argumento.startsWith(prefijo))
+  ));
+  if (desconocido) throw new TypeError(`argumento desconocido: ${desconocido}`);
+  const presentes = argv.filter((argumento) => modos.has(argumento));
+  if (presentes.length !== 1) throw new TypeError('indica exactamente un modo: --migrate-bootstrap, --write o --check');
+  opciones.mode = presentes[0];
+  for (const argumento of argv) {
+    if (argumento.startsWith('--root=')) opciones.root = argumento.slice(7);
+    if (argumento.startsWith('--manifest=')) opciones.manifestPath = argumento.slice(11);
+  }
+  return opciones;
+}
+
+function main(argv = process.argv.slice(2), dependencias = {}) {
+  try {
+    const opciones = parsearArgs(argv);
+    if (dependencias.registry) opciones.registry = dependencias.registry;
+    if (dependencias.trackedFiles) opciones.trackedFiles = dependencias.trackedFiles;
+    const resultado = opciones.mode === '--migrate-bootstrap'
+      ? migrarBootstrap(opciones)
+      : opciones.mode === '--write' ? escribirClaims(opciones) : verificarClaims(opciones);
+    if (!resultado.ok) console.error(`[generar-claims-runtime] ${resultado.errors?.join('; ') || 'drift detectado'}`);
+    process.exitCode = opciones.mode === '--check' ? resultado.code : (resultado.ok ? 0 : 1);
+    return resultado;
+  } catch (error) {
+    console.error(`[generar-claims-runtime] ${error.message}`);
+    process.exitCode = 1;
+    return { ok: false, errors: [error.message] };
+  }
+}
+
+module.exports = {
+  DESCRIPCION,
+  MARCA_FIN,
+  MARCA_INICIO,
+  REGISTRO_SUPERFICIES,
+  escanearClaimsLegacy,
+  escribirClaims,
+  main,
+  migrarBootstrap,
+  parsearArgs,
+  renderBloque,
+  verificarClaims,
+};
+
+if (require.main === module) main();