@saulwade/swl-ses 1.6.1 → 1.6.3

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,
+};

package/hooks/validar-intent-spec.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: validar-intent-spec.js
+ * Tipo: PostToolUse  (aplica a: Write, Edit, MultiEdit sobre agentes/*.md)
+ *
+ * Verifica que los agentes con `nivelRiesgo: ALTO` declaren las 6 partes
+ * del framework Intent Engineering exigidas por `reglas/intent-engineering.md`:
+ *   - strategy (Parte 1)
+ *   - healthMetrics (Parte 4)
+ *   - steering (Parte 6 — prompt-level)
+ *   - hardGuardrails (Parte 6 — orchestration-level)
+ *   - fragmentos: [_intent-spec]
+ *   - maxTurnos (Parte 8 — Stop Rules)
+ *
+ * Comportamiento:
+ *   - NUNCA bloquea (exit code 0 siempre — blocking:false en hooks-config)
+ *   - Solo emite nudge cuando faltan campos en agente ALTO — ruido mínimo
+ *   - Solo se dispara con archivos `agentes/*.md` (no fragmentos `_*.md`)
+ *   - Respeta exclusiones: temp/, node_modules/, respositorios-git/, _userland/
+ *
+ * Opt-out: SWL_INTENT_SPEC=0 desactiva completamente el hook.
+ *
+ * Formato del nudge:
+ *   {
+ *     id: string,
+ *     kind: "intent-spec-incomplete",
+ *     target: "auto-evolucion-swl",
+ *     source: "hooks/validar-intent-spec.js",
+ *     message: "...",
+ *     data: { archivo, agente, faltan: [...] },
+ *     ts: ISO,
+ *     accionado: false
+ *   }
+ *
+ * Origen: ADR-0027 (F3 Opción B integración Lead Agents + DDIA).
+ * Plan de promoción a `blocking:true`: tras 2 semanas sin falsos positivos
+ * documentados, con nudges accionados, considerar bloqueo activo.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// ─── Opt-out global ───────────────────────────────────────────────────────
+if (process.env.SWL_INTENT_SPEC === '0') {
+  process.exit(0);
+}
+
+let hookInput = '';
+try {
+  hookInput = fs.readFileSync(0, 'utf-8');
+} catch (_) {
+  process.exit(0);
+}
+
+let evento;
+try {
+  evento = JSON.parse(hookInput);
+} catch (_) {
+  process.exit(0);
+}
+
+const toolName = evento?.tool_name;
+const toolInput = evento?.tool_input;
+
+if (!toolName || !['Write', 'Edit', 'MultiEdit'].includes(toolName)) {
+  process.exit(0);
+}
+
+const filePath = toolInput?.file_path;
+if (!filePath) {
+  process.exit(0);
+}
+
+const pathNormalized = filePath.replace(/\\/g, '/');
+
+// Solo agentes/*.md (NO fragmentos _*.md)
+if (!/\/agentes\/[^_][^/]*\.md$/.test(pathNormalized)) {
+  process.exit(0);
+}
+
+const RUTAS_EXCLUIDAS = [
+  '/temp/',
+  '/node_modules/',
+  '/respositorios-git/',
+  '/_userland/',
+  '/.planning/',
+];
+if (RUTAS_EXCLUIDAS.some((excluida) => pathNormalized.includes(excluida))) {
+  process.exit(0);
+}
+
+if (!fs.existsSync(filePath)) {
+  process.exit(0);
+}
+
+// ─── Parsear frontmatter YAML ─────────────────────────────────────────────
+let contenido;
+try {
+  contenido = fs.readFileSync(filePath, 'utf-8');
+} catch (_) {
+  process.exit(0);
+}
+
+// Normalizar line endings (CRLF Windows → LF) antes del regex.
+// Sin esto el hook nunca detectaba frontmatter en archivos guardados desde
+// Git for Windows con autocrlf=true (bug reportado 2026-05-18).
+contenido = contenido.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+
+const matchFM = contenido.match(/^---\n([\s\S]+?)\n---/);
+if (!matchFM) {
+  // Sin frontmatter — no es un agente conforme. Otros validadores lo detectan.
+  process.exit(0);
+}
+
+const yamlBlob = matchFM[1];
+
+// Parser mínimo de frontmatter (sin dependencias). Solo lee:
+// - nivelRiesgo: VALOR
+// - presencia de claves de primer nivel
+const lineas = yamlBlob.split('\n');
+const claves = new Set();
+let nivelRiesgo = null;
+let fragmentosTieneIntentSpec = false;
+let dentroDeFragmentos = false;
+
+// Strip inline YAML comments (' # ...' o '\t# ...') y comillas wrapping.
+// Sin esto, `nivelRiesgo: ALTO # ejemplo` se parsearía como "ALTO # ejemplo"
+// y la comparación con 'ALTO' fallaría silenciosamente (bug latente 2026-05-18).
+function limpiarValorYaml(crudo) {
+  let v = crudo;
+  // Comentario inline: '#' precedido de whitespace (no '#' dentro de strings comillados,
+  // que en este parser mínimo no soportamos pero sí intentamos respetar).
+  const m = v.match(/^(.*?)(?:\s+#.*)?$/);
+  if (m) v = m[1];
+  v = v.trim();
+  // Strip comillas wrapping si las hay
+  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+    v = v.slice(1, -1);
+  }
+  return v;
+}
+
+for (const linea of lineas) {
+  // Detectar clave de primer nivel (sin indent)
+  const m = linea.match(/^([a-zA-Z_][a-zA-Z0-9_]*):/);
+  if (m) {
+    claves.add(m[1]);
+    if (m[1] === 'nivelRiesgo') {
+      const crudo = linea.split(':').slice(1).join(':').trim();
+      nivelRiesgo = limpiarValorYaml(crudo);
+      dentroDeFragmentos = false;
+    } else if (m[1] === 'fragmentos') {
+      dentroDeFragmentos = true;
+      // Caso fragmentos: [_intent-spec] inline
+      if (linea.includes('_intent-spec')) {
+        fragmentosTieneIntentSpec = true;
+      }
+    } else {
+      dentroDeFragmentos = false;
+    }
+  } else if (dentroDeFragmentos && linea.includes('_intent-spec')) {
+    fragmentosTieneIntentSpec = true;
+  }
+}
+
+// Solo evaluar agentes ALTO
+if (nivelRiesgo !== 'ALTO') {
+  process.exit(0);
+}
+
+// Verificar las 6 partes obligatorias
+const CAMPOS_OBLIGATORIOS = ['strategy', 'healthMetrics', 'steering', 'hardGuardrails', 'maxTurnos'];
+const faltan = CAMPOS_OBLIGATORIOS.filter((c) => !claves.has(c));
+
+if (!fragmentosTieneIntentSpec) {
+  faltan.push('fragmentos:[_intent-spec]');
+}
+
+if (faltan.length === 0) {
+  process.exit(0);
+}
+
+// ─── Emitir nudge ─────────────────────────────────────────────────────────
+const CWD = process.cwd();
+const rutaRelativa = path.relative(CWD, filePath).replace(/\\/g, '/');
+const nombreAgente = path.basename(filePath, '.md');
+
+const nudge = {
+  id: crypto.randomBytes(8).toString('hex'),
+  kind: 'intent-spec-incomplete',
+  target: 'auto-evolucion-swl',
+  source: 'hooks/validar-intent-spec.js',
+  message:
+    `Agente ALTO riesgo ${nombreAgente} no declara intent spec completo. ` +
+    `Faltan: ${faltan.join(', ')}. Cargar Skill("proceso-intent-engineering") + ` +
+    `regla intent-engineering.md y completar frontmatter.`,
+  data: {
+    archivo: rutaRelativa,
+    agente: nombreAgente,
+    nivelRiesgo: 'ALTO',
+    faltan,
+  },
+  ts: new Date().toISOString(),
+  accionado: false,
+};
+
+const nudgesDir = path.join(CWD, '.planning', 'evolucion');
+const nudgesFile = path.join(nudgesDir, 'nudges.jsonl');
+
+try {
+  if (!fs.existsSync(nudgesDir)) {
+    fs.mkdirSync(nudgesDir, { recursive: true });
+  }
+  fs.appendFileSync(nudgesFile, JSON.stringify(nudge) + '\n');
+} catch (_) {
+  // Si falla persistir, no romper el flujo del usuario
+}
+
+process.exit(0);

package/manifiestos/hooks-config.json

@@ -356,6 +356,15 @@
       "maxConsecutiveFailures": 5,
       "degradeOnFailure": "skip"
     },
+    "validar-intent-spec.js": {
+      "event": "PostToolUse",
+      "matcher": "Write|Edit|MultiEdit",
+      "description": "Verifica que agentes nivelRiesgo:ALTO declaren las 6 partes del framework Intent Engineering (strategy, healthMetrics, steering, hardGuardrails, maxTurnos, fragmentos:[_intent-spec]) segun reglas/intent-engineering.md. Solo aplica a agentes/*.md no fragmentos. Emite nudge a .planning/evolucion/nudges.jsonl si faltan campos. No bloquea (modo warn-only inicial; promocion a blocking:true tras 2 semanas estables). Excluye temp/, node_modules/, respositorios-git/, _userland/, .planning/. Opt-out: SWL_INTENT_SPEC=0. ADR-0027.",
+      "blocking": false,
+      "async": true,
+      "maxConsecutiveFailures": 5,
+      "degradeOnFailure": "skip"
+    },
     "notificacion-telegram.js": {
       "event": "Stop",
       "matcher": "",

package/manifiestos/modulos.json

@@ -234,7 +234,14 @@
         "habilidades/tracing-processor",
         "habilidades/guardrail-semantico",
         "habilidades/legacy-code-rescue",
-        "habilidades/harness-claude-code"
+        "habilidades/harness-claude-code",
+        "habilidades/proceso-confianza-pre-implementacion",
+        "habilidades/proceso-autoverificacion-evidencias",
+        "habilidades/aprender-de-git-diff",
+        "habilidades/reducir-entropia",
+        "habilidades/proceso-intent-engineering",
+        "habilidades/proceso-ddia-fundamentos",
+        "habilidades/proceso-ddia-streaming"
       ],
       "targets": [
         "claude",
@@ -887,7 +894,8 @@
         "reglas/arreglar-al-detectar.md",
         "reglas/analisis-previo-tareas-grandes.md",
         "reglas/registro-componentes-nuevos.md",
-        "reglas/auditorias-documentales-estructurales.md"
+        "reglas/auditorias-documentales-estructurales.md",
+        "reglas/intent-engineering.md"
       ],
       "targets": [
         "claude",
@@ -1006,6 +1014,7 @@
         "hooks/inbox-aviso.js",
         "hooks/aiisms-detector.js",
         "hooks/claudemd-bloat-detector.js",
+        "hooks/validar-intent-spec.js",
         "hooks/sugerir-regenerar-inventario.js",
         "hooks/sugerir-contribuir.js",
         "hooks/_run-hook.sh",