@saulwade/swl-ses 1.6.1 → 1.6.5

package/hooks/lib/deep-links.js

@@ -0,0 +1,185 @@
+'use strict';
+
+/**
+ * Deep Links — Helper zero-deps para construir URLs que abren archivos en
+ * IDEs y editores directamente desde notificaciones.
+ *
+ * Cubre VS Code (vscode://), VS Code Insiders, Cursor (cursor://), JetBrains
+ * (jetbrains://), Codex Desktop (codex://) y fallbacks para apps sin esquema
+ * oficial (Visual Studio en Windows usa CLI fallback).
+ *
+ * Documentación funcional y matriz de soporte en:
+ *   habilidades/agent-deep-links/SKILL.md
+ *
+ * Documentado en ADR-0029 (integración parcial awesome-codex-skills).
+ *
+ * @module hooks/lib/deep-links
+ */
+
+const path = require('node:path');
+
+/**
+ * IDEs soportados con esquema oficial confiable.
+ * Cualquier valor fuera de esta lista retorna null en construirDeepLink.
+ */
+const IDES_SOPORTADOS = Object.freeze([
+  'vscode',
+  'vscode-insiders',
+  'cursor',
+  'codex',
+  'jetbrains-idea',
+  'jetbrains-pycharm',
+  'jetbrains-webstorm',
+  'jetbrains-goland',
+  'jetbrains-rubymine',
+  'jetbrains-clion',
+  'jetbrains-rider',
+  'jetbrains-phpstorm',
+]);
+
+/**
+ * Map de IDE → esquema base. JetBrains usa formato distinto (manejado en
+ * función separada).
+ */
+const ESQUEMAS = Object.freeze({
+  'vscode':           'vscode://file',
+  'vscode-insiders':  'vscode-insiders://file',
+  'cursor':           'cursor://file',
+});
+
+/**
+ * Indica si un IDE soporta deep links a archivo:línea.
+ *
+ * @param {string} ide - Identificador del IDE.
+ * @returns {boolean}
+ */
+function soportaDeepLinks(ide) {
+  if (typeof ide !== 'string') return false;
+  return IDES_SOPORTADOS.includes(ide);
+}
+
+/**
+ * Normaliza un path absoluto para uso en deep links.
+ * - Resuelve a absoluto (rechaza relativos).
+ * - Normaliza separadores (Windows backslash → forward slash; VS Code/Cursor
+ *   aceptan forward slashes incluso en Windows).
+ * - Encoding URI para espacios y caracteres especiales.
+ *
+ * @param {string} rutaAbsoluta
+ * @returns {string|null}
+ * @private
+ */
+function _normalizarPath(rutaAbsoluta) {
+  if (typeof rutaAbsoluta !== 'string' || rutaAbsoluta.length === 0) {
+    return null;
+  }
+  if (!path.isAbsolute(rutaAbsoluta)) {
+    return null;
+  }
+  // path.resolve normaliza .., ., dobles separadores.
+  const resuelto = path.resolve(rutaAbsoluta);
+  // Forward slashes en todos los SO — los IDEs los aceptan en Windows también.
+  const forwardSlashes = resuelto.split(path.sep).join('/');
+  // encodeURI preserva : y / (los necesitamos), encodea espacios y caracteres especiales.
+  return encodeURI(forwardSlashes);
+}
+
+/**
+ * Valida que línea y columna sean enteros positivos si están definidos.
+ * @private
+ */
+function _validarPosicion(linea, columna) {
+  if (linea !== undefined && linea !== null) {
+    if (!Number.isInteger(linea) || linea < 1) return false;
+  }
+  if (columna !== undefined && columna !== null) {
+    if (!Number.isInteger(columna) || columna < 1) return false;
+  }
+  return true;
+}
+
+/**
+ * Construye un deep link para abrir un archivo en el IDE especificado.
+ *
+ * Retorna null cuando:
+ *   - El IDE no soporta deep links a archivos (Codex Desktop, Xcode, etc.).
+ *   - La ruta no es absoluta o está vacía.
+ *   - Línea/columna están definidas pero no son enteros positivos.
+ *   - El IDE es JetBrains pero falta `proyecto` (requerido).
+ *
+ * @param {object} params
+ * @param {string} params.ide - 'vscode' | 'vscode-insiders' | 'cursor' | 'jetbrains-<ide-id>'
+ * @param {string} params.rutaAbsoluta - Path absoluto al archivo. Forward o backslashes.
+ * @param {number} [params.linea] - Línea 1-indexed.
+ * @param {number} [params.columna] - Columna 1-indexed.
+ * @param {string} [params.proyecto] - Solo para JetBrains: nombre del proyecto.
+ * @returns {string|null} URL del deep link, o null si no se puede construir.
+ */
+function construirDeepLink(params) {
+  const { ide, rutaAbsoluta, linea, columna, proyecto } = params || {};
+
+  if (!soportaDeepLinks(ide)) return null;
+  if (!_validarPosicion(linea, columna)) return null;
+
+  const pathNormalizado = _normalizarPath(rutaAbsoluta);
+  if (!pathNormalizado) return null;
+
+  // JetBrains usa un formato distinto al resto.
+  if (ide.startsWith('jetbrains-')) {
+    if (!proyecto || typeof proyecto !== 'string') return null;
+    const ideId = ide.slice('jetbrains-'.length);
+    // jetbrains://idea/navigate/reference?project=<name>&path=<rel>:<line>
+    const query = new URLSearchParams({
+      project: proyecto,
+      path: linea ? `${pathNormalizado}:${linea}` : pathNormalizado,
+    }).toString();
+    return `jetbrains://${ideId}/navigate/reference?${query}`;
+  }
+
+  // VS Code / Cursor / VS Code Insiders.
+  const base = ESQUEMAS[ide];
+  let url = `${base}${pathNormalizado.startsWith('/') ? '' : '/'}${pathNormalizado}`;
+  if (linea) {
+    url += `:${linea}`;
+    if (columna) {
+      url += `:${columna}`;
+    }
+  }
+  return url;
+}
+
+/**
+ * Formato según receptor — envuelve un deep link en la sintaxis correcta del
+ * canal destino. Devuelve texto plano (con sufijo "(abrir manualmente)") si
+ * el deep link es null.
+ *
+ * @param {string|null} deepLink - URL del deep link, o null para fallback.
+ * @param {string} etiqueta - Texto visible para el usuario.
+ * @param {string} receptor - 'telegram' | 'discord' | 'slack' | 'email' | 'plain'
+ * @returns {string}
+ */
+function formatearEnlace(deepLink, etiqueta, receptor) {
+  if (!deepLink) {
+    return `${etiqueta} (abrir manualmente)`;
+  }
+  switch (receptor) {
+    case 'slack':
+      return `<${deepLink}|${etiqueta}>`;
+    case 'telegram':
+    case 'discord':
+      // Ambos usan Markdown estándar para enlaces.
+      return `[${etiqueta}](${deepLink})`;
+    case 'email':
+      return `<a href="${deepLink}">${etiqueta}</a>`;
+    case 'plain':
+    default:
+      return `${etiqueta}: ${deepLink}`;
+  }
+}
+
+module.exports = {
+  construirDeepLink,
+  formatearEnlace,
+  soportaDeepLinks,
+  IDES_SOPORTADOS,
+};

package/hooks/lib/evolution-tracker.js

@@ -345,6 +345,30 @@ function _stripEvolutionFields(content) {
     .join('\n');
 }
 
+/**
+ * Separa frontmatter YAML del body en un archivo markdown SWL.
+ *
+ * Cuando se calcula el diff de mutaciones de un archivo evolucionado, el
+ * frontmatter SIEMPRE diverge (el destino tiene campos `evolved-*` que el
+ * origen no tiene, y viceversa con campos nuevos del paquete). Contar esas
+ * diferencias como "mutaciones del usuario" genera ruido masivo por
+ * desplazamiento de líneas. Esta función permite comparar solo el body.
+ *
+ * @param {string} content - Contenido completo del archivo .md.
+ * @returns {{ frontmatter: string, body: string }}
+ *   - `frontmatter`: bloque YAML entre `---` (vacío si no hay frontmatter).
+ *   - `body`: todo lo que viene después del frontmatter cerrado.
+ * @private
+ */
+function _splitFrontmatterAndBody(content) {
+  const m = content.match(/^(---\r?\n[\s\S]*?\r?\n---\r?\n?)([\s\S]*)$/);
+  if (!m) return { frontmatter: '', body: content };
+  return { frontmatter: m[1], body: m[2] };
+}
+
+/** Umbral defensivo: tras este número de diffs el archivo pasa a modo resumen. */
+const DIFF_NOISY_THRESHOLD = 50;
+
 // ---------------------------------------------------------------------------
 // Merge de evoluciones
 // ---------------------------------------------------------------------------
@@ -356,10 +380,29 @@ function _stripEvolutionFields(content) {
  * evolución (frontmatter evolved-*). Las mutaciones de contenido se preservan
  * generando un archivo .evolved-diff.md que Claude puede re-aplicar.
  *
+ * Comparación: solo el body (post-frontmatter) se compara línea-a-línea.
+ * El frontmatter SIEMPRE diverge (el destino tiene campos `evolved-*` que el
+ * origen no tiene, y viceversa con campos nuevos del paquete), por lo que
+ * contarlo como mutación genera ruido por desplazamiento.
+ *
+ * Limpieza: cuando un merge posterior elimina la divergencia (diffs vacíos),
+ * borra el `.evolved-diff.md` huérfano de sesiones previas si existe.
+ *
+ * Cap defensivo: si tras alinear correctamente el body aún hay más de
+ * `DIFF_NOISY_THRESHOLD` líneas distintas, genera un resumen estadístico
+ * con muestra (primeras 20 + últimas 5) en lugar del dump completo.
+ *
  * @param {string} destino      - Ruta del archivo evolucionado (local).
  * @param {string} origen       - Ruta del archivo nuevo del paquete.
  * @param {string} versionNueva - Versión del paquete nuevo.
- * @returns {{ merged: boolean, diffPath?: string, error?: string }}
+ * @returns {{
+ *   merged: boolean,
+ *   diffPath?: string,
+ *   diffsCount?: number,
+ *   cleanedDiff?: boolean,
+ *   truncated?: boolean,
+ *   error?: string
+ * }}
  */
 function mergeEvolved(destino, origen, versionNueva) {
   try {
@@ -375,11 +418,14 @@ function mergeEvolved(destino, origen, versionNueva) {
     const destinoContent = fs.readFileSync(destino, 'utf8');
     const origenContent  = fs.readFileSync(origen, 'utf8');
 
-    // Extraer las líneas que son diferentes entre destino (sin evolved fields) y origen.
-    // Normalizar CRLF a LF para comparar independientemente del SO de origen.
-    const destinoSinEvo = _stripEvolutionFields(destinoContent);
-    const origenLines    = origenContent.split(/\r?\n/);
-    const destinoLines   = destinoSinEvo.split(/\r?\n/);
+    // Comparar SOLO el body, no el frontmatter. El frontmatter del destino
+    // tiene los campos `evolved-*` que el origen no tiene — contarlos como
+    // mutaciones desplaza todas las líneas siguientes y genera ruido.
+    const { body: destinoBody } = _splitFrontmatterAndBody(destinoContent);
+    const { body: origenBody  } = _splitFrontmatterAndBody(origenContent);
+
+    const origenLines  = origenBody.split(/\r?\n/);
+    const destinoLines = destinoBody.split(/\r?\n/);
 
     const diffs = [];
     const maxLen = Math.max(origenLines.length, destinoLines.length);
@@ -395,34 +441,85 @@ function mergeEvolved(destino, origen, versionNueva) {
       }
     }
 
+    const diffPath = destino.replace(/\.md$/, '.evolved-diff.md');
+
     if (diffs.length === 0) {
-      // Sin diferencias reales — solo re-aplicar campos evolved al nuevo
+      // Sin diferencias reales — limpiar diff huérfano si existe (de sesión
+      // previa donde sí hubo divergencia que ya quedó resuelta) y re-aplicar
+      // campos evolved al destino.
+      let cleanedDiff = false;
+      if (fs.existsSync(diffPath)) {
+        try {
+          fs.unlinkSync(diffPath);
+          cleanedDiff = true;
+        } catch {
+          // Best-effort: si el unlink falla por permisos/locks, dejarlo —
+          // el merge sigue siendo válido.
+        }
+      }
+
+      // force: true — `mergeEvolved` solo se invoca en contexto de update
+      // intencional. El skip de isPackageRoot() aplica a la primera marca
+      // del mantenedor, no a re-aplicar campos tras un merge resuelto.
       const marked = markAsEvolved(destino, {
         from: versionNueva,
         by: evo.metadata.evolvedBy || 'auto-evolución',
         rounds: evo.metadata.evolvedRounds ? parseInt(evo.metadata.evolvedRounds, 10) : undefined,
         score: evo.metadata.evolvedScore,
         note: `Re-aplicado desde v${evo.metadata.evolvedFrom || '?'} tras actualización a v${versionNueva}`,
+        force: true,
       });
-      return { merged: marked.marked };
+      return { merged: marked.marked, cleanedDiff };
     }
 
-    // Guardar diff para revisión/re-aplicación por Claude
-    const diffPath = destino.replace(/\.md$/, '.evolved-diff.md');
-    const diffContent = [
+    // Cap defensivo: tras alinear correctamente sigue habiendo más de N diffs.
+    // En lugar de dumpear cada línea (puede explotar a miles), generar resumen
+    // con muestra acotada.
+    const truncated = diffs.length > DIFF_NOISY_THRESHOLD;
+    const diffsParaMostrar = truncated
+      ? [...diffs.slice(0, 20), ...diffs.slice(-5)]
+      : diffs;
+
+    const header = [
       `# Diff de evolución — ${path.basename(destino)}`,
       ``,
       `**Archivo evolucionado por**: ${evo.metadata.evolvedBy || 'auto-evolución'}`,
       `**Versión base original**: ${evo.metadata.evolvedFrom || '?'}`,
       `**Versión nueva**: ${versionNueva}`,
       `**Fecha**: ${new Date().toISOString().split('T')[0]}`,
+      `**Diferencias detectadas (body)**: ${diffs.length}`,
       ``,
-      `## Mutaciones locales a re-aplicar`,
-      ``,
-      `Estas son las líneas que difieren entre la versión evolucionada y la nueva.`,
-      `Re-aplicar con \`/swl:autoresearch\` o manualmente.`,
-      ``,
-      ...diffs.map(d => [
+    ];
+
+    if (truncated) {
+      header.push(
+        `## ⚠ Resumen (truncado)`,
+        ``,
+        `El diff excede el umbral defensivo de ${DIFF_NOISY_THRESHOLD} líneas`,
+        `(${diffs.length} diferencias detectadas). Esto suele indicar:`,
+        ``,
+        `- El archivo fue reescrito completo entre versiones (rebrand, refactor).`,
+        `- El alineamiento línea-a-línea no es útil aquí — usar \`git diff\`.`,
+        ``,
+        `Se muestran las primeras 20 + últimas 5 diferencias como muestra.`,
+        `Para diff completo: \`diff <(sed '1,/^---$/d; 1,/^---$/d' archivo) <(...)\`.`,
+        ``,
+        `## Muestra de mutaciones (primeras 20 + últimas 5)`,
+        ``,
+      );
+    } else {
+      header.push(
+        `## Mutaciones locales a re-aplicar`,
+        ``,
+        `Estas son las líneas del body que difieren entre la versión`,
+        `evolucionada y la nueva. Re-aplicar con \`/swl:autoresearch\` o manualmente.`,
+        ``,
+      );
+    }
+
+    const diffContent = [
+      ...header,
+      ...diffsParaMostrar.map(d => [
         `### Línea ${d.line}`,
         `- **Nueva (base)**: \`${d.origen}\``,
         `- **Evolucionada**: \`${d.destino}\``,
@@ -432,7 +529,7 @@ function mergeEvolved(destino, origen, versionNueva) {
 
     atomicWriteSync(diffPath, diffContent, 'utf8');
 
-    return { merged: true, diffPath, diffsCount: diffs.length };
+    return { merged: true, diffPath, diffsCount: diffs.length, truncated };
   } catch (err) {
     return { merged: false, error: err.message };
   }

package/hooks/lib/gateway-notify.js

@@ -21,9 +21,23 @@ const fs   = require('fs');
 const path = require('path');
 const { atomicWriteJSON } = require('./atomic-write');
 
+// Deep links opt-in (ADR-0029). Si el módulo no carga (instalación incompleta),
+// el enriquecimiento se omite silenciosamente — comportamiento default sin
+// cambios respecto a versiones previas.
+let construirDeepLink, formatearEnlace;
+try {
+  ({ construirDeepLink, formatearEnlace } = require('./deep-links'));
+} catch {
+  construirDeepLink = () => null;
+  formatearEnlace   = (_, etiqueta) => etiqueta;
+}
+
 const COMMS_DIR = '.planning/comms';
 const CONFIG_PATH = 'manifiestos/gateway-config.json';
 
+/** Receptores reconocidos para formato de deep link. */
+const RECEPTORES = new Set(['telegram', 'discord', 'slack', 'email', 'plain']);
+
 /**
  * Verifica si el gateway está habilitado en configuración.
  * @returns {boolean}
@@ -66,10 +80,52 @@ function tipoHabilitado(tipo) {
   }
 }
 
+/**
+ * Si el payload incluye `fileRef` + `idePreferido`, retorna el enlace
+ * formateado al receptor; en otro caso retorna null. No modifica el payload.
+ *
+ * Estructura esperada del payload (opt-in, ADR-0029):
+ *   payload.fileRef = {
+ *     archivo: '/abs/path/al/archivo.js',
+ *     linea?: 42,
+ *     columna?: 8,
+ *     etiqueta?: 'Abrir archivo.js:42',   // default: archivo:linea
+ *     proyecto?: 'mi-proyecto',           // requerido solo para JetBrains
+ *   }
+ *   payload.idePreferido = 'vscode' | 'cursor' | ...
+ *
+ * @param {object} payload
+ * @param {string} receptor - 'telegram' | 'discord' | 'slack' | 'email' | 'plain'
+ * @returns {string|null}
+ * @private
+ */
+function _construirEnlaceFileRef(payload, receptor) {
+  if (!payload || !payload.fileRef || !payload.idePreferido) return null;
+  const { archivo, linea, columna, etiqueta, proyecto } = payload.fileRef;
+  if (!archivo) return null;
+
+  const url = construirDeepLink({
+    ide: payload.idePreferido,
+    rutaAbsoluta: archivo,
+    linea,
+    columna,
+    proyecto,
+  });
+
+  const label = etiqueta || (linea ? `${path.basename(archivo)}:${linea}` : path.basename(archivo));
+  const formato = RECEPTORES.has(receptor) ? receptor : 'plain';
+  return formatearEnlace(url, label, formato);
+}
+
 /**
  * Encola una notificación para el gateway.
  * No bloquea ni lanza. Retorna true si se encoló, false si fue descartada.
  *
+ * Enriquecimiento opt-in (ADR-0029): si `params.payload.fileRef` +
+ * `params.payload.idePreferido` están presentes, el mensaje agrega el campo
+ * `enlace` con un deep link formateado al receptor. Sin esos campos, el
+ * comportamiento es idéntico al previo (compatibilidad hacia atrás).
+ *
  * @param {object} params
  * @param {string} params.tipo - session-stop, checkpoint, error, release, build-fail, custom
  * @param {string} [params.titulo] - Título corto.
@@ -89,17 +145,24 @@ function notificarGateway(params) {
     }
 
     const id = `msg-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+    const receptor = params.to || 'all';
+    const payloadBase = {
+      tipo:   params.tipo,
+      titulo: params.titulo || '',
+      texto:  params.texto  || '',
+      ...(params.payload || {}),
+    };
+
+    // Enriquecimiento opt-in con deep link (ADR-0029).
+    const enlace = _construirEnlaceFileRef(payloadBase, receptor);
+    if (enlace) payloadBase.enlace = enlace;
+
     const msg = {
       id,
       type:   'gateway_notification',
       from:   'swl-system',
-      to:     params.to || 'all',
-      payload: {
-        tipo:   params.tipo,
-        titulo: params.titulo || '',
-        texto:  params.texto  || '',
-        ...(params.payload || {}),
-      },
+      to:     receptor,
+      payload: payloadBase,
       text: params.texto || '',
       timestamp: new Date().toISOString(),
       status: 'pending',

package/hooks/lib/task-budget.js

@@ -0,0 +1,218 @@
+'use strict';
+
+/**
+ * task-budget.js — presupuesto SEMÁNTICO de tokens por tarea.
+ *
+ * Adaptación de SuperClaude_Framework `pm_agent/token_budget.py` (MIT) a Node
+ * zero-deps. Provee un contrato de presupuesto por COMPLEJIDAD de tarea que
+ * agentes y orquestador pueden consultar para gating, NO un contador exacto
+ * de tokens consumidos (el modelo no expone tokens en runtime).
+ *
+ * IMPORTANTE: no confundir con `hooks/lib/token-budget.js`, que distribuye
+ * presupuesto entre BLOQUES DE CONTEXTO (memoria/observaciones/reglas) con
+ * scoring de recencia+importancia. Aquel es para inyección de contexto;
+ * éste es para clasificación de TAREAS.
+ *
+ * Niveles de complejidad y presupuesto recomendado:
+ *   - simple:  200   tokens — typo fix, rename, comentario, formato.
+ *   - medium:  1000  tokens — bugfix acotado, feature pequeña.
+ *   - complex: 2500  tokens — feature grande, refactor cross-módulo.
+ *
+ * Uso típico:
+ *   const { TaskBudget } = require('./task-budget');
+ *   const budget = new TaskBudget('medium');
+ *   if (budget.tryUse(150)) {
+ *     // proceder con la sub-tarea
+ *   } else {
+ *     // presupuesto agotado — pausar, reportar, escalar
+ *   }
+ *
+ * Semántica de "rebasado": si un agente declara tarea "simple" y consume
+ * 800 tokens, hay señal de que la clasificación fue incorrecta o el scope
+ * creció. El orquestador puede actuar (re-clasificar, pausar, alertar).
+ *
+ * @module hooks/lib/task-budget
+ */
+
+/** @typedef {'simple' | 'medium' | 'complex'} ComplexityLevel */
+
+/**
+ * Límites por defecto. Defaults recomendados por el material fuente
+ * (SuperClaude pm_agent). Modificables vía constructor para escenarios
+ * especiales.
+ * @type {Readonly<Record<ComplexityLevel, number>>}
+ */
+const DEFAULT_LIMITS = Object.freeze({
+  simple: 200,
+  medium: 1000,
+  complex: 2500,
+});
+
+/**
+ * Gestor de presupuesto semántico por tarea.
+ *
+ * Inmutable en `limit` y `complexity` tras la construcción; mutable solo
+ * en `used` vía `tryUse()` / `forceUse()` / `reset()`.
+ */
+class TaskBudget {
+  /**
+   * @param {ComplexityLevel} [complexity='medium'] - Complejidad declarada.
+   * @param {Partial<Record<ComplexityLevel, number>>} [overrides] - Límites custom.
+   */
+  constructor(complexity = 'medium', overrides = undefined) {
+    const limits = overrides
+      ? Object.freeze({ ...DEFAULT_LIMITS, ...overrides })
+      : DEFAULT_LIMITS;
+
+    // Default defensivo a 'medium' si llega un nivel desconocido — el
+    // material fuente hace lo mismo. Evita excepciones por typo.
+    const normalized = Object.prototype.hasOwnProperty.call(limits, complexity)
+      ? complexity
+      : 'medium';
+
+    /** @type {ComplexityLevel} */
+    this.complexity = /** @type {ComplexityLevel} */ (normalized);
+    /** @type {number} */
+    this.limit = limits[normalized];
+    /** @type {number} */
+    this.used = 0;
+  }
+
+  /**
+   * Intenta consumir `amount` tokens. Si excede el presupuesto, NO consume
+   * y retorna false. Útil cuando el caller debe decidir entre proceder o
+   * escalar.
+   *
+   * @param {number} amount - Cantidad a consumir. Debe ser número finito >= 0.
+   * @returns {boolean} true si se consumió, false si excedería el presupuesto.
+   * @throws {TypeError} si amount no es número finito >= 0.
+   */
+  tryUse(amount) {
+    if (!Number.isFinite(amount) || amount < 0) {
+      throw new TypeError(`TaskBudget.tryUse: amount debe ser número finito >= 0, recibido: ${amount}`);
+    }
+    if (this.used + amount > this.limit) {
+      return false;
+    }
+    this.used += amount;
+    return true;
+  }
+
+  /**
+   * Alias semántico de `tryUse` para callers que prefieren `allocate`.
+   * Mantiene paridad con el API original (pm_agent.token_budget.allocate).
+   *
+   * @param {number} amount
+   * @returns {boolean}
+   */
+  allocate(amount) {
+    return this.tryUse(amount);
+  }
+
+  /**
+   * Consume `amount` tokens FORZOSAMENTE, incluso si excede el presupuesto.
+   * Útil cuando el consumo ya ocurrió y se quiere registrar para auditoría.
+   * Retorna true si quedó dentro del presupuesto, false si lo rebasó.
+   *
+   * @param {number} amount
+   * @returns {boolean} true si dentro del presupuesto, false si lo rebasó.
+   * @throws {TypeError} si amount no es número finito >= 0.
+   */
+  forceUse(amount) {
+    if (!Number.isFinite(amount) || amount < 0) {
+      throw new TypeError(`TaskBudget.forceUse: amount debe ser número finito >= 0, recibido: ${amount}`);
+    }
+    this.used += amount;
+    return this.used <= this.limit;
+  }
+
+  /**
+   * Tokens disponibles restantes. Puede ser negativo si se usó `forceUse`
+   * con consumo que rebasó el límite.
+   * @returns {number}
+   */
+  get remaining() {
+    return this.limit - this.used;
+  }
+
+  /**
+   * Fracción del presupuesto consumida en [0, ∞). 1.0 = exactamente lleno;
+   * >1.0 = rebasado. Útil para alertas "65% consumido".
+   * @returns {number}
+   */
+  get usedFraction() {
+    return this.limit === 0 ? 0 : this.used / this.limit;
+  }
+
+  /**
+   * true si el presupuesto fue rebasado (used > limit). Señal operacional
+   * de mala clasificación de complejidad o scope creep.
+   * @returns {boolean}
+   */
+  get isOver() {
+    return this.used > this.limit;
+  }
+
+  /**
+   * Resetea el contador de usados. NO cambia el límite ni la complejidad.
+   */
+  reset() {
+    this.used = 0;
+  }
+
+  /**
+   * Representación para logs / debugging.
+   * @returns {string}
+   */
+  toString() {
+    return `TaskBudget(complexity=${this.complexity}, limit=${this.limit}, used=${this.used})`;
+  }
+}
+
+/**
+ * Sugiere nivel de complejidad a partir de heurística simple sobre el
+ * descriptor de la tarea. NO es clasificación inteligente — es atajo para
+ * callers que no quieren razonar el nivel manualmente.
+ *
+ * Heurística:
+ *   - menciona "typo", "rename", "format", "comment" → simple
+ *   - menciona "feature", "refactor", "migration", "arquitectura" → complex
+ *   - resto → medium
+ *
+ * @param {string} description - Descripción libre de la tarea.
+ * @returns {ComplexityLevel}
+ */
+function suggestComplexity(description) {
+  if (typeof description !== 'string' || description.length === 0) {
+    return 'medium';
+  }
+  const lower = description.toLowerCase();
+
+  const simpleHints = ['typo', 'rename', 'format', 'comment', 'whitespace', 'comentario', 'formato'];
+  if (simpleHints.some((hint) => lower.includes(hint))) {
+    return 'simple';
+  }
+
+  const complexHints = [
+    'refactor',
+    'migration',
+    'migración',
+    'feature nueva',
+    'cross-module',
+    'cross-modulo',
+    'arquitectura',
+    'rewrite',
+    'reescritura',
+  ];
+  if (complexHints.some((hint) => lower.includes(hint))) {
+    return 'complex';
+  }
+
+  return 'medium';
+}
+
+module.exports = {
+  TaskBudget,
+  DEFAULT_LIMITS,
+  suggestComplexity,
+};